These functions draw a custom shape at coordinates (X, Y) of the current Output. The Output provides the destination surface (which can be either D-Type's Memory Device Context surface or Windows compatible Device Context surface) and style attributes that are applied to the shape when its image is actually rendered.
In addition, depending on the value of bitmap_flag, this function makes an attempt to provide your application with a pointer to the shape's plain 8-bit grayscale memory bitmap, provided that the shape image is not completely outside the device context's clipping region.
When the device context redirection is disabled in the Output, the function does not render the shape to the output surface and its behavior heavily depends on the value of the bitmap_flag parameter:
Before rendering the shape, applications can call RasterizerSetFillRule to tell the Rasterizer whether to apply the Odd-Even or Nonzero Winding Number filling rule when identifying interior regions of the shape.
ShapesDoOutputFrac is identical to ShapesDoOutput except that some of its parameters are 24.8 signed fractional values. For more details on fractional units, see the D-Type Units section of this document.
Parameter | Description |
---|---|
linedecor |
See DT_LINEDECOR. |
bitmap_flag |
A hint to the Shape Engine defined as follows:
While the above two basic hints are sufficient for most applications, the following special-purpose hints are also available:
|
x |
X coordinate of the shape's origin point, in pixels. |
y |
Y coordinate of the shape's origin point, in pixels. |
extent |
The coordinates of the imaginary box that fully or partially encloses the shape. This must be a valid pointer to the DT_RECT_SLONG structure. Its members contain the following values: xmn — Minimum X coordinate of the imaginary box in pixels When bitmap_flag is set to 0 (DV_BITMAP_OFF), 1 (DV_BITMAP_ON) or -1 (DV_BITMAP_ON_ONLYIFOPAQUEANDINSIDE) the shape must be completely inside this imaginary enclosing box. When bitmap_flag is set to 2 (DV_BITMAPPART_OFF), 3 (DV_BITMAPPART_ON) or -3 (DV_BITMAPPART_ON_ONLYIFOPAQUEANDINSIDE), the imaginary enclosing box may enclose the shape only partially. Please note that a failure to set the imaginary enclosing box as described here might cause unexpected rendering and/or clipping results. |
flag |
Tells the Shape Engine how the shape is defined. The Shape Engine can render shapes that are defined in six different ways:
See the tables below for details on the mixed, absolute and relative positioning modes. |
i_arr |
Depending on flag, this is either a valid pointer to a user-defined buffer that fully describes the shape or an array that contains instructions that describe the corresponding pair of coordinates in the x_arr and y_arr arrays. See below for details. |
x_arr, y_arr |
An array of control points that define the shape. When flag = 0 (DV_SHAPE_BUFFER_MIXED) or flag = 2 (DV_SHAPE_BUFFER_ABSOLUTE) or flag = 4 (DV_SHAPE_BUFFER_RELATIVE), both arrays are ignored and should be set to DV_NULL. Otherwise, they must be valid array pointers. See below for details. |
memory_bitmap |
A valid pointer to the DT_BMP structure that will receive information about the shape's plain 8-bit grayscale memory bitmap:
You may set memory_bitmap to DV_NULL only if you do not wish to retrieve information about the shape's plain 8-bit grayscale memory bitmap and bitmap_flag is set to 0 (DV_BITMAP_OFF) or 2 (DV_BITMAPPART_OFF). In all other cases, memory_bitmap must be a valid pointer to the DT_BMP structure. |
The return value is 1 if the function was successful. Otherwise, the function returns 0.
As mentioned above, the Shape Engine can render shapes that are defined in six different ways:
If flag = 0 (DV_SHAPE_BUFFER_MIXED) or flag = 2 (DV_SHAPE_BUFFER_ABSOLUTE) or flag = 4 (DV_SHAPE_BUFFER_RELATIVE), then i_arr is a pointer to a buffer that stores a complete description of the custom shape to be rendered. This buffer contains a sequence of instruction-parameters.
In this mode, the New Contour (16) instruction specifies its (X1, Y1) coordinates as absolute positions while all other instructions specify their coordinates as relative deltas. The tables below illustrates the meaning and format of each instruction-parameters sequence:
DT_UBYTE — Instruction | Parameters |
---|---|
New Contour: 16 | |
Line: 20 | |
Quadratic | |
Bézier Curve: 24 |
|
End Of Shape: 8 |
No parameters. |
In this mode all instructions specify their coordinates as absolute positions. The tables below illustrates the meaning and format of each instruction-parameters sequence:
DT_UBYTE — Instruction | Parameters |
---|---|
New Contour: 16 | |
Line: 20 | |
Quadratic | |
Bézier Curve: 24 |
|
End Of Shape: 8 |
No parameters. |
In this mode all instructions specify their coordinates as relative deltas. The tables below illustrates the meaning and format of each instruction-parameters sequence:
DT_UBYTE — Instruction | Parameters |
---|---|
New Contour: 16 | |
Line: 20 | |
Quadratic | |
Bézier Curve: 24 |
|
End Of Shape: 8 |
No parameters. |
*Note: Whether it's DT_FLOAT or DT_SFRAC depends on which version of the function is used. If ShapesDoOutputFrac is used, all coordinates in the buffer must be in the DT_SFRAC format. If ShapesDoOutput is used, all coordinates in the buffer must be in the DT_FLOAT format.
See Example 2 and Example 3 at the end of this manual to see how the ShapesDoOutput function can be used to render some basic geometric shapes using this method.
If flag = 1 (DV_SHAPE_ARRAY_MIXED) or flag = 3 (DV_SHAPE_ARRAY_ABSOLUTE) or flag = 5 (DV_SHAPE_ARRAY_RELATIVE), then i_arr contains instructions that describe the corresponding pair of coordinates in the x_arr and y_arr arrays. Possible values for i_arr are:
The following table describes how the arrays should be created. Please note that Quadratic B-Spline curves require two consecutive rows in each array while Bézier curves require three consecutive rows.
In this mode, the New Contour (16) instruction specifies its (X1, Y1) coordinates as absolute positions while all other instructions specify their coordinates as relative deltas. The tables below illustrates the meaning and format of each instruction-parameters sequence:
i_arr | x_arr | y_arr |
---|---|---|
New Contour — This must always be the first array entry | ||
16 | X1 coordinate in pixels (absolute position) | Y1 coordinate in pixels (absolute position) |
Line | ||
20 | dX1 in pixels (relative delta) | dY1 in pixels (relative delta) |
Quadratic B-Spline Curve | ||
25 | dX1 in pixels (relative delta) | dY1 in pixels (relative delta) |
n | dX2 in pixels (relative delta) | dY2 in pixels (relative delta) |
Bézier Curve | ||
24 | dX1 in pixels (relative delta) | dY1 in pixels (relative delta) |
n | dX2 in pixels (relative delta) | dY2 in pixels (relative delta) |
Must be set to 0. | dX3 in pixels (relative delta) | dY3 in pixels (relative delta) |
End Of Shape — This must always be the last array entry | ||
8 | Must be set to 0. | Must be set to 0. |
In this mode all instructions specify their coordinates as absolute positions. The tables below illustrates the meaning and format of each instruction-parameters sequence:
i_arr | x_arr | y_arr |
---|---|---|
New Contour — This must always be the first array entry | ||
16 | X1 coordinate in pixels (absolute position) | Y1 coordinate in pixels (absolute position) |
Line | ||
20 | X1 in pixels (absolute position) | Y1 in pixels (absolute position) |
Quadratic B-Spline Curve | ||
25 | X1 in pixels (absolute position) | Y1 in pixels (absolute position) |
n | X2 in pixels (absolute position) | Y2 in pixels (absolute position) |
Bézier Curve | ||
24 | X1 in pixels (absolute position) | Y1 in pixels (absolute position) |
n | X2 in pixels (absolute position) | Y2 in pixels (absolute position) |
Must be set to 0. | X3 in pixels (absolute position) | Y3 in pixels (absolute position) |
End Of Shape — This must always be the last array entry | ||
8 | Must be set to 0. | Must be set to 0. |
In this mode all instructions specify their coordinates as relative deltas. The tables below illustrates the meaning and format of each instruction-parameters sequence:
i_arr | x_arr | y_arr |
---|---|---|
New Contour — This must always be the first array entry | ||
16 | dX1 coordinate in pixels (relative delta) | dY1 coordinate in pixels (relative delta) |
Line | ||
20 | dX1 in pixels (relative delta) | dY1 in pixels (relative delta) |
Quadratic B-Spline Curve | ||
25 | dX1 in pixels (relative delta) | dY1 in pixels (relative delta) |
n | dX2 in pixels (relative delta) | dY2 in pixels (relative delta) |
Bézier Curve | ||
24 | dX1 in pixels (relative delta) | dY1 in pixels (relative delta) |
n | dX2 in pixels (relative delta) | dY2 in pixels (relative delta) |
Must be set to 0. | dX3 in pixels (relative delta) | dY3 in pixels (relative delta) |
End Of Shape — This must always be the last array entry | ||
8 | Must be set to 0. | Must be set to 0. |
n = number of curve segments. Set to 0 and this value will be automatically calculated.
See Example 4 at the end of this manual to see how the ShapesDoOutput function can be used to render a simple shape using this method.
The term plain 8-bit grayscale memory bitmap means a grayscale bitmap without any style effects (e.g. transparency, blur, emboss etc). Special effects are applied only when the bitmap is actually rendered to the Output surface (MDC or HDC) in which the style effect is selected using the OutputSetStyleAttribs function. Plain 8-bit grayscale memory bitmaps are sometimes useful to applications that independently post-process plain 8-bit grayscale data.
Finally, when memory_bitmap.m is not DV_NULL, don't forget to release the memory bitmap when it is no longer needed by calling the BitmapFree function.