MergeFontPackage function (fontsub.h)

Article
10/13/2021

The MergeFontPackage function manipulates fonts created by CreateFontPackage. It is slightly more flexible than its name might suggest: it can appropriately handle all of the subset fonts and font packages created by CreateFontPackage. It can turn a font package into a working font, and it can merge a Delta font package into an appropriately prepared working font.

Typically, CreateFontPackage creates subset fonts and font packages to pass to a printer or print server; MergeFontPackage runs on that printer or print server.

Syntax

unsigned long MergeFontPackage(
  [in]  const unsigned char  *puchMergeFontBuffer,
  [in]  const unsigned long  ulMergeFontBufferSize,
  [in]  const unsigned char  *puchFontPackageBuffer,
  [in]  const unsigned long  ulFontPackageBufferSize,
  [out] unsigned char        **ppuchDestBuffer,
  [out] unsigned long        *pulDestBufferSize,
  [out] unsigned long        *pulBytesWritten,
  [in]  const unsigned short usMode,
  [in]  CFP_ALLOCPROC        lpfnAllocate,
  [in]  CFP_REALLOCPROC      lpfnReAllocate,
  [in]  CFP_FREEPROC         lpfnFree,
  [in]  void                 *lpvReserved
);

Parameters

[in] puchMergeFontBuffer

A pointer to a buffer containing a font to merge with. This is used only when usMode is TTFMFP_DELTA.

[in] ulMergeFontBufferSize

Specifies size of *puchMergeFontBuffer, in bytes.

[in] puchFontPackageBuffer

A pointer to a to buffer containing a font package.

[in] ulFontPackageBufferSize

Specifies size of *puchMergeFontBuffer, in bytes.

[out] ppuchDestBuffer

A pointer to a variable of type unsigned char*. The MergeFontPackage function will allocate a buffer **ppuchDestBuffer, using lpfnAllocate and lpfnReAllocate. On successful return, that buffer will contain the resulting merged or expanded font. The application is responsible for eventually freeing that buffer.

[out] pulDestBufferSize

Points to an unsigned long, which on successful return will specify the allocated size of buffer **ppuchDestBuffer.

[out] pulBytesWritten

Points to an unsigned long, which on successful return will specify the number of bytes actually used in buffer **ppuchDestBuffer.

[in] usMode

Specifies what kind of process to perform. Select one of these values; they cannot be combined.

Value	Meaning
TTFMFP_SUBSET	Copies a simple working font; see remarks below. puchMergeFontBuffer will be ignored; puchFontPackageBuffer should contain a working font created by CreateFontPackage with usSubsetFormat set to TTFCFP_SUBSET; this working font will simply be copied to ppuchDestBuffer.
TTFMFP_SUBSET1	Turns a font package into a mergeable working font; see remarks below. puchMergeFontBuffer will be ignored; puchFontPackageBuffer should contain a mergeable working font created by CreateFontPackage with usSubsetFormat set to TTFCFP_SUBSET1. The result in **ppuchDestBuffer will be a working font that may be merged with later.
TTFMFP_DELTA	Merges a Delta font package into a mergeable working font; see remarks below. *puchFontPackageBuffer should contain a font package created by CreateFontPackage with usSubsetFormat set to TTFCFP_DELTA and puchMergeFontBuffer should contain a font package created by a prior call to MergeFontPackage with usMode set to TTFMFP_SUBSET1 or TTFMFP_DELTA. The resulting merged font in **ppuchDestBuffer will be a working font that may be merged with later.

[in] lpfnAllocate

The callback function to allocate initial memory for ppuchDestBuffer and for temporary buffers.

[in] lpfnReAllocate

The callback function to reallocate memory for ppuchDestBuffer 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

This function handles four distinct, related entities, each representing a subset font:

Entity	Produced by	Directly usable as a font
Simple working font	CreateFontPackage with usSubsetFormat set to TFCFP_SUBSET.	Yes
Font package	CreateFontPackage with usSubsetFormat set to TTFCFP_SUBSET1.	No
Delta font package	CreateFontPackage with usSubsetFormat set to TTFCFP_DELTA.	No
Mergeable working font	MergeFontPackage with usMode set to TTFMFP_SUBSET1 or TTFMFP_DELTA.	Yes

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