Index

C/C++ Functions

dtShapesDoOutput

DT_SWORD dtShapesDoOutput(DT_DTENGINE engine, const DT_LINEDECOR_L* linedecor, DT_ID_SWORD bitmap_flag, DT_SRAST_L x, DT_SRAST_L y, const DT_RECT_L* extent, DT_ID_SWORD flag, const DT_UBYTE i_arr[], const DT_FLOAT x_arr[], const DT_FLOAT y_arr[], DT_BMP* memory_bitmap)

Short Description: Render custom shapes to Output

dtShapesDoOutputFrac

DT_SWORD dtShapesDoOutputFrac(DT_DTENGINE engine, const DT_LINEDECOR_L* linedecor, DT_ID_SWORD bitmap_flag, DT_SRAST_L x, DT_SRAST_L y, const DT_RECT_L* extent, DT_ID_SWORD flag, const DT_UBYTE i_arr[], const DT_SFRAC_L x_arr[], const DT_SFRAC_L y_arr[], DT_BMP* memory_bitmap)

Short Description: Render custom shapes to Output - fractional version

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 dtRasterizerSetFillRule to tell the Rasterizer whether to apply the Odd-Even or Nonzero Winding Number filling rule when identifying interior regions of the shape.

dtShapesDoOutputFrac is identical to dtShapesDoOutput 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

engine

Handle of the previously created Standard Engine instance.

linedecor

See DT_LINEDECOR.

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

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 dtShapesDoOutputFrac is used, all coordinates in the buffer must be in the DT_SFRAC format. If dtShapesDoOutput 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 dtShapesDoOutput 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 dtShapesDoOutput 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 dtOutputSetStyleAttribs 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 dtBitmapFree function.

 

Index