Core Text integration: HarfBuzz Manual

## Core Text integration

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.

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 `mort`, `morx`, and `kerx`, which AAT fonts use instead of `GSUB` and `GPOS`.

On a macOS or iOS system, the primary integration points offered by HarfBuzz are for face objects and font objects.

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 CGFontRef, which enables access to typeface properties, but does not include size information. Core Text's CTFontRef 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 hb_font_t font object can be hooked up to a Core Text CTFontRef, and a HarfBuzz hb_face_t face object can be hooked up to a CGFontRef.

You can create a hb_face_t from a CGFontRef by using the `hb_coretext_face_create()`. Subsequently, you can retrieve the CGFontRef from a hb_face_t with `hb_coretext_face_get_cg_font()`.

Likewise, you create a hb_font_t from a CTFontRef by calling `hb_coretext_font_create()`, and you can fetch the associated CTFontRef from a hb_font_t font object with `hb_coretext_face_get_ct_font()`.

HarfBuzz also offers a `hb_font_set_ptem()` that you an use to set the nominal point size on any hb_font_t font object. Core Text uses this value to implement optical scaling.

When integrating your client code with Core Text, it is important to recognize that Core Text `points` 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.

HarfBuzz's font functions take this distinction into account, but it can be an easy detail to miss in cross-platform code.

As a final note, you may notice a reference to an optional `coretext` shaper back-end in the the section called “Configuration options” section of the HarfBuzz manual. This option is not a Core Text-integration facility.

Instead, it is a internal code path used in the hb-shape 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.

Because this back-end is only used when testing HarfBuzz functionality, it is disabled by default when building the HarfBuzz binaries.