libcaca documentation

# libcucul font handling

## Functions
cucul_font_t * | cucul_load_font (void const *, unsigned int)
| Load a font from memory for future use.
char const *const * | cucul_get_font_list (void)
| Get available builtin fonts.
unsigned int | cucul_get_font_width (cucul_font_t *)
| Get a font's standard glyph width.
unsigned int | cucul_get_font_height (cucul_font_t *)
| Get a font's standard glyph height.
unsigned long int const * | cucul_get_font_blocks (cucul_font_t *)
| Get a font's list of supported glyphs.
int | cucul_render_canvas (cucul_canvas_t *, cucul_font_t *, void *, unsigned int, unsigned int, unsigned int)
| Render the canvas onto an image buffer.
int | cucul_free_font (cucul_font_t *)
| Free a font structure.

## Detailed Description

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

## Function Documentation

cucul_font_t* cucul_load_font | ( | void const * | data,
|  | unsigned int | size |
| ) |  |  |

This function loads a font and returns a handle to its internal structure. The handle can then be used with cucul_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 cucul_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.

char const* const* cucul_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.

unsigned int cucul_get_font_width | ( | cucul_font_t * | 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 cucul_load_font()

Returns:
  The standard glyph width.

unsigned int cucul_get_font_height | ( | cucul_font_t * | 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 cucul_load_font()

Returns:
  The standard glyph height.

unsigned long int const* cucul_get_font_blocks | ( | cucul_font_t * | 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 cucul_load_font()

Returns:
  The list of Unicode blocks supported by the font.

int cucul_render_canvas | ( | cucul_canvas_t * | cv,
|  | cucul_font_t * | f,
|  | void * | buf,
|  | unsigned int | width,
|  | unsigned int | height,
|  | unsigned 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 cucul_get_canvas_width() and cucul_get_font_width(). The required height can be computed using cucul_get_canvas_height() and cucul_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.

This function never fails.

Parameters:

  | cv | The canvas to render
  | f | The font, as returned by cucul_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:
  This function always returns 0.

int cucul_free_font | ( | cucul_font_t * | f | ) |

This function frees all data allocated by cucul_load_font(). The font structure is no longer usable by other libcucul functions. Once this function has returned, the memory area that was given to cucul_load_font() can be freed.

This function never fails.

Parameters:

  | f | The font, as returned by cucul_load_font()

Returns:
  This function always returns 0.