The pdDocDraw 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 pdDocSetTransformPlus, pdDocSetTransform or pdDocSetScale.
Parameter | Description |
---|---|
power_doc |
Handle of the associated Power Engine document. |
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 pdFree. |
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). |
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.
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:
In D-Type Power Engine API, the following memory surface formats are called key memory surface formats:
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. |
Most PowerDoc objects support the full spectrum of D-Type Standard Engine surface formats (see the dtOutputSetAsMDC function). However, there are currently three PowerDoc objects that only support the key memory surface formats described above. These objects are: the Pattern object, the Gradient object and the Bitmap Image object. This is because these three objects are not internally rendered by D-Type Standard Engine (which includes D-Type Rasterizer, D-Type Shape Engine and D-Type Font Engine) but specialized bitmap rendering routines inside D-Type Power Engine. Attempting to render these objects using one of the non key memory surface formats may result in blank output (in either all or some color channels).
A similar limitation might apply to user-defined objects. If a page contains any user-defined objects, they will render only to those memory surface formats that their developer decided to support.
Alpha-masking is only supported when the objects are rendered to the key memory surface formats. Attempting to alpha-mask objects that are rendered to one of the non key memory surface formats may not generate the correct result (in either all or some color channels).
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.
This is only a brief description of the pdDocDraw 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.
pdDocInvertLine, pdDocInvertBox, pdDocInvertFrames