C functions

daegun_status daegun_bidi_runs_at(
    const daegun_bidi_runs *runs,
    size_t index,
    const daegun_run **out_run,
    uint8_t *out_level,
    const size_t **out_chars,
    size_t *out_chars_count
);

The run is BORROWED, valid until the set is freed. Do not pass it to daegun_run_free.

daegun_status daegun_bidi_runs_count(
    const daegun_bidi_runs *runs,
    size_t *out
);

How many direction runs the text resolved into, written to out.

Walk them with daegun_bidi_runs_at. They come back in the order they should be drawn.

void daegun_bidi_runs_free(daegun_bidi_runs *runs);

Frees a daegun_bidi_runs.

Every run borrowed through daegun_bidi_runs_at becomes invalid.

daegun_status daegun_font_shape_bidi(
    const daegun_font *font,
    const char *text,
    const daegun_axis *axes,
    size_t axes_len,
    int32_t base,
    daegun_bidi_runs **out
);

base: 0 left-to-right, 1 right-to-left, -1 to let the first strong character decide. That is how C says Option<bool>, and it recurs everywhere a direction may be unstated.

daegun_status daegun_font_shape_bidi_with(
    const daegun_font *font,
    const char *text,
    const daegun_axis *axes,
    size_t axes_len,
    int32_t base,
    const daegun_shape_options *opts,
    daegun_bidi_runs **out
);

Resolves mixed-direction text and shapes each run with the full shape options.

The same as daegun_font_shape_bidi but applying your daegun_shape_options to every run, so features and language tags carry through. base selects the paragraph direction: negative to detect it, 0 for left to right, 1 for right to left. Free with daegun_bidi_runs_free.

daegun_status daegun_batch_append(
    daegun_batch *batch,
    const float *quads,
    size_t count,
    daegun_glyph_slot *out
);

Adds raw quadratic geometry to a batch directly, producing a slot that draws it.

For drawing shapes of your own through the same GPU path glyphs use. quads is a flat array of quadratic control points and count is the number of quads. The array is copied, so you may free or reuse it immediately.

const uint32_t *daegun_batch_band_curves(
    const daegun_batch *batch,
    size_t *out_count
);

The band-curve index of a batch, borrowed, with the count written to out_count.

Curve indices grouped by band, which the bands point into. The pointer dies with the handle, so copy it out if you need it to outlive one. NULL if either argument is NULL.

const daegun_band *daegun_batch_bands(
    const daegun_batch *batch,
    size_t *out_count
);

The bands of a batch, borrowed, with the count written to out_count.

A band is a horizontal or vertical slice of a glyph naming a run in the band-curve index; the shader uses them to skip curves that cannot affect a pixel. The pointer dies with the handle, so copy it out if you need it to outlive one. NULL if either argument is NULL.

daegun_status daegun_batch_clear(daegun_batch *batch);

Empties a batch, keeping its allocation so it can be refilled without reallocating.

Any slot obtained from the batch before clearing no longer refers to anything.

const daegun_curve_point *daegun_batch_curves(
    const daegun_batch *batch,
    size_t *out_count
);

The four buffers, borrowed. Valid until the batch is CHANGED or freed – appending a glyph may reallocate, so holding one of these across a draw is holding a dangling pointer. daegun_batch_revision is how to tell.

void daegun_batch_free(daegun_batch *batch);

Frees a GPU batch.

Every slot and every buffer taken from it becomes invalid, including geometry already uploaded from it.

const daegun_hull_vertex *daegun_batch_hulls(
    const daegun_batch *batch,
    size_t *out_count
);

The hull vertices of a batch, borrowed, with the count written to out_count.

The coarse geometry drawn to invoke the fragment shader over the area a glyph can cover. The pointer dies with the handle, so copy it out if you need it to outlive one. NULL if either argument is NULL.

daegun_status daegun_batch_new(daegun_batch **out);

Creates a GPU batch, the buffer that accumulates glyph geometry for upload.

The GPU path stores each glyph once in em space and draws it at any size, so a batch is filled with curves, bands and hulls, uploaded once, and then drawn from with per-placement instances. Free with daegun_batch_free.

daegun_status daegun_batch_revision(
    const daegun_batch *batch,
    uint64_t *out
);

Bumped whenever the buffers change, so you know when to re-upload.

const daegun_color_slot *daegun_color_slots_data(
    const daegun_color_slots *slots,
    size_t *out_count
);

The slots inside a daegun_color_slots, borrowed, with the count written to out_count.

Valid only until the handle is freed. Draw them in this order, back to front.

void daegun_color_slots_free(daegun_color_slots *slots);

Frees a daegun_color_slots. The array taken from it becomes invalid.

const daegun_colr_layer *daegun_colr_layers_data(
    const daegun_colr_layers *layers,
    size_t *out_count
);

The layers inside a daegun_colr_layers, borrowed, with the count written to out_count.

They arrive in painting order, back to front, and each carries its glyph, its color and the is_foreground flag. Valid only until the layers handle is freed.

void daegun_colr_layers_free(daegun_colr_layers *layers);

Frees a daegun_colr_layers. The layer array taken from it becomes invalid.

daegun_status daegun_drawn_bitmap(
    const daegun_drawn *d,
    const daegun_bitmap **out
);

BORROWED. Do not free these separately – they belong to the draw result.

const daegun_color_slot *daegun_drawn_color_slots(
    const daegun_drawn *d,
    size_t *out_count
);

The per-layer GPU slots of a drawn color glyph, borrowed, with the count written to out_count.

Valid only when the kind is DAEGUN_DRAWN_GPU_COLOR. Draw them in the order returned – back to front, since the shader does no depth testing.

void daegun_drawn_free(daegun_drawn *d);

Frees a daegun_drawn.

The slot, scene or bitmap it carried becomes invalid.

daegun_status daegun_drawn_is_ok(const daegun_drawn *d, bool *out);

Whether the request was served, written to out.

False only for a refusal or a full batch. Note that "nothing drawn" counts as ok – a space has no ink and was handled correctly.

daegun_status daegun_drawn_kind(const daegun_drawn *d, int32_t *out);

Which path a drawn glyph actually took, written to out as a DAEGUN_DRAWN_* value.

The router decides per glyph, so this is how you find out what you got: a CPU bitmap, a GPU slot, color slots, a finished scene, nothing at all, a full batch, or a refusal.

daegun_status daegun_drawn_scene(
    const daegun_drawn *d,
    const daegun_scene **out
);

The rendered scene inside a drawn color glyph, borrowed.

Valid only when the kind is DAEGUN_DRAWN_SCENE. It dies with the daegun_drawn.

daegun_status daegun_drawn_slot(
    const daegun_drawn *d,
    daegun_glyph_slot *out
);

The GPU slot inside a drawn glyph, written to out.

Valid only when daegun_drawn_kind reports DAEGUN_DRAWN_GPU; anything else returns a failure status rather than a meaningless slot.

daegun_status daegun_font_colr_layers(
    const daegun_font *font,
    uint16_t gid,
    daegun_colr_layers **out
);

The COLR v0 layers of a glyph – a stack of ordinary glyphs, each with a palette color.

Draw them in the order returned, back to front. A layer with is_foreground set takes your text color rather than one from the palette, which is how a font offers a shape that tints with surrounding text. Colors come from palette 0; use daegun_font_colr_layers_for_palette to choose another. Free with daegun_colr_layers_free.

daegun_colr_layers *ls = NULL;
if (daegun_font_colr_layers(font, gid, &ls) == DAEGUN_OK) {
    size_t n = 0;
    const daegun_colr_layer *l = daegun_colr_layers_data(ls, &n);
    for (size_t i = 0; i < n; i++)      /* back to front */
        draw(l[i].gid, l[i].is_foreground ? text_color : rgba(l[i]));
    daegun_colr_layers_free(ls);
}

daegun_status daegun_font_colr_layers_for_palette(
    const daegun_font *font,
    uint16_t gid,
    uint16_t palette_index,
    daegun_colr_layers **out
);

The COLR v0 layers of a glyph with colors taken from a specific palette.

The same as daegun_font_colr_layers but reading the palette you name – use it to honour a font's dark-mode palette, which daegun_font_palette_info will identify.

daegun_status daegun_font_colr_v1_paint(
    const daegun_font *font,
    uint16_t gid,
    const daegun_axis *axes,
    size_t axes_len,
    uint16_t palette_index,
    daegun_paint **out
);

The COLR v1 paint graph for a glyph, unrendered, as an owned handle.

COLR v1 describes a glyph as a tree of paint operations – solid fills, gradients, transforms, clips and blends. This hands you that tree for your own compositor. If you just want pixels, use daegun_font_render_colr_glyph instead.

daegun_status daegun_font_draw_glyph(
    const daegun_font *font,
    daegun_batch *batch,
    const void *device,
    const daegun_policy *policy,
    uint16_t gid,
    float px,
    const daegun_axis *axes,
    size_t axes_len,
    const daegun_raster_options *opts,
    int32_t palette,
    daegun_drawn **out
);

Draws one glyph wherever the policy and the device say it belongs. THERE IS NO DRAW TARGET HANDLE, and that is deliberate. DrawTarget borrows the batch mutably, and a handle would let you outlive the borrow – a use-after-free C cannot see. Building it inside the call makes that unrepresentable: a NULL device is the CPU-only arrangement, a non-NULL one is the device-aware one, and the policy is a parameter rather than something you configure and keep. palette is the color palette index, or -1 for none. opts, policy and device may all be NULL.

daegun_status daegun_font_glyph_bitmap(
    const daegun_font *font,
    uint16_t gid,
    uint16_t target_ppem,
    daegun_glyph_bitmap **out
);

An embedded bitmap, as PNG BYTES rather than pixels – the face stores them that way and daegun does not decode images. You already have a PNG decoder or do not want one.

daegun_status daegun_font_gpu_color_glyph(
    const daegun_font *font,
    daegun_batch *batch,
    uint16_t gid,
    const daegun_axis *axes,
    size_t axes_len,
    uint16_t palette_index,
    daegun_color_slots **out
);

The color equivalent of daegun_font_gpu_glyph: one slot per flat-colored layer, each with its tint.

Draw them in the order returned – they paint back to front and the shader does no depth testing. palette_index selects which CPAL palette supplies the colors. Free with daegun_color_slots_free.

daegun_status daegun_font_gpu_glyph(
    const daegun_font *font,
    daegun_batch *batch,
    uint16_t gid,
    const daegun_axis *axes,
    size_t axes_len,
    daegun_glyph_slot *out
);

Adds a glyph's curves to a batch and writes the slot that identifies it.

One slot serves every size on screen, because the shader evaluates coverage from the curves rather than sampling an atlas – so there is no resolution to choose. Upload the batch once, then build one instance per placement.

daegun_batch *batch = NULL;
daegun_batch_new(&batch);

daegun_glyph_slot slot;
daegun_font_gpu_glyph(font, batch, gid, NULL, 0, &slot);
/* upload the batch's curves, bands and hulls, then instance the slot per placement */

daegun_status daegun_font_palette_count(
    const daegun_font *font,
    uint16_t *out
);

How many CPAL palettes the font carries, or 0 if it carries none.

Most color fonts ship exactly one. Any index below this count is valid wherever a palette index is taken.

daegun_status daegun_font_palette_info(
    const daegun_font *font,
    daegun_palettes **out
);

What each palette is for, including whether it suits a light or a dark background.

Fonts may label their palettes with usability flags. This surfaces them, so you can pick the palette matching your background rather than always taking 0. Free with daegun_palettes_free.

daegun_status daegun_font_render_colr_glyph(
    const daegun_font *font,
    uint16_t gid,
    float px,
    const daegun_axis *axes,
    size_t axes_len,
    uint16_t palette_index,
    daegun_scene **out
);

out_skipped_ops is how many paint operations the renderer could not carry out. Non-zero means the image is incomplete rather than wrong, and anything showing it should know.

void daegun_glyph_bitmap_free(daegun_glyph_bitmap *b);

Frees a daegun_glyph_bitmap.

The PNG bytes taken from it become invalid.

const uint8_t *daegun_glyph_bitmap_png(
    const daegun_glyph_bitmap *b,
    size_t *out_len,
    uint16_t *out_ppem,
    int16_t *out_origin_x,
    int16_t *out_origin_y
);

An embedded bitmap strike as PNG bytes, with its resolution and origin.

Some color fonts ship photographic bitmaps rather than outlines. The data is PNG, not raw pixels – decode it before use. out_ppem is the strike's own resolution, which may differ from the size you asked for, so scale accordingly. The origin places the image relative to the pen.

const uint32_t *daegun_paint_children(
    const daegun_paint *p,
    size_t *out_count
);

A node's children are the child_count entries at child_start.

void daegun_paint_free(daegun_paint *p);

Frees a paint graph.

The node array taken from it becomes invalid.

const daegun_paint_node *daegun_paint_nodes(
    const daegun_paint *p,
    size_t *out_count
);

The nodes of a paint graph, borrowed, with the count written to out_count.

The tree flattened into an array, with nodes referring to each other by index. Valid only until the paint handle is freed.

daegun_status daegun_paint_stops(
    const daegun_paint *p,
    size_t *out_count,
    const double **out_offsets,
    const uint8_t **out_colors
);

Every gradient's stops in one run: a node's are the stops_count entries at stops_start, and out_colors holds FOUR bytes per stop, so stop i is at 4 * i.

const daegun_palette_info *daegun_palettes_data(
    const daegun_palettes *p,
    size_t *out_count
);

The palette entries inside a daegun_palettes, borrowed, with the count written to out_count.

One entry per palette, in the order the font declares them, each carrying the usability flags that say whether it suits a light or a dark background. Valid only until the palettes handle is freed.

void daegun_palettes_free(daegun_palettes *p);

Frees a daegun_palettes. The array taken from it becomes invalid.

daegun_status daegun_policy_default(daegun_policy *out);

Fills a daegun_policy with its defaults – how the router chooses between CPU and GPU.

Call this rather than zeroing the struct. The defaults are a reasonable middle: very large glyphs favor the GPU, very small ones favor the CPU where hinting helps most.

void daegun_scene_free(daegun_scene *s);

Frees a rendered scene.

The RGBA pixel pointer taken from it becomes invalid.

const uint8_t *daegun_scene_rgba(
    const daegun_scene *s,
    size_t *out_len,
    size_t *out_width,
    size_t *out_height,
    int32_t *out_left,
    int32_t *out_top,
    size_t *out_skipped_ops
);

A rendered scene's pixels, borrowed, with its size, position and how many operations were skipped.

Straight alpha RGBA8, not premultiplied, four bytes per pixel. out_left and out_top place the image relative to the origin you rendered at. out_skipped_ops counts paint operations the renderer could not carry out – non-zero means the glyph used something unsupported and the result is incomplete, which is worth checking rather than assuming. Any out parameter may be NULL.

daegun_status daegun_d3d11_draw(
    const daegun_d3d11_renderer *renderer,
    daegun_d3d11_target *target,
    const daegun_d3d11_geometry *geometry,
    const daegun_glyph_instance *instances,
    size_t instance_count,
    const daegun_subpixel_params *subpixel,
    int32_t mode
);

Draws glyph instances into a Direct3D 11 target.

Takes the geometry and an array of instances, each placing one glyph at a position, scale and color. Instance offsets are in device pixels with y up from the bottom of the target, which is the opposite of the top-down convention most 2D layout uses – getting this wrong draws the text mirrored vertically. Use _draw_with to choose the blending mode.

daegun_status daegun_d3d11_draw_with(
    const daegun_d3d11_renderer *renderer,
    daegun_d3d11_target *target,
    const daegun_d3d11_geometry *geometry,
    const daegun_glyph_instance *instances,
    size_t instance_count,
    const daegun_subpixel_params *subpixel,
    int32_t mode,
    const float *projection
);

Under a projection of your own – column-major, NULL for the default.

void daegun_d3d11_geometry_free(daegun_d3d11_geometry *geometry);

Frees Direct3D 11 geometry and the device resources behind it.

Free it before the renderer it was created from.

daegun_status daegun_d3d11_geometry_new(
    const daegun_d3d11_renderer *renderer,
    const daegun_batch *batch,
    daegun_d3d11_geometry **out
);

Uploads a batch's curves, bands and hulls to the Direct3D 11 device as drawable geometry.

This is the step that moves glyph data onto the GPU. Build the batch first, then create geometry from it once and draw from that geometry many times – rebuilding it per frame throws away the whole point of the GPU path. _geometry_revision tells you when the batch has changed enough to need a fresh upload.

daegun_status daegun_d3d11_geometry_revision(
    const daegun_d3d11_geometry *geometry,
    uint64_t *out
);

Compare against daegun_batch_revision to know whether this upload is stale.

daegun_status daegun_d3d11_ortho(
    uint32_t width,
    uint32_t height,
    float *out
);

The default projection, column-major. Needs no device: it depends on this API's clip-space * convention and nothing else, so it can be built before anything is opened.

const uint8_t *daegun_d3d11_read_pixels(
    const daegun_d3d11_renderer *renderer,
    daegun_d3d11_target *target,
    size_t *out_count
);

Waits, copies off the device, and hands back BGRA. BORROWED, valid until the target is drawn * into again or freed. NULL on failure, with the reason in daegun_last_error. * * THIS IS THE EXPENSIVE CALL. On a discrete GPU the readback dominates: 489 us of a 513 us * frame at 1024x1024, measured. A caller that can consume the target on the device should not * call it at all.

daegun_status daegun_d3d11_renderer_device_name(
    const daegun_d3d11_renderer *renderer,
    daegun_text **out
);

Free with daegun_text_free.

void daegun_d3d11_renderer_free(daegun_d3d11_renderer *renderer);

Safe to call while a target or geometry is still alive; the device goes with the last.

daegun_status daegun_d3d11_renderer_new(daegun_d3d11_renderer **out);

DAEGUN_UNSUPPORTED when there is no such device, which is an answer and not a failure.

daegun_status daegun_d3d11_renderer_profile(
    const daegun_d3d11_renderer *renderer,
    daegun_device_profile **out
);

Free with daegun_device_profile_free.

daegun_status daegun_d3d11_renderer_supports_subpixel(
    const daegun_d3d11_renderer *renderer,
    int32_t *out
);

Whether this Direct3D 11 device can do subpixel rendering, written to out.

Subpixel output needs dual-source blending, which not every device and driver exposes. When this is false, use grayscale coverage instead – the text is still correct, just without the threefold horizontal resolution an LCD stripe would allow.

void daegun_d3d11_target_free(daegun_d3d11_target *target);

Frees a Direct3D 11 target.

Any pixel pointer taken from it becomes invalid.

daegun_status daegun_d3d11_target_height(
    const daegun_d3d11_target *target,
    uint32_t *out
);

The height of a Direct3D 11 target in pixels, written to out.

daegun_status daegun_d3d11_target_new(
    const daegun_d3d11_renderer *renderer,
    uint32_t width,
    uint32_t height,
    daegun_d3d11_target **out
);

Creates a Direct3D 11 render target of the given size.

The target owns its pixels, which you read back with _target_pixels or _read_pixels. Free it with _target_free before the renderer it came from.

daegun_status daegun_d3d11_target_pixel(
    const daegun_d3d11_target *target,
    uint32_t x,
    uint32_t y,
    uint8_t *out
);

One pixel as BGRA into four bytes. DAEGUN_RANGE outside the target.

const uint8_t *daegun_d3d11_target_pixels(
    const daegun_d3d11_target *target,
    size_t *out_count
);

BORROWED, BGRA. What the last _read_pixels left behind, without the round trip. Valid until * the target is drawn into again or freed.

daegun_status daegun_d3d11_target_width(
    const daegun_d3d11_target *target,
    uint32_t *out
);

The width of a Direct3D 11 target in pixels, written to out.

daegun_status daegun_d3d11_wait(
    const daegun_d3d11_renderer *renderer,
    daegun_d3d11_target *target
);

Blocks until the Direct3D 11 device has finished the work already submitted.

Needed before reading pixels back, and at shutdown. On a normal render loop you do not want this – it gives up the parallelism between CPU and GPU that makes the GPU path worth using.

daegun_status daegun_d3d12_draw(
    const daegun_d3d12_renderer *renderer,
    daegun_d3d12_target *target,
    const daegun_d3d12_geometry *geometry,
    const daegun_glyph_instance *instances,
    size_t instance_count,
    const daegun_subpixel_params *subpixel,
    int32_t mode
);

Draws glyph instances into a Direct3D 12 target.

Takes the geometry and an array of instances, each placing one glyph at a position, scale and color. Instance offsets are in device pixels with y up from the bottom of the target, which is the opposite of the top-down convention most 2D layout uses – getting this wrong draws the text mirrored vertically. Use _draw_with to choose the blending mode.

daegun_status daegun_d3d12_draw_with(
    const daegun_d3d12_renderer *renderer,
    daegun_d3d12_target *target,
    const daegun_d3d12_geometry *geometry,
    const daegun_glyph_instance *instances,
    size_t instance_count,
    const daegun_subpixel_params *subpixel,
    int32_t mode,
    const float *projection
);

Under a projection of your own – column-major, NULL for the default.

void daegun_d3d12_geometry_free(daegun_d3d12_geometry *geometry);

Frees Direct3D 12 geometry and the device resources behind it.

Free it before the renderer it was created from.

daegun_status daegun_d3d12_geometry_new(
    const daegun_d3d12_renderer *renderer,
    const daegun_batch *batch,
    daegun_d3d12_geometry **out
);

Uploads a batch's curves, bands and hulls to the Direct3D 12 device as drawable geometry.

This is the step that moves glyph data onto the GPU. Build the batch first, then create geometry from it once and draw from that geometry many times – rebuilding it per frame throws away the whole point of the GPU path. _geometry_revision tells you when the batch has changed enough to need a fresh upload.

daegun_status daegun_d3d12_geometry_revision(
    const daegun_d3d12_geometry *geometry,
    uint64_t *out
);

Compare against daegun_batch_revision to know whether this upload is stale.

daegun_status daegun_d3d12_ortho(
    uint32_t width,
    uint32_t height,
    float *out
);

The default projection, column-major. Needs no device: it depends on this API's clip-space * convention and nothing else, so it can be built before anything is opened.

const uint8_t *daegun_d3d12_read_pixels(
    const daegun_d3d12_renderer *renderer,
    daegun_d3d12_target *target,
    size_t *out_count
);

Waits, copies off the device, and hands back BGRA. BORROWED, valid until the target is drawn * into again or freed. NULL on failure, with the reason in daegun_last_error. * * THIS IS THE EXPENSIVE CALL. On a discrete GPU the readback dominates: 489 us of a 513 us * frame at 1024x1024, measured. A caller that can consume the target on the device should not * call it at all.

daegun_status daegun_d3d12_renderer_device_name(
    const daegun_d3d12_renderer *renderer,
    daegun_text **out
);

Free with daegun_text_free.

void daegun_d3d12_renderer_free(daegun_d3d12_renderer *renderer);

Safe to call while a target or geometry is still alive; the device goes with the last.

daegun_status daegun_d3d12_renderer_new(daegun_d3d12_renderer **out);

DAEGUN_UNSUPPORTED when there is no such device, which is an answer and not a failure.

daegun_status daegun_d3d12_renderer_profile(
    const daegun_d3d12_renderer *renderer,
    daegun_device_profile **out
);

Free with daegun_device_profile_free.

daegun_status daegun_d3d12_renderer_supports_subpixel(
    const daegun_d3d12_renderer *renderer,
    int32_t *out
);

Whether this Direct3D 12 device can do subpixel rendering, written to out.

Subpixel output needs dual-source blending, which not every device and driver exposes. When this is false, use grayscale coverage instead – the text is still correct, just without the threefold horizontal resolution an LCD stripe would allow.

void daegun_d3d12_target_free(daegun_d3d12_target *target);

Frees a Direct3D 12 target.

Any pixel pointer taken from it becomes invalid.

daegun_status daegun_d3d12_target_height(
    const daegun_d3d12_target *target,
    uint32_t *out
);

The height of a Direct3D 12 target in pixels, written to out.

daegun_status daegun_d3d12_target_new(
    const daegun_d3d12_renderer *renderer,
    uint32_t width,
    uint32_t height,
    daegun_d3d12_target **out
);

Creates a Direct3D 12 render target of the given size.

The target owns its pixels, which you read back with _target_pixels or _read_pixels. Free it with _target_free before the renderer it came from.

daegun_status daegun_d3d12_target_pixel(
    const daegun_d3d12_target *target,
    uint32_t x,
    uint32_t y,
    uint8_t *out
);

One pixel as BGRA into four bytes. DAEGUN_RANGE outside the target.

const uint8_t *daegun_d3d12_target_pixels(
    const daegun_d3d12_target *target,
    size_t *out_count
);

BORROWED, BGRA. What the last _read_pixels left behind, without the round trip. Valid until * the target is drawn into again or freed.

daegun_status daegun_d3d12_target_width(
    const daegun_d3d12_target *target,
    uint32_t *out
);

The width of a Direct3D 12 target in pixels, written to out.

daegun_status daegun_d3d12_wait(
    const daegun_d3d12_renderer *renderer,
    daegun_d3d12_target *target
);

Blocks until the Direct3D 12 device has finished the work already submitted.

Needed before reading pixels back, and at shutdown. On a normal render loop you do not want this – it gives up the parallelism between CPU and GPU that makes the GPU path worth using.

void daegun_font_buffer_free(uint8_t *data, size_t len);

Frees a buffer you took but never handed over. Null is a no-op. Do NOT call this after daegun_font_open_owned – that took ownership, whether it succeeded or not.

uint8_t *daegun_font_buffer_new(size_t len);

A buffer for a font, allocated by daegun so it can be handed back without a copy. daegun_font_open copies your bytes so you may free them the moment it returns. This is the way around that copy – take a buffer, read the file into it, hand it back: uint8_t *buf = daegun_font_buffer_new(len); fread(buf, 1, len, fp); daegun_font *font = NULL; daegun_status st = daegun_font_open_owned(buf, len, &font); // buf belongs to the font now, pass or fail. Do not free it, do not read it. NULL for a zero length. This is not an ordinary pointer: never free() it.

void daegun_font_free(daegun_font *font);

Frees a font. NULL is a no-op, as free(NULL) is.

daegun_status daegun_font_glyph_id(
    const daegun_font *font,
    uint32_t codepoint,
    uint16_t *out
);

The glyph a Unicode codepoint maps to. DAEGUN_ABSENT when the font has none.

daegun_status daegun_font_num_glyphs(
    const daegun_font *font,
    uint16_t *out
);

How many glyphs the face has.

daegun_status daegun_font_open(
    const uint8_t *data,
    size_t len,
    daegun_font **out
);

Opens a font. The bytes are COPIED, so you may free them the moment this returns.

daegun_status daegun_font_open_collection(
    const uint8_t *data,
    size_t len,
    size_t index,
    daegun_font **out
);

The same, for one face of a .ttc collection.

daegun_status daegun_font_open_owned(
    uint8_t *data,
    size_t len,
    daegun_font **out
);

Opens a font from a daegun buffer, taking ownership of it. Copies nothing. The buffer belongs to the font afterwards either way: freed with daegun_font_free, or immediately if the bytes did not parse. len must be exactly what you passed to daegun_font_buffer_new.

daegun_status daegun_font_upm(const daegun_font *font, uint16_t *out);

Units per em: the denominator every em-space figure in this API is in.

daegun_status daegun_ttc_font_count(
    const uint8_t *data,
    size_t len,
    size_t *out
);

How many faces a .ttc holds. Zero for data that is not a collection. Takes bytes rather than a font, because it answers what a caller asks before deciding which face to open.

daegun_status daegun_font_advance_widths(
    const daegun_font *font,
    const uint16_t *gids,
    size_t gids_len,
    const daegun_axis *axes,
    size_t axes_len,
    daegun_f64_list **out
);

The advance width of each given glyph, on the 1000-unit em, returned as an owned daegun_f64_list.

Batched because the values are cached per axis position, so asking for many at once is much cheaper than one call each. These are raw per-glyph widths with no kerning or positioning applied – to measure text, use the advances from a shaped run instead. Free the list with daegun_f64_list_free.

daegun_f64_list *w = NULL;
daegun_font_advance_widths(font, gids, n, NULL, 0, &w);
size_t count = 0;
const double *vals = daegun_f64_list_data(w, &count);
daegun_f64_list_free(w);

daegun_status daegun_font_caret_positions(
    const daegun_font *font,
    const char *text,
    const daegun_axis *axes,
    size_t axes_len,
    bool vertical,
    daegun_f64_list **out
);

Every position a cursor may occupy in a string, one per character boundary, on the 1000-unit em.

Shapes the text and works out where each character boundary landed – which is harder than it sounds, because ligatures collapse several characters into one glyph, marks take no width, and right-to-left runs advance leftward. Returns one more value than there are characters: the position after the last. Free with daegun_f64_list_free.

daegun_f64_list *carets = NULL;
daegun_font_caret_positions(font, "office", NULL, 0, false, &carets);
size_t n = 0;
const double *pos = daegun_f64_list_data(carets, &n);
/* pos[2] sits between the two f's, though they shaped to one glyph */
daegun_f64_list_free(carets);

daegun_status daegun_font_codepoints(
    const daegun_font *font,
    daegun_u32_list **out
);

Every code point the font supports, as an owned daegun_u32_list.

The cmap flattened, without the glyph ids. Build a set from it once if you are testing many characters. Free with daegun_u32_list_free.

daegun_status daegun_font_coverage(
    const daegun_font *font,
    daegun_u32_list **out_codepoints,
    daegun_u16_list **out_gids
);

Every codepoint the cmap maps, with the glyph each reaches, at matching indices.

daegun_status daegun_font_default_vertical_origin(
    const daegun_font *font,
    int32_t *out
);

The vertical origin the font uses for glyphs that do not specify their own, on the 1000-unit em.

Writes 0 for a TrueType outline font, which derives origins per glyph instead.

daegun_status daegun_font_glyph_bounds(
    const daegun_font *font,
    uint16_t gid,
    const daegun_axis *axes,
    size_t axes_len,
    double *out
);

A glyph's tight ink box at a location: out receives FOUR doubles, [xmin, ymin, xmax, ymax]. DAEGUN_ABSENT for a glyph that draws nothing – a space has no ink, which differs from a box of zero size.

daegun_status daegun_font_glyph_class(
    const daegun_font *font,
    uint16_t gid,
    int32_t *out
);

What kind of glyph this is – base, ligature, mark or component – written to out as a DAEGUN_GLYPH_CLASS_* value.

From the GDEF table. Chiefly used to tell a combining mark from a spacing glyph, since a mark takes no advance of its own. Returns DAEGUN_ABSENT when the font does not classify the glyph, which is common and not an error.

daegun_status daegun_font_glyph_ids(
    const daegun_font *font,
    const char *text,
    daegun_u16_list **out_gids,
    daegun_blob **out_present
);

The glyph each character of a string maps to. TWO lists, because entries may be absent: out_gids holds one id per character, out_present one byte per character, non-zero where the font actually has a glyph. A sentinel would not work – 0 is .notdef and every other uint16_t is a real glyph id in some face. Either may be NULL.

daegun_status daegun_font_glyph_name(
    const daegun_font *font,
    uint16_t gid,
    daegun_text **out
);

The PostScript name of one glyph, as an owned daegun_text *.

Many fonts ship a version 3 post table, which stores no names at all, so DAEGUN_ABSENT is common and expected. Read the string with daegun_text_str and free with daegun_text_free. Names are for debugging and PDF, never for identifying a glyph programmatically – use the id.

daegun_text *name = NULL;
if (daegun_font_glyph_name(font, gid, &name) == DAEGUN_OK) {
    daegun_str s;
    daegun_text_str(name, &s);
    printf("%.*s\n", (int)s.len, s.data);
    daegun_text_free(name);
}

daegun_status daegun_font_glyph_names(
    const daegun_font *font,
    daegun_str_list **out_names,
    daegun_blob **out_present
);

Two lists again: an empty string is a name a font can genuinely state, so out_present says which entries mean anything.

daegun_status daegun_font_has_glyph(
    const daegun_font *font,
    uint32_t codepoint,
    bool *out
);

Whether the font can render a code point, written to out.

Useful for choosing a fallback font before committing to one.

bool ok = false;
daegun_font_has_glyph(font, 0x5B57, &ok);   /* U+5B57 字 */

daegun_status daegun_font_ligature_carets(
    const daegun_font *font,
    uint16_t gid,
    const daegun_axis *axes,
    size_t axes_len,
    daegun_f64_list **out
);

Where a text cursor may sit inside a ligature, on the 1000-unit em, as an owned daegun_f64_list.

When "fi" becomes one glyph, a cursor still has to be placeable between the f and the i. The positions are offset from the ligature's own origin. Empty for an ordinary glyph. For cursor positions across a whole string, use daegun_font_caret_positions.

daegun_status daegun_font_mark_attachment_class(
    const daegun_font *font,
    uint16_t gid,
    uint16_t *out
);

The mark attachment class of a glyph, or 0 when it has none.

Fonts group marks into classes so a positioning rule can apply to a whole group. The number is meaningful only against the rules in that same font.

daegun_status daegun_font_variation_glyph_id(
    const daegun_font *font,
    uint32_t base,
    uint32_t selector,
    uint16_t *out
);

Resolves a base character plus a Unicode variation selector to a glyph id.

Variation sequences let one character request a specific form: U+FE0E asks for the text presentation of an emoji and U+FE0F for the emoji presentation. Returns DAEGUN_ABSENT when the font does not map the pair. Shaping applies these already, so use this only when handling selectors yourself.

daegun_status daegun_font_vertical_advance(
    const daegun_font *font,
    uint16_t gid,
    const daegun_axis *axes,
    size_t axes_len,
    uint32_t *out
);

The vertical advance of one glyph on the 1000-unit em, for text set top to bottom.

How far the pen moves down after this glyph. Writes 0 for a glyph id past the end of the font – a deliberate refusal, since other tables will answer confidently for ids that do not exist.

daegun_status daegun_font_vertical_origin(
    const daegun_font *font,
    uint16_t gid,
    const daegun_axis *axes,
    size_t axes_len,
    int32_t *out
);

The y origin used when a glyph is set vertically, on the 1000-unit em.

In vertical text a glyph hangs from an origin above the baseline rather than sitting on it. Returns DAEGUN_ABSENT for a glyph id past the end of the font rather than a plausible wrong number.

const uint32_t *daegun_u32_list_data(
    const daegun_u32_list *list,
    size_t *out_count
);

The elements of a daegun_u32_list, borrowed, with the count written to out_count.

The pointer is valid only until the list is freed. Copy the elements out if you need them to outlive it. Returns NULL if either argument is NULL.

void daegun_u32_list_free(daegun_u32_list *list);

Frees a daegun_u32_list. Any pointer obtained from it becomes invalid.

void daegun_cff_hints_free(daegun_cff_hints *hints);

Frees a daegun_cff_hints.

The stem positions taken from it become invalid.

const double *daegun_cff_hints_stems(
    const daegun_cff_hints *hints,
    size_t *out_count
);

THREE doubles per stem – is_vertical as 0 or 1, then the edge positions min and max, so a stem's width is max - min. out_count receives the number of STEMS, not of doubles.

daegun_status daegun_font_cff_hints(
    const daegun_font *font,
    uint16_t gid,
    daegun_cff_hints **out
);

The hint data a CFF glyph carries – its stem positions and any hint replacement.

CFF fonts declare stems declaratively rather than running bytecode. Returns DAEGUN_ABSENT for TrueType outlines, which hint through instructions instead.

daegun_status daegun_font_hinted_glyph(
    const daegun_font *font,
    uint16_t gid,
    float px,
    const daegun_axis *axes,
    size_t axes_len,
    int32_t hint_mode,
    daegun_hinted_outline **out
);

A glyph's outline after hinting has moved it onto the pixel grid, without rasterizing it.

Hinting normally happens inside rasterizing; this exposes the result for inspection or for a rasterizer of your own. The outline is in pixel space at the size you asked for, not in font units, because grid fitting is only meaningful at a size.

const size_t *daegun_hinted_outline_contours(
    const daegun_hinted_outline *outline,
    size_t *out_count
);

Where each contour ends, as an index one past its last point.

void daegun_hinted_outline_free(daegun_hinted_outline *outline);

Frees a hinted outline.

The grid-fitted points become invalid; replay them onto a pen first if you need them.

daegun_status daegun_hinted_outline_points(
    const daegun_hinted_outline *outline,
    size_t *out_count,
    const int32_t **out_x,
    const int32_t **out_y,
    const uint8_t **out_flags
);

Every pointer but out_count may be NULL.

daegun_status daegun_font_justification_extenders(
    const daegun_font *font,
    const char *script_tag,
    daegun_u16_list **out
);

The glyphs a script uses to stretch a line, such as the Arabic kashida.

From the JSTF table. Empty for scripts that do not justify this way and for fonts that do not say. Needed only when implementing justification yourself. Free with daegun_u16_list_free.

daegun_status daegun_font_justification_priorities(
    const daegun_font *font,
    const char *script_tag,
    const char *lang_sys_tag,
    daegun_jstf_priorities **out
);

lang_sys_tag may be NULL.

daegun_status daegun_font_justify(
    const daegun_font *font,
    const char *text,
    const daegun_axis *axes,
    size_t axes_len,
    bool vertical,
    const char *script_tag,
    const char *lang_sys_tag,
    double target_width,
    double tolerance,
    daegun_justified **out
);

Shapes a string and fits it to a target width using the font's own justification rules.

The call to use for justified text. It prefers what the font was designed to do – elongating Arabic kashida, substituting alternate forms described in JSTF – and falls back to spacing adjustments. target_width and tolerance are on the 1000-unit em like every other measurement, so divide a pixel target by px / 1000.0 on the way in. script_tag selects the rules, since Arabic and Latin justify quite differently; lang_sys_tag may be NULL. Free the result with daegun_justified_free.

double px = 16.0, scale = px / 1000.0;

daegun_justified *j = NULL;
daegun_status st = daegun_font_justify(
    font, line, NULL, 0, false,
    "latn", NULL,
    320.0 / scale,   /* a 320px measure, on the 1000-unit em */
    0.05,
    &j);

if (st == DAEGUN_OK) {
    const daegun_run *run = daegun_justified_run(j);
    /* draw the run, then */
    daegun_justified_free(j);
}

daegun_status daegun_font_shape_justified(
    const daegun_font *font,
    const char *text,
    const daegun_axis *axes,
    size_t axes_len,
    bool vertical,
    const daegun_jstf_mods *mods,
    bool shrink,
    daegun_run **out
);

Shapes a string and applies the font's justification rules to stretch or shrink it.

Rather than only adding space between words, this uses what the font offers – elongating kashida, substituting wider or narrower forms. mods selects which of those to apply and shrink chooses tightening over stretching. daegun_font_justify is the higher-level call that takes a target width instead.

daegun_status daegun_jstf_priorities_at(
    const daegun_jstf_priorities *p,
    size_t index,
    const daegun_jstf_mods **out
);

One level, BORROWED – valid until the priorities are freed, and there is nothing to free.

daegun_status daegun_jstf_priorities_count(
    const daegun_jstf_priorities *p,
    size_t *out
);

How many justification priority levels the font describes, written to out.

Fonts describe justification as an ordered sequence of adjustments to try. This is how many steps that sequence has.

void daegun_jstf_priorities_free(daegun_jstf_priorities *p);

Frees a daegun_jstf_priorities.

The priority levels taken from it become invalid.

void daegun_justified_free(daegun_justified *j);

Frees a daegun_justified.

The shaped run borrowed through daegun_justified_run becomes invalid.

daegun_status daegun_justified_info(
    const daegun_justified *j,
    bool *out_has_level,
    size_t *out_level,
    bool *out_shrink,
    double *out_width,
    bool *out_best_effort
);

What justification achieved: the level applied, the direction, the width reached, and whether it fell short.

out_width is on the 1000-unit em. out_best_effort is set when the target could not be met exactly – a line with nothing stretchable in it cannot always be made to fit. out_shrink says the line was tightened rather than stretched. Any out parameter may be NULL.

const daegun_run *daegun_justified_run(const daegun_justified *j);

The shaped run inside a justification result, borrowed.

Valid only until the daegun_justified is freed.

daegun_status daegun_bidi_paragraph_base_level(
    const daegun_bidi_paragraph *p,
    uint8_t *out
);

The paragraph's base embedding level: 0 for left to right, 1 for right to left.

What direction resolution settled on, whether you supplied it or let it be detected.

void daegun_bidi_paragraph_free(daegun_bidi_paragraph *p);

Frees a daegun_bidi_paragraph.

daegun_status daegun_font_layout(
    const daegun_font *font,
    const char *text,
    const daegun_axis *axes,
    size_t axes_len,
    const daegun_layout_options *opts,
    daegun_layout **out
);

Shapes, breaks and positions a whole paragraph into lines in one call.

The complete paragraph path: it shapes the text, finds break opportunities, chooses where to break, and positions each line. Every size in and out is on the 1000-unit em, so a pixel measure goes in as px_value / (px / 1000.0). Fill the options with daegun_layout_options_default first. Free the result with daegun_layout_free.

daegun_layout_options opts;
daegun_layout_options_default(&opts);

double px = 16.0, scale = px / 1000.0;
opts.max_inline_size = 320.0 / scale;
opts.strategy = DAEGUN_BREAK_OPTIMAL;

daegun_layout *layout = NULL;
if (daegun_font_layout(font, text, NULL, 0, &opts, &layout) == DAEGUN_OK) {
    size_t lines = 0; double iw = 0, bh = 0; bool trunc = false; size_t tcount = 0;
    daegun_layout_info(layout, &lines, &iw, &bh, &trunc, &tcount);
    daegun_layout_free(layout);
}

void daegun_layout_free(daegun_layout *layout);

Frees a laid-out paragraph.

Every line and every positioned run borrowed from it becomes invalid.

daegun_status daegun_layout_info(
    const daegun_layout *layout,
    size_t *out_line_count,
    double *out_inline_size,
    double *out_block_size,
    bool *out_has_truncated,
    size_t *out_truncated
);

The summary of a laid-out paragraph: line count, its measured size, and whether anything was truncated.

Sizes are on the 1000-unit em. out_has_truncated and out_truncated report text that did not fit within a line limit, so you can show an ellipsis or grow the box. Any out parameter may be NULL if you do not want that value.

daegun_status daegun_layout_line(
    const daegun_layout *layout,
    size_t index,
    size_t *out_run_count,
    size_t *out_char_start,
    size_t *out_char_end,
    double *out_baseline,
    double *out_inline_size,
    double *out_ascent,
    double *out_descent,
    bool *out_hard_break
);

One line of a laid-out paragraph by index.

Lines are numbered from 0 up to the count daegun_layout_info reports.

daegun_status daegun_layout_options_default(daegun_layout_options *out);

Fills a daegun_layout_options with its defaults.

Call this rather than zeroing the struct. A zeroed struct means a measure of zero, which wraps every word onto its own line.

daegun_status daegun_layout_run(
    const daegun_layout *layout,
    size_t line,
    size_t index,
    const daegun_run **out_run,
    double *out_offset_x,
    double *out_offset_y,
    uint8_t *out_level,
    size_t *out_char_start,
    size_t *out_char_end,
    bool *out_upright
);

The run is BORROWED, valid until the layout is freed.

daegun_status daegun_script_is_rtl(uint16_t script, bool *out);

DAEGUN_ABSENT where the script has no inherent direction.

daegun_status daegun_script_name(uint16_t script, daegun_text **out);

The human-readable name of a script code, as an owned daegun_text.

For display and debugging. Free with daegun_text_free.

daegun_status daegun_text_bidi_paragraph(
    const char *text,
    int32_t base,
    daegun_bidi_paragraph **out
);

The same bidi resolution as daegun_text_resolve_bidi, kept in a handle rather than copied out.

Use this when you will ask several questions of the same paragraph – splitting successive lines into visual runs, for instance – so the work is done once. Free with daegun_bidi_paragraph_free.

daegun_status daegun_text_grapheme_boundaries(
    const char *text,
    daegun_u32_list **out
);

Every position where a user-perceived character begins, as byte offsets in an owned daegun_u32_list.

What a person calls "a character" is a grapheme cluster, often several code points: a letter plus accents, a regional indicator pair, an emoji with a skin tone modifier. These are the boundaries cursor movement, selection and deletion should step by. Free with daegun_u32_list_free.

daegun_status daegun_text_line_break_opportunities(
    const char *text,
    daegun_u32_list **out_at,
    daegun_blob **out_mandatory
);

Two lists at matching indices: byte offsets, and one byte each, non-zero for a break the text demands rather than merely allows.

daegun_status daegun_text_line_visual_runs(
    const daegun_bidi_paragraph *p,
    size_t start,
    size_t end,
    daegun_visual_runs **out
);

start and end are CHARACTER indices into the paragraph, not bytes.

daegun_status daegun_text_resolve_bidi(
    const char *text,
    int32_t base,
    uint8_t *out_base_level,
    daegun_blob **out_levels,
    daegun_u32_list **out_visual_order
);

Runs the Unicode bidirectional algorithm, writing each character's level and the visual order.

Mixed Arabic and Latin text is stored in reading order but drawn in another, and working out that order is a real algorithm rather than a reversal. out_levels is a byte per character – even is left to right, odd is right to left – and out_visual_order lists character indices in drawing order. base selects the paragraph direction: negative to detect it, 0 for left to right, 1 for right to left. Free both outputs.

daegun_status daegun_text_script_runs(
    const char *text,
    daegun_u32_list **out
);

Where each run of a single script begins, as byte offsets.

Shaping works on one script at a time, so mixed text must be split first. Common characters – spaces, digits, punctuation – fold into the surrounding run rather than starting a new one.

daegun_status daegun_text_word_boundaries(
    const char *text,
    daegun_u32_list **out
);

Every position where a word begins or ends, as byte offsets in an owned daegun_u32_list.

Unicode word segmentation, for double-click selection and word-wise cursor movement. It handles what splitting on spaces does not: contractions stay whole, numbers with separators stay whole, and scripts written without spaces follow their own rules.

daegun_status daegun_visual_runs_at(
    const daegun_visual_runs *runs,
    size_t index,
    uint8_t *out_level,
    const size_t **out_chars,
    size_t *out_chars_count
);

One visual run by index: its embedding level and the characters it covers.

Even levels run left to right, odd levels right to left. out_chars borrows from the runs handle. Runs are indexed in the order they should be drawn, so walking 0 upward lays the line out correctly without further reordering.

daegun_status daegun_visual_runs_count(
    const daegun_visual_runs *runs,
    size_t *out
);

How many single-direction runs a line splits into, written to out.

void daegun_visual_runs_free(daegun_visual_runs *runs);

Frees a daegun_visual_runs. The run array taken from it becomes invalid.

bool daegun_writing_mode_is_vertical(int32_t mode);

Whether a writing mode runs top to bottom.

False for horizontal, true for both vertical modes. The two vertical modes differ only in whether successive lines advance left or right; both run their glyphs downward.

uint32_t daegun_abi_version(void);

The ABI this library was built with, as (major << 16) | (minor << 8) | patch. Refuse a library whose major does not match what you compiled against. A struct that grew a field is not detectable any other way.

daegun_str daegun_last_error(void);

What the last failing call ON THIS THREAD said, as UTF-8. Empty when nothing has failed. Per-thread, like errno, because handles are shared and a global slot would hand one thread another's failure. Valid until the next failing call on this thread.

daegun_status daegun_metal_draw(
    const daegun_metal_renderer *renderer,
    daegun_metal_target *target,
    const daegun_metal_geometry *geometry,
    const daegun_glyph_instance *instances,
    size_t instance_count,
    const daegun_subpixel_params *subpixel,
    int32_t mode
);

Draws glyph instances into a Metal target.

Takes the geometry and an array of instances, each placing one glyph at a position, scale and color. Instance offsets are in device pixels with y up from the bottom of the target, which is the opposite of the top-down convention most 2D layout uses – getting this wrong draws the text mirrored vertically. Use _draw_with to choose the blending mode.

daegun_status daegun_metal_draw_with(
    const daegun_metal_renderer *renderer,
    daegun_metal_target *target,
    const daegun_metal_geometry *geometry,
    const daegun_glyph_instance *instances,
    size_t instance_count,
    const daegun_subpixel_params *subpixel,
    int32_t mode,
    const float *projection
);

Under a projection of your own – column-major, NULL for the default.

void daegun_metal_geometry_free(daegun_metal_geometry *geometry);

Frees Metal geometry and the device resources behind it.

Free it before the renderer it was created from.

daegun_status daegun_metal_geometry_new(
    const daegun_metal_renderer *renderer,
    const daegun_batch *batch,
    daegun_metal_geometry **out
);

Uploads a batch's curves, bands and hulls to the Metal device as drawable geometry.

This is the step that moves glyph data onto the GPU. Build the batch first, then create geometry from it once and draw from that geometry many times – rebuilding it per frame throws away the whole point of the GPU path. _geometry_revision tells you when the batch has changed enough to need a fresh upload.

daegun_status daegun_metal_geometry_revision(
    const daegun_metal_geometry *geometry,
    uint64_t *out
);

Compare against daegun_batch_revision to know whether this upload is stale.

daegun_status daegun_metal_ortho(
    uint32_t width,
    uint32_t height,
    float *out
);

The default projection, column-major. Needs no device: it depends on this API's clip-space * convention and nothing else, so it can be built before anything is opened.

const uint8_t *daegun_metal_read_pixels(
    const daegun_metal_renderer *renderer,
    daegun_metal_target *target,
    size_t *out_count
);

Waits, copies off the device, and hands back BGRA. BORROWED, valid until the target is drawn * into again or freed. NULL on failure, with the reason in daegun_last_error. * * THIS IS THE EXPENSIVE CALL. On a discrete GPU the readback dominates: 489 us of a 513 us * frame at 1024x1024, measured. A caller that can consume the target on the device should not * call it at all.

daegun_status daegun_metal_renderer_device_name(
    const daegun_metal_renderer *renderer,
    daegun_text **out
);

Free with daegun_text_free.

void daegun_metal_renderer_free(daegun_metal_renderer *renderer);

Safe to call while a target or geometry is still alive; the device goes with the last.

daegun_status daegun_metal_renderer_new(daegun_metal_renderer **out);

DAEGUN_UNSUPPORTED when there is no such device, which is an answer and not a failure.

daegun_status daegun_metal_renderer_profile(
    const daegun_metal_renderer *renderer,
    daegun_device_profile **out
);

Free with daegun_device_profile_free.

daegun_status daegun_metal_renderer_supports_subpixel(
    const daegun_metal_renderer *renderer,
    int32_t *out
);

Whether this Metal device can do subpixel rendering, written to out.

Subpixel output needs dual-source blending, which not every device and driver exposes. When this is false, use grayscale coverage instead – the text is still correct, just without the threefold horizontal resolution an LCD stripe would allow.

void daegun_metal_target_free(daegun_metal_target *target);

Frees a Metal target.

Any pixel pointer taken from it becomes invalid.

daegun_status daegun_metal_target_height(
    const daegun_metal_target *target,
    uint32_t *out
);

The height of a Metal target in pixels, written to out.

daegun_status daegun_metal_target_new(
    const daegun_metal_renderer *renderer,
    uint32_t width,
    uint32_t height,
    daegun_metal_target **out
);

Creates a Metal render target of the given size.

The target owns its pixels, which you read back with _target_pixels or _read_pixels. Free it with _target_free before the renderer it came from.

daegun_status daegun_metal_target_pixel(
    const daegun_metal_target *target,
    uint32_t x,
    uint32_t y,
    uint8_t *out
);

One pixel as BGRA into four bytes. DAEGUN_RANGE outside the target.

const uint8_t *daegun_metal_target_pixels(
    const daegun_metal_target *target,
    size_t *out_count
);

BORROWED, BGRA. What the last _read_pixels left behind, without the round trip. Valid until * the target is drawn into again or freed.

daegun_status daegun_metal_target_width(
    const daegun_metal_target *target,
    uint32_t *out
);

The width of a Metal target in pixels, written to out.

daegun_status daegun_metal_wait(
    const daegun_metal_renderer *renderer,
    daegun_metal_target *target
);

Blocks until the Metal device has finished the work already submitted.

Needed before reading pixels back, and at shutdown. On a normal render loop you do not want this – it gives up the parallelism between CPU and GPU that makes the GPU path worth using.

daegun_status daegun_raster_options_default(daegun_raster_options *out);

Fills a daegun_raster_options with its defaults.

Call this rather than zeroing the struct. You can also pass NULL for the options to any call that takes them, which means exactly these defaults – so you need not build the struct at all unless you are changing something.

daegun_raster_options opts;
daegun_raster_options_default(&opts);
opts.hinting = DAEGUN_HINT_AUTO;

daegun_status daegun_font_clear_prewarm(const daegun_font *font);

Drops every cached outline, leaving the rasterized glyph cache alone.

The two caches are independent: daegun_font_clear_glyph_cache clears the rasterized bitmaps, this clears the outlines.

daegun_status daegun_font_outline_glyph(
    const daegun_font *font,
    uint16_t gid,
    const daegun_pen *pen
);

The stored outline – the default instance, whatever location you are working at.

daegun_status daegun_font_outline_glyph_instanced(
    const daegun_font *font,
    uint16_t gid,
    const daegun_axis *axes,
    size_t axes_len,
    const daegun_pen *pen
);

The same, resolving variation deltas at a location first.

daegun_status daegun_font_prewarm(
    const daegun_font *font,
    const uint16_t *gids,
    size_t gids_len,
    const daegun_axis *axes,
    size_t axes_len,
    size_t *out_added
);

Loads and caches outlines for a set of glyphs ahead of time, writing how many were newly added.

Parsing and instancing an outline is the expensive part of drawing a glyph the first time. Doing it up front keeps that cost off the frame that needs the glyph. It caches outlines, not rasterized bitmaps, so it helps at every size. Glyphs already cached are skipped, hence the count.

const uint8_t *daegun_blob_data(const daegun_blob *blob, size_t *out_count);

The bytes of a daegun_blob, borrowed, with the count written to out_count.

Raw bytes daegun assembled for you – an instanced table, or a built font file. The pointer dies with the handle, so copy it out if you need it to outlive one. NULL if either argument is NULL.

void daegun_blob_free(daegun_blob *blob);

Frees a daegun_blob. Any pointer obtained from it becomes invalid.

const double *daegun_f64_list_data(
    const daegun_f64_list *list,
    size_t *out_count
);

The elements of a daegun_f64_list, borrowed, with the count written to out_count.

Doubles on the 1000-unit em: advances, caret positions, ligature carets. The pointer dies with the handle, so copy it out if you need it to outlive one. NULL if either argument is NULL.

void daegun_f64_list_free(daegun_f64_list *list);

Frees a daegun_f64_list. Any pointer obtained from it becomes invalid.

const daegun_glyph_value *daegun_glyph_value_list_data(
    const daegun_glyph_value_list *list,
    size_t *out_count
);

The glyph and value pairs of a daegun_glyph_value_list, borrowed, with the count written to out_count.

Each entry pairs a glyph id with the value a table assigns it, in table order. The pointer dies with the handle, so copy it out if you need it to outlive one. NULL if either argument is NULL.

void daegun_glyph_value_list_free(daegun_glyph_value_list *list);

Frees a daegun_glyph_value_list. Any pointer obtained from it becomes invalid.

const int32_t *daegun_i32_list_data(
    const daegun_i32_list *list,
    size_t *out_count
);

The elements of a daegun_i32_list, borrowed, with the count written to out_count.

Signed 32-bit values, used for anything measured in whole font units. The pointer dies with the handle, so copy it out if you need it to outlive one. NULL if either argument is NULL.

void daegun_i32_list_free(daegun_i32_list *list);

Frees a daegun_i32_list. Any pointer obtained from it becomes invalid.

daegun_status daegun_str_list_at(
    const daegun_str_list *list,
    size_t index,
    daegun_str *out
);

DAEGUN_RANGE past the end, rather than an empty string – a font may hold an empty name and you must be able to tell the two apart.

daegun_status daegun_str_list_count(
    const daegun_str_list *list,
    size_t *out
);

How many strings a daegun_str_list holds, written to out.

Pair it with daegun_str_list_at to walk the list.

void daegun_str_list_free(daegun_str_list *list);

Frees a daegun_str_list.

Every string borrowed from it becomes invalid.

void daegun_text_free(daegun_text *text);

Frees a daegun_text. Any daegun_str taken from it becomes invalid.

daegun_status daegun_text_str(const daegun_text *text, daegun_str *out);

Borrows the string inside a daegun_text as a pointer and length.

The daegun_str points into the text object and is valid only until it is freed. The string is both NUL-terminated and length-carrying, so either convention works – but prefer the length, since a font's name table may contain an interior NUL.

const uint16_t *daegun_u16_list_data(
    const daegun_u16_list *list,
    size_t *out_count
);

The elements, borrowed. NULL if the list or the count pointer is NULL.

void daegun_u16_list_free(daegun_u16_list *list);

Frees a daegun_u16_list. Any pointer obtained from it becomes invalid.

const size_t *daegun_usize_list_data(
    const daegun_usize_list *list,
    size_t *out_count
);

The elements of a daegun_usize_list, borrowed, with the count written to out_count.

Sizes and offsets, such as the per-glyph positions the loca table stores. The pointer dies with the handle, so copy it out if you need it to outlive one. NULL if either argument is NULL.

void daegun_usize_list_free(daegun_usize_list *list);

Frees a daegun_usize_list. Any pointer obtained from it becomes invalid.

daegun_status daegun_hinted_outline_draw(
    const daegun_hinted_outline *outline,
    const daegun_pen *pen
);

Replays a hinted glyph onto a pen, converting F26Dot6 to whole pixels on the way. The other half of daegun_font_hinted_glyph: that one grid-fits, this turns the result back into geometry.

daegun_status daegun_path_as_pen(daegun_path *path, daegun_pen *out);

A pen that appends to this path – the other direction through daegun_pen, so a glyph outline can be captured as a value. BORROWS the path: valid until the path is freed.

daegun_status daegun_path_bounds(
    const daegun_path *path,
    double *out_min_x,
    double *out_min_y,
    double *out_max_x,
    double *out_max_y
);

DAEGUN_ABSENT when the path has no points.

daegun_status daegun_path_close(daegun_path *path);

Closes the current contour, joining its end back to its start.

Fill rules need closed contours to decide inside from outside, so close every contour you intend to fill.

daegun_status daegun_path_cost(const daegun_path *path, size_t *out);

What the path costs to fill, in the engine's own units – the number daegun_policy compares against to decide whether a glyph is worth a GPU round trip.

daegun_status daegun_path_curve_to(
    daegun_path *path,
    float c1x,
    float c1y,
    float c2x,
    float c2y,
    float x,
    float y
);

Adds a cubic Bézier through two control points.

The curve CFF and PostScript outlines use.

void daegun_path_free(daegun_path *path);

Frees a path.

daegun_status daegun_path_is_empty(const daegun_path *path, int32_t *out);

Whether the path holds no segments, written to out as 0 or 1.

A glyph with no ink – a space – produces an empty path, which is normal rather than an error.

daegun_status daegun_path_line_to(daegun_path *path, float x, float y);

Adds a straight segment from the current point to a new one.

daegun_status daegun_path_move_to(daegun_path *path, float x, float y);

Starts a new contour at a point, ending any contour in progress.

Coordinates are in whatever space you are working in; daegun does not impose one here.

daegun_path *daegun_path_new(void);

Creates an empty path, or NULL if allocation fails.

An owned handle: add verbs to it, use it, then free it with daegun_path_free. Check for NULL – unlike the fallible calls this returns the pointer directly and has no status to report through.

daegun_path *p = daegun_path_new();
if (!p) return 1;
daegun_path_move_to(p, 0.0f, 0.0f);
daegun_path_line_to(p, 100.0f, 0.0f);
daegun_path_close(p);
daegun_path_free(p);

daegun_status daegun_path_points(
    const daegun_path *path,
    float *out_x,
    float *out_y,
    size_t capacity,
    size_t *out_count
);

Copies a path's points into arrays you supply, writing how many there are.

A copy rather than a borrow, so you own the result. Pass capacity as the size of your arrays; out_count reports the true number of points, which may exceed it. Call once with a capacity of 0 to learn the count, then allocate and call again.

size_t n = 0;
daegun_path_points(path, NULL, NULL, 0, &n);      /* how many? */

float *xs = malloc(n * sizeof *xs), *ys = malloc(n * sizeof *ys);
daegun_path_points(path, xs, ys, n, &n);

daegun_status daegun_path_quad_to(
    daegun_path *path,
    float cx,
    float cy,
    float x,
    float y
);

Adds a quadratic Bézier through one control point.

The curve TrueType outlines are made of, and the only curve the GPU path takes, so a shape built from quadratics can be drawn either way.

daegun_status daegun_path_replay(
    const daegun_path *path,
    const double *transform,
    const daegun_pen *pen
);

Replays onto a pen, optionally through a 2x3 transform [a, b, c, d, e, f], or NULL for none.

daegun_status daegun_path_stroke(
    const daegun_path *path,
    const daegun_stroke_style *style,
    float tolerance,
    const daegun_pen *pen
);

tolerance is how far the flattened curves may sit from the true ones, in the path's units.

daegun_status daegun_path_stroke_simplified(
    const daegun_path *path,
    const daegun_stroke_style *style,
    float tolerance,
    const daegun_pen *pen
);

The same, with the outline's self-intersections resolved into one boundary – what a filler that does not do non-zero winding needs, since a stroke overlaps itself at every join.

daegun_status daegun_path_verbs(
    const daegun_path *path,
    uint8_t *out,
    size_t capacity,
    size_t *out_count
);

The verbs and points, COPIED into your buffers – the one place this ABI copies rather than borrowing. Call with capacity 0 to learn the count, then again to fill.

daegun_status daegun_scene_builder_fill(
    daegun_scene_builder *b,
    size_t path_id,
    const uint8_t rgba[4],
    int32_t rule,
    const double transform[6]
);

rgba is four bytes, transform six doubles [a, b, c, d, e, f] for x' = a*x + c*y + e. rule is DAEGUN_FILL_NONZERO or DAEGUN_FILL_EVENODD. DAEGUN_RANGE for an unknown path id, an unknown rule, or a transform that is not finite.

void daegun_scene_builder_free(daegun_scene_builder *b);

Frees a scene builder.

daegun_status daegun_scene_builder_is_empty(
    const daegun_scene_builder *b,
    bool *out
);

Reading a builder back. op_count is how many fills it holds; path hands back a copy of one you pushed, which you free with daegun_path_free.

daegun_scene_builder *daegun_scene_builder_new(void);

Creates a scene builder, for composing a drawing of your own rather than receiving one from a color glyph.

Push paths into it, add fills referring to them, then render. Free with daegun_scene_builder_free. Returns NULL if allocation fails, so check the pointer.

daegun_status daegun_scene_builder_op_count(
    const daegun_scene_builder *b,
    size_t *out
);

How many drawing operations a scene builder holds, written to out.

daegun_status daegun_scene_builder_path(
    const daegun_scene_builder *b,
    size_t path_id,
    daegun_path **out
);

One path from a scene builder by the id it was pushed under.

Returns DAEGUN_RANGE for an id the builder does not hold.

daegun_status daegun_scene_builder_push_path(
    daegun_scene_builder *b,
    const daegun_path *path,
    size_t *out_id
);

Copies the path in, so you may free or reuse yours immediately.

daegun_status daegun_scene_builder_render(
    const daegun_scene_builder *b,
    float px,
    float upem,
    daegun_scene **out
);

The canvas is fitted to the ink, so fill a full-bleed background first if you want a fixed size. Free the result with daegun_scene_free.

void daegun_bitmap_free(daegun_bitmap *bitmap);

Frees a bitmap. The pixel pointer taken from it becomes invalid.

daegun_status daegun_bitmap_metrics(
    const daegun_bitmap *bitmap,
    daegun_metrics *out
);

Where a rasterized bitmap sits and how big it is.

width and height are in pixels; xmin and ymin place the bitmap relative to the pen, in pixels, with y up. Rows in the pixel data run top to bottom.

daegun_metrics m;
daegun_bitmap_metrics(bmp, &m);
size_t len = 0;
const uint8_t *px = daegun_bitmap_pixels(bmp, &len);
/* m.width x m.height, one coverage byte each */

const uint8_t *daegun_bitmap_pixels(
    const daegun_bitmap *bitmap,
    size_t *out_len
);

The coverage, borrowed. One byte per pixel for grayscale, three for a subpixel layout – the LENGTH is what says which, so divide by width * height rather than tracking what you asked for.

daegun_status daegun_font_rasterize_glyph(
    const daegun_font *font,
    uint16_t gid,
    float px,
    const daegun_axis *axes,
    size_t axes_len,
    daegun_bitmap **out
);

DAEGUN_ABSENT for a glyph that draws nothing. A space rasterizes to no pixels, which is an answer rather than a failure.

daegun_status daegun_font_rasterize_glyph_with(
    const daegun_font *font,
    uint16_t gid,
    float px,
    const daegun_axis *axes,
    size_t axes_len,
    const daegun_raster_options *opts,
    daegun_bitmap **out
);

A NULL opts means the defaults, so you need not build the struct to get them.

daegun_status daegun_font_has_table(
    const daegun_font *font,
    const char *tag,
    int32_t *out
);

Whether the font contains a table with the given tag, written to out as 0 or 1.

Cheaper than fetching the table when you only want to know it is there – testing "glyf" against "CFF " to tell TrueType outlines from CFF ones, for instance. Tags are four characters, padded with spaces.

daegun_status daegun_font_instance_table(
    const daegun_font *font,
    const daegun_axis *axes,
    size_t axis_count,
    const char *tag,
    daegun_blob **out
);

One table of the font pinned to axes, copied. Free with daegun_blob_free.

daegun_status daegun_font_instance_tables(
    const daegun_font *font,
    const daegun_axis *axes,
    size_t axis_count,
    daegun_table_map **out
);

Every table of the font pinned to axes. DAEGUN_ABSENT only when a variable font's own variation tables do not parse. The bytes are COPIED out of the font. The Rust call borrows wherever a table passes through untouched, and that borrow cannot cross into C – nothing would stop the font being freed while the map still pointed into it. Use daegun_font_instance_table when only one table is wanted; it keeps the saving.

daegun_status daegun_font_table(
    const daegun_font *font,
    const char *tag,
    daegun_bytes *out
);

One table's bytes, exactly as the file stores them. BORROWED: valid until the font is freed. tag is the four-character name – "GSUB", "cmap", "OS/2" – including any trailing space, since "cvt " and "CFF " really are spelled that way. DAEGUN_ABSENT when the font has no such table, which is not the same as a table that is empty. These are the font's bytes, not an instance's: a variable font's glyf here is the stored default shape. daegun_font_instance_table is what resolves a location.

daegun_status daegun_font_table_tags(
    const daegun_font *font,
    daegun_str_list **out
);

Every table the font carries, in sorted order. Free with daegun_str_list_free.

daegun_status daegun_outline_glyf_bytes(
    const uint8_t *glyf,
    size_t glyf_len,
    const size_t *loca,
    size_t loca_len,
    uint16_t glyph,
    const daegun_pen *pen
);

Draws one glyph straight out of glyf bytes, composites resolved – the escape hatch for a table that did not come from a font this ABI opened.

daegun_status daegun_parse_loca(
    const uint8_t *loca,
    size_t len,
    int16_t format,
    size_t num_glyphs,
    daegun_usize_list **out
);

The offsets loca stores, one per glyph plus a terminator. format is head's indexToLocFormat: 0 for the short form, 1 for the long one. Free with daegun_usize_list_free.

daegun_status daegun_table_map_build(
    const daegun_table_map *map,
    daegun_blob **out
);

Assembles the map into an sfnt: the directory, the offsets, and the checksums. An empty map is DAEGUN_RANGE rather than a header describing nothing. Free with daegun_blob_free.

daegun_status daegun_table_map_bytes_at(
    const daegun_table_map *map,
    size_t index,
    daegun_bytes *out
);

One table's bytes by index, borrowed from the map.

Valid only until the map is freed. Index from 0 to the count minus one.

daegun_status daegun_table_map_count(
    const daegun_table_map *map,
    size_t *out
);

How many tables the map holds.

void daegun_table_map_free(daegun_table_map *map);

Frees a table map and everything added to it.

daegun_status daegun_table_map_get(
    const daegun_table_map *map,
    const char *tag,
    daegun_bytes *out
);

One table's bytes by tag, borrowed from the map.

Returns DAEGUN_ABSENT when the map holds no table with that tag.

daegun_table_map *daegun_table_map_new(void);

Creates an empty table map, for assembling a font file from tables of your own.

Returns NULL if allocation fails. Free with daegun_table_map_free.

daegun_status daegun_table_map_remove(
    daegun_table_map *map,
    const char *tag
);

Removes a table from a map by tag.

Returns DAEGUN_ABSENT when the map holds no table with that tag. Any bytes borrowed for that table become invalid.

daegun_status daegun_table_map_set(
    daegun_table_map *map,
    const char *tag,
    const uint8_t *data,
    size_t len
);

Copies the bytes.

daegun_status daegun_table_map_tag_at(
    const daegun_table_map *map,
    size_t index,
    daegun_str *out
);

BORROWED, and invalidated by _set and _remove as well as by _free.

daegun_status daegun_aat_lookup_entries(
    const daegun_aat_lookup *lookup,
    daegun_glyph_value_list **out
);

Every mapping. Free with daegun_glyph_value_list_free.

void daegun_aat_lookup_free(daegun_aat_lookup *lookup);

Frees an AAT lookup handle.

daegun_status daegun_aat_lookup_open(
    const uint8_t *data,
    size_t len,
    uint16_t num_glyphs,
    daegun_aat_lookup **out
);

Opens an Apple Advanced Typography lookup table for reading.

AAT lookups map glyph ids to values in one of several formats. num_glyphs bounds the lookup so a malformed table cannot claim entries beyond the font. Free with daegun_aat_lookup_free.

daegun_status daegun_aat_lookup_value(
    const daegun_aat_lookup *lookup,
    uint16_t glyph,
    uint16_t *out
);

DAEGUN_ABSENT when the lookup maps nothing to this glyph.

daegun_status daegun_aat_state_table_class(
    const daegun_aat_state_table *table,
    uint16_t glyph,
    uint16_t *out
);

Out-of-bounds glyphs get the table's own out-of-bounds class.

daegun_status daegun_aat_state_table_entry(
    const daegun_aat_state_table *table,
    uint16_t state,
    uint16_t class_,
    daegun_aat_entry *out
);

DAEGUN_RANGE when the table has no such cell.

void daegun_aat_state_table_free(daegun_aat_state_table *table);

Frees an Apple state machine table.

The state and entry arrays taken from it become invalid.

daegun_status daegun_aat_state_table_open(
    const uint8_t *data,
    size_t len,
    size_t extra_words,
    uint16_t num_glyphs,
    daegun_aat_state_table **out
);

extra_words is how many type-specific words each entry carries: none for rearrangement, one for ligature and contextual substitution.

daegun_status daegun_ankr_anchor_point(
    const daegun_ankr *ankr,
    uint16_t glyph,
    uint16_t index,
    int16_t *out_x,
    int16_t *out_y
);

DAEGUN_ABSENT when the glyph has no anchor at that index.

daegun_status daegun_ankr_control_point(
    const uint8_t *data,
    size_t len,
    size_t at,
    int16_t *out_x,
    int16_t *out_y
);

One control point read straight out of a buffer, without an ankr around it.

void daegun_ankr_free(daegun_ankr *ankr);

Frees an ankr handle.

Anchor points read from it become invalid.

daegun_status daegun_ankr_open(
    const uint8_t *data,
    size_t len,
    uint16_t num_glyphs,
    daegun_ankr **out
);

Opens an Apple ankr anchor point table for reading.

Anchor points are where marks attach in Apple's positioning model. num_glyphs bounds the table so a malformed one cannot claim entries beyond the font. Free with daegun_ankr_free.

daegun_status daegun_ankr_point_count(
    const daegun_ankr *ankr,
    uint16_t glyph,
    uint32_t *out
);

How many anchor points a glyph has in an ankr table.

Anchor points are where marks attach in Apple's positioning model.

daegun_status daegun_ankr_version(
    const uint8_t *data,
    size_t len,
    uint16_t *out
);

The version of an Apple ankr anchor point table.

Reads the version from raw bytes, bounds-checked, so a truncated table produces a refusal rather than a read past the end.

const uint8_t *daegun_bytes_window(
    const uint8_t *data,
    size_t len,
    size_t off,
    size_t n
);

n bytes at off, or NULL when they do not fit. BORROWS data. The Rust form is const-generic – window<4> – and C has no such thing, so the width is an argument; what survives is the point of it: one bounds check, and a pointer either good for n bytes or NULL.

daegun_status daegun_coverage_glyphs(
    const uint8_t *buf,
    size_t len,
    size_t off,
    daegun_u16_list **out
);

Every glyph a coverage table covers, in table order. Free with daegun_u16_list_free.

daegun_status daegun_coverage_index(
    const uint8_t *data,
    size_t len,
    uint16_t glyph,
    uint16_t *out
);