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

Last change on this file since 4146 was 4146, checked in by Sam Hocevar, 10 years ago

Fix an alignment issue in caca_get_canvas_chars() and caca_get_canvas_attrs().
Fixes #41.

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