|
www.riscos.com Technical Support: |
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.
There are some small differences between the output of the DrawFile module and that of !Draw:
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 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.
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:
The following do not:
By preceding the former with the latter, the problem can be avoided.
For a sprite without a palette, the colours used are the Wimp colours, found by using Wimp_ReadPalette.
The errors the DrawFile module provides are
Issued when the SWI DrawFile_Render encounters an unrecognised object
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 |
R1 = 0 if claimed, otherwise preserved
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:
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.
Issued when the SWI DrawFile_DeclareFonts encounters an unrecognised object
R0 = object type
R1 = &45541 (reason code)
R2 = pointer to declare font state block
R1 = 0 if claimed, otherwise preserved
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:
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.
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
|
R0 - R5 preserved
Interrupt status in undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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).
Returns the bounding box (in Draw units) a given Draw file will occupy
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
R0 - R4 preserved
Interrupt status in undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call returns the bounding box (in Draw units) the given Draw file would occupy, were it to be plotted with the given transformation.
Declares all fonts in a Draw file by calling PDriver_DeclareFont
R0 = flags:
do not download font (passed to PDriver_DeclareFont)
R0 - R2 preserved
Interrupt status in undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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.
*Render [-file] filename [m00 m01 m10 m11 m20 m21]
[-bbox] [-suppress] [-flatness flatness]
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
*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.
*Render ADFS::MHardy.$.DrawFile 0 "-1.5" 1.5 0 0 800 -bbox -flatness .5