.TH "caca_font" 3caca "Sat Apr 6 2019" "Version 0.99.beta19" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
caca_font
.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "__extern \fBcaca_font_t\fP * \fBcaca_load_font\fP (void const *, size_t)"
.br
.RI "Load a font from memory for future use\&. "
.ti -1c
.RI "__extern char const  *const  * \fBcaca_get_font_list\fP (void)"
.br
.RI "Get available builtin fonts\&. "
.ti -1c
.RI "__extern int \fBcaca_get_font_width\fP (\fBcaca_font_t\fP const *)"
.br
.RI "Get a font's standard glyph width\&. "
.ti -1c
.RI "__extern int \fBcaca_get_font_height\fP (\fBcaca_font_t\fP const *)"
.br
.RI "Get a font's standard glyph height\&. "
.ti -1c
.RI "__extern uint32_t const  * \fBcaca_get_font_blocks\fP (\fBcaca_font_t\fP const *)"
.br
.RI "Get a font's list of supported glyphs\&. "
.ti -1c
.RI "__extern int \fBcaca_render_canvas\fP (\fBcaca_canvas_t\fP const *, \fBcaca_font_t\fP const *, void *, int, int, int)"
.br
.RI "Render the canvas onto an image buffer\&. "
.ti -1c
.RI "__extern int \fBcaca_free_font\fP (\fBcaca_font_t\fP *)"
.br
.RI "Free a font structure\&. "
.in -1c
.SH "Detailed Description"
.PP 
These functions provide bitmap font handling routines and high quality canvas to bitmap rendering\&. 
.SH "Function Documentation"
.PP 
.SS "__extern \fBcaca_font_t\fP* 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 \fBcaca_render_canvas()\fP for bitmap output\&.
.PP
Internal fonts can also be loaded: if \fCsize\fP is set to 0, \fCdata\fP must be a string containing the internal font name\&.
.PP
If \fCsize\fP is non-zero, the \fCsize\fP bytes of memory at address \fCdata\fP are loaded as a font\&. This memory are must not be freed by the calling program until the font handle has been freed with \fBcaca_free_font()\fP\&.
.PP
If an error occurs, NULL is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOENT\fP Requested built-in font does not exist\&.
.IP "\(bu" 2
\fCEINVAL\fP Invalid font data in memory area\&.
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate font structure\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIdata\fP The memory area containing the font or its name\&. 
.br
\fIsize\fP The size of the memory area, or 0 if the font name is given\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
A font handle or NULL in case of error\&. 
.RE
.PP

.PP
Referenced by caca_get_export_list(), and caca_render_canvas()\&.
.SS "__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\&.
.PP
This function never fails\&.
.PP
\fBReturns:\fP
.RS 4
An array of strings\&. 
.RE
.PP

.PP
Referenced by caca_get_export_list(), and caca_render_canvas()\&.
.SS "__extern int caca_get_font_width (\fBcaca_font_t\fP const * f)"
Return the standard value for the current font's glyphs\&. Most glyphs in the font will have this width, except fullwidth characters\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIf\fP The font, as returned by \fBcaca_load_font()\fP 
.RE
.PP
\fBReturns:\fP
.RS 4
The standard glyph width\&. 
.RE
.PP

.PP
Referenced by caca_get_export_list(), and caca_render_canvas()\&.
.SS "__extern int caca_get_font_height (\fBcaca_font_t\fP const * f)"
Returns the standard value for the current font's glyphs\&. Most glyphs in the font will have this height\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIf\fP The font, as returned by \fBcaca_load_font()\fP 
.RE
.PP
\fBReturns:\fP
.RS 4
The standard glyph height\&. 
.RE
.PP

.PP
Referenced by caca_get_export_list(), and caca_render_canvas()\&.
.SS "__extern uint32_t const* caca_get_font_blocks (\fBcaca_font_t\fP 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:
.PP
.PP
.nf
{
   0x0000, 0x0080,   // Basic latin: A, B, C, a, b, c
   0x0080, 0x0100,   // Latin-1 supplement: "A, 'e, ^u
   0x0530, 0x0590,   // Armenian
   0x0000, 0x0000,   // END
};
.fi
.PP
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIf\fP The font, as returned by \fBcaca_load_font()\fP 
.RE
.PP
\fBReturns:\fP
.RS 4
The list of Unicode blocks supported by the font\&. 
.RE
.PP

.PP
Referenced by caca_render_canvas()\&.
.SS "__extern int caca_render_canvas (\fBcaca_canvas_t\fP const * cv, \fBcaca_font_t\fP 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)\&.
.PP
The required image width can be computed using \fBcaca_get_canvas_width()\fP and \fBcaca_get_font_width()\fP\&. The required height can be computed using \fBcaca_get_canvas_height()\fP and \fBcaca_get_font_height()\fP\&.
.PP
Glyphs that do not fit in the image buffer are currently not rendered at all\&. They may be cropped instead in future versions\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Specified width, height or pitch is invalid\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcv\fP The canvas to render 
.br
\fIf\fP The font, as returned by \fBcaca_load_font()\fP 
.br
\fIbuf\fP The image buffer 
.br
\fIwidth\fP The width (in pixels) of the image buffer 
.br
\fIheight\fP The height (in pixels) of the image buffer 
.br
\fIpitch\fP The pitch (in bytes) of an image buffer line\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.PP
References caca_attr_to_argb64(), caca_free_font(), caca_get_font_blocks(), caca_get_font_height(), caca_get_font_list(), caca_get_font_width(), and caca_load_font()\&.
.PP
Referenced by caca_get_export_list()\&.
.SS "__extern int caca_free_font (\fBcaca_font_t\fP * f)"
This function frees all data allocated by \fBcaca_load_font()\fP\&. The font structure is no longer usable by other libcaca functions\&. Once this function has returned, the memory area that was given to \fBcaca_load_font()\fP can be freed\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIf\fP The font, as returned by \fBcaca_load_font()\fP 
.RE
.PP
\fBReturns:\fP
.RS 4
This function always returns 0\&. 
.RE
.PP

.PP
Referenced by caca_get_export_list(), and caca_render_canvas()\&.
.SH "Author"
.PP 
Generated automatically by Doxygen for libcaca from the source code\&.