home *** CD-ROM | disk | FTP | other *** search
/ Current Shareware 1994 January / SHAR194.ISO / drawing / tdraw462.zip / QB4UTIL.BI < prev    next >
Text File  |  1993-09-07  |  10KB  |  198 lines
  1. '
  2. '   QUICKBASIC SUPPORT ROUTINES FOR THEDRAW OBJECT FILES
  3. '-----------------------------------------------------------------------------
  4. '   Compatible with Microsoft QuickBasic v4.0 and v4.5 text modes.
  5. '-----------------------------------------------------------------------------
  6. '
  7. '   There are a few routines within the QB4UTIL.LIB file.  These are
  8. '   (along with brief descriptions):
  9. '
  10. '     UNCRUNCH          - Flash display routine for crunched image files.
  11. '     ASCIIDISPLAY      - Display routine for ascii only image files.
  12. '     NORMALDISPLAY     - Display routine for normal full binary image files.
  13. '     INITSCREENARRAY   - Maps a dynamic integer array to the physical video
  14. '                         memory.
  15. '
  16. '=============================================================================
  17. '   UNCRUNCH (imagedata,video offset)
  18. '   ASCIIDISPLAY (imagedata,video offset)
  19. '   NORMALDISPLAY (imagedata,video offset)
  20. '=============================================================================
  21. '
  22. '   These three subroutines operate similarly.  Each takes a specific data
  23. '   format (TheDraw crunched data, ascii only, or normal binary) and displays
  24. '   the image on the screen.  Monochrome and color text video displays are
  25. '   supported.  The integer offset parameter is useful with block images,
  26. '   giving control over where the block appears.
  27. '
  28. '   Example calls:
  29. '     CALL UNCRUNCH (ImageData&,vidoffset%)        <- for crunched data
  30. '     CALL ASCIIDISPLAY (ImageData&,vidoffset%)    <- for ascii-only data
  31. '     CALL NORMALDISPLAY (ImageData&,vidoffset%)   <- for normal binary data
  32. '
  33. '   The parameter IMAGEDATA is the identifier you assign when saving
  34. '   a QuickBasic object file with TheDraw.  ImageData actually becomes a
  35. '   short function returning information Uncrunch, AsciiDisplay, and
  36. '   NormalDisplay use to find the screen contents.  In addition, three
  37. '   other related integer functions are created.  Assuming the identifier
  38. '   IMAGEDATA, these are:
  39. '
  40. '         IMAGEDATAWIDTH%
  41. '         IMAGEDATADEPTH%
  42. '         IMAGEDATALENGTH%
  43. '
  44. '   The width and depth functions return the size of the block in final
  45. '   form (ie: a full screen would yield the numbers 80 and 25 respectfully).
  46. '   The length function returns the size of the stored data.  For crunched
  47. '   files and block saves this might be very small.  For a 80x25 full screen
  48. '   binary image it will be 4000 bytes.  The integer functions are useful for
  49. '   computing screen or window dimensions, etc...
  50. '
  51. '   You must declare all four functions in your Basic source code before
  52. '   they can be used (naturally).  The following code example illustrates.
  53. '   The identifier used is IMAGEDATA.  The data is a 40 character by 10 line
  54. '   block saved as normal binary.
  55. '
  56. '     ----------------------------------------------------------------------
  57. '       REM $INCLUDE: 'QB4UTIL.BI'
  58. '       DECLARE FUNCTION ImageData&         ' Important!  Do not neglect
  59. '       DECLARE FUNCTION ImageDataWidth%    ' the "&" and "%" symbols
  60. '       DECLARE FUNCTION ImageDataDepth%    ' after the function names.
  61. '       DECLARE FUNCTION ImageDataLength%
  62. '
  63. '       CALL NORMALDISPLAY (ImageData&, 34 *2+( 5 *160)-162)
  64. '     ----------------------------------------------------------------------
  65. '
  66. '   That's it!  The above displays the 40x10 block at screen coordinates
  67. '   column 34, line 5 (note these two numbers in above example).  If the
  68. '   data was crunched or ascii use the corresponding routine.
  69. '
  70. '      Note: The ascii-only screen image does not have any color controls.
  71. '            Whatever the on-screen colors were before, they will be after.
  72. '            You might want to insert COLOR and CLS statements before calling
  73. '            the ASCIIDISPLAY routine.
  74. '
  75. '   Regardless of which routine used, each remembers the original horizontal
  76. '   starting column when it goes to the next line.  This permits a block to
  77. '   be displayed correctly anywhere on the screen.  ie:
  78. '
  79. '       +-------------------------------------------------+
  80. '       |                                                 |
  81. '       |                                                 | <- Pretend this
  82. '       |                                                 |    is the video
  83. '       |           ┌─────────────────────┐               |    display.
  84. '       |           │█████████████████████│               |
  85. '       |           │█████████████████████│               |
  86. '       |           │██ ImageData block ██│               |
  87. '       |           │█████████████████████│               |
  88. '       |           │█████████████████████│               |
  89. '       |           │█████████████████████│               |
  90. '       |           └─────────────────────┘               |
  91. '       |                                                 |
  92. '       |                                                 |
  93. '       |                                                 |
  94. '       +-------------------------------------------------+
  95. '
  96. '
  97. '   The ImageData block could be shown in the upper-left corner of the
  98. '   screen by changing the call to:
  99. '
  100. '         CALL NORMALDISPLAY (ImageData&,0)
  101. '
  102. '   Notice the video offset has been removed, since we want the upper-left
  103. '   corner.  To display the block in the lower-right corner you would use:
  104. '
  105. '         CALL NORMALDISPLAY (ImageData&, 40 *2+( 15 *160)-162)
  106. '
  107. '   The block is 40 characters wide by 10 lines deep.  Therefore to display
  108. '   such a large block, we must display the block at column 40, line 15.
  109. '   (column 80 minus 40, line 25 minus 10).
  110. '
  111. '
  112. ' NOTES ON THE UNCRUNCH ROUTINE
  113. ' --------------------------------------------------------------------------
  114. '
  115. '   Many people favor "crunching" screens with TheDraw because the size
  116. '   of the data generally goes down.  When uncrunching an image however,
  117. '   there is no guarantee what was previously on-screen will be replaced.
  118. '
  119. '   In particular, the uncruncher assumes the screen is previously erased to
  120. '   black thus permitting better data compression.  For instance, assume the
  121. '   video completely filled with blocks, overwritten by an uncrunched image:
  122. '
  123. '      ┌─────────────────────┐            ┌─────────────────────┐
  124. '      │█████████████████████│            │tetetetetet██████████│
  125. '      │█████████████████████│            │█████████████████████│
  126. '      │█████████████████████│            │    etetetetetete████│
  127. '      │█████████████████████│            │tetetetet████████████│
  128. '      │█████████████████████│            │         ete█████████│
  129. '      │█████████████████████│            │       etetetetetet██│
  130. '      └─────────────────────┘            └─────────────────────┘
  131. '          before uncrunch                    after uncrunch
  132. '
  133. '   By omitting a CLS statement, the new text appears surrounded by bits of
  134. '   the previous screen.  Proper usage would typically be:
  135. '
  136. '     ----------------------------------------------------------------------
  137. '       REM $INCLUDE: 'QB4UTIL.BI'
  138. '       DECLARE FUNCTION ImageData&         ' Important!  Do not neglect
  139. '       DECLARE FUNCTION ImageDataWidth%    ' the "&" and "%" symbols
  140. '       DECLARE FUNCTION ImageDataDepth%    ' after the function names.
  141. '       DECLARE FUNCTION ImageDataLength%
  142. '
  143. '       COLOR 15,0 : CLS                      ' Clear to black screen
  144. '       CALL UNCRUNCH (ImageData&, 34 *2+( 5 *160)-162)
  145. '     ----------------------------------------------------------------------
  146. '
  147. '
  148. '=============================================================================
  149. '   INITSCREENARRAY
  150. '=============================================================================
  151. '
  152. '   To directly access the video screen memory requires you to use the
  153. '   PEEK/POKE statements after setting the DEF SEG value.  A cumbersome
  154. '   and compiler inefficient approach.  In addition, you must have some
  155. '   way of determining if a monochrome or color video is being used before
  156. '   the DEF SEG can be set properly.
  157. '
  158. '   This subroutine offers a simpler approach, by effectively mapping or
  159. '   placing an integer array over the video screen.  Instead of PEEK/POKE,
  160. '   you merely reference an array element.  ie:
  161. '
  162. '     ----------------------------------------------------------------------
  163. '       REM $INCLUDE: 'QB4UTIL.BI'
  164. '
  165. '       REM $DYNAMIC    <- very important to place this before DIM statement
  166. '       DIM S%(0)
  167. '       CALL INITSCREENARRAY (S%())
  168. '
  169. '       S%(0) = ASC("H") + 15 *256 + 1 *4096
  170. '       S%(1) = ASC("E") + 15 *256 + 1 *4096
  171. '       S%(2) = ASC("L") + 15 *256 + 1 *4096
  172. '       S%(3) = ASC("L") + 15 *256 + 1 *4096
  173. '       S%(4) = ASC("O") + 15 *256 + 1 *4096
  174. '     ----------------------------------------------------------------------
  175. '
  176. '   The above example directly places the message "HELLO" on the screen
  177. '   for you, in white lettering (the 15*256) on a blue background (1*4096).
  178. '   To alter the foreground color, change the 15's to some other number.
  179. '   Change the 1's for the background color.
  180. '
  181. '   Each array element contains both the character to display plus the
  182. '   color information.  This explains the bit of math following each
  183. '   ASC statement.  You could minimize this using a FOR/NEXT loop.
  184. '
  185. '   The S% array has 2000 elements (0 to 1999) representing the entire
  186. '   80 by 25 line video.  If in an EGA/VGA screen mode change the 1999 to
  187. '   3439 or 3999 respectfully.
  188. '
  189. '   There is no pressing reason to use the array approach, however it
  190. '   does free up the DEFSEG/PEEK/POKE combination for other uses.  In
  191. '   any case, enjoy!
  192. '
  193. '
  194. DECLARE SUB UNCRUNCH (X&, Z%)
  195. DECLARE SUB ASCIIDISPLAY (X&, Z%)
  196. DECLARE SUB NORMALDISPLAY (X&, Z%)
  197. DECLARE SUB INITSCREENARRAY (A%())
  198.