Index

C/C++ Functions

txTextDraw

DT_SLONG txTextDraw(DT_TXDOC text_doc, DT_SLONG page, DT_SRAST_L x_off, DT_SRAST_L y_off, DT_ID_SWORD format, DT_ID_SWORD subformat, DT_MDC* memory_surface, DT_PD_DOCDRAW_PARAMS* params, DT_ID_SWORD flags)

Short Description: Draw textflow areas on the specified page of the text document

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.

Parameters

ParameterDescription

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:

  • 0 (TX_DRAW_DEFAULT_A) = Same as 8

  • 1 (TX_DRAW_DEFAULT_B) = Same as 17

  • 4 (TX_DRAW_NONE) = Do not draw anything; do not generate text flows and frames (the function does nothing in this case)

  • 6 (TX_DRAW_NONE_ALLFRAMES) = Do not draw anything; generate text flows and frames for all glyphs on the page

  • 8 (TX_DRAW_TEXT) = Draw text only; do not generate text flows and frames

  • 9 (TX_DRAW_TEXT_VISIBLEFRAMES) = Draw text only; generate text flows and frames only for glyphs that are within the visible portion of the page

  • 10 (TX_DRAW_TEXT_ALLFRAMES) = Draw text only; generate text flows and frames for all glyphs on the page

  • 14 (TX_DRAW_MARKERS_ALLFRAMES) = Draw the cursor and any highlighted text selections only; generate text flows and frames for all glyphs on the page

  • 17 (TX_DRAW_TEXT_MARKERS_VISIBLEFRAMES) = First draw text, then draw the cursor and any highlighted text selections; generate text flows and frames only for glyphs that are within the visible portion of the page

  • 18 (TX_DRAW_TEXT_MARKERS_ALLFRAMES) = First draw text, then draw the cursor and any highlighted text selections; generate text flows and frames for all glyphs on the page

  • 22 (TX_DRAW_MARKERS_TEXT_ALLFRAMES) = First draw the cursor and any highlighted text selections, then draw text; generate text flows and frames for all glyphs on the page

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.

Return Value

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.

Comments

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-bit grayscale surface (RGB averaging mode). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = (0.33333*R + 0.33333*G + 0.33333*B).

8

1

TTTTTTTT
8-bit alpha surface. Eight bits (1 byte) are used to represent transparency. 256 alpha values.

8

2

gggggggg
8-bit grayscale surface (RGB normalized mode). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = (0.21268*R + 0.7151*G + 0.07217*B).

8

3

gggggggg
8-bit grayscale surface (R channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = R.

8

4

gggggggg
8-bit grayscale surface (G channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = G.

8

5

gggggggg
8-bit grayscale surface (B channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = B.

8

10

gggggggg
8-bit grayscale surface (inverted RGB averaging mode). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = 255 - (0.33333*R + 0.33333*G + 0.33333*B).

8

12

gggggggg
8-bit grayscale surface (inverted RGB normalized mode). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = 255 - (0.21268*R + 0.7151*G + 0.07217*B).

8

13

gggggggg
8-bit grayscale surface (inverted R channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = 255 - R.

8

14

gggggggg
8-bit grayscale surface (inverted G channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = 255 - G.

8

15

gggggggg
8-bit grayscale surface (inverted B channel). Eight bits (1 byte) are used to represent the relative intensities of gray. 256 intensities calculated as g = 255 - B.

16

0

xBBBBBGG GGGRRRRR
16-bit RGB surface (1-5-5-5). Five bits are used for each color component. The first bit is not used. 32768 colors.

16

1

BBBBBBGG GGGRRRRR
16-bit RGB surface (6-5-5). Six bits are used for red; five bits are used for green and blue. 65,536 colors.

16

2

BBBBBGGG GGGRRRRR
16-bit RGB surface (5-6-5). Six bits are used for green; five bits are used for red and blue. 65,536 colors.

16

3

BBBBBGGG GGRRRRRR
16-bit RGB surface (5-5-6). Six bits are used for blue; five bits are used for red and green. 65,536 colors.

16

4

BBBBBGGG GGRRRRRx
16-bit RGB surface (5-5-5-1). Five bits are used for each color component. The last bit is not used. 32768 colors.

16

5

BBBBBxGG GGGRRRRR
16-bit RGB surface (5-1-5-5). Five bits are used for each color component. The bit between red and green component is not used. 32768 colors.

16

6

BBBBBGGG GGxRRRRR
16-bit RGB surface (5-5-1-5). Five bits are used for each color component. The bit between green and blue component is not used. 32768 colors.

24

0

BBBBBBBB GGGGGGGG RRRRRRRR
Standard 24-bit RGB surface. Eight bits (1 byte) are used for each color component. 16,777,216 colors.

32

0

BBBBBBBB GGGGGGGG RRRRRRRR xxxxxxxx
32-bit RGB surface. Eight bits (1 byte) are used for each color component. The last byte is not used. 16,777,216 colors.

32

1

xxxxxxxx BBBBBBBB GGGGGGGG RRRRRRRR
32-bit RGB surface. Eight bits (1 byte) are used for each color component. The first byte is not used. 16,777,216 colors.

Legend:
g = bits used to describe gray
R = bits used to describe red, G = bits used to describe green, B = bits used to describe blue
T = bits used to describe transparency (0=fully opaque, 255=fully transparent)
x = unused bits

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.

Note 1

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.

Note 2

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.

 

Index