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 */

        struct FORMstruct {
            ULONG       ID;             /* DR2D */
            ULONG       Size;
        };

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

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

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 < XRight, the X-axis increases toward the right. If YTop < 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.

        struct PPRFstruct {
            ULONG       ID;
            ULONG       Size;
            char        Prefs[Size];
        };

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=<unit-type>
               Portrait=<boolean>
               PageType=<page-type>
               GridSize=<number>

where:

               <unit-type>     is either Inch, Cm, or Pica
               <boolean>       is either True or False
               <page-type>     is either Standard, Legal, B4, B5, A3,
                                 A4, A5, or Custom 
               <number>        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.

        struct CMAPstruct {
            ULONG       ID;
            ULONG       Size;
            UBYTE       ColorMap[Size];
        };

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.

        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 */
        };

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.

        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 */
        };

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.

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.

        #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];
        };

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.

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

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.

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 (Fig. A). The bounding box shown in Fig. 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 (Fig. 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 (Fig. C) being filled. The object's path is called a clipping path, as it ``clips its shape from the tiled pattern (Fig. 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.

        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 */
        };

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:

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

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.

        /* 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              */
        };

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:

        /* 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 */

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.

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

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.

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

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.

        /* 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 */

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.

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 */
};

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.

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

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.

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:

        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 < 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 & IND_MOVETO ) {
                    /* Close and fill, if appropriate */
                    if( ID == CPLY ) {
                        FillPath();
                    }
                    else {
                        StrokePath();
                    }
 
                    /* Set up the new path */
                    NewPath();
                    FirstPoint = 1;
                }
                if( Temp1.bits & 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();
        }

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.

        struct GROUPstruct {
            ULONG       ID;
            ULONG       Size;
            USHORT      NumObjs;
        };

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.

        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];
        };

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.

        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 */
        };

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:

        #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 */

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 }
           }
   }

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.

        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

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.

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 */
};

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.

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 */

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.