Functions
libcaca bitmap font handling

Functions

__extern caca_font_tcaca_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:
dataThe memory area containing the font or its name.
sizeThe 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().

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:
fThe 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:
fThe 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:
fThe 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:
cvThe canvas to render
fThe font, as returned by caca_load_font()
bufThe image buffer
widthThe width (in pixels) of the image buffer
heightThe height (in pixels) of the image buffer
pitchThe 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:
fThe font, as returned by caca_load_font()
Returns:
This function always returns 0.