text_layout.h

#include <modkit/text_layout.h>21 functions · 11 structs · 4 enums · 15 typedefs · 2 macros

Retained multilingual paragraph layout.

This package is available when MODKIT_HAS_SHAPING is enabled. Layouts own a copy of their UTF-8 text and style spans. Drawing scale is deliberately separate from layout size so zooming does not reshape or rewrap text.

Functions

mk_font_family_countfunction

uint16_t mk_font_family_count(mk_font_family_t family)

Perform the font family count operation.

Parameter	Type	Description
family	mk_font_family_t	Value for family.

Returns The resulting value.

mk_font_family_createfunction

mk_font_family_t mk_font_family_create(const mk_font_t *fonts, uint16_t font_count)

Create font family.

Parameter	Type	Description
fonts	const mk_font_t *	Value for fonts.
font_count	uint16_t	Number of font entries.

Returns The resulting handle or value.

mk_font_family_destroyfunction

void mk_font_family_destroy(mk_font_family_t family)

Destroy the font family.

Parameter	Type	Description
family	mk_font_family_t	Value for family.

mk_font_family_fontfunction

mk_font_t mk_font_family_font(mk_font_family_t family, uint16_t index)

Perform the font family font operation.

Parameter	Type	Description
family	mk_font_family_t	Value for family.
index	uint16_t	Zero-based index.

Returns The resulting handle or value.

mk_font_family_is_validfunction

bool mk_font_family_is_valid(mk_font_family_t family)

Test whether the font family is valid.

Parameter	Type	Description
family	mk_font_family_t	Value for family.

Returns True when the condition holds.

mk_font_family_updatefunction

bool mk_font_family_update(mk_font_family_t family, const mk_font_t *fonts, uint16_t font_count)

Update font family.

Parameter	Type	Description
family	mk_font_family_t	Value for family.
fonts	const mk_font_t *	Value for fonts.
font_count	uint16_t	Number of font entries.

Returns True when the operation succeeds.

mk_text_layout_cache_get_statsfunction

void mk_text_layout_cache_get_stats(mk_text_layout_cache_stats_t *stats)

Get stats from the text layout cache.

Parameter	Type	Description
stats	mk_text_layout_cache_stats_t *	Value for stats.

mk_text_layout_cache_reset_statsfunction

void mk_text_layout_cache_reset_stats(void)

Reset the stats for the text layout cache.

mk_text_layout_caret_rectfunction

bool mk_text_layout_caret_rect(mk_text_layout_t layout, uint32_t byte_offset, mk_text_caret_affinity_t affinity, mk_text_rect_t *rect)

Perform the text layout caret rect operation.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.
byte_offset	uint32_t	Value for byte offset.
affinity	mk_text_caret_affinity_t	Value for affinity.
rect	mk_text_rect_t *	Value for rect.

Returns True when the operation succeeds.

mk_text_layout_composition_rectsfunction

uint32_t mk_text_layout_composition_rects(mk_text_layout_t layout, uint32_t byte_start, uint32_t byte_end, float thickness, mk_text_rect_t *rects, uint32_t max_rects)

Return underline rectangles for an IME composition byte range.

The range is snapped to grapheme-safe caret stops.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.
byte_start	uint32_t	Value for byte start.
byte_end	uint32_t	Value for byte end.
thickness	float	Value for thickness.
rects	mk_text_rect_t *	Value for rects.
max_rects	uint32_t	Value for max rects.

Returns The resulting value.

mk_text_layout_createfunction

mk_text_layout_t mk_text_layout_create(const mk_text_layout_desc_t *desc)

Create text layout.

Parameter	Type	Description
desc	const mk_text_layout_desc_t *	Configuration descriptor.

Returns The resulting handle or value.

mk_text_layout_destroyfunction

void mk_text_layout_destroy(mk_text_layout_t layout)

Destroy the text layout.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.

mk_text_layout_drawfunction

void mk_text_layout_draw(mk_text_layout_t layout, float x, float y, float scale)

Draw inside mk_text_begin()/mk_text_end() without changing layout metrics.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.
x	float	Value for x.
y	float	Value for y.
scale	float	Value for scale.

mk_text_layout_get_intrinsicsfunction

bool mk_text_layout_get_intrinsics(mk_text_layout_t layout, mk_text_layout_intrinsics_t *intrinsics)

Query shaped intrinsic widths for an existing layout.

Hard line breaks are honored; the current width, height, and overflow constraints are ignored.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.
intrinsics	mk_text_layout_intrinsics_t *	Value for intrinsics.

Returns True when the operation succeeds.

mk_text_layout_get_linefunction

bool mk_text_layout_get_line(mk_text_layout_t layout, uint32_t line_index, mk_text_line_metrics_t *line)

Get line from the text layout.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.
line_index	uint32_t	Value for line index.
line	mk_text_line_metrics_t *	Value for line.

Returns True when the operation succeeds.

mk_text_layout_get_metricsfunction

bool mk_text_layout_get_metrics(mk_text_layout_t layout, mk_text_layout_metrics_t *metrics)

Get metrics from the text layout.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.
metrics	mk_text_layout_metrics_t *	Value for metrics.

Returns True when the operation succeeds.

mk_text_layout_hit_testfunction

bool mk_text_layout_hit_test(mk_text_layout_t layout, float x, float y, mk_text_hit_t *hit)

Perform the text layout hit test operation.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.
x	float	Value for x.
y	float	Value for y.
hit	mk_text_hit_t *	Value for hit.

Returns True when the operation succeeds.

mk_text_layout_is_validfunction

bool mk_text_layout_is_valid(mk_text_layout_t layout)

Test whether the text layout is valid.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.

Returns True when the condition holds.

mk_text_layout_preparefunction

bool mk_text_layout_prepare(mk_text_layout_t layout, uint32_t budget_us)

Prepare shaping and raster data.

budget_us is a soft interactive budget; zero requests blocking preparation suitable for loading screens. A budgeted call returns true when preparation is complete and false when the caller should continue it on a later frame.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.
budget_us	uint32_t	Value for budget us.

Returns True when the operation succeeds.

mk_text_layout_selection_rectsfunction

uint32_t mk_text_layout_selection_rects(mk_text_layout_t layout, uint32_t byte_start, uint32_t byte_end, mk_text_rect_t *rects, uint32_t max_rects)

Perform the text layout selection rects operation.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.
byte_start	uint32_t	Value for byte start.
byte_end	uint32_t	Value for byte end.
rects	mk_text_rect_t *	Value for rects.
max_rects	uint32_t	Value for max rects.

Returns The resulting value.

mk_text_layout_updatefunction

bool mk_text_layout_update(mk_text_layout_t layout, const mk_text_layout_desc_t *desc)

Atomically replace layout content.

Parameter	Type	Description
layout	mk_text_layout_t	Value for layout.
desc	const mk_text_layout_desc_t *	Configuration descriptor.

Returns True when the operation succeeds.

Structs

mk_font_familystruct

Data for font family.

Field	Type	Description
idx	uint16_t	The idx.
generation	uint16_t	The generation.

mk_text_hitstruct

Data for text hit.

Field	Type	Description
byte_offset	uint32_t	The byte offset.
line_index	uint32_t	The line index.
affinity	mk_text_caret_affinity_t	The affinity.
trailing	bool	The trailing.

mk_text_layoutstruct

Data for text layout.

Field	Type	Description
idx	uint16_t	The idx.
generation	uint16_t	The generation.

mk_text_layout_cache_statsstruct

Data for text layout cache stats.

Field	Type	Description
shaping_hits	uint64_t	The shaping hits.
shaping_misses	uint64_t	The shaping misses.
layout_hits	uint64_t	The layout hits.
layout_misses	uint64_t	The layout misses.
rasterizations	uint64_t	The rasterizations.
uploads	uint64_t	The uploads.
pages	uint64_t	The pages.
atlas_bytes	uint64_t	The atlas bytes.
evictions	uint64_t	The evictions.
draw_batches	uint64_t	The draw batches.

mk_text_layout_descstruct

Data for text layout desc.

Field	Type	Description
text	const char *	The text.
text_len	size_t	The text len.
default_style	mk_text_span_style_t	The default style.
spans	const mk_text_style_span_t *	The spans.
span_count	uint32_t	The span count.
width	float	The width.
height	float	The height.
max_lines	uint32_t	The max lines.
wrap	mk_text_wrap_t	The wrap.
overflow	mk_text_overflow_t	The overflow.
align	mk_text_paragraph_align_t	The align.
direction	mk_text_direction_t	The direction.
locale	const char *	The locale.
line_height	float	The line height.
tab_width	float	The tab width.

mk_text_layout_intrinsicsstruct

Widths derived from shaped text before applying a soft width constraint.

Field	Type	Description
min_width	float	The min width.
preferred_width	float	The preferred width.

mk_text_layout_metricsstruct

Data for text layout metrics.

Field	Type	Description
width	float	The width.
height	float	The height.
content_width	float	The content width.
content_height	float	The content height.
line_count	uint32_t	The line count.
glyph_count	uint32_t	The glyph count.
source_bytes	uint32_t	The source bytes.
draw_batches	uint32_t	The draw batches.
truncated	bool	The truncated.

mk_text_line_metricsstruct

Data for text line metrics.

Field	Type	Description
byte_start	uint32_t	The byte start.
byte_end	uint32_t	The byte end.
x	float	The x.
baseline_y	float	The baseline y.
width	float	The width.
ascender	float	The ascender.
descender	float	The descender.

mk_text_rectstruct

Data for text rect.

Field	Type	Description
x	float	The x.
y	float	The y.
width	float	The width.
height	float	The height.
byte_start	uint32_t	The byte start.
byte_end	uint32_t	The byte end.

mk_text_span_stylestruct

Data for text span style.

Field	Type	Description
family	mk_font_family_t	The family.
size_px	float	The size px.
paint	mk_text_style_t	The paint.
features	const mk_text_feature_t *	The features.
feature_count	uint16_t	The feature count.
axes	const mk_font_axis_value_t *	The axes.
axis_count	uint16_t	The axis count.
background_color	uint32_t	The background color.
underline	bool	The underline.
strike_through	bool	The strike through.

mk_text_style_spanstruct

Data for text style span.

Field	Type	Description
byte_start	uint32_t	The byte start.
byte_end	uint32_t	The byte end.
style	mk_text_span_style_t	The style.

Enums

mk_text_caret_affinityenum

Values for text caret affinity.

Value	Description
MK_TEXT_AFFINITY_UPSTREAM	Selects upstream.
MK_TEXT_AFFINITY_DOWNSTREAM	Selects downstream.

mk_text_overflowenum

Values for text overflow.

Value	Description
MK_TEXT_OVERFLOW_VISIBLE	Selects visible.
MK_TEXT_OVERFLOW_CLIP	Selects clip.
MK_TEXT_OVERFLOW_ELLIPSIS	Selects ellipsis.

mk_text_paragraph_alignenum

Values for text paragraph align.

Value	Description
MK_TEXT_PARAGRAPH_START	Selects start.
MK_TEXT_PARAGRAPH_CENTER	Selects center.
MK_TEXT_PARAGRAPH_END	Selects end.
MK_TEXT_PARAGRAPH_JUSTIFY	Selects justify.

mk_text_wrapenum

Values for text wrap.

Value	Description
MK_TEXT_WRAP_NONE	Selects none.
MK_TEXT_WRAP_WORD	Selects word.
MK_TEXT_WRAP_GRAPHEME	Selects grapheme.

Typedefs

mk_font_family_ttypedef

typedef struct mk_font_family mk_font_family_t

Data for font family.

mk_text_caret_affinity_ttypedef

typedef enum mk_text_caret_affinity mk_text_caret_affinity_t

Values for text caret affinity.

mk_text_hit_ttypedef

typedef struct mk_text_hit mk_text_hit_t

Data for text hit.

mk_text_layout_cache_stats_ttypedef

typedef struct mk_text_layout_cache_stats mk_text_layout_cache_stats_t

Data for text layout cache stats.

mk_text_layout_desc_ttypedef

typedef struct mk_text_layout_desc mk_text_layout_desc_t

Data for text layout desc.

mk_text_layout_intrinsics_ttypedef

typedef struct mk_text_layout_intrinsics mk_text_layout_intrinsics_t

Widths derived from shaped text before applying a soft width constraint.

mk_text_layout_metrics_ttypedef

typedef struct mk_text_layout_metrics mk_text_layout_metrics_t

Data for text layout metrics.

mk_text_layout_ttypedef

typedef struct mk_text_layout mk_text_layout_t

Data for text layout.

mk_text_line_metrics_ttypedef

typedef struct mk_text_line_metrics mk_text_line_metrics_t

Data for text line metrics.

mk_text_overflow_ttypedef

typedef enum mk_text_overflow mk_text_overflow_t

Values for text overflow.

mk_text_paragraph_align_ttypedef

typedef enum mk_text_paragraph_align mk_text_paragraph_align_t

Values for text paragraph align.

mk_text_rect_ttypedef

typedef struct mk_text_rect mk_text_rect_t

Data for text rect.

mk_text_span_style_ttypedef

typedef struct mk_text_span_style mk_text_span_style_t

Data for text span style.

mk_text_style_span_ttypedef

typedef struct mk_text_style_span mk_text_style_span_t

Data for text style span.

mk_text_wrap_ttypedef

typedef enum mk_text_wrap mk_text_wrap_t

Values for text wrap.

Macros

MK_FONT_FAMILY_INVALIDdefine

MK_FONT_FAMILY_INVALID

Invalid sentinel for font family.

MK_TEXT_LAYOUT_INVALIDdefine

MK_TEXT_LAYOUT_INVALID

Invalid sentinel for text layout.