Index

CDTEngineV8

FontSaveToStream

The function saves the specified font in the Font Catalog to a font file, in D-Type (.dtf) format. Optionally, this function can be used to subset the specified font i.e. store only a subset of its glyphs in the output D-Type font. Subsetted D-Type fonts are almost always smaller in size than the original input fonts (since they contain fewer glyphs) and, therefore, very suitable for embedding in electronic documents.

Parameters

ParameterDescription

font_index

Index of the font to be saved in D-Type font format.

reserved

Reserved for future use. Must be set to 0.

sd

A valid pointer to the DT_STREAM_DESC structure which supplies the location of the output font file to be created. If the specified output file already exists, it will be overwritten.

font_subset_func

This parameter must be either DV_NULL or a valid pointer to your own callback function declared as follows:

DT_SWORD your_font_subset_func(DT_ID_ULONG glyph_index, void* user_param)

where your_font_subset_func is the name of your own C function, glyph_index an index of the glyph in the specified font and user_param a pointer to your own data type that you will receive during the callback.

Your function is called for every glyph in the specified font. Therefore, there will be as many callbacks as there are glyphs in the specified font. Every time you receive a callback, glyph_index will indicate which glyph the callback is for.

The purpose of these callbacks is twofold:

  • to inform you about the general progress of the function
  • to allow you to exclude certain glyphs from the output D-Type font, (i.e. perform glyph subsetting)

Depending on the glyph_index, your callback function should return 1 if that glyph is to be included in the output D-Type font or 0 otherwise. Thus, if your function returns 0, then the glyph for which the callback was initiated (glyph_index) will be excluded from the output D-Type font. If your function returns 1, then that glyph will be included in the output D-Type font.

To disable all callbacks (i.e. glyph subsetting), simply set font_subset_func to DV_NULL. In this case all glyphs in the specified font will be saved in the output D-Type font.

user_param

A void pointer to your own data type that you will receive during the callback. This pointer is passed back to your function during the callback to help you track the state of execution, identify the font being saved or provide other information useful to your application. This pointer is not accessed or modified by D-Type Engine in any way; it is simply sent back to your function as supplied. You can set this parameter to DV_NULL if you have no need for it.

Return Value

If the function was successful, the return value is 1. Otherwise, the function returns a negative number.

Comments

Applications can use FontSaveToStream to save fonts in D-Type format. Please note, however, that existing TrueType, OpenType, Type 1, Type 3 and CFF fonts may be protected under copyright law. The unauthorized use or distribution of those files, whether in their native or D-Type format, could be a violation of the rights of the author. Be sure you obtain any permission required from such authors.

The FontSaveToStream function also gives you full control over the glyph subsetting process. This, for example, allows you to save in the output D-Type font only those glyphs that are actually used in your document. If you wish to exclude certain characters from the output D-Type font, then you must convert your character codes to glyph indices using the FontGetGlyphIndex before calling FontSaveToStream. You can use the user_param variable to store information important to your application between the callbacks.

Note 1

See How To Use D-Type Streams And Stream Macros.



 

Index