Skip to content
modkitv0.2

font.h

#include <modkit/font.h>55 functions · 21 structs · 13 enums · 37 typedefs · 12 macros

Retained atlas-backed text rendering with FreeType and MTSDF.

Provides simple text rendering independent of NanoVG. Supports hinted grayscale coverage and multi-channel signed distance fields for scalable, stylized text. Usage: mk_font_t font = mk_font_load("fonts/Roboto.ttf", 24.0f, MK_FONT_BITMAP); mk_text_begin(encoder, view, width, height); mk_text_draw(font, 10, 30, "Hello World", 0, 0xFFFFFFFF, MK_TEXT_ALIGN_LEFT); mk_text_end(); mk_font_destroy(font);

Functions

mk_font_atlasfunction

mk_texture_t mk_font_atlas(mk_font_t font)

Get a font's first atlas page.

ParameterTypeDescription
fontmk_font_tValue for font.

Returns The resulting handle or value.

mk_font_atlas_pagefunction

bool mk_font_atlas_page(mk_font_t font, uint16_t page_index, mk_font_atlas_page_t *page)

Query one generation-checked atlas page.

ParameterTypeDescription
fontmk_font_tValue for font.
page_indexuint16_tValue for page index.
pagemk_font_atlas_page_t *Value for page.

Returns True when the operation succeeds.

mk_font_atlas_page_countfunction

uint16_t mk_font_atlas_page_count(mk_font_t font)

Number of live atlas pages owned by a font.

ParameterTypeDescription
fontmk_font_tValue for font.

Returns The resulting value.

mk_font_cache_get_statsfunction

void mk_font_cache_get_stats(mk_font_cache_stats_t *stats)

Query aggregate atlas/raster/upload counters.

ParameterTypeDescription
statsmk_font_cache_stats_t *Value for stats.

mk_font_cache_set_gpu_budgetfunction

void mk_font_cache_set_gpu_budget(uint64_t bytes)

Override the shared font-atlas GPU budget in bytes.

ParameterTypeDescription
bytesuint64_tValue for bytes.

mk_font_destroyfunction

void mk_font_destroy(mk_font_t font)

Destroy font and release resources.

ParameterTypeDescription
fontmk_font_tValue for font.

mk_font_get_metricsfunction

void mk_font_get_metrics(mk_font_t font, float size_px, mk_font_metrics_t *metrics)

Get font metrics at specified size.

ParameterTypeDescription
fontmk_font_tFont handle
size_pxfloatPixel size (0 = use default size from mk_font_load)
metricsmk_font_metrics_t *Output metrics (can be NULL)

mk_font_get_typefunction

mk_font_type_t mk_font_get_type(mk_font_t font)

Get font type (bitmap or SDF).

ParameterTypeDescription
fontmk_font_tValue for font.

Returns The resulting handle or value.

mk_font_initfunction

bool mk_font_init(void)

Initialize font rendering system.

Called automatically by mk_init().

Returns True when the operation succeeds.

mk_font_is_validfunction

bool mk_font_is_valid(mk_font_t font)

Check if font handle is valid.

ParameterTypeDescription
fontmk_font_tValue for font.

Returns True when the condition holds.

mk_font_loadfunction

mk_font_t mk_font_load(const char *path, float size_px, mk_font_type_t type)

Load font from file.

Supports TTF/OTF (TrueType/OpenType), BDF (Bitmap Distribution Format), and PSF (PC Screen Font) files. BDF/PSF fonts are loaded as MK_FONT_BITMAP regardless of the type parameter, with all 256 glyphs pre-populated.

ParameterTypeDescription
pathconst char *Path to .ttf, .otf, .bdf, or .psf file
size_pxfloatDefault pixel size for rendering (0 = native height for BDF/PSF)
typemk_font_type_tMK_FONT_BITMAP for crisp text, MK_FONT_SDF for scalable text

Returns Font handle or MK_FONT_INVALID on failure

mk_font_load_exfunction

mk_font_t mk_font_load_ex(const mk_font_load_desc_t *desc)

Load raw OpenType or cooked .mkfont input with explicit face/render options.

ParameterTypeDescription
descconst mk_font_load_desc_t *Configuration descriptor.

Returns The resulting handle or value.

mk_font_load_memfunction

mk_font_t mk_font_load_mem(const void *data, uint32_t size, float size_px, mk_font_type_t type)

Load font from memory.

Data is copied internally. Supports TTF/OTF, BDF, and PSF formats.

ParameterTypeDescription
dataconst void *Font file data (TTF/OTF/BDF/PSF)
sizeuint32_tSize of font data in bytes
size_pxfloatDefault pixel size for rendering (0 = native height for BDF/PSF)
typemk_font_type_tMK_FONT_BITMAP or MK_FONT_SDF

Returns Font handle or MK_FONT_INVALID on failure

mk_font_prewarmfunction

bool mk_font_prewarm(mk_font_t font, const char *text, float size_px, mk_font_render_policy_t policy)

Blocking glyph prewarm.

The UTF-8 text is shaped when shaping is enabled. GPU uploads are issued on the calling API thread before this function returns.

ParameterTypeDescription
fontmk_font_tValue for font.
textconst char *Value for text.
size_pxfloatValue for size px.
policymk_font_render_policy_tValue for policy.

Returns True when the operation succeeds.

mk_font_probefunction

mk_result mk_font_probe(const char *path, uint32_t face_index, mk_font_metadata_t *metadata)

Read basic metadata from one face without creating a renderable font.

ParameterTypeDescription
pathconst char *Value for path.
face_indexuint32_tValue for face index.
metadatamk_font_metadata_t *Value for metadata.

Returns MK_SUCCESS or an error result.

mk_font_probe_memfunction

mk_result mk_font_probe_mem(const void *data, uint32_t size, uint32_t face_index, mk_font_metadata_t *metadata)

Read basic metadata from an in-memory font or collection.

ParameterTypeDescription
dataconst void *Data buffer.
sizeuint32_tSize in bytes.
face_indexuint32_tValue for face index.
metadatamk_font_metadata_t *Value for metadata.

Returns MK_SUCCESS or an error result.

mk_font_shutdownfunction

void mk_font_shutdown(void)

Shutdown font rendering system and free all fonts.

Called automatically by mk_shutdown().

mk_system_font_catalog_generationfunction

uint64_t mk_system_font_catalog_generation(void)

Generation of the latest successful catalog snapshot.

Returns The resulting value.

mk_system_font_countfunction

uint32_t mk_system_font_count(void)

Query the latest successful installed-font snapshot.

Query the latest successful installed-font snapshot.

Returns The resulting value.

mk_system_font_face_atfunction

mk_system_font_face_t * mk_system_font_face_at(uint32_t index)

Return an owned face from the current snapshot.

ParameterTypeDescription
indexuint32_tZero-based index.

Returns A borrowed pointer, or NULL when unavailable.

mk_system_font_face_findfunction

mk_system_font_face_t * mk_system_font_face_find(const char *name)

Find system font face.

ParameterTypeDescription
nameconst char *Stable name.

Returns A borrowed pointer, or NULL when unavailable.

mk_system_font_face_get_infofunction

mk_result mk_system_font_face_get_info(const mk_system_font_face_t *face, mk_system_font_face_info_t *info)

Get info from the system font face.

ParameterTypeDescription
faceconst mk_system_font_face_t *Value for face.
infomk_system_font_face_info_t *Value for info.

Returns MK_SUCCESS or an error result.

mk_system_font_face_has_codepointfunction

bool mk_system_font_face_has_codepoint(const mk_system_font_face_t *face, uint32_t codepoint)

Test whether the system font face has codepoint.

ParameterTypeDescription
faceconst mk_system_font_face_t *Value for face.
codepointuint32_tValue for codepoint.

Returns True when the condition holds.

mk_system_font_face_info_initfunction

void mk_system_font_face_info_init(mk_system_font_face_info_t *info)

Initialize the system font face info.

ParameterTypeDescription
infomk_system_font_face_info_t *Value for info.

mk_system_font_face_is_validfunction

bool mk_system_font_face_is_valid(const mk_system_font_face_t *face)

Test whether the system font face is valid.

ParameterTypeDescription
faceconst mk_system_font_face_t *Value for face.

Returns True when the condition holds.

mk_system_font_face_load_asyncfunction

mk_result mk_system_font_face_load_async(mk_system_font_face_t *face, float size_px, mk_font_type_t type, mk_system_font_face_load_fn callback, void *user_data)

Load async for the system font face.

ParameterTypeDescription
facemk_system_font_face_t *Value for face.
size_pxfloatValue for size px.
typemk_font_type_tValue for type.
callbackmk_system_font_face_load_fnCompletion callback.
user_datavoid *Caller-provided context.

Returns MK_SUCCESS or an error result.

mk_system_font_face_queryfunction

uint32_t mk_system_font_face_query(const char *text, mk_system_font_face_t **matches, uint32_t capacity)

Query system font face.

ParameterTypeDescription
textconst char *Value for text.
matchesmk_system_font_face_t **Value for matches.
capacityuint32_tValue for capacity.

Returns The resulting value.

mk_system_font_face_releasefunction

void mk_system_font_face_release(mk_system_font_face_t *face)

Release system font face.

ParameterTypeDescription
facemk_system_font_face_t *Value for face.

mk_system_font_face_retainfunction

mk_system_font_face_t * mk_system_font_face_retain(mk_system_font_face_t *face)

Retain system font face.

ParameterTypeDescription
facemk_system_font_face_t *Value for face.

Returns A borrowed pointer, or NULL when unavailable.

mk_system_font_fallback_desc_initfunction

void mk_system_font_fallback_desc_init(mk_system_font_fallback_desc_t *desc)

Initialize the system font fallback desc.

ParameterTypeDescription
descmk_system_font_fallback_desc_t *Configuration descriptor.

mk_system_font_fallbacksfunction

uint32_t mk_system_font_fallbacks(const mk_system_font_fallback_desc_t *desc, mk_system_font_face_t **faces, uint32_t capacity)

Perform the system font fallbacks operation.

ParameterTypeDescription
descconst mk_system_font_fallback_desc_t *Configuration descriptor.
facesmk_system_font_face_t **Value for faces.
capacityuint32_tValue for capacity.

Returns The resulting value.

mk_system_font_findfunction

int32_t mk_system_font_find(const char *family_or_postscript_name)

Find a face by PostScript/full name, or the closest regular face in a family.

Returns -1 when no face matches. Find a face by PostScript/full name, or the closest regular face in a family.

ParameterTypeDescription
family_or_postscript_nameconst char *Value for family or postscript name.

Returns The resulting value.

mk_system_font_infofunction

mk_result mk_system_font_info(uint32_t index, mk_font_metadata_t *metadata)

Perform the system font info operation.

ParameterTypeDescription
indexuint32_tZero-based index.
metadatamk_font_metadata_t *Value for metadata.

Returns MK_SUCCESS or an error result.

mk_system_font_load_asyncfunction

mk_result mk_system_font_load_async(uint32_t index, float size_px, mk_font_type_t type, mk_system_font_load_fn callback, void *user_data)

Load one face from the current snapshot, completing on a later frame.

Load one face from the current snapshot, completing on a later frame.

ParameterTypeDescription
indexuint32_tZero-based index.
size_pxfloatValue for size px.
typemk_font_type_tValue for type.
callbackmk_system_font_load_fnCompletion callback.
user_datavoid *Caller-provided context.

Returns MK_SUCCESS or an error result.

mk_system_font_matchfunction

mk_result mk_system_font_match(const mk_system_font_match_desc_t *desc, mk_system_font_face_t **face)

Perform the system font match operation.

ParameterTypeDescription
descconst mk_system_font_match_desc_t *Configuration descriptor.
facemk_system_font_face_t **Value for face.

Returns MK_SUCCESS or an error result.

mk_system_font_match_desc_initfunction

void mk_system_font_match_desc_init(mk_system_font_match_desc_t *desc)

Initialize the system font match desc.

ParameterTypeDescription
descmk_system_font_match_desc_t *Configuration descriptor.

mk_system_font_queryfunction

uint32_t mk_system_font_query(const char *text, uint32_t *matches, uint32_t capacity)

Query faces whose family, style, full name, or PostScript name contains text.

Matching is case-insensitive. Writes up to capacity catalog indices to matches and returns the total match count; matches may be NULL to count only. Query faces whose family, style, full name, or PostScript name contains text.

ParameterTypeDescription
textconst char *Value for text.
matchesuint32_t *Value for matches.
capacityuint32_tValue for capacity.

Returns The resulting value.

mk_system_fonts_refreshfunction

mk_result mk_system_fonts_refresh(mk_system_fonts_fn callback, void *user_data)

Refresh the installed-font snapshot.

Completion runs on a later main-loop frame. Only one refresh may be in flight at a time.

ParameterTypeDescription
callbackmk_system_fonts_fnCompletion callback.
user_datavoid *Caller-provided context.

Returns MK_SUCCESS or an error result.

mk_system_fonts_supportedfunction

bool mk_system_fonts_supported(void)

True when this platform can expose locally installed fonts.

Returns True when the condition holds.

mk_textfunction

float mk_text(mk_font_t font, float x, float y, const char *text, uint32_t color)

Draw text at position with default alignment (left, baseline).

ParameterTypeDescription
fontmk_font_tValue for font.
xfloatValue for x.
yfloatValue for y.
textconst char *Value for text.
coloruint32_tValue for color.

Returns The resulting value.

mk_text_beginfunction

void mk_text_begin(mk_encoder_t encoder, mk_view_id_t view, uint16_t width, uint16_t height)

Begin text drawing mode.

Sets up orthographic projection for 2D text rendering. Must be called before mk_text_draw(). This compatibility entry point assumes a 1:1 logical-to-framebuffer scale. Use mk_text_begin_ex() for HiDPI windows and other scaled targets.

ParameterTypeDescription
encodermk_encoder_tEncoder to submit draw calls to
viewmk_view_id_tView ID to render to
widthuint16_tLogical viewport width in pixels
heightuint16_tLogical viewport height in pixels

mk_text_begin_exfunction

bool mk_text_begin_ex(const mk_text_begin_desc *desc)

Begin text drawing with independent logical and framebuffer dimensions.

Text positions remain in logical pixels while raster selection and effects use the projected framebuffer density.

ParameterTypeDescription
descconst mk_text_begin_desc *Configuration descriptor.

Returns true when the context was begun, false for invalid parameters

mk_text_buildfunction

uint32_t mk_text_build(mk_font_t font, const char *text, float size_px, mk_glyph_quad *out_quads, uint32_t max_quads, mk_text_geometry *out_geom)

Lay out a string into glyph quads (does not draw anything).

Walks the UTF-8 string, rasterizing/caching glyphs into the font atlas, and writes one mk_glyph_quad per visible glyph into the caller-provided buffer. The quads are in layout space with the pen origin at (0,0); apply your own model/ortho transform when you submit them. Bitmap/SDF fonts only (the NanoVG path has no exposed geometry — use mk_text_draw_styled for that). Newly rasterized glyphs are uploaded before the frame's draw submissions and can be used immediately.

ParameterTypeDescription
fontmk_font_tFont (MK_FONT_BITMAP or MK_FONT_SDF)
textconst char *UTF-8 string
size_pxfloatPixel size to lay out at
out_quadsmk_glyph_quad *Caller buffer to fill
max_quadsuint32_tCapacity of out_quads
out_geommk_text_geometry *Filled with {quads=out_quads, count, atlas, width, height}

Returns Number of glyph quads written (== out_geom->count)

mk_text_build_batchesfunction

mk_text_build_error_t mk_text_build_batches(mk_font_t font, const char *text, float size_px, mk_glyph_quad *out_quads, uint32_t max_quads, mk_text_geometry_batch_t *out_batches, uint16_t max_batches, mk_text_batch_geometry_t *out_geom)

Batch-aware geometry builder for text spanning multiple atlas pages.

Batches reference consecutive ranges in out_quads and expose page metadata.

ParameterTypeDescription
fontmk_font_tValue for font.
textconst char *Value for text.
size_pxfloatValue for size px.
out_quadsmk_glyph_quad *Receives the quads.
max_quadsuint32_tValue for max quads.
out_batchesmk_text_geometry_batch_t *Receives the batches.
max_batchesuint16_tValue for max batches.
out_geommk_text_batch_geometry_t *Receives the geom.

Returns The resulting handle or value.

mk_text_drawfunction

float mk_text_draw(mk_font_t font, float x, float y, const char *text, float size_px, uint32_t color, int align)

Draw text with simple parameters.

ParameterTypeDescription
fontmk_font_tFont handle
xfloatX position
yfloatY position
textconst char *UTF-8 text string
size_pxfloatPixel size (0 = use font default)
coloruint32_tText color (0xRRGGBBAA)
alignintAlignment flags (MK_TEXT_ALIGN_*)

Returns Horizontal advance to next text position

mk_text_draw_boxfunction

float mk_text_draw_box(mk_font_t font, float x, float y, float max_width, float max_height, const char *text, float size_px, const mk_text_style_t *style, int align)

Draw text within a bounding box with automatic word wrap.

ParameterTypeDescription
fontmk_font_tFont handle
xfloatX position of box left edge
yfloatY position of box top edge
max_widthfloatMaximum box width (0 = no limit)
max_heightfloatMaximum box height (0 = no limit, text may be clipped)
textconst char *UTF-8 text string
size_pxfloatPixel size (0 = use font default)
styleconst mk_text_style_t *Text style with color and effects
alignintAlignment flags (horizontal alignment applies within box)

Returns Total height of rendered text

mk_text_draw_nfunction

float mk_text_draw_n(mk_font_t font, float x, float y, const char *text, size_t len, float size_px, uint32_t color, int align)

Draw text with length limit.

ParameterTypeDescription
fontmk_font_tFont handle
xfloatX position
yfloatY position
textconst char *UTF-8 text string
lensize_tMaximum bytes to render (or 0 for entire string)
size_pxfloatPixel size (0 = use font default)
coloruint32_tText color (0xRRGGBBAA)
alignintAlignment flags

Returns Horizontal advance

mk_text_draw_styledfunction

float mk_text_draw_styled(mk_font_t font, float x, float y, const char *text, float size_px, const mk_text_style_t *style, int align)

Draw text with full styling (for SDF effects).

ParameterTypeDescription
fontmk_font_tFont handle
xfloatX position
yfloatY position
textconst char *UTF-8 text string
size_pxfloatPixel size (0 = use font default)
styleconst mk_text_style_t *Text style with color and effects
alignintAlignment flags

Returns Horizontal advance

mk_text_draw_styled_nfunction

float mk_text_draw_styled_n(mk_font_t font, float x, float y, const char *text, size_t len, float size_px, const mk_text_style_t *style, int align)

Draw a length-delimited styled UTF-8 slice.

ParameterTypeDescription
fontmk_font_tValue for font.
xfloatValue for x.
yfloatValue for y.
textconst char *Value for text.
lensize_tValue for len.
size_pxfloatValue for size px.
styleconst mk_text_style_t *Value for style.
alignintValue for align.

Returns The resulting value.

mk_text_endfunction

void mk_text_end(void)

End text drawing mode and flush all pending text.

mk_text_measurefunction

float mk_text_measure(mk_font_t font, const char *text, float size_px, mk_text_bounds_t *bounds)

Measure text bounds without rendering.

ParameterTypeDescription
fontmk_font_tFont handle
textconst char *UTF-8 text string
size_pxfloatPixel size (0 = use default)
boundsmk_text_bounds_t *Output bounding box (can be NULL)

Returns Horizontal advance (width of text)

mk_text_measure_boxfunction

float mk_text_measure_box(mk_font_t font, const char *text, float size_px, float max_width, float line_height_scale, mk_text_bounds_t *bounds)

Measure text box dimensions with word wrap.

ParameterTypeDescription
fontmk_font_tFont handle
textconst char *UTF-8 text string
size_pxfloatPixel size (0 = use font default)
max_widthfloatMaximum width for wrapping (0 = no limit)
line_height_scalefloatLine height multiplier (1.0 = default)
boundsmk_text_bounds_t *Output bounding box (can be NULL)

Returns Total height of text box

mk_text_measure_nfunction

float mk_text_measure_n(mk_font_t font, const char *text, size_t len, float size_px, mk_text_bounds_t *bounds)

Measure text bounds with length limit.

ParameterTypeDescription
fontmk_font_tFont handle
textconst char *UTF-8 text string
lensize_tMaximum bytes to measure (or 0 for entire string)
size_pxfloatPixel size (0 = use default)
boundsmk_text_bounds_t *Output bounding box (can be NULL)

Returns Horizontal advance

mk_text_measure_styled_nfunction

float mk_text_measure_styled_n(mk_font_t font, const char *text, size_t len, float size_px, const mk_text_style_t *style, mk_text_bounds_t *bounds)

Measure a length-delimited styled UTF-8 slice.

Letter spacing from style is included in the returned advance.

ParameterTypeDescription
fontmk_font_tValue for font.
textconst char *Value for text.
lensize_tValue for len.
size_pxfloatValue for size px.
styleconst mk_text_style_t *Value for style.
boundsmk_text_bounds_t *Value for bounds.

Returns The resulting value.

mk_text_sizefunction

float mk_text_size(mk_font_t font, float x, float y, const char *text, float size_px, uint32_t color)

Draw text at position with specified size.

ParameterTypeDescription
fontmk_font_tValue for font.
xfloatValue for x.
yfloatValue for y.
textconst char *Value for text.
size_pxfloatValue for size px.
coloruint32_tValue for color.

Returns The resulting value.

Structs

mk_font_atlas_pagestruct

Data for font atlas page.

FieldTypeDescription
texturemk_texture_tThe texture.
formatmk_texture_format_tThe format.
raster_kindmk_font_raster_kind_tThe raster kind.
distance_rangefloatThe distance range.
generationuint32_tThe generation.
widthuint16_tThe width.
heightuint16_tThe height.

mk_font_axis_valuestruct

Data for font axis value.

FieldTypeDescription
taguint32_tFour-byte OpenType tag in big-endian byte order.
valuefloatDesign-space axis coordinate.

mk_font_cache_statsstruct

Data for font cache stats.

FieldTypeDescription
rasterizationsuint32_tThe rasterizations.
uploadsuint32_tThe uploads.
pagesuint32_tThe pages.
evictionsuint32_tThe evictions.
gpu_bytesuint64_tThe GPU bytes.
gpu_budgetuint64_tThe GPU budget.

mk_font_load_descstruct

Extended font load descriptor.

Set either path or data/data_size. Raw OpenType and cooked .mkfont input are detected from content magic.

FieldTypeDescription
pathconst char *The path.
dataconst void *The data.
data_sizeuint32_tThe data size.
size_pxfloatThe size px.
typemk_font_type_tThe type.
face_indexuint32_tThe face index.
paletteuint16_tThe palette.
color_modemk_font_color_mode_tThe color mode.
render_policymk_font_render_policy_tThe render policy.
hintingmk_font_hinting_tThe hinting.
axesconst mk_font_axis_value_t *The axes.
axis_countuint16_tThe axis count.

mk_font_metadatastruct

Portable metadata for one face in an outline-font file or system catalog.

FieldTypeDescription
familycharThe family.
stylecharThe style.
full_namecharThe full name.
postscript_namecharThe postscript name.
weightuint16_tOpenType weight, 1..1000; zero if unknown.
width_classuint8_tOpenType width class, 1..9; zero if unknown.
face_indexuint32_tThe face index.
flagsuint32_tmk_font_metadata_flags_t bits.

mk_font_metricsstruct

Font vertical metrics.

FieldTypeDescription
ascenderfloatDistance from baseline to top of tallest glyph.
descenderfloatDistance from baseline to bottom (negative).
line_heightfloatRecommended line spacing.
underline_positionfloatStroke center from baseline; below is negative.
underline_thicknessfloatRecommended underline thickness.
strikethrough_positionfloatStroke center from baseline; above is positive.
strikethrough_thicknessfloatRecommended strikethrough thickness.

mk_font_tstruct

Data for font.

FieldTypeDescription
idxuint16_tThe idx.

mk_glyph_quadstruct

One laid-out glyph: a position rect (layout space, pen origin at 0,0, +x right, +y down) and its atlas UV rect (normalized).

FieldTypeDescription
x0floatLeft edge in layout space.
y0floatTop edge in layout space.
x1floatRight edge in layout space.
y1floatBottom edge in layout space.
u0floatLeft atlas coordinate, normalized to 0..1.
v0floatTop atlas coordinate, normalized to 0..1.
u1floatRight atlas coordinate, normalized to 0..1.
v1floatBottom atlas coordinate, normalized to 0..1.

mk_system_font_face_infostruct

Data for system font face info.

FieldTypeDescription
struct_sizeuint32_tThe struct size.
struct_versionuint32_tThe struct version.
metadatamk_font_metadata_tThe metadata.
local_pathconst char *The local path.
catalog_generationuint64_tThe catalog generation.

mk_system_font_fallback_descstruct

Data for system font fallback desc.

FieldTypeDescription
struct_sizeuint32_tThe struct size.
struct_versionuint32_tThe struct version.
textconst char *The text.
text_lengthsize_tThe text length.
stylemk_system_font_match_desc_tThe style.

mk_system_font_match_descstruct

Data for system font match desc.

FieldTypeDescription
struct_sizeuint32_tThe struct size.
struct_versionuint32_tThe struct version.
familyconst char *The family.
generic_familymk_system_font_generic_family_tThe generic family.
weightuint16_tThe weight.
width_classuint8_tThe width class.
italicboolThe italic.
italic_setboolThe italic set.
localeconst char *The locale.

mk_text_batch_geometrystruct

Data for text batch geometry.

FieldTypeDescription
quadsmk_glyph_quad *The quads.
countuint32_tThe count.
batchesmk_text_geometry_batch_t *The batches.
batch_countuint16_tThe batch count.
widthfloatThe width.
heightfloatThe height.
errormk_text_build_error_tThe error.

mk_text_begin_descstruct

Extended begin parameters with independent logical and physical sizes.

FieldTypeDescription
encodermk_encoder_tThe encoder.
viewmk_view_id_tThe view.
logical_widthuint16_tThe logical width.
logical_heightuint16_tThe logical height.
framebuffer_widthuint16_tThe framebuffer width.
framebuffer_heightuint16_tThe framebuffer height.

mk_text_boundsstruct

Text bounding box.

FieldTypeDescription
min_xfloatLeft edge of the bounding box.
min_yfloatTop edge of the bounding box.
max_xfloatRight edge of the bounding box.
max_yfloatBottom edge of the bounding box.

mk_text_effectsstruct

Tagged rasterizer-specific effects.

Zero-init means "no effects".

FieldTypeDescription
kindmk_text_effects_kind_tThe kind.
uunion mk_text_effects::@133072235115173253031100010240227140303205024371The u.
u.mtsdfmk_text_effects_mtsdf_tValid iff kind == MK_TEXT_EFFECTS_MTSDF.
u.slugmk_text_effects_slug_tValid iff kind == MK_TEXT_EFFECTS_SLUG.

mk_text_effects_mtsdfstruct

Distance-field effects.

Require MTSDF rendering: they work with MK_FONT_SDF and cause MK_FONT_AUTO fonts to select MTSDF.

FieldTypeDescription
outline_widthfloatOutline width in pixels (0 = no outline).
outline_coloruint32_tOutline color (0xRRGGBBAA).
shadow_offset_xfloatDrop shadow X offset in pixels.
shadow_offset_yfloatDrop shadow Y offset in pixels.
shadow_coloruint32_tShadow color (0xRRGGBBAA).
shadow_softnessfloatShadow blur amount (0 = sharp, 1 = very soft).
glow_sizefloatGlow radius in pixels (0 = no glow).
glow_coloruint32_tGlow color (0xRRGGBBAA).

mk_text_effects_slugstruct

Analytical effects for MK_FONT_SLUG.

Dimensions are logical pixels.

FieldTypeDescription
optical_weightfloat0 = original, 1 = strongest edge-coverage boost
outline_widthfloatThe outline width.
outline_coloruint32_tThe outline color.
outline_modemk_slug_outline_mode_tThe outline mode.
shadow_offset_xfloatThe shadow offset x.
shadow_offset_yfloatThe shadow offset y.
shadow_coloruint32_tThe shadow color.
shadow_softnessfloatClamped to [0,1].
glow_sizefloatThe glow size.
glow_coloruint32_tThe glow color.

mk_text_fillstruct

Text fill.

Linear endpoints are normalized against the untransformed run bounds, so (0,0) is its top-left and (1,1) is its bottom-right.

FieldTypeDescription
kindmk_text_fill_kind_tThe kind.
linearstruct mk_text_fill::@075220143346001235335115226143361043130366304364The linear.
linear.x0floatNormalized start X coordinate.
linear.y0floatNormalized start Y coordinate.
linear.x1floatNormalized end X coordinate.
linear.y1floatNormalized end Y coordinate.
linear.color0uint32_tThe color0.
linear.color1uint32_tThe color1.

mk_text_geometrystruct

Result of mk_text_build: the quads + the atlas to sample + measured bounds.

FieldTypeDescription
quadsmk_glyph_quad *Points at the caller's buffer.
countuint32_tNumber of visible glyph quads written.
atlasmk_texture_tOne R8 coverage or RGBA8 MTSDF/color page.
page_indexuint16_tThe page index.
page_generationuint32_tThe page generation.
raster_kindmk_font_raster_kind_tThe raster kind.
distance_rangefloatThe distance range.
widthfloatTotal advance width (size_px units).
heightfloatLine height (size_px units).
errorint32_tmk_text_build_error_t

mk_text_geometry_batchstruct

Data for text geometry batch.

FieldTypeDescription
first_quaduint32_tThe first quad.
quad_countuint32_tThe quad count.
pagemk_font_atlas_page_tThe page.

mk_text_stylestruct

Text style: colour and formatting shared by every rasterizer, plus optional rasterizer-specific effects.

FieldTypeDescription
coloruint32_tText color (0xRRGGBBAA).
letter_spacingfloatAdditional space between shaped clusters (pixels).
line_height_scalefloatLine height multiplier (1.0 = default).
background_coloruint32_tBackground highlight color (0 = none).
horizontal_scalefloatHorizontal text scale.
vertical_scalefloatBaseline-relative vertical glyph scale.
baseline_shiftfloatPositive values raise the baseline in logical pixels.
skew_xfloatBaseline-relative horizontal shear.
decorationsuint32_tBitwise mk_text_decoration_flags values.
fillmk_text_fill_tThe fill.
effectsmk_text_effects_tRasterizer-specific effects; ignored by rasterizers that cannot apply them (a mismatch is logged once, and the text draws unstyled).

Enums

mk_font_color_modeenum

Color-glyph selection is fixed per font handle because it participates in atlas and Slug glyph residency.

ValueDescription
MK_FONT_COLOR_AUTOUse color tables when the font has them.
MK_FONT_COLOR_MONOCHROMERender a tintable monochrome glyph.

mk_font_hintingenum

Values for font hinting.

ValueDescription
MK_FONT_HINTING_DEFAULTSelects default.
MK_FONT_HINTING_NONESelects none.
MK_FONT_HINTING_LIGHTSelects light.
MK_FONT_HINTING_FULLSelects full.

mk_font_metadata_flagsenum

Values for font metadata flags.

ValueDescription
MK_FONT_METADATA_ITALICSelects italic.
MK_FONT_METADATA_MONOSPACESelects monospace.
MK_FONT_METADATA_VARIABLESelects variable.
MK_FONT_METADATA_COLORSelects color.

mk_font_raster_kindenum

Values for font raster kind.

ValueDescription
MK_FONT_RASTER_COVERAGESelects coverage.
MK_FONT_RASTER_MTSDFSelects mtsdf.
MK_FONT_RASTER_COLORSelects color.

mk_font_render_policyenum

Raster policy precedence for outline fonts: prebuilt/MK_FONT_BITMAP fonts use coverage, an explicit render policy comes next, MK_FONT_SDF uses MTSDF, and MK_FONT_AUTO selects by device size.

ValueDescription
MK_FONT_RENDER_DEFAULTUse the default implied by the font type.
MK_FONT_RENDER_COVERAGEForce coverage for scalable outline fonts.
MK_FONT_RENDER_MTSDFForce MTSDF for scalable outline fonts.
MK_FONT_RENDER_AUTOChoose from projected device-pixel size.

mk_font_typeenum

Font rendering type.

ValueDescription
MK_FONT_BITMAPStandard bitmap rendering (crisp at target size).
MK_FONT_SDFMTSDF RGBA8 (scalable, supports effects).
MK_FONT_NANOVGNanoVG vector rendering (anti-aliased, good quality).
MK_FONT_AUTOCoverage for small screen text, MTSDF otherwise.
MK_FONT_SLUGCurve-based, resolution-independent (modkit/slug.h).

mk_slug_outline_modeenum

Values for slug outline mode.

ValueDescription
MK_SLUG_OUTLINE_SAMPLEDSelects sampled.
MK_SLUG_OUTLINE_GEOMETRICSelects geometric.

mk_system_font_generic_familyenum

Values for system font generic family.

ValueDescription
MK_SYSTEM_FONT_GENERIC_NONESelects none.
MK_SYSTEM_FONT_GENERIC_SYSTEM_UISelects system UI.
MK_SYSTEM_FONT_GENERIC_SANSSelects sans.
MK_SYSTEM_FONT_GENERIC_SERIFSelects serif.
MK_SYSTEM_FONT_GENERIC_MONOSPACESelects monospace.
MK_SYSTEM_FONT_GENERIC_EMOJISelects emoji.

mk_text_alignenum

Text alignment flags.

Combine one horizontal and one vertical flag.

ValueDescription
MK_TEXT_ALIGN_LEFTAlign text to the left.
MK_TEXT_ALIGN_CENTERCenter text horizontally.
MK_TEXT_ALIGN_RIGHTAlign text to the right.
MK_TEXT_ALIGN_TOPAlign text to the top.
MK_TEXT_ALIGN_MIDDLECenter text vertically.
MK_TEXT_ALIGN_BOTTOMAlign text to the bottom.
MK_TEXT_ALIGN_BASELINEAlign text to the baseline (default).

mk_text_build_errorenum

Values for text build error.

ValueDescription
MK_TEXT_BUILD_OKSelects ok.
MK_TEXT_BUILD_INVALID_ARGUMENTSelects invalid argument.
MK_TEXT_BUILD_MULTIPLE_PAGESSelects multiple pages.
MK_TEXT_BUILD_CAPACITYSelects capacity.

mk_text_decoration_flagsenum

Values for text decoration flags.

ValueDescription
MK_TEXT_DECORATION_NONESelects none.
MK_TEXT_DECORATION_UNDERLINESelects underline.
MK_TEXT_DECORATION_STRIKETHROUGHSelects strikethrough.

mk_text_effects_kindenum

Which rasterizer's effects an mk_text_effects_t carries.

Effects are rasterizer-specific: MTSDF uses signed-distance thresholds, while Slug resamples analytical coverage. Tagging them keeps a mismatch detectable instead of silently rendering the wrong thing.

ValueDescription
MK_TEXT_EFFECTS_NONENo effects; colour and formatting only.
MK_TEXT_EFFECTS_MTSDFDistance-field effects; needs MTSDF raster.
MK_TEXT_EFFECTS_SLUGAnalytical Slug coverage effects.

mk_text_fill_kindenum

Values for text fill kind.

ValueDescription
MK_TEXT_FILL_SOLIDSelects solid.
MK_TEXT_FILL_LINEARSelects linear.

Typedefs

mk_font_atlas_page_ttypedef

typedef struct mk_font_atlas_page mk_font_atlas_page_t

Data for font atlas page.

mk_font_axis_value_ttypedef

typedef struct mk_font_axis_value mk_font_axis_value_t

Data for font axis value.

mk_font_cache_stats_ttypedef

typedef struct mk_font_cache_stats mk_font_cache_stats_t

Data for font cache stats.

mk_font_color_mode_ttypedef

typedef enum mk_font_color_mode mk_font_color_mode_t

Color-glyph selection is fixed per font handle because it participates in atlas and Slug glyph residency.

mk_font_hinting_ttypedef

typedef enum mk_font_hinting mk_font_hinting_t

Values for font hinting.

mk_font_load_desc_ttypedef

typedef struct mk_font_load_desc mk_font_load_desc_t

Extended font load descriptor.

Set either path or data/data_size. Raw OpenType and cooked .mkfont input are detected from content magic.

mk_font_metadata_flags_ttypedef

typedef enum mk_font_metadata_flags mk_font_metadata_flags_t

Values for font metadata flags.

mk_font_metadata_ttypedef

typedef struct mk_font_metadata mk_font_metadata_t

Portable metadata for one face in an outline-font file or system catalog.

mk_font_metrics_ttypedef

typedef struct mk_font_metrics mk_font_metrics_t

Font vertical metrics.

mk_font_raster_kind_ttypedef

typedef enum mk_font_raster_kind mk_font_raster_kind_t

Values for font raster kind.

mk_font_render_policy_ttypedef

typedef enum mk_font_render_policy mk_font_render_policy_t

Raster policy precedence for outline fonts: prebuilt/MK_FONT_BITMAP fonts use coverage, an explicit render policy comes next, MK_FONT_SDF uses MTSDF, and MK_FONT_AUTO selects by device size.

mk_font_type_ttypedef

typedef enum mk_font_type mk_font_type_t

Font rendering type.

mk_glyph_quadtypedef

typedef struct mk_glyph_quad mk_glyph_quad

One laid-out glyph: a position rect (layout space, pen origin at 0,0, +x right, +y down) and its atlas UV rect (normalized).

mk_slug_outline_mode_ttypedef

typedef enum mk_slug_outline_mode mk_slug_outline_mode_t

Values for slug outline mode.

mk_system_font_face_info_ttypedef

typedef struct mk_system_font_face_info mk_system_font_face_info_t

Data for system font face info.

mk_system_font_face_load_fntypedef

typedef void(*) mk_system_font_face_load_fn(mk_result result, mk_font_t font, void *user_data)

Callback used for system font face load.

mk_system_font_face_ttypedef

typedef struct mk_system_font_face_s mk_system_font_face_t

Type used for system font face.

mk_system_font_fallback_desc_ttypedef

typedef struct mk_system_font_fallback_desc mk_system_font_fallback_desc_t

Data for system font fallback desc.

mk_system_font_generic_family_ttypedef

typedef enum mk_system_font_generic_family mk_system_font_generic_family_t

Values for system font generic family.

mk_system_font_load_fntypedef

typedef void(*) mk_system_font_load_fn(mk_result result, mk_font_t font, void *user_data)

Callback used for system font load.

mk_system_font_match_desc_ttypedef

typedef struct mk_system_font_match_desc mk_system_font_match_desc_t

Data for system font match desc.

mk_system_fonts_fntypedef

typedef void(*) mk_system_fonts_fn(mk_result result, uint32_t count, void *user_data)

Callback used for system fonts.

mk_text_align_ttypedef

typedef enum mk_text_align mk_text_align_t

Text alignment flags.

Combine one horizontal and one vertical flag.

mk_text_batch_geometry_ttypedef

typedef struct mk_text_batch_geometry mk_text_batch_geometry_t

Data for text batch geometry.

mk_text_begin_desctypedef

typedef struct mk_text_begin_desc mk_text_begin_desc

Extended begin parameters with independent logical and physical sizes.

mk_text_bounds_ttypedef

typedef struct mk_text_bounds mk_text_bounds_t

Text bounding box.

mk_text_build_error_ttypedef

typedef enum mk_text_build_error mk_text_build_error_t

Values for text build error.

mk_text_decoration_flags_ttypedef

typedef enum mk_text_decoration_flags mk_text_decoration_flags_t

Values for text decoration flags.

mk_text_effects_kind_ttypedef

typedef enum mk_text_effects_kind mk_text_effects_kind_t

Which rasterizer's effects an mk_text_effects_t carries.

Effects are rasterizer-specific: MTSDF uses signed-distance thresholds, while Slug resamples analytical coverage. Tagging them keeps a mismatch detectable instead of silently rendering the wrong thing.

mk_text_effects_mtsdf_ttypedef

typedef struct mk_text_effects_mtsdf mk_text_effects_mtsdf_t

Distance-field effects.

Require MTSDF rendering: they work with MK_FONT_SDF and cause MK_FONT_AUTO fonts to select MTSDF.

mk_text_effects_slug_ttypedef

typedef struct mk_text_effects_slug mk_text_effects_slug_t

Analytical effects for MK_FONT_SLUG.

Dimensions are logical pixels.

mk_text_effects_ttypedef

typedef struct mk_text_effects mk_text_effects_t

Tagged rasterizer-specific effects.

Zero-init means "no effects".

mk_text_fill_kind_ttypedef

typedef enum mk_text_fill_kind mk_text_fill_kind_t

Values for text fill kind.

mk_text_fill_ttypedef

typedef struct mk_text_fill mk_text_fill_t

Text fill.

Linear endpoints are normalized against the untransformed run bounds, so (0,0) is its top-left and (1,1) is its bottom-right.

mk_text_geometrytypedef

typedef struct mk_text_geometry mk_text_geometry

Result of mk_text_build: the quads + the atlas to sample + measured bounds.

mk_text_geometry_batch_ttypedef

typedef struct mk_text_geometry_batch mk_text_geometry_batch_t

Data for text geometry batch.

mk_text_style_ttypedef

typedef struct mk_text_style mk_text_style_t

Text style: colour and formatting shared by every rasterizer, plus optional rasterizer-specific effects.

Macros

MK_FONT_FAMILY_NAME_MAXdefine

MK_FONT_FAMILY_NAME_MAX

Maximum supported font family name max.

MK_FONT_FULL_NAME_MAXdefine

MK_FONT_FULL_NAME_MAX

Maximum supported font full name max.

MK_FONT_INVALIDdefine

MK_FONT_INVALID

Invalid sentinel for font.

MK_FONT_POSTSCRIPT_NAME_MAXdefine

MK_FONT_POSTSCRIPT_NAME_MAX

Maximum supported font postscript name max.

MK_FONT_STYLE_NAME_MAXdefine

MK_FONT_STYLE_NAME_MAX

Maximum supported font style name max.

MK_SYSTEM_FONT_FACE_INFO_VERSIONdefine

MK_SYSTEM_FONT_FACE_INFO_VERSION

ABI or format version for system font face info.

MK_SYSTEM_FONT_FALLBACK_DESC_VERSIONdefine

MK_SYSTEM_FONT_FALLBACK_DESC_VERSION

ABI or format version for system font fallback desc.

MK_SYSTEM_FONT_MATCH_DESC_VERSIONdefine

MK_SYSTEM_FONT_MATCH_DESC_VERSION

ABI or format version for system font match desc.

MK_TEXT_ALIGN_DEFAULTdefine

MK_TEXT_ALIGN_DEFAULT

Constant for text align default.

MK_TEXT_EFFECTS_MTSDF_DEFAULTdefine

MK_TEXT_EFFECTS_MTSDF_DEFAULT

MTSDF effects preset: sensible colours, all effects switched off.

Enable one by setting its width/size, e.g.

mk_text_style_t style = MK_TEXT_STYLE_DEFAULT;
style.effects = MK_TEXT_EFFECTS_MTSDF_DEFAULT;
style.effects.u.mtsdf.outline_width = 2.0f;

MK_TEXT_EFFECTS_SLUG_DEFAULTdefine

MK_TEXT_EFFECTS_SLUG_DEFAULT

Slug effects preset with every effect switched off.

MK_TEXT_STYLE_DEFAULTdefine

MK_TEXT_STYLE_DEFAULT

Default text style: white text with no effects.