Files
harfbuzz/docs/libharfbuzz-vector.md
T

173 lines
6.4 KiB
Markdown

# 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` (especially `util/draw-output.hh` and `util/draw-output-color.hh`), moving implementation into `src/`.
- Keep API shape similar to `libharfbuzz-raster` object 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.cc` for outline draw callbacks
- `src/hb-vector-paint.cc` for 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`: consume `hb_draw_funcs_t` callbacks, render vector output.
- `hb_vector_paint_t`: consume `hb_paint_funcs_t` callbacks, render vector output.
Both follow HB object conventions:
- `create_or_fail`, `reference`, `destroy`
- `set_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()` returns `NULL`.
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)
```c
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-draw` will be renamed to `hb-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()` returns `NULL`.
- Output is owned as `hb_blob_t*`.
- Generic API remains backend-neutral; format-specific options stay format-specific.