walkero
/
harfbuzz
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[Docs, usermanual] Reword hb_ft_font_create_referenced explanation

This commit is contained in:
n8willis 2020-04-19 15:26:28 +01:00 committed by GitHub
parent b57b904242
commit d6edd9a408
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 19 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/usermanual-integration.xml
View File

@ -207,18 +207,27 @@
FT_Set_Char_Size(face, 0, 1000, 0, 0);
hb_font_t *font = hb_ft_font_create(face);
</programlisting>
<para>
<function>hb_ft_font_create_referenced()</function> is
the recommended function for creating an <type>hb_face_t</type> face
object. This function calls <function>FT_Reference_Face()</function>
before using the <type>FT_Face</type> and calls
<function>FT_Done_Face()</function> when it is finished using the
<type>FT_Face</type>. Consequently, your client program does not need
to worry about destroying the <type>FT_Face</type> while HarfBuzz
is still using it.
</para>
<para>
Although <function>hb_ft_font_create_referenced()</function> is
the recommended function, there is another variant. The simpler
version of the function is
<function>hb_ft_font_create()</function>, which takes an
<type>FT_Face</type> and an optional destroy callback as its
arguments. The critical difference between the two is that
<function>hb_ft_font_create()</function> does not offer the
lifecycle-management feature. Your client code will be
responsible for tracking references to the <type>FT_Face</type> objects and
destroying them when they are no longer needed. If you do not
have a valid reason for doing this, user
the recommended function, there is another variant for client code
where special circumstances make it necessary. The simpler
version of the function is <function>hb_ft_font_create()</function>,
which takes an <type>FT_Face</type> and an optional destroy callback
as its arguments. Because <function>hb_ft_font_create()</function>
does not offer lifecycle management, however, your client code will
be responsible for tracking references to the <type>FT_Face</type>
objects and destroying them when they are no longer needed. If you
do not have a valid reason for doing this, use
<function>hb_ft_font_create_referenced()</function>.
</para>
<para>