--- name: "cucul_canvas" section: "3caca" platform: "linux" package: "libcucul-dev" version: "0.99.beta14-1" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/cucul_canvas" --- # cucul\_canvas(3caca) ## NAME libcucul canvas drawing - ### Defines \#define **CUCUL\_MAGIC\_FULLWIDTH** 0x000ffffe\ ### Functions \_\_extern int **cucul\_gotoxy** (**cucul\_canvas\_t** \*, int, int)\ *Set cursor position.* \_\_extern int **cucul\_get\_cursor\_x** (**cucul\_canvas\_t** const \*)\ *Get X cursor position.* \_\_extern int **cucul\_get\_cursor\_y** (**cucul\_canvas\_t** const \*)\ *Get Y cursor position.* \_\_extern int **cucul\_put\_char** (**cucul\_canvas\_t** \*, int, int, uint32\_t)\ *Print an ASCII or Unicode character.* \_\_extern uint32\_t **cucul\_get\_char** (**cucul\_canvas\_t** const \*, int, int)\ *Get the Unicode character at the given coordinates.* \_\_extern int **cucul\_put\_str** (**cucul\_canvas\_t** \*, int, int, char const \*)\ *Print a string.* \_\_extern uint32\_t **cucul\_get\_attr** (**cucul\_canvas\_t** const \*, int, int)\ *Get the text attribute at the given coordinates.* \_\_extern int **cucul\_set\_attr** (**cucul\_canvas\_t** \*, uint32\_t)\ *Set the default character attribute.* \_\_extern int **cucul\_put\_attr** (**cucul\_canvas\_t** \*, int, int, uint32\_t)\ *Set the character attribute at the given coordinates.* \_\_extern int **cucul\_set\_color\_ansi** (**cucul\_canvas\_t** \*, uint8\_t, uint8\_t)\ *Set the default colour pair for text (ANSI version).* \_\_extern int **cucul\_set\_color\_argb** (**cucul\_canvas\_t** \*, uint16\_t, uint16\_t)\ *Set the default colour pair for text (truecolor version).* \_\_extern int **cucul\_printf** (**cucul\_canvas\_t** \*, int, int, char const \*,...)\ *Print a formated string.* \_\_extern int **cucul\_clear\_canvas** (**cucul\_canvas\_t** \*)\ *Clear the canvas.* \_\_extern int **cucul\_set\_canvas\_handle** (**cucul\_canvas\_t** \*, int, int)\ *Set cursor handle.* \_\_extern int **cucul\_get\_canvas\_handle\_x** (**cucul\_canvas\_t** const \*)\ *Get X handle position.* \_\_extern int **cucul\_get\_canvas\_handle\_y** (**cucul\_canvas\_t** const \*)\ *Get Y handle position.* \_\_extern int **cucul\_blit** (**cucul\_canvas\_t** \*, int, int, **cucul\_canvas\_t** const \*, **cucul\_canvas\_t** const \*)\ *Blit a canvas onto another one.* \_\_extern int **cucul\_set\_canvas\_boundaries** (**cucul\_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. ## Define Documentation ### #define CUCUL\_MAGIC\_FULLWIDTH 0x000ffffe Used to indicate that the previous character was a fullwidth glyph. Referenced by cucul\_blit(), cucul\_flip(), cucul\_put\_attr(), cucul\_put\_char(), and cucul\_rotate\_180(). ## Function Documentation ### \_\_extern int cucul\_gotoxy (cucul\_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 libcucul canvas. \ *x* X cursor coordinate. \ *y* Y cursor coordinate. **Returns:** This function always returns 0. ### \_\_extern int cucul\_get\_cursor\_x (cucul\_canvas\_t const \* cv) Retrieve the X coordinate of the cursor's position. This function never fails. **Parameters:** *cv* A handle to the libcucul canvas. **Returns:** The cursor's X coordinate. ### \_\_extern int cucul\_get\_cursor\_y (cucul\_canvas\_t const \* cv) Retrieve the Y coordinate of the cursor's position. This function never fails. **Parameters:** *cv* A handle to the libcucul canvas. **Returns:** The cursor's Y coordinate. ### \_\_extern int cucul\_put\_char (cucul\_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 **cucul\_put\_str()** function. This function never fails. **Parameters:** *cv* A handle to the libcucul canvas. \ *x* X coordinate. \ *y* Y coordinate. \ *ch* The character to print. **Returns:** This function always returns 0. References CUCUL\_MAGIC\_FULLWIDTH, and cucul\_utf32\_is\_fullwidth(). Referenced by cucul\_dither\_bitmap(), cucul\_draw\_cp437\_box(), cucul\_draw\_thin\_box(), cucul\_fill\_box(), cucul\_fill\_triangle(), and cucul\_put\_str(). ### \_\_extern uint32\_t cucul\_get\_char (cucul\_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 CUCUL\_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 libcucul canvas. \ *x* X coordinate. \ *y* Y coordinate. **Returns:** This function always returns 0. ### \_\_extern int cucul\_put\_str (cucul\_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 **cucul\_put\_char()** for more information on how fullwidth characters are handled when overwriting each other or at the canvas' boundaries. This function never fails. **Parameters:** *cv* A handle to the libcucul canvas. \ *x* X coordinate. \ *y* Y coordinate. \ *s* The string to print. **Returns:** This function always returns 0. References cucul\_put\_char(), cucul\_utf32\_is\_fullwidth(), and cucul\_utf8\_to\_utf32(). Referenced by cucul\_printf(). ### \_\_extern uint32\_t cucul\_get\_attr (cucul\_canvas\_t const \* cv, int x, int y) Get the internal *libcucul* attribute value of the character at the given coordinates. The attribute value has 32 significant bits, organised as follows from MSB to LSB: - • 3 bits for the background alpha - • 4 bits for the background red component - • 4 bits for the background green component - • 3 bits for the background blue component - • 3 bits for the foreground alpha - • 4 bits for the foreground red component - • 4 bits for the foreground green component - • 3 bits for the foreground blue component - • 4 bits for the bold, italics, underline and blink flags If the coordinates are outside the canvas boundaries, the current attribute is returned. This function never fails. **Parameters:** *cv* A handle to the libcucul canvas. \ *x* X coordinate. \ *y* Y coordinate. **Returns:** The requested attribute. Referenced by cucul\_dither\_bitmap(). ### \_\_extern int cucul\_set\_attr (cucul\_canvas\_t \* cv, uint32\_t attr) Set the default character attribute for drawing. Attributes define foreground and background colour, transparency, bold, italics and underline styles, as well as blink. String functions such as caca\_printf() and graphical primitive functions such as caca\_draw\_line() will use this attribute. The value of *attr* is either: - • a 32-bit integer as returned by **cucul\_get\_attr()**, in which case it also contains colour information, - • a combination (bitwise OR) of style values (*CUCUL\_UNDERLINE*, *CUCUL\_BLINK*, *CUCUL\_BOLD* and *CUCUL\_ITALICS*), in which case setting the attribute does not modify the current colour information. To retrieve the current attribute value, use cucul\_get\_attr(-1,-1). This function never fails. **Parameters:** *cv* A handle to the libcucul canvas. \ *attr* The requested attribute value. **Returns:** This function always returns 0. Referenced by cucul\_dither\_bitmap(). ### \_\_extern int cucul\_put\_attr (cucul\_canvas\_t \* cv, int x, int y, uint32\_t attr) Set the character attribute, without changing the character's value. If the character at the given coordinates is a fullwidth character, both cells' attributes are replaced. The value of *attr* is either: - • a 32-bit integer as returned by **cucul\_get\_attr()**, in which case it also contains colour information, - • a combination (bitwise OR) of style values (*CUCUL\_UNDERLINE*, *CUCUL\_BLINK*, *CUCUL\_BOLD* and *CUCUL\_ITALICS*), in which case setting the attribute does not modify the current colour information. This function never fails. **Parameters:** *cv* A handle to the libcucul canvas. \ *x* X coordinate. \ *y* Y coordinate. \ *attr* The requested attribute value. **Returns:** This function always returns 0. References CUCUL\_MAGIC\_FULLWIDTH. ### \_\_extern int cucul\_set\_color\_ansi (cucul\_canvas\_t \* cv, uint8\_t fg, uint8\_t bg) Set the default ANSI colour pair for text drawing. String functions such as caca\_printf() and graphical primitive functions such as caca\_draw\_line() will use these attributes. Color values are those defined in **cucul.h**, such as CUCUL\_RED or CUCUL\_TRANSPARENT. If an error occurs, 0 is returned and **errno** is set accordingly: - • `EINVAL` At least one of the colour values is invalid. **Parameters:** *cv* A handle to the libcucul canvas. \ *fg* The requested ANSI foreground colour. \ *bg* The requested ANSI background colour. **Returns:** 0 in case of success, -1 if an error occurred. Referenced by cucul\_create\_canvas(), and cucul\_dither\_bitmap(). ### \_\_extern int cucul\_set\_color\_argb (cucul\_canvas\_t \* cv, uint16\_t fg, uint16\_t bg) Set the default ARGB colour pair for text drawing. String functions such as caca\_printf() and graphical primitive functions such as caca\_draw\_line() will use these attributes. Colors are 16-bit ARGB values, each component being coded on 4 bits. For instance, 0xf088 is solid dark cyan (A=15 R=0 G=8 B=8), and 0x8fff is white with 50% alpha (A=8 R=15 G=15 B=15). This function never fails. **Parameters:** *cv* A handle to the libcucul canvas. \ *fg* The requested ARGB foreground colour. \ *bg* The requested ARGB background colour. **Returns:** This function always returns 0. ### \_\_extern int cucul\_printf (cucul\_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 never fails. **Parameters:** *cv* A handle to the libcucul canvas. \ *x* X coordinate. \ *y* Y coordinate. \ *format* The format string to print. \ *...* Arguments to the format string. **Returns:** This function always returns 0. References cucul\_put\_str(). ### \_\_extern int cucul\_clear\_canvas (cucul\_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. ### \_\_extern int cucul\_set\_canvas\_handle (cucul\_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 libcucul canvas. \ *x* X handle coordinate. \ *y* Y handle coordinate. **Returns:** This function always returns 0. ### \_\_extern int cucul\_get\_canvas\_handle\_x (cucul\_canvas\_t const \* cv) Retrieve the X coordinate of the canvas' handle. This function never fails. **Parameters:** *cv* A handle to the libcucul canvas. **Returns:** The canvas' handle's X coordinate. ### \_\_extern int cucul\_get\_canvas\_handle\_y (cucul\_canvas\_t const \* cv) Retrieve the Y coordinate of the canvas' handle. This function never fails. **Parameters:** *cv* A handle to the libcucul canvas. **Returns:** The canvas' handle's Y coordinate. ### \_\_extern int cucul\_blit (cucul\_canvas\_t \* dst, int x, int y, cucul\_canvas\_t const \* src, cucul\_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 CUCUL\_MAGIC\_FULLWIDTH. Referenced by cucul\_set\_canvas\_boundaries(). ### \_\_extern int cucul\_set\_canvas\_boundaries (cucul\_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 cucul\_blit(), cucul\_create\_canvas(), cucul\_create\_frame(), cucul\_get\_frame\_count(), and cucul\_set\_frame().