View source for DR2D IFF 2-D Objects

= 2-D Object standard format =

FORM DR2D

Description by Ross Cunniff and John Orr

A standard IFF FORM to describe 2D drawings has been sorely needed for a long time. Several commercial drawing packages have been available for some time but none has established its file format as the Amiga standard.  The absence of a 2D drawing standard hinders the development of applications that use 2D drawings as it forces each application to understand several private standards instead of a single one.  Without a standard, data exchange for both the developer and the user is difficult, if not impossible.

The DR2D FORM fills this void. This FORM was developed by Taliesin, Inc. for use as the native file format for their two-dimensional structured drawing package, ProVector.  Saxon Industries and Soft Logik Publishing Corporation are planning to support this new FORM in
the near future.

Many of the values stored in the DR2D FORM are stored as IEEE single precision floating point numbers. These numbers consist of 32 bits, arranged as follows:

  _______________________________________________________________________
 | s e e e e e e e | e m m m m m m m | m m m m m m m m | m m m m m m m m |
  -----------------------------------------------------------------------
   31            24  23            16  15            8   7             0


where: 

        s       is the sign of the number where 1 is negative and 0 is
                  positive. 
        e       is the 8 bit exponent in excess 127 form.  This number
                  is the power of two to which the mantissa is raised
                  (Excess 127 form means that 127 is added to the
                  exponent before packing it into the IEEE number.) 
        m       is the 23 bit mantissa.  It ranges from 1.0000000 to
                  1.999999..., where the leading base-ten one is
                  assumed. 

An IEEE single precision with the value of 0.0000000 has all its bits cleared. 

= The DR2D Chunks =

== FORM ==

FORM (0x464F524D)     /* All drawings are a FORM */

<syntaxhighlight>
        struct FORMstruct {
            ULONG       ID;             /* DR2D */
            ULONG       Size;
        };
</syntaxhighlight>

== DR2D ==

DR2D (0x44523244) /* ID of 2D drawing */

The DR2D chunks are broken up into three groups: the global drawing
attribute chunks, the object attribute chunks, and the object chunks.
The global drawing attribute chunks describe elements of a 2D drawing
that are common to many objects in the drawing.  Document preferences,
palette information, and custom fill patterns are typical
document-wide settings defined in global drawing attribute chunks.
The object attribute chunks are used to set certain properties of the
object chunk(s) that follows the object attribute chunk.  The current
fill pattern, dash pattern, and line color are all set using an object
attribute chunk.  Object chunks describe the actual DR2D drawing.
Polygons, text, and bitmaps are found in these chunks.

== The Global Drawing Attribute Chunks ==

The following chunks describe global attributes of a DR2D document.

=== DRHD ===

DRHD (0x44524844)       /* Drawing header */

The DRHD chunk contains the upper left and lower right extremes of the
document in (X, Y) coordinates.  This chunk is required and should
only appear once in a document in the outermost layer of the DR2D file
(DR2Ds can be nested).

<syntaxhighlight>
        struct DRHDstruct {
            ULONG       ID;
            ULONG       Size;                   /* Always 16 */
            IEEE        XLeft, YTop,
                        XRight, YBot;
        };
</syntaxhighlight>

The point (XLeft,YTop) is the upper left corner of the project and the
point (XRight,YBot) is its lower right corner.  These coordinates not
only supply the size and position of the document in a coordinate
system, they also supply the project's orientation.  If XLeft &lt;
XRight, the X-axis increases toward the right.  If YTop &lt; YBot, the
Y-axis increases toward the bottom.  Other combinations are possible;
for example in Cartesian coordinates, XLeft would be less than XRight
but YTop would be greater than YBot.

=== PPRF ===

PPRF (0x50505249)       /* Page preferences */

The PPRF chunk contains preference settings for ProVector.  Although
this chunk is not required, its use is encouraged because it contains
some important environment information.

<syntaxhighlight>
        struct PPRFstruct {
            ULONG       ID;
            ULONG       Size;
            char        Prefs[Size];
        };
</syntaxhighlight>

DR2D stores preferences as a concatenation of several null-terminated
strings, in the Prefs[] array.  The strings can appear in any order.
The currently supported strings are:

                Units=&lt;unit-type&gt;
                Portrait=&lt;boolean&gt;
                PageType=&lt;page-type&gt;
                GridSize=&lt;number&gt;

where:
                &lt;unit-type&gt;     is either Inch, Cm, or Pica
                &lt;boolean&gt;       is either True or False
                &lt;page-type&gt;     is either Standard, Legal, B4, B5, A3,
                                  A4, A5, or Custom 
                &lt;number&gt;        is a floating-point number

The DR2D FORM does not require this chunk to explicitly state all the
possible preferences.  In the absence of any particular preference
string, a DR2D reader should fall back on the default value.  The
defaults are:

                Units=Inch
                Portrait=True
                PageType=Standard
                GridSize=1.0

=== CMAP ===

CMAP (0x434D4150)       /* Color map (Same as ILBM CMAP) */

This chunk is identical to the ILBM CMAP chunk as described in the IFF
ILBM documentation.

<syntaxhighlight>
        struct CMAPstruct {
            ULONG       ID;
            ULONG       Size;
            UBYTE       ColorMap[Size];
        };
</syntaxhighlight>

ColorMap is an array of 24-bit RGB color values.  The 24-bit value is
spread across three bytes, the first of which contains the red
intensity, the next contains the green intensity, and the third
contains the blue intensity.  Because DR2D stores its colors with
24-bit accuracy, DR2D readers must not make the mistake that some ILBM
readers do in assuming the CMAP chunk colors correspond directly to
Amiga color registers.

=== FONS ===

FONS (0x464F4E53)       /* Font chunk (Same as FTXT FONS chunk) */

The FONS chunk contains information about a font used in the DR2D
FORM.  ProVector does not include support for Amiga fonts.  Instead,
ProVector uses fonts defined in the OFNT FORM which is documented
later in this article.

<syntaxhighlight>
        struct FONSstruct {
            ULONG       ID;
            ULONG       Size;
            UBYTE       FontID;         /* ID the font is referenced by */
            UBYTE       Pad1;           /* Always 0 */
            UBYTE       Proportional;   /* Is it proportional? */
            UBYTE       Serif;          /* does it have serifs? */
            CHAR        Name[Size-4];   /* The name of the font */
        };
</syntaxhighlight>

The UBYTE FontID field is the number DR2D assigns to this font.
References to this font by other DR2D chunks are made using this
number.    

The Proportional and Serif fields indicate properties of this font.
Specifically, Proportional indicates if this font is proportional, and
Serif indicates if this font has serifs.  These two options were
created to allow for font substitution in case the specified font is
not available.  They are set according to these values:

        0       The DR2D writer didn't know if this font is
                  proportional/has serifs. 
        1       No, this font is not proportional/does not have
                  serifs. 
        2       Yes, this font is proportional/does have serifs.

The last field, Name[], is a NULL terminated string containing the
name of the font. 

=== DASH ===

DASH (0x44415348)       /* Line dash pattern for edges */

This chunk describes the on-off dash pattern associated with a line.

<syntaxhighlight>
        struct DASHstruct {
            ULONG       ID;
            ULONG       Size;
            USHORT      DashID;                 /* ID of the dash pattern */
            USHORT      NumDashes;              /* Should always be even */
            IEEE        Dashes[NumDashes];      /* On-off pattern */
        };
</syntaxhighlight>

DashID is the number assigned to this specific dash pattern. References to this dash pattern by other DR2D chunks are made using
this number.

The Dashes[] array contains the actual dash pattern. The first number in the array (element 0) is the length of the "on" portion of the
pattern. The second number (element 1) specifies the "off" portion of the pattern. If there are more entries in the Dashes array, the
pattern will continue.  Even-index elements specify the length of an "on" span, while odd-index elements specify the length of an "off"
span.  There must be an even number of entries.  These lengths are not in the same units as specified in the PPRF chunk, but are multiples of the line width, so a line of width 2.5 and a dash pattern of 1.0, 2.0 would have an "on" span of length 1.0 x 2.5 = 2.5 followed by an "off" span of length 2.0 x 2.5 = 5.  The following figure shows several dash pattern examples.  Notice that for lines longer than the dash pattern, the pattern repeats.

[[File:dr2d-1.png|frame|center|Dash Patterns]]

By convention, DashID 0 is reserved to mean "No line pattern at all", i.e. the edges are invisible.  This DASH pattern should not be defined by a DR2D DASH chunk.  Again by convention, a NumDashes of 0 means that the line is solid.

=== AROW ===

AROW (0x41524F57)       /* An arrow-head pattern */

The AROW chunk describes an arrowhead pattern.  DR2D open polygons
(OPLY) can have arrowheads attached to their endpoints.  See the
description of the OPLY chunk later in this article for more
information on the OPLY chunk.

<syntaxhighlight>
        #define ARROW_FIRST  0x01 /* Draw an arrow on the OPLY's first point */
        #define ARROW_LAST   0x02 /* Draw an arrow on the OPLY's last point */

        struct AROWstruct {
            ULONG       ID;
            ULONG       Size;
            UBYTE       Flags;          /* Flags, from ARROW_*, above */
            UBYTE       Pad0;           /* Should always 0 */
            USHORT      ArrowID;        /* Name of the arrow head */
            USHORT      NumPoints;
            IEEE        ArrowPoints[NumPoints*2];
        };
</syntaxhighlight>

The Flags field specifies which end(s) of an OPLY to place an
arrowhead based on the #defines above.  ArrowID is the number by which
an OPLY will reference this arrowhead pattern.

The coordinates in the array ArrowPoints[] define the arrowhead's
shape.  These points form a closed polygon.  See the section on the
OPLY/CPLY object chunks for a descriptionof how DR2D defines shapes.
The arrowhead is drawn in the same coordinate system relative to the
endpoint of the OPLY the arrowhead is attached to.  The arrowhead's
origin (0,0) coincides with the OPLY's endpoint.  DR2D assumes that
the arrowhead represented in the AROW chunk is pointing to the right
so the proper rotation can be applied to the arrowhead.  The arrow is
filled according to the current fill pattern set in the ATTR object
attribute chunk.

=== FILL ===

FILL (0x46494C4C)       /* Object-oriented fill pattern */

The FILL chunk defines a fill pattern.  This chunk is only valid inside nested DR2D FORMs.  The GRUP object chunk section of this article contans an example of the FILL chunk.

<syntaxhighlight>
struct FILLstruct {
  ULONG       ID;
  ULONG       Size;
  USHORT      FillID;                 /* ID of the fill */
};
</syntaxhighlight>

FillID is the number by which the ATTR object attribute chunk references fill patterns.  The FILL chunk must be the first chunk inside a nested DR2D FORM.  A FILL is followed by one DR2D object plus any of the object attribute chunks (ATTR, BBOX) associated with the object.

[[File:dr2d-2.png|frame|center|Fill Patterns]]

DR2D makes a "tile" out of the fill pattern, giving it a virtual bounding box based on the extreme X and Y values of the FILL's object
(Figure A).  The bounding box shown in Figure A surrounding the pattern (the two ellipses) is invisible to the user.  In concept, this
rectangle is pasted on the page left to right, top to bottom like floor tiles (Figure B). Again, the bounding boxes are not visible.  The
only portion of this tiled pattern that is visible is the part that overlaps the object (Figure C) being filled.  The object's path is
called a clipping path, as it "clips" its shape from the tiled pattern (Figure D).  Note that the fill is only masked on top of
underlying objects, so any "holes" in the pattern will act as a window, leaving visible underlying objects.

=== LAYR ===

LAYR (0x4C415952)       /* Define a layer */

A DR2D project is broken up into one or more layers.  Each DR2D object
is in one of these layers.  Layers provide several useful features.
Any particular layer can be "turned off", so that the objects in the
layer are not displayed.  This eliminates the unnecessary display of
objects not currently needed on the screen.  Also, the user can lock a
layer to protect the layer's objects from accidental changes.
        
<syntaxhighlight>
        struct LAYRstruct {
            ULONG    ID;
            ULONG    Size;
            USHORT   LayerID;              /* ID of the layer */
            char     LayerName[16];        /* Null terminated and padded */
            UBYTE    Flags;                /* Flags, from LF_*, below */
            UBYTE    Pad0;                 /* Always 0 */
        };    
</syntaxhighlight>

LayerID is the number assigned to this layer.  As the field's name
indicates, LayerName[] is the NULL terminated name of the layer.
Flags is a bit field who's bits are set according to the #defines
below:

<syntaxhighlight>
        #define LF_ACTIVE       0x01    /* Active for editing */
        #define LF_DISPLAYED    0x02    /* Displayed on the screen */
</syntaxhighlight>

If the LF_ACTIVE bit is set, this layer is unlocked.  A set
LF_DISPLAYED bit indicates that this layer is currently visible on the
screen.  A cleared LF_DISPLAYED bit implies that LF_ACTIVE is not set.
The reason for this is to keep the user from accidentally editing
layers that are invisible.

== The Object Attribute Chunks ==

=== ATTR ===

ATTR (0x41545452)       /* Object attributes */

The ATTR chunk sets various attributes for the objects that follow it.
The attributes stay in effect until the next ATTR changes the
attributes, or the enclosing FORM ends, whichever comes first.

<syntaxhighlight>
        /* Various fill types */
        #define FT_NONE         0    /* No fill                 */
        #define FT_COLOR        1    /* Fill with color from palette */
        #define FT_OBJECTS      2    /* Fill with tiled objects */

        
        struct ATTRstruct {
            ULONG       ID;
            ULONG       Size;
            UBYTE       FillType;    /* One of FT_*, above      */
            UBYTE       JoinType;    /* One of JT_*, below      */
            UBYTE       DashPattern; /* ID of edge dash pattern */
            UBYTE       ArrowHead;   /* ID of arrowhead to use  */
            USHORT      FillValue;   /* Color or object with which to fill */
            USHORT      EdgeValue;   /* Edge color index        */
            USHORT      WhichLayer;  /* ID of layer it's in     */
            IEEE        EdgeThick;   /* Line width              */
        };
</syntaxhighlight>

FillType specifies what kind of fill to use on this ATTR chunk's
objects.  A value of FT_NONE means that this ATTR chunk's objects are
not filled.  FT_COLOR indicates that the objects should be filled in
with a color.  That color's ID (from the CMAP chunk) is stored in the
FillValue field.  If FillType is equal to FT_OBJECTS, FillValue
contains the ID of a fill pattern defined in a FILL chunk.

JoinType determines which style of line join to use when connecting
the edges of line segments.  The field contains one of these four
values:

<syntaxhighlight>
        /* Join types */
        #define JT_NONE    0            /* Don't do line joins */
        #define JT_MITER        1       /* Mitered join */
        #define JT_BEVEL        2       /* Beveled join */
        #define JT_ROUND        3       /* Round join */
</syntaxhighlight>

DashPattern and ArrowHead contain the ID of the dash pattern and arrow
head for this ATTR's objects.  A DashPattern of zero means that there
is no dash pattern so lines will be invisible.  If ArrowHead is 0,
OPLYs have no arrow head.  EdgeValue is the color of the line
segments.  WhichLayer contains the ID of the layer this ATTR's objects
are in.  EdgeThick is the width of this ATTR's line segments.

=== BBOX ===

BBOX (0x42424F48)       /* Bounding box of next object in FORM */


The BBOX chunk supplies the dimensions and position of a bounding box
surrounding the DR2D object that follows this chunk in the FORM.  A
BBOX chunk can apply to a FILL or AROW as well as a DR2D object.  The
BBOX chunk appears just before its DR2D object, FILL, or AROW chunk.

<syntaxhighlight>
        struct BBOXstruct {
            ULONG       ID;
            ULONG       Size;
            IEEE                XMin, YMin,     /* Bounding box of obj. */
                                XMax, YMax;     /* including line width */
        };
</syntaxhighlight>

In a Cartesian coordinate system, the point (XMin, YMin) is the
coordinate of the lower left hand corner of the bounding box and
(XMax, YMax) is the upper right.  These coordinates take into
consideration the width of the lines making up the bounding box.

=== XTRN ===

XTRN (0x5854524E)       /* Externally controlled object */

The XTRN chunk was created primarily to allow ProVector to link DR2D
objects to ARexx functions. 

<syntaxhighlight>
        struct XTRNstruct {
            ULONG   ID;
            ULONG   Size;
            short   ApplCallBacks;             /* From #defines, below */
            short   ApplNameLength;
            char    ApplName[ApplNameLength];  /* Name of ARexx func to call */
        };
</syntaxhighlight>

ApplName[] contains the name of the ARexx script ProVector calls when
the user manipulates the object in some way.  The ApplCallBacks field
specifies the particular action that triggers calling the ARexx script
according to the #defines listed below.

<syntaxhighlight>
        /* Flags for ARexx script callbacks */
        #define    X_CLONE     0x0001    /* The object has been cloned */
        #define    X_MOVE      0x0002    /* The object has been moved */
        #define    X_ROTATE    0x0004    /* The object has been rotated */
        #define    X_RESIZE    0x0008    /* The object has been resized */
        #define    X_CHANGE    0x0010    /* An attribute (see ATTR) of the 
                                            object has changed */
        #define    X_DELETE    0x0020    /* The object has been deleted */
        #define    X_CUT       0x0040    /* The object has been deleted, but
                                            stored in the clipboard */
        #define    X_COPY      0x0080    /* The object has been copied to the
                                            clipboard */
        #define    X_UNGROUP   0x0100    /* The object has been ungrouped */
</syntaxhighlight>

For example, given the XTRN object:

        FORM xxxx DR2D {
                XTRN xxxx { X_RESIZE | X_MOVE, 10, "Dimension" }
                ATTR xxxx { 0, 0, 1, 0, 0, 0, 0.0 }
                FORM xxxx DR2D {
                        GRUP xxxx { 2 }
                        STXT xxxx { 0, 0.5, 1.0, 6.0, 5.0, 0.0, 4, "3.0" }
                        OPLY xxxx { 2, { 5.5, 5.5, 8.5, 5.5 } }
                }
        }

ProVector would call the ARexx script named Dimension if the user
resized or moved this object.  What exactly ProVector sends depends
upon what the user does to the object.  The following list shows what
string(s) ProVector sends according to which flag(s) are set.  The
parameters are described below.

        X_CLONE     "appl CLONE objID dx dy"
        X_MOVE      "appl MOVE objID dx dy"
        X_ROTATE    "appl ROTATE objID cx cy angle"
        X_RESIZE    "appl RESIZE objID cx cy sx sy"
        X_CHANGE    "appl CHANGE objID et ev ft fv ew jt fn"
        X_DELETE    "appl DELETE objID"
        X_CUT       "appl CUT objID"
        X_COPY      "appl COPY objID"
        X_UNGROUP   "appl UNGROUP objID"

where:
        appl is the name of the ARexx script
        CLONE, MOVE, ROTATE, RESIZE, etc. are literal strings
        objID is the object ID that ProVector assigns to this object
        (dx, dy) is the position offset of the CLONE or MOVE
        (cx, cy) is the point around which the object is rotated or resized
        angle is the angle (in degrees) the object is rotated
        sx and sy are the scaling factors in the horizontal and
          vertical directions, respectively. 
        et is the edge type (the dash pattern index)
        ev is the edge value (the edge color index)
        ft is the fill type
        fv is the fill index
        ew is the edge weight
        jt is the join type
        fn is the font name

The X_CHANGE message reflects changes to the attributes found in the
ATTR chunk. 

If the user resized the XTRN object shown above by factor of 2,
ProVector would call the ARexx script Dimension like this: 

        Dimension RESIZE 1985427 7.0 4.75 2.0 2.0

== The Object Chunks ==

The following chunks define the objects available in the DR2D FORM.

=== VBM ===

VBM  (0x56424D20)       /* Virtual BitMap */

The VBM chunk contains the position, dimensions, and file name of an
ILBM image. 

<syntaxhighlight>
struct VBMstruct {
    IEEE        XPos, YPos,     /* Virtual coords */
                XSize, YSize,   /* Virtual size */
                Rotation;       /* in degrees */
    USHORT      PathLen;        /* Length of dir path */
    char        Path[PathLen];  /* Null-terminated path of file */
};
</syntaxhighlight>

The coordinate (XPos, YPos) is the position of the upper left hand
corner of the bitmap and the XSize and YSize fields supply the x and y
dimensions to which the image should be scaled.  Rotation tells how
many degrees to rotate the ILBM around its upper left hand corner.
ProVector does not currently support rotation of bitmaps and will
ignore this value.  Path contains the name of the ILBM file and may
also contain a partial or full path to the file.  DR2D readers should
not assume the path is correct.  The full path to an ILBM on one
system may not match the path to the same ILBM on another system.  If
a DR2D reader cannot locate an ILBM file based on the full path name
or the file name itself (looking in the current directory), it should
ask the user where to find the image.
 
=== CPLY and OPLY ===

CPLY (0x43504C59)       /* Closed polygon */
OPLY (0x4F504C59)       /* Open polygon */

Polygons are the basic components of almost all 2D objects in the DR2D
FORM.  Lines, squares, circles, and arcs are all examples of DR2D
polygons.  There are two types of DR2D polygons, the open polygon
(OPLY) and the closed polygon (CPLY).  The difference between a closed
and open polygon is that the computer adds a line segment connecting
the endpoints of a closed polygon so that it is a continuous path.  An
open polygon's endpoints do not have to meet, like the endpoints of a
line segment.

<syntaxhighlight>
        struct POLYstruct {
            ULONG       ID;
            ULONG       Size;
            USHORT      NumPoints;
            IEEE        PolyPoints[2*NumPoints];
        };
</syntaxhighlight>

The NumPoints field contains the number of points in the polygon and
the PolyPoints array contains the (X, Y) coordinates of the points of
the non-curved parts of polygons.  The even index elements are X
coordinates and the odd index elements are Y coordinates.

[[File:dr2d-3.png|frame|center|Bezier curves]]

DR2D uses Bezier cubic sections, or cubic splines, to describe curves
in polygons.  A set of four coordinates (P1 through P4) defines the
shape of a cubic spline.  The first coordinate (P1) is the point where
the curve begins.  The line from the first to the second coordinate
(P1 to P2) is tangent to the curve at the first point.  The line from
P3 to P4 is tangent to the cubic section, where it ends at P4.

The coordinates describing the cubic section are stored in the
PolyPoints[] array with the coordinates of the normal points.  DR2D
inserts an indicator point before a set of cubic section points to
differentiate a normal point from the points that describe a curve.
An indicator point has an X value of 0xFFFFFFFF.  The indicator
point's Y value is a bit field.  If this bit field's low-order bit is
set, the points that follow the indicator point make up a cubic
section.

The second lowest order bit in the indicator point's bit field is the
MOVETO flag.  If this bit is set, the point (or set of cubic section
points) starts a new polygon, or subpolygon.  This subpolygon will
appear to be completely separate from other polygons but there is an
important connection between a polygon and its subpolygon.
Subpolygons make it possible to create holes in polygons.  An example
of a polygon with a hole is the letter "O".  The "O" is a filled
circular polygon with a smaller circular polygon within it.  The
reason the inner polygon isn't covered up when the outer polygon is
filled is that DR2D fills are done using the even-odd rule.

The even-odd rule determines if a point is "inside" a polygon by
drawing a ray outward from that point and counting the number of path
segments the ray crosses.  If the number is even, the point is outside
the object and shouldn't be filled.  Conversely, an odd number of
crossings means the point is inside and should be filled.  DR2D only
applies the even-odd rule to a polygon and its subpolygons, so no
other objects are considered in the calculations.

Taliesin, Inc. supplied the following algorithm to illustrate the
format of DR2D polygons.  OPLYs, CPLYs, AROWs, and ProVector's outline
fonts all use the same format:

<syntaxhighlight>
        typedef union {
            IEEE num;
            LONG bits;
        } Coord;

        #define INDICATOR       0xFFFFFFFF
        #define IND_SPLINE      0x00000001
        #define IND_MOVETO      0x00000002

        /* A common pitfall in attempts to support DR2D has
                been to fail to recognize the case when an
                INDICATOR point indicates the following
                coordinate to be the first point of BOTH a
                Bezier cubic and a sub-polygon, ie. the
                value of the flag = (IND_CURVE | IND_MOVETO) */

        Coord   Temp0, Temp1;
        int     FirstPoint, i, Increment;

        /* Initialize the path */
        NewPath();
        FirstPoint = 1;

        /* Draw the path */
        i = 0;
        while( i &lt; NumPoints ) {
            Temp0.num = PolyPoints[2*i];    Temp1.num = PolyPoints[2*i + 1];
            if( Temp0.bits == INDICATOR ) {
                /* Increment past the indicator */
                Increment = 1;
                if( Temp1.bits &amp; IND_MOVETO ) {
                    /* Close and fill, if appropriate */
                    if( ID == CPLY ) {
                        FillPath();
                    }
                    else {
                        StrokePath();
                    }

                    /* Set up the new path */
                    NewPath();
                    FirstPoint = 1;
                }
                if( Temp1.bits &amp; IND_CURVE ) {
                    /* The next 4 points are Bezier cubic control points */
                    if( FirstPoint )
                        MoveTo( PolyPoints[2*i + 2], PolyPoints[2*i + 3] );
                    else
                        LineTo( PolyPoints[2*i + 2], PolyPoints[2*i + 3] );
                    CurveTo(    PolyPoints[2*i + 4], PolyPoints[2*i + 5],
                                PolyPoints[2*i + 6], PolyPoints[2*i + 7],
                                PolyPoints[2*i + 8], PolyPoints[2*i + 9] );
                    FirstPoint = 0;
                    /* Increment past the control points */
                    Increment += 4;
                }
            }
            else {
                if( FirstPoint )
                    MoveTo(     PolyPoints[2*i], PolyPoints[2*i + 1] );
                else
                    LineTo(     PolyPoints[2*i], PolyPoints[2*i + 1] );
                FirstPoint = 0;

                /* Increment past the last endpoint */
                Increment = 1;
            }

            /* Add the increment */
            i += Increment;
        }

        /* Close the last path */
        if( ID == CPLY ) {
            FillPath();
        }
        else {
            StrokePath();
        }
</syntaxhighlight>

=== GRUP ===

GRUP (0x47525550)       /* Group */

The GRUP chunk combines several DR2D objects into one.  This chunk is
only valid inside nested DR2D FORMs, and must be the first chunk in
the FORM.

<syntaxhighlight>
        struct GROUPstruct {
            ULONG       ID;
            ULONG       Size;
            USHORT      NumObjs;
        };
</syntaxhighlight>

The NumObjs field contains the number of objects contained in this
group.  Note that the layer of the GRUP FORM overrides the layer of
objects within the GRUP.  The following example illustrates the layout
of the GRUP (and FILL) chunk.

       FORM { DR2D              /* Top-level drawing... */
                DRHD { ... }    /* Confirmed by presence of DRHD chunk */
                CMAP { ... }    /* Various other things... */
                FONS { ... }
                FORM { DR2D             /* A nested form... */
                        FILL { 1 }      /* Ah!  The fill-pattern table */
                        CPLY { ... }    /* with only 1 object */
                }
                FORM { DR2D             /* Yet another nested form */
                        GRUP { ..., 3 } /* Ah! A group of 3 objects */
                        TEXT { ... }
                        CPLY { ... }
                        OPLY { ... }
                }
                FORM { DR2D             /* Still another nested form */
                        GRUP { ..., 2 } /* A GRUP with 2 objects */
                        OPLY { ... }
                        TEXT { ... }
                }
        }

=== STXT ===

STXT (0x53545854)               /* Simple text */

The STXT chunk contains a text string along with some information on
how and where to render the text. 

<syntaxhighlight>
        struct STXTstruct {
            ULONG       ID;
            ULONG       Size;
            UBYTE       Pad0;           /* Always 0 (for future expansion) */
            UBYTE       WhichFont;      /* Which font to use */
            IEEE        CharW, CharH,   /* W/H of an individual char */
                        BaseX, BaseY,   /* Start of baseline */
                        Rotation;       /* Angle of text (in degrees) */
            USHORT      NumChars;
            char        TextChars[NumChars];
        };
</syntaxhighlight>

The text string is in the character array, TextChars[].  The ID of the
font used to render the text is WhichFont.  The font's ID is set in a
FONS chunk.  The starting point of the baseline of the text is (BaseX,
BaseY).  This is the point around which the text is rotated.  If the
Rotation field is zero (degrees), the text's baseline will originate
at (BaseX, BaseY) and move to the right.  CharW and CharH are used to
scale the text after rotation.  CharW is the average character width
and CharH is the average character height.  The CharW/H fields are
comparable to an X and Y font size.  

=== TPTH ===

TPTH (0x54505448)               /* A text string along a path */

This chunk defines a path (polygon) and supplies a string to render
along the edge of the path.

<syntaxhighlight>
        struct TPTHstruct {
            ULONG   ID;
            ULONG   Size;
            UBYTE   Justification;      /* see defines, below */
            UBYTE   WhichFont;          /* Which font to use */
            IEEE    CharW, CharH;       /* W/H of an individual char    */
            USHORT  NumChars;           /* Number of chars in the string */
            USHORT  NumPoints;          /* Number of points in the path */
            char    TextChars[NumChars];/* PAD TO EVEN #! */
            IEEE    Path[2*NumPoints];  /* The path on which the text lies */
        };
</syntaxhighlight>

WhichFont contains the ID of the font used to render the text.
Justification controls how the text is justified on the line.
Justification can be one of the following values:

<syntaxhighlight>
        #define J_LEFT          0x00    /* Left justified */
        #define J_RIGHT         0x01    /* Right justified */
        #define J_CENTER        0x02    /* Center text */
        #define J_SPREAD        0x03    /* Spread text across path */
</syntaxhighlight>

CharW and CharH are the average width and height of the font
characters and are akin to X and Y font sizes, respectively.  A
negative FontH implies that the font is upsidedown.  Note that CharW
must not be negative.  NumChars is the number of characters in the
TextChars[] string, the string containing the text to be rendered.
NumPoints is the number of points in the Path[] array.  Path[] is the
path along which the text is rendered.  The path itself is not
rendered.  The points of Path[] are in the same format as the points
of a DR2D polygon.

= A Simple DR2D Example =

Here is a (symbolic) DR2D FORM:

    FORM { DR2D
            DRHD 16 { 0.0, 0.0, 10.0, 8.0 }
            CMAP  6 { 0,0,0, 255,255,255 }
            FONS  9 { 1, 0, 1, 0, "Roman" } 0
            DASH 12 { 1, 2, {1.0, 1.0} }
            ATTR 14 { 0, 0, 1, 0, 0, 0, 0, 0.0 }
            BBOX 16 { 2.0, 2.0, 8.0, 6.0 }
            FORM { DR2D
                  GRUP  2 { 2 }
                  BBOX 16 { 3.0, 4.0, 7.0, 5.0 }
                  STXT 36 { 0,1, 0.5, 1.0, 3.0, 5.0, 0.0, 12, "Hello, World" }
                  BBOX 16 { 2.0, 2.0, 8.0, 6.0 }
                  OPLY 42 { 5, {2.0,2.0, 8.0,2.0, 8.0,6.0, 2.0,6.0, 2.0,2.0 }
            }
    }


[[File:dr2d-4.png|frame|center|Simple DR2D drawing]]

= The OFNT FORM =

== OFNT ==

OFNT    (0x4F464E54)    /* ID of outline font file */

ProVector's outline fonts are stored in an IFF FORM called OFNT.  This
IFF is a separate file from a DR2D.  DR2D's FONS chunk refers only to
fonts defined in the OFNT form.

== OFHD ==

OFHD    (0x4F464844)    /* ID of OutlineFontHeaDer */

This chunk contains some basic information on the font.

<syntaxhighlight>
        struct OFHDstruct {
            char   FontName[32];   /* Font name, null padded */
            short  FontAttrs;      /* See FA_*, below */
            IEEE   FontTop,        /* Typical height above baseline */
                   FontBot,        /* Typical descent below baseline */
                   FontWidth;      /* Typical width, i.e. of the letter O */
        };

        #define FA_BOLD         0x0001
        #define FA_OBLIQUE      0x0002
        #define FA_SERIF        0x0004
</syntaxhighlight>

The FontName field is a NULL terminated string containing the name of
this font.  FontAttrs is a bit field with flags for several font
attributes.  The flags, as defined above, are bold, oblique, and
serif.  The unused higher order bits are reserved for later use.  The
other fields describe the average dimensions of the characters in this
font.  FontTop is the average height above the baseline, FontBot is
the average descent below the baseline, and FontWidth is the average
character width.

== KERN ==

KERN    (0x4B45524C)    /* Kerning pair */

The KERN chunk describes a kerning pair.  A kerning pair sets the
distance between a specific pair of characters.  

<syntaxhighlight>
struct KERNstruct {
    short   Ch1, Ch2;           /* The pair to kern (allows for 16 bits...) */
    IEEE    XDisplace,          /* Amount to displace -left +right */
            YDisplace;          /* Amount to displace -down +up */
};
</syntaxhighlight>

The Ch1 and Ch2 fields contain the pair of characters to kern.  These
characters are typically stored as ASCII codes.  Notice that OFNT
stores the characters as a 16-bit value.  Normally, characters are
stored as 8-bit values.  The wary programmer will be sure to cast
assigns properly to avoid problems with assigning an 8-bit value to a
16-bit variable.  The remaining fields, XDisplace and YDisplace,
supply the baseline shift from Ch1 to Ch2.

== CHDF ==

CHDF    (0x43484446)    /* Character definition */

This chunk defines the shape of ProVector's outline fonts.  

<syntaxhighlight>
struct CHDFstruct {
    short   Ch;         /* The character we're defining (ASCII) */
    short   NumPoints;  /* The number of points in the definition */
    IEEE    XWidth,     /* Position for next char on baseline - X */
            YWidth;     /* Position for next char on baseline - Y */
 /* IEEE    Points[2*NumPoints]*/       /* The actual points */
};

#define INDICATOR       0xFFFFFFFF      /* If X == INDICATOR, Y is an action */
#define IND_SPLINE      0x00000001      /* Next 4 pts are spline control pts */
#define IND_MOVETO      0x00000002         /* Start new subpoly */
#define IND_STROKE      0x00000004      /* Stroke previous path */
#define IND_FILL        0x00000008      /* Fill previous path */
</syntaxhighlight>

Ch is the value (normally ASCII) of the character outline this chunk
defines.  Like Ch1 and Ch2 in the KERN chunk, Ch is stored as a 16-bit
value.  (XWidth,YWidth) is the offset to the baseline for the
following character.  OFNT outlines are defined using the same method
used to define DR2D's polygons (see the description of OPLY/CPLY for
details).

Because the OFNT FORM does not have an ATTR chunk, it needed an
alternative to make fills and strokes possible.  There are two extra
bits used in font indicator points not found in polygon indicator
points, the IND_STROKE and IND_FILL bits (see defines above).  These
two defines describe how to render the current path when rendering
fonts.

The current path remains invisible until the path is either filled
and/or stroked.  When the IND_FILL bit is set, the currently defined
path is filled in with the current fill pattern (as specified in the
current ATTR chunk).  A set IND_STROKE bit indicates that the
currently defined path itself should be rendered.  The current ATTR's
chunk dictates the width of the line, as well as several other
attributes of the line.  These two bits apply only to the OFNT FORM
and should not be used in describing DR2D polygons.