Version Number: 1.07
The ArcDraw file format provides an object-oriented description of a graphic image. It represents an object in its editable form, unlike a page-description language such as PostScript which simply describes an image. This document describes the file format, and the rules that should be used in order to render the object on a display device.
Parties wishing to define their own object types should use the same approach as for the allocation of SWI numbers [Reference: Arthur/RISC OS Programmer's Reference Manual].
All coordinates within an ArcDraw file are signed 32-bit integers that give absolute positions on a large image plane. The units are 1/(180*256) inches, or 1/640 of a printer's point. When plotting on an Archimedes screen, an assumption is made that one OS-unit on the screen is 1/180 of an inch. This gives an image reaching over half a mile in each direction from the origin. The actual image size (e.g. the page format) is not defined by the file, though the maximum extent of the objects defined is quite easy to calculate. Positive-x is to the right, Positive-y is up. The printed page conventionally has the origin at its bottom left hand corner. When rendering the image on a raster device, the origin is at the bottom left hand corner of a device pixel.
Colours are specified in ArcDraw files as absolute RGB values in a
32-bit word. The format is:
byte 0: reserved (must be zero)
byte 1: unsigned red value
byte 2: unsigned green value
byte 3: unsigned blue value
For 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: when creating such an object, set to zero when reading such an object, do NOT assume that these fields are zero This allows the fields to be used for future expansion. End aside.)
The bytes in a word of an ArcDraw file are in little-endian order, e.g. 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 consists of a header, followed by a sequence of objects.
The file header is of the following form.
1-byte ASCII 'D'
1-byte ASCII 'r'
1-byte ASCII 'a'
1-byte ASCII 'w'
1-word major format version stamp - currently 201 (decimal)
1-word minor format version stamp - currently 0
12-byte identity of the program that produced this file.
typically 8 ASCII chars, padded with spaces.
4-word bounding box: low x, low y, high x, high y
When rendering an ArcDraw file, check the major version number. If this is greater than the latest version you recognise then refuse to render the file (e.g. 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.
A Draw file containing a file header but no objects is legal; however, the bounding box is undefined. In particular the 'x0' value may be greater than the 'x1' value (and similarly for the y values).
Each object consists of an object header, followed by a variable amount of
data depending on the object type. The object header is of the following
form:
1-word object type field
1-word object size: number of bytes in the object, always a multiple of 4
4-word 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.
A Font Table object has no bounding box in its object header.
object type number: 0
object data:
sequence of font number definitions
up to 3 zero characters, to pad to word boundary
a font number definition consists of:
1 character font number (non-zero)
textual name of corresponding font (characters within 32..126)
zero character
Comparison of font names is case-insensitive.
The character string consists of printing ANSI 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:
bits 0..7: one byte font number
bits 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.
An outline width of 0 means draw the thinnest possible outline that the device can represent.
A path component consists of:
1-word tag identifier
sequence of 2-word (x,y) coordinate pairs
Each tag identifier word consists of:
bits 0..7: tag identifier byte
bits 8..31: reserved, must be zero
Possible tag identifier byte values:
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
(Aside: 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 componenets, followed (optionally) by a "close sub-path" path component.
The path style description word is as follows:
bits 0..1: join style:
0 = mitred joins
1 = round joins
2 = bevelled joins
bits 2..3: end cap style:
0 = butt caps
1 = round caps
2 = projecting square caps
3 = triangular caps
bits 4..5: start cap style (same possible values)
bit 6: winding rule:
0 = non-zero
1 = even-odd
bit 7: dash pattern:
0 = dash pattern missing
1 = dash pattern present
bits 8..15: reserved and must be zero
bits 16..23: triangle cap width:
a value within 0..255,
measured in sixteenths of the line width.
bits 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 (e.g. 10).
If the dash pattern is present then it is in the following format: 1-word offset distance into the dash pattern to start 1-word number of elements in the dash pattern for each element of the dash pattern,
1-word 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.
[Reference: Arthur/RISC OS Programmer's Reference Manual].
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.
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.
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 attatch 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.
null character
0..3 null characters to align to a 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.
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:
Text column objects