Index

C/C++ Functions

pdEngineIniViaStream

DT_SWORD pdEngineIniViaStream(DT_PDENGINE* engine, const DT_STREAM_DESC* sd, DT_INIT_INFO* init_info)

Short Description: Create and initialize D-Type Power Engine - via stream

The pdEngineIniViaStream function creates and initializes a new instance of D-Type Power Engine (or simply Engine within the scope of D-Type Power Engine Manual) using a set of external initialization streams. The pdEngineIniViaStream function must be called before any other D-Type Power Engine function can be used.

Applications can later associate one or more documents with this Power Engine instance by calling the pdDocIni function. Consequently, before this Power Engine instance is destroyed using the pdEngineExt function, all of its documents must first be destroyed using the pdDocExt function.

It is important to understand that each Power Engine instance has its own internal instance of D-Type Standard Engine. Together, these two engine instances hold a set of fonts, patterns, grayscale levels and other needed resources. Each Power Engine instance always owns exactly one internal D-Type Standard Engine instance. More specifically, when your application creates a new instance of D-Type Power Engine by calling pdEngineIniViaStream, D-Type Power Engine in turn automatically creates its own instance of D-Type Standard Engine. To get a handle of this D-Type Standard Engine instance, applications can call the pdEngineGetDTEngineInst function. For more information on D-Type Standard Engine, see D-Type Standard Engine Manual.

Additionally, each Power Engine instance keeps its own internal instance of D-Type Hyphenator, D-Type Layout Cache and other objects. See pdEngineGetHyphenatorInst and pdEngineGetLayoutCacheInst for details.

Parameters

ParameterDescription

engine

Pointer to the handle of the newly created Power Engine instance.

sd

A valid pointer to the DT_STREAM_DESC structure which supplies the location of the main D-Type initialization file. This is the same file that is used to initialize D-Type Standard Engine (dtype.inf). For more information, please see the dtEngineIniViaStream function in D-Type Standard Engine Manual. When appropriate, your application can provide its own (i.e. altered) version of the dtype.inf file. Also, it is possible for each Power Engine instance to be initialized via its own unique initialization file.

init_info

An optional pointer to the DT_INIT_INFO structure that provides additional initialization information to the engine and receives additional initialization information from the engine. This parameter has the same purpose as init_info in Standard Engine's dtEngineIniViaStream function. For details, see the dtEngineIniViaStream function in D-Type Standard Engine Manual. If you do not wish to make use of this parameter, simply set it to DV_NULL.

Return Value

If the initialization was successful, the return value is 1 and engine holds a handle of the newly created Power Engine instance. Otherwise, the function returns 0 and engine holds DV_NULL. Applications that make use of the init_info structure can get extended error information via its init_status member.

Comments

An application can create multiple instances of D-Type Power Engine by calling the pdEngineIniViaStream function more than once. Each instance is created dynamically and must be destroyed by calling the pdEngineExt function before the application terminates. In multi-threaded applications, each thread can initialize its own Power Engine instance. This approach allows multiple threads to call the library's functions simultaneously (without using mutexes or other synchronization or blocking code). However, depending on the font cache, number of fonts and other utilized resources, a large number of Power Engine instances may require a significant amount of RAM.

Related Functions

pdEngineExt, pdEngineGetDTEngineInst
pdDocIni

Note 1

To ensure that the initialization is successful, the location that sd holds must point to the main D-Type initialization file. For more information on the structure of the main D-Type initialization file, see the Initialization Files section of this document. In addition, any other stream descriptors that the main D-Type initialization file may contain (e.g. locations of the initial font list, pattern catalog, etc.) must be valid and should stay valid until the corresponding Power Engine instance is destroyed by calling pdEngineExt. Remember that D-Type Engine might attempt to open some of these streams later during the execution of your application so it is important to ensure that they remain accessible to D-Type Engine even after the pdEngineIniViaStream function returns.

Note 2

See How To Use D-Type Streams And Stream Macros.

Note 3

See our notes regarding file based streams.

Note 4

See our note for MS Visual C++ users.

Note 5

Please note that any stream descriptors that are part of the Optional Secondary Initialization Files section of dtype.inf are optional. If not needed, they can be specified as NONE streams (Stream ID = -1, Stream Locator = NONE). Otherwise they must be valid or your initialization could fail.

Note 6

Char Translation and Alignment stream descriptors (the .ccv file paths) that are specified within the Font Factories section of dtype.inf are highly recommended because those files allow your application to create custom character encodings and, additionally, contain instruction designed to improve font rendering. Therefore, we do not recommend you specify them as NONE streams.

Note 7

This function is similar in design to dtEngineIniViaStream. Please carefully review this function in D-Type Standard Engine Manual.

 

Index