DynaPDF Manual - Page 699

Previous Page 698   Index   Next Page 700

Function Reference
Page 699 of 839
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 possible.
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:
To improve processing speed the directory in which CMap files are stored should not
contain other file types.
CMap files should be loaded once per PDF instance and one PDF instance should be used as
long as possible to create an arbitrary number of PDF files.

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

Next topic: SetColDefFile