This function draws a single page in the text document (which may contain one or more textflow areas) to a memory surface specified by format, subformat and memory_surface. While drawing the page, the function respects the transform matrix set by txTextSetTransformPlus, txTextSetTransform or txTextSetScale.
Parameter | Description |
---|---|
text_doc |
Handle of the associated text document instance. |
page |
The index of the page in the text document to draw. |
x_off |
Horizontal offset to apply when drawing the textflow area, in pixels. |
y_off |
Vertical offset to apply when drawing the textflow area, in pixels. |
format |
Specifies the format, or number of bits-per-pixel, of the memory surface to which the textflow area is drawn. See below for details. |
subformat |
Color configuration of the pixel. See below for details. |
memory_surface |
A pointer to the DT_MDC structure that describes the surface. See D-Type Standard Engine Manual for details. When calling txTextDraw, it is allowed to set the m member of the DT_MDC structure to DV_NULL. This means that D-Type Unicode Text Module should allocate memory for the surface. In this case, the surface's memory must later be released by calling txFree. |
params |
Additional parameters. See the description of the DT_PD_DOCDRAW_PARAMS structure for details. Set to DV_NULL if no additional parameters are needed (i.e. to use default parameters). |
flags |
Flags to control the way D-Type Unicode Text Module draws the page and generates its text flows and frames. The following values are supported:
Any values not listed above are reserved for future use and must not be used. Note that when the generation of text flows and frames is disabled (values 0, 4, 8), D-Type Unicode Text Module will not be able to provide any text edit, cursor movement and selection highlighting functionality (e.g. using the txTextHit, txTextCommand or txTextSetSelect functions). When the generation of text flows and frames is enabled only for glyphs that are within the visible portion of the page (values 1, 9, 17), D-Type Unicode Text Module will be able to provide limited text edit, cursor movement and selection highlighting functionality (i.e. only within the visible portion of the page). Finally, when the generation of text flows and frames is enabled for all glyphs on the page (values 6, 10, 14, 18, 22), D-Type Unicode Text Module will be able to provide full text edit, cursor movement and selection highlighting functionality on that page. Any text flows and frames generated by this function are available to your application, if you wish to process them using your own code (see Note 1 below). However, if you do so, remember that your application does not own the text flows and frames generated by this function and should not attempt to modify them or free their memory. |
If successful, the function will return 1. If the function is not successful, the return value is 0. This can happen if the input values are invalid or out-of-memory conditions occur (e.g. if D-Type Unicode Text Module is requested to allocate memory for the surface by setting the m member of the DT_MDC structure to DV_NULL and the allocation fails). Additionally, when the processing of critical object-specific errors is enabled via the Flags member of the DT_PD_DOCDRAW_PARAMS structure, the function can also return one of the following error codes:
PD_RET_OBJ_ERR_MDC -8 /* memory surface not supported by object */ PD_RET_OBJ_ERR_PATTERN -7 /* pattern file access error */ PD_RET_OBJ_ERR_BITMAP -6 /* bitmap file access error */ PD_RET_OBJ_ERR_VECTOR -5 /* vector file access error */ PD_RET_OBJ_ERR_FONT -4 /* font file access error */ PD_RET_OBJ_ERR_MEMORY -3 /* not enough memory to process the object */ PD_RET_OBJ_ERR_DEFINITION -2 /* object not properly defined */
If something goes wrong while rendering one of the PowerDoc objects in the text document, these error codes provide more information about the cause of the error. Note that in this situation only the error code of the first encountered object-specific error is returned and only if it is classified as critical (meaning that it has a severe impact on the rendering outcome). It is your application's responsibility to decide how to handle a critical object-specific error (e.g. ignore it, retry rendering, report to the user etc). If the function returns one of these error codes, you should assume that the document has not been rendered completely and/or correctly.
However, if a critical object-specific error is encountered but the processing of critical object-specific errors is disabled, the function will assume that the object in question was rendered successfully and will not return its object-specific error code. In this case, the function might return 1 indicating that overall the rendering was successful, even though some objects in the document did not render completely and/or correctly.
The format parameter specifies the number of bits-per-pixel and is used to calculate the amount of memory required to store the surface; subformat defines the configuration of a single pixel and is used to calculate the maximum number of colors in the surface. See the dtOutputSetAsMDC function in D-Type Standard Engine Manual for a list of all the surface formats supported by D-Type Standard Engine.
Although the txTextDraw function will accept any memory surface format that is supported by D-Type Standard Engine, the following four key memory surface formats are recommended:
These surface formats represent a subset of the full spectrum of D-Type Standard Engine surface formats. The combination format = 8, subformat = 1 represents an alpha-surface and is useful for alpha-making. The combination format = 24, subformat = 0 is a popular and frequently used 24-bpp RGB color surface format. Finally, the combinations format = 32, subformat = 0 and format = 32, subformat = 1 are both commonly used 32-bpp RGB color surface formats.
The following table illustrates the pixel configuration of the key memory surface formats. Please note that this table is merely a striped down version of the table included in D-Type Standard Engine Manual (see the dtOutputSetAsMDC function).
Format (bits-per-pixel) | Subformat | Description |
---|---|---|
8 | 0 |
gggggggg |
8 | 1 |
TTTTTTTT |
8 | 2 |
gggggggg |
8 | 3 |
gggggggg |
8 | 4 |
gggggggg |
8 | 5 |
gggggggg |
8 | 10 |
gggggggg |
8 | 12 |
gggggggg |
8 | 13 |
gggggggg |
8 | 14 |
gggggggg |
8 | 15 |
gggggggg |
16 | 0 |
xBBBBBGG GGGRRRRR |
16 | 1 |
BBBBBBGG GGGRRRRR |
16 | 2 |
BBBBBGGG GGGRRRRR |
16 | 3 |
BBBBBGGG GGRRRRRR |
16 | 4 |
BBBBBGGG GGRRRRRx |
16 | 5 |
BBBBBxGG GGGRRRRR |
16 | 6 |
BBBBBGGG GGxRRRRR |
24 | 0 |
BBBBBBBB GGGGGGGG RRRRRRRR |
32 | 0 |
BBBBBBBB GGGGGGGG RRRRRRRR xxxxxxxx |
32 | 1 |
xxxxxxxx BBBBBBBB GGGGGGGG RRRRRRRR |
Legend: Note 1: RGB and alpha values are stored only for pixels that are actually rendered by D-Type. Your application must ensure that the surface is cleared with appropriate values before rendering. |
For more information on why these four key memory surface formats are recommended, see the pdDocDraw function in D-Type Power Engine Manual.
This is only a brief description of the txTextDraw function. Additional functionality is possible. Please refer to the DT_PD_DOCDRAW_PARAMS structure and the Text Flows and Frames document in the D-Type Workshop section.
When flags is set to instruct D-Type Unicode Text Module to generate text flows and frames and params is not DV_NULL but points to a DT_PD_DOCDRAW_PARAMS structure, the txTextDraw function will internally set the Flows member of that structure to 2 and take complete control over the memory management of its text flows and frames. In this case, as mentioned above, you application may still read the text flows and frames after the function returns (which will be available in DT_PD_FRAME_FORMAT2 format) but must not attempt to free their memory.