[Docs] Usermanual: integration chapter; add CoreText/Mac section.
This commit is contained in:
Nathan Willis
parent
dd1c7656a5
commit
c0bb66ecbf
|
|
@ -303,13 +303,14 @@
|
|||
<section id="integration-uniscribe">
|
||||
<title>Uniscribe integration</title>
|
||||
<para>
|
||||
If your client program is running on Windows, HarfBuzz can
|
||||
integrate with the Uniscribe engine.
|
||||
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 the shaping
|
||||
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
|
||||
|
|
@ -321,8 +322,9 @@
|
|||
<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.
|
||||
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
|
||||
|
|
@ -363,10 +365,14 @@
|
|||
structure holds font-wide attributes, including metrics, size,
|
||||
and style information.
|
||||
</para>
|
||||
|
||||
SCRIPT_CACHE holds context, including LOGFONT https://docs.microsoft.com/en-us/windows/desktop/Intl/script-cache
|
||||
https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-logfontw
|
||||
|
||||
<!--
|
||||
<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
|
||||
|
|
@ -401,28 +407,93 @@ SCRIPT_CACHE holds context, including LOGFONT https://docs.microsoft.com/en
|
|||
<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 user 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 CoreText-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 CoreText entirely, when run on a
|
||||
macOS system. That allows testing HarfBuzz's native output
|
||||
against the CoreText 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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue