slug.h

#include <modkit/slug.h>10 functions · 5 structs · 1 enums · 6 typedefs

Curve-based glyph rendering (opt-in package).

An OPT-IN package (MODKIT_ENABLE_SLUG, default OFF, requires MODKIT_ENABLE_FONT). Slug stores each glyph's Bezier outlines in textures and evaluates coverage analytically in the fragment shader, instead of sampling a baked atlas. Text stays sharp at any magnification, and one copy of a glyph's data serves every size there is no per-size re-bake. Basic use treats Slug as just another font type: Measurement, shaping and layout are unchanged those come from FreeType and HarfBuzz, not from the rasterizer. When to reach for it: large text, text the user can zoom, text on a surface in 3D, or any case where the camera is not tightly controlled. When not to: small UI text, where hinted coverage looks better and Slug's per-pixel curve loop is pure cost. MK_FONT_AUTO deliberately never selects Slug. Limitations:COLRv0 and solid, transformed, source-over COLRv1 glyphs stay vector. Gradients, images, complex clips and other composites fall back to the colour atlas atomically. CBDT/sbix and bitmap-only faces also fall back.Slug has its own optical-weight, outline, shadow and glow effects. MTSDF effects remain specific to MK_FONT_SDF.Unavailable on the legacy GL 2.1 profile; mk_slug_is_supported() reports this, and fonts fall back to MTSDF. Algorithm by Eric Lengyel (JCGT 2017). The patent was dedicated to the public domain on March 17, 2026 and the reference shaders published under MIT; see licenses/slug-MIT.txt.

Functions

mk_slug_band_texturefunction

mk_texture_t mk_slug_band_texture(void)

Band headers and index lists (RG16U), bind at stage 1.

Returns The resulting handle or value.

mk_slug_build_geometryfunction

mk_result mk_slug_build_geometry(mk_font_t font, const char *text, float size_px, uint32_t color, mk_slug_vertex *out_vertices, uint16_t *out_indices, uint32_t max_glyphs, mk_slug_geometry *out_geometry)

Lay out a UTF-8 string as Slug quads without drawing anything.

The pen origin is (0, 0) with +x right and +y down, matching mk_text_build, so the caller applies its own transform. Glyphs are made resident as a side effect, which touches the GPU textures.

Parameter	Type	Description
font	mk_font_t	Font containing the glyphs
text	const char *	Null-terminated UTF-8 text
size_px	float	Font size in pixels
color	uint32_t	Packed glyph color
out_vertices	mk_slug_vertex *	Caller buffer, 4 per glyph.
out_indices	uint16_t *	Caller buffer, 6 per glyph.
max_glyphs	uint32_t	Capacity of both, in glyphs.
out_geometry	mk_slug_geometry *	Receives the generated geometry and texture handles

Returns MK_SUCCESS, or MK_ERROR_INVALID_ARGUMENT / MK_ERROR_UNSUPPORTED. Running out of capacity truncates and still returns MK_SUCCESS with the counts written.

mk_slug_curve_texturefunction

mk_texture_t mk_slug_curve_texture(void)

Curve control points (RGBA16F), bind at stage 0.

Returns The resulting handle or value.

mk_slug_draw_3dfunction

float mk_slug_draw_3d(mk_font_t font, const char *text, float size_px, uint32_t color, const float *model)

Draw text on a plane in 3D, with dilation.

A glyph quad sized exactly to its outline loses the partially covered pixels at its boundary once foreshortened. This path uses the dilating vertex shader, which pushes each corner outward by however much the current projection needs and shifts the sample coordinate to match, so the glyph stays put. That is what keeps Slug sharp under perspective where a distance-field atlas degrades. Text is laid out in the XY plane with +y down, one unit per size_px, and transformed by model. Call inside a pass with a view and projection set.

Parameter	Type	Description
font	mk_font_t	Font containing the glyphs
text	const char *	Null-terminated UTF-8 text
size_px	float	Font size in model units
color	uint32_t	Packed glyph color
model	const float *	4x4 column-major model matrix, or NULL for identity.

Returns Advance width in model units, or 0 on failure.

mk_slug_get_statsfunction

void mk_slug_get_stats(mk_slug_stats *out)

Read back the current counters.

Parameter	Type	Description
out	mk_slug_stats *	Value for out.

mk_slug_is_supportedfunction

bool mk_slug_is_supported(void)

Whether this renderer can run Slug at all.

False on the legacy GL 2.1 profile, and on any backend not reporting support for the integer band texture. Loading a font as MK_FONT_SLUG when this is false succeeds but renders through MTSDF.

Returns True when the condition holds.

mk_slug_mesh_desc_initfunction

mk_slug_mesh_desc mk_slug_mesh_desc_init(void)

Initialize the slug mesh desc.

Returns The resulting value.

mk_slug_set_paramsfunction

mk_result mk_slug_set_params(const mk_slug_params *params)

Apply build tuning.

Affects glyphs built after the call; glyphs already resident keep the settings they were built with. NULL restores defaults.

Parameter	Type	Description
params	const mk_slug_params *	Value for params.

Returns MK_SUCCESS or an error result.

mk_slug_text_mesh_createfunction

mk_result mk_slug_text_mesh_create(const mk_slug_mesh_desc *desc, mk_geometry_t *out_geometry)

Build and upload one shaped text mesh.

Color/bitmap glyphs and runs exceeding the 16-bit geometry index limit are rejected atomically. If the selected bevel profile would self-intersect, its width is reduced for that glyph before falling back to a plain extrusion. The caller owns a successful geometry handle and destroys it with mk_geometry_destroy().

Parameter	Type	Description
desc	const mk_slug_mesh_desc *	Configuration descriptor.
out_geometry	mk_geometry_t *	Receives the geometry.

Returns MK_SUCCESS or an error result.

mk_slug_vertex_layoutfunction

const mk_layout_t * mk_slug_vertex_layout(void)

Vertex layout matching mk_slug_vertex, for your own submission.

Returns A borrowed pointer, or NULL when unavailable.

Structs

mk_slug_geometrystruct

Result of mk_slug_build_geometry.

Field	Type	Description
vertices	mk_slug_vertex *	Points at the caller's buffer.
indices	uint16_t *	Points at the caller's buffer.
vertex_count	uint32_t	The vertex count.
index_count	uint32_t	The index count.
curve_texture	mk_texture_t	Bind at stage 0.
band_texture	mk_texture_t	Bind at stage 1.
width	float	Total advance, in size_px units.
skipped	uint32_t	Glyphs not resident, so not emitted.

mk_slug_mesh_descstruct

Shaped text converted to an ordinary reusable triangle mesh.

size_px is interpreted as model units. The baseline origin is (0,0,0), +X runs with the text, +Y is up, and the front face points toward +Z.

Field	Type	Description
font	mk_font_t	The font.
text	mk_text_shape_desc_t	String, size, and shaping controls.
depth	float	Front-to-back depth in model units.
bevel_width	float	Rounded edge width in model units.
bevel_segments	uint16_t	Rounded subdivisions, 0 disables bevel.
bevel_profile	mk_slug_bevel_profile_t	Inset or convex outset.
curve_tolerance	float	Flattening tolerance; 0 selects default.
face_color	uint32_t	Front/back color, 0xRRGGBBAA.
bevel_color	uint32_t	Bevel color, 0xRRGGBBAA.
side_color	uint32_t	Side-wall color, 0xRRGGBBAA.

mk_slug_paramsstruct

Build-time tuning.

Zero-init selects the defaults.

Field	Type	Description
cubic_tolerance	float	Allowed deviation, in em, when approximating a cubic with quadratics.
max_bands	uint16_t	Cap on bands per direction.
budget_bytes	uint64_t	Combined byte cap on the curve and band textures.

mk_slug_statsstruct

Runtime counters, for budgeting and for the example's HUD.

Field	Type	Description
glyphs	uint32_t	Glyphs resident in the curve/band textures.
fallback_color	uint32_t	Routed to the colour atlas instead.
fallback_bitmap	uint32_t	Routed to the bitmap path instead.
fallback_failed	uint32_t	Refused by the builder or over budget.
fallback_outline	uint32_t	The fallback outline.
gpu_bytes	uint64_t	Combined size of both textures.
budget_bytes	uint64_t	The budget bytes.

mk_slug_vertexstruct

One Slug quad corner.

Matches mk_slug_vertex_layout(): POSITION, TEXCOORD0 (em-space sample coordinate), TEXCOORD1 (band scale/offset), TEXCOORD2 (glyph data location and band maxima), COLOR0. band_* and glyph_* are constant across a quad and belong in flat varyings. They are plain floats rather than bit-packed integers because the bit-cast intrinsics are unavailable on GLSL ES 3.0; see docs/slug.md.

Field	Type	Description
x	float	Layout-space X position.
y	float	Layout-space Y position.
nx	float	Outward normal X component for 3D dilation.
ny	float	Outward normal Y component for 3D dilation.
u	float	Em-space sample U coordinate.
v	float	Em-space sample V coordinate.
band_scale_x	float	Horizontal band scale.
band_scale_y	float	Vertical band scale.
band_offset_x	float	Horizontal band offset.
band_offset_y	float	Vertical band offset.
glyph_x	float	Glyph location X in the band texture.
glyph_y	float	Glyph location Y in the band texture.
band_max_x	float	Maximum horizontal band coordinate.
band_max_y	float	Maximum vertical band coordinate.
jac_xx	float	Inverse Jacobian XX component.
jac_xy	float	Inverse Jacobian XY component.
jac_yx	float	Inverse Jacobian YX component.
jac_yy	float	Inverse Jacobian YY component.
abgr	uint32_t	The abgr.

Enums

mk_slug_bevel_profileenum

Values for slug bevel profile.

Value	Description
MK_SLUG_BEVEL_INSET	Face inset toward the original side wall.
MK_SLUG_BEVEL_OUTSET	Original face with a convex expanded edge.

Typedefs

mk_slug_bevel_profile_ttypedef

typedef enum mk_slug_bevel_profile mk_slug_bevel_profile_t

Values for slug bevel profile.

mk_slug_geometrytypedef

typedef struct mk_slug_geometry mk_slug_geometry

Result of mk_slug_build_geometry.

mk_slug_mesh_desctypedef

typedef struct mk_slug_mesh_desc mk_slug_mesh_desc

Shaped text converted to an ordinary reusable triangle mesh.

size_px is interpreted as model units. The baseline origin is (0,0,0), +X runs with the text, +Y is up, and the front face points toward +Z.

mk_slug_paramstypedef

typedef struct mk_slug_params mk_slug_params

Build-time tuning.

Zero-init selects the defaults.

mk_slug_statstypedef

typedef struct mk_slug_stats mk_slug_stats

Runtime counters, for budgeting and for the example's HUD.

mk_slug_vertextypedef

typedef struct mk_slug_vertex mk_slug_vertex

One Slug quad corner.

Matches mk_slug_vertex_layout(): POSITION, TEXCOORD0 (em-space sample coordinate), TEXCOORD1 (band scale/offset), TEXCOORD2 (glyph data location and band maxima), COLOR0. band_* and glyph_* are constant across a quad and belong in flat varyings. They are plain floats rather than bit-packed integers because the bit-cast intrinsics are unavailable on GLSL ES 3.0; see docs/slug.md.