---
name: "caca_font"
section: "3caca"
platform: "linux"
package: "libcaca"
version: "0.99.beta20-7"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/caca_font"
---

# caca\_font(3caca)

libcaca bitmap font handling

## NAME

caca\_font - libcaca bitmap font handling

## SYNOPSIS

### Topics

**libcaca FIGfont handling**\

### Functions

\_\_extern **caca\_font\_t** \* **caca\_load\_font** (void const \*, size\_t)\
 Load a font from memory for future use.  \_\_extern char const \*const \* **caca\_get\_font\_list** (void)\
 Get available builtin fonts.  \_\_extern int **caca\_get\_font\_width** (**caca\_font\_t** const \*)\
 Get a font's standard glyph width.  \_\_extern int **caca\_get\_font\_height** (**caca\_font\_t** const \*)\
 Get a font's standard glyph height.  \_\_extern uint32\_t const \* **caca\_get\_font\_blocks** (**caca\_font\_t** const \*)\
 Get a font's list of supported glyphs.  \_\_extern int **caca\_render\_canvas** (**caca\_canvas\_t** const \*, **caca\_font\_t** const \*, void \*, int, int, int)\
 Render the canvas onto an image buffer.  \_\_extern int **caca\_free\_font** (**caca\_font\_t** \*)\
 Free a font structure.

## Detailed Description

These functions provide bitmap font handling routines and high quality canvas to bitmap rendering.

## Function Documentation

### \_\_extern caca\_font\_t \* caca\_load\_font (void const \* data, size\_t size)

This function loads a font and returns a handle to its internal structure. The handle can then be used with **caca\_render\_canvas()** for bitmap output.

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

If size is non-zero, the size bytes of memory at address data are loaded as a font. This memory are must not be freed by the calling program until the font handle has been freed with **caca\_free\_font()**.

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

- •

  ENOENT Requested built-in font does not exist.

- •

  EINVAL Invalid font data in memory area.

- •

  ENOMEM Not enough memory to allocate 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()**.

### \_\_extern char const \*const \* caca\_get\_font\_list (void )

Return a list of available builtin fonts. The list is a NULL-terminated array of strings.

This function never fails.

**Returns**

An array of strings.

### \_\_extern int caca\_get\_font\_width (caca\_font\_t const \* f)

Return the standard value for the current font's glyphs. Most glyphs in the font will have this width, except fullwidth characters.

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 is an example:

```
{
   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 on an image buffer using a specific font. The pixel format is fixed (32-bit ARGB, 8 bits for each component).

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.

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. Once this function has returned, the memory area that was given to **caca\_load\_font()** can be freed.

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.