The Datafile PD-CD 5

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