Drawfile format
Drawfile formatThis document describes the file format, and the rules that should be used in order to render the object on a display device.
Programmers wishing to define their own object types should use the same approach as for the allocation of SWI numbers.
Byte Description ----------- ---------------------------------------------------- 0 reserved (must be zero) 1 unsigned red value 2 unsigned green value 3 unsigned blue valueFor colour values, 0 means none of that colour and 255 means fully saturated in that colour.
(Aside: the phrase "reserved and must be zero" means:
This allows the fields to be used for future expansion. End aside.)
The bytes in a word of an Draw file are in little-endian order, eg. the lest significant byte appears first in the file.
The special value &FFFFFFFF is used in the filling of areas and outlines to mean 'transparent'.
The file header is of the following form.
Size Description
----------- ----------------------------------------------------
4 'Draw'
4 major format version stamp - currently 201 (decimal)
4 minor format version stamp - currently 0
12 identity of the program that produced this file
- typically 8 ASCII chars, padded with spaces.
16 Bounding box: low x, low y, high x, high y
When rendering an Draw file, check the major version number. If this is
greater than the latest version you recognise then refuse to render the file
(eg. generate an error message for the user), as an incompatible change in
the format has occured.
The entire file is rendred by rendering the objects one by one, as they appear in the file.
The bounding box indicates the intended image size for this drawing.
Size Description
----------- ----------------------------------------------------
4 object type field
4 object size: number of bytes in the object, always a
multiple of 4
16 object bounding box: low x, low y, high x, high y
The bounding box describes the maximum extent of the rendition of the
object: the object cannot affect the appearance of the display outside this
rectangle. The upper coordinates are an outer bound, in that the device
pixel at (x-low, y-low) may be affected by the object, but the one at
(x-high, y-high) may not be. The rendition procedure may use clipping on
these rectangles to abandon obviously invisible objects.
Objects with no direct effect on the rendition of the file have no bounding box: these will be identified explicitly in the object descriptions that follow.
If an unidientified object type field is encountered when rendering a file, ignore the object and contine.
The object size field includes the object header.
The rest of the data for and object depends on the object type field.
This is followed by a sequence of font number definitions
Size Description ----------- ---------------------------------------------------- 1 font number (non-zero) n n character textual font name, null terminated 0 - 3 up to 3 zero characters, to pad to word boundaryThis object is somewhat special in that only one of it ever appears in an Draw file. It has no direct effect on the appearance of the image, but maps font numbers (used in text objects) to textual names of fonts. It must precede all Text objects.
A Font Table object has no bounding box in its object header.
Comparison of font names is case-insensitive.
Size Description ----------- ---------------------------------------------------- 4 text colour 4 text background colour hint 4 text style 4 X unsigned nominal size of the font 4 Y unsigned nominal size of the font 8 X,Y coordinates of the start of the text base line n n characters in the string, null terminated 0 - 3 up to 3 zero characters, to pad to word boundaryThe character string consists of printing ASCII characters with codes within 32-126 or 128-255. This need not be checked during rendering, but other codes may produce undefined or system-dependent results.
The style word consists of the following:
Bit(s) Description ----------- ---------------------------------------------------- 0 - 7 one byte font number 8 - 31 reserved (must be zero)Italic, bold etc. variants are assumed to be distinct fonts.
The font number is related to the textual name of a font by a preceding Font Table object within the file (see below). The exception to this is font number 0, which is a system font that is sure to be present. When rendering a draw file, if a font is not recognised, the system font should be used instead. The system font is monospaced, with the gap between letters equal to the x nominal size of the font.
The background colour hint can be used by font rendition code when performing anti-aliasing. It is referred to as a hint because it has no effect on the rendition of the object on a "perfect" printer, nevertheless for screen rendition it can improve the appearance of text on coloured backgrounds. The font redition code can assume that the text appears on a background that matches the background colour hint.
Size Description ----------- ---------------------------------------------------- 4 fill colour (-1 means do not fill) 4 outline colour (-1 means no outline) 4 outline width (unsigned) 4 path style description ? optional dash pattern definition ? sequence of path components.An outline width of 0 means draw the thinnest possible outline that the device can represent.
A path component consists of:
Size Description ----------- ---------------------------------------------------- 4 tag identifier n sequence of 2-word (x,y) coordinate pairsEach tag identifier word consists of:
Bit(s) Description ----------- ---------------------------------------------------- 0 - 7 tag identifier byte 8 - 31 reserved, must be zeroPossible tag identifier byte values are:
0 end of path: no arguments
2 move to absolute position: followed by x,y pair
5 close current sub-path
8 draw to absolute position: followed by x,y pair
6 bezier curve through two control points, to absolute position:
followed by three x,y pairs
The tag values match the arguments required by the Draw
module. This block of memory can be passed directly to the Draw module for
rendition, see the relevant documentation for precise rules concerning the
appearance of paths.
(See also manuals on PostScript [Reference: PostScript Language Reference Manual, Addison-Wesley]).
The possible set of legal path components in a path object is described as follows. A path consists of a sequence of (at least one) subpaths, followed by an 'end of path' path component. A subpath consists of a 'move to' path component, followed by a sequence of (at least one) 'draw to' and 'bezier to' path components, followed (optionally) by a "close sub-path" path component.
The path style description word is as follows:
Bit(s) Description
----------- ----------------------------------------------------
0 - 1 join style:
0 = mitred joins
1 = round joins
2 = bevelled joins
2 - 3 end cap style:
0 = butt caps
1 = round caps
2 = projecting square caps
3 = triangular caps
4 - 5 start cap style (same possible values)
6 winding rule:
0 = non-zero
1 = even-odd
7 dash pattern:
0 = dash pattern missing
1 = dash pattern present
8 - 15 reserved and must be zero
16 - 23 triangle cap width:
a value within 0 - 255, measured in sixteenths
of the line width.
24 - 31 triangle cap length:
a value within 0 - 255, measured in sixteenths
of the line width.
The mitre cut-off value is the PostScript default (eg. 10).
If the dash pattern is present then it is in the following format:
Size Description
----------- ----------------------------------------------------
4 offset distance into the dash pattern to start
4 number of elements in the dash pattern
for each element of the dash pattern,
4 length of the dash pattern element
The dash pattern is reused cyclically along the length of the path,
with the first element being filled, the next a gap, and so on.
This is followed by a sprite.
This contains a pixelmap image. The image is scaled to entirely fill the bounding box.
If the sprite has a palette then this gives absolute values for the various possible pixels. If the sprite has no palette then colours are defined locally. Within RISC OS the available 'Wimp colours' are used.
Size Description ----------- ---------------------------------------------------- 12 group object name, padded with spaces.This is followed by a sequence of other objects.
The objects contained within the group will have rectangles contained entirely within the rectangle of the group. Nested grouped objects are allowed.
The object name has no effect on the rendition of the object. It should consist entirely of printing characters. It may have meaning to specific editors or programs. It should be preserved when copying objects. If no name is intended, twelve space characters should be used.
Size Description ----------- ---------------------------------------------------- 4 tag identifierThis is followed by an object and optional word alligned data.
To render a Tagged object, simply render the enclosed object. The identifier and additional data have no effect on the rendition of the object. This allows specific programs to attach meaning to certain objects, while keeping the image renderable.
Parties wishing to define their own object tags should use the same approach as for the allocation of SWI numbers.
Size Description
----------- ----------------------------------------------------
? 1 or more text column objects (object type 10)
4 zero, to mark the end of the text columns
4 reserved (must be zero)
4 reserved (must be zero)
4 initial text foreground colour
4 initial text background colour hint
? the body of the text column: ASCII characters,
terminated by a null character.
0 - 3 up to 3 zero characters, to pad to word boundary.
A text area contains a number of text columns. The text area has a body of
text associated with it, which is partioned between the columns. If there
is just one text column object then its bounding box must be exactly
coincident with that of the text area.
The body of the text is paginated in the columns. Effects such as font settings and colour changes are controlled by escape sequences within the body of the text. All escape sequences start with a backslash character (\); the escape code is case sensitive, though any arguments is has are not.
Arguments of variable length are terminated by a '/' or
Values with range limits mean that if a value falls outside the range, then the value
is truncated to this limit.
\A<code><optional />
\B<R><spaces><G><spaces><B><newline or />
\C<R><spaces><G><spaces><B><newline or />
\D<number><newline or />
\F<digit*><name><spaces><size>[<spaces><width>]<newline or />
\<digit*><optional />
\L<leading><newline or />
\M<leftmargin><spaces><rightmargin><newline or />
\P<leading><newline or />
\U<position><spaces><thickness><newline or />
\V[-]<digit><optional />
\-
\<newline>
\\
\;<text><newline>
Other escape sequences are flagged as errors during verification.
Lines within a paragraph are split either at a space, or at a soft hyphen,
or (if a single word is longer than a line) at any character.
A few other characters have a special interpretation:
Lines which protrude beyond the limits of the box vertically, e.g. because
the leading is too small are not displayed; however, any font changes, colour
changes, etc. in the text are applied. Characters should not protrude
horizontally beyond the limits of the text column, e.g. due to italic overhang
for this font being greater than the margin setting.
No futher data. It is just an object header.
A text column object may only occur within a text area object.
Its use is described in the section on text area objects.
The object header for an options object has space allocated for a bounding box, but is
unused. Treat these four words as reserved, and set then to zero.
The transform maps the sprite at its normal size (0,0 - width*XEig, height*YEig) to the
coordinates it occupies in the diagram.
Escape sequences:
\! <version><newline or />
Must appear at the start of the text, and only there.
<version> must be 1.
Set alignment.
<code> is one of L (left = default), R (right), C (centre),
D (double). A change in alignment forces a line break.
Set text background colour hint to the given RGB
intensity (or the best available approximation). Each
value is limited to 0 - 255.
Set text foreground colour to the given RGB intensity
(or the best available approximation). Each value is
limited to 0 - 255.
Indicates that the text area is to contain <number>
columns. Must appear before any printing text.
Defines a font reference number. <name> is the name of the
font, and <size> its height. <width> may be omitted, in
which case the font width and height are the same. Font
reference numbers may be reassigned.
<digit*> is one or two digits.
<size> and <width> are in points.
Selects a font, using the font reference number.
Define the leading in points from the end of the
(output) line in which the \L appears.
Default is 10 points.
Defines margins that will be left on either size of the
text, from the start of the output line in which the
sequence appears. The margins are given in points, and
are limited to values > 0. If the sum of the margins is
greater than the width of the column, the effects are
undefined.
Both values default to 1 point.
Define the paragraph leading in points.
Default is 10 points.
Switch on underlining, at <position> units relative to the
character base, and of <thickness> units, where a unit is
1/256 of the current font size.
<position> is limited to -128 - +127, and
<thickness> to 0 - 255.
To turn the underlining off, either give a thickness of 0,
or use the command '\U.' (\U followed by a dot).
Vertical move by the specified number of points.
Soft hyphen: if a line cannot be split at a space, a hyphen
may be inserted at this point instead; otherwise, it has no
printing effect.
Force line break.
Appears as a single '\' on the page
Comment: ignored.
Text column objects
Object type number 10
Options object
Object type number 11
Size Description
----------- ----------------------------------------------------
4 (paper size + 1) * &100 (ie. &500 for A4)
4 paper limits options:
bit 0 set -> paper limits shown (1=on)
bit 4 set -> landscape (else portrait)
bit 8 set -> printer limits are default
All other bits reserved, and should be zero.
8 grid spacing (double fp)
4 grid subdivisions
4 grid type (zero -> rect, non-zero -> isometric grid)
4 grid auto-adjustment (zero -> off, non-zero -> on)
4 grid shown 1 = grid show on
4 grid locking 1 = grid locking on
4 grid units
0 = inches
1 = cm
(0 by default, but cm is the default Draw setting)
(reflects the 'X' setting, but BOTH set from this
upon loading)
4 zoom multiplier (1 - 8)
4 zoom divisor (1 - 8)
4 zoom locking 1 = zoom lock on
4 toolbox presence 1 = tools on 0 = tools off
4 initial entry mode
bit 0 set -> line
bit 1 set -> closed line
bit 2 set -> curve
bit 3 set -> closed curve
bit 4 set -> rectangle
bit 5 set -> ellipse
bit 6 set -> text
bit 7 set -> select
4 undo buffer size, in bytes
Only the first options object in file is used - others are discarded.
Transformed text objects
Object type number 12
Size Description
----------- ----------------------------------------------------
24 Transformation matrix (standard draw module type)
4 Font flags
Followed by a standard text object - without the header.
eg..
Size Description
----------- ----------------------------------------------------
4 text colour
4 text background colour hint
4 text style
4 X unsigned nominal size of the font
4 Y unsigned nominal size of the font
8 X,Y coordinates of the start of the text base line
n n characters in the string, null terminated
0 - 3 up to 3 zero characters, to pad to word boundary
The font flags have the following meanings:
Bit(s) Description
----------- ----------------------------------------------------
0 kerning flag: set -> text should be kerned
1 writing direction: set -> text should be written right to left.
Transformed sprite objects
Object type number 13
Size Description
----------- ----------------------------------------------------
24 Transformation matrix (standard draw module type)
This is followed by a sprite (as for a normal sprite object)
_ _ | a b 0 | | c d 0 | |_ e f 1 _|This matrix transforms a coordinate (x,y) into another coordinate (x',y') as follows:
x' = ax + cy + e
y' = bx + dy + f
When a transformation matrix appears in a Drawfile, it is stored as follows:
Size Description ----------- ---------------------------------------------------- 4 a 4 b 4 c 4 d 4 e 4 fValues a - d are stored in '16.16' fixed point format (ie. 16 bits for the integer part and 16 bits for the fractional part). Values e and f are integers and are in Draw units.
