Index

C/C++ Functions

dtGlyphGetExtras

DT_UBYTE* dtGlyphGetExtras(DT_DTENGINE engine, DT_ID_SWORD font_index, DT_ID_ULONG glyph_index, DT_UWORD flags, const DT_SLONG params[], DT_SLONG* len, DT_UWORD* xtra_bits)

Short Description: Get extra data that might be associated with a glyph

dtCharGetExtras

DT_UBYTE* dtCharGetExtras(DT_DTENGINE engine, DT_ID_SWORD font_index, DT_ID_ULONG char_code, DT_UWORD flags, const DT_SLONG params[], DT_SLONG* len, DT_UWORD* xtra_bits)

Short Description: Get extra data that might be associated with a character

This function retrieves extra data (or extras) associated with a single glyph represented by a Unicode character code (or font dependent glyph index) that might be available in the specified font. Extras presently include PNG, JPEG or TIFF images stored in the font's OpenType sbix table, color glyph layer data stored in the COLR and CPAL tables and SVG document data stored in the SVG table. In the future, other types of extras might be supported as well. Please note that not all fonts have extras. Currently only certain OpenType fonts contain extras (e.g. fonts that provide support for colored glyphs or emojis). However, even in those fonts, there is no guarantee that every single glyph will have extras. If a glyph does not have any extras, it is represented using standard outlines.

Parameters

ParameterDescription

engine

Handle of the previously created Standard Engine instance.

font_index

Font index of the font or font instance in the Font Catalog.

char_code

Unicode character code of the glyph for which the extras will be retrieved.

glyph_index

Font dependent index of the glyph for which the extras will be retrieved.

flags

A value that identifies what extras to retrieve. At present this can be:

  • 0 — don't retrieve any extras, only return the bitmask value via the xtra_bits parameter
  • 1 — retrieve sbix extras and return the bitmask value via the xtra_bits parameter
  • 2 — retrieve COLR/CPAL extras and return the bitmask value via the xtra_bits parameter
  • 3 — retrieve SVG extras and return the bitmask value via the xtra_bits parameter

Note that only one type of extra data at a time can be retrieved using this function. In other words, it is not possible to return, for example, both sbix and COLR/CPAL extras in one function call. However, the xtra_bits parameter always contains a bitmask value representing all types of extras available for the specified glyph. To retrieve multiple types of extras for the same glyph, multiple function calls are necessary.

params

An optional array of parameters specific to the type of extras retrieved. If no additional parameters need to be passed, params can be set to DV_NULL. See the comments below for details.

len

A valid pointer to the DT_SLONG type that will receive the total length of the retrieved extra data in the buffer.

xtra_bits

A valid pointer to the DT_UWORD type that will receive the bitmask value which specifies what glyph extras are available.

  • bit 0 (1) — The glyph has a bitmap image stored in the font's sbix OpenType table. The image can be in PNG, JPEG or TIFF format.
  • bit 1 (2) — The glyph has color glyph layers stored in the font's COLR and CPAL OpenType tables.
  • bit 2 (4) — The glyph has SVG data stored in the font's SVG table.

Other bits are reserved for future.

Return Value

The return value is a pointer to the buffer that stores extra glyph data. This buffer is dynamically allocated and must be freed by calling dtFree when no longer needed. If no extra glyph data can be retrieved, this value will be DV_NULL and len will hold 0.

Comments

1) To only check what glyph extras are available, set flags to 0 when calling the function. In this case the function will set the xtra_bits accordingly and return DV_NULL. The len parameter will hold the value 0.

2) To retrieve sbix extras and also check what glyph extras are available, set flags to 1 when calling the function. In this case the function will set the xtra_bits accordingly and return a pointer to a dynamically allocated buffer that holds the extra data, if the requested data is available. The size of the buffer will be returned via the len parameter. The format of the data in the buffer will be as follows:

10-Byte Header

Actual Data — Immediately after the header, the actual image data follows.

When calling the function to retrieve sbix extras, the params parameter currently has no purpose and should be set to DV_NULL. If sbix data is not available for the specified glyph, the function will return DV_NULL and set len to 0.

3) To retrieve COLR/CPAL extras and also check what glyph extras are available, set flags to 2 when calling the function and, optionally, set the first element of the params array to the index of the desired color palette. The index 0 is always valid and means the first (default) palette. If the first (default) palette is to be used, params can also be set to DV_NULL. The function will set the xtra_bits accordingly and return a pointer to a dynamically allocated buffer that holds the extra data, if the requested data is available. The size of the buffer will be returned via the len parameter. The format of the data in the buffer will be as follows:

6-Byte Header

Actual Data — Immediately after the header, the buffer contains N records, each representing one glyph layer. Glyph layers are stored in the bottom-to-top order. Each record is 8 bytes in size has the following format:

If COLR/CPAL data is not available for the specified glyph, the function will return DV_NULL and set len to 0.

4) To retrieve SVG extras and also check what glyph extras are available, set flags to 3 when calling the function. In this case the function will set the xtra_bits accordingly and return a pointer to a dynamically allocated buffer that holds the extra data, if the requested data is available. The size of the buffer will be returned via the len parameter. The format of the data in the buffer will be as follows:

10-Byte Header

Actual Data — Immediately after the header, the actual SVG data follows.

When calling the function to retrieve SVG extras, the params parameter currently has no purpose and should be set to DV_NULL. If SVG data is not available for the specified glyph, the function will return DV_NULL and set len to 0.  

Index