home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilsd / duamodule / DUAmodSWIs < prev   
Text File  |  1995-08-20  |  31KB  |  762 lines
  1.  
  2. DUAmodSWIs:
  3.   SWI calls for DrawUtilsA module V1.10 (21 Aug 95)
  4.   -------------------------------------------------
  5.  
  6. Introduction
  7. ============
  8. This module provides a number of SWI calls concerned with the pre-processing
  9. and display of drawfiles. The module can render all of the object types
  10. currently used by Draw (including text area objects), and also sprite
  11. objects containing the new 'deep-colour' (32 thousand & 16 million colour)
  12. sprites introduced with RISC OS 3.5.
  13.  
  14. The SWI calls are:
  15.    Name                  Number
  16.    -------------------   ------
  17.    DF_LastErrorA         &4B0C0
  18.    DF_Verify             &4B0C1
  19.    DF_ListUnknownFonts   &4B0C2
  20.    DF_ChangeFont         &4B0C3
  21.    DF_CompileFontTable   &4B0C4
  22.    DF_SetBBoxes          &4B0C5
  23.    DF_GetPageSize        &4B0C6
  24.    DF_GetImageSize       &4B0C7
  25.    DF_Render             &4B0C8
  26.  
  27. The module should only be used with RISC OS version 3.1 or later.
  28.  
  29. All SWI calls (except DF_LastErrorA) perform error checking on their entry
  30. parameters and on the drawfile header (up to and including the image
  31. bounding box). DF_Verify provides a means of checking the structure of the
  32. drawfile in detail; the other calls perform a lesser (sometimes minimal)
  33. degree of error checking, and it is recommended that the file be verified
  34. before using these calls. 
  35.  
  36.  
  37. Error reporting
  38. ===============
  39. With the exception of DF_LastErrorA and (in part) DF_Verify, reporting of
  40. any error condition can be made in one of two ways depending on the setting
  41. of bit 0 of the control flags parameter passed in R0.
  42.  
  43. If bit 0 of the control flags is set, then a standard os error block is
  44. returned and the error can be trapped (e.g.) in Basic with an ON ERROR
  45. statement. However, the error code value is always the same as the module
  46. base chunk number (&4B0C0) and the error text is always "DrawUtils(A) module
  47. error". To identify the error, DF_LastErrorA should be called immediately
  48. the error is returned (i.e. before any other calls to the module which would
  49. over-write the internal error status block). In Basic this could be
  50. implemented as:
  51.  
  52.     DEF PROCchange_font
  53.       LOCAL fault%
  54.       LOCAL ERROR : ON ERROR LOCAL fault% = TRUE
  55.       IF NOT(fault%) THEN
  56.         REM prepare for call
  57.         SYS "DF_ChangeFont", 1, other parameters...
  58.         REM no error, continue
  59.       ELSE
  60.         SYS "DF_LastErrorA" TO code%, tag%, pos%, offset%
  61.         REM report error and/or
  62.         REM take corrective action
  63.       ENDIF
  64.       RESTORE ERROR
  65.     ENDPROC
  66.  
  67. If bit 0 of the control flags is clear then details of the error are
  68. returned in R0 - R3 (code%, tag%, pos% and offset% respectively). In this
  69. case, if R0 = 0 on return it indicates that no error has occurred. The full
  70. error description can be obtained by recording R0 - R3 on return, or only R0
  71. and then calling DF_LastErrorA. In Basic the latter method could be
  72. implemented as:
  73.  
  74.     DEF PROCchange_font
  75.       REM prepare for call
  76.       SYS "DF_ChangeFont", 0, other parameters... TO code%, other results
  77.       IF code% = 0 THEN
  78.         REM no error, continue
  79.       ELSE
  80.         SYS "DF_LastErrorA", TO code%, tag%, pos%, offset%
  81.         REM (actually we already had code% before this call)
  82.         REM report error and/or
  83.         REM take corrective action
  84.       ENDIF
  85.     ENDPROC
  86.  
  87. In both examples, code% is a non-zero error code (see list below), tag% is
  88. the tag type of the object causing the error (e.g. 1 = text object, 2 = path
  89. object), pos% is the position of the object in bytes from the start of the
  90. file, and offset% is the location of the error-causing sequence in bytes
  91. from the start of the object. In many cases, offset will be zero since the
  92. location of the error-causing sequence will be evident from the error code.
  93.  
  94.  
  95.  
  96. DF_LastErrorA  (SWI &4B0C0)
  97. ===========================
  98.  
  99. Purpose: return contents of module error status block.
  100.  
  101. On entry:   registers unused
  102.  
  103. On exit:    R0    = error code
  104.             R1    = tag of type of object containing error
  105.             R2    = position of object
  106.             R3    = offset to error sequence
  107.  
  108. This call returns details of the last error to occur for any of the other
  109. module SWI calls; see the explanation of error reporting above for details.
  110. If there was no error then R0 = 0 and the other registers are undefined.
  111.  
  112.  
  113.  
  114. DF_Verify  (SWI &4B0C1)
  115. =======================
  116.  
  117. Purpose: verify a drawfile.
  118.  
  119. On entry:   R0    = control flags
  120.             R1    = pointer to buffer containing drawfile 
  121.                     (in user area, address > &8000)
  122.             R2    = drawfile size (bytes, must be correct)
  123.             R3    = pointer to message block (in user area,
  124.                     address > &8000, minimum size 64 bytes)
  125.             R4    = message block size (bytes)
  126.  
  127.    control flags: bit   meaning when set
  128.                   ----  ----------------
  129.                    0    determines method of error reporting
  130.                   1-31  reserved (should be zero)
  131.  
  132. On exit:    R0    = depends on method of error reporting
  133.           R1 - R4 = preserved
  134.             R5    = number of errors listed in message block
  135.             R6    = -1 if whole file verified, else zero
  136.             R7    = status flags (only if R6 = -1)
  137.  
  138.     If bit 0 of control flags = 0 then any error in the
  139.     entry parameters or drawfile header is reported in
  140.     R0 - R3 (other registers are undefined); R0 = 0 means
  141.     no error has occurred.
  142.  
  143.     status flags: bit   meaning when set
  144.                   ----  ----------------
  145.                    0    other error (not unknown font) in drawfile
  146.                    1    unknown font(s) used
  147.                    2    image and/or object bounding box(es) may
  148.                         be incorrect
  149.                    3    options object present
  150.                    4    deep colour sprites present
  151.  
  152. Any error in the entry parameters or the drawfile header is reported as
  153. described above. Otherwise, the file is scanned and a list of errors (if
  154. any) is built up in the message block. The format of the block is:
  155.  
  156.     block +  0 : error code (of first error)
  157.           +  4 : tag               "
  158.           +  8 : position          "
  159.           + 12 : offset            "
  160.  
  161.     block + 16 : error code (of second error)
  162.           + 20 : tag               "
  163.           + 24 : position          "
  164.           + 28 : offset            "
  165.  
  166. The error code is non-zero (see list below). Tag is the tag type of the
  167. object containing the error. Position is its position in bytes from the
  168. start of the file. Offset is the location of the error-causing sequence in
  169. bytes from the start of the object; this is zero if the location of the
  170. error-causing sequence can be determined from the error code.
  171.  
  172. Compilation of the error list continues until the whole file has been
  173. verified, or there is no room to list more errors in the message block, or a
  174. bad object size error is encountered at the top level (i.e. not inside a
  175. group or tagged object). 
  176.  
  177. Fonts listed in the font table but not used in any type of text object are
  178. ignored.
  179.  
  180. Use of an unknown font in any type of text object is listed as an error in
  181. the message block.
  182.  
  183. Only the first error encountered in an object is listed; scanning then
  184. proceeds to the next object (unless it was an unknown font usage error in
  185. which case it is listed in the message block and scanning continues within
  186. the object). Verification is terminated if a bad object size error is
  187. encountered at the top level (i.e. not inside a group object or tagged
  188. object)
  189.  
  190. If an error is found in the header of a group object or tagged object then
  191. the object(s) contained within it are not examined.
  192.  
  193. All objects contained within a group object are examined before proceeding
  194. to the object following the group object (therefore all objects are examined
  195. in the order in which they occur in the file).
  196.  
  197. In the case of objects contained inside a group object, the first error
  198. encountered is reported and scanning proceeds to the next object (in the
  199. group) unless it was a bad object size error in which case scanning
  200. continues at the object after the group object.
  201.  
  202. Status flags
  203. ------------
  204. If no errors are found then bits 0 and 1 of status flags are clear. If only
  205. unknown font usage errors are found, then bit 1 of status