API
API
C
API reference (Font) — Alpha (1.14.1)
DEFOLD
Home Features Showcase Learn Asset Portal Community Blog Support API Free Download Donate  

Defold Learn logo

Defold Learn logo

Font

Font API for loading a font (truetype), getting glyph metrics and bitmap/sdf data

Include: #include <dmsdk/font/font.h>
ENUMS
FontCurveType Commands used to describe a glyph's analytical out...
FontGlyphBitmapFlags FontGlyphBitmapFlags
FontResult FontResult
FontType FontType
STRUCTS
struct FontCurveCommand One command in a glyph outline. The command type d...
struct FontCurvePoint A point in a glyph outline, measured in pixels at ...
struct FontGlyph Represents a glyph
struct FontGlyphBitmap Holds the bitmap data of a glyph
struct FontGlyphOptions Holds the bitmap data of a glyph
struct FontGlyphOutline Analytical glyph outline and unpadded bounds at th...
struct FontGlyphVector Holds prebaked normalized quadratic curves for a v...
FUNCTIONS
void FontDestroy (HFont font) Destroys a loaded font
dmFont::FontResult FontFreeGlyph (HFont font, dmFont::Glyph* glyph) Free the bitmap of the glyph
float FontGetAscent (HFont font, float scale) Get the max ascent of the font
float FontGetDescent (HFont font, float scale) Get the max descent of the font
FontFontResult FontGetGlyph (HFont font, uint32_t codepoint,  options,  glyph) Get the metrics of a glyph
FontFontResult FontGetGlyphByIndex (HFont font, uint32_t glyph_index,  options,  glyph) Get the metrics of a glyph
uint32_t FontGetGlyphIndex (HFont font, uint32_t codepoint) Get glyph index of a codepoint
float FontGetLineGap (HFont font, float scale) Get the line gap of the font
const char* FontGetPath (HFont font) Gets the path of the loaded font
uint32_t FontGetPathHash (HFont font) Gets the path hash of the loaded font
uint32_t FontGetResourceSize (HFont font) Get the bytes used by this resource
float FontGetScaleFromSize (HFont font, float size) Get the scale factor from a given pixel size
dmFont::FontType FontGetType (HFont font) Gets the specific implementation of the loaded fon...
HFont FontLoadFromMemory (const char* name, void* data, uint32_t data_size, bool allocate) Loads a font from memory
HFont FontLoadFromPath (const char* path) Loads a font using a path

Functions

FontDestroy

void FontDestroy(HFont font)

Destroys a loaded font

PARAMETERS

HFont font The font to deallocate

FontFreeGlyph

dmFont::FontResult FontFreeGlyph(HFont font, dmFont::Glyph* glyph)

Free the bitmap of the glyph

PARAMETERS

HFont font The font
dmFont::Glyph* glyph The glyph

RETURNS

dmFont::FontResult The result

FontGetAscent

float FontGetAscent(HFont font, float scale)

Get the max ascent of the font

PARAMETERS

HFont font The font
float scale The scale factor

RETURNS

float The max ascent

FontGetDescent

float FontGetDescent(HFont font, float scale)

Get the max descent of the font

PARAMETERS

HFont font The font
float scale The scale factor

RETURNS

float The max descent

FontGetGlyph

FontFontResult FontGetGlyph(HFont font, uint32_t codepoint,  options,  glyph)

Get the metrics of a glyph

PARAMETERS

HFont font The font
uint32_t codepoint The unicode code point
options (in) FontGlyphOptions* The glyph options
glyph (out) FontGlyph* The glyph

RETURNS

FontFontResult If successful, user must call FreeGlyph() on the result to clear any image data.

FontGetGlyphByIndex

FontFontResult FontGetGlyphByIndex(HFont font, uint32_t glyph_index,  options,  glyph)

Get the metrics of a glyph

PARAMETERS

HFont font The font
uint32_t glyph_index The unicode code point
options (in) FontGlyphOptions* The glyph options
glyph (out) FontGlyph* The glyph

RETURNS

FontFontResult If successful, user must call FreeGlyph() on the result to clear any image data.

FontGetGlyphIndex

uint32_t FontGetGlyphIndex(HFont font, uint32_t codepoint)

Get glyph index of a codepoint

PARAMETERS

HFont font The font
uint32_t codepoint The unicode code point

RETURNS

uint32_t 0 if no index was found

FontGetLineGap

float FontGetLineGap(HFont font, float scale)

Get the line gap of the font

PARAMETERS

HFont font The font
float scale The scale factor

RETURNS

float The line gap

FontGetPath

const char* FontGetPath(HFont font)

Gets the path of the loaded font

PARAMETERS

HFont font The font

RETURNS

const char* The path

FontGetPathHash

uint32_t FontGetPathHash(HFont font)

Gets the path hash of the loaded font

PARAMETERS

HFont font The font

RETURNS

uint32_t The path

FontGetResourceSize

uint32_t FontGetResourceSize(HFont font)

Get the bytes used by this resource

PARAMETERS

HFont font The font

RETURNS

uint32_t The resource size

FontGetScaleFromSize

float FontGetScaleFromSize(HFont font, float size)

Get the scale factor from a given pixel size. Used to convert from points to pixel size

PARAMETERS

HFont font The font
float size The font size (in pixel height)

RETURNS

float The scale factor

FontGetType

dmFont::FontType FontGetType(HFont font)

Gets the specific implementation of the loaded font

PARAMETERS

HFont font The font

RETURNS

dmFont::FontType The type

FontLoadFromMemory

HFont FontLoadFromMemory(const char* name, void* data, uint32_t data_size, bool allocate)

Loads a font from memory

PARAMETERS

const char* name The name of the resource. For easier debugging
void* data The raw data
uint32_t data_size The length of the data (in bytes)
bool allocate If true, the font may allocate a copy of the data (if needed). If false, the caller will own the memory.

RETURNS

HFont The loaded font, or null if it failed to load.

FontLoadFromPath

HFont FontLoadFromPath(const char* path)

Loads a font using a path

PARAMETERS

const char* path The path to the resource

RETURNS

HFont The loaded font, or null if it failed to load.

Structs

FontCurveCommand

TYPE

struct FontCurveCommand

One command in a glyph outline. The command type determines which points are used.

MEMBERS

FontCurvePoint[2] m_Points Control and endpoint coordinates. See #FontCurveType.
uint8_t m_Type Command type from #FontCurveType.
uint8_t m_Reserved0 Reserved; must be zero.
uint16_t m_Reserved1 Reserved; must be zero.

FontCurvePoint

TYPE

struct FontCurvePoint

A point in a glyph outline, measured in pixels at the requested glyph size. Coordinates are relative to the glyph's pen origin on the baseline.

MEMBERS

float m_X Horizontal coordinate, increasing to the right.
float m_Y Vertical coordinate, increasing above the baseline.

FontGlyph

TYPE

struct FontGlyph

Represents a glyph. If there's an associated image, it is of size width * height * channels.

MEMBERS

FontGlyphBitmap m_Bitmap The bitmap data of the glyph.
FontGlyphOutline m_Outline Analytical outline commands and unpadded bounds.
FontGlyphVector m_Vector Prebaked normalized vector curves, when available.
uint32_t m_Codepoint The unicode code point
float m_Width The glyph bounding width
float m_Height The glyph bounding height
float m_Advance The advance step of the glyph (in pixels)
float m_LeftBearing The left bearing of the glyph (in pixels)
float m_Ascent The ascent of the glyph. (in pixels)
float m_Descent The descent of the glyph. Positive! (in pixels)

FontGlyphBitmap

TYPE

struct FontGlyphBitmap

Holds the bitmap data of a glyph. If there's an associated image, it is of size width * height * channels.

MEMBERS

uint16_t m_Width The glyph image width
uint16_t m_Height The glyph image height
uint8_t m_Channels The number of color channels
uint8_t m_Flags Flags describing the data. See #FontGlyphBitmapFlags.
uint8_t* m_Data The bitmap data, or null if no data available.
uint32_t m_DataSize The bitmap data size (e.g. if the data is compressed)

FontGlyphOptions

TYPE

struct FontGlyphOptions

Holds the bitmap data of a glyph. If there's an associated image, it is of size width * height * channels.

MEMBERS

float m_Scale The font scale
bool m_UseUnpaddedBounds For metrics-only queries, use unpadded outline bounds when available. Older glyph banks retain their bitmap bounds.
bool m_GenerateImage If true, generates an SDF image and uses its sampled bounds and origin for glyph dimensions and left bearing. Advances remain unchanged.
bool m_GenerateOutline If true, generates outline data and fills out the glyph.m_Outline structure.
int m_StbttSDFPadding The SDF padding value (valid for FONT_TYPE_TTF and FONT_TYPE_OTF fonts)
int m_StbttSDFOnEdgeValue Where the edge value is located (valid for FONT_TYPE_TTF and FONT_TYPE_OTF fonts)

FontGlyphOutline

TYPE

struct FontGlyphOutline

Analytical glyph outline and unpadded bounds at the requested glyph size. Generated commands belong to the glyph and are released by FontFreeGlyph.

MEMBERS

FontCurveCommand* m_Commands Contour commands, or null when no outline was generated.
uint32_t m_CommandCount Number of contour commands.
uint32_t m_Flags Reserved; must be zero.
float m_Width Unpadded outline width in pixels.
float m_Height Unpadded outline height in pixels.
float m_LeftBearing Horizontal offset from the pen origin to the outline's left edge.
float m_Ascent Outline extent above the baseline in pixels.
float m_Descent Distance from the baseline to the outline's bottom edge in pixels; positive below the baseline.

FontGlyphVector

TYPE

struct FontGlyphVector

Holds prebaked normalized quadratic curves for a vector glyph. Every curve contains P0, P1, P2, start tangent angle, and end tangent angle as eight consecutive float32 values.

MEMBERS

const uint8_t* m_Data Encoded curve data, or null when unavailable.
uint32_t m_DataSize Encoded curve data size in bytes.
uint32_t m_CurveCount Number of encoded quadratic curves.

Enums

FontCurveType

Commands used to describe a glyph's analytical outline.

FONT_CURVE_MOVE_TO Starts a contour at m_Points[0].
FONT_CURVE_LINE_TO Adds a line from the current point to m_Points[0].
FONT_CURVE_QUADRATIC_TO Adds a quadratic curve with control point m_Points[0] and endpoint m_Points[1].
FONT_CURVE_CLOSE Closes the current contour; no points are used.

FontGlyphBitmapFlags

FontGlyphBitmapFlags

GLYPH_BM_FLAG_COMPRESSION_NONE = 0
GLYPH_BM_FLAG_COMPRESSION_DEFLATE = 1

FontResult

FontResult

FONT_RESULT_OK
FONT_RESULT_NOT_SUPPORTED
FONT_RESULT_ERROR

FontType

FontType

FONT_TYPE_TTF
FONT_TYPE_OTF
FONT_TYPE_GLYPH_BANK
FONT_TYPE_UNKNOWN = 0xFFFFFFFF