NAME

       dtk_load_font - Load an font

SYNOPSIS

       #include <drawtk.h>

       dtk_hfont dtk_load_font(const char *fontname);
       void dtk_destroy_font(dtk_hfont font);

DESCRIPTION

       dtk_load_font()  loads the font specified by fontname 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"). dtk_load_font() will first interpret fontname as
       a  font  filename  and then, if this fail interpret as a font pattern and load the closest
       font available on the system.

       Upon creation, the font data is then tracked by an internal resource manager so  that  the
       next  call using the same fontname argument will return the same font handle, thus sparing
       the resources of the system.

       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.

       dtk_destroy_font() frees the resource referenced by font. If  the  font  is  used  several
       times,  i.e.  several  call  to  dtk_load_font() with the same file path, it decreases the
       number of uses by one.

       Calling dtk_destroy_texture() 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),  dtk_destroy_font()  should  be
       called on each created font to avoid any memory leak.

RETURN VALUE

       In  case of success, the dtk_load_font() returns the handle to the loaded font. In case of
       failure, NULL is returned.

       dtk_destroy_texture() does not return any value.

THREAD SAFETY

       dtk_load_font() and dtk_destroy_texture() are thread-safe.

SEE ALSO

       dtk_create_string(3) fc-list(1) FcPatternFormat(3)