DynaPDF Manual - Page 645

Previous Page 644   Index   Next Page 646

Function Reference
Page 645 of 777
Return values:
If the function succeeds the return value is the font handle, a value greater or equal zero. If the
function fails, the return value is a negative error code.
SI32 pdfSetCMapDir(
const PPDF* IPDF,
// Instance pointer
const char* Path,
// Directory that contains CMap files
TLoadCMapFlags Flags) // See below
typedef enum
= 0, // Load the cmaps in the directory now
lcmRecursive = 1, // Load sub directories recursively
= 2
// Load the files when required
The function sets a search path from which external CMap files can be loaded. External CMap files
are sometimes required, e.g. when extracting text from Asian PDF files or when rendering PDF
pages. However, it is also possible to load external CMaps with OpenType or TrueType fonts. This is
a key feature when creating Asian PDF files (see SetCIDFont() for further information).
Although the function name suggests that only one directory can set at time it is possible to load an
arbitrary number of directories. Each time the function is called a duplicate check is performed so
that only unique CMap files reside in the CMap cache.
The parameter Flags specifies how and when the CMaps should be loaded. When the flag
lcmDelayed is set, the function adds the path to the internal array of search paths, but the CMap files
will be loaded when a font requires an external CMap, e.g. during text extraction or rendering. The
flag lcmDelayed should be set in viewer applications so that the first page can be loaded as fast as
CMap files can be divided into three categories:
CMaps which provide a mapping from an arbitrary character encoding to a predefined
character collection.
CMaps which provide an identity mapping to a predefined character collection. Such CMaps
should contain the DSC comment "%%BeginResource: CMap (Identity)".
CMaps which provide a CID to Unicode mapping of a character collection.
If a CMap should be loaded for use with an OpenType or TrueType font, two CMap files are
required: the one that provides the mapping into the character collection, and the one that provides
the CID to Unicode mapping. If one of these CMap files base in turn on another CMap, the
corresponding base CMap must be available too.
The following notes should be considered when working with external CMaps:

Previous topic: Word Spacing, Vertical Writing Mode, Encodings Identity-H and Identity-V

Next topic: SetColDefFile