
Draw files

The Draw 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. Programmers wishing to define their own object types should contact Acorn; see Appendix H: Registering names. 
Coordinates

All coordinates within a Draw 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 a standard RISC OS 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 (eg 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

Colours are specified in Draw files as absolute RGB values in a 32-bit word. The format is:

Byte	Description
0	reserved (must be zero)
1	unsigned red value
2	unsigned green value
3	unsigned blue value

For colour values, 0 means none of that colour and 255 means fully saturated in that colour. You must always write byte 0 (the reserved one) as 0, but don't assume that it always will be 0 when reading. The bytes in a word of an Draw file are in little-endian order, eg the least significant byte appears first in the file. The special value &FFFFFFFF is used in the filling of areas and outlines to mean 'transparent'. 
File headers

The file consists of a header, followed by a sequence of objects.

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 characters, padded with spaces
4	x-low bounding box
4	y-low bottom-left (x-low, y-low) is inclusive
4	x-high top-right (x-high, y-high) is exclusive
4	y-high

When rendering a 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 occurred. The entire file is rendered 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 'x-low' value may be greater than the 'x-high' value (and similarly for the y values). 
Objects

Each object consists of an object header, followed by a variable amount of data depending on the object type. 

Object header

The object header is of the following form:

Size	Description
4	object type field
4	object size: number of bytes in the object - always a multiple of 4
4	x-low object bounding box
4	y-low bottom-left (x-low, y-low) is inclusive
4	x-high top-right (x-high, y-high) is exclusive
4	y-high

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 (hence the header is only two words long). Such objects will be identified explicitly in the object descriptions that follow. If an unidentified object type field is encountered when rendering a file, ignore the object and continue. The rest of the data for an object depends on the object type. 

Font table object

Object type number 0

A font table object has no bounding box in its object header, which is followed by a sequence of font number definitions:

Size	Description
1	font number (non-zero)
n	character textual font name, null terminated 
repeat for all fonts
0 - 3	up to 3 zero characters, to pad the object to a word boundary 

This object type is somewhat special in that only one instance of it ever appears in a 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. Comparison of font names is case-insensitive. In RISC OS 3.5 and earlier, the Draw application expects the font table object to be the first object in the file; we suggest that any Draw files you generate obey this restriction. From RISC OS 3,6 onwards, Draw merely expects that the font table object precedes any text objects or transformed text objects that use it. 

Text object

Object type number 1

Size	Description
4	text colour
4	text background colour hint
4	text style
4	unsigned nominal x size of the font (in 1/640 point)
4	unsigned nominal y size of the font (in 1/640 point)
8	x, y coordinates of the start of the text base line
n	characters in the string, null terminated
0 - 3	up to 3 zero characters, to pad to a word boundary

The character string consists of printing ANSI characters with codes within the ranges 32 - 126 and 128 - 255. This need not be checked during rendering, but other codes may produce undefined or system-dependent results. The text style word consists of the following:

Bit(s)	Description
0 - 7	one byte font number
8 - 31	reserved (must be zero)

Italic, bold variants etc 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 above). 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 nominal x 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 rendition code can assume that the text appears on a background that matches the background colour hint. 

Path object

Object type number 2

Size	Description
4	fill colour (-1 <=&GT;> do not fill)
4	outline colour (-1 <=&GT;> 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	1-word tag identifier:
	bits 0 - 7 = tag identifier byte:
	0 > end of path: no arguments
	2 > move to absolute position: followed by one x, y pair
	5 > close current sub-path: no arguments
	8 > draw to absolute position: followed by one x, y pair
	6 > Bezier curve through two control points, to absolute position: followed by three x, y pairs
	bits 8 - 31 reserved (must be zero)
n  8	sequence of n 2-word (x, y) coordinate pairs (where n is zero, one or three, as determined by the value of the tag identifier)

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 chapter entitled Draw module for precise rules concerning the appearance of paths. See also manuals on PostScript. (Reference: PostScript Language Reference Manual. Adobe Systems Incorporated (1990) 2nd ed. Addison-Wesley, Reading, Mass, USA). 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/or '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 as end cap style)
6	winding rule:
	0 = non-zero
	1 = even-odd
7	dash pattern:
	0 = dash pattern missing
	1 = dash pattern present
8 - 15	reserved (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 followed by, for each element of the dash pattern:
Size	Description
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. 

Sprite object

Object type number 5

This is followed by a sprite. See the chapter entitled Format of a sprite for details. 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 - for further details see the chapter entitled Sprites and the The Window Manager. 

Group object

Object type number 6

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. 

Tagged object

Object type number 7

Size	Description
4	tag identifier

This is followed by an object and optional word-aligned 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. Programmers wishing to define their own object tags should contact Acorn; see Appendix H: Registering names. 

Text area object

Object type number 9

Size	Description

?	1 or more text column objects (object type 10, no data - see below)
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 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 partitioned 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 it has are not. Arguments of variable length are terminated by a '/' or <newline>. Arguments of fixed length are terminated by an optional '/'. Values with range limits mean that if a value falls outside the range, then the value is truncated to this limit. Escape sequence

Description

\! <version><newline or />

Must appear at the start of the text, and only there. <version> must be 1.

\A<code><optional />

Set alignment. <code> is one of L (left = default), R (right), C (centre), D (double). A change in alignment forces a line break.

\B<R><spaces><G><spaces><B><newline or />

Set text background colour hint to the given RGB intensity (or the best available approximation). Each value is limited to 0 - 255.

\C<R><spaces><G><spaces><B><newline or />

Set text foreground colour to the given RGB intensity (or the best available approximation). Each value is limited to 0 - 255.

\D<number><newline or />

Indicates that the text area is to contain <number> columns. Must appear before any printing text.

\F<digit*><name><spaces><size>[<spaces><width>]<newline 
or />

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.

\<digit*><optional />

Selects a font, using the font reference number

\L<leading><newline or />

Define the leading in points from the end of the (output) line in which the \L appears - ie the vertical separation between the bases of characters on separate lines. Default, 10 points.

\M<leftmargin><spaces><rightmargin><newline or />

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.

\P<leading><newline or />

Define the paragraph leading in points, ie the vertical separation between the end of one paragraph and the beginning of a new paragraph. Default, 10 points.

\U<position><spaces><thickness><newline or />

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

\V[-]<digit><optional />

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.

\<newline>

Force line break.

\\

appears as \ on the screen

\;<text><newline> 
Comment: ignored.

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:    
	* Control characters are ignored, except for tab, which is replaced by a space.    
	* Newlines (that are not part of an escape sequence) are interpreted as follows:
	Occurring before any printing text: a paragraph leading is inserted for each newline.
	In the body of the text: a single newline is replaced by a space, except when it is already followed or preceded by a space or tab. A sequence of n newlines inserts a space of (n-1) times the paragraph leading, except that paragraph leading at the top of a new text column is ignored. Lines which protrude beyond the limits of the box vertically, eg 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, eg owing to italic overhang for this font being greater than the margin setting.

Restrictions

If a chunk of text contains more than 16 colour change sequences, only the last 16 will be rendered correctly. This is a consequence of the size of the colour cache used within the font manager. A chunk in this case means a block of text up to anything that forces a line break, eg the end of a paragraph or a change on the alignment.

Text column object

Object type number 10

No further data, ie 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.

Options object

Object type number 11

The object header for an options object has space allocated for a bounding box, but since one would be meaningless, the space is unused. You must treat the 4 words normally used for the bounding box as reserved, and set them to zero.

Size	Description
4	(paper size + 1)  &100 (ie &500 for A4)
4	paper limits options:
	bit 0 set > paper limits shown
	bits 1 - 3 reserved (must be zero)
	bit 4 set > landscape orientation (else portrait)
	bits 5 - 7 reserved (must be zero)
	bit 8 set > printer limits are default
	bits 9 - 31 reserved (must be zero)
8	grid spacing (floating point)
4	grid division
4	grid type (zero > RECTANGULAR_ NON-ZERO > isometric)
4	grid auto-adjustment (zero > OFF_ NON-ZERO > on)
4	grid shown (zero > NO_ NON-ZERO > yes)
4	grid locking (zero > OFF_ NON-ZERO > on)
4	grid units (zero > INCHES_ NON-ZERO > centimetres)
4	zoom multiplier (1 - 8)
4	zoom divider (1 - 8)
4	zoom locking (zero > NONE_ NON-ZERO > locked to powers of two)
4	toolbox presence (zero > NO_ NON-ZERO > yes)
4	initial entry mode: one of
	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 line
	bit 7 set > select
4	undo buffer size, in bytes

When Draw reads a draw file, only the first options object is taken into account - any others are discarded. When it saves a diagram to file, the options in force for that diagram are saved with it. The Draw application supplied with RISC OS 2 does not use this object type. 

Transformed text object

Object type number 12

Size	Description
24	transformation matrix
4	font flags:
	bit 0 set > text should be kerned
	bit 1 set > text written from right to left
	bits 2 - 31 reserved (must be zero)
4	text colour
4	text background colour hint
4	text style
4	unsigned nominal x size of the font (in 1/640 point)
4	unsigned nominal y size of the font (in 1/640 point)
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 a word boundary

The transformation matrix is as described in Font_Paint, in the same format used elsewhere in the Draw module. However, the exception that the translation part of the matrix must be zero. The remaining fields are exactly as specified for Text objects (see Text object). The Draw application supplied with RISC OS 2 does not use this object type. 

Transformed sprite object

Object type number 13

Size	Description
24	Transformation matrix

This is followed by a sprite. See the chapter entitled Format of a sprite for details. This contains a pixelmap image. The image is transformed from its own coordinates (ie the bottom-left at (0, 0) and the top-right at (w  x_eig, h  y_eig), where (w, h) are the width and height of the sprite in pixels, and (x_eig, y_eig) are the EIG factors for the mode in which it was defined) by the transformation held in the matrix. 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 - for further details see the chapter entitled Sprites and the The Window Manager. The Draw application supplied with RISC OS 2 does not use this object type. 
