libcaca documentation

Functions
libcaca bitmap font handling

## Functions
__extern caca_font_t * | caca_load_font (void const *, size_t)
| Load a font from memory for future use. More...
__extern char const *const * | caca_get_font_list (void)
| Get available builtin fonts. More...
__extern int | caca_get_font_width (caca_font_t const *)
| Get a font's standard glyph width. More...
__extern int | caca_get_font_height (caca_font_t const *)
| Get a font's standard glyph height. More...
__extern uint32_t const * | caca_get_font_blocks (caca_font_t const *)
| Get a font's list of supported glyphs. More...
__extern int | caca_render_canvas (caca_canvas_t const *, caca_font_t const *, void *, int, int, int)
| Render the canvas onto an image buffer. More...
__extern int | caca_free_font (caca_font_t *)
| Free a font structure. More...

## 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.

__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:

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

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.