API reference (Font Generation) | Defold 1.14.1 (Beta)

Font generation

Asynchronously generates glyphs and hands them to a caller-owned cache. Glyph insertion and completion callbacks run on the job context owner, or on the caller of FontGenUpdateGlyphs for a batch started with FontGenStartGlyphs. Cache lookup runs while preparing the batch. The caller context must remain valid until the completion callback has run or the job has been cancelled.


Namespace:	`FontGeneration`
Include:	`#include <engine/font/src/fontgen.h>`

TYPES
FFontGenAddGlyph	Inserts a generated glyph into the caller-owned cache.
FFontGenComplete	Reports completion of a glyph generation batch.
FFontGenIsGlyphCached	Looks up a glyph in the caller-owned cache.

STRUCTS
struct FontGenParams	Runtime glyph generation parameters.

FUNCTIONS
FontGenJobData* FontGenCreateJobData (FontGenParams* params, uint32_t num_glyphs)	Allocates scratch data for one generation batch.
void FontGenDestroyJobData (FontGenJobData* jobdata)	Releases a generation batch and its untransferred glyphs.
bool FontGenIsSupported ()	Tests whether runtime glyph generation is linked into the engine.
bool FontGenStartGlyphs (FontGenJobData* jobdata, ::TextGlyph* glyphs, uint32_t num_glyphs)	Starts a batch whose results are consumed by its caller.
bool FontGenUpdateGlyphs (FontGenJobData* jobdata, uint64_t time_limit)	Consumes results for a batch started with FontGenStartGlyphs.

Functions

FontGenCreateJobData

FontGenJobData* FontGenCreateJobData(FontGenParams* params, uint32_t num_glyphs)

Allocates scratch data for one generation batch.

PARAMETERS

`FontGenParams*`	`params`	Generation settings and callbacks. The values are copied.
`uint32_t`	`num_glyphs`	Maximum number of glyphs in the batch.

RETURNS

FontGenJobData* Job data, or null when unsupported.

FontGenDestroyJobData

void FontGenDestroyJobData(FontGenJobData* jobdata)

Batches started with FontGenStartGlyphs cancel and wait for their own jobs. Other batches must already have finished or been canceled by the caller.

PARAMETERS

FontGenJobData* jobdata Batch to release.

FontGenIsSupported

bool FontGenIsSupported()

Tests whether runtime glyph generation is linked into the engine.

PARAMETERS

RETURNS

bool True when the full font_gen library is linked.

FontGenStartGlyphs

bool FontGenStartGlyphs(FontGenJobData* jobdata, ::TextGlyph* glyphs, uint32_t num_glyphs)

Worker jobs generate glyphs without invoking callbacks. Call FontGenUpdateGlyphs on the resource's creation thread to install the results. That update can take over queued glyphs, including when the caller occupies the last worker. With no workers it generates all glyphs. The job context must outlive the batch.

PARAMETERS

`FontGenJobData*`	`jobdata`	Fresh batch; keep alive until completion or destruction.
`::TextGlyph*`	`glyphs`	Input glyphs, copied during this call.
`uint32_t`	`num_glyphs`	Number of input glyphs.

RETURNS

bool False when runtime generation is unsupported.

FontGenUpdateGlyphs

bool FontGenUpdateGlyphs(FontGenJobData* jobdata, uint64_t time_limit)

Generates queued glyphs or consumes finished results without dispatching other jobs or callbacks. Running jobs keep ownership until they finish. The completion callback may destroy the batch. Calls for one batch must be serialized by its owner.

PARAMETERS

`FontGenJobData*`	`jobdata`	Batch to advance.
`uint64_t`	`time_limit`	Soft time limit in microseconds; 0 processes at most one glyph.

RETURNS

bool True once all glyphs and the completion callback have been processed.

Structs

FontGenParams

TYPE

struct FontGenParams

Runtime glyph generation parameters.

MEMBERS

`void*`	`m_UserContext`	Opaque context passed to all callbacks.
`FFontGenIsGlyphCached`	`m_IsGlyphCached`	Cache lookup callback.
`FFontGenAddGlyph`	`m_AddGlyph`	Glyph insertion callback.
`FFontGenComplete`	`m_Complete`	Batch completion callback.
`HJobContext`	`m_Jobs`	Job system used for asynchronous generation.
`float`	`m_Size`	Glyph generation size in pixels.
`float`	`m_OutlineWidth`	Outline width in pixels.
`float`	`m_ShadowBlur`	Shadow blur spread in pixels.
`uint8_t`	`m_IsSdf`	Non-zero when SDF output is requested.
`uint8_t`	`m_IsVector`	Non-zero when Vector glyph output is requested.
`uint8_t`	`m_BitmapEffects`	Generate RGB vector effect bitmaps on the CPU.
`uint8_t`	`m_HasOutline`	Include the authored outline in the effect bitmaps.
`uint8_t`	`m_HasShadow`	Generate the authored shadow bitmap.

Types

FFontGenAddGlyph

void FFontGenAddGlyph()

Returning FONT_RESULT_OK transfers ownership of the glyph to the callback. For every other result, font_gen retains ownership and frees the glyph.

PARAMETERS

FFontGenComplete

void FFontGenComplete()

Reports completion of a glyph generation batch.

PARAMETERS

FFontGenIsGlyphCached

void FFontGenIsGlyphCached()

Looks up a glyph in the caller-owned cache.

PARAMETERS