mirror of
https://github.com/storytold/harfbuzz.git
synced 2026-11-20 22:41:10 +01:00
6.4 KiB
6.4 KiB
libharfbuzz-vector Design and API
Goals
- Add a new optional library:
libharfbuzz-vector. - Start with SVG generation.
- Reuse the existing conversion logic currently in
util/hb-draw(especiallyutil/draw-output.hhandutil/draw-output-color.hh), moving implementation intosrc/. - Keep API shape similar to
libharfbuzz-rasterobject lifecycle and callback flow.
Non-goals (initial version)
- No text layout API in this library.
- No logical/ink bbox policy in the library API.
- No PDF backend yet (but API should allow adding one later).
High-level architecture
- Public API is format-agnostic:
hb_vector_*. - Backends are internal and format-specific (SVG now, PDF later).
- Dispatch is internal via function tables, not C++ virtual methods.
This follows HarfBuzz style and keeps ABI explicit and stable.
Naming and layering
- Library name:
harfbuzz-vector - Public header:
src/hb-vector.h - Core dispatch/docs:
src/hb-vector.cc - SVG backend:
src/hb-vector-svg.cc - Optional split:
src/hb-vector-draw.ccfor outline draw callbackssrc/hb-vector-paint.ccfor COLR paint callbacks
Note: this coexists with internal template container header src/hb-vector.hh.
Core API model
Two opaque context objects:
hb_vector_draw_t: consumehb_draw_funcs_tcallbacks, render vector output.hb_vector_paint_t: consumehb_paint_funcs_tcallbacks, render vector output.
Both follow HB object conventions:
create_or_fail,reference,destroyset_user_data,get_user_data- mutable configuration via setters
render,reset
Extents policy
Extents are required before render().
- Caller sets extents explicitly with
set_extents(...). set_glyph_extents(...)is a convenience helper for single-glyph cases and sets extents based on current transform/scale.- If extents are not set,
render()returnsNULL.
The library does not decide logical-vs-ink bounds.
Output format policy
Public API includes a format enum for backend selection:
HB_VECTOR_FORMAT_SVG(initial and default)- Future:
HB_VECTOR_FORMAT_PDF, etc.
Public API stays generic; backend-specific options are exposed as extension setters.
Backend-specific options
Do not put SVG-only options in generic setters.
SVG-specific API:
hb_vector_svg_set_flat(...)hb_vector_svg_set_precision(...)
Future PDF-specific options should be hb_vector_pdf_set_*.
Draft API surface (proposed)
typedef enum {
HB_VECTOR_FORMAT_SVG = 0,
} hb_vector_format_t;
typedef struct hb_vector_extents_t {
float x, y, width, height;
} hb_vector_extents_t;
typedef struct hb_vector_draw_t hb_vector_draw_t;
typedef struct hb_vector_paint_t hb_vector_paint_t;
/* draw */
hb_vector_draw_t *hb_vector_draw_create_or_fail (void);
hb_vector_draw_t *hb_vector_draw_reference (hb_vector_draw_t *draw);
void hb_vector_draw_destroy (hb_vector_draw_t *draw);
hb_bool_t hb_vector_draw_set_user_data (hb_vector_draw_t*, hb_user_data_key_t*, void*, hb_destroy_func_t, hb_bool_t);
void *hb_vector_draw_get_user_data (hb_vector_draw_t*, hb_user_data_key_t*);
void hb_vector_draw_set_format (hb_vector_draw_t*, hb_vector_format_t format);
void hb_vector_draw_set_transform (hb_vector_draw_t*, float xx, float yx, float xy, float yy, float dx, float dy);
void hb_vector_draw_set_scale_factor (hb_vector_draw_t*, float x_scale_factor, float y_scale_factor);
void hb_vector_draw_set_extents (hb_vector_draw_t*, const hb_vector_extents_t *extents);
hb_bool_t hb_vector_draw_set_glyph_extents (hb_vector_draw_t*, const hb_glyph_extents_t *glyph_extents);
hb_draw_funcs_t *hb_vector_draw_get_funcs (void);
hb_blob_t *hb_vector_draw_render (hb_vector_draw_t *draw);
void hb_vector_draw_reset (hb_vector_draw_t *draw);
/* paint */
hb_vector_paint_t *hb_vector_paint_create_or_fail (void);
hb_vector_paint_t *hb_vector_paint_reference (hb_vector_paint_t *paint);
void hb_vector_paint_destroy (hb_vector_paint_t *paint);
hb_bool_t hb_vector_paint_set_user_data (hb_vector_paint_t*, hb_user_data_key_t*, void*, hb_destroy_func_t, hb_bool_t);
void *hb_vector_paint_get_user_data (hb_vector_paint_t*, hb_user_data_key_t*);
void hb_vector_paint_set_format (hb_vector_paint_t*, hb_vector_format_t format);
void hb_vector_paint_set_transform (hb_vector_paint_t*, float xx, float yx, float xy, float yy, float dx, float dy);
void hb_vector_paint_set_scale_factor (hb_vector_paint_t*, float x_scale_factor, float y_scale_factor);
void hb_vector_paint_set_extents (hb_vector_paint_t*, const hb_vector_extents_t *extents);
hb_bool_t hb_vector_paint_set_glyph_extents (hb_vector_paint_t*, const hb_glyph_extents_t *glyph_extents);
void hb_vector_paint_set_foreground (hb_vector_paint_t*, hb_color_t foreground);
void hb_vector_paint_set_palette (hb_vector_paint_t*, int palette);
hb_paint_funcs_t *hb_vector_paint_get_funcs (void);
hb_blob_t *hb_vector_paint_render (hb_vector_paint_t *paint);
void hb_vector_paint_reset (hb_vector_paint_t *paint);
/* SVG-specific options */
void hb_vector_svg_set_flat (hb_vector_draw_t *draw, hb_bool_t flat);
void hb_vector_svg_set_precision (hb_vector_draw_t *draw, unsigned precision);
void hb_vector_svg_paint_set_flat (hb_vector_paint_t *paint, hb_bool_t flat);
void hb_vector_svg_paint_set_precision (hb_vector_paint_t *paint, unsigned precision);
CLI migration
util/hb-drawwill be renamed tohb-vector.- Default output format is SVG.
- CLI retains layout-oriented policies (line placement, bbox mode decisions, etc.).
- Library API remains low-level conversion-only.
Build integration plan
Meson:
- Add
hb_vector_sources,hb_vector_headers. - Build/install
libharfbuzz-vector. - Generate
harfbuzz-vector.def. - Generate
harfbuzz-vector.pc. - Add dependency override:
meson.override_dependency('harfbuzz-vector', ...).
CMake:
- Not currently wiring
harfbuzz-raster; vector integration may start in Meson first. - If desired, add CMake target in a follow-up for parity.
Expected implementation extraction
From utility code to src/:
- Path building / numeric formatting
- Reuse-vs-flat SVG emission
- Paint graph to SVG conversion:
- clip, transform, group/composite
- color/image paint
- linear/radial/sweep gradients
Behavioral contract summary
- API is explicit and deterministic.
- Caller controls extents.
- Missing extents =>
render()returnsNULL. - Output is owned as
hb_blob_t*. - Generic API remains backend-neutral; format-specific options stay format-specific.