caca_font(3caca)

🎀 NAME 🎀

caca_font — libcaca bitmap font handling

okay so this is the page for caca_font(3caca), like, the whole libcaca bitmap font situation. buckle up bestie 💖

---

✨ SYNOPSIS ✨

🦋 Topics

• libcaca FIGfont handling

🌸 Functions

• __extern caca_font_t * caca_load_font (void const *, size_t) — loads a font from memory so you can use it later, slay
• __extern char const *const * caca_get_font_list (void) — gives you all the builtin fonts that exist
• __extern int caca_get_font_width (caca_font_t const *) — the standard glyph width of a font
• __extern int caca_get_font_height (caca_font_t const *) — the standard glyph height of a font
• __extern uint32_t const * caca_get_font_blocks (caca_font_t const *) — the list of glyphs a 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, iconic
• __extern int caca_free_font (caca_font_t *) — frees a font structure, bye bestie 👋

---

🌈 Detailed Description

these functions are literally the bitmap font handling squad 💅 they also do high quality canvas-to-bitmap rendering. main character energy tbh.

---

👑 Function Documentation

🌟 __extern caca_font_t * caca_load_font (void const * data, size_t size)

this function loads a font and hands you back a handle to its internal structure. you can then use that handle with caca_render_canvas() to get bitmap output. no cap ✨

internal fonts can also be loaded too: if size is set to 0, then data must be a string containing the internal font name.

if size is non-zero, then the size bytes of memory at address data get loaded as a font. and listen — this memory area must not be freed by the calling program until the font handle has been freed with caca_free_font(). do not skip that part fr fr 🙈

if an error occurs, NULL is returned and errno is set accordingly:

• ENOENT — the requested built-in font does not exist 😭
• EINVAL — invalid font data in the memory area
• ENOMEM — not enough memory to allocate the font structure 💀

Parameters

• data — the memory area containing the font or its name.
• size — the size of the memory area, or 0 if the font name is given.

Returns

a font handle, or NULL in case of error.

References caca_load_font(), and caca_load_font().

Referenced by caca_load_font().

yeah it cites itself twice, don't ask, it's just that kind of function 🫶

---

⭐ __extern char const *const * caca_get_font_list (void)

returns a list of available builtin fonts. the list is a NULL-terminated array of strings. this function never fails — she simply cannot flop 💖

Returns

an array of strings.

---

🧚 __extern int caca_get_font_width (caca_font_t const * f)

returns the standard value for the current font's glyphs. most glyphs in the font will have this width, except fullwidth characters (they're built different).

this function never fails.

Parameters

• f — the font, as returned by caca_load_font()

Returns

the standard glyph width.

---

🍓 __extern int caca_get_font_height (caca_font_t const * f)

returns the standard value for the current font's glyphs. most glyphs in the font will have this height.

this function never fails.

Parameters

• f — the font, as returned by caca_load_font()

Returns

the standard glyph height.

---

🔥 __extern uint32_t const * caca_get_font_blocks (caca_font_t const * f)

this function returns the list of Unicode blocks supported by the given font. the list is a zero-terminated list of indices. here's an example so you can see the vibe:

{
   0x0000, 0x0080,   // Basic latin: A, B, C, a, b, c
   0x0080, 0x0100,   // Latin-1 supplement: "A, 'e, ^u
   0x0530, 0x0590,   // Armenian
   0x0000, 0x0000,   // END
};

this function never fails.

Parameters

• f — the font, as returned by caca_load_font()

Returns

the list of Unicode blocks supported by the font.

---

💜 __extern int caca_render_canvas (caca_canvas_t const * cv, caca_font_t const * f, void * buf, int width, int height, int pitch)

this function renders the given canvas onto an image buffer using a specific font. the pixel format is fixed — 32-bit ARGB, 8 bits for each component. no negotiating 💅

the required image width can be computed using caca_get_canvas_width() and caca_get_font_width(). the required height can be computed using caca_get_canvas_height() and caca_get_font_height().

glyphs that do not fit in the image buffer are currently not rendered at all. they may be cropped instead in future versions — so that's the current behaviour, noted, moving on 👀

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

• EINVAL — specified width, height or pitch is invalid.

Parameters

• cv — the canvas to render
• f — the font, as returned by caca_load_font()
• buf — the image buffer
• width — the width (in pixels) of the image buffer
• height — the height (in pixels) of the image buffer
• pitch — the pitch (in bytes) of an image buffer line.

Returns

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

References caca_attr_to_argb64().

---

🦄 __extern int caca_free_font (caca_font_t * f)

this function frees all data allocated by caca_load_font(). the font structure is no longer usable by other libcaca functions — she's retired, respect it. once this function has returned, the memory area that was given to caca_load_font() can be freed. finally 😭

this function never fails.

Parameters

• f — the font, as returned by caca_load_font()

Returns

this function always returns 0.

---

🌸 Author

Generated automatically by Doxygen for libcaca from the source code.

---

and that's the whole page, bestie 🫶 this was caca_font(3caca) from libcaca, version 0.99.beta20, dated Wed May 13 2026 09:45:08 — go forth and render some fonts, ily 💖✨