The Datafile PD-CD 5

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / dubmodule / Drawfiles / DFformat < prev

Wrap

Text File | 1996-03-27 | 25.0 KB | 584 lines

Drawfile format =============== File structure -------------- A drawfile usually consists of a 40 byte header followed by a font table object (only required if text objects are present in the file) followed by an options object, and then one or more objects to be displayed. In principle, the font table need only be located before any text objects and the options object could be located anywhere. However, !Draw (V0.99) will crash if the sequence header-options object-font table object is used (other permutations have not been investigated). Therefore it seems wise to use the same structure as !Draw, i.e. header followed by the font table (if required) followed by the options object. A drawfile consisting only of the header with or without the font table and/or options object is valid (but a bit pointless). Displayable objects (text, path, sprite and text area objects) are rendered in the order in which they appear in the drawfile. There is no end-of-file marker, nor is there anything in the drawfile to indicate its size. The file size is denoted only by the file size attribute, which must be set correctly. Programs which render or otherwise process drawfiles use this attribute to tell when to stop rendering (or processing). Bounding boxes -------------- Most objects have a bounding box, which defines a rectangular area which (should) exactly enclose the object. The main purpose of these bounding boxes is to determine which objects need to be rendered by comparing them with the wimp redraw rectangle for the window in which the drawfile is displayed. If an object bounding box is incorrect, the object may be rendered unnecessarily (which slows the process down) or may not be rendered when required (so parts of the image may appear to be missing). Some applications which export drawfiles simply write zero for the bounding box coordinates. This is valid, since !Draw will calculate the correct bounding box coordinates when a file is loaded. However, other applications may not render the file correctly for the reason described above. !Draw will report an error and refuse to load the file if any bounding box is inverted (i.e. xmin > xmax or ymin > ymax). Units ----- One draw unit is 1/640th of a point (1 point = 1/72nd of an inch). Therefore, 1 inch = 46080 draw units 1 cm = 18141.73228 draw units On screen, 1 os unit = 256 draw units (at a zoom factor of 1.0). Note ---- In the descriptions below, the offset values give the distance in bytes from the start of the object to each component and the size of the components is in bytes. Drawfile header =============== A drawfile must start with a 40 byte header with the format described below. Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 file identification word (= &77617244 = 'Draw'). +4 4 major file format version number (currently 201 decimal). +8 4 minor version number (usually 0). +12 12 source identification string (usually name of program which generated the drawfile, max 12 chars, padded with spaces if less). +24 4 image bounding box xmin (inclusive). +28 4 " " " ymin (inclusive). +32 4 " " " xmax (exclusive). +36 4 " " " ymax (exclusive). If the major version number is greater than 201 it indicates a significant difference in the file format; rendering (or otherwise processing) the drawfile is not recommended unless the software used recognizes this new format. The image bounding box defines a rectangular area which exactly encloses all the displayable objects in the file. An application which renders drawfiles may compare the image bounding box with the redraw rectangle to determine if any objects need to be displayed. Therefore if the bounding box is incorrect the file may not render correctly. Font table object (object type number 0) ======================================== Text objects (including transformed text objects) indicate which outline font to use by a number; the font table object provides a font name for each number. For text objects using the system font, this number is zero and there is no entry in the font table. For outline fonts used only in text area objects, there is no need for these fonts to be listed in the font table since each text area object contains its own equivalent of the font table; the drawfile will be rendered correctly (unless perhaps a list of all fonts used is required e.g. before printing on a PostScript printer). !Draw does include fonts used only in text area objects in the font table. There should be only one font table object in the drawfile, and as noted in the introductory section it should be located immediately afer the drawfile header. The font number is a single byte quantity in the range 1-255, with numbering usually starting at 1. Numbering does not have to be consecutive. Font names are case-insensitive. Duplication in the font table should be avoided. If (e.g.) fonts 3 and 5 are defined as Trinity.Medium, !Draw will render a text object with font number 3 correctly, but one with font number 5 will be rendered using the system font. If a text object uses an unknown font, !Draw will render it using the system font. The DrawFile module renders it using the System.Fixed font scaled to fit the object bounding box. The DrawUtilsA module provides facilities to list any unknown fonts in the drawfile and replace them with other fonts. In a text area object, if an unknown font is used at the start of the text then nothing is displayed, otherwise the unknown font selection is ignored and rendering continues with the previously selected font. The format of the font table is as follows (note that there is no bounding box for this object): Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 0). +4 4 total size of this object (bytes). +8 1 single byte number (non-zero) for first font. m+1 name of first font (m chars) terminated by a null char. 1 single byte number (non-zero) for second font. n+1 name of second font (n chars) terminated by a null char. ...further font number/name pairs as required... 0—3 additional null chars as padding to a word boundary (i.e. so total size of the object is a multiple of 4 bytes). Options Object (object type number 11) ====================================== Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 11). +4 4 total size of this object (= 88 bytes). +8 4 bounding box xmin (must be zero). +12 4 bounding box ymin ( " ). +16 4 bounding box xmax ( " ). +20 4 bounding box ymax ( " ). +24 4 (paper size + 1) * 256, e.g. A4 paper = &500. +28 4 paper limits options: bit 0 when set, paper limits shown bits 1-3 reserved (must be zero) bit 4 when set, paper landscape orientation bits 5-7 reserved (must be zero) bit 8 when set, printer limits are default bits 9-31 reserved (must be zero). +32 8 grid spacing (double precision value, inches or cm depending on units selection at +60). +40 4 number of grid divisions. +44 4 grid type (0 = rectangular, non-zero = isometric). +48 4 grid auto-adjust (0 = off, non-zero = on). +52 4 grid shown (0 = no, non-zero = yes). +56 4 grid lock (0 = off, non-zero = on). +60 4 grid units (0 = inches, non-zero = cm). +64 4 zoom multiplier (allowable values 1-8). +68 4 zoom divisor (allowable values 1-8). +72 4 zoom lock (0 = off, non-zero = locked to powers of 2). +76 4 toolbox shown(0 = no, non-zero = yes). +80 4 toolbox icon selected on file load (one only should be set) bit 0 = line bit 1 = closed line bit 2 = curve bit 3 = closed curve bit 4 = rectangle bit 5 = circle/ellipse bit 6 = text bit 7 = select mode. +84 4 undo buffer size in bytes. There should be only one options object in the drawfile (subsequent ones will be ignored), and as noted in the introductory section it should be located immediately after the font table (if present) or after the drawfile header. The options object is itself optional. Most of the entries are editor- specific (e.g. grid type and spacing); the only ones relevant to rendering the file are the page size and orientation entries (at +24 and bit 4 of +28). When the file is loaded into !Draw, the window size is set to match the specified paper size and orientation (e.g. A4 = 1488 x 2104 os units). In the absence of an options object, the object bounding boxes (including the image bounding box) are used to determine the smallest paper 'A' size which will accomodate the image and the window size is set accordingly. Text Object (object type number 1) ================================== Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 1). +4 4 total size of this object (bytes). +8 4 bounding box xmin (inclusive). +12 4 bounding box ymin (inclusive). +16 4 bounding box xmax (exclusive). +20 4 bounding box ymax (exclusive). +24 4 text colour (as &BBGGRR00). +28 4 text background colour hint (as &BBGGRR00). +32 4 text style (i.e. font number). +36 4 horizontal (x) font size (in 1/640th point). +40 4 vertical (y) font size (in 1/640th point). +44 4 x-coordinate } of start of text +48 4 y-coordinate } base line. +52 n+1 the text string (n characters) terminated by a null char. 0—3 additional null chars as padding to a word boundary (i.e. so total size of the object is a multiple of 4 bytes). The text style word at +32 gives the font number as described in the section on the font table object. Only bits 0-7 are used and bits 8-31 must be clear; for the system font, this number is zero. The minimum font size is 1 point. The background colour hint is used to set up a palette for anti-aliasing. There is no 'rub-out' box and the text is simply overlaid on whatever forms the background - specifying the background colour correctly will improve the appearance of the text on screen and possibly on the printed copy. The text base line is an imaginary underline; descenders such as 'g' and 'y' go below this line. The text string must contain only printable characters (ascii 32-126 and 128-255 inclusive). !Draw does not allow the escape sequences for colour selection, underlining etc which the font manager recognizes. Path Object (object type number 2) ================================== Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 2). +4 4 total size of this object (bytes). +8 4 bounding box xmin (inclusive). +12 4 bounding box ymin (inclusive). +16 4 bounding box xmax (exclusive). +20 4 bounding box ymax (exclusive). +24 4 fill colour (as &BBGGRR00, use -1 for none). +28 4 line colour (as &BBGGRR00, use -1 for none). +32 4 line width (in draw units). +36 4 path style description. +40 n dash pattern definition (optional). sequence of path components, starting with a move (component = 2) and ending with an end-path (component = 0). A line width of zero means 'draw the thinnest possible line'. Path style description ---------------------- The path style description is a 32-bit field as follows: Bit(s) Description ------ ----------------------------- 0-1 join style (0 = mitred, 1 = round, 2 = bevelled, 3 = unused). 2-3 end cap style (0 = butt, 1 = round, 2 = projecting square, 3 = triangular). 4-5 start cap style (as for end cap). 6 winding rule (0 = non-zero, 1 = even-odd). 7 dash pattern (0 = none, 1 = present). 8-15 reserved (must be zero). 16-23 triangular cap width (in 1/16ths of the line width, possible values 1-255). 24-31 triangular cap length (in 1/16ths of the line width, possible values 1-255). Dash pattern ------------ If a dash pattern definition is present it has the following format (as an example, this is the definition for the fourth pattern - long/short dash - provided by !Draw). Each entry is one word (= 4 bytes), offsets are from the start of the pattern definition. Offset Value Description ------ ----- --------------------------------------------- +0 = 0 initial gap length (draw units, must be >= 0) +4 = 4 number of entries following (multiple of 2) +8 = &2400 dash length } +12 = &900 gap length } draw units, +16 = &900 dash length } should be > 0 +20 = &900 gap length } Path components and structure ----------------------------- The possible path components and their use is as follows. Each entry is one word (= 4 bytes), so (e.g.) a [move x,y] component uses 12 bytes. Component Additional data Description --------- ------------------- ---------------------------------------- 0 (end of path) 2 x y (move to x,y) 5 (close subpath) 6 cx1 cy1 cx2 cy2 x y (bezier curve segment to x,y with control points at cx1,cy1 and cx2,cy2) 8 x y (draw straight line to x,y) A path consists of one or more subpaths. Each subpath must start with a move (2), which must be followed by at least one straight line (8) or curve (6) component. Optionally, the last component of a subpath can be a close-path (5). A move (2) to start a new subpath automatically terminates the preceeding subpath. The last (and only the last) subpath must be followed by an end-path (0). When creating a closed subpath, there should be a final line or curve segment going back to the start point followed by a close-path component. The main effect of a close-path is to ensure that the correct join style is applied where the beginning and end of the subpath meet, but see the accompanying files 'Bezier1' through 'Bezier4' for a further discussion of path closure and an explanation of how bezier curves are created. Sprite Object (object type number 5) ==================================== Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 5). +4 4 total size of this object (bytes). +8 4 bounding box xmin (inclusive). +12 4 bounding box ymin (inclusive). +16 4 bounding box xmax (exclusive). +20 4 bounding box ymax (exclusive). +24 a single sprite (without the sprite area control block). The standard 24 byte object header is followed by the sprite. When the drawfile is rendered, the sprite is scaled to exactly fit the bounding box. For full details of the sprite format, see the Programmers Reference Manual. In brief, the format is: •sprite control block •palette (optional) •sprite image •sprite mask (optional). with the format of the sprite control block being: Bytes Description ----- ---------------------------------------------------------- 0-3 total size of the sprite (bytes) 4-15 sprite name (max 12 chars, padded with null chars) 16-19 width in words-1 20-23 height in scan lines-1 24-27 first bit used 28-31 last bit used 32-35 offset¹ to sprite image (if > 44 then palette data present) 36-39 offset¹ to mask (if none then offset to image) 40-43 mode sprite was defined in (¹offsets are in bytes from the start of the sprite control block). Group Object (object type number 6) =================================== Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 6). +4 4 total size of this object (bytes). +8 4 bounding box xmin (inclusive). +12 4 bounding box ymin (inclusive). +16 4 bounding box xmax (exclusive). +20 4 bounding box ymax (exclusive). +24 12 group object name (max 12 chars, padded with spaces). This is followed by a sequence of other objects (one or more). Grouping allows a number of objects to be handled (e.g. moved, scaled, rotated, etc) as a single unit. Group objects can be nested. The group object name is ignored by !Draw, but might be relevant to certain editors. There is no end-of-group marker; the number of objects following the group header which are included in the group is determined solely by the size of the group object (i.e. the total size is 36 bytes for the header plus the sum of the sizes of all objects in the group). The bounding box should be that which exactly encloses all objects in the group. Tagged Object (object type number 7) ==================================== Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 7). +4 4 total size of this object (= 28+n+x bytes). +8 4 bounding box xmin (inclusive). +12 4 bounding box ymin (inclusive). +16 4 bounding box xmax (exclusive). +20 4 bounding box ymax (exclusive). +24 4 secondary type identifier. +28 n a single 'enclosed' object of size n bytes. +28+n x optional additional data (multiple of 4 bytes). Tagged objects allow a standard object (text object, path object, etc) to be packaged along with additional data which would be relevant to a specific editor (or other software). This additional data comprises the secondary type identifier and the extra data at the end of the object (if present). !Draw ignores these data and simply renders the enclosed object. The enclosed object can be a group object (containing one or more objects), or a tagged object (i.e. they can be nested), or one of the standard objects used by !Draw. Tagged objects cannot be edited in !Draw. They cannot be moved, scaled or rotated and the attributes of the enclosed object (font name & size, path style, colours, etc) cannot be altered. Note: when the enclosed object is a text object, !Draw (V0.99) sometimes gets confused over which font to use. Text Area Object (object type number 9) ======================================= A text area object allows a block of text to be formatted across one or more rectangular areas according to escape sequences embedded in the text. These escape sequences begin with a back-slash ('\') character and most end with either a slash character or a newline (ascii 10). See the section on !Draw in the User Guide/Applications Guide or the section on file formats in the Programmers Reference Manual for a full description of these escape sequences and other details of using these objects. Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 9). +4 4 total size of this object (bytes). +8 4 bounding box xmin (inclusive). +12 4 bounding box ymin (inclusive). +16 4 bounding box xmax (exclusive). +20 4 bounding box ymax (exclusive). +24 n*24 one or more text column objects (each 24 bytes - see below) 4 zero word to mark the end of text column objects. 4 reserved (must be zero). 4 reserved (must be zero). 4 initial text colour (as &BBGGRR00). 4 initial text background colour hint (as &BBGGRR00). ? the text, terminated by a newline (ascii 10) followed by a null char. 0—3 additional null chars as padding to a word boundary (i.e. so total size of the object is a multiple of 4 bytes). A text column object consists only of a 24 byte object header and defines one of the rectangular areas over which the text will be formatted, i.e. Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 10 for a text column object). +4 4 total size of this object (= 24 bytes). +8 4 bounding box xmin (inclusive). +12 4 bounding box ymin (inclusive). +16 4 bounding box xmax (exclusive). +20 4 bounding box ymax (exclusive). The bounding box for the text area object should be that which exactly encloses all of the text columns. The text should consist only of printable characters (ascii 32-126 and 128-255 inclusive) and newlines (ascii 10) except for the null char terminator. Large text areas can be very slow to render. Where possible, break the text down into smaller blocks (e.g. use a separate text area object for each paragraph). This also makes it easier to predict in advance how the text will be formatted. For example, two or more (=n) consecutive newlines usually gives a vertical gap equal to (n-1) times the paragraph spacing plus one linespace, but this varies depending on certain combinations of escape sequences preceeding the newlines. Also, if the text is prepared using an editor such as !Edit, it is a good idea to check for trailing spaces or lines consisting only of spaces (these are easily seen if the text is selected so that the foreground and background colours are inverted). Such superfluous white space can affect formatting of the text area object in ways which appear rather unpredictable. Transformed Text Object (object type number 12) =============================================== Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 12). +4 4 total size of this object (bytes). +8 4 bounding box xmin (inclusive). +12 4 bounding box ymin (inclusive). +16 4 bounding box xmax (exclusive). +20 4 bounding box ymax (exclusive). +24 24 transformation matrix. +48 4 font flags. +52 4 text colour (as &BBGGRR00). +56 4 text background colour hint (as &BBGGRR00). +60 4 text style (i.e. font number). +64 4 horizontal (x) font size (in 1/640th point). +68 4 vertical (y) font size (in 1/640th point). +72 4 x-coordinate } of start of text +76 4 y-coordinate } base line. +80 n+1 the text string (n characters) terminated by a null char. 0—3 additional null chars as padding to a word boundary (i.e. so total size of the object is a multiple of 4 bytes). The transformation matrix is a 24 byte block with the general format (entries are signed 32-bit integers): +0 65536 * xscale * cos(angle) +4 65536 * xscale * sin(angle) +8 65536 * yscale * -sin(angle) +12 65536 * yscale * cos(angle) +16 xshift (in draw units) +20 yshift ( " ) where xscale and yscale are the horizontal and vertical scale factors, angle determines rotation (positive rotation is anti-clockwise), and xshift and yshift move the object horizontally and vertically respectively. In effect, scaling is applied first and has no effect on the location of the start of the text baseline (x0,y0 - defined by the coordinates at +72 and +76). The scale factors and the font size entries at +64 and +68 determine the final size of the text. Then the text is rotated about x0,y0 by the specified angle. The last two entries in the transformation matrix (usually zero) are added to the coordinates at +72 and +76. The font flags at +48 are: bit 0 : if set, text should be kerned bit 1 : if set, text written from right to left bits 2-31: reserved (must be zero). See the description of the text object format above for an explanation of the other components of this object. Transformed Sprite Object (object type number 13) ================================================= Offset Size Description ------ ---- ----------------------------------------------------------- +0 4 object type identifier (= 13). +4 4 total size of this object (bytes). +8 4 bounding box xmin (inclusive). +12 4 bounding box ymin (inclusive). +16 4 bounding box xmax (exclusive). +20 4 bounding box ymax (exclusive). +24 24 transformation matrix. +48 a single sprite (without the sprite area control block). The 24 byte object header is followed by the transformation matrix (see transformed text object format) and then the sprite as described previously for sprite objects. The coordinates of the (pre-transformation) bottom-left corner of the sprite - which are unaffected by scaling and/or rotation - are given by the last two entries in the transformation matrix. The size of the sprite when rendered depends on the size of the sprite itself and the scale factors in the matrix.