Index

PowerDoc Objects

Custom Shape or Polygon

Overview

This objects represents a polygon or a custom shape. In Power Engine API, polygons consist of any number of connected straight line segments. Similarly, shapes consist of any number of connected straight and/or curved line segments.

While constructing the Custom Shape or Polygon object, an optional shadow and/or outline may be specified.

Designated Rendering Function: pdDrawPoly (13), pdDrawPolygon (13), pdDrawShape (13)

Note 1: Although pdBodyPtr is a key link, it is not mandatory. This means it is possible to construct a shape/polygon that has no body, only an outline and/or a shadow.

Note 2: pdPolyArrX_08, pdPolyArrX_16, pdPolyArrX_24 and pdPolyArrX_32 cannot be used at the same time. pdPolyArrX_32 takes precedence over pdPolyArrX_24. pdPolyArrX_24 takes precedence over pdPolyArrX_16. Finally, pdPolyArrX_16 takes precedence over pdPolyArrX_08.

Note 3: pdPolyArrY_08, pdPolyArrY_16, pdPolyArrY_24 and pdPolyArrY_32 cannot be used at the same time. pdPolyArrY_32 takes precedence over pdPolyArrY_24. pdPolyArrY_24 takes precedence over pdPolyArrY_16. Finally, pdPolyArrY_16 takes precedence over pdPolyArrY_08.

The following table illustrates how the elements of the pdPolyArrI, pdPolyArrX_32 and pdPolyArrI arrays must be synchronized in order to properly define a straight or curved segment. It is important to note that in order to define a Bezier curve, three consecutive elements in the pdPolyArrI, pdPolyArrX_32 and pdPolyArrY_32 array are required. Similarly, in order to define a Quadratic B-Spline curve, two consecutive elements in the pdPolyArrI, pdPolyArrX_32 and pdPolyArrY_32 array are required.

                         pdPolyArrI  pdPolyArrX_32  pdPolyArrY_32
____________________________________________________________
New Closed Contour 16 X Y
____________________________________________________________
New Open Contour 17 X Y
____________________________________________________________
Line 20 X Y
____________________________________________________________
Bezier Curve 24 X1 Y1
n X2 Y2
0 X3 Y3
____________________________________________________________
Quadratic B-Spline Curve 25 X1 Y1
n X2 Y2
____________________________________________________________
n = suggested number of segments; zero means auto-calculation

pdBodyPtr (1013)

Also appears in: Typography (For Outline Fonts), Row Boundary, Typographic Frame, Library Shape, Rectangle, Circle/Ellipse, True Circle/Ellipse, Slice, Pattern, Grid, Gradient, Gradient (As Fast Rectangle)

Link to the Surface Definition object.

This link supplies style attributes for the body of an object. Style attributes include color, transparency, pattern fills, special effects (e.g. blur, emboss, pattern fill) etc.

pdOutlinePtr (1014)

Also appears in: Typography (For Outline Fonts), Row Boundary, Typographic Frame, Library Shape, Rectangle, Circle/Ellipse, True Circle/Ellipse, Slice, Grid

Link to the Outline Definition object.

This link supplies parameters necessary to render the outline of an object.

pdShadowPtr (1016)

Also appears in: Typography (For Outline Fonts), Baseline, Row Boundary, Typographic Frame, Library Polyline, Library Shape, Line, Rectangle, Circle/Ellipse, True Circle/Ellipse, Slice, Arc, Grid, Polyline (also Bezier and B-Spline curve)

Link to the Shadow Definition object.

Used to render the shadow of a line, shape or some other object.

Properties

pdPolyArrI (1041)   PD_ARR_BYTE_UNSIGNED

Supported Compression Methods: 012, 015

Also appears in: Polyline (also Bezier and B-Spline curve), Text Path, Rich Text Path

Instructions for PolyArrX and PolyArrY (variable length, 1 byte per instruction).

pdPolyArrI is an array containing instructions that describe the corresponding pair of coordinates in the pdPolyArrX_... and pdPolyArrY_... arrays. Possible values for pdPolyArrI are:

A. Standard segment construction instructions:

D-Type Grayscale Rasterizers:

16 = New closed contour
17 = New open contour
20 = Line
24 = Bezier curve. Must be followed by n and 0 (see below).
25 = Quadratic B-Spline curve. Must be followed by n (see below).

D-Type Direct Color RGBA Rasterizers and D-Type Shading Rasterizers extend these instructions:

16 = New closed RGBT contour (the next 4-byte RGBT color value is read from pdPolyArrC)
17 = New open RGBT contour (the next 4-byte RGBT color value is read from pdPolyArrC)
20 = Line (the next 4-byte RGBT color value is unchanged).
24 = Bezier curve (the next 4-byte RGBT color value is unchanged). Must be followed by n and 0 (see below).
25 = Quadratic B-Spline curve (the next 4-byte RGBT color value is unchanged). Must be followed by n (see below).
40 = RGBT Line (the next 4-byte RGBT color value is read from pdPolyArrC)
44 = RGBT Bezier curve (the next 4-byte RGBT color value is read from pdPolyArrC). Must be followed by n and 0 (see below).
45 = RGBT Quadratic B-Spline curve (the next 4-byte RGBT color value is read from pdPolyArrC). Must be followed by n (see below).

B. Instructions that can only follow 24 or 25:

n = A positive number or zero. Used only when the preceding instruction is 24 (Bezier curve) or 25 (Quadratic B-Spline curve). A positive number represents the suggested number of line segments that the curve will be approximated with. Zero means that the rendering engine should automatically calculate the optimum number of line segments when rendering the curve.

0 = Reserved. Used only when the first instruction in a segment is 24.

C. Special "one byte does it all" instructions:

254 = Open Polyline/Polygon - All coordinates in the corresponding pdPolyArrX_... and pdPolyArrY_... arrays are interpreted as Polyline/Polygon vertices connected using straight line segments. There can be no curved segments in this case. As such, no other instructions in pdPolyArrI are needed. Polylines constructed using this method are not automatically closed.

255 = Closed Polyline/Polygon - All coordinates in the corresponding pdPolyArrX_... and pdPolyArrY_... arrays are interpreted as Polyline/Polygon vertices connected using straight line segments. There can be no curved segments in this case. As such, no other instructions in pdPolyArrI are needed. Polylines constructed using this method are automatically closed.

The instruction 254 and 255 are special. Only one of them can be used per single Polyline/Polygon. When specified, this instruction must be the only instruction in the pdPolyArrI array. In other words, pdPolyArrI must be a single element array, containing only the instruction 254 or 255.

Sample values:

"16, 20, 20, 20"
"16, 20, 25, 0, 20"
"16, 20, 20, 24, 0, 0, 20, 25, 10, 20, 20"
"254"
"255"

pdPolyArrX_32 (1042)   PD_ARR_LONG_SIGNED

Supported Compression Methods: 000

Also appears in: Polyline (also Bezier and B-Spline curve), Text Path, Rich Text Path

An array containing X coordinates of segment's control points (variable length, 4 bytes per coordinate).

Sample values:

"0, 400, 300, 200"
"100, 200, -100, -200, -250"
"50, 100, 120, 80, 120, 95, 130, 40, 80, 100, 190"

pdPolyArrX_24 (1140)   PD_ARR_TRIO_SIGNED

Supported Compression Methods: 002

Also appears in: Polyline (also Bezier and B-Spline curve), Text Path, Rich Text Path

An array containing X coordinates of segment's control points (variable length, 3 bytes per coordinate).

Sample values:

"0, 400, 300, 200"
"100, 200, -100, -200, -250"
"50, 100, 120, 80, 120, 95, 130, 40, 80, 100, 190"

pdPolyArrX_16 (1141)   PD_ARR_WORD_SIGNED

Supported Compression Methods: 004

Also appears in: Polyline (also Bezier and B-Spline curve), Text Path, Rich Text Path

An array containing X coordinates of segment's control points (variable length, 2 bytes per coordinate).

Sample values:

"0, 400, 300, 200"
"100, 200, -100, -200, -250"
"50, 100, 120, 80, 120, 95, 130, 40, 80, 100, 190"

pdPolyArrX_08 (1142)   PD_ARR_BYTE_SIGNED

Supported Compression Methods: 006

Also appears in: Polyline (also Bezier and B-Spline curve), Text Path, Rich Text Path

An array containing X coordinates of segment's control points (variable length, 1 byte per coordinate).

Sample values:

"0, 40, 30, 20"
"10, 20, -10, -20, -25"
"5, 10, 12, 8, 12, 9, 13, 4, 8, 10, 19"

pdPolyArrY_32 (1043)   PD_ARR_LONG_SIGNED

Supported Compression Methods: 000

Also appears in: Polyline (also Bezier and B-Spline curve), Text Path, Rich Text Path

An array containing Y coordinates of segment's control points (variable length, 4 bytes per coordinate).

Sample values:

"0, 100, 350, 200"
"200, 200, -200, -200, 100"
"-50, -90, -20, -80, -120, 10, 30, 20, -20, 10, 50"

pdPolyArrY_24 (1143)   PD_ARR_TRIO_SIGNED

Supported Compression Methods: 002

Also appears in: Polyline (also Bezier and B-Spline curve), Text Path, Rich Text Path

An array containing Y coordinates of segment's control points (variable length, 3 bytes per coordinate).

Sample values:

"0, 100, 350, 200"
"200, 200, -200, -200, 100"
"-50, -90, -20, -80, -120, 10, 30, 20, -20, 10, 50"

pdPolyArrY_16 (1144)   PD_ARR_WORD_SIGNED

Supported Compression Methods: 004

Also appears in: Polyline (also Bezier and B-Spline curve), Text Path, Rich Text Path

An array containing Y coordinates of segment's control points (variable length, 2 bytes per coordinate).

Sample values:

"0, 100, 350, 200"
"200, 200, -200, -200, 100"
"-50, -90, -20, -80, -120, 10, 30, 20, -20, 10, 50"

pdPolyArrY_08 (1145)   PD_ARR_BYTE_SIGNED

Supported Compression Methods: 006

Also appears in: Polyline (also Bezier and B-Spline curve), Text Path, Rich Text Path

An array containing Y coordinates of segment's control points (variable length, 1 byte per coordinate).

Sample values:

"0, 10, 35, 20"
"20, 20, -20, -20, 10"
"-5, -9, -2, -8, -12, 1, 3, 2, -2, 1, 5"

pdPolyArrC (1146)   PD_ARR_BYTE_UNSIGNED

An array containing RGBT values of each contour (variable length, 4 bytes per contour). This property should be used when each contour in the polygon has a different RGBA value (color and/or transparency). Additionally, the presence of this array is a signal to D-Type Power Engine to render the body of the polygon using D-Type Direct Color RGBA Rasterizer. This ensures the best possible output quality.

Sample values:

"255, 128, 140, 0"
"255, 128, 140, 0, 145, 185, 64, 128"

pdPolyFillRule (1064)   PD_BYTE_UNSIGNED

Fill rule (for polygons and shapes)

Supported values:

0 = Odd-Even Rule
1 = Nonzero Winding Number Rule

pdStitching (1153)   PD_BYTE_UNSIGNED

Pixel Stitching. This property is respected only when polygons/shapes are rendered using the Reference RGBA Rasterizer. In all other cases it is ignored.

Supported values:

0 = Default
1 = Coarse
2 = Average
3 = Fine
4 = Best

pdRasterizer (1154)   PD_BYTE_UNSIGNED

Rasterizer.

Supported values:

0 = Default Grayscale Rasterizer

When pdPolyArrC is used:

D-Type Direct Color RGBA Rasterizers and D-Type Shading Rasterizers

0 = Direct Color RGBA Rasterizer: Ultra-Fast Rasterizer
1 = Direct Color RGBA Rasterizer: No-Overlap Rasterizer
2 = Direct Color RGBA Rasterizer: Reference Rasterizer
3 = Direct Color RGBA Rasterizer: Alpha-Blend Rasterizer
10 = Shading Rasterizer: Mean Value Coordinates - Algorithm A
11 = Shading Rasterizer: Mean Value Coordinates - Algorithm B
12 = Shading Rasterizer: Inverse Distance Weighting
13 = Shading Rasterizer: Gouraud Shading With Anti-Aliased Edges
15 = Shading Rasterizer: Gouraud Shading Without Anti-Aliased Edges
16 = Shading Rasterizer: Distance Field Method A
17 = Shading Rasterizer: Distance Field Method B

Example

C/C++

DT_ID_SLONG obj[6];

obj[0] = pdObjAdd(pd, 0, "Poly Outline Style");
obj[1] = pdObjAdd(pd, 0, "Poly Body Style");
obj[2] = pdObjAdd(pd, 0, "Poly Shadow Style");
obj[3] = pdObjAdd(pd, 0, "Poly Outline");
obj[4] = pdObjAdd(pd, 0, "Poly Shadow");
obj[5] = pdObjAdd(pd, 0, "Poly");

/* Properties for object 0 */
pdPropAdd(pd, obj[0], pdRGBT, "50641400", PD_HEX);

/* Properties for object 1 */
pdPropAdd(pd, obj[1], pdRGBT, "B4961400", PD_HEX);

/* Properties for object 2 */
pdPropAdd(pd, obj[2], pdRGBT, "80808078", PD_HEX);

/* Properties for object 3 */
pdLinkAdd(pd, obj[3], pdStylePtr, obj[0]);
pdPropAdd(pd, obj[3], pdLineThickness, "240", PD_WORD_SIGNED);

/* Properties for object 4 */
pdLinkAdd(pd, obj[4], pdStylePtr, obj[2]);
pdPropAdd(pd, obj[4], pdShadowDx, "5", PD_WORD_SIGNED);
pdPropAdd(pd, obj[4], pdShadowDy, "5", PD_WORD_SIGNED);

/* Properties for object 5 */
pdLinkAdd(pd, obj[5], pdBodyPtr, obj[1]);
pdLinkAdd(pd, obj[5], pdOutlinePtr, obj[3]);
pdLinkAdd(pd, obj[5], pdShadowPtr, obj[4]);
pdPropAdd(pd, obj[5], pdPolyArrI, "16, 20, 25, 20, 20", PD_ARR_BYTE_UNSIGNED);
pdPropAdd(pd, obj[5], pdPolyArrX_32, "0, 400, 300, 200, -60", PD_ARR_LONG_SIGNED);
pdPropAdd(pd, obj[5], pdPolyArrY_32, "0, 100, 350, 200, 100", PD_ARR_LONG_SIGNED);


/* Image placement */
pdImgAdd(pd, obj[5], 0, 100, 100, 0, 0, 0, pdDrawPoly, DV_NULL);

INTEGRAL DSL

/* Lambda shortcuts */

local o = @(label = "") CDTObj(::my.doc, label); /* to make object */
local p = @(id, str, len = PD_DEFAULT) CDTProp(id, str, len); /* to add property - general */
local s = @(id, str) CDTPropStr(id, str); /* to add property - string */
local i = @(id, num) CDTPropInt(id, num); /* to add property - integer */
local l = @(id, obj) CDTLink(id, obj); /* to add link */

/* Objects */

local obj_0 = o("Poly Outline Style");
local obj_1 = o("Poly Body Style");
local obj_2 = o("Poly Shadow Style");
local obj_3 = o("Poly Outline");
local obj_4 = o("Poly Shadow");
local obj_5 = o("Poly");

/* Object Properties */

obj_0 + s(pdRGBT, "50641400");

obj_1 + s(pdRGBT, "B4961400");

obj_2 + s(pdRGBT, "80808078");

obj_3 + l(pdStylePtr, obj_0);
obj_3 + i(pdLineThickness, 240);

obj_4 + l(pdStylePtr, obj_2);
obj_4 + i(pdShadowDx, 5);
obj_4 + i(pdShadowDy, 5);

obj_5 + l(pdBodyPtr, obj_1);
obj_5 + l(pdOutlinePtr, obj_3);
obj_5 + l(pdShadowPtr, obj_4);
obj_5 + p(pdPolyArrI, "16, 20, 25, 20, 20");
obj_5 + p(pdPolyArrX_32, "0, 400, 300, 200, -60");
obj_5 + p(pdPolyArrY_32, "0, 100, 350, 200, 100");

/* Image Pinning */

obj_5.Pin(0, 100, 100, pdDrawPoly);
 

Index