Index

C/C++ Functions

dtEngineIniViaStream

DT_SWORD dtEngineIniViaStream(DT_DTENGINE* engine, const DT_STREAM_DESC* sd, DT_INIT_INFO* init_info)

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

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

Parameters

ParameterDescription

engine

Pointer to the handle of the newly created Standard Engine instance (also called D-Type Engine instance).

sd

A valid pointer to the DT_STREAM_DESC structure which supplies the location of the main D-Type initialization file. Typically, this is dtype.inf. When appropriate, your application can provide its own (i.e. altered) version of the dtype.inf file. Also, it is possible for each Standard Engine instance to be initialized via its own unique initialization file, meaning that different Standard Engine instances can be initialized using a different set of initialization parameters.

init_info

A pointer to the DT_INIT_INFO structure that provides additional initialization information to D-Type Engine and receives additional initialization information from D-Type Engine. If you do not wish to make use of this parameter, simply set it to DV_NULL.

The members of this structure have the following meaning:

init_key — this parameter is reserved for future and must be set to 0:

init_flag — this parameter is reserved for future and must be set to 0:

init_status — this parameter provides extended initialization information and is set by D-Type Engine. One of the following values will be returned:

  • init_status = 0 — OK — The engine did not detect any critical errors during the initialization, or they were automatically corrected or ignored. The engine initialized successfully.

  • init_status = -1 — Warning — At least one initialization path is invalid. The engine initialized in a degraded mode.

  • init_status = 1 — Error — At least one initialization path is invalid. The engine could not be initialized.

  • init_status = -2 — Warning — There was not enough memory for full initialization. The engine initialized in a degraded mode.

  • init_status = 2 — Error — There was not enough memory for full initialization. The engine could not be initialized.

  • init_status = -3 or any other negative value indicates that an unspecified or unknown warning was encountered during the initialization and the engine initialized in a degraded mode.

  • init_status = 3 or any other positive value indicates that an unspecified or unknown error was encountered during the initialization and the engine could not be initialized.

reserved1 — reserved for future and must be set to 0.

reserved2 — reserved for future and must be set to 0.

reserved3 — reserved for future and must be set to DV_NULL.

reserved4 — reserved for future and must be set to DV_NULL.

Return Value

If the initialization was successful, the return value is 1 and engine holds a handle of the newly created Standard 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 Standard Engine by calling the dtEngineIniViaStream function more than once. Each instance is created dynamically and must be destroyed by calling the dtEngineExt function before the application terminates. In multi-threaded applications, each thread can initialize its own Standard 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 Standard Engine instances may require a significant amount of RAM.

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 Standard Engine instance is destroyed by calling dtEngineExt. 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 dtEngineIniViaStream 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.

 

Index