Functions

libcaca bitmap font handling

Functions

caca_font_tcaca_load_font (void const *, size_t)
 Load a font from memory for future use.
char const *const caca_get_font_list (void)
 Get available builtin fonts.
int caca_get_font_width (caca_font_t const *)
 Get a font's standard glyph width.
int caca_get_font_height (caca_font_t const *)
 Get a font's standard glyph height.
uint32_t const * caca_get_font_blocks (caca_font_t const *)
 Get a font's list of supported glyphs.
int caca_render_canvas (caca_canvas_t const *, caca_font_t const *, void *, int, int, int)
 Render the canvas onto an image buffer.
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

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().

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.
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.
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.
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.
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().

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.