CreateFontPackage function (fontsub.h)
The CreateFontPackage function creates a subset version of a specified TrueType font, typically in order to pass it to a printer. In order to allow for the fact that pages later in a document may need characters or glyphs that were not used on the first page, this function can create an initial subset font package, then create "Delta" font packages that can be merged with the original subset font package, effectively extending it.
Syntax
unsigned long CreateFontPackage(
[in] const unsigned char *puchSrcBuffer,
[in] const unsigned long ulSrcBufferSize,
[out] unsigned char **ppuchFontPackageBuffer,
[out] unsigned long *pulFontPackageBufferSize,
[out] unsigned long *pulBytesWritten,
[in] const unsigned short usFlag,
[in] const unsigned short usTTCIndex,
[in] const unsigned short usSubsetFormat,
[in] const unsigned short usSubsetLanguage,
[in] const unsigned short usSubsetPlatform,
[in] const unsigned short usSubsetEncoding,
[in] const unsigned short *pusSubsetKeepList,
[in] const unsigned short usSubsetListCount,
[in] CFP_ALLOCPROC lpfnAllocate,
[in] CFP_REALLOCPROC lpfnReAllocate,
[in] CFP_FREEPROC lpfnFree,
[in] void *lpvReserved
);
Parameters
[in] puchSrcBuffer
Points to a buffer containing source TTF or TTC data, describing the font that is to be subsetted.
[in] ulSrcBufferSize
Specifies size of *puchSrcBuffer, in bytes.
[out] ppuchFontPackageBuffer
Points to a variable of type unsigned char*. The CreateFontPackage function will allocate a buffer **puchFontPackageBuffer, using lpfnAllocate and lpfnReAllocate. On successful return, the buffer will contain the subset font or font package. The application is responsible for eventually freeing the buffer.
[out] pulFontPackageBufferSize
Points to an unsigned long, which on successful return will specify the allocated size of buffer **puchFontPackageBuffer.
[out] pulBytesWritten
Points to an unsigned long, which on successful return will specify the number of bytes actually used in buffer **puchFontPackageBuffer.
[in] usFlag
Specifies whether this font should be subsetted, compressed, or both; whether it is a TTF or TTC; and whether*pusSubsetKeepListrepresents character codes or glyph indices. Any combination of the following flags may be specified:
[in] usTTCIndex
The zero based TTC Index; only used if TTFCFP_FLAGS_TTC is set in usFlags.
[in] usSubsetFormat
The format of the file to create. Select one of these values; they cannot be combined.
[in] usSubsetLanguage
The language in the Name table to retain. If Set to 0, all languages will be retained. Used only for initial subsetting: that is, used only if usSubsetFormat is either TTFCFP_SUBSET or TTFCFP_SUBSET1, and the TTFCFP_FLAGS_SUBSET flag is set in usFlags.
[in] usSubsetPlatform
In conjunction with usSubsetEncoding, specifies which CMAP to use. Used only if *pusSubsetKeepList is a list of characters: that is, used only if TTFCFP_FLAGS_GLYPHLIST is not set in usFlags. In that case, by this CMAP subtable is applied to pusSubsetKeepList to create a list of glyphs to retain in the output font or font package.
If used, this must take one of the following values; they cannot be combined:
| Value | Meaning |
|---|---|
|
|
|
|
|
|
|
[in] usSubsetEncoding
In conjunction with usSubsetPlatform, specifies which CMAP to use. Used only if *pusSubsetKeepList is a list of characters: that is, used only if TTFCFP_FLAGS_GLYPHLIST is not set in usFlags.
If used, this must take one of the following values; they cannot be combined:
[in] pusSubsetKeepList
Points to an array of integers which comprise a list of character codes or glyph indices that should be retained in the output font or font package. If this list contains character codes (that is, if TTFCFP_FLAGS_GLYPHLIST is not set in usFlags), this list may be either Unicode or some other type of encoding, depending on the Platform-Encoding CMAP specified by usSubsetPlatform and usSubsetEncoding.
[in] usSubsetListCount
The number of elements in the list *pusSubsetKeepList.
[in] lpfnAllocate
The callback function to allocate initial memory for puchFontPackageBuffer and for temporary buffers.
[in] lpfnReAllocate
The callback function to reallocate memory for puchFontPackageBuffer and for temporary buffers.
[in] lpfnFree
The callback function to free up memory allocated by lpfnAllocate and lpfnReAllocate.
[in] lpvReserved
Must be set to NULL.
Return value
If the function is successful, returns zero.
Otherwise, returns a nonzero value. See Font-Package Function Error Messages for possible error returns.
Remarks
By specifying a value of TTFCFP_SUBSET for usSubsetFormat, you can directly create a working font rather than a font package. This does not allow for future merging, but if there is no need for merging, this skips a step in the downstream processing: a font package needs to be converted back to a working font before it can be used.
By specifying a value of TTFCFP_SUBSET1 for usSubsetFormat, you can create a font package that allows later merging. For example, consider the case where an application calls this function at the start of a large print job. Part way through the print job, the application discovers that it needs glyphs that are not in the subset it has built. The application can make another call to CreateFontPackage, this time specifying a value of TTFCFP_DELTA for usSubsetFormat. The printer can use MergeFontPackage to merge in these additional glyphs.
A CMAP maps from character encodings to glyphs. If *pusSubsetKeepList is a list of character values, then the application uses parameters usSubsetPlatform and usSubsetEncoding to specify what type of CMAP is being used, so that character values can be mapped to glyphs.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | fontsub.h |
| Library | FontSub.lib |
| DLL | FontSub.dll |