What is HarfBuzz?

HarfBuzz is the industry-standard text shaping engine. It takes a sequence of Unicode codepoints and a font, and produces a sequence of glyph IDs with precise placement offsets ready for a renderer such as FreeType or Cairo. Without shaping, rendered text would be broken for any script beyond basic ASCII.

HarfBuzz handles the full complexity of international typography: ligatures (fi fl ff ffi ffl collapse to single glyphs), kerning (adjust spacing between specific pairs like AV), Arabic and Hebrew right-to-left and contextual letter forms, Devanagari conjunct consonants and vowel mark attachment, CJK ideographic spacing and vertical text modes, bidirectional (BiDi) mixed LTR+RTL paragraphs, mark placement (diacritics, combining characters), and the full OpenType GSUB/GPOS glyph substitution and positioning pipeline.

HarfBuzz is used inside Chrome, Firefox, Android, iOS (CoreText), LibreOffice, Pango, Qt, GNOME, WebKit, and Inkscape — essentially every modern application that renders text on Linux, Android, or the web.

Why Shaping Matters

Typical Pipeline

Types

API Reference

Face & Font

Buffer

Shaping

Convenience

OpenType Features

Info

Shape English Text

uses harfbuzz;

var
  Face  : THBFace;
  Font  : THBFont;
  Buf   : THBBuffer;
  Res   : THBShapeResult;
  I     : Integer;
begin
  Face := NewFaceFromFile('/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', 0);
  Font := NewFont(Face);
  SetFontScale(Font, 32 * 64, 32 * 64);  { 32 px in 26.6 fixed-point format }

  Buf := NewBuffer;
  AddText(Buf, 'Hello, world!');
  GuessProperties(Buf);  { auto-detect: LTR + Latin }
  Shape(Font, Buf);

  Res := GetShapeResult(Buf);
  for I := 0 to Res.GlyphCount - 1 do
    WriteLn('Glyph ', Res.Glyphs[I].GlyphIndex,
            ' advance ', Res.Positions[I].XAdvance);

  FreeBuffer(Buf);
  FreeFont(Font);
  FreeFace(Face);
end.

Disable Ligatures with OpenType Features

By default HarfBuzz applies all active features in the font, including liga (standard ligatures) and kern. Use ShapeEx to override specific features:

uses harfbuzz;

var
  Face    : THBFace;
  Font    : THBFont;
  Buf     : THBBuffer;
  Res     : THBShapeResult;
  NoLiga  : THBFeature;
begin
  Face := NewFaceFromFile('/usr/share/fonts/opentype/eb-garamond/EBGaramond-Regular.otf', 0);
  Font := NewFont(Face);
  SetFontScale(Font, 18 * 64, 18 * 64);

  Buf := NewBuffer;
  AddText(Buf, 'difficult office affairs');
  GuessProperties(Buf);

  { Disable standard ligatures: 'fi', 'fl', 'ff' will remain separate glyphs }
  NoLiga := ParseFeature('liga=0');
  ShapeEx(Font, Buf, [NoLiga]);

  Res := GetShapeResult(Buf);
  WriteLn('Glyph count: ', Res.GlyphCount);

  FreeBuffer(Buf);
  FreeFont(Font);
  FreeFace(Face);
end.

One-shot Convenience

For simple cases where you only need to shape once and do not want to manage a buffer manually, use ShapeText:

uses harfbuzz;

var
  Face : THBFace;
  Font : THBFont;
  Res  : THBShapeResult;
  I    : Integer;
begin
  Face := NewFaceFromFile('/usr/share/fonts/truetype/noto/NotoSansArabic-Regular.ttf', 0);
  Font := NewFont(Face);
  SetFontScale(Font, 24 * 64, 24 * 64);

  { Shape Arabic text right-to-left }
  Res := ShapeText(Font, 'مرحبا بالعالم', hdRTL, hsArabic, 'ar');

  for I := 0 to Res.GlyphCount - 1 do
    WriteLn(Res.Glyphs[I].GlyphIndex, ' @cluster ', Res.Glyphs[I].Cluster);

  FreeFont(Font);
  FreeFace(Face);
end.