home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilsd / duamodule / DUAmodSWIs < prev   
Encoding:
Text File  |  1995-08-20  |  30.7 KB  |  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 flags is set. If
  206. any other type of error is found then bit 0 of status flags is set; in this
  207. case further processing or display of the file is not recommended.
  208.  
  209. During verification, the module checks for invalid object bounding boxes
  210. (width or height <= 0) and, if found, issues a warning by setting bit 2 of
  211. status flags. The verification routine does not check that the bounding
  212. boxes are set correctly. An invalid bounding box is not reported as an error
  213. unless it applies to a (transformed) sprite object. In the case of text area
  214. objects, an error is also reported if all of the text column objects have
  215. invalid bounding boxes.
  216.  
  217. If deep colour sprites (32 thousand or 16 million colour) are found then bit
  218. 4 of status flags is set. It is left to the software calling the module to
  219. determine if the host machine is capable of displaying these sprites.
  220.  
  221.  
  222.  
  223. DF_ListUnknownFonts  (SWI &4B0C2)
  224. =================================
  225.  
  226. Purpose: obtain a list of unknown fonts used in the drawfile.
  227.  
  228. On entry:   R0    = control flags
  229.             R1    = pointer to buffer containing drawfile 
  230.                     (in user area, address > &8000)
  231.             R2    = drawfile size (bytes, must be correct)
  232.             R3    = pointer to message block (in user area,
  233.                     address > &8000, minimum size 64 bytes)
  234.             R4    = message block size (bytes)
  235.  
  236.    control flags: bit   meaning when set
  237.                   ----  ----------------
  238.                    0    determines method of error reporting
  239.                   1-31  reserved (should be zero)
  240.  
  241. On exit:    R0    = depends on method of error reporting
  242.           R1 - R4 = preserved
  243.             R5    = number of fonts listed in message block
  244.             R6    = -1 if whole file processed, else zero
  245.  
  246.     If bit 0 of control flags = 0 then any error is reported
  247.     in R0 - R3 (other registers are undefined); R0 = 0 means
  248.     no error has occurred.
  249.  
  250. A list of unknown fonts is written into the message block. The structure of
  251. the block is:
  252.  
  253.     block +  0 : first font
  254.     block + 40 : second font
  255.     block + 80 : third font, etc.
  256.  
  257. Each font name is terminated with a null character (zero byte). Compilation
  258. of the list continues until the whole file has been processed, or there is
  259. no room to list more fonts in the message block, or an error is found. With
  260. the exception of those relating to path objects and sprite objects, this
  261. call can return most of the errors recognized by DF_Verify. Each distinct
  262. font is listed once only irrespective of the number of times it is used in
  263. the drawfile. Fonts listed in the font table but not used in any text
  264. objects are ignored. Unknown fonts used only in text area objects and not
  265. listed in the font table are returned.
  266.  
  267.  
  268.  
  269. DF_ChangeFont  (SWI &4B0C3)
  270. ===========================
  271.  
  272. Purpose: replace one or more fonts in the drawfile.
  273.  
  274. On entry:   R0    = control flags
  275.             R1    = pointer to buffer containing drawfile 
  276.                     (in user area, address > &8000)
  277.             R2    = drawfile size (bytes, must be correct)
  278.             R3    = pointer to block containing search list
  279.                     (in user area, address > &8000)
  280.             R4    = pointer to block containing replace list
  281.                     (in user area, address > &8000)
  282.  
  283.  
  284.    control flags: bit   meaning when set
  285.                   ----  ----------------
  286.                    0    determines method of error reporting
  287.                    1    return new size of drawfile only (i.e.
  288.                         without altering file)
  289.                   2-31  reserved (should be zero)
  290.  
  291. On exit:    R0    = depends on method of error reporting
  292.           R1 - R4 = preserved
  293.             R5    = new drawfile size (bytes)
  294.  
  295.     If bit 0 of control flags = 0 then any error is reported
  296.     in R0 - R3 (other registers are undefined); R0 = 0 means
  297.     no error has occurred.
  298.  
  299. On entry R3 points to a list of font names to search for and R4 points to a
  300. list of replacements. The structure of the blocks is:
  301.  
  302.     search_block +  0 : unknown font 1
  303.     search_block + 40 : unknown font 2
  304.     (may be others at 40 byte intervals)
  305.     search_block + 80 : null string terminator
  306.  
  307.     replace_block +  0 : replacement font 1 (or null string)
  308.     replace_block + 40 : replacement font 2 (or null string)
  309.     (may be others at 40 byte intervals)
  310.  
  311. Font names can be terminated with any control character (ASCII code < 32).
  312. The search list is terminated by a null string. For each font in the search
  313. list, the corresponding position in the replace list should contain either a
  314. replacement font or a null string if no substitution is to be performed for
  315. that particular font. The system font cannot appear in either list. Unknown
  316. fonts used only in text area objects and not listed in the font table are
  317. replaced. The module assumes that the buffer holding the drawfile is large
  318. enough to accommodate any increase in file size that may result from this
  319. call.
  320.  
  321. The list returned by DF_ListUnknownFonts can be used as the search list, but
  322. you must add the null string terminator.
  323.  
  324.  
  325.  
  326. DF_CompileFontTable  (SWI &4B0C4)
  327. =================================
  328.  
  329. Purpose: update the drawfile font table.
  330.  
  331. On entry:   R0    = control flags
  332.             R1    = pointer to buffer containing drawfile 
  333.                     (in user area, address > &8000)
  334.             R2    = drawfile size (bytes, must be correct)
  335.  
  336.    control flags: bit   meaning when set
  337.                   ----  ----------------
  338.                    0    determines method of error reporting
  339.                    1    return new size of drawfile only (i.e.
  340.                         without altering file)
  341.                   2-31  reserved (should be zero)
  342.  
  343. On exit:    R0    = depends on method of error reporting
  344.           R1 - R4 = preserved
  345.             R5    = new drawfile size (bytes)
  346.  
  347.     If bit 0 of control flags = 0 then any error is reported
  348.     in R0 - R3 (other registers are undefined); R0 = 0 means
  349.     no error has occurred.
  350.  
  351. This call may be useful whether or not font substitution has been performed
  352. using DF_ChangeFont. Fonts listed in the font table but not used in any text
  353. objects are removed. Fonts used only in text area objects and not listed in
  354. the font table are included (if there is no font table then one will be
  355. inserted). If a font table is present and there are no text objects of any
  356. type then the font table is deleted. This call will not cause duplication of
  357. any font in the font table, but neither will it remove such duplication if
  358. present originally. The module assumes that the buffer holding the drawfile
  359. is large enough to accommodate any increase in file size that may result
  360. from this call.
  361.  
  362.  
  363.  
  364. DF_SetBBoxes  (SWI &4B0C5)
  365. ==========================
  366.  
  367. Purpose: set object bounding boxes correctly.
  368.  
  369. On entry:   R0    = control flags
  370.             R1    = pointer to buffer containing drawfile 
  371.                     (in user area, address > &8000)
  372.             R2    = drawfile size (bytes, must be correct)
  373.  
  374.    control flags: bit   meaning when set
  375.                   ----  ----------------
  376.                    0    determines method of error reporting
  377.                    1    update options object (if present)
  378.                   2-31  reserved (should be zero)
  379.  
  380. On exit:    R0    = depends on method of error reporting
  381.             R1    = image bounding box xmin (in Draw units)
  382.             R2    = image bounding box ymin       "
  383.             R3    = image bounding box xmax       "
  384.             R4    = image bounding box ymax       "
  385.             R5    = page size code
  386.  
  387.     If bit 0 of control flags = 0 then any error is reported
  388.     in R0 - R3 (other registers are undefined); R0 = 0 means
  389.     no error has occurred.
  390.  
  391. The bounding box for each text object and path object is calculated and
  392. written into the object header. The bounding box for each text area object
  393. is set according to its text column objects (except any with width or height
  394. <= 0). The bounding box for each group object and tagged object is set
  395. according to the objects contained within it. Unknown objects are ignored,
  396. as are sprite objects with an invalid bounding box. The image bounding box
  397. (in the drawfile header) is set according to all objects with a valid
  398. bounding box in the file. If bit 1 of control flags is set, the smallest
  399. paper 'A' size required to hold the image is determined and used to update
  400. the options object (if one is present).
  401.  
  402. The page size code returned in R5 is the paper 'A' size plus 1 multiplied by
  403. 256 plus 1 if landscape orientation is required (e.g. A4 portrait = &500, A4
  404. landscape = &501, A5 portrait = &600, A5 landscape = &601).
  405.  
  406.  
  407.  
  408. DF_GetPageSize  (SWI &4B0C6)
  409. ============================
  410.  
  411. Purpose: obtain window and page size for image.
  412.  
  413. On entry:   R0    = control flags
  414.             R1    = pointer to buffer containing drawfile 
  415.                     (in user area, address > &8000)
  416.             R2    = drawfile size (bytes, must be correct)
  417.             R3    = unused
  418.             R4    = unused
  419.             R5    = zoom factor multiplied by 1000 (125 - 8000)
  420.  
  421.    control flags: bit   meaning when set
  422.                   ----  ----------------
  423.                    0    determines method of error reporting
  424.                    1    use image bounding box to determine window/page size
  425.                         (only applies if no options object is present)
  426.                   2-31  reserved (should be zero)
  427.  
  428. On exit:    R0    = depends on method of error reporting
  429.             R1    = preserved
  430.             R2    = preserved
  431.             R3    = window width (os units)
  432.             R4    = window height (os units)
  433.             R5    = page size code
  434.             R6    = 1 if options object used, else zero
  435.  
  436.     If bit 0 of control flags = 0 then any error is reported
  437.     in R0 - R3 (other registers are undefined); R0 = 0 means
  438.     no error has occurred.
  439.  
  440. This call returns the page size code for the image and the corresponding
  441. window size (in os units) for the specified zoom factor. The latter could be
  442. passed to Wimp_SetExtent to set the window size prior to displaying the
  443. image.
  444.  
  445. Note that this call is only applicable to 'simple mode' rendering (see
  446. description of DF_Render). For 'transform' mode rendering, the image
  447. bounding box should be obtained with DF_GetImageSize and transformed as
  448. appropriate to determine the required window size.
  449.  
  450. See DF_SetBBoxes for an explanation of the page size code.
  451.  
  452. If an options object is present, the page size is determined from it and
  453. used to calculate the window size.
  454.  
  455. In the absence of an options object, the page/window sizes are determined
  456. according to bit 1 of the control flags passed in R0. If the bit is clear,
  457. the bounding boxes of the top level objects (i.e. not those inside group
  458. objects or tagged objects) are used to define the image size (negative
  459. values are treated as zero). The smallest paper 'A' size required to contain
  460. the image is then determined and used to calculate the window size. If the
  461. bit is set, the page/window size is determined from the image bounding box
  462. in the drawfile header. This means that (in the absence of an options
  463. object), the page size can be specified by setting the image bounding box
  464. coordinates slightly smaller than the page size.
  465.  
  466. The module allows a zoom factor of one eighth to eight times actual size;
  467. multiplying by 1000 gives an allowable range of 125 - 8000 for the zoom
  468. parameter passed in R5.
  469.  
  470.  
  471.  
  472. DF_GetImageSize  (SWI &4B0C7)
  473. =============================
  474.  
  475. Purpose: obtain image size.
  476.  
  477. On entry:   R0    = control flags
  478.             R1    = pointer to buffer containing drawfile 
  479.                     (in user area, address > &8000)
  480.             R2    = drawfile size (bytes, must be correct)
  481.  
  482.    control flags: bit   meaning when set
  483.                   ----  ----------------
  484.                    0    determines method of error reporting
  485.                    1    return values in millipoints, else in
  486.                         Draw units
  487.                   2-31  reserved (should be zero)
  488.  
  489. On exit:    R0    = depends on method of error reporting
  490.             R1    = image xmin
  491.             R2    = image ymin
  492.             R3    = image xmax
  493.             R4    = image ymax
  494.  
  495.     If bit 0 of control flags = 0 then any error is reported
  496.     in R0 - R3 (other registers are undefined); R0 = 0 means
  497.     no error has occurred.
  498.  
  499. This call examines the bounding boxes of the top-level objects (not those
  500. inside group objects or tagged objects) and returns the image size in Draw
  501. units or millipoints. Negative values may be returned.
  502.  
  503.  
  504.  
  505. DF_Render  (SWI &4B0C8)
  506. =======================
  507.  
  508. Purpose: display a drawfile.
  509.  
  510. This swi can operate in 'simple' mode (bit 1 of R0 clear) or 'transform'
  511. mode (bit 1 of R0 set):
  512.  
  513. Simple mode does not allow independent horizontal and vertical scaling or
  514. rotation of the image. It is intended for use where a single drawfile is
  515. displayed in a window rather than as part of a larger document. Because the
  516. transformation calculations are omitted this mode is slightly faster than
  517. transform mode. In this mode the window should have its work area origin
  518. (co-ordinate 0,0) at the bottom left corner.
  519.  
  520. Transform mode allows separate horizontal and vertical scaling and rotation
  521. of the image and positioning of the drawfile anywhere within a user-defined
  522. work area co-ordinate system. Thus the drawfile can be displayed as part of
  523. a larger document.
  524.  
  525. DF_Render (Simple mode)
  526. -----------------------
  527. On entry:   R0    = control flags
  528.             R1    = pointer to buffer containing drawfile 
  529.             R2    = drawfile size (bytes, must be correct)
  530.             R3    = unused
  531.             R4    = unused
  532.             R5    = zoom factor multiplied by 1000
  533.                       (allowable range 125 - 8000)
  534.             R6    = pointer to Wimp redraw block
  535.  
  536. R1 and R6 must point to locations in the user area (address >= &8000).
  537.  
  538.    control flags: bit   meaning when set
  539.                   ----  ----------------
  540.                    0    determines method of error reporting
  541.                    1    must be clear for 'simple' rendering 
  542.                   2-31  reserved (should be zero)
  543.  
  544. On exit:    R0    = depends on method of error reporting
  545.           R1 - R6 = preserved
  546.  
  547.     If bit 0 of control flags = 0 then any error is reported
  548.     in R0 - R3 (other registers are undefined); R0 = 0 means
  549.     no error has occurred.
  550.  
  551. On entry, R5 contains the zoom factor multiplied by 1000 (allowable range
  552. 125 - 8000) and R6 contains a pointer to a Wimp redraw block as returned by
  553. Wimp_RedrawWindow and Wimp_GetRectangle. The coordinates of the rectangle to
  554. be redrawn (four entries starting at redraw_block+28) are compared with the
  555. object bounding boxes (after scaling) to determine which objects need to be
  556. rendered. The bounding boxes must therefore be set correctly. If the
  557. drawfile is displayed in a Wimp window, the window must have its work area
  558. origin (co-ordinate 0,0) at the bottom left corner.
  559.  
  560. The module calculates the screen position of the drawfile origin as
  561.   screen_x0 = (redraw_block+4) - (redraw_block+20)
  562.   screen_y0 = (redraw_block+16) - (redraw_block+24)
  563.  
  564.  
  565. DF_Render (Transform mode)
  566. --------------------------
  567. On entry:   R0    = control flags
  568.             R1    = pointer to buffer containing drawfile 
  569.             R2    = drawfile size (bytes, must be correct)
  570.             R3    = unused
  571.             R4    = unused
  572.             R5    = pointer to transformation matrix
  573.             R6    = pointer to Wimp redraw block
  574.             R7    = flatness value for path object rendering
  575.                     (only used if bit 2 of control flags is set)
  576.  
  577. R1, R5 and R6 must point to locations in the user area (address >= &8000).
  578.  
  579.    control flags: bit   meaning when set
  580.                   ----  ----------------
  581.                    0    determines method of error reporting
  582.                    1    must be set for 'transform' rendering 
  583.                    2    use flatness value in R7
  584.                   3-31  reserved (should be zero)
  585.  
  586. On exit:    as for 'simple' mode.
  587.  
  588.  
  589. The transformation matrix is a 24 byte block with the format
  590.  
  591.   block +  0 = xscale *  COS(angle) * 65536
  592.   block +  4 = xscale *  SIN(angle) * 65536
  593.   block +  8 = yscale * -SIN(angle) * 65536
  594.   block + 12 = yscale *  COS(angle) * 65536
  595.   block + 16 = x_position
  596.   block + 20 = y_position
  597.  
  598. where xscale and yscale are the horizontal and vertical scale factors (which
  599. are effectively applied before rotation), angle defines rotation of the
  600. image, and x_position and y_position specify the location of the drawfile
  601. origin within the window in work area co-ordinates. The scale factors can be
  602. zero or negative; no lower or upper limit is imposed. Any co-ordinate system
  603. can be used for the window work area; e.g. to align the drawfile origin with
  604. the bottom left corner of the work area use block+16 = work_area_xmin and
  605. block+20 = work_area_ymin.
  606.  
  607. The Wimp redraw block is that returned by Wimp_RedrawWindow and
  608. Wimp_GetRectangle.
  609.  
  610. The flatness value in R7 is only used if bit 2 of the control flags
  611. parameter is set. Otherwise the module calculates a suitable flatness value
  612. from the scale factors defined in the transformation matrix.
  613.  
  614. The module calculates the screen position of the drawfile origin as
  615.   screen_x0 = x_position - (redraw_block+20) + (redraw_block+4)
  616.   screen_y0 = y_position - (redraw_block+24) + (redraw_block+16)
  617.  
  618. After scaling and rotation, the drawfile object bounding boxes are compared
  619. with the graphics clip-rectangle (four entries starting at redraw_block+28)
  620. to determine which objects need to be rendered. The bounding boxes must
  621. therefore be set correctly.
  622.  
  623.  
  624. Error codes
  625. ===========
  626. With the exception of error codes less than 100, most of these errors are
  627. only returned in the message block by DF_Verify. DF_ChangeFont can also
  628. return most errors except those relating to path objects and sprite objects.
  629.  
  630. Entry parameter / general errors
  631. --------------------------------
  632.   1. Invalid message block pointer (block must be in user workspace,
  633.      address > &8000).
  634.   2. Message block is too small (minimum size is 64 bytes).
  635.   3. Invalid pointer to buffer containing drawfile (must be in user
  636.      workspace, address > &8000).
  637.   4. Invalid drawfile size (must be at least 40 bytes and a multiple of 4).
  638.   5. Invalid zoom factor (allowable range is 125 - 8000 denoting one eighth
  639.      to eight times normal size)
  640.   6. Invalid redraw block pointer (Wimp redraw block block must be in user
  641.      workspace, address > &8000).
  642.   7. Unknown SWI (module recognizes SWI numbers &4B0C0 - &4B0C8).
  643.   8. Not used.
  644.   9. Module cannot obtain workspace in RMA.
  645.  10. Not used.
  646.  11. Invalid pointer to block containing font list (block must be in user
  647.      workspace, address > &8000). May be returned by DF_ChangeFont.
  648.  12. Invalid font name in font list (too long or contains illegal
  649.      characters). May be returned by DF_ChangeFont.
  650.  13. Font list contains system font. May be returned by DF_ChangeFont.
  651.  14. Font table full (fonts 1-255 are defined, cannot insert any more). May
  652.      be returned by DF_CompileFontTable.
  653.  
  654. Drawfile header / general errors
  655. --------------------------------
  656.  31. Not a drawfile (first word of file is incorrect).
  657.  32. Unknown drawfile version (second word is not 201).
  658.  33. Drawfile is too small (less than 40 bytes).
  659.  34. Invalid drawfile size (not a multiple of four bytes).
  660.  35. Image bounding box in drawfile header is invalid (width or height
  661.      <= 0). May be returned by DF_GetPageSize and DF_Render.
  662.  36. Invalid object size (too small or not a multiple of four bytes).
  663.      Can be returned for any object.
  664.  
  665. Font table errors
  666. -----------------
  667. 101. Two or more font tables in drawfile.
  668. 102. Font table appears after (transformed) text object.
  669. 103. Invalid font table termination (must only be null chars to word
  670.      boundary).
  671. 104. Font number in font table is zero.
  672. 105. Invalid font name (too long or contains illegal characters).
  673. 106. Font name terminator is not null character.
  674.  
  675. Text object errors
  676. ------------------
  677. 201. Text object appears before font table.
  678. 202. Font number is < 0 or > 255.
  679. 203. Unknown font.
  680. 204. Font size too low (< 1 pt).
  681. 205. Invalid object termination (must only be null chars to word boundary).
  682. 206. Text contains illegal characters (control chars or ASCII 127).
  683. 207. Illegal font flags in transformed text object.
  684. 208. Font is not defined in font table.
  685.  
  686. Path object errors
  687. ------------------
  688. 301. Non-zero reserved bits in path style description.
  689. 302. Illegal number of elements in dash pattern definition.
  690. 303. Path object has no components.
  691. 304. Early path end.
  692. 305. Path does not start with a move.
  693. 306. Early path closure.
  694. 307. Unknown path component.
  695.  
  696. Sprite object errors
  697. --------------------
  698. 401. Invalid object bounding box (width or height <= 0).
  699. 402. Sprite size inconsistent with object size.
  700. 403. Invalid sprite dimensions (width or height <= 0).
  701. 404. Invalid sprite offset (< &2C).
  702. 405. Sprite defined in unknown mode.
  703. 406. Invalid sprite palette size.
  704. 407. Invalid mask offset (< &2C).
  705. 408. Image size inconsistent with sprite dimensions.
  706. 409. Mask size inconsistent with sprite dimensions.
  707. 410. Unknown sprite type (from top byte of mode entry).
  708.  
  709. Text area object errors
  710. -----------------------
  711. 501. Text column object: invalid size (must be 24 bytes).
  712. 502. Text column object: inverted bounding box (width or height < 0).
  713. 503. Invalid termination for text column objects.
  714. 504. Total area defined by text column objects invalid (width or 
  715.      height <= 0).
  716. 505. Non-zero reserved words in object header.
  717. 506. No text column objects.
  718. 507. Multiple initializer ('\!') sequences.
  719. 508. Invalid initializer (not '\! 1').
  720. 509. Invalid termination for escape sequence (most require '/' or newline).
  721.      Newline = ASCII 10.
  722. 510. Absent initializer.
  723. 511. Late '\D' sequence (must appear before text).
  724. 512. Multiple '\D' sequences.
  725. 513. Invalid '\D' sequence (value < 1 or syntax error).
  726. 514. Number of text column objects inconsistent with '\D' sequence.
  727. 515. '\F' sequence: illegal font number (< 0 or > 99) or syntax error.
  728. 516. '\F' sequence: unknown font.
  729. 517. '\F' sequence: invalid font size (< 1 pt) or syntax error.
  730. 518. '\A' sequence: invalid alignment code (not L, R, D or C).
  731. 519. '\M' sequence: illegal value or syntax error.
  732. 520. '\C' or '\B' sequence: illegal value or syntax error.
  733. 521. '\L' sequence: illegal value or syntax error.
  734. 522. '\P' sequence: illegal value or syntax error.
  735. 523. '\U' sequence: illegal value or syntax error.
  736. 524. '\V' sequence: illegal value or syntax error.
  737. 525. Font selection ('\n') sequence : illegal value or syntax error.
  738. 526. No font selected at start of text.
  739. 527. Illegal character in text (control char or ASCII 127).
  740. 528. Invalid text area termination (must be newline + null character(s) to
  741.      word boundary). Newline = ASCII 10.
  742. 529. Font selection ('\n') sequence selects an undefined font.
  743.  
  744. Options object errors
  745. ---------------------
  746. 601. Bounding box entries are non-zero.
  747. 602. Unrecognized page size.
  748. 603. Reserved bits are non-zero.
  749. 604. Invalid grid spacing (<= 0).
  750. 605. Invalid grid division (<= 0).
  751. 606. Zoom multiplier or divisor out of range (< 1 or > 8).
  752.  
  753.  
  754.  
  755.  
  756. Comments concerning this software to:
  757.     James McQueen
  758.     9/2 15 Croftbank Street
  759.     Springburn
  760.     Glasgow
  761.     G21 4LP
  762.