harfbuzz-world.cc

Add HarfBuzz to your project as a submodule or vendor a checkout alongside your code. Compile src/harfbuzz-world.cc, the amalgamation that includes the library's source files in a single C++ translation unit:

c++ -std=c++11 -O2 \
    -c third_party/harfbuzz/src/harfbuzz-world.cc \
    -o harfbuzz-world.o

Link harfbuzz-world.o with the rest of your program and call the public C API as usual:

#include <hb.h>
#include <hb-ot.h>

hb_blob_t  *blob = hb_blob_create_from_file ("MyFont.ttf");
hb_face_t  *face = hb_face_create (blob, 0);
hb_font_t  *font = hb_font_create (face);
hb_buffer_t *buf = hb_buffer_create ();

hb_buffer_add_utf8 (buf, "Hello", -1, 0, -1);
hb_buffer_guess_segment_properties (buf);  /* toy: real apps set script/lang/dir explicitly */
hb_shape (font, buf, NULL, 0);

unsigned len;
hb_glyph_info_t      *info = hb_buffer_get_glyph_infos     (buf, &len);
hb_glyph_position_t  *pos  = hb_buffer_get_glyph_positions (buf, NULL);
/* …draw the glyphs… */

Customizing the build

Configure the amalgamation with compile-time #defines. Pass them on the command line (-DHB_TINY) or via a small wrapper header that #defines them and then #includes harfbuzz-world.cc.

• HB_TINY — enable a compact build by disabling optional features, including deprecated APIs, variable fonts, AAT, legacy fallbacks, hinting, glyph names, math, name-table access, and metrics. It also selects compiler optimizations for size. All script shapers remain available. Use the HB_HAS_* flags below to include the subsystems you need.
• HB_HAS_SUBSET — include hb-subset for font subsetting.
• HB_HAS_RASTER — include hb-raster for software rendering.
• HB_HAS_VECTOR — include hb-vector for SVG and PDF output.
• HB_HAS_GPU — include hb-gpu for GPU rendering with the Slug algorithm.
• HB_HAS_FREETYPE, HB_HAS_GLIB, HB_HAS_ICU, HB_HAS_GRAPHITE, HB_HAS_CAIRO, and others — enable the corresponding library integrations.

To restore a feature disabled by HB_TINY, undefine its HB_NO_* flag in your override header. For example, undefine HB_NO_AAT to enable shaping with Apple Advanced Typography tables such as morx, kerx, and trak, used by some Mac system fonts.

Building for the web (Emscripten)

The amalgamation also compiles to WebAssembly with em++. This site enables shaping, subsetting, raster rendering, vector output, and AAT support. The GPU tab embeds a separate hb-gpu demo.

em++ -std=c++11 -Oz -flto \
     -I third_party/harfbuzz/src \
     -DHB_TINY -DHB_HAS_SUBSET -DHB_HAS_RASTER \
     -DHB_HAS_VECTOR -DHB_HAS_GPU \
     bindings.cc third_party/harfbuzz/src/harfbuzz-world.cc \
     -sMODULARIZE=1 -sALLOW_MEMORY_GROWTH=1 \
     -sEXPORTED_FUNCTIONS='["_my_shape_export","_malloc","_free"]' \
     -o myhb.js

See this site's scripts/build.sh and src/bindings.cc for a complete working example.

• github.com/harfbuzz/harfbuzz — source, issues, releases.
• harfbuzz.github.io — user manual and API reference.
• BUILD.md — build and packaging instructions, including Meson.
• CONFIG.md — an overview of compile-time configuration. See src/hb-config.hh (HB_NO_* feature gates and the HB_TINY / HB_LEAN / HB_MINI presets) and src/hb-features.h.in (the HB_HAS_* subsystem flags).
• github.com/harfbuzz/harfbuzz-world.cc — source for this site.

Other languages

HarfBuzz is also available through these bindings and ports:

• uharfbuzz — Python bindings, used by FontTools.
• harfbuzzjs — JavaScript and WebAssembly bindings for browsers and Node.js.
• harfrust — a Rust port with no C dependency.

Text shaping turns a Unicode string and a font into positioned glyphs. HarfBuzz handles complex scripts such as Arabic, Indic scripts, and Khmer, along with OpenType features, variable fonts including avar2, and Apple Advanced Typography (AAT).

📖 User manual and API reference

Font subsetting removes unused glyphs and font data while preserving the layout rules needed for shaping. Common uses include smaller web fonts and subsets for document embedding. The subsetter can also produce static instances of variable fonts, limit or reshape the variation space, and change default axis values.

📖 API reference

The software rasterizer supports COLRv1 gradients, compositing, and transforms, as well as embedded PNG glyph images. Monochrome outlines produce A8 coverage masks; color glyphs produce premultiplied BGRA32 pixels. It renders without hinting and is designed for high-DPI displays and embedded use.

📖 API reference

hb-vector produces SVG and PDF output from glyph outlines and COLRv1 color paint data. SVG is useful for previews, web graphics, and debugging. PDF output can embed color glyphs as Type 3 fonts, preserving scalable outlines in document applications such as LibreOffice.

📖 API reference

hb-gpu targets games, UI frameworks, and other real-time applications. It renders glyph outlines and COLRv1 color paint data in fragment shaders. The client manages an atlas of encoded glyph data, while the GPU rasterizes glyphs at the requested scale. Shader sources are available in GLSL, WGSL, MSL, and HLSL.

📖 API reference