font

libcucul font handling(3caca)       libcaca      libcucul font handling(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.

       References cucul_load_font().

       Referenced by cucul_load_font().

   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.

Version 0.99.beta11               21 Feb 2008    libcucul font handling(3caca)