Index

C/C++ Functions

dcRasterizerMultiSegment

DT_SWORD dcRasterizerMultiSegment(DT_DCRASTER dcr, DT_FLOAT x, DT_FLOAT y, DT_ID_SWORD flag, const DT_UBYTE i_arr[], const DT_UBYTE c_arr[], const DT_FLOAT x_arr[], const DT_FLOAT y_arr[])

Short Description: MultiSegment command

dcRasterizerMultiSegmentFrac

DT_SWORD dcRasterizerMultiSegmentFrac(DT_DCRASTER dcr, DT_SFRAC_L x, DT_SFRAC_L y, DT_ID_SWORD flag, const DT_UBYTE i_arr[], const DT_UBYTE c_arr[], const DT_SFRAC_L x_arr[], const DT_SFRAC_L y_arr[])

Short Description: MultiSegmentFrac command

The dcRasterizerMultiSegment (or dcRasterizerMultiSegmentFrac) function instructs D-Type Direct Color Rasterizer to add one or more line and/or curve segments to the current contour and/or one or more contours to the current scene. This function can be used in conjunction with other scene construction functions (dcRasterizerMoveTo, dcRasterizerMoveToFrac, dcRasterizerLineTo, dcRasterizerLineToFrac, dcRasterizerBSplineTo, dcRasterizerBSplineToFrac, dcRasterizerBezierTo, dcRasterizerBezierToFrac) or on its own to create a complete scene that D-Type Direct Color Rasterizer will render by a subsequent call to dcRasterizerDoOutput.

dcRasterizerMultiSegmentFrac is identical to dcRasterizerMultiSegment 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

dcr

Handle of the previously created D-Type Direct Color Rasterizer instance.

x

Horizontal offset to apply to all X coordinates supplied by this function, in pixels.

y

Vertical offset to apply to all Y coordinates supplied by this function, in pixels.

flag

Tells D-Type Direct Color Rasterizer how the segments supplied by this function are defined. The following six options are available:

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

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

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

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

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

  • If flag = 5 (DV_SHAPE_ARRAY_RELATIVE), the segments are defined via the i_arr, c_arr, x_arr and y_arr arrays using a relative positioning mode. In this case all four 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 segments or an array that contains instructions that describe the corresponding pair of coordinates in the c_arr, x_arr and y_arr arrays. See below for details.

c_arr

An array of colors (RGBT values) for each of the contours.

When flag = 0 (DV_SHAPE_BUFFER_MIXED) or flag = 2 (DV_SHAPE_BUFFER_ABSOLUTE) or flag = 4 (DV_SHAPE_BUFFER_RELATIVE), this array is ignored and should be set to DV_NULL. Otherwise, this must be a valid array pointer. See below for details.

x_arr, y_arr

An array of control points that define the segments.

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.

Return Value

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

Comments

As mentioned above, the following six options are available when defining the segments:
  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 segments to be rendered. This buffer contains a sequence of instruction-parameters.

    A) Mixed Positioning Mode

    In this mode, the New Contour (16) and New Contour + Color (14) instructions specify their (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 + Color: 14
    This must always be the first instruction.

    • DT_UBYTE — Reserved. Must be 0.
    • DT_FLOAT or DT_SFRAC* — X1 coordinate in pixels (absolute position)
    • DT_FLOAT or DT_SFRAC* — Y1 coordinate in pixels (absolute position)
    • DT_UBYTE — Color of the new contour — Red component (R). Must be between 0 and 255.
    • DT_UBYTE — Color of the new contour — Green component (G). Must be between 0 and 255.
    • DT_UBYTE — Color of the new contour — Blue component (B). Must be between 0 and 255.
    • DT_UBYTE — Transparency of the new contour (T). Must be between 0 and 255.

    New Contour: 16
    The color and transparency of this contour is identical to the previous contour.

    Line: 20

    Quadratic
    B-Spline Curve: 25

    Bézier Curve: 24

    End Of Segments: 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 + Color: 14
    This must always be the first instruction.

    • DT_UBYTE — Reserved. Must be 0.
    • DT_FLOAT or DT_SFRAC* — X1 coordinate in pixels (absolute position)
    • DT_FLOAT or DT_SFRAC* — Y1 coordinate in pixels (absolute position)
    • DT_UBYTE — Color of the new contour — Red component (R). Must be between 0 and 255.
    • DT_UBYTE — Color of the new contour — Green component (G). Must be between 0 and 255.
    • DT_UBYTE — Color of the new contour — Blue component (B). Must be between 0 and 255.
    • DT_UBYTE — Transparency of the new contour (T). Must be between 0 and 255.

    New Contour: 16
    The color and transparency of this contour is identical to the previous contour.

    Line: 20

    Quadratic
    B-Spline Curve: 25

    Bézier Curve: 24

    End Of Segments: 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 + Color: 14
    This must always be the first instruction.

    • DT_UBYTE — Reserved. Must be 0.
    • DT_FLOAT or DT_SFRAC* — dX1 coordinate in pixels (relative delta)
    • DT_FLOAT or DT_SFRAC* — dY1 coordinate in pixels (relative delta)
    • DT_UBYTE — Color of the new contour — Red component (R). Must be between 0 and 255.
    • DT_UBYTE — Color of the new contour — Green component (G). Must be between 0 and 255.
    • DT_UBYTE — Color of the new contour — Blue component (B). Must be between 0 and 255.
    • DT_UBYTE — Transparency of the new contour (T). Must be between 0 and 255.

    New Contour: 16
    The color and transparency of this contour is identical to the previous contour.

    Line: 20

    Quadratic
    B-Spline Curve: 25

    Bézier Curve: 24

    End Of Segments: 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 dcRasterizerMultiSegmentFrac is used, all coordinates in the buffer must be in the DT_SFRAC format. If dcRasterizerMultiSegment is used, all coordinates in the buffer must be in the DT_FLOAT format.

  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. Additionally, the c_arr array contains color and transparency (R, G, B, T) values for all New contour + Color (14) instructions. 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) and New Contour + Color (14) instructions specify their (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 c_arr x_arr y_arr
    New Contour + Color — This must always be the first array entry

    14

    R, G, B, T

    X1 coordinate in pixels (absolute position)

    Y1 coordinate in pixels (absolute position)

    New Contour — The color and transparency of this contour is identical to the previous contour

    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 Segments — 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 c_arr x_arr y_arr
    New Contour + Color — This must always be the first array entry

    14

    R, G, B, T

    X1 coordinate in pixels (absolute position)

    Y1 coordinate in pixels (absolute position)

    New Contour — The color and transparency of this contour is identical to the previous contour

    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 Segments — 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 c_arr x_arr y_arr
    New Contour + Color — This must always be the first array entry

    14

    R, G, B, T

    dX1 coordinate in pixels (relative delta)

    dY1 coordinate in pixels (relative delta)

    New Contour — The color and transparency of this contour is identical to the previous contour

    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 Segments — 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.

 

Index