Skip to content

Home

Jump to bottom
Behdad Esfahbod edited this page Aug 7, 2022 · 78 revisions

HarfBuzz, the text shaping library

HarfBuzz

HarfBuzz is a text shaping engine. It primarily supports OpenType, but also Apple Advanced Typography.

The current HarfBuzz tree, used to be also known as harfbuzz-ng, is under active development and is what is directly used in Firefox, Chrome, LibreOffice, XeTeX, Minikin/Android/Flutter, PlayStation, Qt/KDE, GTK+/Gnome, Java, Emacs and Unreal Engine among many other places directly or indirectly.

The old HarfBuzz tree, derived from FreeType, Pango, and Qt is not actively developed or maintained, and is buggy. All users are encouraged to switch over to the new HarfBuzz. There are no release tarballs of old HarfBuzz whatsoever.

For tarball releases of HarfBuzz, look here. At the same place you will also find Win32 binary bundles that include libharfbuzz DLL, hb-shape.exe, and all dependencies.

If you are not sure whether Pango or HarfBuzz is right for you, read this.

API/ABI guarantee

The API that comes with hb.h will not change incompatibly. Other, peripheral, headers are more likely to go through minor modifications, but again, we do our best to never change API in an incompatible way. We will never break the ABI.

Building

See the build instructions.

Community and Development

Development

To get a better idea of where HarfBuzz stands in the text rendering stack you may want to read State of Text Rendering, though, that document is many years old. Here are a few presentation slides about HarfBuzz at the Internationalization and Unicode Conference over the years:

Both development and user support discussion around HarfBuzz happens on the issue tracker. Some old discussions can be found on the harfbuzz at lists freedesktop org mailing list. Some of the developers frequent the #harfbuzz channel on freenode IRC server. If you write to the mailing list, you should get an answer, though the issue tracker is preferable. The same is not necessarily true about the IRC channel, or if you write to individual developers. Feel free to write to the list to tell us how you are using HarfBuzz, or how well it has been suiting your project's needs.

To report bugs or submit patches please use github issues and pull-requests.

For a comparison of old vs new HarfBuzz memory consumption see this.

You can monitor various aspects of the project using the following online services:

  • The code is replicated on GitHub; pull requests are responded to,
  • With each commit, all tests are run on Travis CI,
  • Public API / ABI changes are tracked across releases on ABI Tracker,
  • Extensive testing dashboard run by Jonathan Kew here,

History

HarfBuzz (حرف‌باز) is my (Behdad Esfahbod) Persian translation of "OpenType", transliterated using the Latin script. It sports a second meaning, but that ain't translatable.

Background: Originally there was this font format called TrueType. People and companies started calling their type engines all things ending in Type: FreeType, CoolType, ClearType, etc. And then came OpenType, which is the successor of TrueType. So, for my OpenType implementation, I decided to stick with the concept but use the Persian translation. Which is fitting given that Persian is written in the Arabic script, and OpenType is an extension of TrueType that adds support for complex script rendering, and HarfBuzz is an implementation of OpenType complex text shaping.

More on the Wikipedia entry for HarfBuzz

Hackfests

Major HarfBuzz development, specially the South / South-East Asian shaper, has happened in HarfBuzz Hackfests, intense week-long pair-programming hackathons between Behdad Esfahbod and Jonathan Kew. We have found that these intense hacking events are a very productive way to develop HarfBuzz, and as such looking to continue them. Here's a timeline:

  • May 2016, Mozilla London. Updated to Unicode 9.0, update Universal Shaping Engine to latest draft spec from Microsoft, and fixed various bugs,
  • December 2015, Mozilla London. Updated Indic shaper to Unicode 8.0 and fixed various bugs,
  • July 2015, Mozilla London. Implemented Win10-style Universal Shaping Engine and various fixes and improvements,
  • Udupi HarfBuzz Hackfest October 2013, Mozilla Paris / Google Paris. Implemented Win8.1-style Javanese / Buginese shaping, and fixed various bugs,
  • Ngapi HarfBuzz Hackfest February 2013, Google London / Mozilla London. Implemented Win8-style Myanmar shaping, and Tai Tham, Cham, and New Tai Lue shaping, and fixed various bugs. Read full report,
  • HarfBuzz "All-You-Can-Eat-Sushi" Hackfest November 2012, Mozilla Vancouver. Mostly fixed shaping with tricky / old / broken fonts for Sinhala, Khmer, and Thai, and started introspection APIs,
  • Lemongrass HarfBuzz Hackfest July 2012, Mozilla Toronto. Further streamlines support for main Indic scripts and moved east-ward, adding support for Khmer. Read full report,
  • HarfBuzz Massala Hackfest May 2012, Google Zurich. Serious work on the Indic shaper was started and a major milestone reached by the end of the week. Read full report,
  • May 2010, Reading, UK,
  • October 2009, Mozilla Toronto. Read full report, Before these hackfests, there were other gatherings under the umbrella of TextLayout summits.

ICU LayoutEngine

If your application uses ICU LayoutEngine library, there is a replacement library called icu-le-hb here that uses HarfBuzz to provide the ICU LayoutEngine API. The C++ API is not ABI compatible, but the C API is. This library has not been tested seriously. If you use it, please report your experience to the mailing list.

If you use ICU ParagraphLayout (aka layoutex, aka libiculx), you need to build that against icu-le-hb. See here for instructions.

State of Text Rendering

To get a better idea of where HarfBuzz stands in the text rendering stack read Behdad Esfahbod's State of Text Rendering.

User Examples

  • Akita Noek's example code which uses SDL, cairo, freetype, and harfbuzz to do ttf/otf text layout and rendering.

  • Alexander Sabourenkov's fork of Akita Noek's example. This version does not use Cairo, glib or ICU. It demonstrates anti-aliased font rasterization rendering directly into 32bpp memory without intermediate FT_Bitmaps.

  • Look in the HarfBuzz util directory for the source code of the hb-shape, and hb-view utilities.

  • harfbuzz-tutorial, along with the walk-though accompanying that.

  • harfbuzz-example, using Freetype, OpenGL and GLFW.

  • [harfbuzz.js demo](harfbuzz.github.io/harfbuzzjs/], how to use harfbuzz.js

  • crowbar, how harfbuzz shapes step by step, source

  • Rana Kufi

User Reference

Internals Guide

Internals Reference

Glossary

  • SFNT is a font file format used for PostScript, TrueType and OpenType fonts.
  • Uniscribe is the Microsoft Windows implementation of complex text layout.

Documentation To Do List

Clone this wiki locally