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.
Parameter | Description |
---|---|
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:
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. |
The return value is 1 if the function was successful. Otherwise, the function returns 0.
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.
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 |
|
New Contour: 16 | |
Line: 20 | |
Quadratic | |
Bézier Curve: 24 |
|
End Of Segments: 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 + Color: 14 |
|
New Contour: 16 | |
Line: 20 | |
Quadratic | |
Bézier Curve: 24 |
|
End Of Segments: 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 + Color: 14 |
|
New Contour: 16 | |
Line: 20 | |
Quadratic | |
Bézier Curve: 24 |
|
End Of Segments: 8 |
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.
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.
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. |
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. |
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.