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); FT_Set_Char_Size(face, 0, 1000, 0, 0);
hb_font_t *font = hb_ft_font_create(face); hb_font_t *font = hb_ft_font_create(face);
</programlisting> </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> <para>
Although <function>hb_ft_font_create_referenced()</function> is Although <function>hb_ft_font_create_referenced()</function> is
the recommended function, there is another variant. The simpler the recommended function, there is another variant for client code
version of the function is where special circumstances make it necessary. The simpler
<function>hb_ft_font_create()</function>, which takes an version of the function is <function>hb_ft_font_create()</function>,
<type>FT_Face</type> and an optional destroy callback as its which takes an <type>FT_Face</type> and an optional destroy callback
arguments. The critical difference between the two is that as its arguments. Because <function>hb_ft_font_create()</function>
<function>hb_ft_font_create()</function> does not offer the does not offer lifecycle management, however, your client code will
lifecycle-management feature. Your client code will be be responsible for tracking references to the <type>FT_Face</type>
responsible for tracking references to the <type>FT_Face</type> objects and objects and destroying them when they are no longer needed. If you
destroying them when they are no longer needed. If you do not do not have a valid reason for doing this, use
have a valid reason for doing this, user
<function>hb_ft_font_create_referenced()</function>. <function>hb_ft_font_create_referenced()</function>.
</para> </para>
<para> <para>