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

Merge pull request #1729 from n8willis/usermanual-integration 

[Docs] Usermanual: Add OS/platform-integration chapter
This commit is contained in:
Behdad Esfahbod 2020-04-24 08:15:32 -07:00 committed by GitHub
parent 5a0936f53e a11db0b9d4
commit cc1ed76f38
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 938 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/Makefile.am
View File

@ -83,6 +83,7 @@ content_files= \
usermanual-opentype-features.xml \ usermanual-opentype-features.xml \
usermanual-clusters.xml \ usermanual-clusters.xml \
usermanual-utilities.xml \ usermanual-utilities.xml \
usermanual-integration.xml \
version.xml version.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded

1
docs/harfbuzz-docs.xml
View File

@ -39,6 +39,7 @@
<xi:include href="usermanual-opentype-features.xml"/> <xi:include href="usermanual-opentype-features.xml"/>
<xi:include href="usermanual-clusters.xml"/> <xi:include href="usermanual-clusters.xml"/>
<xi:include href="usermanual-utilities.xml"/> <xi:include href="usermanual-utilities.xml"/>
<xi:include href="usermanual-integration.xml"/>
</part> </part>
<part> <part>

603
docs/usermanual-integration.xml Normal file
View File

@ -0,0 +1,603 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<chapter id="integration">
<title>Platform Integration Guide</title>
<para>
HarfBuzz was first developed for use with the GNOME and GTK
software stack commonly found in desktop Linux
distributions. Nevertheless, it can be used on other operating
systems and platforms, from iOS and macOS to Windows. It can also
be used with other application frameworks and components, such as
Android, Qt, or application-specific widget libraries.
</para>
<para>
This chapter will look at how HarfBuzz fits into a typical
text-rendering pipeline, and will discuss the APIs available to
integrate HarfBuzz with contemporary Linux, Mac, and Windows
software. It will also show how HarfBuzz integrates with popular
external libraries like FreeType and International Components for
Unicode (ICU) and describe the HarfBuzz language bindings for
Python.
</para>
<para>
On a GNOME system, HarfBuzz is designed to tie in with several
other common system libraries. The most common architecture uses
Pango at the layer directly "above" HarfBuzz; Pango is responsible
for text segmentation and for ensuring that each input
<type>hb_buffer_t</type> passed to HarfBuzz for shaping contains
Unicode code points that share the same segment properties
(namely, direction, language, and script, but also higher-level
properties like the active font, font style, and so on).
</para>
<para>
The layer directly "below" HarfBuzz is typically FreeType, which
is used to rasterize glyph outlines at the necessary optical size,
hinting settings, and pixel resolution. FreeType provides APIs for
accessing font and face information, so HarfBuzz includes
functions to create <type>hb_face_t</type> and
<type>hb_font_t</type> objects directly from FreeType
objects. HarfBuzz can use FreeType's built-in functions for
<structfield>font_funcs</structfield> vtable in an <type>hb_font_t</type>.
</para>
<para>
FreeType's output is bitmaps of the rasterized glyphs; on a
typical Linux system these will then be drawn by a graphics
library like Cairo, but those details are beyond HarfBuzz's
control. On the other hand, at the top end of the stack, Pango is
part of the larger GNOME framework, and HarfBuzz does include APIs
for working with key components of GNOME's higher-level libraries
&mdash; most notably GLib.
</para>
<para>
For other operating systems or application frameworks, the
critical integration points are where HarfBuzz gets font and face
information about the font used for shaping and where HarfBuzz
gets Unicode data about the input-buffer code points.
</para>
<para>
The font and face information is necessary for text shaping
because HarfBuzz needs to retrieve the glyph indices for
particular code points, and to know the extents and advances of
glyphs. Note that, in an OpenType variable font, both of those
types of information can change with different variation-axis
settings.
</para>
<para>
The Unicode information is necessary for shaping because the
properties of a code point (such as its General Category (gc),
Canonical Combining Class (ccc), and decomposition) can directly
impact the shaping moves that HarfBuzz performs.
</para>
<section id="integration-glib">
<title>GNOME integration, GLib, and GObject</title>
<para>
As mentioned in the preceding section, HarfBuzz offers
integration APIs to help client programs using the
GNOME and GTK framework commonly found in desktop Linux
distributions.
</para>
<para>
GLib is the main utility library for GNOME applications. It
provides basic data types and conversions, file abstractions,
string manipulation, and macros, as well as facilities like
memory allocation and the main event loop.
</para>
<para>
Where text shaping is concerned, GLib provides several utilities
that HarfBuzz can take advantage of, including a set of
Unicode-data functions and a data type for script
information. Both are useful when working with HarfBuzz
buffers. To make use of them, you will need to include the
<filename>hb-glib.h</filename> header file.
</para>
<para>
GLib's <ulink
url="https://developer.gnome.org/glib/stable/glib-Unicode-Manipulation.html">Unicode
manipulation API</ulink> includes all the functionality
necessary to retrieve Unicode data for the
<structfield>unicode_funcs</structfield> structure of a HarfBuzz
<type>hb_buffer_t</type>.
</para>
<para>
The function <function>hb_glib_get_unicode_funcs()</function>
sets up a <type>hb_unicode_funcs_t</type> structure configured
with the GLib Unicode functions and returns a pointer to it.
</para>
<para>
You can attach this Unicode-functions structure to your buffer,
and it will be ready for use with GLib:
</para>
<programlisting language="C">
#include &lt;hb-glib.h&gt;
...
hb_unicode_funcs_t *glibufunctions;
glibufunctions = hb_glib_get_unicode_funcs();
hb_buffer_set_unicode_funcs(buf, glibufunctions);
</programlisting>
<para>
For script information, GLib uses the
<type>GUnicodeScript</type> type. Like HarfBuzz's own
<type>hb_script_t</type>, this data type is an enumeration
of Unicode scripts, but text segments passed in from GLib code
will be tagged with a <type>GUnicodeScript</type>. Therefore,
when setting the script property on a <type>hb_buffer_t</type>,
you will need to convert between the <type>GUnicodeScript</type>
of the input provided by GLib and HarfBuzz's
<type>hb_script_t</type> type.
</para>
<para>
The <function>hb_glib_script_to_script()</function> function
takes an <type>GUnicodeScript</type> script identifier as its
sole argument and returns the corresponding <type>hb_script_t</type>.
The <function>hb_glib_script_from_script()</function> does the
reverse, taking an <type>hb_script_t</type> and returning the
<type>GUnicodeScript</type> identifier for GLib.
</para>
<para>
Finally, GLib also provides a reference-counted object type called <ulink
url="https://developer.gnome.org/glib/stable/glib-Byte-Arrays.html#GBytes"><type>GBytes</type></ulink>
that is used for accessing raw memory segments with the benefits
of GLib's lifecycle management. HarfBuzz provides a
<function>hb_glib_blob_create()</function> function that lets
you create an <type>hb_blob_t</type> directly from a
<type>GBytes</type> object. This function takes only the
<type>GBytes</type> object as its input; HarfBuzz registers the
GLib <function>destroy</function> callback automatically.
</para>
<para>
The GNOME platform also features an object system called
GObject. For HarfBuzz, the main advantage of GObject is a
feature called <ulink
url="https://gi.readthedocs.io/en/latest/">GObject
Introspection</ulink>. This is a middleware facility that can be
used to generate language bindings for C libraries. HarfBuzz uses it
to build its Python bindings, which we will look at in a separate section.
</para>
</section>
<section id="integration-freetype">
<title>FreeType integration</title>
<para>
FreeType is the free-software font-rendering engine included in
desktop Linux distributions, Android, ChromeOS, iOS, and multiple Unix
operating systems, and used by cross-platform programs like
Chrome, Java, and GhostScript. Used together, HarfBuzz can
perform shaping on Unicode text segments, outputting the glyph
IDs that FreeType should rasterize from the active font as well
as the positions at which those glyphs should be drawn.
</para>
<para>
HarfBuzz provides integration points with FreeType at the
face-object and font-object level and for the font-functions
virtual-method structure of a font object. To use the
FreeType-integration API, include the
<filename>hb-ft.h</filename> header.
</para>
<para>
In a typical client program, you will create your
<type>hb_face_t</type> face object and <type>hb_font_t</type>
font object from a FreeType <type>FT_Face</type>. HarfBuzz
provides a suite of functions for doing this.
</para>
<para>
In the most common case, you will want to use
<function>hb_ft_font_create_referenced()</function>, which
creates both an <type>hb_face_t</type> face object and
<type>hb_font_t</type> font object (linked to that face object),
and provides lifecycle management.
</para>
<para>
It is important to note,
though, that while HarfBuzz makes a distinction between its face and
font objects, FreeType's <type>FT_Face</type> does not. After
you create your <type>FT_Face</type>, you must set its size
parameter using <function>FT_Set_Char_Size()</function>, because
an <type>hb_font_t</type> is defined as an instance of an
<type>hb_face_t</type> with size specified.
</para>
<programlisting language="C">
#include &lt;hb-ft.h&gt;
...
FT_New_Face(ft_library, font_path, index, &amp;face);
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 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>
After you have created your font object from your
<type>FT_Face</type>, you can set or retrieve the
<structfield>load_flags</structfield> of the
<type>FT_Face</type> through the <type>hb_font_t</type>
object. HarfBuzz provides
<function>hb_ft_font_set_load_flags()</function> and
<function>hb_ft_font_get_load_flags()</function> for this
purpose. The ability to set the
<structfield>load_flags</structfield> through the font object
could be useful for enabling or disabling hinting, for example,
or to activate vertical layout.
</para>
<para>
HarfBuzz also provides a utility function called
<function>hb_ft_font_has_changed()</function> that you should
call whenever you have altered the properties of your underlying
<type>FT_Face</type>, as well as a
<function>hb_ft_get_face()</function> that you can call on an
<type>hb_font_t</type> font object to fetch its underlying <type>FT_Face</type>.
</para>
<para>
With an <type>hb_face_t</type> and <type>hb_font_t</type> both linked
to your <type>FT_Face</type>, you will typically also want to
use FreeType for the <structfield>font_funcs</structfield>
vtable of your <type>hb_font_t</type>. As a reminder, this
font-functions structure is the set of methods that HarfBuzz
will use to fetch important information from the font, such as
the advances and extents of individual glyphs.
</para>
<para>
All you need to do is call
</para>
<programlisting language="C">
hb_ft_font_set_funcs(font);
</programlisting>
<para>
and HarfBuzz will use FreeType for the font-functions in
<literal>font</literal>.
</para>
<para>
As we noted above, an <type>hb_font_t</type> is derived from an
<type>hb_face_t</type> with size (and, perhaps, other
parameters, such as variation-axis coordinates)
specified. Consequently, you can reuse an <type>hb_face_t</type>
with several <type>hb_font_t</type> objects, and HarfBuzz
provides functions to simplify this.
</para>
<para>
The <function>hb_ft_face_create_referenced()</function>
function creates just an <type>hb_face_t</type> from a FreeType
<type>FT_Face</type> and, as with
<function>hb_ft_font_create_referenced()</function> above,
provides lifecycle management for the <type>FT_Face</type>.
</para>
<para>
Similarly, there is an <function>hb_ft_face_create()</function>
function variant that does not provide the lifecycle-management
feature. As with the font-object case, if you use this version
of the function, it will be your client code's respsonsibility
to track usage of the <type>FT_Face</type> objects.
</para>
<para>
A third variant of this function is
<function>hb_ft_face_create_cached()</function>, which is the
same as <function>hb_ft_face_create()</function> except that it
also uses the <structfield>generic</structfield> field of the
<type>FT_Face</type> structure to save a pointer to the newly
created <type>hb_face_t</type>. Subsequently, function calls
that pass the same <type>FT_Face</type> will get the same
<type>hb_face_t</type> returned &mdash; and the
<type>hb_face_t</type> will be correctly reference
counted. Still, as with
<function>hb_ft_face_create()</function>, your client code must
track references to the <type>FT_Face</type> itself, and destroy
it when it is unneeded.
</para>
</section>
<section id="integration-uniscribe">
<title>Uniscribe integration</title>
<para>
If your client program is running on Windows, HarfBuzz offers
an additional API that can help integrate with Microsoft's
Uniscribe engine and the Windows GDI.
</para>
<para>
Overall, the Uniscribe API covers a broader set of typographic
layout functions than HarfBuzz implements, but HarfBuzz's
shaping API can serve as a drop-in replacement for Uniscribe's shaping
functionality. In fact, one of HarfBuzz's design goals is to
accurately reproduce the same output for shaping a given text
segment that Uniscribe produces &mdash; even to the point of
duplicating known shaping bugs or deviations from the
specification &mdash; so you can be confident that your users'
documents with their existing fonts will not be affected adversely by
switching to HarfBuzz.
</para>
<para>
At a basic level, HarfBuzz's <function>hb_shape()</function>
function replaces both the <ulink url=""><function>ScriptShape()</function></ulink>
and <ulink
url="https://docs.microsoft.com/en-us/windows/desktop/api/Usp10/nf-usp10-scriptplace"><function>ScriptPlace()</function></ulink>
functions from Uniscribe.
</para>
<para>
However, whereas <function>ScriptShape()</function> returns the
glyphs and clusters for a shaped sequence and
<function>ScriptPlace()</function> returns the advances and
offsets for those glyphs, <function>hb_shape()</function>
handles both. After <function>hb_shape()</function> shapes a
buffer, the output glyph IDs and cluster IDs are returned as
an array of <structname>hb_glyph_info_t</structname> structures, and the
glyph advances and offsets are returned as an array of
<structname>hb_glyph_position_t</structname> structures.
</para>
<para>
Your client program only needs to ensure that it coverts
correctly between HarfBuzz's low-level data types (such as
<type>hb_position_t</type>) and Windows's corresponding types
(such as <type>GOFFSET</type> and <type>ABC</type>). Be sure you
read the <xref linkend="buffers-language-script-and-direction"
/>
chapter for a full explanation of how HarfBuzz input buffers are
used, and see <xref linkend="shaping-buffer-output" /> for the
details of what <function>hb_shape()</function> returns in the
output buffer when shaping is complete.
</para>
<para>
Although <function>hb_shape()</function> itself is functionally
equivalent to Uniscribe's shaping routines, there are two
additional HarfBuzz functions you may want to use to integrate
the libraries in your code. Both are used to link HarfBuzz font
objects to the equivalent Windows structures.
</para>
<para>
The <function>hb_uniscribe_font_get_logfontw()</function>
function takes a <type>hb_font_t</type> font object and returns
a pointer to the <ulink
url="https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-logfontw"><type>LOGFONTW</type></ulink>
"logical font" that corresponds to it. A <type>LOGFONTW</type>
structure holds font-wide attributes, including metrics, size,
and style information.
</para>
<!--
<para>
In Uniscribe's model, the <type>SCRIPT_CACHE</type> holds the
device context, including the logical font that the shaping
functions apply.
https://docs.microsoft.com/en-us/windows/desktop/Intl/script-cache
</para>
-->
<para>
The <function>hb_uniscribe_font_get_hfont()</function> function
also takes a <type>hb_font_t</type> font object, but it returns
an <type>HFONT</type> &mdash; a handle to the underlying logical
font &mdash; instead.
</para>
<para>
<type>LOGFONTW</type>s and <type>HFONT</type>s are both needed
by other Uniscribe functions.
</para>
<para>
As a final note, you may notice a reference to an optional
<literal>uniscribe</literal> shaper back-end in the <xref
linkend="configuration" /> section of the HarfBuzz manual. This
option is not a Uniscribe-integration facility.
</para>
<para>
Instead, it is a internal code path used in the
<command>hb-shape</command> command-line utility, which hands
shaping functionality over to Uniscribe entirely, when run on a
Windows system. That allows testing HarfBuzz's native output
against the Uniscribe engine, for tracking compatibility and
debugging.
</para>
<para>
Because this back-end is only used when testing HarfBuzz
functionality, it is disabled by default when building the
HarfBuzz binaries.
</para>
</section>
<section id="integration-coretext">
<title>Core Text integration</title>
<para>
If your client program is running on macOS or iOS, HarfBuzz offers
an additional API that can help integrate with Apple's
Core Text engine and the underlying Core Graphics
framework. HarfBuzz does not attempt to offer the same
drop-in-replacement functionality for Core Text that it strives
for with Uniscribe on Windows, but you can still use HarfBuzz
to perform text shaping in native macOS and iOS applications.
</para>
<para>
Note, though, that if your interest is just in using fonts that
contain Apple Advanced Typography (AAT) features, then you do
not need to add Core Text integration. HarfBuzz natively
supports AAT features and will shape AAT fonts (on any platform)
automatically, without requiring additional work on your
part. This includes support for AAT-specific TrueType tables
such as <literal>mort</literal>, <literal>morx</literal>, and
<literal>kerx</literal>, which AAT fonts use instead of
<literal>GSUB</literal> and <literal>GPOS</literal>.
</para>
<para>
On a macOS or iOS system, the primary integration points offered
by HarfBuzz are for face objects and font objects.
</para>
<para>
The Apple APIs offer a pair of data structures that map well to
HarfBuzz's face and font objects. The Core Graphics API, which
is slightly lower-level than Core Text, provides
<ulink url="https://developer.apple.com/documentation/coregraphics/cgfontref"><type>CGFontRef</type></ulink>, which enables access to typeface
properties, but does not include size information. Core Text's
<ulink url="https://developer.apple.com/documentation/coretext/ctfont-q6r"><type>CTFontRef</type></ulink> is analagous to a HarfBuzz font object,
with all of the properties required to render text at a specific
size and configuration.
Consequently, a HarfBuzz <type>hb_font_t</type> font object can
be hooked up to a Core Text <type>CTFontRef</type>, and a HarfBuzz
<type>hb_face_t</type> face object can be hooked up to a
<type>CGFontRef</type>.
</para>
<para>
You can create a <type>hb_face_t</type> from a
<type>CGFontRef</type> by using the
<function>hb_coretext_face_create()</function>. Subsequently,
you can retrieve the <type>CGFontRef</type> from a
<type>hb_face_t</type> with <function>hb_coretext_face_get_cg_font()</function>.
</para>
<para>
Likewise, you create a <type>hb_font_t</type> from a
<type>CTFontRef</type> by calling
<function>hb_coretext_font_create()</function>, and you can
fetch the associated <type>CTFontRef</type> from a
<type>hb_font_t</type> font object with
<function>hb_coretext_face_get_ct_font()</function>.
</para>
<para>
HarfBuzz also offers a <function>hb_font_set_ptem()</function>
that you an use to set the nominal point size on any
<type>hb_font_t</type> font object. Core Text uses this value to
implement optical scaling.
</para>
<para>
When integrating your client code with Core Text, it is
important to recognize that Core Text <literal>points</literal>
are not typographic points (standardized at 72 per inch) as the
term is used elsewhere in OpenType. Instead, Core Text points
are CSS points, which are standardized at 96 per inch.
</para>
<para>
HarfBuzz's font functions take this distinction into account,
but it can be an easy detail to miss in cross-platform
code.
</para>
<para>
As a final note, you may notice a reference to an optional
<literal>coretext</literal> shaper back-end in the <xref
linkend="configuration" /> section of the HarfBuzz manual. This
option is not a Core Text-integration facility.
</para>
<para>
Instead, it is a internal code path used in the
<command>hb-shape</command> command-line utility, which hands
shaping functionality over to Core Text entirely, when run on a
macOS system. That allows testing HarfBuzz's native output
against the Core Text engine, for tracking compatibility and debugging.
</para>
<para>
Because this back-end is only used when testing HarfBuzz
functionality, it is disabled by default when building the
HarfBuzz binaries.
</para>
</section>
<section id="integration-icu">
<title>ICU integration</title>
<para>
Although HarfBuzz includes its own Unicode-data functions, it
also provides integration APIs for using the International
Components for Unicode (ICU) library as a source of Unicode data
on any supported platform.
</para>
<para>
The principal integration point with ICU is the
<type>hb_unicode_funcs_t</type> Unicode-functions structure
attached to a buffer. This structure holds the virtual methods
used for retrieving Unicode character properties, such as
General Category, Script, Combining Class, decomposition
mappings, and mirroring information.
</para>
<para>
To use ICU in your client program, you need to call
<function>hb_icu_get_unicode_funcs()</function>, which creates a
Unicode-functions structure populated with the ICU function for
each included method. Subsequently, you can attach the
Unicode-functions structure to your buffer:
</para>
<programlisting language="C">
hb_unicode_funcs_t *icufunctions;
icufunctions = hb_icu_get_unicode_funcs();
hb_buffer_set_unicode_funcs(buf, icufunctions);
</programlisting>
<para>
and ICU will be used for Unicode-data access.
</para>
<para>
HarfBuzz also supplies a pair of functions
(<function>hb_icu_script_from_script()</function> and
<function>hb_icu_script_to_script()</function>) for converting
between ICU's and HarfBuzz's internal enumerations of Unicode
scripts. The <function>hb_icu_script_from_script()</function>
function converts from a HarfBuzz <type>hb_script_t</type> to an
ICU <type>UScriptCode</type>. The
<function>hb_icu_script_to_script()</function> function does the
reverse: converting from a <type>UScriptCode</type> identifier
to a <type>hb_script_t</type>.
</para>
<para>
By default, HarfBuzz's ICU support is built as a separate shared
library (<filename class="libraryfile">libharfbuzz-icu.so</filename>)
when compiling HarfBuzz from source. This allows client programs
that do not need ICU to link against HarfBuzz without unnecessarily
adding ICU as a dependency. You can also build HarfBuzz with ICU
support built directly into the main HarfBuzz shared library
(<filename class="libraryfile">libharfbuzz.so</filename>),
by specifying the <literal>--with-icu=builtin</literal>
compile-time option.
</para>
</section>
<section id="integration-python">
<title>Python bindings</title>
<para>
As noted in the <xref linkend="integration-glib" /> section,
HarfBuzz uses a feature called <ulink
url="https://wiki.gnome.org/Projects/GObjectIntrospection">GObject
Introspection</ulink> (GI) to provide bindings for Python.
</para>
<para>
At compile time, the GI scanner analyzes the HarfBuzz C source
and builds metadata objects connecting the language bindings to
the C library. Your Python code can then use the HarfBuzz binary
through its Python interface.
</para>
<para>
HarfBuzz's Python bindings support Python 2 and Python 3. To use
them, you will need to have the <literal>pygobject</literal>
package installed. Then you should import
<literal>HarfBuzz</literal> from
<literal>gi.repository</literal>:
</para>
<programlisting language="Python">
from gi.repository import HarfBuzz
</programlisting>
<para>
and you can call HarfBuzz functions from Python. Sample code can
be found in the <filename>sample.py</filename> script in the
HarfBuzz <filename>src</filename> directory.
</para>
<para>
Do note, however, that the Python API is subject to change
without advance notice. GI allows the bindings to be
automatically updated, which is one of its advantages, but you
may need to update your Python code.
</para>
</section>
</chapter>

45
src/hb-coretext.cc
View File

@ -278,13 +278,32 @@ _hb_coretext_shaper_face_data_destroy (hb_coretext_face_data_t *data)
CFRelease ((CGFontRef) data); CFRelease ((CGFontRef) data);
} }
/**
* hb_coretext_face_create:
* @cg_font: The CGFontRef to work upon
*
* Creates an #hb_face_t face object from the specified
* CGFontRef.
*
* Return value: the new #hb_face_t face object
*
* Since: 0.9.10
*/
hb_face_t * hb_face_t *
hb_coretext_face_create (CGFontRef cg_font) hb_coretext_face_create (CGFontRef cg_font)
{ {
return hb_face_create_for_tables (_hb_cg_reference_table, CGFontRetain (cg_font), _hb_cg_font_release); return hb_face_create_for_tables (_hb_cg_reference_table, CGFontRetain (cg_font), _hb_cg_font_release);
} }
/* /**
* hb_coretext_face_get_cg_font:
* @face: The #hb_face_t to work upon
*
* Fetches the CGFontRef associated with an #hb_face_t
* face object
*
* Return value: the CGFontRef found
*
* Since: 0.9.10 * Since: 0.9.10
*/ */
CGFontRef CGFontRef
@ -351,10 +370,17 @@ retry:
return font->data.coretext; return font->data.coretext;
} }
/**
/* * hb_coretext_font_create:
* @ct_font: The CTFontRef to work upon
*
* Creates an #hb_font_t font object from the specified
* CTFontRef.
*
* Return value: the new #hb_font_t font object
*
* Since: 1.7.2 * Since: 1.7.2
*/ **/
hb_font_t * hb_font_t *
hb_coretext_font_create (CTFontRef ct_font) hb_coretext_font_create (CTFontRef ct_font)
{ {
@ -375,6 +401,17 @@ hb_coretext_font_create (CTFontRef ct_font)
return font; return font;
} }
/**
* hb_coretext_face_get_ct_font:
* @font: #hb_font_t to work upon
*
* Fetches the CTFontRef associated with the specified
* #hb_font_t font object.
*
* Return value: the CTFontRef found
*
* Since: 0.9.10
*/
CTFontRef CTFontRef
hb_coretext_font_get_ct_font (hb_font_t *font) hb_coretext_font_get_ct_font (hb_font_t *font)
{ {

32
src/hb-coretext.h
View File

@ -40,8 +40,40 @@
HB_BEGIN_DECLS HB_BEGIN_DECLS
/**
* HB_CORETEXT_TAG_MORT:
*
* The #hb_tag_t tag for the `mort` (glyph metamorphosis) table,
* which holds AAT features.
*
* For more information, see
* https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6mort.html
*
**/
#define HB_CORETEXT_TAG_MORT HB_TAG('m','o','r','t') #define HB_CORETEXT_TAG_MORT HB_TAG('m','o','r','t')
/**
* HB_CORETEXT_TAG_MORX:
*
* The #hb_tag_t tag for the `morx` (extended glyph metamorphosis)
* table, which holds AAT features.
*
* For more information, see
* https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6morx.html
*
**/
#define HB_CORETEXT_TAG_MORX HB_TAG('m','o','r','x') #define HB_CORETEXT_TAG_MORX HB_TAG('m','o','r','x')
/**
* HB_CORETEXT_TAG_KERX:
*
* The #hb_tag_t tag for the `kerx` (extended kerning) table, which
* holds AAT kerning information.
*
* For more information, see
* https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6kerx.html
*
**/
#define HB_CORETEXT_TAG_KERX HB_TAG('k','e','r','x') #define HB_CORETEXT_TAG_KERX HB_TAG('k','e','r','x')

148
src/hb-ft.cc
View File

@ -48,8 +48,13 @@
* @short_description: FreeType integration * @short_description: FreeType integration
* @include: hb-ft.h * @include: hb-ft.h
* *
* Functions for using HarfBuzz with the FreeType library to provide face and * Functions for using HarfBuzz with the FreeType library.
*
* HarfBuzz supports using FreeType to provide face and
* font data. * font data.
*
* <note>Note that FreeType is not thread-safe, therefore these
* functions are not thread-safe either.</note>
**/ **/
@ -127,10 +132,13 @@ _hb_ft_font_destroy (void *data)
/** /**
* hb_ft_font_set_load_flags: * hb_ft_font_set_load_flags:
* @font: * @font: #hb_font_t to work upon
* @load_flags: * @load_flags: The FreeType load flags to set
* *
* Sets the FT_Load_Glyph load flags for the specified #hb_font_t.
* *
* For more information, see
* https://www.freetype.org/freetype2/docs/reference/ft2-base_interface.html#ft_load_xxx
* *
* Since: 1.0.5 * Since: 1.0.5
**/ **/
@ -150,11 +158,15 @@ hb_ft_font_set_load_flags (hb_font_t *font, int load_flags)
/** /**
* hb_ft_font_get_load_flags: * hb_ft_font_get_load_flags:
* @font: * @font: #hb_font_t to work upon
* *
* Fetches the FT_Load_Glyph load flags of the specified #hb_font_t.
* *
* For more information, see
* https://www.freetype.org/freetype2/docs/reference/ft2-base_interface.html#ft_load_xxx
*
* Return value: FT_Load_Glyph flags found
* *
* Return value:
* Since: 1.0.5 * Since: 1.0.5
**/ **/
int int
@ -169,12 +181,14 @@ hb_ft_font_get_load_flags (hb_font_t *font)
} }
/** /**
* hb_ft_font_get_face: * hb_ft_get_face:
* @font: * @font: #hb_font_t to work upon
* *
* Fetches the FT_Face associated with the specified #hb_font_t
* font object.
* *
* Return value: the FT_Face found
* *
* Return value:
* Since: 0.9.2 * Since: 0.9.2
**/ **/
FT_Face FT_Face
@ -645,12 +659,22 @@ _hb_ft_reference_table (hb_face_t *face HB_UNUSED, hb_tag_t tag, void *user_data
/** /**
* hb_ft_face_create: * hb_ft_face_create:
* @ft_face: (destroy destroy) (scope notified): * @ft_face: (destroy destroy) (scope notified): FT_Face to work upon
* @destroy: * @destroy: A callback to call when the face object is not needed anymore
* *
* Creates an #hb_face_t face object from the specified FT_Face.
* *
* This variant of the function does not provide any life-cycle management.
*
* Most client programs should use hb_ft_face_create_referenced()
* (or, perhaps, hb_ft_face_create_cached()) instead.
*
* If you know you have valid reasons not to use hb_ft_face_create_referenced(),
* then it is the client program's responsibility to destroy @ft_face
* after the #hb_face_t face object has been destroyed.
*
* Return value: (transfer full): the new #hb_face_t face object
* *
* Return value: (transfer full):
* Since: 0.9.2 * Since: 0.9.2
**/ **/
hb_face_t * hb_face_t *
@ -680,11 +704,20 @@ hb_ft_face_create (FT_Face ft_face,
/** /**
* hb_ft_face_create_referenced: * hb_ft_face_create_referenced:
* @ft_face: * @ft_face: FT_Face to work upon
* *
* Creates an #hb_face_t face object from the specified FT_Face.
* *
* This is the preferred variant of the hb_ft_face_create*
* function family, because it calls FT_Reference_Face() on @ft_face,
* ensuring that @ft_face remains alive as long as the resulting
* #hb_face_t face object remains alive. Also calls FT_Done_Face()
* when the #hb_face_t face object is destroyed.
*
* Use this version unless you know you have good reasons not to.
*
* Return value: (transfer full): the new #hb_face_t face object
* *
* Return value: (transfer full):
* Since: 0.9.38 * Since: 0.9.38
**/ **/
hb_face_t * hb_face_t *
@ -702,11 +735,21 @@ hb_ft_face_finalize (FT_Face ft_face)
/** /**
* hb_ft_face_create_cached: * hb_ft_face_create_cached:
* @ft_face: * @ft_face: FT_Face to work upon
* *
* Creates an #hb_face_t face object from the specified FT_Face.
* *
* This variant of the function caches the newly created #hb_face_t
* face object, using the @generic pointer of @ft_face. Subsequent function
* calls that are passed the same @ft_face parameter will have the same
* #hb_face_t returned to them, and that #hb_face_t will be correctly
* reference counted.
*
* However, client programs are still responsible for destroying
* @ft_face after the last #hb_face_t face object has been destroyed.
*
* Return value: (transfer full): the new #hb_face_t face object
* *
* Return value: (transfer full):
* Since: 0.9.2 * Since: 0.9.2
**/ **/
hb_face_t * hb_face_t *
@ -724,15 +767,34 @@ hb_ft_face_create_cached (FT_Face ft_face)
return hb_face_reference ((hb_face_t *) ft_face->generic.data); return hb_face_reference ((hb_face_t *) ft_face->generic.data);
} }
/** /**
* hb_ft_font_create: * hb_ft_font_create:
* @ft_face: (destroy destroy) (scope notified): * @ft_face: (destroy destroy) (scope notified): FT_Face to work upon
* @destroy: * @destroy: (optional): A callback to call when the font object is not needed anymore
* *
* Creates an #hb_font_t font object from the specified FT_Face.
* *
* <note>Note: You must set the face size on @ft_face before calling
* hb_ft_font_create() on it. Otherwise, HarfBuzz will not pick up
* the face size.</note>
*
* This variant of the function does not provide any life-cycle management.
*
* Most client programs should use hb_ft_font_create_referenced()
* instead.
*
* If you know you have valid reasons not to use hb_ft_font_create_referenced(),
* then it is the client program's responsibility to destroy @ft_face
* after the #hb_font_t font object has been destroyed.
*
* HarfBuzz will use the @destroy callback on the #hb_font_t font object
* if it is supplied when you use this function. However, even if @destroy
* is provided, it is the client program's responsibility to destroy @ft_face,
* and it is the client program's responsibility to ensure that @ft_face is
* destroyed only after the #hb_font_t font object has been destroyed.
*
* Return value: (transfer full): the new #hb_font_t font object
* *
* Return value: (transfer full):
* Since: 0.9.2 * Since: 0.9.2
**/ **/
hb_font_t * hb_font_t *
@ -750,6 +812,16 @@ hb_ft_font_create (FT_Face ft_face,
return font; return font;
} }
/**
* hb_ft_font_has_changed:
* @font: #hb_font_t to work upon
*
* Refreshes the state of @font when the underlying FT_Face has changed.
* This function should be called after changing the size or
* variation-axis settings on the FT_Face.
*
* Since: 1.0.5
**/
void void
hb_ft_font_changed (hb_font_t *font) hb_ft_font_changed (hb_font_t *font)
{ {
@ -805,11 +877,23 @@ hb_ft_font_changed (hb_font_t *font)
/** /**
* hb_ft_font_create_referenced: * hb_ft_font_create_referenced:
* @ft_face: * @ft_face: FT_Face to work upon
* *
* Creates an #hb_font_t font object from the specified FT_Face.
* *
* <note>Note: You must set the face size on @ft_face before calling
* hb_ft_font_create_references() on it. Otherwise, HarfBuzz will not pick up
* the face size.</note>
*
* This is the preferred variant of the hb_ft_font_create*
* function family, because it calls FT_Reference_Face() on @ft_face,
* ensuring that @ft_face remains alive as long as the resulting
* #hb_font_t font object remains alive.
*
* Use this version unless you know you have good reasons not to.
*
* Return value: (transfer full): the new #hb_font_t font object
* *
* Return value: (transfer full):
* Since: 0.9.38 * Since: 0.9.38
**/ **/
hb_font_t * hb_font_t *
@ -868,6 +952,28 @@ _release_blob (FT_Face ft_face)
hb_blob_destroy ((hb_blob_t *) ft_face->generic.data); hb_blob_destroy ((hb_blob_t *) ft_face->generic.data);
} }
/**
* hb_ft_font_set_funcs:
* @font: #hb_font_t to work upon
*
* Configures the font-functions structure of the specified
* #hb_font_t font object to use FreeType font functions.
*
* In particular, you can use this function to configure an
* existing #hb_face_t face object for use with FreeType font
* functions even if that #hb_face_t face object was initially
* created with hb_face_create(), and therefore was not
* initially configured to use FreeType font functions.
*
* An #hb_face_t face object created with hb_ft_face_create()
* is preconfigured for FreeType font functions and does not
* require this function to be used.
*
* <note>Note: Internally, this function creates an FT_Face.
* </note>
*
* Since: 1.0.5
**/
void void
hb_ft_font_set_funcs (hb_font_t *font) hb_ft_font_set_funcs (hb_font_t *font)
{ {

44
src/hb-glib.cc
View File

@ -41,7 +41,11 @@
* @short_description: GLib integration * @short_description: GLib integration
* @include: hb-glib.h * @include: hb-glib.h
* *
* Functions for using HarfBuzz with the GLib library to provide Unicode data. * Functions for using HarfBuzz with the GLib library.
*
* HarfBuzz supports using GLib to provide Unicode data, by attaching
* GLib functions to the virtual methods in a #hb_unicode_funcs_t function
* structure.
**/ **/
@ -169,6 +173,17 @@ glib_script_to_script[] =
}; };
#endif #endif
/**
* hb_glib_script_to_script:
* @script: The GUnicodeScript identifier to query
*
* Fetches the #hb_script_t script that corresponds to the
* specified GUnicodeScript identifier.
*
* Return value: the #hb_script_t script found
*
* Since: 0.9.38
**/
hb_script_t hb_script_t
hb_glib_script_to_script (GUnicodeScript script) hb_glib_script_to_script (GUnicodeScript script)
{ {
@ -185,6 +200,17 @@ hb_glib_script_to_script (GUnicodeScript script)
#endif #endif
} }
/**
* hb_glib_script_from_script:
* @script: The #hb_script_t to query
*
* Fetches the GUnicodeScript identifier that corresponds to the
* specified #hb_script_t script.
*
* Return value: the GUnicodeScript identifier found
*
* Since: 0.9.38
**/
GUnicodeScript GUnicodeScript
hb_glib_script_from_script (hb_script_t script) hb_glib_script_from_script (hb_script_t script)
{ {
@ -373,6 +399,16 @@ void free_static_glib_funcs ()
} }
#endif #endif
/**
* hb_glib_get_unicode_funcs:
*
* Fetches a Unicode-functions structure that is populated
* with the appropriate GLib function for each method.
*
* Return value: (transfer none): a pointer to the #hb_unicode_funcs_t Unicode-functions structure
*
* Since: 0.9.38
**/
hb_unicode_funcs_t * hb_unicode_funcs_t *
hb_glib_get_unicode_funcs () hb_glib_get_unicode_funcs ()
{ {
@ -391,6 +427,12 @@ _hb_g_bytes_unref (void *data)
/** /**
* hb_glib_blob_create: * hb_glib_blob_create:
* @gbytes: the GBytes structure to work upon
*
* Creates an #hb_blob_t blob from the specified
* GBytes data structure.
*
* Return value: (transfer full): the new #hb_blob_t blob object
* *
* Since: 0.9.38 * Since: 0.9.38
**/ **/

13
src/hb-gobject-structs.cc
View File

@ -32,11 +32,20 @@
/** /**
* SECTION:hb-gobject * SECTION:hb-gobject
* @title: hb-gobject * @title: hb-gobject
* @short_description: GObject integration * @short_description: GObject integration support
* @include: hb-gobject.h * @include: hb-gobject.h
* *
* Functions for using HarfBuzz with the GObject library to provide * Support for using HarfBuzz with the GObject library to provide
* type data. * type data.
*
* The types and functions listed here are solely a linkage between
* HarfBuzz's public data types and the GTypes used by the GObject framework.
* HarfBuzz uses GObject introspection to generate its Python bindings
* (and potentially other language bindings); client programs should never need
* to access the GObject-integration mechanics.
*
* For client programs using the GNOME and GTK software stack, please see the
* GLib and FreeType integration pages.
**/ **/

16
src/hb-graphite2.cc
View File

@ -45,7 +45,11 @@
* @short_description: Graphite2 integration * @short_description: Graphite2 integration
* @include: hb-graphite2.h * @include: hb-graphite2.h
* *
* Functions for using HarfBuzz with the Graphite2 fonts. * Functions for using HarfBuzz with fonts that include Graphite features.
*
* For Graphite features to work, you must be sure that HarfBuzz was compiled
* with the `graphite2` shaping engine enabled. Currently, the default is to
* not enable `graphite2` shaping.
**/ **/
@ -152,7 +156,15 @@ _hb_graphite2_shaper_face_data_destroy (hb_graphite2_face_data_t *data)
free (data); free (data);
} }
/* /**
* hb_graphite2_face_get_gr_face:
* @face: @hb_face_t to query
*
* Fetches the Graphite2 gr_face corresponding to the specified
* #hb_face_t face object.
*
* Return value: the gr_face found
*
* Since: 0.9.10 * Since: 0.9.10
*/ */
gr_face * gr_face *

10
src/hb-graphite2.h
View File

@ -32,7 +32,15 @@
HB_BEGIN_DECLS HB_BEGIN_DECLS
/**
* HB_GRAPHITE2_TAG_SILF:
*
* The #hb_tag_t tag for the `Silf` table, which holds Graphite
* features.
*
* For more information, see http://graphite.sil.org/
*
**/
#define HB_GRAPHITE2_TAG_SILF HB_TAG('S','i','l','f') #define HB_GRAPHITE2_TAG_SILF HB_TAG('S','i','l','f')

36
src/hb-icu.cc
View File

@ -54,7 +54,21 @@
* @short_description: ICU integration * @short_description: ICU integration
* @include: hb-icu.h * @include: hb-icu.h
* *
* Functions for using HarfBuzz with the ICU library to provide Unicode data. * Functions for using HarfBuzz with the International Components for Unicode
* (ICU) library. HarfBuzz supports using ICU to provide Unicode data, by attaching
* ICU functions to the virtual methods in a #hb_unicode_funcs_t function
* structure.
**/
/**
* hb_icu_script_to_script:
* @script: The UScriptCode identifier to query
*
* Fetches the #hb_script_t script that corresponds to the
* specified UScriptCode identifier.
*
* Return value: the #hb_script_t script found
*
**/ **/
hb_script_t hb_script_t
@ -66,6 +80,16 @@ hb_icu_script_to_script (UScriptCode script)
return hb_script_from_string (uscript_getShortName (script), -1); return hb_script_from_string (uscript_getShortName (script), -1);
} }
/**
* hb_icu_script_from_script:
* @script: The #hb_script_t script to query
*
* Fetches the UScriptCode identifier that corresponds to the
* specified #hb_script_t script.
*
* Return value: the UScriptCode identifier found
*
**/
UScriptCode UScriptCode
hb_icu_script_from_script (hb_script_t script) hb_icu_script_from_script (hb_script_t script)
{ {
@ -350,6 +374,16 @@ void free_static_icu_funcs ()
} }
#endif #endif
/**
* hb_icu_get_unicode_funcs:
*
* Fetches a Unicode-functions structure that is populated
* with the appropriate ICU function for each method.
*
* Return value: (transfer none): a pointer to the #hb_unicode_funcs_t Unicode-functions structure
*
* Since: 0.9.38
**/
hb_unicode_funcs_t * hb_unicode_funcs_t *
hb_icu_get_unicode_funcs () hb_icu_get_unicode_funcs ()
{ {

22
src/hb-uniscribe.cc
View File

@ -55,7 +55,7 @@
* @short_description: Windows integration * @short_description: Windows integration
* @include: hb-uniscribe.h * @include: hb-uniscribe.h
* *
* Functions for using HarfBuzz with the Windows fonts. * Functions for using HarfBuzz with Windows fonts.
**/ **/
typedef HRESULT (WINAPI *SIOT) /*ScriptItemizeOpenType*/( typedef HRESULT (WINAPI *SIOT) /*ScriptItemizeOpenType*/(
@ -583,6 +583,16 @@ _hb_uniscribe_shaper_font_data_destroy (hb_uniscribe_font_data_t *data)
free (data); free (data);
} }
/**
* hb_uniscribe_font_get_logfontw:
* @font: The #hb_font_t to work upon
*
* Fetches the LOGFONTW structure that corresponds to the
* specified #hb_font_t font.
*
* Return value: a pointer to the LOGFONTW retrieved
*
**/
LOGFONTW * LOGFONTW *
hb_uniscribe_font_get_logfontw (hb_font_t *font) hb_uniscribe_font_get_logfontw (hb_font_t *font)
{ {
@ -590,6 +600,16 @@ hb_uniscribe_font_get_logfontw (hb_font_t *font)
return data ? &data->log_font : nullptr; return data ? &data->log_font : nullptr;
} }
/**
* hb_uniscribe_font_get_hfont:
* @font: The #hb_font_t to work upon
*
* Fetches the HFONT handle that corresponds to the
* specified #hb_font_t font.
*
* Return value: the HFONT retreieved
*
**/
HFONT HFONT
hb_uniscribe_font_get_hfont (hb_font_t *font) hb_uniscribe_font_get_hfont (hb_font_t *font)
{ {