Index

CDTDocV8

Draw

The Draw function draws a single page in a Power Engine document to a memory surface specified by format, subformat and memory_surface. While drawing the page, the function respects the transform matrix set by SetTransformPlus, SetTransform or SetScale.

Parameters

ParameterDescription

page

The number of the page to draw.

x_off

Horizontal offset to apply when drawing the page area, in pixels.

y_off

Vertical offset to apply when drawing the page area, in pixels.

format

Specifies the format, or number of bits-per-pixel, of the memory surface to which the page 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 pdDocDraw, it is allowed to set the m member of the DT_MDC structure to DV_NULL. This means that D-Type Power Engine should allocate memory for the surface. In this case, the surface's memory must later be released by calling Free.

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).

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 Power Engine 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 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 pdDocDraw function will accept any memory surface format that is supported by D-Type Standard Engine, certain limitations apply. Application developers should note the following:

Note to application developers who wish to implement user-defined PowerDoc objects:

If you wish to extend Power Engine API by developing your own user-defined objects then you should also ensure that these objects can be rendered to as many surface formats as possible. Although not mandatory, we strongly recommend that your objects support all the key memory surface formats. In addition, you should ensure that your objects can be rendered to both the top-to-bottom and bottom-to-top surfaces.

Because of the above considerations, we recommend that you render user-defined objects using D-Type Standard Engine (D-Type Rasterizer and/or D-Type Shape Engine and/or D-Type Font Engine). In this way you will not have to spend time developing your own routines to support various surface formats and pixel configurations. At the same time, users of those objects will get automatic support for all the memory surface formats that are supported by D-Type Standard Engine.

Note 1

This is only a brief description of the Draw 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.



 

Index