.\"Copyright 2010 (c) EPFL
.TH DTK_LOAD_FONT 3 2010 "EPFL" "Draw Toolkit manual"
.SH NAME
dtk_load_font - Load an font
.SH SYNOPSIS
.LP
.B #include <drawtk.h>
.sp
.BI "dtk_hfont dtk_load_font(const char *" fontname ");"
.br
.BI "void dtk_destroy_font(dtk_hfont " font ");"
.br
.SH DESCRIPTION
.LP
\fBdtk_load_font\fP() loads the font specified by \fIfontname\fP
argument. This should be the path of a file whose file format can be any of
the file format supported by the freetype library (TrueType and Type 1 among
many others) or a font description pattern understood by fontconfig (like
"Times new roman:bold"). \fBdtk_load_font\fP() will first interpret
\fIfontname\fP as a font filename and then, if this fail interpret as a font
pattern and load the closest font available on the system.
.LP
Upon creation, the font data is then tracked by an internal resource manager
so that the next call using the same \fIfontname\fP argument will return the
same font handle, thus sparing the resources of the system. 
.LP
There is no need for a valid window to create successfully a font, i.e.
font loading is completely decoupled from the creation of others
resources and can even be created in one thread to be used in another one.
.LP
\fBdtk_destroy_font\fP() frees the resource referenced by \fIfont\fP. If the
font is used several times, i.e. several call to \fBdtk_load_font\fP() with
the same file path, it decreases the number of uses by one.
.LP
Calling \fBdtk_destroy_texture\fP() on each created font is currently not
mandatory since all font remaining fonts are destroyed when the last
window is closed. However, if no window can be closed (for example, no
window has been created), \fBdtk_destroy_font\fP() should be called on each
created font to avoid any memory leak.
.SH "RETURN VALUE"
.LP
In case of success, the \fBdtk_load_font\fP() returns the handle to the
loaded font. In case of failure, \fINULL\fP is returned.
.LP
\fBdtk_destroy_texture\fP() does not return any value.
.SH "THREAD SAFETY"
.LP
\fBdtk_load_font\fP() and \fBdtk_destroy_texture\fP() are thread-safe.
.SH "SEE ALSO"
.BR dtk_create_string (3)
.BR fc-list (1)
.BR FcPatternFormat (3)