home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilst / zap / !Zap / Docs / Redraw < prev   
Text File  |  1995-03-30  |  38KB  |  870 lines
  1. *************************************************************************
  2. * >Redraw - Documentation for the ZapRedraw module v0.22        *
  3. *************************************************************************
  4.  
  5. Summary:
  6. --------
  7.  
  8. The module ZapRedraw provides the "ZapRedraw_" SWI's which are capable of
  9. drawing a rectangle of text characters on screen. It offers the following
  10. features:
  11.  
  12. * Redraw may be by direct screen access (henceforth DSA) where the
  13.   data is poked into the screen memory or by the standard VDU redraw.
  14.   
  15. * Full colour provided (with your own definable palette). Supports up to 32
  16.   bits per pixel in DSA mode and 24 bit colour in VDU mode.
  17.  
  18. * DSA redraw can handle any size of bitmap characters. Special optimised
  19.   code is provided for 8 pixel wide characters in all modes.
  20.   Also 8*8 and 8*16 character sizes are given priority.
  21.   Up to 65536 characters can be defined.
  22.   
  23. * VDU redraw mode can handle any font and font size.
  24.  
  25. * Support is provided for cursors.
  26.  
  27. * Many extra SWIs perform all the work of creating cached bitmaps, updating
  28.   them on a mode change etc. Swi's are also provided for creating palettes
  29.   and other functions related to the redraw.
  30.  
  31. * An example program is provided which can be used as a template.
  32.   
  33. Limitations:
  34.  
  35. * All characters are equally spaced. Proportional spacing is not supported.
  36.  
  37. Copyright:
  38. ----------
  39.  
  40. The ZapRedraw module is copyright Dominic Symes 1994. Please contact me if
  41. you wish to use it in a program other than Zap. See the Zap Copyright file
  42. for my address.
  43.  
  44. Definitions required for the SWI's
  45. ==================================
  46.  
  47. ZapRedraw chunk prefix: ZapRedraw
  48. ZapRedraw chunk number: &48480
  49.  
  50. All SWI numbers below are given as offsets from the chunk number.
  51.  
  52. 'DSA' means direct screen access mode (characters poked into the screen).
  53. 'VDU' means VDU mode (operating system called to draw characters).
  54.  
  55. Pixel co-ordinates are used wherever possible to prevent rounding errors when
  56. OS co-ordinates are not pixel aligned (these errors DO mess things up!).
  57. Pixel co-ordinates are from the top left of the screen with the y axis
  58. descending. By a 'pixel' I mean a hardware pixel (this differs from an OS
  59. pixel in double-pixel emulation modes - this only crops up in the RISC OS 2
  60. MODE 2 wimp!).
  61.  
  62. Zap redraw block:
  63. -----------------
  64.  
  65. For several SWI's, R1 points to a redraw block of the type described below.
  66. The SWI documentation will mention which data in the block is actually used
  67. by that SWI (so should be filled in). Each offset in the block is named with
  68. a name beginning 'r_'. The Basic program E-Library contains a procedure to
  69. set these variables up should you be using the Basic assembler. The contents
  70. of some offsets depends on which redraw mode is being used (VDU or DSA), this
  71. is indicated by 'VDU:' and 'DSA:'.
  72.  
  73. Offset    Name        Function
  74.  
  75. &00    r_flags        Flags word determining the type of redraw:
  76.             b0 Clear for DSA mode. Set for VDU redraw mode.
  77.             b1 Set for 'double height mode'. Only valid in DSA
  78.                mode. Draws each raster twice so actual character
  79.                height is 2*r_charh and spacing 2*r_linesp.
  80.             b2 Extension routine provided.
  81.                Only valid in DSA mode. See ZapRedraw_RedrawArea.
  82.             b3-31 Reserved - set to zero.
  83. &04    r_minx        Min x of redraw (pixels from lhs - inclusive)
  84. &08    r_miny        Min y of redraw (pixels from top - inclusive)
  85. &0C    r_maxx        Max x of redraw (pixels form lhs - exclusive)
  86. &10    r_maxy        Max y of redraw (pixels from top - exclusive)
  87. &14    r_screen    DSA: Address of screen to write to or 0 to read the
  88.                  current screen address.
  89.             VDU: ignored
  90. &18    r_bpl        DSA: Bytes per raster line of the screen
  91.             VDU: ignored
  92. &1C    r_bpp        Log base 2 of number of bits per pixel
  93.             (ie 0=2 cols 1=4 cols 2=16 cols 3=256 cols
  94.             4=65536 cols 5=2^32 cols).
  95. &20    r_charw        Width of a character in pixels
  96. &24    r_charh        Height of a character in pixels
  97. &28    r_caddr        DSA: Address of character cache (format below)
  98.             VDU: Pointer to font name or 0 for system font
  99. &2C    r_cbpl        DSA: Number of bytes per cached character line.
  100.             VDU: x os offset of where to print the font char
  101.                  in the character 'box'. (eg 0 for system font)
  102. &30    r_cbpc        DSA: Number of bytes per cached character.
  103.             VDU: y os offset of where to print the font char
  104.                  in the character 'box'. (eg char height-1 for
  105.                  system font as VDU5 plots char downwards).
  106. &34    r_linesp    Line spacing in pixels.
  107. &38    r_data        Address of data (rectangle of characters) to print
  108.             on the screen (format below).
  109. &3C    r_scrollx    Horizontal scroll offset in rectangle of characters
  110.             given in r_data of top left of redraw rectangle.
  111.             This is in pixels from the lhs of the characters.
  112.             Thus it equals n*r_charw+m where n is the number of
  113.             characters in and m is the number of pixels into
  114.             the n'th character.
  115. &40    r_scrolly    Vertical scroll offset in rectangle of characters
  116.             given in r_data of top left of redraw rectangle.
  117.             This is in pixels from the top of the characters.
  118.             Note that in single height mode each line is
  119.             r_charh+r_linesp pixels high and in double height
  120.             mode each line is 2*(r_charh+r_linesp) pixels high.
  121. &44    r_palette    Address of palette to be used for colour translation.
  122.             (see below).
  123. &48    r_for        Foreground colour to use at the start of a line as an
  124.             offset in the palette table.
  125. &4C    r_bac        Background colour to use at the start of a line as
  126.             an offset in the palette table.
  127. &50    r_workarea    Pointer to an area of workspace for the SWI to use.
  128.             The size of this workspace depends on the SWI.
  129.             (It must be word aligned).
  130. &54    r_magx        Log base 2 of number of x os co-ords per pixel.
  131. &58    r_magy      Log base 2 of number of y os co-ords per pixel.
  132. &5C    r_xsize        Width of screen in pixels.
  133. &60    r_ysize        Height of screen in pixels.
  134. &64    r_mode        Current screen mode.
  135.  
  136. Character cache format (r_caddr):
  137. ---------------------------------
  138.  
  139. When using VDU redraw, this should point to the name of the font to use, or
  140. be zero for the system font.
  141.  
  142. When using direct screen access, the module will expect this block to contain
  143. the bitmaps for all the characters it is asked to print. Each character has
  144. size r_cbpc so it will expect to find the bitmap for ascii character 'n' at
  145. address char_start=(!r_caddr)+n*r_cbpc. The character definition then
  146. consists of r_charh rows of r_cbpl each so r_cbpc=r_charh*r_cbpl. NB r_cbpl
  147. need not be a multiple of 4 so this address need not be word aligned.
  148.  
  149. The format of a row is the same of that for a sprite file except there is
  150. never any lhs wastage. Ie, the first pixel is aligned to the start of the
  151. first word. Each character is r_charw pixels wide and thus requires
  152. N=r_charw<<r_bpp bits of storage. There are special cases when N is small:
  153.  
  154.  If 0<N=<8  then r_cbpl=1 and the top 8-N bits of each byte are wasted.
  155.  If 8<N=<16 then r_cbpl=2 and the top 16-N bits of each byte are wasted.
  156.  If N>16    then r_cbpl is aligned to the next multiple of 4 bytes greater
  157.   or equal to N. (eg 16<N=<32 => r_cbpl=4, 32<N=<64 => r_cbpl=8 etc).
  158.   
  159. The SWI ZapRedraw_CachedCharSize will calculate the values of r_cbpl and
  160. r_cbpc for you from a given size of character.
  161.  
  162. Only TWO colours can be used in the defn of the character. Set all foreground
  163. pixels to 1's and background pixels to 0's. Eg, in a 16 colour mode pixels
  164. will be either 1111 or 0000. Unused bits at the end of the words (or bytes)
  165. are ignored and so can contain rubbish. The real foreground and background
  166. colours are masked in at run time.
  167.  
  168.  Examples:
  169.  
  170.  For 8*8 characters at 1 bit per pixel we have 1 byte per row. Eg "E" may be
  171.  cached as:
  172.                   b0 .. b7
  173.       row0    &7E        01111110
  174.     row1    &06        01100000
  175.       row2    &06        01100000
  176.       row3    &7E        01111110
  177.       row4    &06        01100000
  178.       row5    &06        01100000
  179.       row6    &7E        01111110
  180.       row7    &00        00000000
  181.  
  182.  If it was in a 16 colour mode then there would be one word per row and the
  183.  first rows would be:
  184.                  b0 ......................... b31
  185.      row0    &01111110    00001111111111111111111111110000
  186.      row1    &00000110    00001111111100000000000000000000
  187.      ...
  188.       
  189.  In general you have:
  190.  
  191.      Word 0                    Word (N/4)-1
  192.      b0 .... b31    ...................      b0 ..... b31
  193.      pix0 pix1 ......................pix(r_charw-1) 00000
  194.      
  195. In practice you first cache the font at one bit per pixel (eg use
  196. ZapRed