There are two ways to use the Text Layout Extension: without the built-in caching subsystem and with the built-in caching subsystem.
A typical life cycle of an application that uses D-Type Layout Extension without its built-in caching subsystem is briefly summarized in the following table:
Step | Function |
---|---|
1. For a given script and font, initialize text layout instance | lxLayoutIni or lxLayoutIniPlus |
2. Apply text layout instance to a run of text (array of Unicode characters) | lxLayoutApply or lxLayoutApplyPlus |
3. For each positioned glyph in the returned output glyph array, scale its font dependent (x, y) coordinates to the screen coordinates (pixels) and render glyphs using D-Type Font Engine | dtGlyphDoOutput |
4. Deinitialize (destroy) layout instance | lxLayoutExt |
This approach is suitable if you don't require services of the built-in caching subsystem or whish to implement your own caching system. For a given script and font, your application calls lxLayoutIni or lxLayoutIniPlus to get the corresponding text layout instance. You can call lxLayoutIni or lxLayoutIniPlus to create as many text layout instances as needed (optionally, those instances can be cached by your application). To apply a text layout instance to a run of text, simply call lxLayoutApply or lxLayoutApplyPlus. All created text layout instances must be destroyed by calling lxLayoutExt either when they are no longer needed or before your application terminates.
Please remember that each call to lxLayoutIni or lxLayoutIniPlus takes some time because the corresponding font must be accessed to obtain any required font layout tables. Therefore, avoid calling lxLayoutIni or lxLayoutIniPlus repeatedly for the same script and font. Alternatively, use the built-in caching subsystem to speed up the text layout process.
A typical life cycle of an application that uses D-Type Layout Extension with its built-in caching subsystem is briefly summarized in the following table:
Step | Function |
---|---|
1. Initialize the layout cache | lxCacheIni |
2. For a given script and font, obtain text layout instance from the layout cache | lxCacheObtainLayout or lxCacheObtainLayoutPlus |
3. Apply text layout instance to a run of text (array of Unicode characters) | lxLayoutApply or lxLayoutApplyPlus |
4. For each positioned glyph in the returned output glyph array, scale its font dependent (x, y) coordinates to the screen coordinates (pixels) and render glyphs using D-Type Font Engine | dtGlyphDoOutput |
4. Deinitialize (destroy) the layout cache | lxCacheExt |
This approach is similar to the one described above, but takes advantage of the built-in caching system. This system caches created text layout instance so they can be quickly re-applied to multiple runs of text.
With this approach clients first call lxCacheIni to create the layout cache object. Your application will typically create one layout cache object. Your application is then responsible for destroying this object by calling lxCacheExt before its termination.
Next, for a given script and font, your application calls lxCacheObtainLayout or lxCacheObtainLayoutPlus to get the corresponding text layout instance. This call is usually quick, because if the requested text layout instance is already in the layout cache, the corresponding font will not be accessed. Keep in mind that the returned text layout instance is under exclusive control of the caching subsystem; your application does not own the returned text layout instance and must not attempt to destroy it. Also, you must remember that this instance is valid only until the next call to lxCacheObtainLayout / lxCacheObtainLayoutPlus (or lxCacheClear / lxCacheClearPlus). This is because subsequent requests for additional text layout instances might empty the layout cache and invalidate your text layout instance. Therefore, use the lxCacheObtainLayout or lxCacheObtainLayoutPlus functions just before laying out a run of text.
Please note that the above table only identifies the most important steps and functions. Your application might need additional steps and/or functions.