The txMakeCachedFontmap function creates a cached font map from the standard font map file (typically fontmap.inf).
The cached font map serves the same purpose as the standard font map file (i.e. it specifies what fonts to use for different Unicode scripts) but is optimized for performance. Thus, this font map can be passed to any other D-Type Unicode Text Module functions that accept a font map stream descriptor (e.g. txTextIniViaStream, txTextIniViaBuffer, txTextMakeViaStream, txTextMakeViaBuffer, txTextPasteViaStream, txTextPasteViaBuffer) and the results of the text layout process will be identical. However, the cached font map will make these functions run noticeably faster.
Parameter | Description |
---|---|
engine |
Handle of the previously created D-Type Power Engine instance. See the pdEngineIniViaStream function for details on how to initialize D-Type Power Engine. |
input_fontmap_sd |
A valid pointer to the DT_STREAM_DESC structure which supplies the location of the input font map file. This must be a standard font map file, i.e. a plain text file (not binary). Typically, this is fontmap.inf. When appropriate, your application can provide its own (i.e. altered) version of the fontmap.inf file. |
output_fontmap_sd |
A valid pointer to the DT_STREAM_DESC structure which supplies the location of the output font map file. This will be the cached font map file i.e. an optimized binary file (not plain text). For best performance, the cached font map file should reside in memory. The DT_STREAM_DESC structure then describes a memory based stream. Memory based streams can be processed more quickly than file based streams. See the DT_STREAM_MEMORY macro and the How To Use D-Type Streams And Stream Macros section for more information on memory based streams. Also, see the examples at the bottom of this page. |
reserved |
Reserved for future use. Must be set to 0. |
If the cached font map was created successfully, the return value is 1. Otherwise, the function returns -1.
As mentioned above, the cached font map serves the same purpose as the standard font map file (i.e. it specifies what fonts to use for different Unicode scripts). However, the cached font map is optimized for performance. When passed to txTextIniViaStream, txTextIniViaBuffer, txTextMakeViaStream, txTextMakeViaBuffer or any other D-Type Unicode Text Module functions that accept a font map stream descriptor, it will make them run noticeably faster. The results of the text layout process will be the same as if the standard font map file descriptor was used.
The cached font map is particularly useful in applications that create many text document instances but use the same list of fonts. In these situations the cached font map should be created once and passed many times to txTextIniViaStream, txTextIniViaBuffer, txTextMakeViaStream, txTextMakeViaBuffer or any other D-Type Unicode Text Module functions that accept a font map stream descriptor. For best performance, the cached font map file should reside in memory.
The cached font map is a binary file and its structure will not be discussed here. It should only be created by calling the txMakeCachedFontmap function. Additionally, before calling the txMakeCachedFontmap function, applications must ensure that all the fonts referenced in the standard font map file (fontmap.inf) have been added to D-Type Font Engine's Font Catalog. For more information on the Font Catalog, see D-Type Standard Engine Manual.
See How To Use D-Type Streams And Stream Macros.
See our notes regarding file based streams.
If creating a cached font map file in memory, remember to release the memory when the cached font map file is no longer needed (and after destroying all text document instances that use it).
The following example shows how to create a cached font map (as a file on disk) using the txMakeCachedFontmap function. This cached font map is then used to create a new text document 500 times. The execution time of this process is shown at the end.
DT_SLONG i; DT_TX_TEXTFLOW_AREA textflow_area = {10, 10, 800, 800, TX_RECT, TX_TYPOROW, 0, TX_DIR_ROW_LR_TB, TX_LAY_DEVICE_B, TX_TM_NULL, {DV_NULL}}; DT_STREAM_FILE(sd_text, "sample_text.txt"); /* input file - plain text */ DT_STREAM_FILE(sd_fontmap, "fontmap.inf"); /* input file - standard font map */ DT_STREAM_FILE(sd_fontmap_cached, "fontmap-cached.inf"); /* output file - cached font map (will be stored on disk) */ txMakeCachedFontmap(Engine, &sd_fontmap, &sd_fontmap_cached, 0); clock_t clock_start = clock(); for (i = 0; i < 500; i++) { /* create a new text document */ txTextIniViaStream(&TextDoc, Engine, TX_AUTO, &sd_text, TX_IMPORT_UNICODE_BIDI | TX_IMPORT_UNICODE_SCRIPT, &textflow_area, DV_NULL, &sd_fontmap_cached); /* and destroy it */ txTextExt(TextDoc); } clock_t clock_end = clock(); printf("time = %f seconds (%d ticks)\n", (clock_end - clock_start) / (DT_FLOAT)CLOCKS_PER_SEC, clock_end - clock_start);
Output:
time = 1.94 seconds (1940 ticks)
The following example is identical to the one above, except that the cached font map is stored in memory. Again, the execution time of this process is shown at the end.
DT_SLONG i; DT_TX_TEXTFLOW_AREA textflow_area = {10, 10, 800, 800, TX_RECT, TX_TYPOROW, 0, TX_DIR_ROW_LR_TB, TX_LAY_DEVICE_B, TX_TM_NULL, {DV_NULL}}; DT_STREAM_FILE(sd_text, "sample_text.txt"); /* input file - plain text */ DT_STREAM_FILE(sd_fontmap, "fontmap.inf"); /* input file - standard font map */ DT_STREAM_MEMORY(sd_fontmap_cached, DV_NULL, 0); /* output file - cached font map (will be stored in memory) */ txMakeCachedFontmap(Engine, &sd_fontmap, &sd_fontmap_cached, 0); clock_t clock_start = clock(); for (i = 0; i < 500; i++) { /* create a new text document */ txTextIniViaStream(&TextDoc, Engine, TX_AUTO, &sd_text, TX_IMPORT_UNICODE_BIDI | TX_IMPORT_UNICODE_SCRIPT, &textflow_area, DV_NULL, &sd_fontmap_cached); /* and destroy it */ txTextExt(TextDoc); } txFree(sd_fontmap_cached.stream_locator.mem_w.addr); /* release memory that txMakeCachedFontmap allocated for the cached font map */ clock_t clock_end = clock(); printf("time = %f seconds (%d ticks)\n", (clock_end - clock_start) / (DT_FLOAT)CLOCKS_PER_SEC, clock_end - clock_start);
Output:
time = 1.62 seconds (1620 ticks)
The final example is similar to the first two, except that this time no cached font map is used. As it can be seen, the execution time of this process is noticeably higher than in the first two examples.
DT_SLONG i; DT_TX_TEXTFLOW_AREA textflow_area = {10, 10, 800, 800, TX_RECT, TX_TYPOROW, 0, TX_DIR_ROW_LR_TB, TX_LAY_DEVICE_B, TX_TM_NULL, {DV_NULL}}; DT_STREAM_FILE(sd_text, "sample_text.txt"); /* input file - plain text */ DT_STREAM_FILE(sd_fontmap, "fontmap.inf"); /* input file - standard font map */ clock_t clock_start = clock(); for (i = 0; i < 500; i++) { /* create a new text document */ txTextIniViaStream(&TextDoc, Engine, TX_AUTO, &sd_text, TX_IMPORT_UNICODE_BIDI | TX_IMPORT_UNICODE_SCRIPT, &textflow_area, DV_NULL, &sd_fontmap); /* and destroy it */ txTextExt(TextDoc); } clock_t clock_end = clock(); printf("time = %f seconds (%d ticks)\n", (clock_end - clock_start) / (DT_FLOAT)CLOCKS_PER_SEC, clock_end - clock_start);
Output:
time = 4.16 seconds (4160 ticks)