---
name: "font"
section: "3caca"
platform: "linux"
package: "libcucul-dev"
version: "0.99.beta11.debian-2"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/font/3caca"
---

# font(3caca)

## NAME

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.