source: libcaca/trunk/caca/string.c @ 3556

Last change on this file since 3556 was 3556, checked in by Pascal Terjan, 10 years ago
  • When blitting, only add dirty rectangles on changed lines, or on changed chars if we have a mask
  • Property svn:keywords set to Id
File size: 16.3 KB
Line 
1/*
2 *  libcaca       Colour ASCII-Art library
3 *  Copyright (c) 2002-2009 Sam Hocevar <sam@hocevar.net>
4 *                All Rights Reserved
5 *
6 *  $Id: string.c 3556 2009-07-19 20:37:12Z pterjan $
7 *
8 *  This library is free software. It comes without any warranty, to
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
12 *  http://sam.zoy.org/wtfpl/COPYING for more details.
13 */
14
15/*
16 *  This file contains various canvas handling functions such as character
17 *  and string drawing.
18 */
19
20#include "config.h"
21
22#if !defined(__KERNEL__)
23#   include <stdio.h> /* BUFSIZ */
24#   include <string.h>
25#   include <stdlib.h>
26#   include <stdarg.h>
27#   if defined(HAVE_UNISTD_H)
28#       include <unistd.h>
29#   endif
30#   if defined(HAVE_SIGNAL_H)
31#       include <signal.h>
32#   endif
33#   if defined(HAVE_SYS_IOCTL_H)
34#       include <sys/ioctl.h>
35#   endif
36#endif
37
38#include "caca.h"
39#include "caca_internals.h"
40
41/** \brief Set cursor position.
42 *
43 *  Put the cursor at the given coordinates. Functions making use of the
44 *  cursor will use the new values. Setting the cursor position outside the
45 *  canvas is legal but the cursor will not be shown.
46 *
47 *  This function never fails.
48 *
49 *  \param cv A handle to the libcaca canvas.
50 *  \param x X cursor coordinate.
51 *  \param y Y cursor coordinate.
52 *  \return This function always returns 0.
53 */
54int caca_gotoxy(caca_canvas_t *cv, int x, int y)
55{
56    cv->frames[cv->frame].x = x;
57    cv->frames[cv->frame].y = y;
58
59    return 0;
60}
61
62/** \brief Get X cursor position.
63 *
64 *  Retrieve the X coordinate of the cursor's position.
65 *
66 *  This function never fails.
67 *
68 *  \param cv A handle to the libcaca canvas.
69 *  \return The cursor's X coordinate.
70 */
71int caca_get_cursor_x(caca_canvas_t const *cv)
72{
73    return cv->frames[cv->frame].x;
74}
75
76/** \brief Get Y cursor position.
77 *
78 *  Retrieve the Y coordinate of the cursor's position.
79 *
80 *  This function never fails.
81 *
82 *  \param cv A handle to the libcaca canvas.
83 *  \return The cursor's Y coordinate.
84 */
85int caca_get_cursor_y(caca_canvas_t const *cv)
86{
87    return cv->frames[cv->frame].y;
88}
89
90/** \brief Print an ASCII or Unicode character.
91 *
92 *  Print an ASCII or Unicode character at the given coordinates, using
93 *  the default foreground and background colour values.
94 *
95 *  If the coordinates are outside the canvas boundaries, nothing is printed.
96 *  If a fullwidth Unicode character gets overwritten, its remaining visible
97 *  parts are replaced with spaces. If the canvas' boundaries would split the
98 *  fullwidth character in two, a space is printed instead.
99 *
100 *  The behaviour when printing non-printable characters or invalid UTF-32
101 *  characters is undefined. To print a sequence of bytes forming an UTF-8
102 *  character instead of an UTF-32 character, use the caca_put_str() function.
103 *
104 *  This function never fails.
105 *
106 *  \param cv A handle to the libcaca canvas.
107 *  \param x X coordinate.
108 *  \param y Y coordinate.
109 *  \param ch The character to print.
110 *  \return This function always returns 0.
111 */
112int caca_put_char(caca_canvas_t *cv, int x, int y, uint32_t ch)
113{
114    uint32_t *curchar, *curattr, attr;
115    int fullwidth, xmin, xmax;
116
117    if(x >= (int)cv->width || y < 0 || y >= (int)cv->height)
118        return 0;
119
120    if(ch == CACA_MAGIC_FULLWIDTH)
121        return 0;
122
123    fullwidth = caca_utf32_is_fullwidth(ch);
124
125    if(x == -1 && fullwidth)
126    {
127        x = 0;
128        ch = ' ';
129        fullwidth = 0;
130    }
131    else if(x < 0)
132        return 0;
133
134    curchar = cv->chars + x + y * cv->width;
135    curattr = cv->attrs + x + y * cv->width;
136    attr = cv->curattr;
137
138    xmin = xmax = x;
139
140    /* When overwriting the right part of a fullwidth character,
141     * replace its left part with a space. */
142    if(x && curchar[0] == CACA_MAGIC_FULLWIDTH)
143    {
144        curchar[-1] = ' ';
145        xmin--;
146    }
147
148    if(fullwidth)
149    {
150        if(x + 1 == (int)cv->width)
151            ch = ' ';
152        else
153        {
154            xmax++;
155
156            /* When overwriting the left part of a fullwidth character,
157             * replace its right part with a space. */
158            if(x + 2 < (int)cv->width && curchar[2] == CACA_MAGIC_FULLWIDTH)
159            {
160                curchar[2] = ' ';
161                xmax++;
162            }
163
164            curchar[1] = CACA_MAGIC_FULLWIDTH;
165            curattr[1] = attr;
166        }
167    }
168    else
169    {
170        /* When overwriting the left part of a fullwidth character,
171         * replace its right part with a space. */
172        if(x + 1 != (int)cv->width && curchar[1] == CACA_MAGIC_FULLWIDTH)
173        {
174            curchar[1] = ' ';
175            xmax++;
176        }
177    }
178
179    /* Only add a dirty rectangle if we are pasting a different character
180     * or attribute at that place. This does not account for inconsistencies
181     * in the canvas, ie. if CACA_MAGIC_FULLWIDTH lies at illegal places,
182     * but it's the caller's responsibility not to corrupt the contents. */
183    if(curchar[0] != ch || curattr[0] != attr)
184        caca_add_dirty_rect(cv, xmin, y, xmax - xmin + 1, 1);
185
186    curchar[0] = ch;
187    curattr[0] = attr;
188
189    return 0;
190}
191
192/** \brief Get the Unicode character at the given coordinates.
193 *
194 *  Get the ASCII or Unicode value of the character at the given
195 *  coordinates. If the value is less or equal to 127 (0x7f),
196 *  the character can be printed as ASCII. Otherise, it must be handled
197 *  as a UTF-32 value.
198 *
199 *  If the coordinates are outside the canvas boundaries, a space (0x20)
200 *  is returned.
201 *
202 *  A special exception is when CACA_MAGIC_FULLWIDTH is returned. This
203 *  value is guaranteed not to be a valid Unicode character, and indicates
204 *  that the character at the left of the requested one is a fullwidth
205 *  character.
206 *
207 *  This function never fails.
208 *
209 *  \param cv A handle to the libcaca canvas.
210 *  \param x X coordinate.
211 *  \param y Y coordinate.
212 *  \return The Unicode character at the given coordinates.
213 */
214uint32_t caca_get_char(caca_canvas_t const *cv, int x, int y)
215{
216    if(x < 0 || x >= (int)cv->width || y < 0 || y >= (int)cv->height)
217        return ' ';
218
219    return cv->chars[x + y * cv->width];
220}
221
222/** \brief Print a string.
223 *
224 *  Print an UTF-8 string at the given coordinates, using the default
225 *  foreground and background values. The coordinates may be outside the
226 *  canvas boundaries (eg. a negative Y coordinate) and the string will
227 *  be cropped accordingly if it is too long.
228 *
229 *  See caca_put_char() for more information on how fullwidth characters
230 *  are handled when overwriting each other or at the canvas' boundaries.
231 *
232 *  This function never fails.
233 *
234 *  \param cv A handle to the libcaca canvas.
235 *  \param x X coordinate.
236 *  \param y Y coordinate.
237 *  \param s The string to print.
238 *  \return This function always returns 0.
239 */
240int caca_put_str(caca_canvas_t *cv, int x, int y, char const *s)
241{
242    size_t rd;
243
244    if(y < 0 || y >= (int)cv->height || x >= (int)cv->width)
245        return 0;
246
247    while(*s && x < -1)
248    {
249        x += caca_utf32_is_fullwidth(caca_utf8_to_utf32(s, &rd)) ? 2 : 1;
250        s += rd;
251    }
252
253    while(*s && x < (int)cv->width)
254    {
255        uint32_t ch = caca_utf8_to_utf32(s, &rd);
256        caca_put_char(cv, x, y, ch);
257        x += caca_utf32_is_fullwidth(ch) ? 2 : 1;
258        s += rd;
259    }
260
261    return 0;
262}
263
264/** \brief Print a formated string.
265 *
266 *  Format a string at the given coordinates, using the default foreground
267 *  and background values. The coordinates may be outside the canvas
268 *  boundaries (eg. a negative Y coordinate) and the string will be cropped
269 *  accordingly if it is too long. The syntax of the format string is the
270 *  same as for the C printf() function.
271 *
272 *  This function never fails.
273 *
274 *  \param cv A handle to the libcaca canvas.
275 *  \param x X coordinate.
276 *  \param y Y coordinate.
277 *  \param format The format string to print.
278 *  \param ... Arguments to the format string.
279 *  \return This function always returns 0.
280 */
281int caca_printf(caca_canvas_t *cv, int x, int y, char const *format, ...)
282{
283    char tmp[BUFSIZ];
284    char *buf = tmp;
285    va_list args;
286
287    if(y < 0 || y >= (int)cv->height || x >= (int)cv->width)
288        return 0;
289
290    if(cv->width - x + 1 > BUFSIZ)
291        buf = malloc(cv->width - x + 1);
292
293    va_start(args, format);
294#if defined(HAVE_VSNPRINTF)
295    vsnprintf(buf, cv->width - x + 1, format, args);
296#else
297    vsprintf(buf, format, args);
298#endif
299    buf[cv->width - x] = '\0';
300    va_end(args);
301
302    caca_put_str(cv, x, y, buf);
303
304    if(buf != tmp)
305        free(buf);
306
307    return 0;
308}
309
310/** \brief Clear the canvas.
311 *
312 *  Clear the canvas using the current foreground and background colours.
313 *
314 *  This function never fails.
315 *
316 *  \param cv The canvas to clear.
317 *  \return This function always returns 0.
318 */
319int caca_clear_canvas(caca_canvas_t *cv)
320{
321    uint32_t attr = cv->curattr;
322    int n;
323
324    for(n = cv->width * cv->height; n--; )
325    {
326        cv->chars[n] = (uint32_t)' ';
327        cv->attrs[n] = attr;
328    }
329
330    caca_add_dirty_rect(cv, 0, 0, cv->width, cv->height);
331
332    return 0;
333}
334
335/** \brief Set cursor handle.
336 *
337 *  Set the canvas' handle. Blitting functions will use the handle value
338 *  to put the canvas at the proper coordinates.
339 *
340 *  This function never fails.
341 *
342 *  \param cv A handle to the libcaca canvas.
343 *  \param x X handle coordinate.
344 *  \param y Y handle coordinate.
345 *  \return This function always returns 0.
346 */
347int caca_set_canvas_handle(caca_canvas_t *cv, int x, int y)
348{
349    cv->frames[cv->frame].handlex = x;
350    cv->frames[cv->frame].handley = y;
351
352    return 0;
353}
354
355/** \brief Get X handle position.
356 *
357 *  Retrieve the X coordinate of the canvas' handle.
358 *
359 *  This function never fails.
360 *
361 *  \param cv A handle to the libcaca canvas.
362 *  \return The canvas' handle's X coordinate.
363 */
364int caca_get_canvas_handle_x(caca_canvas_t const *cv)
365{
366    return cv->frames[cv->frame].handlex;
367}
368
369/** \brief Get Y handle position.
370 *
371 *  Retrieve the Y coordinate of the canvas' handle.
372 *
373 *  This function never fails.
374 *
375 *  \param cv A handle to the libcaca canvas.
376 *  \return The canvas' handle's Y coordinate.
377 */
378int caca_get_canvas_handle_y(caca_canvas_t const *cv)
379{
380    return cv->frames[cv->frame].handley;
381}
382
383/** \brief Blit a canvas onto another one.
384 *
385 *  Blit a canvas onto another one at the given coordinates.
386 *  An optional mask canvas can be used.
387 *
388 *  If an error occurs, -1 is returned and \b errno is set accordingly:
389 *  - \c EINVAL A mask was specified but the mask size and source canvas
390 *    size do not match.
391 *
392 *  \param dst The destination canvas.
393 *  \param x X coordinate.
394 *  \param y Y coordinate.
395 *  \param src The source canvas.
396 *  \param mask The mask canvas.
397 *  \return 0 in case of success, -1 if an error occurred.
398 */
399int caca_blit(caca_canvas_t *dst, int x, int y,
400              caca_canvas_t const *src, caca_canvas_t const *mask)
401{
402    int i, j, starti, startj, endi, endj, stride, bleed_left, bleed_right;
403
404    if(mask && (src->width != mask->width || src->height != mask->height))
405    {
406        seterrno(EINVAL);
407        return -1;
408    }
409
410    x -= src->frames[src->frame].handlex;
411    y -= src->frames[src->frame].handley;
412
413    starti = x < 0 ? -x : 0;
414    startj = y < 0 ? -y : 0;
415    endi = (x + src->width >= dst->width) ? dst->width - x : src->width;
416    endj = (y + src->height >= dst->height) ? dst->height - y : src->height;
417    stride = endi - starti;
418
419    if(starti > src->width || startj > src->height
420        || starti >= endi || startj >= endj)
421        return 0;
422
423    bleed_left = bleed_right = 0;
424
425    for(j = startj; j < endj; j++)
426    {
427        int dstix = (j + y) * dst->width + starti + x;
428        int srcix = j * src->width + starti;
429
430        /* FIXME: we are ignoring the mask here */
431        if((starti + x) && dst->chars[dstix] == CACA_MAGIC_FULLWIDTH)
432        {
433            dst->chars[dstix - 1] = ' ';
434            bleed_left = 1;
435        }
436
437        if(endi + x < dst->width
438                && dst->chars[dstix + stride] == CACA_MAGIC_FULLWIDTH)
439        {
440            dst->chars[dstix + stride] = ' ';
441            bleed_right = 1;
442        }
443
444        if(mask)
445        {
446            for(i = 0; i < stride; i++)
447            {
448                if(mask->chars[srcix + i] == (uint32_t)' ')
449                    continue;
450
451                if(dst->chars[dstix + i] != src->chars[srcix + i] ||
452                   dst->attrs[dstix + i] != src->attrs[srcix + i])
453                {
454                    dst->chars[dstix + i] = src->chars[srcix + i];
455                    dst->attrs[dstix + i] = src->attrs[srcix + i];
456                    caca_add_dirty_rect(dst, x + starti + i, y + j, 1, 1);
457                }
458            }
459        }
460        else
461        {
462            if(memcmp(dst->chars + dstix, src->chars + srcix, stride * 4) ||
463               memcmp(dst->attrs + dstix, src->attrs + srcix, stride * 4))
464            {
465                /* FIXME be more precise ? */
466                memcpy(dst->chars + dstix, src->chars + srcix, stride * 4);
467                memcpy(dst->attrs + dstix, src->attrs + srcix, stride * 4);
468                caca_add_dirty_rect(dst, x + starti, y + j, stride, 1);
469            }
470        }
471
472        /* Fix split fullwidth chars */
473        if(src->chars[srcix] == CACA_MAGIC_FULLWIDTH)
474            dst->chars[dstix] = ' ';
475
476        if(endi < src->width && src->chars[endi] == CACA_MAGIC_FULLWIDTH)
477            dst->chars[dstix + stride - 1] = ' ';
478    }
479
480
481    return 0;
482}
483
484/** \brief Set a canvas' new boundaries.
485 *
486 *  Set new boundaries for a canvas. This function can be used to crop a
487 *  canvas, to expand it or for combinations of both actions. All frames
488 *  are affected by this function.
489 *
490 *  If an error occurs, -1 is returned and \b errno is set accordingly:
491 *  - \c EINVAL Specified width or height is invalid.
492 *  - \c EBUSY The canvas is in use by a display driver and cannot be resized.
493 *  - \c ENOMEM Not enough memory for the requested canvas size. If this
494 *    happens, the canvas handle becomes invalid and should not be used.
495 *
496 *  \param cv The canvas to crop.
497 *  \param x X coordinate of the top-left corner.
498 *  \param y Y coordinate of the top-left corner.
499 *  \param w The width of the cropped area.
500 *  \param h The height of the cropped area.
501 *  \return 0 in case of success, -1 if an error occurred.
502 */
503int caca_set_canvas_boundaries(caca_canvas_t *cv, int x, int y, int w, int h)
504{
505    caca_canvas_t *new;
506    int f, saved_f, framecount;
507
508    if(cv->refcount)
509    {
510        seterrno(EBUSY);
511        return -1;
512    }
513
514    if(w < 0 || h < 0)
515    {
516        seterrno(EINVAL);
517        return -1;
518    }
519
520    new = caca_create_canvas(w, h);
521
522    framecount = caca_get_frame_count(cv);
523    saved_f = cv->frame;
524
525    for(f = 0; f < framecount; f++)
526    {
527        if(f)
528            caca_create_frame(new, framecount);
529
530        caca_set_frame(cv, f);
531        caca_set_frame(new, f);
532        caca_blit(new, -x, -y, cv, NULL);
533        free(cv->frames[f].chars);
534        free(cv->frames[f].attrs);
535    }
536    free(cv->frames);
537
538    cv->frames = new->frames;
539    free(new);
540
541    caca_set_frame(cv, saved_f);
542    _caca_load_frame_info(cv);
543
544    /* FIXME: this may be optimised somewhat */
545    caca_add_dirty_rect(cv, 0, 0, cv->width, cv->height);
546
547    return 0;
548}
549
550/*
551 * XXX: The following functions are aliases.
552 */
553
554int cucul_gotoxy(cucul_canvas_t *, int, int) CACA_ALIAS(caca_gotoxy);
555int cucul_get_cursor_x(cucul_canvas_t const *) CACA_ALIAS(caca_get_cursor_x);
556int cucul_get_cursor_y(cucul_canvas_t const *) CACA_ALIAS(caca_get_cursor_y);
557int cucul_put_char(cucul_canvas_t *, int, int, uint32_t)
558         CACA_ALIAS(caca_put_char);
559uint32_t cucul_get_char(cucul_canvas_t const *, int, int)
560         CACA_ALIAS(caca_get_char);
561int cucul_put_str(cucul_canvas_t *, int, int, char const *)
562         CACA_ALIAS(caca_put_str);
563int cucul_printf(cucul_canvas_t *, int, int, char const *, ...)
564         CACA_ALIAS(caca_printf);
565int cucul_clear_canvas(cucul_canvas_t *) CACA_ALIAS(caca_clear_canvas);
566int cucul_set_canvas_handle(cucul_canvas_t *, int, int)
567         CACA_ALIAS(caca_set_canvas_handle);
568int cucul_get_canvas_handle_x(cucul_canvas_t const *)
569         CACA_ALIAS(caca_get_canvas_handle_x);
570int cucul_get_canvas_handle_y(cucul_canvas_t const *)
571         CACA_ALIAS(caca_get_canvas_handle_y);
572int cucul_blit(cucul_canvas_t *, int, int, cucul_canvas_t const *,
573                        cucul_canvas_t const *) CACA_ALIAS(caca_blit);
574int cucul_set_canvas_boundaries(cucul_canvas_t *, int, int, int, int)
575         CACA_ALIAS(caca_set_canvas_boundaries);
576
Note: See TracBrowser for help on using the repository browser.