Index

CDTEngineV8

ShapeDoOutput

ShapeDoOutputFrac

ShapeDoOutputPlus

ShapeDoOutputFracPlus

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.

ShapeDoOutputFrac is identical to ShapeDoOutput 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.

Parameters

ParameterDescription

bitmap_flag

A hint to the Shape Engine defined as follows:

  • If bitmap_flag = 0 (DV_BITMAP_OFF), the function will not attempt to retrieve an 8-bit grayscale bitmap for the shape. In this case, memory_bitmap.m will always be set to DV_NULL.

  • If bitmap_flag = 1 (DV_BITMAP_ON), the function will make an attempt to retrieve the bitmap.

While the above two basic hints are sufficient for most applications, the following special-purpose hints are also available:

  • If bitmap_flag = -1 (DV_BITMAP_ON_ONLYIFOPAQUEANDINSIDE), the function will make an attempt to retrieve the bitmap only if its extent box (which is described below) is fully inside the output surface and the shape is not completely transparent.

  • bitmap_flag = 2 (DV_BITMAPPART_OFF) indicates that the shape is not fully enclosed by the extent box described below and the function will not attempt to retrieve its 8-bit grayscale bitmap. In this case, memory_bitmap.m will always be set to DV_NULL.

  • bitmap_flag = 3 (DV_BITMAPPART_ON) indicates that the shape is not fully enclosed by the extent box described below but the function will attempt to retrieve its partial 8-bit grayscale bitmap.

  • bitmap_flag = -3 (DV_BITMAPPART_ON_ONLYIFOPAQUEANDINSIDE) indicates that the shape is not fully enclosed by the extent box described below; the function will attempt to retrieve its partial 8-bit grayscale bitmap only if this extent box is fully inside the output surface and the shape is not completely transparent.

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
ymn — Minimum Y coordinate of the imaginary box in pixels
xmx — Maximum X coordinate of the imaginary box in pixels
ymx — Maximum Y 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:

  • If flag = 0 (DV_SHAPE_BUFFER_MIXED), the shape is defined via a buffer using a mixed positioning mode. In this case, i_arr is a pointer to a buffer that fully describes the shape to be rendered while x_arr and y_arr are ignored and should be both set to DV_NULL.

  • If flag = 2 (DV_SHAPE_BUFFER_ABSOLUTE), the shape is defined via a buffer using an abolute positioning mode. In this case, i_arr is a pointer to a buffer that fully describes the shape to be rendered while x_arr and y_arr are ignored and should be both set to DV_NULL.

  • If flag = 4 (DV_SHAPE_BUFFER_RELATIVE), the shape is defined via a buffer using a relative positioning mode. In this case, i_arr is a pointer to a buffer that fully describes the shape to be rendered while x_arr and y_arr are ignored and should be both set to DV_NULL.

  • If flag = 1 (DV_SHAPE_ARRAY_MIXED), the shape is defined via the i_arr, x_arr and y_arr arrays using a mixed positioning mode. In this case all three values must be valid array pointers.

  • If flag = 3 (DV_SHAPE_ARRAY_ABSOLUTE), the shape is defined via the i_arr, x_arr and y_arr arrays using an abolute positioning mode. In this case all three values must be valid array pointers.

  • If flag = 5 (DV_SHAPE_ARRAY_RELATIVE), the shape is defined via the i_arr, x_arr and y_arr arrays using a relative positioning mode. In this case all three values must be valid array pointers.

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:

  • memory_bitmap.m — pointer to a memory buffer at which the grayscale memory bitmap data begins. This buffer is dynamically allocated and must be released later by calling the BitmapFree function. The buffer always contains plain 8-bpp grayscale bitmap (non-compressed) data. If DV_NULL, the bitmap image could not be retrieved or was not requested. In this case all other member variables will be set to 0.

  • memory_bitmap.l — length of the memory buffer in bytes as defined by the DT_BMP structure

  • memory_bitmap.w — width of the bitmap in pixels as defined by the DT_BMP structure

  • memory_bitmap.h — height of the bitmap in pixels as defined by the DT_BMP structure

  • memory_bitmap.x — horizontal distance between the bitmap's left edge and shape's origin in pixels as defined by the DT_BMP structure

  • memory_bitmap.y — vertical distance between the shape's origin and bitmap's top edge in pixels as defined by the DT_BMP structure

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.

thickness

When positive, this parameter represents the amount of outline thickness in 1/100 pixels. In this case the shape will be rendered outlined. When negative, this parameter represents the amount of outline expansion in 1/100 pixels. In this case the shape will be rendered dilated. If zero, the shape will be rendered in standard mode (without any outline effects).

segment

This parameter is used in conjunction with the thickness parameter. More precisely, when thickness is non-zero, then segment can be used to indicate that the outline should be subdivided into a number of smaller segments (each consisting of a dash and a gap) so that the overall shape appearance is dashed.

The value of the segment parameter indicates the desired length of a single segment, in pixels. Each segment consists of a dash and a gap. The dash takes approximately two thirds of the segment's length, while the gap uses the remaining one third. Therefore, if segment is set to 30 pixels, then each dash will be approximately 20 pixels in length while each gap will be approximately 10 pixels in length.

At present this parameter must be non-negative. It should be set to zero if the segments are not desired or if thickness is set to zero. In this case the outline will appear solid and continuous.

Return Value

The return value is 1 if the function was successful. Otherwise, the function returns 0.

Comments

As mentioned above, the Shape Engine can render shapes that are defined in six different ways:

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

    A) Mixed Positioning Mode

    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
    This must always be the first instruction.

    Line: 20

    Quadratic
    B-Spline Curve: 25

    Bézier Curve: 24

    End Of Shape: 8
    This must always be the last instruction.

    No parameters.

    B) Absolute Positioning Mode

    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
    This must always be the first instruction.

    Line: 20

    Quadratic
    B-Spline Curve: 25

    Bézier Curve: 24

    End Of Shape: 8
    This must always be the last instruction.

    No parameters.

    C) Relative Positioning Mode

    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
    This must always be the first instruction.

    Line: 20

    Quadratic
    B-Spline Curve: 25

    Bézier Curve: 24

    End Of Shape: 8
    This must always be the last instruction.

    No parameters.

    *Note: Whether it's DT_FLOAT or DT_SFRAC depends on which version of the function is used. If ShapeDoOutputFrac is used, all coordinates in the buffer must be in the DT_SFRAC format. If ShapeDoOutput 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 ShapeDoOutput function can be used to render some basic geometric shapes using this method.

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

    A) Mixed Positioning Mode

    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.

    B) Absolute Positioning Mode

    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.

    C) Relative Positioning Mode

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



 

Index