DEFOLD
Home Features Showcase Learn Asset Portal Community Support API Free Download Donate  

Defold Learn logo

Defold Learn logo

Textlayout

API for laying out complex text into format ready for display

Include: #include <dmsdk/font/text_layout.h>
TYPES
FTextLayoutReleaseObject Release a resource acquired by FTextLayoutResolveObject
FTextLayoutResolveObject Resolve a resource-backed layout object
HTextLayout A handle representing a text layout
ENUMS
TextDecorationPattern Text decoration pattern
TextDirection An enum representing text layout directions
TextGlyphFlags Text glyph flags
TextLayoutType An enum representing text layout features Each fon...
TextResult An enum representing text layout results
STRUCTS
struct TextDecoration Resolved line decoration
struct TextGlyph Glyph representing the final position within a lay...
struct TextLayoutObject Object found while resolving markup for a layout
struct TextLayoutObjectAttribute Attribute belonging to a layout object
struct TextLayoutSettings Describes how to do a text layout
struct TextLine Represents a line of glyphs
struct TextParagraph Represents a paragraph of lines
FUNCTIONS
void TextLayoutAcquire (HTextLayout layout) Acquire a shared reference to a previously created...
TextResult TextLayoutCreate (HFontCollection collection, uint32_t* codepoints, uint32_t num_codepoints, TextLayoutSettings* settings, HTextLayout* layout) Create a text layout using a font collection if su...
float* TextLayoutGetBounds (HTextLayout layout) Get the lines in the layout
uint32_t TextLayoutGetDecorationCount (HTextLayout layout) Get resolved decoration count
const TextDecoration* TextLayoutGetDecorations (HTextLayout layout) Get resolved decorations
uint32_t TextLayoutGetGlyphCount (HTextLayout layout) Get the glyph count in the layout
TextGlyph* TextLayoutGetGlyphs (HTextLayout layout) Get the glyphs in the layout
uint32_t TextLayoutGetLineCount (HTextLayout layout) Get the line count in the layout
TextLine* TextLayoutGetLines (HTextLayout layout) Get the lines in the layout
const TextLayoutObjectAttribute* TextLayoutGetObjectAttributes (HTextLayout layout) Get layout object attributes
uint32_t TextLayoutGetObjectCount (HTextLayout layout) Get layout object count
uint8_t TextLayoutGetObjectPosition (HTextLayout layout, const TextLayoutObject* object, float paragraph_x, float paragraph_top, float paragraph_width, float* x, float* y) Get the rendered position of a layout object
const TextLayoutObject* TextLayoutGetObjects (HTextLayout layout) Get layout objects
const char* TextLayoutGetObjectSource (HTextLayout layout) Get the UTF-8 source referenced by layout object attributes
uint32_t TextLayoutGetParagraphCount (HTextLayout layout) Get the paragraph count in the layout
TextParagraph* TextLayoutGetParagraphs (HTextLayout layout) Get the paragraphs in the layout
void TextLayoutRelease (HTextLayout layout) Release a previously created layout
uint8_t TextLayoutSetObjectStyle (HTextLayout layout, uint64_t object_id, dmhash_t style) Set a layout object's named style override
void TextLayoutUpdate (HTextLayout layout, float delta_time) Advance the animation clock used by markup effects...

Functions

TextLayoutAcquire

void TextLayoutAcquire(HTextLayout layout)

Acquire a shared reference to a previously created layout

PARAMETERS

HTextLayout layout the text layout

TextLayoutCreate

TextResult TextLayoutCreate(HFontCollection collection, uint32_t* codepoints, uint32_t num_codepoints, TextLayoutSettings* settings, HTextLayout* layout)

Create a text layout using a font collection if successful, the caller owns the returned layout and must call TextLayoutRelease()

PARAMETERS

HFontCollection collection the font collection
uint32_t* codepoints an array of codepoints
uint32_t num_codepoints number of codepoints in the array
TextLayoutSettings* settings the settings used for rendering
HTextLayout* layout (out) the output text layout

RETURNS

TextResult the result. TEXT_RESULT_OK if successful

TextLayoutGetBounds

float* TextLayoutGetBounds(HTextLayout layout)

Get the lines in the layout

PARAMETERS

HTextLayout layout the text layout

RETURNS

float* the total width of the layout (out)
float* the total height of the layout (out)

TextLayoutGetDecorationCount

uint32_t TextLayoutGetDecorationCount(HTextLayout layout)

Get resolved decoration count

PARAMETERS

HTextLayout layout the text layout

RETURNS

uint32_t number of underline and strike segments

TextLayoutGetDecorations

const TextDecoration* TextLayoutGetDecorations(HTextLayout layout)

Get resolved decorations

PARAMETERS

HTextLayout layout the text layout

RETURNS

const TextDecoration* borrowed decoration array

TextLayoutGetGlyphCount

uint32_t TextLayoutGetGlyphCount(HTextLayout layout)

Get the glyph count in the layout

PARAMETERS

HTextLayout layout the text layout

RETURNS

uint32_t the number of glyphs in the layout

TextLayoutGetGlyphs

TextGlyph* TextLayoutGetGlyphs(HTextLayout layout)

Get the glyphs in the layout

PARAMETERS

HTextLayout layout the text layout

RETURNS

TextGlyph* the array of glyphs in the layout

TextLayoutGetLineCount

uint32_t TextLayoutGetLineCount(HTextLayout layout)

Get the line count in the layout

PARAMETERS

HTextLayout layout the text layout

RETURNS

uint32_t the number of lines in the layout

TextLayoutGetLines

TextLine* TextLayoutGetLines(HTextLayout layout)

Get the lines in the layout

PARAMETERS

HTextLayout layout the text layout

RETURNS

TextLine* the array of lines in the layout

TextLayoutGetObjectAttributes

const TextLayoutObjectAttribute* TextLayoutGetObjectAttributes(HTextLayout layout)

Get layout object attributes

PARAMETERS

HTextLayout layout the text layout

RETURNS

const TextLayoutObjectAttribute* attribute array

TextLayoutGetObjectCount

uint32_t TextLayoutGetObjectCount(HTextLayout layout)

Get layout object count

PARAMETERS

HTextLayout layout the text layout

RETURNS

uint32_t number of sprites and links

TextLayoutGetObjectPosition

uint8_t TextLayoutGetObjectPosition(HTextLayout layout, const TextLayoutObject* object, float paragraph_x, float paragraph_top, float paragraph_width, float* x, float* y)

Resolves the lower-left corner of an object using the same shaped-line coordinate normalization as text rendering. paragraph_x and paragraph_top define the upper-left layout origin. paragraph_width is used to place right-to-left lines.

PARAMETERS

HTextLayout layout the text layout
const TextLayoutObject* object object borrowed from TextLayoutGetObjects
float paragraph_x left layout origin
float paragraph_top top layout origin
float paragraph_width layout width
float* x resolved lower-left x coordinate (out)
float* y resolved lower-left y coordinate (out)

RETURNS

uint8_t non-zero when the object belongs to a layout line

TextLayoutGetObjects

const TextLayoutObject* TextLayoutGetObjects(HTextLayout layout)

The borrowed array remains valid until the layout is released.

PARAMETERS

HTextLayout layout the text layout

RETURNS

const TextLayoutObject* layout object array

TextLayoutGetObjectSource

const char* TextLayoutGetObjectSource(HTextLayout layout)

Get the UTF-8 source referenced by layout object attributes

PARAMETERS

HTextLayout layout the text layout

RETURNS

const char* null-terminated markup source copy

TextLayoutGetParagraphCount

uint32_t TextLayoutGetParagraphCount(HTextLayout layout)

Get the paragraph count in the layout

PARAMETERS

HTextLayout layout the text layout

RETURNS

uint32_t the number of paragraphs in the layout

TextLayoutGetParagraphs

TextParagraph* TextLayoutGetParagraphs(HTextLayout layout)

Get the paragraphs in the layout

PARAMETERS

HTextLayout layout the text layout

RETURNS

TextParagraph* the array of paragraphs in the layout

TextLayoutRelease

void TextLayoutRelease(HTextLayout layout)

Release a previously created layout

PARAMETERS

HTextLayout layout the text layout

TextLayoutSetObjectStyle

uint8_t TextLayoutSetObjectStyle(HTextLayout layout, uint64_t object_id, dmhash_t style)

The named style replaces the object's default render properties, effects, and decorations. The default is the markup style attribute when present, otherwise the object's tag name. Inline markup remains applied over the selected style. Pass zero to restore the default style. This affects rendering only and never reshapes or reflows text.

PARAMETERS

HTextLayout layout the text layout
uint64_t object_id ID returned in TextLayoutObject.m_Id
dmhash_t style named style hash, or zero to restore the default

RETURNS

uint8_t non-zero when the object style changed

TextLayoutUpdate

void TextLayoutUpdate(HTextLayout layout, float delta_time)

Advance the animation clock used by markup effects in a text layout. This function only changes the layout's accumulated effect time. It does not reshape text or alter the base glyph positions, lines, paragraphs, or bounds. Animated offsets are applied later when glyph vertices are generated. Call this once per frame with the elapsed time since the previous frame. Non-finite and non-positive values are ignored.

PARAMETERS

HTextLayout layout the text layout
float delta_time elapsed time in seconds

Structs

TextDecoration

TYPE

struct TextDecoration

Decorations contain backend-independent geometry after shaping, BiDi reordering, and line wrapping. m_Y is relative to the line baseline. The original underline or strike type is deliberately omitted because its font metrics have already been resolved into m_Y and m_Thickness.

MEMBERS

float m_X Start position in the shaped line coordinate system.
float m_Y Vertical offset from the line baseline.
float m_Length Decoration length.
float m_Thickness Resolved font-derived thickness.
float m_PatternOffset Stable pattern phase offset.
uint32_t m_GlyphStart First associated layout glyph.
uint16_t m_GlyphCount Number of associated layout glyphs.
uint16_t m_LineIndex Physical line containing the decoration.
TextDecorationPattern m_Pattern Line pattern.

TextGlyph

TYPE

struct TextGlyph

Glyph representing the final position within a layout

MEMBERS

HFont m_Font The font used for this glyph
float m_X the final x position, relative the top-left corner of the layout
float m_Y the final y position, relative the top-left corner of the layout
float m_Width the width of the glyph
float m_Height the height of the glyph
float m_RenderScale scale applied to the cached glyph geometry during vertex generation
uint32_t m_Codepoint original codepoint (if available)
uint16_t m_GlyphIndex the glyph index in the font
uint32_t m_Cluster the index in the visible UTF-32 text that this glyph corresponds to
uint16_t m_StyleIndex resolved render style index
uint16_t m_BaseStyleIndex render style before layout-object named styles are applied
uint16_t m_MarkupSpanIndex resolved markup span index, or 0xffff when no markup is present
uint16_t m_BaseMarkupSpanIndex markup span before layout-object named styles are applied
uint16_t m_Flags TextGlyphFlags describing non-text layout glyphs

TextLayoutObject

TYPE

struct TextLayoutObject

Sprite objects have resolved dimensions and an opaque value owned by the resolver. Their dimensions reserve inline layout space; rendering the sprite is the caller's responsibility. Link objects describe their visible UTF-32 text range and have zero dimensions until their geometry is queried.

MEMBERS

uintptr_t m_Resource Opaque resolver-owned resource value.
float m_Width Resolved object width in layout units.
float m_Height Resolved object height in layout units.
uint32_t m_TextOffset Zero-based UTF-32 offset in visible text.
uint32_t m_TextLength Visible UTF-32 length; one for an inline sprite's U+FFFC object-replacement codepoint.
uint64_t m_Id Stable object identifier derived from the id attribute, or generated from its order in the layout source.
uint16_t m_AttributeIndex First object attribute in the layout attribute array.
uint16_t m_AttributeCount Number of consecutive object attributes.
dmhash_t m_Tag Hash of the markup tag name.

TextLayoutObjectAttribute

TYPE

struct TextLayoutObjectAttribute

Offsets and lengths are UTF-8 byte ranges in the string returned by TextLayoutGetObjectSource().

MEMBERS

uint32_t m_NameOffset Attribute-name byte offset in the object source.
uint32_t m_ValueOffset Attribute-value byte offset in the object source.
uint16_t m_NameLength Attribute-name length in bytes; zero for shorthand values.
uint16_t m_ValueLength Attribute-value length in bytes.

TextLayoutSettings

TYPE

struct TextLayoutSettings

Describes how to do a text layout

MEMBERS

float m_Size The desired size of the font (in pixels)
float m_Width Max layout width. Used only when m_LineBreak is non-zero
float m_Leading The extra space between each line. Set 1.0f as default.
float m_Tracking The extra tracking between glyphs. Set 0 as default.
FTextLayoutResolveObject m_ResolveObject Resolver required when markup contains a sprite.
FTextLayoutReleaseObject m_ReleaseObject Optional finalizer for resources acquired by the resolver.
void* m_ObjectContext User context passed to both object callbacks.
uint32_t m_Padding Legacy: Padding for monospace, glyphbank fonts
dmhash_t m_BaseStyle Named base style; zero selects no style.
uint8_t:1 m_UseBaseStyle Use explicit base styling instead of legacy font layers, including when m_BaseStyle is zero.
uint8_t:1 m_LineBreak Allow line breaks
uint8_t:1 m_Monospace Legacy: Is the font a monospace font. Current: should be set on the font in the font collection!

TextLine

TYPE

struct TextLine

Represents a line of glyphs

MEMBERS

float m_Width Width of the line
uint16_t m_Index Index into the list of glyphs
uint16_t m_Length Number of glyphs to render
uint16_t m_ParagraphIndex Index of the paragraph containing the line
float m_Baseline Final baseline position measured from the bottom of the layout

TextParagraph

TYPE

struct TextParagraph

Represents a paragraph of lines

MEMBERS

uint32_t m_TextIndex Index into the source codepoints
uint32_t m_TextLength Number of source codepoints, excluding the paragraph separator
uint16_t m_LineIndex Index into the list of lines
uint16_t m_LineCount Number of lines in the paragraph
TextDirection m_Direction Base direction of the paragraph

Types

FTextLayoutReleaseObject

void FTextLayoutReleaseObject(void* context, const TextLayoutObject* object)

Called during the layout's final release for each resolved sprite. The callback may be null when the resolver never acquires resources.

PARAMETERS

void* context User context from TextLayoutSettings.m_ObjectContext.
const TextLayoutObject* object Sprite object whose resource should be released.

FTextLayoutResolveObject

uint8_t FTextLayoutResolveObject(void* context, const char* source, const TextLayoutObjectAttribute* attributes, float proposed_width, float proposed_height, TextLayoutObject* object)

Called once for every sprite, including cache misses. The proposed dimensions already include explicit markup dimensions; each unspecified dimension is one em. The callback must set object->m_Width and object->m_Height, and may store an acquired resource handle in object->m_Resource. Returning false aborts markup layout creation. source and attributes are borrowed and valid for the duration of the callback. Equivalent data can later be obtained from the created layout.

PARAMETERS

void* context User context from TextLayoutSettings.m_ObjectContext.
const char* source Null-terminated markup source owned by the layout being created.
const TextLayoutObjectAttribute* attributes Attribute array indexed by object->m_AttributeIndex.
float proposed_width Explicit markup width, or one em when omitted.
float proposed_height Explicit markup height, or one em when omitted.
TextLayoutObject* object Object to update with resolved dimensions and an optional resource.

RETURNS

uint8_t Non-zero on success; zero aborts layout creation.

HTextLayout

void HTextLayout()

A handle representing a text layout

PARAMETERS

Enums

TextDecorationPattern

Text decoration pattern

TEXT_DECORATION_PATTERN_SOLID A continuous decoration line.
TEXT_DECORATION_PATTERN_DASHED A dashed decoration line.

TextDirection

An enum representing text layout directions

TEXT_DIRECTION_LTR Left-to-right text direction
TEXT_DIRECTION_RTL Right-to-left text direction

TextGlyphFlags

Text glyph flags

TEXT_GLYPH_FLAG_OBJECT The glyph reserves inline layout space for a layout object and must not be rasterized as text.

TextLayoutType

An enum representing text layout features Each font supports a layout type The selected layout type it the minimum value of layout types

TEXT_LAYOUT_TYPE_LEGACY Legacy text shaping api
TEXT_LAYOUT_TYPE_FULL Full text shaping api

TextResult

An enum representing text layout results

TEXT_RESULT_OK
TEXT_RESULT_ERROR