NAME

       caca_canvas - libcaca canvas drawing

SYNOPSIS

   Modules
       libcaca dirty rectangle manipulation

   Macros
       #define CACA_MAGIC_FULLWIDTH   0x000ffffe

   Functions
       __extern int caca_gotoxy (caca_canvas_t *, int, int)
           Set cursor position.
       __extern int caca_wherex (caca_canvas_t const *)
           Get X cursor position.
       __extern int caca_wherey (caca_canvas_t const *)
           Get Y cursor position.
       __extern int caca_put_char (caca_canvas_t *, int, int, uint32_t)
           Print an ASCII or Unicode character.
       __extern uint32_t caca_get_char (caca_canvas_t const *, int, int)
           Get the Unicode character at the given coordinates.
       __extern int caca_put_str (caca_canvas_t *, int, int, char const *)
           Print a string.
       __extern int caca_printf (caca_canvas_t *, int, int, char const *,...)
           Print a formated string.
       __extern int caca_vprintf (caca_canvas_t *, int, int, char const *, va_list)
           Print a formated string (va_list version).
       __extern int caca_clear_canvas (caca_canvas_t *)
           Clear the canvas.
       __extern int caca_set_canvas_handle (caca_canvas_t *, int, int)
           Set cursor handle.
       __extern int caca_get_canvas_handle_x (caca_canvas_t const *)
           Get X handle position.
       __extern int caca_get_canvas_handle_y (caca_canvas_t const *)
           Get Y handle position.
       __extern int caca_blit (caca_canvas_t *, int, int, caca_canvas_t const *, caca_canvas_t
           const *)
           Blit a canvas onto another one.
       __extern int caca_set_canvas_boundaries (caca_canvas_t *, int, int, int, int)
           Set a canvas' new boundaries.

Detailed Description

       These functions provide low-level character printing routines and higher level graphics
       functions.

Macro Definition Documentation

   #define CACA_MAGIC_FULLWIDTH   0x000ffffe
       Used to indicate that the previous character was a fullwidth glyph.

Function Documentation

   __extern int caca_gotoxy (caca_canvas_t * cv, int x, int y)
       Put the cursor at the given coordinates. Functions making use of the cursor will use the
       new values. Setting the cursor position outside the canvas is legal but the cursor will
       not be shown.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.
           x X cursor coordinate.
           y Y cursor coordinate.

       Returns
           This function always returns 0.

       Referenced by caca_conio_cgets(), caca_conio_clrscr(), caca_conio_cprintf(),
       caca_conio_cputs(), caca_conio_gotoxy(), caca_conio_printf(), and caca_conio_putch().

   __extern int caca_wherex (caca_canvas_t const * cv)
       Retrieve the X coordinate of the cursor's position.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.

       Returns
           The cursor's X coordinate.

       Referenced by caca_conio_cgets(), caca_conio_clreol(), caca_conio_cprintf(),
       caca_conio_cputs(), caca_conio_printf(), caca_conio_putch(), and caca_conio_wherex().

   __extern int caca_wherey (caca_canvas_t const * cv)
       Retrieve the Y coordinate of the cursor's position.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.

       Returns
           The cursor's Y coordinate.

       Referenced by caca_conio_cgets(), caca_conio_clreol(), caca_conio_cprintf(),
       caca_conio_cputs(), caca_conio_printf(), caca_conio_putch(), and caca_conio_wherey().

   __extern int caca_put_char (caca_canvas_t * cv, int x, int y, uint32_t ch)
       Print an ASCII or Unicode character at the given coordinates, using the default foreground
       and background colour values.

       If the coordinates are outside the canvas boundaries, nothing is printed. If a fullwidth
       Unicode character gets overwritten, its remaining visible parts are replaced with spaces.
       If the canvas' boundaries would split the fullwidth character in two, a space is printed
       instead.

       The behaviour when printing non-printable characters or invalid UTF-32 characters is
       undefined. To print a sequence of bytes forming an UTF-8 character instead of an UTF-32
       character, use the caca_put_str() function.

       This function returns the width of the printed character. If it is a fullwidth character,
       2 is returned. Otherwise, 1 is returned.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.
           x X coordinate.
           y Y coordinate.
           ch The character to print.

       Returns
           The width of the printed character: 2 for a fullwidth character, 1 otherwise.

       References caca_add_dirty_rect(), CACA_MAGIC_FULLWIDTH, and caca_utf32_is_fullwidth().

       Referenced by caca_conio_cgets(), caca_conio_cputs(), caca_conio_putch(),
       caca_dither_bitmap(), caca_fill_box(), caca_fill_triangle(), caca_flush_figlet(),
       caca_put_figchar(), and caca_put_str().

   __extern uint32_t caca_get_char (caca_canvas_t const * cv, int x, int y)
       Get the ASCII or Unicode value of the character at the given coordinates. If the value is
       less or equal to 127 (0x7f), the character can be printed as ASCII. Otherise, it must be
       handled as a UTF-32 value.

       If the coordinates are outside the canvas boundaries, a space (0x20) is returned.

       A special exception is when CACA_MAGIC_FULLWIDTH is returned. This value is guaranteed not
       to be a valid Unicode character, and indicates that the character at the left of the
       requested one is a fullwidth character.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.
           x X coordinate.
           y Y coordinate.

       Returns
           The Unicode character at the given coordinates.

       Referenced by caca_flush_figlet(), and caca_put_figchar().

   __extern int caca_put_str (caca_canvas_t * cv, int x, int y, char const * s)
       Print an UTF-8 string at the given coordinates, using the default foreground and
       background values. The coordinates may be outside the canvas boundaries (eg. a negative Y
       coordinate) and the string will be cropped accordingly if it is too long.

       See caca_put_char() for more information on how fullwidth characters are handled when
       overwriting each other or at the canvas' boundaries.

       This function returns the number of cells printed by the string. It is not the number of
       characters printed, because fullwidth characters account for two cells.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.
           x X coordinate.
           y Y coordinate.
           s The string to print.

       Returns
           The number of cells printed.

       References caca_put_char(), caca_utf32_is_fullwidth(), and caca_utf8_to_utf32().

       Referenced by caca_vprintf().

   __extern int caca_printf (caca_canvas_t * cv, int x, int y, char const * format,  ...)
       Format a string at the given coordinates, using the default foreground and background
       values. The coordinates may be outside the canvas boundaries (eg. a negative Y coordinate)
       and the string will be cropped accordingly if it is too long. The syntax of the format
       string is the same as for the C printf() function.

       This function returns the number of cells printed by the string. It is not the number of
       characters printed, because fullwidth characters account for two cells.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.
           x X coordinate.
           y Y coordinate.
           format The format string to print.
           ... Arguments to the format string.

       Returns
           The number of cells printed.

       References caca_vprintf().

   __extern int caca_vprintf (caca_canvas_t * cv, int x, int y, char const * format, va_list
       args)
       Format a string at the given coordinates, using the default foreground and background
       values. The coordinates may be outside the canvas boundaries (eg. a negative X coordinate)
       and the string will be cropped accordingly if it is too long. The syntax of the format
       string is the same as for the C vprintf() function.

       This function returns the number of cells printed by the string. It is not the number of
       characters printed, because fullwidth characters account for two cells.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.
           x X coordinate.
           y Y coordinate.
           format The format string to print.
           args A va_list containting the arguments to the format string.

       Returns
           The number of cells printed.

       References caca_put_str().

       Referenced by caca_conio_cprintf(), caca_conio_printf(), and caca_printf().

   __extern int caca_clear_canvas (caca_canvas_t * cv)
       Clear the canvas using the current foreground and background colours.

       This function never fails.

       Parameters
           cv The canvas to clear.

       Returns
           This function always returns 0.

       References caca_add_dirty_rect().

       Referenced by caca_conio_clrscr().

   __extern int caca_set_canvas_handle (caca_canvas_t * cv, int x, int y)
       Set the canvas' handle. Blitting functions will use the handle value to put the canvas at
       the proper coordinates.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.
           x X handle coordinate.
           y Y handle coordinate.

       Returns
           This function always returns 0.

       Referenced by caca_put_figchar().

   __extern int caca_get_canvas_handle_x (caca_canvas_t const * cv)
       Retrieve the X coordinate of the canvas' handle.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.

       Returns
           The canvas' handle's X coordinate.

   __extern int caca_get_canvas_handle_y (caca_canvas_t const * cv)
       Retrieve the Y coordinate of the canvas' handle.

       This function never fails.

       Parameters
           cv A handle to the libcaca canvas.

       Returns
           The canvas' handle's Y coordinate.

   __extern int caca_blit (caca_canvas_t * dst, int x, int y, caca_canvas_t const * src,
       caca_canvas_t const * mask)
       Blit a canvas onto another one at the given coordinates. An optional mask canvas can be
       used.

       If an error occurs, -1 is returned and errno is set accordingly:

       • EINVAL A mask was specified but the mask size and source canvas size do not match.

       Parameters
           dst The destination canvas.
           x X coordinate.
           y Y coordinate.
           src The source canvas.
           mask The mask canvas.

       Returns
           0 in case of success, -1 if an error occurred.

       References caca_add_dirty_rect(), and CACA_MAGIC_FULLWIDTH.

       Referenced by caca_conio_movetext(), caca_export_area_to_memory(),
       caca_import_area_from_file(), caca_import_area_from_memory(), caca_put_figchar(), and
       caca_set_canvas_boundaries().

   __extern int caca_set_canvas_boundaries (caca_canvas_t * cv, int x, int y, int w, int h)
       Set new boundaries for a canvas. This function can be used to crop a canvas, to expand it
       or for combinations of both actions. All frames are affected by this function.

       If an error occurs, -1 is returned and errno is set accordingly:

       • EINVAL Specified width or height is invalid.

       • EBUSY The canvas is in use by a display driver and cannot be resized.

       • ENOMEM Not enough memory for the requested canvas size. If this happens, the canvas
         handle becomes invalid and should not be used.

       Parameters
           cv The canvas to crop.
           x X coordinate of the top-left corner.
           y Y coordinate of the top-left corner.
           w The width of the cropped area.
           h The height of the cropped area.

       Returns
           0 in case of success, -1 if an error occurred.

       References caca_add_dirty_rect(), caca_blit(), caca_create_canvas(), caca_create_frame(),
       caca_get_frame_count(), and caca_set_frame().

Author

       Generated automatically by Doxygen for libcaca from the source code.