Archive Magazine 1996/ARCHIVE_96.iso/discs/mag_discs/volume_8/issue_06/risc_os/DrawFiles

Text File | 1988-12-01 | 17KB | 411 lines

ArcDraw File Format
===================

Version Number: 1.07

Introduction
------------

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

Coordinates
-----------

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

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

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).
The Object Header
-----------------

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.

The Font Table object
---------------------

This object is somewhat special in that only one of it ever appears in
an ArcDraw 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.

  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.

Text objects
------------
  object type number: 1
  object data:
    1-word text colour
    1-word text background colour hint
    1-word text style
    1-word x unsigned nominal size of the font
    1-word y unsigned nominal size of the font
    2-word x,y coordinates of the start of the text base line
    characters in the string
    zero character
    up to 3 zero characters, to pad to word boundary

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.

Path objects
------------
  object type number: 2
  object data:
    1-word fill colour (-1 means do not fill)
    1-word outline colour (-1 means no outline)
    1-word outline width (unsigned)
    1-word 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:
  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.

Sprite Objects
--------------
  object type number: 5
  object data:
    a sprite
       [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.

Group Objects
-------------
  object type number: 6
  object data:
    12-byte group object name, padded with spaces.
    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
  object data:
    1-word tag identifier
    object
    additional data (multiple of 4 in size)

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.

Text area objects
---------------
  object type number: 9
  object data:
    1 or more text column objects
    1-word zero, to mark the end of the text columns
    1-word reserved, which must be zero
    1-word reserved, which must be zero
    1-word initial text foreground colour
    1-word initial text background colour hint
    the body of the text column: ASCII characters, terminated by a
      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.

1. \! <version><newline or />
   Must appear at the start of the text, and only there. <version> must be 1.
2. \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.
3. \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.
4. \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.
5. \D<number><newline or />
   Indicates that the text area is to contain <number> columns. Must appear
   before any printing text.
6. \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.
7. \<digit*><optional />
   Selects a font.
8. \L<leading><newline or />
   Define the leading in points from the end of the (output) line in which the
   \L appears. Default 10 points.
9. \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.
10. \P<leading><newline or />
    Define the paragraph leading in points. Default 10 points.
11. \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. (\U followed by a dot).
12. \V[-]<digit><optional />
    Vertical move by the specified number of points.
13. \-
    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.
14. \<newline>
    Force line break.
15. \\ appears as \ on the screen
16 . \;<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:

1. Control characters are ignored, except for tab, which is replaced by a
   space.
2. Newlines (that are not part of an escape sequence) are interpreted as
   follows:
   a. occuring before any printing text. A paragraph leading is inserted for
      each newline.
   b. 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) time 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, 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.

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,
e.g. the end of a paragraph or a change on the alignment.

Text column objects
-----------------
  object type number: 10
  object data: none
A text column object may only occur within a text area object.
Its use is described in the section on text area objects.