The pdImgAddPlus (or pdImgAdd) function adds a PowerDoc image of the PowerDoc object obj at the top of the specified PowerDoc page and sets its X, Y coordinates, transformation matrix, visibility and other applicable parameters.
The return value of this function is the image's index in the Power Engine document. This index uniquely identifies the newly created PowerDoc image.
The only difference between pdImgAddPlus and pdImgAdd is that pdImgAddPlus uses a 3x3 transformation matrix while pdImgAdd uses a 2x2 transformation matrix. Therefore, pdImgAdd is more limited (i.e. this function cannot be used to apply a perspective transform to a PowerDoc image).
Parameter | Description | ||||
---|---|---|---|---|---|
power_doc |
Handle of the associated Power Engine document. | ||||
obj |
Index of the PowerDoc object to be associated with the newly created PowerDoc image. | ||||
page |
The number of the page that will hold the PowerDoc image. Although not a requirement, it is recommended that this value be non-negative. | ||||
x |
X coordinate of the PowerDoc image (or more precisely its origin point) on the page, in document units. | ||||
y |
Y coordinate of the PowerDoc image (or more precisely its origin point) on the page, in document units. | ||||
status |
At present, this parameter can have one of the following values: status = 0 indicates a regular (non-selected) PowerDoc image. The Power Engine API provides additional functions that operate on PowerDoc images depending on their status. For example, pdImgToTop, pdImgToBottom, pdImgMoveToPage, pdImgChangeAttribs, pdImgDelete and many other pdx functions use this value when selecting PowerDoc images. When rendering the page using the library's default settings, selected PowerDoc images are visually marked with a small black square located at their origin point. | ||||
attribs |
Represents additional image attributes. Currently, the following values are supported:
Bit 0 unset — indicates a visible PowerDoc image.
Bit 2 unset — do not use fractional positioning for image origins. All other bits are reserved for future use and must be set to 0. | ||||
mask |
The number of the masking page, i.e. the page whose alpha-channel will be used to mask the newly created PowerDoc image. For example, if the PowerDoc image represents a circle and the mask page contains many vertical stripes, then the resulting PowerDoc image will resemble a vertically striped circle. If masking is not required, mask should be set to 0. | ||||
fn_draw |
A numerical value of the rendering function to be associated with the newly created PowerDoc image. This can be a user-defined value or one of the following pre-defined PowerDoc values:
| ||||
transform |
For pdImgAddPlus, this is a 3x3 transformation matrix. This matrix represents the 2D perspective (or projective) transform to apply to the newly created PowerDoc image. For more information, see the description of the DT_TM3X3 basic data type in this manual. For pdImgAdd, this is a 2x2 transformation matrix. This matrix represents the top two rows and columns of the 2D perspective transform to apply to the newly created PowerDoc image. For more information, see the description of the DT_TM2X2 basic data type in this manual. |
The return value is the images's index in the Power Engine document. This number uniquely identifies the newly created PowerDoc image. For this reason, we sometimes refer to this index as the image's unique serial number.
If an error occurs, the return value will be a negative number.
To avoid unexpected results, rendering functions must be assigned to PowerDoc images in accordance with D-Type's Guidelines For Creating PowerDoc Objects.