caca.h(3caca)

📦
version 0.99.beta20 · 12 versions
, in opensuse-leap 16.0

💖 caca.h — The libcaca public header ✨

okay so bestie, welcome to the manual page for caca.h, aka the whole entire public header of libcaca — the page is literally named caca.h(3caca) and it's giving "here's every type, struct, macro and enum you're allowed to touch" 👑. Think of it as the group chat invite list for the library: if it's not on here, it's not in the club 💅.

✨ NAME ✨

caca.h — The libcaca public header. that's it, that's the whole name section, no notes 🎀

🌈 SYNOPSIS 🌈

🧱 Data Structures

These are the structs that are public, like, officially out here for you:

  • struct caca_event — handling of user events. keys, mouse, resizes, the whole vibe check on what the human just did 🖱️
  • struct caca_option — option parsing. yes it does your argv homework for you, iconic behavior fr
  • struct caca_conio_text_info — DOS text area information. retro DOS energy, we love a throwback 💾

🪄 Macros

two macros, both absolute icons:

  • #define CACA_API_VERSION_1 — the API version. you're on version 1, bestie, congrats
  • #define CACA_MAGIC_FULLWIDTH 0x000ffffe — the magic fullwidth value, and honestly the name alone is a serve ✨

🏷️ Typedefs

here's the whole squad of opaque types, each one a typedef so you never have to type struct like a peasant:

typedef struct caca_canvas caca_canvas_t
typedef struct caca_dither caca_dither_t
typedef struct caca_charfont caca_charfont_t
typedef struct caca_font caca_font_t
typedef struct caca_file caca_file_t
typedef struct caca_display caca_display_t
typedef struct caca_event caca_event_t

that last one, caca_event_t, is literally struct caca_event wearing a cuter outfit. same struct, shorter name, main character energy 🫶

🌟 Enumerations

okay this is the big one — six whole enums, so many constants, let's go section by section 💜

enum caca_color

the colour enum, aka the entire palette in one place:

enum caca_color {
    CACA_BLACK = 0x00, CACA_BLUE = 0x01, CACA_GREEN = 0x02,
    CACA_CYAN = 0x03, CACA_RED = 0x04, CACA_MAGENTA = 0x05,
    CACA_BROWN = 0x06, CACA_LIGHTGRAY = 0x07, CACA_DARKGRAY = 0x08,
    CACA_LIGHTBLUE = 0x09, CACA_LIGHTGREEN = 0x0a, CACA_LIGHTCYAN = 0x0b,
    CACA_LIGHTRED = 0x0c, CACA_LIGHTMAGENTA = 0x0d, CACA_YELLOW = 0x0e,
    CACA_WHITE = 0x0f, CACA_DEFAULT = 0x10, CACA_TRANSPARENT = 0x20
};

note how CACA_DEFAULT and CACA_TRANSPARENT are off doing their own thing on their own values — they're not like the other sixteen 🦋

enum caca_style

the style bits, for when you want your text to have a lewk:

enum caca_style {
    CACA_BOLD = 0x01, CACA_ITALICS = 0x02, CACA_UNDERLINE = 0x04,
    CACA_BLINK = 0x08
};

blink is right there at 0x08, use it responsibly 😭

enum caca_event_type

user event type enumeration — literally the enum that knows what kind of event just happened 🔥:

enum caca_event_type {
    CACA_EVENT_NONE = 0x0000, CACA_EVENT_KEY_PRESS = 0x0001,
    CACA_EVENT_KEY_RELEASE = 0x0002, CACA_EVENT_MOUSE_PRESS = 0x0004,
    CACA_EVENT_MOUSE_RELEASE = 0x0008, CACA_EVENT_MOUSE_MOTION = 0x0010,
    CACA_EVENT_RESIZE = 0x0020, CACA_EVENT_QUIT = 0x0040,
    CACA_EVENT_ANY = 0xffff
};

CACA_EVENT_ANY at 0xffff is that one friend who's down for literally anything 💀

enum caca_key

special key values — every last one of them, no skipping, we're listing all 55 because every single one matters:

enum caca_key {
    CACA_KEY_UNKNOWN = 0x00, CACA_KEY_CTRL_A = 0x01, CACA_KEY_CTRL_B = 0x02,
    CACA_KEY_CTRL_C = 0x03, CACA_KEY_CTRL_D = 0x04, CACA_KEY_CTRL_E = 0x05,
    CACA_KEY_CTRL_F = 0x06, CACA_KEY_CTRL_G = 0x07, CACA_KEY_BACKSPACE = 0x08,
    CACA_KEY_TAB = 0x09, CACA_KEY_CTRL_J = 0x0a, CACA_KEY_CTRL_K = 0x0b,
    CACA_KEY_CTRL_L = 0x0c, CACA_KEY_RETURN = 0x0d, CACA_KEY_CTRL_N = 0x0e,
    CACA_KEY_CTRL_O = 0x0f, CACA_KEY_CTRL_P = 0x10, CACA_KEY_CTRL_Q = 0x11,
    CACA_KEY_CTRL_R = 0x12, CACA_KEY_PAUSE = 0x13, CACA_KEY_CTRL_T = 0x14,
    CACA_KEY_CTRL_U = 0x15, CACA_KEY_CTRL_V = 0x16, CACA_KEY_CTRL_W = 0x17,
    CACA_KEY_CTRL_X = 0x18, CACA_KEY_CTRL_Y = 0x19, CACA_KEY_CTRL_Z = 0x1a,
    CACA_KEY_ESCAPE = 0x1b, CACA_KEY_DELETE = 0x7f, CACA_KEY_UP = 0x111,
    CACA_KEY_DOWN = 0x112, CACA_KEY_LEFT = 0x113, CACA_KEY_RIGHT = 0x114,
    CACA_KEY_INSERT = 0x115, CACA_KEY_HOME = 0x116, CACA_KEY_END = 0x117,
    CACA_KEY_PAGEUP = 0x118, CACA_KEY_PAGEDOWN = 0x119, CACA_KEY_F1 = 0x11a,
    CACA_KEY_F2 = 0x11b, CACA_KEY_F3 = 0x11c, CACA_KEY_F4 = 0x11d,
    CACA_KEY_F5 = 0x11e, CACA_KEY_F6 = 0x11f, CACA_KEY_F7 = 0x120,
    CACA_KEY_F8 = 0x121, CACA_KEY_F9 = 0x122, CACA_KEY_F10 = 0x123,
    CACA_KEY_F11 = 0x124, CACA_KEY_F12 = 0x125, CACA_KEY_F13 = 0x126,
    CACA_KEY_F14 = 0x127, CACA_KEY_F15 = 0x128
};

iykyk that CACA_KEY_CTRL_C sitting at 0x03 is the one you never want to catch by accident 😳 and yes, F15 is in there, they really did all fifteen, commitment 💅

tiny heads up: CACA_KEY_CTRL_H and CACA_KEY_CTRL_I and CACA_KEY_CTRL_M are not in this list — 0x08 is CACA_KEY_BACKSPACE, 0x09 is CACA_KEY_TAB, and 0x0d is CACA_KEY_RETURN. same byte, different name, plot twist ✨

enum CACA_CONIO_COLORS

DOS colours — the full retro sixteen plus blink, because DOS said "what if a colour was also a vibe":

enum CACA_CONIO_COLORS {
    CACA_CONIO_BLINK = 128, CACA_CONIO_BLACK = 0, CACA_CONIO_BLUE = 1,
    CACA_CONIO_GREEN = 2, CACA_CONIO_CYAN = 3, CACA_CONIO_RED = 4,
    CACA_CONIO_MAGENTA = 5, CACA_CONIO_BROWN = 6, CACA_CONIO_LIGHTGRAY = 7,
    CACA_CONIO_DARKGRAY = 8, CACA_CONIO_LIGHTBLUE = 9,
    CACA_CONIO_LIGHTGREEN = 10, CACA_CONIO_LIGHTCYAN = 11,
    CACA_CONIO_LIGHTRED = 12, CACA_CONIO_LIGHTMAGENTA = 13,
    CACA_CONIO_YELLOW = 14, CACA_CONIO_WHITE = 15
};

CACA_CONIO_BLINK = 128 is just out here living its best life at a totally different magnitude than everybody else 🎀

enum CACA_CONIO_CURSOR

DOS cursor modes, three of them, short and sweet:

enum CACA_CONIO_CURSOR {
    CACA_CONIO__NOCURSOR = 0, CACA_CONIO__SOLIDCURSOR = 1,
    CACA_CONIO__NORMALCURSOR = 2
};

yes those are double underscores in the names — CACA_CONIO__NOCURSOR, CACA_CONIO__SOLIDCURSOR, CACA_CONIO__NORMALCURSOR — that's not a typo, that's the actual spelling, do not "fix" it 🙈

enum CACA_CONIO_MODE

DOS video modes, and the values are spicy:

enum CACA_CONIO_MODE {
    CACA_CONIO_LASTMODE = -1, CACA_CONIO_BW40 = 0, CACA_CONIO_C40 = 1,
    CACA_CONIO_BW80 = 2, CACA_CONIO_C80 = 3, CACA_CONIO_MONO = 7,
    CACA_CONIO_C4350 = 64
};

CACA_CONIO_LASTMODE is literally -1 (negative! iconique) and CACA_CONIO_C4350 jumps all the way to 64 like it's got somewhere to be 💀 the numbers skip around, that's just how DOS rolls, we don't question the king 👑

more parts are coming, bestie, don't go anywhere 🌸

✨ DESCRIPTION ✨

okay so this is the actual toolbox part, the main character section 💅 — every function the header exposes, in the exact order the page lists them, and ngl it is a lot. Grab a snack, we're going through all of it 🍓

🎀 Functions 🎀

  • __extern caca_canvas_t * caca_create_canvas (int, int) — gets you a fresh, brand-new libcaca canvas ✨ like, the actual starting point for everything.
  • __extern int caca_manage_canvas (caca_canvas_t *, int(*)(void *), void *) — puts a canvas under libcaca's management, callback-style, with that int(*)(void *) and its void * buddy along for the ride 🫶
  • __extern int caca_unmanage_canvas (caca_canvas_t *, int(*)(void *), void *) — unmanages a canvas 💅 same callback + pointer pairing, just going the other way.
  • __extern int caca_set_canvas_size (caca_canvas_t *, int, int) — resizes the canvas, glow-up edition 🌸
  • __extern int caca_get_canvas_width (caca_canvas_t const *) — how wide is it rn 🦋
  • __extern int caca_get_canvas_height (caca_canvas_t const *) — and how tall 💜
  • __extern uint32_t const * caca_get_canvas_chars (caca_canvas_t const *) — hands you the canvas character array, all uint32_t const * and raw and iconic 👑
  • __extern uint32_t const * caca_get_canvas_attrs (caca_canvas_t const *) — same deal but for the attribute array, no cap ⭐
  • __extern int caca_free_canvas (caca_canvas_t *) — frees a libcaca canvas. say bye bestie 💀
  • __extern int caca_rand (int, int) — the page literally gives this one no description, not even a crumb 😭 so I'm not gonna invent one. it's there, it takes two ints, that's all the manpage is giving us 🙈
  • __extern char const * caca_get_version (void) — returns the libcaca version string, so you can check who you're dealing with 💅
  • __extern int caca_gotoxy (caca_canvas_t *, int, int) — sets the cursor position 🎯
  • __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 one ASCII or Unicode character, little guy, big impact ✨
  • __extern uint32_t caca_get_char (caca_canvas_t const *, int, int) — grabs the Unicode character sitting at those coordinates 🔍
  • __extern int caca_put_str (caca_canvas_t *, int, int, char const *) — prints a whole string, main character energy 💖
  • __extern int caca_printf (caca_canvas_t *, int, int, char const *,...) — prints a formated string, printf-style 🎀
  • __extern int caca_vprintf (caca_canvas_t *, int, int, char const *, va_list) — the va_list version of the above, for when you're being fancy 🧚
  • __extern int caca_clear_canvas (caca_canvas_t *) — clears the canvas. fresh start, we love a reset 🌈
  • __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 one canvas onto another one, and yes there are two caca_canvas_t const * params in there, copy the signature exactly bestie 🔥
  • __extern int caca_set_canvas_boundaries (caca_canvas_t *, int, int, int, int) — sets a canvas' new boundaries, four whole ints of it ✨
  • __extern int caca_disable_dirty_rect (caca_canvas_t *) — disables dirty rectangles 🙈
  • __extern int caca_enable_dirty_rect (caca_canvas_t *) — enables them right back up 💅
  • __extern int caca_get_dirty_rect_count (caca_canvas_t *) — how many dirty rectangles are in the canvas rn, the vibes count 🔢
  • __extern int caca_get_dirty_rect (caca_canvas_t *, int, int *, int *, int *, int *) — pulls out one canvas dirty rectangle, four int *s of output, it's giving pointer soup but it slays 🫶
  • __extern int caca_add_dirty_rect (caca_canvas_t *, int, int, int, int) — adds an area to the canvas's dirty rectangle list ✅
  • __extern int caca_remove_dirty_rect (caca_canvas_t *, int, int, int, int) — removes an area from the dirty rectangle list ❌
  • __extern int caca_clear_dirty_rect_list (caca_canvas_t *) — nukes the whole canvas dirty rectangle list in one go 🧹
  • __extern int caca_invert (caca_canvas_t *) — inverts a canvas' colours, spooky season 💀
  • __extern int caca_flip (caca_canvas_t *) — flips a canvas horizontally 🦋
  • __extern int caca_flop (caca_canvas_t *) — flips a canvas vertically 🌸
  • __extern int caca_rotate_180 (caca_canvas_t *) — rotates a canvas 🎡
  • __extern int caca_rotate_left (caca_canvas_t *) — rotates a canvas, 90 degrees counterclockwise 💫
  • __extern int caca_rotate_right (caca_canvas_t *) — rotates a canvas, 90 degrees counterclockwise. yep, that's what the page says for this one too 👀 not me editing the docs, I'm just the messenger 🙈
  • __extern int caca_stretch_left (caca_canvas_t *) — rotates and stretches a canvas, 90 degrees counterclockwise ✨ stretch before the rotate, we're flexible 🧘
  • __extern int caca_stretch_right (caca_canvas_t *) — rotates and stretches a canvas, 90 degrees clockwise 🔥
  • __extern uint32_t caca_get_attr (caca_canvas_t const *, int, int) — gets the text attribute at the given coordinates 🎀
  • __extern int caca_set_attr (caca_canvas_t *, uint32_t) — sets the default character attribute, the blueprint of your whole look 💅
  • __extern int caca_unset_attr (caca_canvas_t *, uint32_t) — unsets specific flags in the default character attribute 🫶
  • __extern int caca_toggle_attr (caca_canvas_t *, uint32_t) — toggles flags in the default character attribute, on-off-on-off 💖
  • __extern int caca_put_attr (caca_canvas_t *, int, int, uint32_t) — sets the character attribute at the given coordinates, one cell at a time ✨
  • __extern int caca_set_color_ansi (caca_canvas_t *, uint8_t, uint8_t) — sets the default colour pair for text, ANSI version 🌈
  • __extern int caca_set_color_argb (caca_canvas_t *, uint16_t, uint16_t) — sets the default colour pair for text, truecolor version, the fancy one 👑
  • __extern uint8_t caca_attr_to_ansi (uint32_t) — gets DOS ANSI information out of an attribute 🔍
  • __extern uint8_t caca_attr_to_ansi_fg (uint32_t) — gets just the ANSI foreground information out of an attribute 🌸
  • __extern uint8_t caca_attr_to_ansi_bg (uint32_t) — gets just the ANSI background information out of an attribute 🌸
  • __extern uint16_t caca_attr_to_rgb12_fg (uint32_t) — gets 12-bit RGB foreground information out of an attribute 🎨
  • __extern uint16_t caca_attr_to_rgb12_bg (uint32_t) — gets 12-bit RGB background information out of an attribute 🎨
  • __extern void caca_attr_to_argb64 (uint32_t, uint8_t[8]) — gets 64-bit ARGB information out of an attribute, straight into that uint8_t[8] array 💾
  • __extern uint32_t caca_utf8_to_utf32 (char const *, size_t *) — converts a UTF-8 character to UTF-32, glow-up across encodings 🦋
  • __extern size_t caca_utf32_to_utf8 (char *, uint32_t) — converts a UTF-32 character to UTF-8, reverse glow-up 💫
  • __extern uint8_t caca_utf32_to_cp437 (uint32_t) — converts a UTF-32 character to CP437, retro era 🕹️
  • __extern uint32_t caca_cp437_to_utf32 (uint8_t) — converts a CP437 character to UTF-32, back to the future 🚀
  • __extern char caca_utf32_to_ascii (uint32_t) — converts a UTF-32 character to ASCII, downsizing but make it chic 💅
  • __extern int caca_utf32_is_fullwidth (uint32_t) — tells you whether a UTF-32 character is fullwidth, the vibe check for wide characters 🫶
  • __extern int caca_draw_line (caca_canvas_t *, int, int, int, int, uint32_t) — draws a line on the canvas using the character you hand it ✏️
  • __extern int caca_draw_polyline (caca_canvas_t *, int const x[], int const y[], int, uint32_t) — draws a polyline from those x[] and y[] arrays, multi-point slay 🔥
  • __extern int caca_draw_thin_line (caca_canvas_t *, int, int, int, int) — draws a thin line on the canvas, using ASCII art 🎀
  • __extern int caca_draw_thin_polyline (caca_canvas_t *, int const x[], int const y[], int) — draws an ASCII art thin polyline, delicate little thing 🌸
  • __extern int caca_draw_circle (caca_canvas_t *, int, int, int, uint32_t) — draws a circle on the canvas using the given character ⭕
  • __extern int caca_draw_ellipse (caca_canvas_t *, int, int, int, int, uint32_t) — draws an ellipse on the canvas using the given character 🥚
  • __extern int caca_draw_thin_ellipse (caca_canvas_t *, int, int, int, int) — draws a thin ellipse on the canvas 🪶
  • __extern int caca_fill_ellipse (caca_canvas_t *, int, int, int, int, uint32_t) — fills an ellipse on the canvas using the given character, no hollow vibes allowed 🙅
  • __extern int caca_draw_box (caca_canvas_t *, int, int, int, int, uint32_t) — draws a box on the canvas using the given character 📦
  • __extern int caca_draw_thin_box (caca_canvas_t *, int, int, int, int) — draws a thin box on the canvas 🎁
  • __extern int caca_draw_cp437_box (caca_canvas_t *, int, int, int, int) — draws a box on the canvas using CP437 characters, old-school but iconic 🕹️
  • __extern int caca_fill_box (caca_canvas_t *, int, int, int, int, uint32_t) — fills a box on the canvas using the given character 🟪
  • __extern int caca_draw_triangle (caca_canvas_t *, int, int, int, int, int, int, uint32_t) — draws a triangle on the canvas using the given character 🔺
  • __extern int caca_draw_thin_triangle (caca_canvas_t *, int, int, int, int, int, int) — draws a thin triangle on the canvas 📐
  • __extern int caca_fill_triangle (caca_canvas_t *, int, int, int, int, int, int, uint32_t) — fills a triangle on the canvas using the given character 🍕
  • __extern int caca_fill_triangle_textured (caca_canvas_t *cv, int coords[6], caca_canvas_t *tex, float uv[6]) — fills a triangle on the canvas using an arbitrary-sized texture, and yes the params are literally int coords[6], caca_canvas_t *tex and float uv[6], copy them exactly bestie 🖼️
  • __extern int caca_get_frame_count (caca_canvas_t const *) — how many frames does this canvas have 🎞️
  • __extern int caca_set_frame (caca_canvas_t *, int) — activates a given canvas frame, spotlight time ✨
  • __extern char const * caca_get_frame_name (caca_canvas_t const *) — gets the current frame's name 🏷️
  • __extern int caca_set_frame_name (caca_canvas_t *, char const *) — sets the current frame's name, give it a cute one 💖
  • __extern int caca_create_frame (caca_canvas_t *, int) — adds a frame to a canvas, more frames more fun 🎬
  • __extern int caca_free_frame (caca_canvas_t *, int) — removes a frame from a canvas, bye frame 💀
  • __extern caca_dither_t * caca_create_dither (int, int, int, int, uint32_t, uint32_t, uint32_t, uint32_t) — creates an internal dither object, four ints and four uint32_ts of it, lowkey a lot but she works 🎨
  • __extern int caca_set_dither_palette (caca_dither_t *, uint32_t r[], uint32_t g[], uint32_t b[], uint32_t a[]) — sets the palette of an 8bpp dither object, that's r[], g[], b[], a[] in that order 🌈
  • __extern int caca_set_dither_brightness (caca_dither_t *, float) — sets the brightness of a dither object ☀️
  • __extern float caca_get_dither_brightness (caca_dither_t const *) — gets the brightness of a dither object 🌤️
  • __extern int caca_set_dither_gamma (caca_dither_t *, float) — sets the gamma of a dither object 🎚️
  • __extern float caca_get_dither_gamma (caca_dither_t const *) — gets the gamma of a dither object 📊
  • __extern int caca_set_dither_contrast (caca_dither_t *, float) — sets the contrast of a dither object 🌗
  • __extern float caca_get_dither_contrast (caca_dither_t const *) — gets the contrast of a dither object 🌓
  • __extern int caca_set_dither_antialias (caca_dither_t *, char const *) — sets dither antialiasing 🪄
  • __extern char const *const * caca_get_dither_antialias_list (caca_dither_t const *) — gets the available antialiasing methods, note the char const *const * return, type it exactly 💅
  • __extern char const * caca_get_dither_antialias (caca_dither_t const *) — gets the current antialiasing method 🔎
  • __extern int caca_set_dither_color (caca_dither_t *, char const *) — chooses the colours used for dithering 🎨
  • __extern char const *const * caca_get_dither_color_list (caca_dither_t const *) — gets the available colour modes 🌈
  • __extern char const * caca_get_dither_color (caca_dither_t const *) — gets the current colour mode 🖍️
  • __extern int caca_set_dither_charset (caca_dither_t *, char const *) — chooses the characters used for dithering 🔤
  • __extern char const *const * caca_get_dither_charset_list (caca_dither_t const *) — gets the available dither character sets 📚
  • __extern char const * caca_get_dither_charset (caca_dither_t const *) — gets the current character set ✨

and that's the whole function wall bestie, every single one, nothing skipped 😤 keep reading, there's more coming 💖

Dithering time 💅 these are the ones that make your bitmaps look all retro-gorgeous:

  • __extern int caca_set_dither_algorithm (caca_dither_t *, char const *) — picks the dithering algorithm for your dither, slay ✨
  • __extern char const *const * caca_get_dither_algorithm_list (caca_dither_t const *) — hands you the whole list of dithering algorithms 🎀
  • __extern char const * caca_get_dither_algorithm (caca_dither_t const *) — which algorithm is it using rn 👀
  • __extern int caca_dither_bitmap (caca_canvas_t *, int, int, int, int, caca_dither_t const *, void const *) — dithers a whole bitmap onto the canvas</b>, iconic 🦋
  • __extern int caca_free_dither (caca_dither_t *) — frees the memory tied to a dither, bye bestie 👋

Fonts and glyphs, aka the glow-up section 💜:

  • __extern caca_charfont_t * caca_load_charfont (void const *, size_t)
  • __extern int caca_free_charfont (caca_charfont_t *)
  • __extern caca_font_t * caca_load_font (void const *, size_t) — loads a font straight outta memory so it's ready for later ✨
  • __extern char const *const * caca_get_font_list (void) — the builtin fonts you've got available 🎀
  • __extern int caca_get_font_width (caca_font_t const *) — the font's standard glyph width, no cap 📏
  • __extern int caca_get_font_height (caca_font_t const *) — the font's standard glyph height 📐
  • __extern uint32_t const * caca_get_font_blocks (caca_font_t const *) — the list of glyphs that font actually supports 🫶
  • __extern int caca_render_canvas (caca_canvas_t const *, caca_font_t const *, void *, int, int, int) — renders the canvas onto an image buffer, literally art 🔥
  • __extern int caca_free_font (caca_font_t *) — frees a font structure 🎀

Figlet-adjacent era 🧚 (yes these are all exactly what they sound like):

  • __extern int caca_canvas_set_figfont (caca_canvas_t *, char const *) — loads a figfont and attaches it to a canvas ✨
  • __extern int caca_set_figfont_smush (caca_canvas_t *, char const *) — sets the smushing mode for the figfont rendering 💅
  • __extern int caca_set_figfont_width (caca_canvas_t *, int) — sets the width of the figfont rendering 🎀
  • __extern int caca_put_figchar (caca_canvas_t *, uint32_t) — pastes a character using the current figfont 🦋
  • __extern int caca_flush_figlet (caca_canvas_t *) — flushes the figlet context, periodt 🌸

File handling, because sometimes you just gotta read a file 😭:

  • __extern caca_file_t * caca_file_open (char const *, const char *) — opens a file for reading or writing 📂
  • __extern int caca_file_close (caca_file_t *) — closes a file handle 👋
  • __extern uint64_t caca_file_tell (caca_file_t *) — where you at in the file handle 📍
  • __extern size_t caca_file_read (caca_file_t *, void *, size_t) — reads data out of a file handle 📖
  • __extern size_t caca_file_write (caca_file_t *, const void *, size_t) — writes data into a file handle ✍️
  • __extern char * caca_file_gets (caca_file_t *, char *, int) — reads one line from a file handle 🍓
  • __extern int caca_file_eof (caca_file_t *) — tells you if the file handle hit end of file 🏁

Import/export 🦋 the trading-cards arc:

  • __extern ssize_t caca_import_canvas_from_memory (caca_canvas_t *, void const *, size_t, char const *) — imports a memory buffer into a canvas ✨
  • __extern ssize_t caca_import_canvas_from_file (caca_canvas_t *, char const *, char const *) — imports a file into a canvas 📥
  • __extern ssize_t caca_import_area_from_memory (caca_canvas_t *, int, int, void const *, size_t, char const *) — imports a memory buffer into a canvas area 🎯
  • __extern ssize_t caca_import_area_from_file (caca_canvas_t *, int, int, char const *, char const *) — imports a file into a canvas area 📥
  • __extern char const *const * caca_get_import_list (void) — all the import formats you can use 💅
  • __extern void * caca_export_canvas_to_memory (caca_canvas_t const *, char const *, size_t *) — exports a canvas into a foreign format, main character energy 👑
  • __extern void * caca_export_area_to_memory (caca_canvas_t const *, int, int, int, int, char const *, size_t *) — exports just a portion of a canvas into a foreign format 🍓
  • __extern char const *const * caca_get_export_list (void) — all the export formats you can use 🌈

Display stuff 🖥️ the whole vibe check of libcaca:

  • __extern caca_display_t * caca_create_display (caca_canvas_t *) — attaches a caca graphical context to a caca canvas ✨
  • __extern caca_display_t * caca_create_display_with_driver (caca_canvas_t *, char const *) — same thing but with a specific caca graphical context 🎀
  • __extern char const *const * caca_get_display_driver_list (void) — the display drivers you've got available 💅
  • __extern char const * caca_get_display_driver (caca_display_t *) — which output driver a caca graphical context is currently on 👀
  • __extern int caca_set_display_driver (caca_display_t *, char const *) — sets the output driver 🛠️
  • __extern int caca_free_display (caca_display_t *) — detaches a caca graphical context from a caca backend context 👋
  • __extern caca_canvas_t * caca_get_canvas (caca_display_t *) — grabs the canvas attached to a caca graphical context 🎨
  • __extern int caca_refresh_display (caca_display_t *) — flushes pending changes and redraws the screen 🔄
  • __extern int caca_set_display_time (caca_display_t *, int) — sets the refresh delay ⏱️
  • __extern int caca_get_display_time (caca_display_t const *) — the display's average rendering time 📊
  • __extern int caca_get_display_width (caca_display_t const *) — the display width 📏
  • __extern int caca_get_display_height (caca_display_t const *) — the display height 📐
  • __extern int caca_set_display_title (caca_display_t *, char const *) — sets the display title 🏷️
  • __extern int caca_set_mouse (caca_display_t *, int) — shows or hides the mouse pointer 🖱️
  • __extern int caca_set_cursor (caca_display_t *, int) — shows or hides the cursor ✨

Events 🎮 input goes in, input goes out:

  • __extern int caca_get_event (caca_display_t *, int, caca_event_t *, int) — grabs the next mouse or keyboard input event ⌨️
  • __extern int caca_get_mouse_x (caca_display_t const *) — the X mouse coordinate 🖱️
  • __extern int caca_get_mouse_y (caca_display_t const *) — the Y mouse coordinate 🖱️
  • __extern enum caca_event_type caca_get_event_type (caca_event_t const *) — what type an event is 🏷️
  • __extern int caca_get_event_key_ch (caca_event_t const *) — a key press or key release event's value ⌨️
  • __extern uint32_t caca_get_event_key_utf32 (caca_event_t const *) — a key press or key release event's Unicode value 🌍
  • __extern int caca_get_event_key_utf8 (caca_event_t const *, char *) — a key press or key release event's UTF-8 value 🌈
  • __extern int caca_get_event_mouse_button (caca_event_t const *) — a mouse press or mouse release event's button 🖱️
  • __extern int caca_get_event_mouse_x (caca_event_t const *) — a mouse motion event's X coordinate 📍
  • __extern int caca_get_event_mouse_y (caca_event_t const *) — a mouse motion event's Y coordinate 📍
  • __extern int caca_get_event_resize_width (caca_event_t const *) — a resize event's display width value 📏
  • __extern int caca_get_event_resize_height (caca_event_t const *) — a resize event's display height value 📐
  • __extern int caca_getopt (int, char *const[], char const *, struct caca_option const *, int *)

And now 😭 the DOS conio.h emulation section, which is honestly such a serve — every single one of these is a DOS equivalent:

  • __extern char * caca_conio_cgets (char *str) — DOS conio.h cgets() equivalent 💅
  • __extern void caca_conio_clreol (void) — DOS conio.h clreol() equivalent ✨
  • __extern void caca_conio_clrscr (void) — DOS conio.h clrscr() equivalent 🧼
  • __extern int caca_conio_cprintf (const char *format,...) — DOS conio.h cprintf() equivalent 🖨️
  • __extern int caca_conio_cputs (const char *str) — DOS conio.h cputs() equivalent 💬
  • __extern int caca_conio_cscanf (char *format,...) — DOS stdio.h cscanf() equivalent 📥
  • __extern void caca_conio_delay (unsigned int) — DOS dos.h delay() equivalent ⏳
  • __extern void caca_conio_delline (void) — DOS conio.h delline() equivalent ✂️
  • __extern int caca_conio_getch (void) — DOS conio.h getch() equivalent ⌨️
  • __extern int caca_conio_getche (void) — DOS conio.h getche() equivalent ⌨️
  • __extern char * caca_conio_getpass (const char *prompt) — DOS conio.h getpass() equivalent 🔐
  • __extern int caca_conio_gettext (int left, int top, int right, int bottom, void *destin) — DOS conio.h gettext() equivalent 📋
  • __extern void caca_conio_gettextinfo (struct caca_conio_text_info *r) — DOS conio.h gettextinfo() equivalent 🗂️
  • __extern void caca_conio_gotoxy (int x, int y) — DOS conio.h gotoxy() equivalent 📍
  • __extern void caca_conio_highvideo (void) — DOS conio.h highvideo() equivalent 🔆
  • __extern void caca_conio_insline (void) — DOS conio.h insline() equivalent ➕
  • __extern int caca_conio_kbhit (void) — DOS conio.h kbhit() equivalent ⌨️
  • __extern void caca_conio_lowvideo (void) — DOS conio.h lowvideo() equivalent 🔅
  • __extern int caca_conio_movetext (int left, int top, int right, int bottom, int destleft, int desttop) — DOS conio.h movetext() equivalent 🚚
  • __extern void caca_conio_normvideo (void) — DOS conio.h normvideo() equivalent 🎚️
  • __extern void caca_conio_nosound (void) — DOS dos.h nosound() equivalent 🔇
  • __extern int caca_conio_printf (const char *format,...) — DOS stdio.h printf() equivalent 🖨️
  • __extern int caca_conio_putch (int ch) — DOS conio.h putch() equivalent ✍️
  • __extern int caca_conio_puttext (int left, int top, int right, int bottom, void *destin) — DOS conio.h puttext() equivalent 📤
  • __extern void caca_conio__setcursortype (int cur_t) — DOS conio.h _setcursortype() equivalent 🖱️
  • __extern void caca_conio_sleep (unsigned int) — DOS dos.h sleep() equivalent 😴
  • __extern void caca_conio_sound (unsigned int) — DOS dos.h sound() equivalent 🔊
  • __extern void caca_conio_textattr (int newattr) — DOS conio.h textattr() equivalent 🎨
  • __extern void caca_conio_textbackground (int newcolor) — DOS conio.h textbackground() equivalent 🖌️
  • __extern void caca_conio_textcolor (int newcolor) — DOS conio.h textcolor() equivalent 🖍️
  • __extern void caca_conio_textmode (int newmode) — DOS conio.h textmode() equivalent 🖥️
  • __extern int caca_conio_ungetch (int ch) — DOS conio.h ungetch() equivalent ↩️
  • __extern int caca_conio_wherex (void) — DOS conio.h wherex() equivalent 📍
  • __extern int caca_conio_wherey (void) — DOS conio.h wherey() equivalent 📍
  • __extern void caca_conio_window (int left, int top, int right, int bottom) — DOS conio.h window() equivalent 🪟

🎀 Variables 🎀

The globals bestie, they're just sitting there being variables:

  • __extern int caca_optind
  • __extern char * caca_optarg
  • __extern int caca_conio_directvideo — DOS direct video control 📺
  • __extern int caca_conio__wscroll — DOS scrolling control 📜

💖 Detailed Description 💖

Okay so the actual tea on this header 🫖:

🌸 Author 🌸

Sam Hocevar sam@hocevar.net — king behaviour honestly 👑

✨ What it is ✨

This header contains the public types and functions that applications using libcaca may use. That's it, that's the whole lore 💅

🦋 Macro Definition Documentation 🦋

🎀 #define CACA_API_VERSION_1 🎀

libcaca API version ✨ fr fr that's what it is, no cap 🫶

✨ Typedef Documentation ✨

okay bestie so this is the part where libcaca hands you a bunch of cute lil' typedefs — think of them as the nicknames it gave to its structs so you don't have to type struct every single time 💅 like they're all basically "this is the handle, go wild with it" and you don't ever touch the actual guts of them. periodt.

  • typedef struct caca_canvas caca_canvas_t — the libcaca canvas. that's your whole drawing surface, your main character energy 💖 everything you print, paint, or blit lives here.
  • typedef struct caca_dither caca_dither_t — the dither structure. dithering is the vibe where you fake a bunch of colours using fewer colours, and this is the handle for that 🎀
  • typedef struct caca_charfont caca_charfont_t — the character font structure. fonty business, but the character kind ✨
  • typedef struct caca_font caca_font_t — the bitmap font structure. the classic bitmap kind of font, iconic, no notes.
  • typedef struct caca_file caca_file_t — the file handle structure. yup, it's a file, and yes it's a handle 🫶
  • typedef struct caca_file caca_file_t — (already said it, but like, bestie, it's the file handle structure, that's the whole thing 😭)
  • typedef struct caca_display caca_display_t — the libcaca display context. this is your window to the world, literally — the thing that shows your canvas on screen 🌈
  • typedef struct caca_event caca_event_t — the libcaca event structure. every keypress, mouse wiggle, and resize lands here, lowkey the gossip channel of the whole library 💀
ngl these are all opaque handles — the docs above literally describe what each typedef is, so don't go poking at the struct fields, that's not the assignment bestie 🙈

👑 Author 👑

okay and who wrote all this? the manpage says it straight up:

Generated automatically by Doxygen for libcaca from the source code.

so like, no human author to thank for this exact page — the Doxygen robot did it, and it ate 🔥 (the library itself is another story, but that's not what this bit says, so we're not gonna pretend it does ✨).

and that's a wrap on caca.h(3caca), bestie!! 🎀💖 this page is from Version 0.99.beta20, dated Wed May 13 2026 09:45:08 — screenshot it, cite it, love it, and go make something iconic with libcaca 💅🦋🌸 byeee 🌈⭐

📦 where this page comes from