home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Datafile PD-CD 5
/
DATAFILE_PDCD5.iso
/
utilities
/
d
/
dubmodule
/
DUBmodule
/
DUBmodSWIs
< prev
Wrap
Text File
|
1996-03-24
|
75KB
|
1,846 lines
DUBmodSWIs:
SWI calls for DrawUtilsB module V1.00 (1 Mar 96)
-------------------------------------------------
Introduction
============
This module provides a number of SWI calls concerned with the creation and -
to a lesser extent - editing of drawfiles. The module can handle all of the
standard object types used by !Draw (up to V0.99 - RISC OS 3.5) but does not
currently support unknown object types.
The SWI calls are:
Name Number Name Number
------------------- ------ ---------------------- ------
DF_LastErrorB &4CCC0 DF_StartTextArea &4CCCD
DF_InitialiseFile &4CCC1 DF_DefineTextArea &4CCCE
DF_SelectFont &4CCC2 DF_WriteTextArea &4CCCF
DF_WriteText &4CCC3 DF_EndTextArea &4CCD0
DF_PathStart &4CCC4 DF_StartTaggedObject &4CCD1
DF_PathMove &4CCC5 DF_EndTaggedObject &4CCD2
DF_PathDraw &4CCC6 DF_StartGroup &4CCD3
DF_PathCurve &4CCC7 DF_EndGroup &4CCD4
DF_PathClose &4CCC8 DF_CompleteFile &4CCD5
DF_PathTextOutline &4CCC9 DF_AbortObject &4CCD6
DF_PathEnd &4CCCA DF_BufferReSized &4CCD7
DF_PreLoadSprite &4CCCB DF_SetUnits &4CCD8
DF_SpriteLoaded &4CCCC DF_SetOrigin &4CCD9
DF_TransformObject &4CCDA
DF_ShiftObject &4CCDB
DF_PrevObjBBox &4CCDC
The module should only be used with RISC OS version 3.1 or later.
Overview
========
Control block & free position offset
------------------------------------
To allow the module to function in a multitasking environment, it needs to
store information about the emerging drawfile in memory rather than within
its own workspace. This 'scratchpad' area is termed the control block, and
occupies the first 1024 bytes of the buffer allocated for the drawfile. Most
of the swi calls require a pointer to the buffer, which is therefore a
pointer to the control block, with the drawfile proper located immediately
after it. The control block is largely invisible to the calling application,
but you must remember not to include it when saving the drawfile.
In most cases the module does not record the address of the next free
location in the drawfile (i.e. where the next entry will be made) but
instead receives and returns a value in R2 which is termed the 'free
position offset'. This is the distance in bytes from the start of the buffer
to the next free location, and is therefore equal to the current drawfile
size plus 1024 bytes for the control block. Thus there is only one actual
pointer (to the buffer itself), which simplifies relocation of the buffer in
memory.
For example, to create and save a simple drawfile containing a line from
(x1%,y1%) to (x2%,y2%) in Basic with coordinates in draw units, you could
use:
DIM buff% 2048
buff_size% = 2048
source_id$ = "MyProg" : REM name of application producing the drawfile
page_size% = &501 : REM code for A4 landscape paper
fpo% = 0 : REM free position offset variable
SYS "DF_InitialiseFile,,buff%,,buff_size%,source_id$,page_size%,0,0 TO,,fpo%
SYS "DF_PathStart",,buff%,fpo%,<parameters for style etc> TO,,fpo%
SYS "DF_PathMove",,buff%,fpo%,,x1%,y1% TO,,fpo%
SYS "DF_PathDraw",,buff%,fpo%,,x2%,y2% TO,,fpo%
SYS "DF_PathEnd",,buff%,fpo% TO,,fpo%
SYS "DF_CompleteFile,,buff%,fpo% TO,,fpo%
SYS "OS_File",10,<Full pathname for drawfile>,&AFF,,(buff%+1024),(buff%+fpo%)
Each swi call requires a pointer to the buffer in R1. DF_InitialiseFile sets
up the control block (1024 bytes), writes the drawfile header (40 bytes) and
options object (88 bytes) specifying A4 landscape paper and returns in R2
the free position offset as fpo% which is therefore 1024+40+88 bytes. This
value is supplied to DF_PathStart which writes the path object header and
returns an incremented value for fpo%, which is supplied in turn to
DF_PathMove and so on.
The calls DF_PathMove/Draw/Curve/Close are included mainly for consistency
and it is usually more efficient to write the necessary values directly into
the drawfile and increment the fpo% value manually. For example
SYS "DF_PathStart",,buff%,fpo%,<parameters for style etc> TO,,fpo%
buff%!fpo% = 2 : buff%!(fpo%+ 4) = x1% : buff%!(fpo%+ 8) = y1%
buff%!(fpo%+12) = 8 : buff%!(fpo%+16) = x2% : buff%!(fpo%+20) = y2%
fpo% += 24
SYS "DF_PathEnd",,buff%,fpo% TO,,fpo%
or you could use an actual pointer (p%) as follows
SYS "DF_PathStart",,buff%,fpo%,<parameters for style etc> TO,,fpo%
p% = buff% + fpo%
!p% = 2 : p%!4 = x1% : p%!8 = y1%
p%!12 = 8 : p%!16 = x2% : p%!20 = y2%
fpo% = p%+24-buff% : REM or just fpo% += 24
SYS "DF_PathEnd",,buff%,fpo% TO,,fpo%
The same method can be used to insert parts of other object types, although
it is probably only useful for path objects.
An incomplete drawfile can be saved for later completion simply by saving it
with its control block. When these are restored the source application can
continue where it left off. A complete drawfile can be loaded for extension
by allocating a buffer of suitable size, calling DF_InitialiseFile to set up
the control block, loading the drawfile (at address = buffer + 1024 bytes)
and finally setting the free position offset value equal to the drawfile
size + 1024 bytes.
Coordinate units & transformation matrices
------------------------------------------
Since the module is accessed by swi calls, all numeric parameters supplied
and results returned are signed 32 bit integers (as used in Basic, C etc).
Thus coordinates must be given as integer values. However, the module can
convert from other (integer) coordinates to draw units according to a units
code passed in R7 to DF_InitialiseFile (this can be changed later using
DF_SetUnits). Currently the module recognizes the following:
Code Units
---- -----------------
0 draw units
1 draw units
2 OS units
3 millipoints
4 millimeters
5 1/10ths millimeter
6 1/1000ths millimeter
An unrecognized units code defaults to draw units.
The selected units are used for all coordinates except those for
DF_TransformObject, DF_ShiftObject and translation entries in transformation
matrices.
Since 1 draw unit = 1/640th of a point (1 point = 1/72nd of an inch), then 1
millimeter = 1814.173 draw units. OS units are used for the screen display
(e.g. a mode 12 screen measures 1280 x 1024 OS units, and notionally 1 OS
unit = 400 millipoints = 256 draw units.
Several swi calls require (or can accept) a transformation matrix to specify
scaling and/or rotation and/or translation; this is a 24 byte block with
(usually) the format:
block%!0 = 65536 * xscale * COS(angle)
block%!4 = 65536 * xscale * SIN(angle)
block%!8 = 65536 * yscale * -SIN(angle)
block%!12 = 65536 * yscale * COS(angle)
block%!16 = x.translation
block%!20 = y.translation
Other formats can be used to distort objects in various ways. In effect,
horizontal and vertical scaling is applied first (xscale, yscale), then
rotation (angle) and finally translation (horizontal and/or vertical shift).
The translation entries are always treated as being in draw units.
Parameters passed by pointer
----------------------------
Various calls accept a pointer to a block of memory containing data (e.g. a
list of fonts, font name, text string or transformation matrix). The block
must be in the user area (address > &8000).
Font names and text strings
---------------------------
Font names and text strings can be terminated by char 0, 10 or 13 (with the
possible exception of DF_WriteTextArea).
Complete and incomplete objects
-------------------------------
Group, tagged, path, sprite and text area objects are created by two or more
calls to the module. The initial call writes the object header with size = 0
and an inverted bounding box (xmin = ymin = large positive value, xmax =
ymax = large negative value). Until the appropriate end-object call is
issued such objects are obviously incomplete. When the end-object call is
issued, the object is verified (to some extent) and if no error is found the
proper size and bounding box values are are written to the header (and the
object is complete).
Once a path object is initiated (DF_PathStart), the module will only accept
path-related calls (DF_PathMove/Draw/Curve/Close/TextOutline) until
DF_PathEnd is called.
Initiating a sprite object (DF_PreLoadSprite) can only be followed by
DF_SpriteLoaded.
Once a text area is initiated, the module will only accept text area-related
calls (with some restrictions on their order) until DF_EndTextArea is
called.
These restrictions do not apply to certain non-object specific calls
(DF_BufferResized, DF_SetUnits, DF_SetOrigin) which can be issued at any
time.
An incomplete path, sprite or text area object can be abandoned by calling
DF_AbortObject. This restores the control block and free position offset to
their state immediately before the object was started. There is no facility
to abort a group object or tagged object.
Error reporting
---------------
Wherever possible, the module checks for an error condition before altering
the drawfile, so that in the event of an error (e.g. insufficient buffer
space or incorrect parameters for an swi call) the drawfile is left
unaltered and the call can be repeated after appropriate corrective action.
This is not always possible (e.g. for path objects created by direct entry
as described above or for sprite objects loaded from disc), and
alternatively or additionally the module will verify an object on its
completion (e.g. DF_PathEnd, DF_SpriteLoaded). If an error is returned in
these circumstances corrective action may be possible but it would probably
be easier to abandon the object (with DF_AbortObject) and redo it.
The method of error reporting is similar (not identical) to that used by the
DrawUtilsA module and depends on bit 0 of the control flags parameter passed
in R0 for all swi calls except DF_LastErrorB (which ignores R0).
If the bit is clear, any error results in a non-zero error code being
returned in R0 (R0 = 0 means no error) with the other registers unchanged.
The calling application should therefore check R0 after each call to the
module.
If the bit is set, the module may return a (non-zero) pointer to an os error
block resulting in an error which (e.g.) can be trapped in Basic with an ON
ERROR statement (you can also use the 'X' form of the swi). There is only
one error number (same as the module base chunk value, &4CCC0) and the error
text is
DrawUtils(B) module error: &code, tag, position, offset
Here, code is the error code in hexadecimal (as indicated by the ampersand),
tag is the tag type of the object containing the error, position is the
location of the object in bytes from the start of the drawfile and offset is
the location of the error-causing sequence in bytes from the start of the
object.
With either method, a call to DF_LastErrorB immediately after the error is
returned (before any other calls which would overwrite the module's internal
status block) will give the code, tag, position and offset values in R0 -
R3.
Most errors are detected by examination of the entry parameters etc before
altering the drawfile, and therefore the error is not actually in the
drawfile. Thus in most cases tag = position = offset = 0 (if tag is zero
then so are the others). An offset value is only returned for path object
errors. The swi calls which can return non-zero tag, position and offset
values are DF_EndPath (checks path object structure), DF_SpriteLoaded
(checks sprite object structure), DF_TransformObject & DF_ShiftObject
(checks path object structure if applied to a path object and scans through
the drawfile to check group & tagged object bounding boxes) and
DF_CompleteFile (also scans through the drawfile to check group & tagged
object bounding boxes).
SWI calls
=========
For all SWI calls-
Interupts are enabled
Fast interupts are enabled
Processor is in SVC mode
SWI is not re-entrant
DF_LastErrorB (SWI &4CCC0)
===========================
Purpose: return contents of module error status block.
On entry: registers unused
On exit: R0 = error code
R1 = tag of type of object containing error
R2 = position of object
R3 = offset to error sequence
This call returns details of the last error to occur for any of the other
module SWI calls; see the explanation of error reporting above for details.
If there was no error then R0 = 0 and the other registers are undefined.
DF_InitialiseFile (SWI &4CCC1)
===============================
Purpose: initialise the control block and write the drawfile header
(optionally with an options object and/or font table object).
On entry: R0 = control flags
R1 = pointer to buffer for control block and
drawfile (must be in user area, address > &8000 and
word-aligned)
R2 = unused
R3 = size of buffer (minimum 2048 bytes)
R4 = pointer to source identification string
R5 = page size code
R6 = pointer to font list for font table object
R7 = units code
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = free position offset
R3 = buffer size (may be altered to a multiple of 4)
R4 = preserved
R5 = page size code (may be altered to a recognized value)
R6 = number of fonts written to font table object
R7 = units code (may be altered to a recognized value)
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
Buffer size
-----------
The minimum size for the buffer is 2048 bytes, and the module uses the first
1024 bytes as the control block. The module needs to know the size of the
buffer so it can check the amount of free space before writing to the
drawfile.
Souce identification string
---------------------------
The source identification string (R4) is a text string (maximum 12
characters, terminated by ascii 0, 10 or 13) which usually identifies the
application which created the drawfile. A maximum of 12 characters will be
copied into the drawfile header or the string will be padded with spaces to
a length of 12 characters.
Page size code & options object creation
----------------------------------------
If the page size code (R5) is non-zero, an options object is added with the
appropriate page size code entry and the default options for !Draw (e.g.
rectangular cm 1 x 2 grid, etc). The page size code is the paper 'A' size
plus 1 multiplied by 256 plus 1 for landscape orientation (e.g. A4 portrait
= &500, A4 landscape = &501, A5 landscape = &601). An unrecognized code
defaults to A0 paper. The page size code can be changed later with
DF_CompleteFile. If the page size code is zero then an options object is not
inserted (and there is no facility to add one later).
Font table creation
-------------------
If R6 is non-zero it is used as a pointer to a block containing a list of
fonts for inclusion in the font table object. The format of the list is
block + 0 1st font name
+ 40 2nd font name
+ ((n-1)*40) nth font name
+ (n*40) null string terminator
Font names can be terminated by ascii 0, 10 or 13. Each font must exist. The
fonts are written into the font table with numbering starting at 1. If a
font in the list is already included in the font table object then it is
ignored (i.e. there will not be duplication in the font table object because
!Draw doesn't like this). Thus the fonts may not be numbered according to
their location in the list. The actual number of fonts written into the font
table object is returned in R6.
Note that even if text objects will subsequently be included in the
drawfile, it is not essential to specify a list of fonts when initialising
the file since the module will insert or extend the font table object if
necessary when DF_WriteText or DF_WriteTextArea (with a '\F' sequence) is
called.
Units code
----------
See 'Overview' above for an explanation of coordinate units and the units
code passed in R7.
DF_SelectFont (SWI &4CCC2)
===========================
Purpose: select a font, size and colours for subsequent use by DF_WriteText
and DF_PathTextOutline.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = unused
R3 = font number (1 - 255) or pointer to font name
R4 = horizontal size (in 256ths of a point)
R5 = vertical size (in 256ths of a point)
R6 = foreground colour (as &BBGGRR00)
R7 = background colour (as &BBGGRR00)
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1-R7 = preserved
This call selects a font, size and colours for subsequent use by
DF_WriteText and DF_PathTextOutline. The selection remains in effect until
changed by another call to DF_SelectFont.
The font can be specified by its number in the font table object (allowable
values 1 - 255 inclusive) providing it is already listed in the font table,
or by name (which must exist and can be terminated by ascii 0, 10 or 13).
The minimum horizontal and vertical size is 1 pt.
DF_WriteText (SWI &4CCC3)
==========================
Purpose: add a text object or transformed text object to the drawfile.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = pointer to text string
R4 = x.position
R5 = y.position
R6 = rotation value or pointer to transformation matrix
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-2 determines interpretation of R6
3-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3-R6 = preserved
R7 = increase in font table object size
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
Font selection & colours
------------------------
A font, size and colours must have been selected with DF_SelectFont before
using this call. The module does not support use of the system font (but you
can use System.Fixed and System.Medium fonts). The background colour is
passed to the font manager when the drawfile is rendered so that an
anti-aliasing palette can be set up (there is no 'rub-out' box behind the
text - the text is just overlaid on whatever forms the background).
Text string
-----------
The text string must contain only printable characters (codes 32-126 and
128-255 inclusive) and can be terminated by ascii 0, 10 or 13.
Coordinates
-----------
The x- and y-coordinates (R4 and R5) are in whatever units are currently
selected and determine the location of the start of the string baseline (an
imaginary underline - descenders such as 'g' and 'y' - go below this line).
Rotation or transformation
--------------------------
If R6 is zero a (non-transformed) text object is created. Otherwise, a
transformed text object is created and R6 is interpreted as follows:
•if R0 bit 2 is set, R6 is a pointer to a transformation matrix; the
translation entries in the matrix (which are in draw units) are added to
the x- and y-position values in R4 and R5 after these have been converted
to draw units.
•if R0 bit 2 is clear, R6 is a rotation angle in 256ths of a degree (R0 bit
1 clear) or 65536ths of a radian (R0 bit 1 set) and a transformation matrix
is generated from this angle.
Scaling and/or rotation do not affect the location of the start of the
string baseline. DF_TransformObject provides a more flexible way of
transforming an object.
A text object can be created with a 'unit' transformation matrix - i.e.
xscale = yscale = 1, rotation = 0, x- and y-translation = 0 - and
transformed later with DF_TransformObject. The overall effect is the same,
but this method would avoid the need to reposition any objects following the
text object to allow insertion of the transformation matrix (although the
module will do this if necessary).
Font table entry
----------------
If the selected font is not already listed in the font table object, the
font table is extended (or one is inserted); since the font table is located
near the start of the drawfile, everything following it is moved upwards in
memory by an amount which is returned (in bytes) in R7. This may be useful
if you have previously recorded the position of an object relative to the
start of the buffer (e.g. for a subsequent call to DF_ShiftObject or
DF_TransformObject). The free position offset value returned in R2 is
automatically adjusted to include any increase in font table size.
DF_PathStart (SWI &4CCC4)
==========================
Purpose: initiate a path object by writing the object header to the
drawfile.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = line colour (as &BBGGRR00); use -1 for none
R4 = fill colour (as &BBGGRR00); use -1 for none
R5 = line width (in draw units)
R6 = dash pattern (use 0 for no dash pattern)
R7 = join style and winding rule
R8 = end cap styles
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3-R8 = preserved
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
Dash pattern
------------
The dash pattern parameter passed in R6 can be 0 (no dash pattern), 1-4 (for
standard patterns as used by !Draw), or a pointer to a block containing a
pattern definition. As an example, the definition for pattern 4 (long/short
dash) is:
block%!0 = 0 : initial gap length (draw units, must be >= 0)
block%!4 = 4 : number of entries following (multiple of 2, max = 8)
block%!8 = &2400 : line length }
block%!12 = &900 : gap length } draw units,
block%!16 = &900 : line length } must be > 0
block%!20 = &900 : gap length }
Join style and winding rule
---------------------------
The join style and winding rule parameter (R7) uses bits 0 and 1 for the
style and bit 8 for the winding rule. Possible join styles are:
0 = mitred (default for unrecognized value)
1 = round
2 = bevelled
If bit 8 is set the winding rule is non-zero, otherwise it is even-odd.
End cap styles
--------------
The end cap styles parameter passed in R8 is a bitfield as follows:
bits 0- 7 leading cap style
bits 8-15 trailing cap style
bits 16-23 triangular cap width } if appropriate, in 16ths of the
bits 24-31 triangular cap length } line width, maximum = 255
Possible styles are:
0 = butt cap (default for unrecognized value)
1 = round cap
2 = projecting square cap
3 = triangular cap
Therefore the R8 parameter could be calculated as:
cap_style1% + (cap_style2% << 8) + (tri_cap_wid% << 16) + (tri_cap_len% << 24)
If leading and trailing triangular caps are selected they must have equal
width and length.
Path structure
--------------
A completed path object consists of the object header followed by one or
more subpaths. Each subpath must start with a move (component tag = 2),
which must be followed by at least one draw (tag = 8) or curve (tag = 6)
component. A subpath can optionally end with a close (tag = 5, e.g. for a
square, circle etc). A move (tag = 2) to start a new subpath automatically
ends the preceeding subpath. The final subpath must be followed by an end
marker (tag = 0).
Subsequent path-related calls
-----------------------------
After this call, the module will only accept DF_PathMove/Draw/Curve/Close/
TextOutline until DF_PathEnd is called (or the path object is abandoned with
DF_AbortObject). To allow the calling application to insert path data
directly into the drawfile, there is no restriction on the order of these
calls (although DF_PathEnd will check that the path structure is valid).
DF_PathMove, DF_PathDraw, DF_PathCurve, DF_PathClose (SWI &4CCC5 - 8)
======================================================================
Purpose: add a component to a path object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = unused
R4 = x-coordinate } these are unused
R5 = y-coordinate } for DF_PathClose
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1 do not write 0 for curve control point coordinates
2-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3-R5 = preserved
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
Coordinates
-----------
The x- and y-coordinates (R4 and R5) are in whatever units are currently
selected. DF_PathClose does not use any coordinates.
Bezier curve segments
---------------------
For a curve segment, the coordinates should be that of a point on the curve;
the module can calculate the appropriate control point coordinates for a
standard bezier curve as would be entered free-hand in !Draw. Curve segments
can be mixed with move/draw/close segments subject to the rules of path
structure described under DF_PathStart. The control point coordinates are
calculated when DF_PathEnd is called. At this stage the module writes zero
for each control point coordinate unless R0 bit 1 is set, in which case it
does not write anything (it skips over the appropriate memory locations).
DF_PathTextOutline (SWI &4CCC9)
================================
Purpose: obtain the outline for a text string and write this as a sub-path.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = pointer to text string
R4 = x.position
R5 = y.position
R6 = rotation value or pointer to transformation matrix
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-2 determines interpretation of R6
3-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3-R6 = preserved
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
Note that this call creates a complete subpath starting with a move; it
could be used (e.g.) as shown below. Text outlines usually give rise to
quite complex path structures and it is recommended that only short text
strings be used. Examples:
DF_PathStart
DF_PathMove 1st subpath
DF_PathDraw/Curve etc "
DF_PathTextOutline 2nd subpath
DF_PathMove 3rd subpath
DF_PathDraw/Curve etc "
DF_PathEnd end of path object
or just
DF_PathStart
DF_PathTextOutline
DF_PathEnd
Path style
----------
This call will change the path style attributes in the object header; join
style is set to mitred and end-cap styles are set to butt.
Font selection
--------------
A font, size and colours must have been selected with DF_SelectFont before
using this call (the colours have no effect - the actual colours used are
specified in the path object header). The module does not support use of the
system font (but you can use System.Fixed and System.Medium fonts).
Text string
-----------
The text string can contain the escape sequences listed below which are
recognized by the Font Manager and can be terminated with ascii 0, 10 or 13.
Each entry is a single byte.
9, dx_low, dx_middle, dx_high (horizontal move)
11, dy_low, dy_middle, dy_high (vertical move)
17, foreground colour } colour is determined by the path object
18, background colour } header - these have no effect
21, comment string (ending with any ctrl character)
25, underline_position, underline_thickness
26, font_handle (to change font, handles must have been assigned
beforehand)
Coordinates
-----------
The x- and y-coordinates (R4 and R5) are in whatever units are currently
selected and determine the location of the start of the string baseline (an
imaginary underline - descenders such as 'g' and 'y' - go below this line).
Rotation or transformation
--------------------------
If R6 is non-zero it is interpreted as follows:
•if R0 bit 2 is set, R6 is a pointer to a transformation matrix; the
translation entries in the matrix (which are in draw units) are added to
the x- and y-position values in R4 and R5 after these have been converted
to draw units.
•if R0 bit 2 is clear, R6 is a rotation angle in 256ths of a degree (R0 bit
1 clear) or 65536ths of a radian (R0 bit 1 set) and a transformation matrix
is generated from this angle.
Scaling and/or rotation do not affect the location of the start of the
string baseline.
DF_PathEnd (SWI &4CCCA)
========================
Purpose: complete a path object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1 only write control point coordinate values if
existing values (x & y) are both zero
2 never write control point coordinates
(takes precedence over bit 1)
3-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call adds the end-of-path marker, verifies the path structure, and (if
no error is found) writes the object size and correct bounding box values to
the object header. Optionally, control point coordinates can be calculated
for bezier curve segments using the standard method (e.g. as used when
entering a curve free-hand in !Draw); this means that you define the curve
by means of points on the curve.
If R0 bit 2 is set, no control point coordinates are calculated; this would
be used if the calling application had calculated these itself or if the
path did not contain any curve segments (this saves a little time).
Otherwise-
•if R0 bit 1 is set the module will only write control point coordinates if
the existing values (both x & y) are zero; this would be used if the
calling application calculated some of the control point coordinates but
wanted the module to do the others (which would initially be written as cx
= cy = 0 when the path curve component was written to the drawfile).
•if R0 bit 1 is clear control point coordinates are calculated and written
for all curve segments in the path.
A curve segment contains two control points (i.e. cx1,cy1 and cx2,cy2) which
- in regard to the comments above - are treated completely separately.
DF_PreLoadSprite (SWI &4CCCB)
==============================
Purpose: write a sprite object header to the drawfile and prepare to load a
sprite file.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = unused
R4 = bounding box xmin }
R5 = " ymin } in whatever units are
R6 = " xmax } currently selected
R7 = " ymax }
R8 = rotation value or pointer to transformation matrix
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-2 determines interpretation of R8
3-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3-R8 = preserved
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
If R8 is zero, a non-transformed sprite object will be created. When the
drawfile is rendered, the sprite will be scaled to exactly fit the bounding
box defined by R4-R7; it is essential that xmax > xmin and ymax > ymin.
If R8 is non-zero, its interpretation depends on bits 1 and 2 of R0 as
follows:
•if R0 bit 2 is set, R8 is a pointer to a transformation matrix. The final
size of the sprite (when the drawfile is rendered) depends on the sprite
itself and the x- and y-scale factors in the matrix, and so the xmax and
ymax values (R6 & R7) are ignored. The xmin and ymin values (R4 & R5)
determine the location of the (pre-transformation) bottom-left corner of
the sprite (which is unaffected by scaling and/or rotation). The
translation entries in the matrix are in draw units and are added to the R4
& R5 coordinates (after the latter have been converted to draw units).
•if R0 bit 2 is clear, R8 is a rotation angle in 256ths of a degree (R0 bit
1 clear) or 65536ths of a radian (R0 bit 1 set). The sprite is scaled to
fit the bounding box defined by R4-R7 (must have xmax > xmin and ymax >
ymin) and rotated by the specified angle about its bottom-left corner.
A sprite object can be created with a 'unit' transformation matrix - i.e.
xscale = yscale = 1, rotation = 0, x- and y-translation = 0 - and
transformed later with DF_TransformObject. The overall effect is the same,
but this method would avoid the need to reposition any objects following the
sprite object to allow insertion of the transformation matrix (although the
module will do this if necessary).
The portion of the buffer after the sprite object header is initialised as a
sprite area (at address = buffer + free position offset after this call);
this is a temporary measure in preparation for loading a sprite file. For
example, you could use:
SYS "DF_PreLoadSprite",1,buff%,fpo%,,xmin%,ymin%,xmax%,ymax%,0 TO,,fpo%
address% = buff% + fpo%
SYS "OS_SpriteOp",(10+256),address%,<full pathname of sprite file>
SYS "DF_SpriteLoaded",1,buff%,fpo% TO,,fpo%
Before loading the sprite file, you should check the amount of free buffer
space (total buffer size minus free position offset value) against the file
size. A sprite file consists of a header followed by one or more sprites; if
there is more than one then only the first is incorporated into the
drawfile.
DF_SpriteLoaded (SWI &4CCCC)
=============================
Purpose: complete a sprite object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call expects to find the sprite object header (24 or 48 bytes) followed
by a standard sprite area control block (initialised by DF_PreLoadSprite and
updated on loading the sprite file) followed by the sprite. The module
obtains the location and size of the sprite from the control area and moves
it down in memory overwriting the control area. The sprite is then verified
and (if no error is found) the correct size and bounding box values are
written to the sprite object header.
DF_StartTextArea (SWI &4CCCD)
==============================
Purpose: initiate a text area object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = unused
R4 = initial text foreground colour (as &BBGGRR00)
R5 = initial text background colour (as &BBGGRR00)
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3-R5 = preserved
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call writes the header for a text area object. It must be followed by
at least one call to DF_DefineTextArea to define the text column object(s)
(the rectangular areas over which the text is formatted).
The DrawUtilsA module provides a call - DF_TextAreaExtent - which finds the
actual area occupied by the text in a text area object. This allows some
degree of automation of sizing and positioning of the text column objects
(the rectangular areas over which the text is formatted). After completing
the text area object, DF_TextAreaExtent could be called and the text column
object coordinates then adjusted manually (the bounding box entries in the
text area object header should be adjusted accordingly).
DF_DefineTextArea (SWI &4CCCE)
===============================
Purpose: add a text column object to a text area object to define a
rectangular area over which the text will be formatted.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = unused
R4 = area xmin } in whatever units are
R5 = ymin } currently selected
R6 = xmax } (must have xmax > xmin
R7 = ymax } and ymax > ymin)
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3-R7 = preserved
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call can be followed only by another call to DF_DefineTextArea or to
DF_WriteTextArea.
DF_WriteTextArea (SWI &4CCCF)
==============================
Purpose: add text to a text area object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset (optional - see below)
R3 = pointer to text string
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting.
1 text string terminator is ascii 0, else is
ascii 0, 10 or 13.
2 on entry, use free position offset in R2.
3 on exit, return free position offset in R2.
4-31 reserved (should be zero).
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset - see below
R3-R6 = preserved
R7 = increase in font table object size (for '\F' sequence)
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call can only be followed by another call to DF_WriteTextArea or one to
DF_EndTextArea.
Free position offset
--------------------
This call is unusual in that by default the module does not use the free
position offset passed and returned in R2, but instead uses an internal
offset value (stored in the drawfile control block area) which is set up by
a call to DF_DefineTextArea, and which is updated automatically with each
call to DF_WriteTextArea (based on the length of the text string).
If R0 bit 2 is clear or R2 is zero on entry, the internal offset is used to
determine where to add the text string to the drawfile. This internal offset
is incremented according to the length of the string and (if R0 bit 3 is
set) returned in R2.
R2 can be used in the usual way if R0 bits 2 and 3 are set, except that the
value does not have to be a multiple of four.
Text string
-----------
The text string should contain only printable characters (codes 32-126 and
128-255). It can be terminated by character 0, 10 or 13 if R0 bit 1 is clear
or only by a null character (ascii 0) if R0 bit 1 is set (the latter would
be used when reading the text from a file).
The text string can contain any of the escape sequences (beginning with a
back-slash character) described in the section on !Draw in the User
Guide/Applications Guide or Programmers Reference Manual. Two or more of
these sequences can be included in the text string, but do not split a
sequence between calls to DF_WriteTextArea.
If the text string contains a font definition ('\F') sequence, the font is
added to the font table object if not already included (a font table object
will be created if necessary). Since the font table is located near the
start of the drawfile, everything following it is moved upwards in memory by
an amount which is returned (in bytes) in R7. The free position offset value
(whether or not returned in R2) is automatically adjusted to include this
increase in font table size.
Reading from file
-----------------
When reading from a text file, loading the text directly into the drawfile
is not recommended. Instead you should use a temporary buffer as shown
below:
REM get size of text file, allocate temporary buffer, load text file
REM and ensure null char terminator.
SYS "OS_File", 17, <full pathname of text file> TO,,,, size%
DIM text_buff% size%
SYS "OS_File", 16, <full pathname of text file>, text_buff%, 0
text_buff%?size% = 0
REM now create the text area object (this example uses R2):
SYS "DF_StartTextArea", 1, buff%, fpo%,,0, &FFFFFF00 TO,,fpo%
SYS "DF_DefineTextArea", 1, buff%, fpo%,,xmin%,ymin%,xmax%,ymax% TO,,fpo%
SYS "DF_WriteTextArea", (1+2+4+8), buff%, fpo%, text_buff% TO,,fpo%
SYS "DF_EndTextArea", (1+4+8), buff%, fpo% TO,,fpo%
Text entry from the calling application
---------------------------------------
The calling application can write directly to the text area object as
follows:
SYS "DF_StartTextArea", 1,buff%,fpo%,,0,&FFFFFF00 TO,,fpo%
SYS "DF_DefineTextArea",1,buff%,fpo%,,xmin%,ymin%,xmax%,ymax%
SYS "DF_WriteTextArea", 1,buff%,,"\!1"
SYS "DF_WriteTextArea", 1,buff%,,"\F0Trinity.Medium 12/\F1Corpus.Bold 12"
SYS "DF_WriteTextArea", 1,buff%,,"\F2Trinity.Bold 16/\F3Corpus.Bold 14"
SYS "DF_WriteTextArea", 1,buff%,,"\AC\L14/\P3/\2Draw\AD"
SYS "DF_WriteTextArea", 1,buff%,,"\1Draw\0\P18/ is the most powerful of the applications"
SYS "DF_WriteTextArea", 1,buff%,,"supplied with \1RISC OS\0. It is a structured"
SYS "DF_WriteTextArea", 1,buff%,,"graphics program that can work with a variety of"
SYS "DF_WriteTextArea", 1,buff%,,"basic object types."
SYS "DF_WriteTextArea", 1,buff%,,""
SYS "DF_WriteTextArea", 1,buff%,,"\AC\P3/\3Paths\AD"
SYS "DF_WriteTextArea", 1,buff%,,"\1\P18/\U-25 15/Paths\0\U./ are sequences of straight"
SYS "DF_WriteTextArea", 1,buff%,,"and curved lines of arbitrary thickness and colour,"
REM more calls to DF_WriteText Area...
SYS "DF_EndTextArea", 1,buff% TO,,fpo%
Each text string can be terminated by character 0, 10 or 13 or only by a
null character (ascii 0) depending on R0 bit 1. These terminating characters
are converted to newlines (ascii 10) when written to the text area object.
When rendered, a single newline is treated as a space. Therefore, the
lengths of the text strings supplied to DF_WriteTextArea do not reflect how
they will be formatted during rendering (this depends on the font and size,
and the area width less margin values, etc).
Two or more (= n) newlines gives a vertical gap equal to (n-1) times the
paragraph leading plus one linespace. Supplying a null string to
DF_WriteTextArea adds a newline to the one ending the previous text string
(giving two newlines) which results in a new paragraph being started.
Escape sequences
----------------
Full details of the escape sequences (which always begin with a back-slash
character) can be found in the User Guide/Applications Guide or Programmers
Reference Manual. Most of these can be terminated either by a slash
character or a newline (DF_WriteTextArea allows chars 0, 10 and 13 for
newline depending on R0 bit 1).
The text must begin with an initializer ('\!1') sequence. If two or more
physical areas are used, you must include a '\Dn' sequence with n equal to
the number of areas (each defined by a call to DF_DefineTextArea). The '\D'
sequence must appear before any printable (i.e. when rendered) text;
immediately after the '\!1' sequence is recommended. If there is only one
physical area then the '\D' sequence is optional.
The escape sequence code letter is case-sensitive; e.g. '\P' defines the
paragraph leading, '\p' is unrecognized and gives an error. Numeric
parameters are integers (a decimal point will result in an error). A font
definition sequence ('\F') will add the specified font (which must exist) to
the font table object if not already listed.
DF_EndTextArea (SWI &4CCD0)
============================
Purpose: complete a text area object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset (optional - see below)
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1 unused (should be zero)
2 on entry, use free position offset in R2.
3-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
If R2 is zero or R0 bit 2 is clear the internal offset value is used to
determine the size of the text area object (see DF_WriteTextArea for
explanation).
This call ensures that the text area object is properly terminated (newline
followed by a null character with additional null chars to a word boundary)
and writes the correct size and bounding box entries to the object header.
DF_StartTaggedObject (SWI &4CCD1)
==================================
Purpose: initiate a tagged object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = secondary tag value
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3 = current tagged object nesting level
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call writes the header for a tagged object. Tagged objects provide a
means by which standard objects can be packaged along with additional data
which is ignored by applications such as !Draw but which would be relevant
to a specific editor or rendering program.
The structure of a tagged object is:
+ 0 Object tag (type identifier, = 7)
+ 4 Total object size (bytes, including additional data at end of
this tagged object)
+ 8 Object bounding box xmin }
+12 " " " ymin } in draw units
+16 " " " xmax }
+20 " " " ymax }
+24 Secondary tag value
+28 A complete object (with size = n bytes, can be a group, tagged,
text, path, sprite or text area object)
+(28+n) Optional additional data (multiple of 4 bytes)
The secondary tag value and optional additional data at the end of the
object are ignored by applications such as !Draw. Tagged objects cannot be
edited in !Draw; they cannot be re-positioned, scaled or rotated and the
style attributes etc. of the object contained within the tagged object
cannot be altered.
The object contained within the tagged object can be a group object
(containing one or more objects) or a tagged object (containing one object)
or a path, text, sprite or text area object. Thus tagged objects can be
nested. The DrawUtilsB module allows a maximum nesting level of 15. The
current nesting level is returned in R3 (this is initially zero, increments
by 1 with each call to DF_StartTaggedObject and decrements by 1 with each
call to DF_EndTaggedObject).
As an example, to incorporate a path object into a tagged object with an
additional 16 bytes of data following, you could use:
SYS "DF_StartTaggedObject",1,buff%,fpo%,0 TO,,fpo%
SYS "DF_PathStart",1,buff%,fpo%,<path style parameters> TO,,fpo%
...calls to DF_PathMove/Draw/Curve/Close etc...
SYS "DF_PathEnd",1,buff%,fpo% TO,,fpo%
buff%!fpo% = extra_data1%
buff%!(fpo%+4) = extra_data2%
buff%!(fpo%+8) = extra_data3%
buff%!(fpo%+12) = extra_data4%
fpo%+= 16
SYS "DF_EndTaggedObject",1,buff%,fpo% TO,,fpo%
DF_EndTaggedObject (SWI &4CCD2)
================================
Purpose: complete a tagged object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3 = current tagged object nesting level
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call completes a tagged object by writing the correct object size and
bounding box values to the object header. The bounding box is identical to
that of the object contained within the tagged object.
Any additional data should be written directly into the drawfile and the
free position offset value incremented by the appropriate amount before
issuing this call (see example under description of DF_StartTaggedObject).
DF_StartGroup (SWI &4CCD3)
===========================
Purpose: initiate a group object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = 0 or pointer to group identifier string
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3 = current group object nesting level
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call writes the header for a group object. On entry, R3 can be a
pointer to a string identifier (max 12 characters) for the group. This may
be relevant to specific editors or rendering programs. Usually this is just
written as 12 spaces (use R3 = 0 for this).
All objects created between issuing this call and the corresponding
DF_EndGroup are included in the group. The DrawUtilsB module allows group
objects to be nested to a depth of 127. The current nesting level is
returned in R3 (this is initially zero, increments by 1 with each call to
DF_StartGroup and decrements by 1 with each call to DF_EndGroup).
DF_EndGroup (SWI &4CCD4)
=========================
Purpose: complete a group object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = incremented free position offset
R3 = current group object nesting level
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call completes a group object by writing the correct object size and
bounding box values to the object header. The bounding box is that which
precisely encloses the bounding boxes of all objects in the group.
DF_CompleteFile (SWI &4CCD5)
=============================
Purpose: check for completion of the drawfile.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3-R5 = unused
R6 = 0 or page size code
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = free position offset
R3 = 0 or incomplete object type (tag value)
R4 = group object nesting level
R5 = tagged object nesting level
R6 = page size code (may be altered to a recognized value)
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
There is no end-of-file marker in a drawfile - its size is given by the file
size attribute which is not actually contained within the file - and this
call is largely optional. This call;
•checks that there is no incomplete path, sprite or text area object in the
drawfile; if there is then its tag value is returned in R3 (otherwise R3 =
0)
•checks that there are no incomplete group or tagged objects; the nesting
levels are returned in R4 and R5 and should both be zero
•if R3=R4=R5=0, checks that group and tagged object bounding boxes are
correct for the object(s) contained therein (this is seldom necessary) and
sets the image bounding box in the drawfile header (which will probably be
correct anyway)
•if no errors are found and R6 is non-zero, R6 is taken as a page size code
(see DF_InitialiseFile) and used to alter the options object (if there is
no options object then R6 is ignored).
Therefore, this call checks for completion of the drawfile and does not
preclude addition of more objects to the file. Alternatively, this call
could be used (e.g.) to check that the image bounding box was correct and
then issued again (after reading the image size) to set the page size in the
options object.
DF_AbortObject (SWI &4CCD6)
============================
Purpose: abandon an incomplete path, sprite or text area object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = free position offset (altered if R3 <> 0)
R3 = 0 or object type (tag value)
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call should be used if a path, sprite or text area object has been
initiated but is to be abandoned (before completion) for any reason. It
resets the control block status flags (including those determining which
calls can be applied to the drawfile) and restores the free position offset
to its value immediately before the object was initiated.
DF_BufferResized (SWI &4CCD7)
==============================
Purpose: describe a change in buffer size.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = unused
R4 = new buffer size (bytes)
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = free position offset
R3 = preserved
R4 = preserved
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
The module needs to know the buffer size so it can check the amount of free
space before making any additions to the drawfile. This call can be issued
at any time (after DF_InitialiseFile) to report a change in buffer size.
Obviously the new size must not be less than the drawfile size.
DF_SetUnits (SWI &4CCD8)
=========================
Purpose: change coordinate units.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = unused
R3 = unused
R4 = new units code
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = preserved
R3 = preserved
R4 = units code (may be altered to a recognized value)
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call changes the units used to specify (most) coordinates; see
'Overview: Coordinate units & transformation matrices' at the beginning of
this file for details.
DF_SetOrigin (SWI &4CCD9)
==========================
Purpose: define the origin for subsequent calls.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = unused
R3 = unused
R4 = new x.origin } in whatever units are
R5 = new y.origin } currently selected
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = preserved
R3-R5 = preserved
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
The x- and y-origin values are added (after conversion to draw units) to the
coordinates used in all subsequent module calls except DF_TransformObject
and DF_ShiftObject. The origin coordinates are initially set to zero.
DF_TransformObject (SWI &4CCDA)
================================
Purpose: transform an object using a transformation matrix.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = unused
R4 = offset to object (bytes from start of buffer)
R5 = pointer to transformation matrix
R6 = x.origin } for transformation
R7 = y.origin } in draw units
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = free position offset (may be altered)
R3-R7 = preserved
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
This call applies the transformation matrix to the object indicated by R4
(R4 is the offset in bytes from the start of the buffer to the start of the
object).
If necessary, text objects will be converted to transformed text objects and
sprite objects will be converted to transformed sprite objects. Such
conversions increase the size of the objects (by 28 and 24 bytes
respectively) and therefore the size of the drawfile, and the free position
offset returned in R2 is incremented accordingly. Any objects located after
the one indicated by R4 will be moved up in memory by the appropriate
amount.
This call can be applied to any completed object - including a group object
or tagged object but not a text area object - even if it is inside a group
object or tagged object, or is part of an (as yet) incomplete group object
or tagged object.
An error will be reported if:
•there is an incomplete path, sprite or text area object in the drawfile
•the object indicated by R4 is an incomplete group object or tagged object
•the object indicated by R4 is a text area object or a group object or
tagged object containing a text area object (you cannot transform a text
area object).
R6 and R7 define a point (in draw units) about which the transformation
(i.e. scaling and/or rotation) is applied. If, for example, R6 and R7 define
the geometric centre of an object, then the object will be scaled and/or
rotated about its centre with the centre remaining in its original
position).
See 'Overview: Coordinate units and transformation matrices' for the format
of the matrix.
All relevant bounding boxes are updated after this call.
DF_ShiftObject (SWI &4CCDB)
============================
Purpose: alter the position of an object.
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = free position offset
R3 = unused
R4 = offset to object (bytes from start of buffer)
R5 = unused
R6 = x.shift } in draw
R7 = y.shift } units
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = free position offset
R3-R7 = preserved
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
In effect, this call performs the translation-only equivalent of
DF_TransformObject. The same result could be obtained using
DF_TransformObject with xscale = yscale = 1 and rotation = 0. However,
DF_ShiftObject does not convert text objects and sprite objects to their
transformed equivalents - for any object it simply adds the x- and y-shift
values to the existing coordinates.
The restrictions described above for DF_TransformObject apply, except that
DF_ShiftObject can be applied to a text area object.
This call could be used (e.g.) to align an object with a specified point in
the image. This could be done by calculating the dimensions of the object
and appropriate coordinates before adding it to the drawfile. Alternatively,
the object could be created with arbitrary coordinates (e.g. 0,0) and then
moved to the required position after reading the bounding box values and
calculating the appropriate horizontal and vertical shift.
All relevant bounding boxes are updated after this call.
DF_PrevObjBBox (SWI &4CCDC)
============================
Purpose: return bounding box for last object created (or processed).
On entry: R0 = control flags
R1 = pointer to buffer for control block and drawfile
R2 = unused
R3-R6 = unused
control flags: bit meaning when set
---- ----------------
0 determines method of error reporting
1-31 reserved (should be zero)
On exit: R0 = error code or zero
R1 = preserved
R2 = preserved
R3-R6 = bounding box xmin, ymin, xmax, ymax (in draw units)
See 'Overview' above for an explanation of error reporting, the control
block and the free position offset value passed and returned in R2.
The calls listed below record the object bounding box values after creating
or processing (shift/transform) an object; DF_PrevObjBBox returns these
values in R3-R6.
DF_WriteText DF_EndTaggedObject
DF_PathEnd DF_EndGroup
DF_SpriteLoaded DF_TransformObject
DF_EndTextArea DF_ShiftObject
Error codes
===========
Error codes have the hexadecimal format &ttssnnnn where tt is the error
type, ss is the subtype and nnnn is the actual error number. There is a
unique nnnn value for each possible error returned - these are given below
in numerical order. Possible error types are:
&00 Entry parameter error (or insufficient buffer or RMA space).
&20 Logical error.
&40 Entry parameter error or possible corruption of control block
and/or drawfile.
&E0 Corrupt object in drawfile (may be possible to scrap the object and redo).
&F0 Corrupt control block and/or drawfile (recovery from this is unlikely).
and subtypes are:
&00 Miscellaneous.
&10 Memory allocation.
&20 Control block and/or drawfile structure error.
&40 Font selection error.
&60 Text string error.
&80 Invalid path object.
&90 Invalid sprite object.
&A0 Invalid text area object.
Code Description
--------- -------------------------------------------------------------------------
General errors
--------------
0000 0001 Unknown swi call.
0010 0002 Module cannot obtain RMA workspace.
0000 0003 Buffer for control block and drawfile must be in user area (address
> &8000).
0000 0004 Buffer address is not word-aligned.
0010 0005 Minimum size for buffer is 2048 bytes.
4020 0006 Incorrect identification word at start of buffer (should be
'MkDr').
F020 0007 Identification word at buffer + 1024 bytes (= start of drawfile) is
not 'Draw'.
F020 0008 Drawfile major version number is not 201.
0000 0009 Free position offset (passed in R2) is incorrect (too small).
0000 0010 Free position offset (passed in R2) is not a multiple of 4.
2000 0011 Inappropriate operation; is returned (e.g.) if you call DF_PathStart and
then DF_WriteText.
0010 0012 Insufficient free space in buffer for this operation.
0000 0013 Data blocks supplied to module must be in user area (address > &8000).
F020 0014 Pointers in control block area have been corrupted (serious error);
applies to objects created by several swi calls (i.e. path, sprite &
text area objects).
4020 0015 Unrecognised object found (only standard Draw objects are supported);
(may be returned by DF_CompleteFile, DF_TransformObject &
DF_ShiftObject when scanning through the file to check group & tagged
object bounding boxes and by Transform/ShiftObject when checking the
specified object).
4020 0016 Object size is too small or not a multiple of 4 bytes (as for code 15).
4020 0017 Object bounding box has width or height <= 0 (as for code 15).
2000 0018 File contains an incomplete group object, tagged object, path object,
sprite object or text area object (may be returned by DF_CompleteFile).
Font & text errors
------------------
F020 0101 Font table not found (should be immediately after drawfile header).
0040 0102 Unknown font.
0040 0103 Expected a font name but found a null string.
0040 0104 Font name too long (max = 39 chars) or contains invalid characters.
0040 0105 Font number is <1 or >255 (when DF_SelectFont is used with a font
number rather than a name).
0040 0106 No font assigned to this number (when DF_SelectFont is used with a
font number rather than a name).
0040 0107 Minimum font size (width and height) is 1 point.
0040 0108 Font table is full (max = 255 fonts).
0040 0109 No font selected (with DF_SelectFont) before calling DF_WriteText or
DF_PathTextOutline.
0060 0110 Expected a text string (e.g. for DF_WriteText & DF_PathTextOutline).
0060 0111 Unrecognised or disallowed control sequence or ascii 127 character in
string.
Path object errors
------------------
0000 0201 Number of elements in dash pattern definition is <2 or >8.
E080 0202 Unknown component found in path object (only 0, 2, 5, 6 & 8 recognised).
E080 0203 Unexpected path end }
E080 0204 " " move }
E080 0205 " " close } in path object.
E080 0206 " " curve }
E080 0207 " " draw }
E080 0208 No end-of-path marker }
0010 0209 Cannot calculate bounding box for path object (all entries = 0,
otherwise path object is complete) due to failure of RMA workspace claim.
Sprite object errors
--------------------
0000 0301 If a bounding box is used to specify a sprite size then must have
xmax > xmin and ymax > ymin.
E090 0302 Sprite size inconsistent with object size.
E090 0303 Invalid sprite dimensions (width or height <= 0).
E090 0304 Invalid sprite offset (<&2C).
E090 0305 Sprite defined in unknown mode.
E090 0306 Invalid sprite palette size.
E090 0307 Invalid mask offset (<&2C).
E090 0308 Image size inconsistent with sprite dimensions.
E090 0309 Mask size inconsistent with sprite dimensions.
E090 0310 Unknown sprite type (from top byte of mode entry).
Text area object errors
-----------------------
0000 0401 Must have xmax > xmin and ymax > ymin for text column object.
00A0 0402 Initialiser is not '\!1'.
00A0 0403 Absent or late '\!' sequence.
00A0 0404 Late or multiple '\!' sequence (must only appear at start of text area).
00A0 0405 '\D' sequence appears after text output.
00A0 0406 Value in '\D' sequence must match the number of text column objects
created with DF_DefineTextArea.
00A0 0407 Unrecognised alignment code (must be one of L, R, D, C).
00A0 0408 Syntax error or missing parameter in escape sequence.
00A0 0409 Invalid parameter value in escape sequence.
00A0 0410 Incorrect terminator for escape sequence (most allow '/' or newline).
00A0 0411 No font defined for font number in font select (\digit) sequence.
00A0 0412 Attempt to write text before selecting a font with \digit sequence.
Tagged object errors
--------------------
2000 0501 Tagged objects already nested to maximum allowed depth (= 15).
2000 0502 Inappropriate call to DF_EndTaggedObject (there was no call to
DF_StartTaggedObject).
4020 0503 Pointers in control block area have been corrupted (serious error) or
may be due to incorrect free position offset value (passed in R2).
Group object errors
-------------------
2000 0601 Group objects already nested to maximum allowed depth (= 127).
2000 0602 Inappropriate call to DF_EndGroup (there was no call to DF_StartGroup).
4020 0603 Pointers in control block area have been corrupted (serious error) or
may be due to incorrect free position offset value (passed in R2).
Transform/Shift object errors
-----------------------------
4020 0701 Invalid offset value to indicate object for DF_TransformObject or
DF_ShiftObject (too small or large or not a multiple of 4 bytes).
2000 0702 Incomplete path, sprite or text area object in file.
2000 0703 Text area object disallowed by DF_TransformObject.
------------------------------------------------------------------------------------
Comments concerning this software to:
James McQueen
9/2 15 Croftbank Street
Springburn
Glasgow
G21 4LP