The Datafile PD-CD 5

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

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / drawprint / !DrawPrint / DUAmodSWIs < prev next >

Wrap

Text File | 1995-01-28 | 26.9 KB | 673 lines

DUAmodSWIs: SWI calls for DrawUtilsA module V1.02 (21 Apr 95) ------------------------------------------------- Introduction ============ This module provides a number of SWI calls concerned with the pre-processing and display of DrawFiles. The module can render all of the object types currently used by Draw (including text area objects), and also sprite objects containing the new 'deep-colour' (32 thousand & 16 million colour) sprites introduced with RISC OS 3.5. The SWI calls are: Name Number ------------------- ------ DF_LastErrorA &4B0C0 DF_Verify &4B0C1 DF_ListUnknownFonts &4B0C2 DF_ChangeFont &4B0C3 DF_CompileFontTable &4B0C4 DF_SetBBoxes &4B0C5 DF_GetPageSize &4B0C6 DF_GetImageSize &4B0C7 DF_Render &4B0C8 The module should only be used with RISC OS version 3.1 or later. All SWI calls (except DF_LastErrorA) perform error checking on their entry parameters and on the DrawFile header (up to and including the image bounding box). DF_Verify provides a means of checking the structure of the DrawFile in detail; the other calls perform a lesser (sometimes minimal) degree of error checking, and it is recommended that the file be verified before using these calls. Error reporting =============== With the exception of DF_LastErrorA and (in part) DF_Verify, reporting of any error condition can be made in one of two ways depending on the setting of bit 0 of the control flags parameter passed in R0. If bit 0 of the control flags is set, then a standard os error block is returned and the error can be trapped (e.g.) in Basic with an ON ERROR statement. However, the error code value is always the same as the module base chunk number (&4B0C0) and the error text is always "DrawUtils(A) module error". To identify the error, DF_LastErrorA should be called immediately the error is returned (i.e. before any other calls to the module which would over-write the internal error status block). In Basic this could be implemented as: DEF PROCchange_font LOCAL fault% LOCAL ERROR : ON ERROR LOCAL fault% = TRUE IF NOT(fault%) THEN REM prepare for call SYS "DF_ChangeFont", 1, other parameters... REM no error, continue ELSE SYS "DF_LastErrorA" TO code%, tag%, pos%, offset% REM report error and/or REM take corrective action ENDIF RESTORE ERROR ENDPROC If bit 0 of the control flags is clear then details of the error are returned in R0 - R3 (code%, tag%, pos% and offset% respectively). In this case, if R0 = 0 on return it indicates that no error has occurred. The full error description can be obtained by recording R0 - R3 on return, or only R0 and then calling DF_LastErrorA. In Basic the latter method could be implemented as: DEF PROCchange_font REM prepare for call SYS "DF_ChangeFont", 0, other parameters... TO code%, other results IF code% = 0 THEN REM no error, continue ELSE SYS "DF_LastErrorA", TO code%, tag%, pos%, offset% REM (actually we already had code% before this call) REM report error and/or REM take corrective action ENDIF ENDPROC In both examples, code% is a non-zero error code (see list below), tag% is the tag type of the object causing the error (e.g. 1 = text object, 2 = path object), pos% is the position of the object in bytes from the start of the file, and offset% is the location of the error-causing sequence in bytes from the start of the object. In many cases, offset will be zero since the location of the error-causing sequence will be evident from the error code. DF_LastErrorA (SWI &4B0C0) =========================== 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_Verify (SWI &4B0C1) ======================= Purpose: verify a DrawFile. On entry: R0 = control flags R1 = pointer to buffer containing DrawFile (in user area, address > &8000) R2 = DrawFile size (bytes, must be correct) R3 = pointer to message block (in user area, address > &8000, minimum size 64 bytes) R4 = message block size (bytes) control flags: bit meaning when set ---- ---------------- 0 determines method of error reporting 1-31 reserved (should be zero) On exit: R0 = depends on method of error reporting R1 - R4 = preserved R5 = number of errors listed in message block R6 = -1 if whole file verified, else zero R7 = status flags (only if R6 = -1) If bit 0 of control flags = 0 then any error in the entry parameters or DrawFile header is reported in R0 - R3 (other registers are undefined); R0 = 0 means no error has occurred. status flags: bit meaning when set ---- ---------------- 0 other error (not unknown font) in DrawFile 1 unknown font(s) used 2 image and/or object bounding box(es) may be incorrect 3 options object present 4 deep colour sprites present Any error in the entry parameters or the DrawFile header is reported as described above. Otherwise, the file is scanned and a list of errors (if any) is built up in the message block. The format of the block is: block + 0 : error code (of first error) + 4 : tag " + 8 : position " + 12 : offset " block + 16 : error code (of second error) + 20 : tag " + 24 : position " + 28 : offset " The error code is non-zero (see list below). Tag is the tag type of the object containing the error. Position is its position in bytes from the start of the file. Offset is the location of the error-causing sequence in bytes from the start of the object; this is zero if the location of the error-causing sequence can be determined from the error code. Compilation of the error list continues until the whole file has been verified, or there is no room to list more errors in the message block, or a bad object size error is encountered at the top level (i.e. not inside a group or tagged object). Fonts listed in the font table but not used in any type of text object are ignored. Use of an unknown font in any type of text object is listed as an error in the message block. Only the first error encountered in an object is listed; scanning then proceeds to the next object (unless it was an unknown font usage error in which case it is listed in the message block and scanning continues within the object). Verification is terminated if a bad object size error is encountered at the top level (i.e. not inside a group object or tagged object) If an error is found in the header of a group object or tagged object then the object(s) contained within it are not examined. All objects contained within a group object are examined before proceeding to the object following the group object (therefore all objects are examined in the order in which they occur in the file). In the case of objects contained inside a group object, the first error encountered is reported and scanning proceeds to the next object (in the group) unless it was a bad object size error in which case scanning continues at the object after the group object. Status flags ------------ If no errors are found then bits 0 and 1 of status flags are clear. If only unknown font usage errors are found, then bit 1 of status flags is set. If any other type of error is found then bit 0 of status flags is set; in this case further processing or display of the file is not recommended. During verification, the module checks for invalid object bounding boxes (width or height <= 0) and, if found, issues a warning by setting bit 2 of status flags. The verification routine does not check that the bounding boxes are set correctly. An invalid bounding box is not reported as an error unless it applies to a (transformed) sprite object. In the case of text area objects, an error is also reported if all of the text column objects have invalid bounding boxes. If deep colour sprites (32 thousand or 16 million colour) are found then bit 4 of status flags is set. It is left to the software calling the module to determine if the host machine is capable of displaying these sprites. DF_ListUnknownFonts (SWI &4B0C2) ================================= Purpose: obtain a list of unknown fonts used in the DrawFile. On entry: R0 = control flags R1 = pointer to buffer containing DrawFile (in user area, address > &8000) R2 = DrawFile size (bytes, must be correct) R3 = pointer to message block (in user area, address > &8000, minimum size 64 bytes) R4 = message block size (bytes) control flags: bit meaning when set ---- ---------------- 0 determines method of error reporting 1-31 reserved (should be zero) On exit: R0 = depends on method of error reporting R1 - R4 = preserved R5 = number of fonts listed in message block R6 = -1 if whole file processed, else zero If bit 0 of control flags = 0 then any error is reported in R0 - R3 (other registers are undefined); R0 = 0 means no error has occurred. A list of unknown fonts is written into the message block. The structure of the block is: block + 0 : first font block + 40 : second font block + 80 : third font, etc. Each font name is terminated with a null character (zero byte). Compilation of the list continues until the whole file has been processed, or there is no room to list more fonts in the message block, or an error is found. With the exception of those relating to path objects and sprite objects, this call can return most of the errors recognized by DF_Verify. Each distinct font is listed once only irrespective of the number of times it is used in the DrawFile. Fonts listed in the font table but not used in any text objects are ignored. Unknown fonts used only in text area objects and not listed in the font table are returned. DF_ChangeFont (SWI &4B0C3) =========================== Purpose: replace one or more fonts in the DrawFile. On entry: R0 = control flags R1 = pointer to buffer containing DrawFile (in user area, address > &8000) R2 = DrawFile size (bytes, must be correct) R3 = pointer to block containing search list (in user area, address > &8000) R4 = pointer to block containing replace list (in user area, address > &8000) control flags: bit meaning when set ---- ---------------- 0 determines method of error reporting 1 return new size of DrawFile only (i.e. without altering file) 2-31 reserved (should be zero) On exit: R0 = depends on method of error reporting R1 - R4 = preserved R5 = new DrawFile size (bytes) If bit 0 of control flags = 0 then any error is reported in R0 - R3 (other registers are undefined); R0 = 0 means no error has occurred. On entry R3 points to a list of font names to search for and R4 points to a list of replacements. The structure of the blocks is: search_block + 0 : unknown font 1 search_block + 40 : unknown font 2 (may be others at 40 byte intervals) search_block + 80 : null string terminator replace_block + 0 : replacement font 1 (or null string) replace_block + 40 : replacement font 2 (or null string) (may be others at 40 byte intervals) Font names can be terminated with any control character (ASCII code < 32). The search list is terminated by a null string. For each font in the search list, the corresponding position in the replace list should contain either a replacement font or a null string if no substitution is to be performed for that particular font. The system font cannot appear in either list. Unknown fonts used only in text area objects and not listed in the font table are replaced. The module assumes that the buffer holding the DrawFile is large enough to accommodate any increase in file size that may result from this call. The list returned by DF_ListUnknownFonts can be used as the search list, but you must add the null string terminator. DF_CompileFontTable (SWI &4B0C4) ================================= Purpose: update the DrawFile font table. On entry: R0 = control flags R1 = pointer to buffer containing DrawFile (in user area, address > &8000) R2 = DrawFile size (bytes, must be correct) control flags: bit meaning when set ---- ---------------- 0 determines method of error reporting 1 return new size of DrawFile only (i.e. without altering file) 2-31 reserved (should be zero) On exit: R0 = depends on method of error reporting R1 - R4 = preserved R5 = new DrawFile size (bytes) If bit 0 of control flags = 0 then any error is reported in R0 - R3 (other registers are undefined); R0 = 0 means no error has occurred. This call may be useful whether or not font substitution has been performed using DF_ChangeFont. Fonts listed in the font table but not used in any text objects are removed. Fonts used only in text area objects and not listed in the font table are included (if there is no font table then one will be inserted). If a font table is present and there are no text objects of any type then the font table is deleted. This call will not cause duplication of any font in the font table, but neither will it remove such duplication if present originally. The module assumes that the buffer holding the DrawFile is large enough to accommodate any increase in file size that may result from this call. DF_SetBBoxes (SWI &4B0C5) ========================== Purpose: set object bounding boxes correctly. On entry: R0 = control flags R1 = pointer to buffer containing DrawFile (in user area, address > &8000) R2 = DrawFile size (bytes, must be correct) control flags: bit meaning when set ---- ---------------- 0 determines method of error reporting 1 update options object (if present) 2-31 reserved (should be zero) On exit: R0 = depends on method of error reporting R1 = image bounding box xmin (in Draw units) R2 = image bounding box ymin " R3 = image bounding box xmax " R4 = image bounding box ymax " R5 = page size code If bit 0 of control flags = 0 then any error is reported in R0 - R3 (other registers are undefined); R0 = 0 means no error has occurred. The bounding box for each text object and path object is calculated and written into the object header. The bounding box for each text area object is set according to its text column objects (except any with width or height <= 0). The bounding box for each group object and tagged object is set according to the objects contained within it. Unknown objects are ignored, as are sprite objects with an invalid bounding box. The image bounding box (in the DrawFile header) is set according to all objects with a valid bounding box in the file. If bit 1 of control flags is set, the smallest paper 'A' size required to hold the image is determined and used to update the options object (if one is present). The page size code returned in R5 is the paper 'A' size plus 1 multiplied by 256 plus 1 if landscape orientation is required (e.g. A4 portrait = &500, A4 landscape = &501, A5 portrait = &600, A5 landscape = &601). DF_GetPageSize (SWI &4B0C6) ============================ Purpose: obtain window and page size for image. On entry: R0 = control flags R1 = pointer to buffer containing DrawFile (in user area, address > &8000) R2 = DrawFile size (bytes, must be correct) R3 = unused R4 = unused R5 = zoom factor multiplied by 1000 (125 - 8000) control flags: bit meaning when set ---- ---------------- 0 determines method of error reporting 1 use image bounding box to determine window/page size (only applies if no options object is present) 2-31 reserved (should be zero) On exit: R0 = depends on method of error reporting R1 = preserved R2 = preserved R3 = window width (os units) R4 = window height (os units) R5 = page size code R6 = 1 if options object used, else zero If bit 0 of control flags = 0 then any error is reported in R0 - R3 (other registers are undefined); R0 = 0 means no error has occurred. This call returns the page size code for the image and the corresponding window size (in os units) for the specified zoom factor. The latter could be passed to Wimp_SetExtent to set the window size prior to displaying the image. Note that the window must have its origin at the bottom left. See DF_SetBBoxes for an explanation of the page size code. If an options object is present, the page size is determined from it and used to calculate the window size. In the absence of an options object, the page/window sizes are determined according to bit 1 of the control flags passed in R0. If the bit is clear, the bounding boxes of the top level objects (i.e. not those inside group objects or tagged objects) are used to define the image size (negative values are treated as zero). The smallest paper 'A' size required to contain the image is then determined and used to calculate the window size. If the bit is set, the page/window size is determined from the image bounding box in the DrawFile header. This means that (in the absence of an options object), the page size can be specified by setting the image bounding box coordinates slightly smaller than the page size. The module allows a zoom factor of one eighth to eight times actual size; multiplying by 1000 gives an allowable range of 125 - 8000 for the zoom parameter passed in R5. DF_GetImageSize (SWI &4B0C7) ============================= Purpose: obtain image size. On entry: R0 = control flags R1 = pointer to buffer containing DrawFile (in user area, address > &8000) R2 = DrawFile size (bytes, must be correct) control flags: bit meaning when set ---- ---------------- 0 determines method of error reporting 1 return values in millipoints, else in Draw units 2-31 reserved (should be zero) On exit: R0 = depends on method of error reporting R1 = image xmin R2 = image ymin R3 = image xmax R4 = image ymax If bit 0 of control flags = 0 then any error is reported in R0 - R3 (other registers are undefined); R0 = 0 means no error has occurred. This call examines the bounding boxes of the top-level objects (not those inside group objects or tagged objects) and returns the image size in Draw units or millipoints. Negative values may be returned. DF_Render (SWI &4B0C8) ======================= Purpose: display a DrawFile. On entry: R0 = control flags R1 = pointer to buffer containing DrawFile (in user area, address > &8000) R2 = DrawFile size (bytes, must be correct) R3 = unused R4 = unused R5 = zoom factor multiplied by 1000 (125 - 8000) R6 = pointer to Wimp redraw block control flags: bit meaning when set ---- ---------------- 0 determines method of error reporting 1-31 reserved (should be zero) On exit: R0 = depends on method of error reporting R1 - R6 = preserved If bit 0 of control flags = 0 then any error is reported in R0 - R3 (other registers are undefined); R0 = 0 means no error has occurred. On entry, R5 contains the zoom factor multiplied by 1000 (allowable range 125 - 8000) and R6 contains a pointer to a Wimp redraw block as returned by Wimp_RedrawWindow and Wimp_GetRectangle. The coordinates of the rectangle to be redrawn are compared with the object bounding boxes to determine which objects need to be rendered. The bounding boxes must therefore be set correctly. If the DrawFile is displayed in a Wimp window, the window must have its origin at the bottom left. Error codes =========== With the exception of error codes less than 100, most of these errors are only returned in the message block by DF_Verify. DF_ChangeFont can also return most errors except those relating to path objects and sprite objects. Entry parameter / general errors -------------------------------- 1. Invalid message block pointer (block must be in user workspace, address > &8000). 2. Message block is too small (minimum size is 64 bytes). 3. Invalid pointer to buffer containing DrawFile (must be in user workspace, address > &8000). 4. Invalid DrawFile size (must be at least 40 bytes and a multiple of 4). 5. Invalid zoom factor (allowable range is 125 - 8000 denoting one eighth to eight times normal size) 6. Invalid redraw block pointer (Wimp redraw block block must be in user workspace, address > &8000). 7. Unknown SWI (module recognizes SWI numbers &4B0C0 - &4B0C8). 8. Not used. 9. Module cannot obtain workspace in RMA. 10. Not used. 11. Invalid pointer to block containing font list (block must be in user workspace, address > &8000). May be returned by DF_ChangeFont. 12. Invalid font name in font list (too long or contains illegal characters). May be returned by DF_ChangeFont. 13. Font list contains system font. May be returned by DF_ChangeFont. 14. Font table full (fonts 1-255 are defined, cannot insert any more). May be returned by DF_CompileFontTable. DrawFile header / general errors -------------------------------- 31. Not a DrawFile (first word of file is incorrect). 32. Unknown DrawFile version (second word is not 201). 33. DrawFile is too small (less than 40 bytes). 34. Invalid DrawFile size (not a multiple of four bytes). 35. Image bounding box in DrawFile header is invalid (width or height <= 0). May be returned by DF_GetPageSize and DF_Render. 36. Invalid object size (too small or not a multiple of four bytes). Can be returned for any object. Font table errors ----------------- 101. Two or more font tables in DrawFile. 102. Font table appears after (transformed) text object. 103. Invalid font table termination (must only be null chars to word boundary). 104. Font number in font table is zero. 105. Invalid font name (too long or contains illegal characters). 106. Font name terminator is not null character. Text object errors ------------------ 201. Text object appears before font table. 202. Font number is < 0 or > 255. 203. Unknown font. 204. Font size too low (< 1 pt). 205. Invalid object termination (must only be null chars to word boundary). 206. Text contains illegal characters (control chars or ASCII 127). 207. Illegal font flags in transformed text object. 208. Font is not defined in font table. Path object errors ------------------ 301. Non-zero reserved bits in path style description. 302. Illegal number of elements in dash pattern definition. 303. Path object has no components. 304. Early path end. 305. Path does not start with a move. 306. Early path closure. 307. Unknown path component. Sprite object errors -------------------- 401. Invalid object bounding box (width or height <= 0). 402. Sprite size inconsistent with object size. 403. Invalid sprite dimensions (width or height <= 0). 404. Invalid sprite offset (< &2C). 405. Sprite defined in unknown mode. 406. Invalid sprite palette size. 407. Invalid mask offset (< &2C). 408. Image size inconsistent with sprite dimensions. 409. Mask size inconsistent with sprite dimensions. 410. Unknown sprite type (from top byte of mode entry). Text area object errors ----------------------- 501. Text column object: invalid size (must be 24 bytes). 502. Text column object: inverted bounding box (width or height < 0). 503. Invalid termination for text column objects. 504. Total area defined by text column objects invalid (width or height <= 0). 505. Non-zero reserved words in object header. 506. No text column objects. 507. Multiple initializer ('\!') sequences. 508. Invalid initializer (not '\! 1'). 509. Invalid termination for escape sequence (most require '/' or newline). Newline = ASCII 10. 510. Absent initializer. 511. Late '\D' sequence (must appear before text). 512. Multiple '\D' sequences. 513. Invalid '\D' sequence (value < 1 or syntax error). 514. Number of text column objects inconsistent with '\D' sequence. 515. '\F' sequence: illegal font number (< 0 or > 99) or syntax error. 516. '\F' sequence: unknown font. 517. '\F' sequence: invalid font size (< 1 pt) or syntax error. 518. '\A' sequence: invalid alignment code (not L, R, D or C). 519. '\M' sequence: illegal value or syntax error. 520. '\C' or '\B' sequence: illegal value or syntax error. 521. '\L' sequence: illegal value or syntax error. 522. '\P' sequence: illegal value or syntax error. 523. '\U' sequence: illegal value or syntax error. 524. '\V' sequence: illegal value or syntax error. 525. Font selection ('\n') sequence : illegal value or syntax error. 526. No font selected at start of text. 527. Illegal character in text (control char or ASCII 127). 528. Invalid text area termination (must be newline + null character(s) to word boundary). Newline = ASCII 10. 529. Font selection ('\n') sequence selects an undefined font. Options object errors --------------------- 601. Bounding box entries are non-zero. 602. Unrecognized page size. 603. Reserved bits are non-zero. 604. Invalid grid spacing (<= 0). 605. Invalid grid division (<= 0). 606. Zoom multiplier or divisor out of range (< 1 or > 8). Comments concerning this software to: James McQueen 9/2 15 Croftbank Street Springburn Glasgow G21 4LP