Index

C/C++ Functions

dtFontAddViaStreams

DT_ID_SWORD dtFontAddViaStreams(DT_DTENGINE engine, DT_ID_SWORD font_format_id, const DT_CHAR* fuid, DT_SWORD fcnr, DT_ID_SWORD cmap_id, DT_ID_UBYTE caching, DT_ID_UBYTE hinting, DT_UBYTE arr_size, const DT_STREAM_DESC* sd[])

Short Description: Add new font to Font Catalog via a set of streams and return its font index

This function adds a font from a set of font files to the Font Catalog of the specified Standard Engine instance. The function then returns a font index of the newly added font. This index uniquely identifies the font in the Font Catalog.

This function is very similar to dtFontAddViaStream. However, this function is more versatile because it allows multiple input files to serve as the data source for the font that is being added to the Font Catalog. Thus, this function is particularly suitable for font formats that supply additional (and usually optional) font data via additional file(s). A typical example of such a format is Type 1. This format, in addition to the main font file, may include an optional font metrics file that contains additional font information (such as global and individual character metrics, kerning, information about writing direction etc). Currently, Type 1 is the only supported font format that consists of multiple input files. In the future, however, this function may be used for other font formats that consist of multiple input files.

The order in which input files are specified when calling this function is extremely important. The first input file is always the font file that supplies vital font data and is called the main input file. The main input file for each font format is defined in the D-Type Font Driver Classes section of this document. This file is mandatory and cannot be omitted. Any additional font files (if applicable) must follow. Their order and purpose is format specific and is also described in the D-Type Font Driver Classes section of this document. This section also explains how D-Type Font Engine (or more precisely its font driver classes) utilize various supported input files.

Parameters

ParameterDescription

engine

Handle of the previously created Standard Engine instance.

font_format_id

See dtFontAddViaStream.

fuid

See dtFontAddViaStream

fcnr

See dtFontAddViaStream.

cmap_id

See dtFontAddViaStream.

caching

See dtFontAddViaStream.

hinting

See dtFontAddViaStream.

arr_size

The size of the file_name array. This parameters tells how many input files will serve as the data source for the font that is being added to the Font Catalog.

sd

An array of valid pointers to the DT_STREAM_DESC structure. Each structure supplies the location of the corresponding input file. The first input file supplies vital font data and is called the main input file; any additional input files (if applicable) are format specific and must follow in a predetermined order. See D-Type Font Driver Classes for details.

The sd array must supply font locations that are valid at least until the corresponding font is permanently removed from the Font Catalog. Remember that D-Type Font Engine will attempt to access your font at various stages during the execution of your application. If some of the sd structures supply a relative file path and your applications changes the current working directory during its execution, you will likely make that font inaccessible to D-Type Font Engine. As a result, your font or some of its glyphs may not render, you may not be able to retrieve various font information etc.

Once again, please note that relative paths are relative. They are relative to your current working directory. Therefore, if the current working directory changes at some point during the execution of your application, your paths may become invalid. Also, see How To Use D-Type Streams And Stream Macros and our notes regarding file based streams.

Return Value

See dtFontAddViaStream.

Comments

See dtFontAddViaStream.

Example

This example shows how to add a new font to the Font Catalog using the dtFontAddViaStreams function.

DT_STREAM_FILE(sd0, "../../fonts/pfb/HSansMM.pfb");
DT_STREAM_FILE(sd1, "../../fonts/pfb/HSansMM.pfa");

const DT_STREAM_DESC* sd[2] = {&sd0, &sd1};
font_index = dtFontAddViaStreams(engine, DV_FONT_TYPE1_ADOBE, DV_NULL, 0, -1, 0, 1, 2, sd);
 

Index