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.
Parameter | Description |
---|---|
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:
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.
Other bits are reserved for future. |
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.
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.
SVG documents stored in this array may be either plain text or gzip-encoded, and applications that support the SVG table must support both. The gzip format is defined in RFC 1952, "GZIP file format specification version 4.3", available at http://www.ietf.org/rfc/rfc1952.txt. Within a gzip-encoded SVG document, the deflate compression method (defined at http://www.ietf.org/rfc/rfc1951.txt) must be used. Thus, the first three bytes of the gzip-encoded document will be 0x1F, 0x8B, 0x08.
Whether compressed or plain-text transfer encoding is used, the len parameter always indicates the length of the encoded data, not the decoded document.
The character encoding of the (uncompressed) SVG document is required by the OpenType specification to be UTF-8.
For details on how to interpret the actual SVG data returned in this array, please refer to the "SVG Documents" section of the official OpenType specification at https://docs.microsoft.com/en-us/typography/opentype/spec/svg
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.