source: libcaca/trunk/caca/canvas.c @ 4369

Last change on this file since 4369 was 4369, checked in by sam, 4 years ago

Add the copyright unit test and update copyright information everywhere.

  • Property svn:keywords set to Id
File size: 15.8 KB
Line 
1/*
2 *  libcaca       Colour ASCII-Art library
3 *  Copyright (c) 2002-2010 Sam Hocevar <sam@hocevar.net>
4 *                All Rights Reserved
5 *
6 *  This library is free software. It comes without any warranty, to
7 *  the extent permitted by applicable law. You can redistribute it
8 *  and/or modify it under the terms of the Do What The Fuck You Want
9 *  To Public License, Version 2, as published by Sam Hocevar. See
10 *  http://sam.zoy.org/wtfpl/COPYING for more details.
11 */
12
13/*
14 *  This file contains the main functions used by \e libcaca applications
15 *  to initialise a drawing context.
16 */
17
18#include "config.h"
19
20#if !defined(__KERNEL__)
21#   include <stdio.h>
22#   include <stdlib.h>
23#   include <string.h>
24#   include <time.h>
25#   include <sys/types.h>
26#   if defined(HAVE_UNISTD_H)
27#       include <unistd.h>
28#   endif
29#endif
30
31#include "caca.h"
32#include "caca_internals.h"
33
34static int caca_resize(caca_canvas_t *, int, int);
35
36/** \brief Initialise a \e libcaca canvas.
37 *
38 *  Initialise internal \e libcaca structures and the backend that will
39 *  be used for subsequent graphical operations. It must be the first
40 *  \e libcaca function to be called in a function. caca_free_canvas()
41 *  should be called at the end of the program to free all allocated resources.
42 *
43 *  Both the cursor and the canvas' handle are initialised at the top-left
44 *  corner.
45 *
46 *  If an error occurs, NULL is returned and \b errno is set accordingly:
47 *  - \c EINVAL Specified width or height is invalid.
48 *  - \c ENOMEM Not enough memory for the requested canvas size.
49 *
50 *  \param width The desired canvas width
51 *  \param height The desired canvas height
52 *  \return A libcaca canvas handle upon success, NULL if an error occurred.
53 */
54caca_canvas_t * caca_create_canvas(int width, int height)
55{
56    caca_canvas_t *cv;
57
58    if(width < 0 || height < 0)
59    {
60        seterrno(EINVAL);
61        return NULL;
62    }
63
64    cv = malloc(sizeof(caca_canvas_t));
65
66    if(!cv)
67        goto nomem;
68
69    cv->refcount = 0;
70    cv->autoinc = 0;
71    cv->resize_callback = NULL;
72    cv->resize_data = NULL;
73
74    cv->frame = 0;
75    cv->framecount = 1;
76    cv->frames = malloc(sizeof(struct caca_frame));
77    if(!cv->frames)
78    {
79        free(cv);
80        goto nomem;
81    }
82
83    cv->frames[0].width = cv->frames[0].height = 0;
84    cv->frames[0].chars = NULL;
85    cv->frames[0].attrs = NULL;
86    cv->frames[0].x = cv->frames[0].y = 0;
87    cv->frames[0].handlex = cv->frames[0].handley = 0;
88    cv->frames[0].curattr = 0;
89    cv->frames[0].name = strdup("frame#00000000");
90
91    _caca_load_frame_info(cv);
92    caca_set_color_ansi(cv, CACA_DEFAULT, CACA_TRANSPARENT);
93
94    cv->ndirty = 0;
95    cv->dirty_disabled = 0;
96    cv->ff = NULL;
97
98    if(caca_resize(cv, width, height) < 0)
99    {
100        int saved_errno = geterrno();
101        free(cv->frames[0].name);
102        free(cv->frames);
103        free(cv);
104        seterrno(saved_errno);
105        return NULL;
106    }
107
108    return cv;
109
110nomem:
111    seterrno(ENOMEM);
112    return NULL;
113}
114
115/** \brief Manage a canvas.
116 *
117 *  Lock a canvas to prevent it from being resized. If non-NULL,
118 *  the \e callback function pointer will be called upon each
119 *  \e caca_set_canvas_size call and if the returned value is zero, the
120 *  canvas resize request will be denied.
121 *
122 *  This function is only useful for display drivers such as the \e libcaca
123 *  library.
124 *
125 *  If an error occurs, -1 is returned and \b errno is set accordingly:
126 *  - \c EBUSY The canvas is already being managed.
127 *
128 *  \param cv A libcaca canvas.
129 *  \param callback An optional callback function pointer.
130 *  \param p The argument to be passed to \e callback.
131 *  \return 0 in case of success, -1 if an error occurred.
132 */
133int caca_manage_canvas(caca_canvas_t *cv, int (*callback)(void *), void *p)
134{
135    if(cv->refcount)
136    {
137        seterrno(EBUSY);
138        return -1;
139    }
140
141    cv->resize_callback = callback;
142    cv->resize_data = p;
143    cv->refcount = 1;
144
145    return 0;
146}
147
148/** \brief unmanage a canvas.
149 *
150 *  unlock a canvas previously locked by caca_manage_canvas(). for safety
151 *  reasons, the callback and callback data arguments must be the same as for
152 *  the caca_manage_canvas() call.
153 *
154 *  this function is only useful for display drivers such as the \e libcaca
155 *  library.
156 *
157 *  if an error occurs, -1 is returned and \b errno is set accordingly:
158 *  - \c einval the canvas is not managed, or the callback arguments do
159 *              not match.
160 *
161 *  \param cv a libcaca canvas.
162 *  \param callback the \e callback argument previously passed to
163 *                  caca_manage_canvas().
164 *  \param p the \e p argument previously passed to caca_manage_canvas().
165 *  \return 0 in case of success, -1 if an error occurred.
166 */
167int caca_unmanage_canvas(caca_canvas_t *cv, int (*callback)(void *), void *p)
168{
169    if(!cv->refcount
170        || cv->resize_callback != callback || cv->resize_data != p)
171    {
172        seterrno(EINVAL);
173        return -1;
174    }
175
176    cv->refcount = 0;
177
178    return 0;
179}
180
181/** \brief Resize a canvas.
182 *
183 *  Set the canvas' width and height, in character cells.
184 *
185 *  The contents of the canvas are preserved to the extent of the new
186 *  canvas size. Newly allocated character cells at the right and/or at
187 *  the bottom of the canvas are filled with spaces.
188 *
189 *  If as a result of the resize the cursor coordinates fall outside the
190 *  new canvas boundaries, they are readjusted. For instance, if the
191 *  current X cursor coordinate is 11 and the requested width is 10, the
192 *  new X cursor coordinate will be 10.
193 *
194 *  It is an error to try to resize the canvas if an output driver has
195 *  been attached to the canvas using caca_create_display(). You need to
196 *  remove the output driver using caca_free_display() before you can change
197 *  the canvas size again. However, the caca output driver can cause a
198 *  canvas resize through user interaction. See the caca_event() documentation
199 *  for more about this.
200 *
201 *  If an error occurs, -1 is returned and \b errno is set accordingly:
202 *  - \c EINVAL Specified width or height is invalid.
203 *  - \c EBUSY The canvas is in use by a display driver and cannot be resized.
204 *  - \c ENOMEM Not enough memory for the requested canvas size. If this
205 *    happens, the canvas handle becomes invalid and should not be used.
206 *
207 *  \param cv A libcaca canvas.
208 *  \param width The desired canvas width.
209 *  \param height The desired canvas height.
210 *  \return 0 in case of success, -1 if an error occurred.
211 */
212int caca_set_canvas_size(caca_canvas_t *cv, int width, int height)
213{
214    if(width < 0 || height < 0)
215    {
216        seterrno(EINVAL);
217        return -1;
218    }
219
220    if(cv->refcount && cv->resize_callback
221        && !cv->resize_callback(cv->resize_data))
222    {
223        seterrno(EBUSY);
224        return -1;
225    }
226
227    return caca_resize(cv, width, height);
228}
229
230/** \brief Get the canvas width.
231 *
232 *  Return the current canvas' width, in character cells.
233 *
234 *  This function never fails.
235 *
236 *  \param cv A libcaca canvas.
237 *  \return The canvas width.
238 */
239int caca_get_canvas_width(caca_canvas_t const *cv)
240{
241    return cv->width;
242}
243
244/** \brief Get the canvas height.
245 *
246 *  Returns the current canvas' height, in character cells.
247 *
248 *  This function never fails.
249 *
250 *  \param cv A libcaca canvas.
251 *  \return The canvas height.
252 */
253int caca_get_canvas_height(caca_canvas_t const *cv)
254{
255    return cv->height;
256}
257
258/** \brief Get the canvas character array.
259 *
260 *  Return the current canvas' internal character array. The array elements
261 *  consist in native endian 32-bit Unicode values as returned by
262 *  caca_get_char().
263 *
264 *  This function is probably only useful for \e libcaca 's internal display
265 *  drivers.
266 *
267 *  This function never fails.
268 *
269 *  \param cv A libcaca canvas.
270 *  \return The canvas character array.
271 */
272uint32_t const * caca_get_canvas_chars(caca_canvas_t const *cv)
273{
274    return (uint32_t const *)cv->chars;
275}
276
277/** \brief Get the canvas attribute array.
278 *
279 *  Returns the current canvas' internal attribute array. The array elements
280 *  consist in native endian 32-bit attribute values as returned by
281 *  caca_get_attr().
282 *
283 *  This function is probably only useful for \e libcaca 's internal display
284 *  drivers.
285 *
286 *  This function never fails.
287 *
288 *  \param cv A libcaca canvas.
289 *  \return The canvas attribute array.
290 */
291uint32_t const * caca_get_canvas_attrs(caca_canvas_t const *cv)
292{
293    return (uint32_t const *)cv->attrs;
294}
295
296/** \brief Free a \e libcaca canvas.
297 *
298 *  Free all resources allocated by caca_create_canvas(). The canvas
299 *  pointer becomes invalid and must no longer be used unless a new call
300 *  to caca_create_canvas() is made.
301 *
302 *  If an error occurs, -1 is returned and \b errno is set accordingly:
303 *  - \c EBUSY The canvas is in use by a display driver and cannot be freed.
304 *
305 *  \param cv A libcaca canvas.
306 *  \return 0 in case of success, -1 if an error occurred.
307 */
308int caca_free_canvas(caca_canvas_t *cv)
309{
310    int f;
311
312    if(cv->refcount)
313    {
314        seterrno(EBUSY);
315        return -1;
316    }
317
318    for(f = 0; f < cv->framecount; f++)
319    {
320        free(cv->frames[f].chars);
321        free(cv->frames[f].attrs);
322        free(cv->frames[f].name);
323    }
324
325    caca_canvas_set_figfont(cv, NULL);
326
327    free(cv->frames);
328    free(cv);
329
330    return 0;
331}
332
333/** \brief Generate a random integer within a range.
334 *
335 *  Generate a random integer within the given range.
336 *
337 *  This function never fails.
338 *
339 *  \param min The lower bound of the integer range.
340 *  \param max The upper bound of the integer range.
341 *  \return A random integer comprised between \p min  and \p max - 1
342 *  (inclusive).
343 */
344int caca_rand(int min, int max)
345{
346    static int need_init = 1;
347
348    if(need_init)
349    {
350        srand(getpid() + time(NULL));
351        need_init = 0;
352    }
353
354    return min + (int)((1.0 * (max - min)) * rand() / (RAND_MAX + 1.0));
355}
356
357
358/*
359 * XXX: The following functions are local.
360 */
361
362int caca_resize(caca_canvas_t *cv, int width, int height)
363{
364    int x, y, f, old_width, old_height, new_size, old_size;
365
366    old_width = cv->width;
367    old_height = cv->height;
368    old_size = old_width * old_height;
369
370    _caca_save_frame_info(cv);
371
372    /* Preload new width and height values into the canvas to optimise
373     * dirty rectangle handling */
374    cv->width = width;
375    cv->height = height;
376    new_size = width * height;
377
378    /* If width or height is smaller (or both), we have the opportunity to
379     * reduce or even remove dirty rectangles */
380    if(width < old_width || height < old_height)
381        _caca_clip_dirty_rect_list(cv);
382
383    /* Step 1: if new area is bigger, resize the memory area now. */
384    if(new_size > old_size)
385    {
386        for(f = 0; f < cv->framecount; f++)
387        {
388            cv->frames[f].chars = realloc(cv->frames[f].chars,
389                                          new_size * sizeof(uint32_t));
390            cv->frames[f].attrs = realloc(cv->frames[f].attrs,
391                                          new_size * sizeof(uint32_t));
392            if(new_size && (!cv->frames[f].chars || !cv->frames[f].attrs))
393            {
394                seterrno(ENOMEM);
395                return -1;
396            }
397        }
398    }
399
400    /* Step 2: move line data if necessary. */
401    if(width == old_width)
402    {
403        /* Width did not change, which means we do not need to move data. */
404        ;
405    }
406    else if(width > old_width)
407    {
408        /* New width is bigger than old width, which means we need to
409         * copy lines starting from the bottom of the screen otherwise
410         * we will overwrite information. */
411        for(f = 0; f < cv->framecount; f++)
412        {
413            uint32_t *chars = cv->frames[f].chars;
414            uint32_t *attrs = cv->frames[f].attrs;
415
416            for(y = height < old_height ? height : old_height; y--; )
417            {
418                uint32_t attr = cv->frames[f].curattr;
419
420                for(x = old_width; x--; )
421                {
422                    chars[y * width + x] = chars[y * old_width + x];
423                    attrs[y * width + x] = attrs[y * old_width + x];
424                }
425
426                /* Zero the end of the line */
427                for(x = width - old_width; x--; )
428                {
429                    chars[y * width + old_width + x] = (uint32_t)' ';
430                    attrs[y * width + old_width + x] = attr;
431                }
432            }
433        }
434
435        if(!cv->dirty_disabled)
436            caca_add_dirty_rect(cv, old_width, 0,
437                                width - old_width, old_height);
438    }
439    else
440    {
441        /* New width is smaller. Copy as many lines as possible. Ignore
442         * the first line, it is already in place. */
443        int lines = height < old_height ? height : old_height;
444
445        for(f = 0; f < cv->framecount; f++)
446        {
447            uint32_t *chars = cv->frames[f].chars;
448            uint32_t *attrs = cv->frames[f].attrs;
449
450            for(y = 1; y < lines; y++)
451            {
452                for(x = 0; x < width; x++)
453                {
454                    chars[y * width + x] = chars[y * old_width + x];
455                    attrs[y * width + x] = attrs[y * old_width + x];
456                }
457            }
458        }
459    }
460
461    /* Step 3: fill the bottom of the new screen if necessary. */
462    if(height > old_height)
463    {
464        for(f = 0; f < cv->framecount; f++)
465        {
466            uint32_t *chars = cv->frames[f].chars;
467            uint32_t *attrs = cv->frames[f].attrs;
468            uint32_t attr = cv->frames[f].curattr;
469
470            /* Zero the bottom of the screen */
471            for(x = (height - old_height) * width; x--; )
472            {
473                chars[old_height * width + x] = (uint32_t)' ';
474                attrs[old_height * width + x] = attr;
475            }
476        }
477
478        if(!cv->dirty_disabled)
479            caca_add_dirty_rect(cv, 0, old_height,
480                                old_width, height - old_height);
481    }
482
483    /* If both width and height are larger, there is a new dirty rectangle
484     * that needs to be created in the lower right corner. */
485    if(!cv->dirty_disabled &&
486        width > old_width && height > old_height)
487        caca_add_dirty_rect(cv, old_width, old_height,
488                            width - old_width, height - old_height);
489
490    /* Step 4: if new area is smaller, resize memory area now. */
491    if(new_size < old_size)
492    {
493        for(f = 0; f < cv->framecount; f++)
494        {
495            cv->frames[f].chars = realloc(cv->frames[f].chars,
496                                          new_size * sizeof(uint32_t));
497            cv->frames[f].attrs = realloc(cv->frames[f].attrs,
498                                          new_size * sizeof(uint32_t));
499            if(new_size && (!cv->frames[f].chars || !cv->frames[f].attrs))
500            {
501                seterrno(ENOMEM);
502                return -1;
503            }
504        }
505    }
506
507    /* Set new size */
508    for(f = 0; f < cv->framecount; f++)
509    {
510        if(cv->frames[f].x > (int)width)
511            cv->frames[f].x = width;
512        if(cv->frames[f].y > (int)height)
513            cv->frames[f].y = height;
514
515        cv->frames[f].width = width;
516        cv->frames[f].height = height;
517    }
518
519    /* Reset the current frame shortcuts */
520    _caca_load_frame_info(cv);
521
522    return 0;
523}
524
525/*
526 * XXX: The following functions are aliases.
527 */
528
529cucul_canvas_t * cucul_create_canvas(int, int) CACA_ALIAS(caca_create_canvas);
530int cucul_manage_canvas(cucul_canvas_t *, int (*)(void *), void *)
531    CACA_ALIAS(caca_manage_canvas);
532int cucul_unmanage_canvas(cucul_canvas_t *, int (*)(void *), void *)
533    CACA_ALIAS(caca_unmanage_canvas);
534int cucul_set_canvas_size(cucul_canvas_t *, int, int)
535    CACA_ALIAS(caca_set_canvas_size);
536int cucul_get_canvas_width(cucul_canvas_t const *)
537    CACA_ALIAS(caca_get_canvas_width);
538int cucul_get_canvas_height(cucul_canvas_t const *)
539    CACA_ALIAS(caca_get_canvas_height);
540uint32_t const * cucul_get_canvas_chars(cucul_canvas_t const *)
541    CACA_ALIAS(caca_get_canvas_chars);
542uint32_t const * cucul_get_canvas_attrs(cucul_canvas_t const *)
543    CACA_ALIAS(caca_get_canvas_attrs);
544int cucul_free_canvas(cucul_canvas_t *) CACA_ALIAS(caca_free_canvas);
545int cucul_rand(int, int) CACA_ALIAS(caca_rand);
546
Note: See TracBrowser for help on using the repository browser.