RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

Draw file renderer


Introduction and Overview

DrawFile is a module that renders Draw files. You can do so either to the screen, or to a printer driver during printing. This makes it easy for you to support imported Draw files in your applications.

You can render a Draw file using either a SWI (DrawFile_Render) or a * command (*Render). Both provide similar facilities; in particular, they allow arbitrary transformations. The SWI DrawFile_BBox allows you to determine a Draw file's bounding box before rendering it.

You can also declare the fonts within a Draw file when printing, without having to scan through the file yourself, by calling the SWI DrawFile_DeclareFonts.

Finally, there are service calls that the above SWIs issue if they encounter unknown objects within a Draw file. This provides a hook for modules that extend the Draw file format to support any new object types they may define. The service calls are Service_DrawObjectRender and Service_DrawObjectDeclareFonts.

Technical details

Differences between DrawFile output and !Draw output

There are some small differences between the output of the DrawFile module and that of !Draw:

Text

A text line that uses a font which can't be found is rendered in the system font at a size to fit its bounding box.

Transformed text

Transformed text lines in the system font are supported.

A transformed text line that uses a font which can't be found is rendered in the system font at a size to fit its bounding box; its transformation is ignored.

Text areas

In a text area, if you change (for example) the margin size (\M command), the change doesn't take effect until the next output line. In Draw this refers to printable characters; but in DrawFile it includes colour and font change commands as well. (This is because DrawFile uses the Font Manager to remember the current font and colours.) This means that line breaks can happen at slightly different places when using DrawFile.

The following commands cause output to occur:

B C U V digits

The following do not:

! ; A D F L M P

By preceding the former with the latter, the problem can be avoided.

Sprite colours

For a sprite without a palette, the colours used are the Wimp colours, found by using Wimp_ReadPalette.

Errors

The errors the DrawFile module provides are

Error name Error number Meaning
Error_DrawFileNotDraw &20C00 The file is not a Draw file (as recognised by the first 4 characters 'D', 'r', 'a', 'w').
Error_DrawFileVersion &20C01 The file specifies a format version number which is not understood.
Error_DrawFileFontTab &20C02 The file contains more than one font table.
Error_DrawFileBadFontNo &20C03 A text line (or transformed text line) uses a font that is not in the font table object.
Error_DrawFileBadMode &20C04 The file contains a sprite defined in a mode which is not recognised.
Error_DrawFileBadFile &20C05 The size of an object in the file is larger than the size of the file allows.
Error_DrawFileBadGroup &20C06 The size of an object in a group is greater than the size of the group allows.
Error_DrawFileBadTag &20C07 The size of a tagged object's data is larger than the size of the tagged object allows.
Error_DrawFileSyntax &20C08 A text area has an illegal or unrecognised command sequence in it.
Error_DrawFileFontNo &20C09 An attempt was made to set a font (with a \<digit> command) which had no definition (\F command).
Error_DrawFileAreaVer &20C0A The text area version command (\!) has specified a version which is not understood.
Error_DrawFileNoAreaVer &20C0B There is a text area with no version (\!) command.

Service calls


Service_DrawObjectRender
(Service Call &45540)

Issued when the SWI DrawFile_Render encounters an unrecognised object

On entry

R0 = object type
R1 = &45540 (reason code)
R2 = pointer to block giving render state:

+ pointer to unknown object (see Draw Objects and JPEG Objects)
+ pointer to Draw file data, as passed to DrawFile_Render
+ pointer to font table object, or 0 if none found yet
+ 2 flags, as passed to DrawFile_Render
+ 6 pointer to transformation matrix, as passed to DrawFile_Render
+ 0 pointer to clipping rectangle, as passed to DrawFile_Render
+ 4 flatness, as passed to DrawFile_Render
+ 8 pointer to error block, or 0 if no error yet
On exit

R1 = 0 if claimed, otherwise preserved

Use

This service call is issued when the SWI DrawFile_Render encounters an object with a type it doesn't recognise, and so cannot process. If a module recognises the unknown object type, it should claim the service call and itself render the object.

If the module encounters an error during rendering, it should examine the error pointer word in the passed render state block:

  • If the word is zero, the declaring module should store its own error pointer in the word.
  • If the word is non-zero, it is already storing an earlier error pointer, which you should not overwrite.

The DrawFile module attempts to render all objects. When it has finished it examines the error pointer word, and if it is non-zero returns the stored error.


Service_DrawObjectDeclareFonts
(Service Call &45541)

Issued when the SWI DrawFile_DeclareFonts encounters an unrecognised object

On entry

R0 = object type
R1 = &45541 (reason code)
R2 = pointer to declare font state block

+ pointer to unknown object (see Objects and Objects)
+ pointer to Draw file data, as passed to DrawFile_DeclareFonts
+ pointer to font table object, or 0 if none found yet
+ 2 flags, as passed to DrawFile_DeclareFonts
+ 6 pointer to error block, or 0 if no error yet
On exit

R1 = 0 if claimed, otherwise preserved

Use

This service call is issued when the SWI DrawFile_DeclareFonts encounters an object with a type it doesn't recognise, and so cannot process. If a module recognises the unknown object type, it should claim the service call and itself declare any fonts in the object.

If the module encounters an error while declaring the fonts, it should examine the error pointer word in the passed font state block:

  • If the word is zero, the declaring module should store its own error pointer in the word.
  • If the word is non-zero, it is already storing an earlier error pointer, which you should not overwrite.

The DrawFile module attempts to declare fonts for all objects. When it has finished it examines the error pointer word, and if it is non-zero returns the stored error.

SWI calls


DrawFile_Render
(SWI &45540)

Renders a Draw file to the screen

On entry

R0 = flags:

bit 0 set => render the bounding boxes around objects as dotted red rectangles
bit 1 set => do not render the objects themselves
bit 2 set => R5 is used as the flatness parameter
R1 = pointer to Draw file data
R2 = size of Draw file data, in bytes
R3 = pointer to transformation matrix, or 0 for identity
R4 = pointer to clipping rectangle in OS units, or 0 if no clipping rectangle set up
R5 = flatness with which to render lines (if bit 2 of R0 set on entry)

On exit

R0 - R5 preserved

Interrupts

Interrupt status in undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call renders a Draw file to the screen. Its position is given by the x- and y-translations in the transformation matrix, which uses the same format as Draw (see Transformation matrix).

Hence to render a non-rotated 1:1 Draw file at screen coordinates (x, y) OS units, the transformation matrix is:

The effects of calling the module with the matrix not of the form:

(ie a translation and a magnification) should not be relied on for underlined text.

If no transformation matrix is given (ie R3 = 0), the unit matrix is used, and so the Draw file is rendered with its bottom left corner at screen coordinates (0, 0).

The clipping rectangle is typically a redraw rectangle returned by the Wimp on a redraw window request. If R4 = 0, then the whole Draw file is rendered. If non-zero, only objects which intersect the clipping rectangle are rendered.

All output calls used when rendering are ones that the printer drivers handle correctly, so you can also use this call to output Draw files when printing.

Just as for all other screen output calls, if you make this call in a Wimp redraw loop (ie after calling Wimp_RedrawWindow) you cannot use Wimp_ReportError to report any error that is returned - since this might lead to an infinite loop of error boxes and redraws of the rectangle covered by the error box. This restriction does not apply to printing redraw loops (ie after calling PDriver_DrawPage).

Related SWIs

DrawFile_BBox, DrawFile_DeclareFonts

Related vectors

None


DrawFile_BBox
(SWI &45541)

Returns the bounding box (in Draw units) a given Draw file will occupy

On entry

R0 = flags: all bits reserved (must be 0)
R1 = pointer to Draw file data
R2 = size of Draw file data, in bytes
R3 = pointer to transformation matrix, or 0 for identity
R4 = pointer to 4 word buffer to hold the bounding box of the Draw file (x0, y0, x1, y1) in internal Draw units

On exit

R0 - R4 preserved

Interrupts

Interrupt status in undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the bounding box (in Draw units) the given Draw file would occupy, were it to be plotted with the given transformation.

Related SWIs

DrawFile_Render, DrawFile_DeclareFonts

Related vectors

None


DrawFile_DeclareFonts
(SWI &45542)

Declares all fonts in a Draw file by calling PDriver_DeclareFont

On entry

R0 = flags:

bit 0 set => do not download font (passed to PDriver_DeclareFont)
R1 = pointer to Draw file data
R2 = size of Draw file data, in bytes

On exit

R0 - R2 preserved

Interrupts

Interrupt status in undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call declares all fonts in a Draw file by calling PDriver_DeclareFont (see PDriver_DeclareFont). If the printer driver you are using supports PDriver_DeclareFont you should call this SWI once for each Draw file to be printed, at the point where you would normally declare fonts (see Declare the fonts your document uses). This saves you having to scan the Draw file yourself to see which fonts it uses. It is your responsibility to make the final call to PDriver_DeclareFont to indicate the end of the list of fonts.

All fonts are declared as 'kerned', since this includes the non-kerned case.

Related SWIs

DrawFile_Render, DrawFile_BBox

Related vectors

None

* Commands


*Render

Displays the contents of a Draw file

Syntax

*Render [-file] filename [m00 m01 m10 m11 m20 m21]
[-bbox] [-suppress] [-flatness flatness]

Parameters

[-file] filename a valid pathname specifying the Draw file to be rendered

m00, m01, m10, m11 - four decimal numbers giving the first four elements of the transformation matrix, which specify the transformation

m20, m21 - two decimal numbers giving the other two elements of the transformation matrix, which specify the translation in OS units

-bbox - render the bounding boxes around objects as dotted red rectangles

-suppress - suppress the rendering of the objects themselves

-flatness flatness - a decimal number giving the flatness used to render curved paths, in OS units

Use

*Render displays the contents of a Draw file. You can optionally transform the output with a transformation matrix, render the bounding boxes around objects as dotted red rectangles, suppress the rendering of the objects themselves, and change the flatness used to render curved paths. In doing so, the file is checked for consistency.

Note that you must quote any negative arguments; see the example below.

Example

*Render ADFS::MHardy.$.DrawFile 0 "-1.5" 1.5 0 0 800 -bbox -flatness .5

Related commands

None

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015