mirror of
https://github.com/harfbuzz/harfbuzz.git
synced 2025-04-04 21:15:06 +00:00
04b2006fc9
As extensively discussed and documented in #1484, Core Text does
not operate in 96 DPI. Core Text doesn't actually have a concept of
DPI internally, as it doesn't rasterize anything by itself, it just
generates vector paths that get passed along to Core Graphics.
In practice this means Core Text operates in the classical macOS
logical DPI of 72, with one typographic point corresponding to one
point in the Core Graphics coordinate system, which for a normal
bitmap context then corresponds to one pixel -- or two pixels for
a "retina" context with a 2x scale transform.
As of f401f85a5a, we no longer apply
any assumptions in HB about the target DPI being different than the
72 DPI used by CT, for example to account for the Web's standard of
96 DPI, so let's remove the documentation that still indicated this
was necessary.
635 lines
29 KiB
XML
635 lines
29 KiB
XML
<?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
|
|
— 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 <hb-glib.h>
|
|
...
|
|
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. These functions
|
|
make it easy for clients that use FreeType for rasterization
|
|
or font-loading, to use HarfBuzz for shaping. 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 <hb-ft.h>
|
|
...
|
|
FT_New_Face(ft_library, font_path, index, &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_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 — 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-cairo">
|
|
<title>Cairo integration</title>
|
|
|
|
<para>
|
|
Cairo is a 2D graphics library that is frequently used together
|
|
with GTK and Pango. Cairo supports rendering text using FreeType, or
|
|
by using callback-based 'user fonts'.
|
|
</para>
|
|
<para>
|
|
HarfBuzz provides integration points with cairo for fonts as well as
|
|
for buffers. To use the Cairo-integration API, link against libharfbuzz-cairo,
|
|
and include the <filename>hb-cairo.h</filename> header. For easy buildsystem
|
|
integration, HarfBuzz comes with a <filename>harfbuzz-cairo.pc</filename>
|
|
pkg-config file.
|
|
</para>
|
|
<para>
|
|
To create a <type>cairo_scaled_font_t</type> font from a HarfBuzz
|
|
<type>hb_font_t</type>, you can use <function>hb_cairo_font_face_create_for_font()</function>
|
|
or <function>hb_cairo_font_face_create_for_face()</function>. The former API
|
|
applies variations and synthetic slant from the <type>hb_font_t</type> when
|
|
rendering, the latter takes them from the <type>cairo_font_options_t</type>
|
|
that were passed when creating the <type>cairo_scaled_font_t</type>.
|
|
</para>
|
|
<para>
|
|
The Cairo fonts created in this way make use of Cairo's user-font facilities.
|
|
They can be used to render on any Cairo context, and provide full support for
|
|
font rendering features, including color. One current limitation of the
|
|
implementation is that it does not support hinting for glyph outlines.
|
|
</para>
|
|
<para>
|
|
When using color fonts with this API, the color palette index is taken from
|
|
the <type>cairo_font_options_t</type> (with new enough Cairo), and the foreground
|
|
color is extracted from the source of the Cairo context.
|
|
</para>
|
|
<para>
|
|
To render the results of shaping a piece of text, use
|
|
<function>hb_cairo_glyphs_from_buffer()</function> to obtain the glyphs in
|
|
a form that can be passed to <function>cairo_show_text_glyphs()</function> or
|
|
<function>cairo_show_glyphs()</function>.
|
|
</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 — even to the point of
|
|
duplicating known shaping bugs or deviations from the
|
|
specification — 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 converts
|
|
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> — a handle to the underlying logical
|
|
font — 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 analogous 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>
|
|
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>
|