home *** CD-ROM | disk | FTP | other *** search
/ Assembly 1994 - The 3rd Phase / ASMROM94.mdf / sources / xlib06.txt < prev    next >
Text File  |  1994-11-12  |  60KB  |  1,656 lines

  1. PART 1 of 2
  2. -----------------------------------------------------------------------------
  3.  
  4.   *********      XLIB - Mode X graphics library           ****************
  5.   *********                                               ****************
  6.   ********* Written By Themie Gouthas                     ****************
  7.   *********                                               ****************
  8.   ********* egg@dstos3.dsto.gov.au                        ****************
  9.   ********* teg@bart.dsto.gov.au                          ****************
  10.  
  11.       Some of the code in this library has been contributed by :
  12.  
  13.                Matthew MacKenzie - matm@eng.umd.edu
  14.  
  15.                 and others. See individual modules.
  16.  
  17.          I informally reserve all rights to the code in XLIB
  18.      Rights to contributed code is also assumed to be reserved by
  19.                    the original authors.
  20. -----------------------------------------------------------------------------
  21.  
  22. DISCLAIMER
  23.  
  24.  This library is distributed AS IS. The author/s specifically disclaim
  25.  any responsibility for any loss of profit or any incidental, consequen-
  26.  tial or other damages.
  27.  
  28. ---------------------------------------------------------------------------
  29. INTRODUCTION
  30. ---------------------------------------------------------------------------
  31.  
  32. XLIB is a "user supported freeware" graphics library specifically designed
  33. with game programming in mind.
  34.  
  35. It has been placed in the public domain for the benefit of all, and
  36. represents *MANY* hours of work so it is requested that all users comply
  37. with the the wishes of the author/s as specified in the individual modules
  38. and:
  39. a) To leave the code in the public domain
  40. b) Not distribute any modified or incomplete versions of this library
  41.  
  42. New contribution and comments are welcome and hopefully there will be
  43. more releases as the code evolves.
  44.  
  45. Finally, do not trust this excuse for a manual if in doubt, as this code has
  46. undergone several revisions. The place to get the answers is in the code
  47. itself.
  48.  
  49. REQUIREMENTS
  50.  
  51. Minimum requirements
  52.         286 processor,
  53.         Turbo C 2.0 or higher, or BORLANDC
  54.         MAKE  2.0 or higher
  55.         TLIB  2.0 or higher
  56.         Turbo Assembler 1.01 or higher
  57.  
  58.  
  59. GENERAL FEATURES
  60.  
  61.    Support for a number of 256 colour tweaked graphics mode resolutions
  62.    320x200 320x240 360x200 360x240 376x282 320x400 320x480 360x400 360x480
  63.    360x360 376x308 376x564
  64.  
  65.    Please note that some of the new resolutions best suit monitors with
  66.    adjustable vertical height.
  67.  
  68.    Virtual screens larger than the physical screen (memory
  69.    permitting) that can be panned at pixel resolution in all directions
  70.  
  71.    A split screen capability for status displays etc.
  72.  
  73.    Text functions supporting 8x8 and 8x14 ROM fonts and user defined fonts
  74.  
  75.    Support for page flipping
  76.  
  77.    Graphics primitives such as line and rectangle drawing functions and
  78.    of course bit block manipulation functions
  79.  
  80. MODULES COMPRISING XLIB
  81.    XMAIN    - Main module containig mode setting code and basic functions
  82.    XPOINT   - Pixel functions
  83.    XRECT    - Filled Rectangle and VRAM to VRAM block move functions
  84.    XPAL     - Palette functions
  85.    XLINE    - Line Functions
  86.    XTEXT    - Text and Font Functions
  87.    XPRINTF  - Printf style string output
  88.    XPBITMAP - Planar Bitmap functions
  89.    XCBITMAP - Compiled Bitmap functions
  90.    XVBITMAP - Video Bitmap functions
  91.    XPBMCLIP - Clipped Planar Bitmap functions
  92.    XMAKEVBM - Support module for video bitmaps
  93.    XBMTOOLS - Bitmap format conversion tools
  94.    XDETECT  - Hardware detection module
  95.    XFILEIO  - File I/O functions
  96.    XRLETOOL - RLE encoding/decoding functions
  97.    XMOUSE   - Mouse functions
  98.    XBEZIER  - Bezier curve drawing
  99.  
  100. -------------------------------------------------------------------------
  101. BUILDING THE LIBRARIES
  102. -------------------------------------------------------------------------
  103.  
  104. Building the library had been made simple through the use of make.
  105.  
  106. To build and examples for one of the two models:
  107.  
  108. a) edit the makefile for the apropriate model (see note in the makefile)
  109. b) edit the makefile for the apropriate compiler (again see note in the
  110.    makefile)
  111. c) type "make" at the dos prompt.
  112.  
  113. It should be as simple as that. If problems are encountered then check
  114. to see if tasm, make, tlib, link and bcc (or tcc) are withinin your path.
  115. If not either change your path or specify the full path for these programs
  116. in the makefile. It is preferrable to have your path set correctly.
  117.  
  118. Individual Compilation
  119. ----------------------
  120.  
  121. each ASM module can be compiled with the following commandline:
  122.  
  123. tasm /ml /d<model> <asm module name>
  124.  
  125. where <model> is s c or l. Where s = small model, c = compact model and
  126. l = large model.
  127.  
  128. The resulting libraries are:
  129.  
  130.   xlib<version>s.lib    - small model library
  131.   xlib<version>c.lib    - large model library
  132.   xlib<version>l.lib    - large model library
  133.  
  134. To link the library with your programs just include the apropriate .lib
  135. file in your project file or on the BCC or TCC command line.
  136.  
  137. Using the library with your programs
  138. ------------------------------------
  139.  
  140. Using the XLIB library in your programs is simple. Knowing the particular
  141. modules you require, just include the associated header files in your program
  142. and link your program modules with the library. If you don't want to wory
  143. about selecting the apropriate header file then just include "XLIB_ALL.H"
  144. which automatically includes all XLIB header files in your program.
  145.  
  146. For example compilations see the supplied makefile.
  147.  
  148. --------------------------------------------------------------------------
  149. GLOBAL DEFINES (xlib.inc)
  150. --------------------------------------------------------------------------
  151.  
  152. Types
  153.  
  154.  BYTE unsigned char
  155.  WORD unsigned int
  156.  
  157. Available X mode resolutions
  158.  
  159.  X_MODE_320x200  0
  160.  X_MODE_320x240  1
  161.  X_MODE_360x200  2
  162.  X_MODE_360x240  3
  163.  X_MODE_360x282  4
  164.  X_MODE_320x400  5
  165.  X_MODE_320x480  6
  166.  X_MODE_360x400  7
  167.  X_MODE_360x480  8
  168.  X_MODE_360x360  9
  169.  X_MODE_376x308  10
  170.  X_MODE_376x564  11
  171.  
  172. Palette rotation direction directiion
  173.  
  174.  BACKWARD 0
  175.  FORWARD  1
  176.  
  177.  
  178.  X_MODE_INVALID -1
  179.  ERROR           1
  180.  OK              0
  181.  
  182.  
  183. --------------------------------------------------------------------------
  184. MODULE XMAIN
  185. --------------------------------------------------------------------------
  186.  
  187. The Xmain module is the base module of the XLIB library. It contains the
  188. essential functions that initialize and customize the graphic environment.
  189.  
  190.  
  191. ASM SOURCES
  192.  
  193.    xmain.asm xmain.inc xlib.inc model.inc
  194.  
  195. C HEADER FILE
  196.  
  197.    xlib.h
  198.  
  199. EXPORTED VARIABLES
  200.  
  201.   NOTE: All variables are read only unless otherwise specified. If you modify
  202.   them manually, the results may be unpredictable.
  203.  
  204.   InGraphics -  BYTE -  Flag indicating that the xlib graphics system is
  205.        active. Set by function "x_set_mode".
  206.  
  207.   CurrXMode - WORD - If the xlib graphics system is active, contains the id
  208.        of the x mode. Set by function "x_set_mode".
  209.        See also defines (ie X_MODE_320x200 ... )
  210.  
  211.   ScrnPhysicalByteWidth - WORD - Physical screen width in bytes. Set by
  212.        function "x_set_mode"
  213.  
  214.   ScrnPhysicalPixelWidth - WORD - Physical screen width in pixels. Set by
  215.        function "x_set_mode"
  216.  
  217.   ScrnPhysicalHeight - WORD - Physical screen height in pixels. Set by
  218.        function "x_set_mode".
  219.  
  220.   ErrorValue - WORD - Contains error value. General use variable to
  221.        communicate the error status from several functions. The value
  222.        in this variable usually is only valid for the the last
  223.        function called that sets it.
  224.  
  225.   SplitScrnOffs - WORD - Offset in video ram of split screen. Set by
  226.        function "x_set_splitscrn". The value is only valid if a split
  227.        screen is active. See also global variable "SplitScrnActive".
  228.  
  229.   SplitScrnScanLine - WORD - Screen Scan Line the Split Screen starts at
  230.        initially when set by function "x_set_splitscrn". The value is only
  231.        valid if a split screen is active. See also global variable
  232.        "SplitScrnActive".This