caca_canvas(3caca)
💖 NAME 💖
caca_canvas — libcaca canvas drawing. Okay so this is the caca_canvas(3caca) page from libcaca, and it's literally the home of canvas drawing lore. ✨
✨ SYNOPSIS ✨
🧵 Topics
libcaca dirty rectangle manipulation— this is the topic linked up in here, bestie. That's the topic, and it's serving exactly what it says. 💅
🪄 Macros
#define CACA_MAGIC_FULLWIDTH 0x000ffffe— the macro in question, with all its spaces and hex energy intact. 🎀
🧚 Functions
__extern int caca_gotoxy (caca_canvas_t *, int, int)— sets the cursor position; it's giving "move the little cursor to a spot" energy.__extern int caca_wherex (caca_canvas_t const *)— gets the X cursor position.__extern int caca_wherey (caca_canvas_t const *)— gets the Y cursor position.__extern int caca_put_char (caca_canvas_t *, int, int, uint32_t)— prints an ASCII or Unicode character.__extern uint32_t caca_get_char (caca_canvas_t const *, int, int)— gets the Unicode character at the given coordinates.__extern int caca_put_str (caca_canvas_t *, int, int, char const *)— prints a string.__extern int caca_printf (caca_canvas_t *, int, int, char const *,...)— prints a formatted string.__extern int caca_vprintf (caca_canvas_t *, int, int, char const *, va_list)— prints a formatted string, but theva_listversion.__extern int caca_clear_canvas (caca_canvas_t *)— clears the canvas.__extern int caca_set_canvas_handle (caca_canvas_t *, int, int)— sets the cursor handle.__extern int caca_get_canvas_handle_x (caca_canvas_t const *)— gets the X handle position.__extern int caca_get_canvas_handle_y (caca_canvas_t const *)— gets the Y handle position.__extern int caca_blit (caca_canvas_t *, int, int, caca_canvas_t const *, caca_canvas_t const *)— blits a canvas onto another one.__extern int caca_set_canvas_boundaries (caca_canvas_t *, int, int, int, int)— sets a canvas' new boundaries.
💬 Detailed Description 💬
These functions provide low-level character printing routines and higher level graphics functions. Lowkey iconic, highkey essential — it's the whole canvas crew in one place. 🫶
📚 Macro Definition Documentation 📚
🎀 #define CACA_MAGIC_FULLWIDTH 0x000ffffe 🎀
Used to indicate that the previous character was a fullwidth glyph. 🦋
Referenced by caca_blit(), caca_flip(), caca_put_attr(), caca_put_char(), and caca_rotate_180(). 👑
✨ Function Documentation ✨
Okay bestie, this is the actual function-by-function part, and honestly? It ate. Every one of these is a little icon. Let's go 🫶
🎀 caca_gotoxy
__extern int caca_gotoxy (caca_canvas_t * cv, int x, int y)Puts the cursor exactly where you tell it to. Every function that cares about the cursor will pick up your shiny new values. And listen — setting the cursor outside the canvas is totally legal 💅, it just means the cursor won't show up. It's giving "invited to the party but not on the guest list."
This function never fails. Never. Not once. Iconic.
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().
🎀 caca_wherex
__extern int caca_wherex (caca_canvas_t const * cv)Gives you the X coordinate of where the cursor is currently sitting. Like a location tag but for your cursor. 📍
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().
🎀 caca_wherey
__extern int caca_wherey (caca_canvas_t const * cv)Same energy as caca_wherex() but for the Y coordinate. Vertical bestie. 🦋
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().
🎀 caca_put_char
__extern int caca_put_char (caca_canvas_t * cv, int x, int y, uint32_t ch)Prints an ASCII or Unicode character at the given coordinates, using the default foreground and background colour values. This is THE main character of the page honestly.
So here's the tea 🍵: if the coordinates are outside the canvas boundaries, nothing gets printed. Nada. If a fullwidth Unicode character gets overwritten, whatever parts of it are still visible get replaced with spaces. And if the canvas' boundaries would split the fullwidth character in two, a space is printed instead — because splitting a character is a crime and libcaca refuses to participate.
⚠️ Real talk: the behaviour when printing non-printable characters or invalid UTF-32 characters is undefined. That's not a vibe, that's a warning. Also — if you've got a sequence of bytes forming an UTF-8 character instead of an UTF-32 character, go use caca_put_str() instead, bestie.
This function returns the width of the printed character. Fullwidth character? You get 2. Otherwise? 1.
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().
🎀 caca_get_char
__extern uint32_t caca_get_char (caca_canvas_t const * cv, int x, int y)Grabs the ASCII or Unicode value of the character hanging out at the given coordinates. If the value is less or equal to 127 (0x7f), it's printable as ASCII. If it's bigger, you gotta handle it as a UTF-32 value. Know the difference, iykyk.
If the coordinates are outside the canvas boundaries, you get a space (0x20) back. Sad but fair.
Now for the special exception that lives rent-free in my head: when CACA_MAGIC_FULLWIDTH is returned. That value is guaranteed not to be a valid Unicode character, and it means the character to the left of the one you asked for is a fullwidth character. Plot twist 🫢
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().
🎀 caca_put_str
__extern int caca_put_str (caca_canvas_t * cv, int x, int y, char const * s)Prints a whole 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's too long. Cropping, not cancelling 👑
For more info on how fullwidth characters are handled when they overwrite each other or hit the canvas' boundaries, go read caca_put_char() — it's got the full lore.
This function returns the number of cells printed by the string, not the number of characters printed, because fullwidth characters account for two cells. Math is math!
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().
🎀 caca_printf
__extern int caca_printf (caca_canvas_t * cv, int x, int y, char const *
format, ...)Formats a string right 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's too long. The format string syntax is the same as for the C printf() function — no cap, it's literally the same. 💅
Returns the number of cells printed, not characters, because fullwidth characters account for two cells. Same deal as before.
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().
🎀 caca_vprintf
__extern int caca_vprintf (caca_canvas_t * cv, int x, int y, char const *
format, va_list args)The va_list sibling of caca_printf() — formats a string at the given coordinates using the default foreground and background values. (Heads up, the original text for this one says "eg. a negative X coordinate" while caca_printf says "negative Y coordinate" — I don't make the rules, I just report them 🙈.) The string will be cropped accordingly if it's too long. Format string syntax matches the C vprintf() function.
Returns the number of cells printed, not characters, 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— ava_listcontainting the arguments to the format string. (yes, "containting" — that's a typo in the original and I'm keeping it because I respect the source 🫶)
Returns The number of cells printed.
References caca_put_str().
Referenced by caca_conio_cprintf(), caca_conio_printf(), and caca_printf().
🎀 caca_clear_canvas
__extern int caca_clear_canvas (caca_canvas_t * cv)Wipes the whole canvas clean using the current foreground and background colours. It's giving fresh start, new semester, clean slate energy ✨
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().
🎀 caca_set_canvas_handle
__extern int caca_set_canvas_handle (caca_canvas_t * cv, int x, int y)Sets the canvas' handle. Blitting functions will use the handle value to put the canvas at the proper coordinates — it's basically the canvas' home address 🏠
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().
🎀 caca_get_canvas_handle_x
__extern int caca_get_canvas_handle_x (caca_canvas_t const * cv)Gets you the X coordinate of the canvas' handle. Simple. Elegant. Does exactly what it says.
This function never fails.
Parameters
cv— a handle to the libcaca canvas.
Returns The canvas' handle's X coordinate.
🎀 caca_get_canvas_handle_y
__extern int caca_get_canvas_handle_y (caca_canvas_t const * cv)The Y-coordinate twin of the one above. Together they're the handle's whole personality.
This function never fails.
Parameters
cv— a handle to the libcaca canvas.
Returns The canvas' handle's Y coordinate.
🎀 caca_blit
__extern int caca_blit (caca_canvas_t * dst, int x, int y, caca_canvas_t
const * src, caca_canvas_t const * mask)Blits a canvas onto another one at the given coordinates. An optional mask canvas can be used. It's copy-paste but make it fashion 💅✨
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. Rude of them tbh.
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().
🎀 caca_set_canvas_boundaries
__extern int caca_set_canvas_boundaries (caca_canvas_t * cv, int x, int y,
int w, int h)Sets new boundaries for a canvas. You can use this to crop a canvas, to expand it, or for combinations of both actions — it's the ultimate glow-up or glow-down, your choice. All frames are affected by this function. Every single one 👑
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. Occupied! Busy! Leave a message after the beep.ENOMEM— not enough memory for the requested canvas size.
💀 Major warning, do not scroll past this one: if ENOMEM happens, the canvas handle becomes invalid and should not be used. Like, at all. Gone. Do not touch. This is not a drill, bestie.
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. (Not a human, but honestly? Serving anyway 🤖💖)
And that's the whole page, bestie — we did it! 🎉 This beauty is from Version 0.99.beta20, dated Wed May 13 2026 09:45:08, and it's the caca_canvas(3caca) manual page. Go forth and blit responsibly. 🦋💜
📦 where this page comes from
- opensuse-leap 16.0: libcaca-devel 0.99.beta20-160000.3.1 · WTFPL
- opensuse-leap 16.0: libcaca-devel 0.99.beta20-160000.3.1 · WTFPL
- opensuse-leap 16.0: libcaca-devel 0.99.beta20-160000.3.1 · WTFPL
- opensuse-leap 16.0: libcaca-devel 0.99.beta20-160000.3.1 · WTFPL
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms