16/xlib/xlibref1.doc

   1 PART 1 of 2\r
   2 -----------------------------------------------------------------------------\r
   3 \r
   4   *********      XLIB - Mode X graphics library           ****************\r
   5   *********                                               ****************\r
   6   ********* Written By Themie Gouthas                     ****************\r
   7   *********                                               ****************\r
   8   ********* egg@dstos3.dsto.gov.au                        ****************\r
   9   ********* teg@bart.dsto.gov.au                          ****************\r
  10 \r
  11       Some of the code in this library has been contributed by :\r
  12 \r
  13                Matthew MacKenzie - matm@eng.umd.edu\r
  14 \r
  15                 and others. See individual modules.\r
  16 \r
  17          I informally reserve all rights to the code in XLIB\r
  18      Rights to contributed code is also assumed to be reserved by\r
  19                    the original authors.\r
  20 -----------------------------------------------------------------------------\r
  21 \r
  22 DISCLAIMER\r
  23 \r
  24  This library is distributed AS IS. The author/s specifically disclaim\r
  25  any responsibility for any loss of profit or any incidental, consequen-\r
  26  tial or other damages.\r
  27 \r
  28 ---------------------------------------------------------------------------\r
  29 INTRODUCTION\r
  30 ---------------------------------------------------------------------------\r
  31 \r
  32 XLIB is a "user supported freeware" graphics library specifically designed\r
  33 with game programming in mind.\r
  34 \r
  35 It has been placed in the public domain for the benefit of all, and\r
  36 represents *MANY* hours of work so it is requested that all users comply\r
  37 with the the wishes of the author/s as specified in the individual modules\r
  38 and:\r
  39 a) To leave the code in the public domain\r
  40 b) Not distribute any modified or incomplete versions of this library\r
  41 \r
  42 New contribution and comments are welcome and hopefully there will be\r
  43 more releases as the code evolves.\r
  44 \r
  45 Finally, do not trust this excuse for a manual if in doubt, as this code has\r
  46 undergone several revisions. The place to get the answers is in the code\r
  47 itself.\r
  48 \r
  49 REQUIREMENTS\r
  50 \r
  51 Minimum requirements\r
  52         286 processor,\r
  53         Turbo C 2.0 or higher, or BORLANDC\r
  54         MAKE  2.0 or higher\r
  55         TLIB  2.0 or higher\r
  56         Turbo Assembler 1.01 or higher\r
  57 \r
  58 \r
  59 GENERAL FEATURES\r
  60 \r
  61    Support for a number of 256 colour tweaked graphics mode resolutions\r
  62    320x200 320x240 360x200 360x240 376x282 320x400 320x480 360x400 360x480\r
  63    360x360 376x308 376x564\r
  64 \r
  65    Please note that some of the new resolutions best suit monitors with\r
  66    adjustable vertical height.\r
  67 \r
  68    Virtual screens larger than the physical screen (memory\r
  69    permitting) that can be panned at pixel resolution in all directions\r
  70 \r
  71    A split screen capability for status displays etc.\r
  72 \r
  73    Text functions supporting 8x8 and 8x14 ROM fonts and user defined fonts\r
  74 \r
  75    Support for page flipping\r
  76 \r
  77    Graphics primitives such as line and rectangle drawing functions and\r
  78    of course bit block manipulation functions\r
  79 \r
  80 MODULES COMPRISING XLIB\r
  81    XMAIN    - Main module containig mode setting code and basic functions\r
  82    XPOINT   - Pixel functions\r
  83    XRECT    - Filled Rectangle and VRAM to VRAM block move functions\r
  84    XPAL     - Palette functions\r
  85    XLINE    - Line Functions\r
  86    XTEXT    - Text and Font Functions\r
  87    XPRINTF  - Printf style string output\r
  88    XPBITMAP - Planar Bitmap functions\r
  89    XCBITMAP - Compiled Bitmap functions\r
  90    XVBITMAP - Video Bitmap functions\r
  91    XPBMCLIP - Clipped Planar Bitmap functions\r
  92    XMAKEVBM - Support module for video bitmaps\r
  93    XBMTOOLS - Bitmap format conversion tools\r
  94    XDETECT  - Hardware detection module\r
  95    XFILEIO  - File I/O functions\r
  96    XRLETOOL - RLE encoding/decoding functions\r
  97    XMOUSE   - Mouse functions\r
  98    XBEZIER  - Bezier curve drawing\r
  99 \r
 100 -------------------------------------------------------------------------\r
 101 BUILDING THE LIBRARIES\r
 102 -------------------------------------------------------------------------\r
 103 \r
 104 Building the library had been made simple through the use of make.\r
 105 \r
 106 To build and examples for one of the two models:\r
 107 \r
 108 a) edit the makefile for the apropriate model (see note in the makefile)\r
 109 b) edit the makefile for the apropriate compiler (again see note in the\r
 110    makefile)\r
 111 c) type "make" at the dos prompt.\r
 112 \r
 113 It should be as simple as that. If problems are encountered then check\r
 114 to see if tasm, make, tlib, link and bcc (or tcc) are withinin your path.\r
 115 If not either change your path or specify the full path for these programs\r
 116 in the makefile. It is preferrable to have your path set correctly.\r
 117 \r
 118 Individual Compilation\r
 119 ----------------------\r
 120 \r
 121 each ASM module can be compiled with the following commandline:\r
 122 \r
 123 tasm /ml /d<model> <asm module name>\r
 124 \r
 125 where <model> is s c or l. Where s = small model, c = compact model and\r
 126 l = large model.\r
 127 \r
 128 The resulting libraries are:\r
 129 \r
 130   xlib<version>s.lib    - small model library\r
 131   xlib<version>c.lib    - large model library\r
 132   xlib<version>l.lib    - large model library\r
 133 \r
 134 To link the library with your programs just include the apropriate .lib\r
 135 file in your project file or on the BCC or TCC command line.\r
 136 \r
 137 Using the library with your programs\r
 138 ------------------------------------\r
 139 \r
 140 Using the XLIB library in your programs is simple. Knowing the particular\r
 141 modules you require, just include the associated header files in your program\r
 142 and link your program modules with the library. If you don't want to wory\r
 143 about selecting the apropriate header file then just include "XLIB_ALL.H"\r
 144 which automatically includes all XLIB header files in your program.\r
 145 \r
 146 For example compilations see the supplied makefile.\r
 147 \r
 148 --------------------------------------------------------------------------\r
 149 GLOBAL DEFINES (xlib.inc)\r
 150 --------------------------------------------------------------------------\r
 151 \r
 152 Types\r
 153 \r
 154  BYTE unsigned char\r
 155  WORD unsigned int\r
 156 \r
 157 Available X mode resolutions\r
 158 \r
 159  X_MODE_320x200  0\r
 160  X_MODE_320x240  1\r
 161  X_MODE_360x200  2\r
 162  X_MODE_360x240  3\r
 163  X_MODE_360x282  4\r
 164  X_MODE_320x400  5\r
 165  X_MODE_320x480  6\r
 166  X_MODE_360x400  7\r
 167  X_MODE_360x480  8\r
 168  X_MODE_360x360  9\r
 169  X_MODE_376x308  10\r
 170  X_MODE_376x564  11\r
 171 \r
 172 Palette rotation direction directiion\r
 173 \r
 174  BACKWARD 0\r
 175  FORWARD  1\r
 176 \r
 177 \r
 178  X_MODE_INVALID -1\r
 179  ERROR           1\r
 180  OK              0\r
 181 \r
 182 \r
 183 --------------------------------------------------------------------------\r
 184 MODULE XMAIN\r
 185 --------------------------------------------------------------------------\r
 186 \r
 187 The Xmain module is the base module of the XLIB library. It contains the\r
 188 essential functions that initialize and customize the graphic environment.\r
 189 \r
 190 \r
 191 ASM SOURCES\r
 192 \r
 193    xmain.asm xmain.inc xlib.inc model.inc\r
 194 \r
 195 C HEADER FILE\r
 196 \r
 197    xlib.h\r
 198 \r
 199 EXPORTED VARIABLES\r
 200 \r
 201   NOTE: All variables are read only unless otherwise specified. If you modify\r
 202   them manually, the results may be unpredictable.\r
 203 \r
 204   InGraphics -  BYTE -  Flag indicating that the xlib graphics system is\r
 205        active. Set by function "x_set_mode".\r
 206 \r
 207   CurrXMode - WORD - If the xlib graphics system is active, contains the id\r
 208        of the x mode. Set by function "x_set_mode".\r
 209        See also defines (ie X_MODE_320x200 ... )\r
 210 \r
 211   ScrnPhysicalByteWidth - WORD - Physical screen width in bytes. Set by\r
 212        function "x_set_mode"\r
 213 \r
 214   ScrnPhysicalPixelWidth - WORD - Physical screen width in pixels. Set by\r
 215        function "x_set_mode"\r
 216 \r
 217   ScrnPhysicalHeight - WORD - Physical screen height in pixels. Set by\r
 218        function "x_set_mode".\r
 219 \r
 220   ErrorValue - WORD - Contains error value. General use variable to\r
 221        communicate the error status from several functions. The value\r
 222        in this variable usually is only valid for the the last\r
 223        function called that sets it.\r
 224 \r
 225   SplitScrnOffs - WORD - Offset in video ram of split screen. Set by\r
 226        function "x_set_splitscrn". The value is only valid if a split\r
 227        screen is active. See also global variable "SplitScrnActive".\r
 228 \r
 229   SplitScrnScanLine - WORD - Screen Scan Line the Split Screen starts at\r
 230        initially when set by function "x_set_splitscrn". The value is only\r
 231        valid if a split screen is active. See also global variable\r
 232        "SplitScrnActive".This variable is not updated by "x_hide_splitscrn",\r
 233        "x_adjust_splitscrn".\r
 234 \r
 235   SplitScrnVisibleHeight - WORD - The number of rows of the initial split\r
 236        screen which are currently displayed. Modified by "x_hide_splitscrn",\r
 237        "x_adjust_splitscrn" and "x_show_splitscrn".\r
 238 \r
 239   Page0_Offs - WORD - Offset in video ram of main virtual screen. Initially\r
 240        set by function "x_set_mode" but is updated by functions\r
 241        "x_set_splitscrn" and "x_set_doublebuffer".\r
 242 \r
 243   Page1_Offs - WORD - Offset in video ram of second virtual screen. Set by\r
 244        and only is valid after a call to "x_set_doublebuffer".\r
 245 \r
 246   ScrnLogicalByteWidth - WORD - Virtual screen width in bytes. Set by\r
 247        function "x_set_mode".\r
 248 \r
 249   ScrnLogicalPixelWidth - WORD - Virtual screen width in pixels. Set\r
 250        by function "x_set_mode".\r
 251 \r
 252   ScrnLogicalHeight - WORD - Virtual screen height in pixels. Set\r
 253        initially by function "x_set_mode" but is updated by functions\r
 254        "x_set_splitscrn" and "x_set_doublebuffer".\r
 255 \r
 256   MaxScrollX - WORD - Max X pixel position of physical screen within\r
 257        virtual screen. Set by function "x_set_mode".\r
 258 \r
 259   MaxScrollY - WORD - Max Y position of physical screen within virtual\r
 260        screen. Set initially by function "x_set_mode" but is updated by\r
 261        functions "x_set_splitscrn" and "x_set_doublebuffer".\r
 262 \r
 263   DoubleBufferActive - WORD - Indicates whether double-buffering is on. Set\r
 264        by function "x_set_doublebuffer".\r
 265 \r
 266   VisiblePageIdx - WORD - Index number of current visible page. Initially\r
 267        set by function "x_set_doublebuffer" but is updated by "x_page_flip".\r
 268        This variable is only used while double buffering is on.\r
 269 \r
 270   HiddenPageOffs - WORD - Offset of hidden page. Initially set by function\r
 271        "x_set_doublebuffer" but is updated by "x_page_flip". This variable\r
 272        is only used while double buffering is on.\r
 273 \r
 274   VisiblePageOffs - WORD - Offset of visible page. Initially set by function\r
 275        "x_set_doublebuffer" but is updated by "x_page_flip". This variable\r
 276        is only used while double buffering is on.\r
 277 \r
 278   NonVisual_Offs - WORD - Offset of first byte of non-visual ram, the ram\r
 279        that is available for bitmap storage etc. Set initially by function\r
 280        "x_set_mode" but is updated by functions "x_set_splitscrn" and\r
 281        "x_set_doublebuffer".\r
 282 \r
 283   TopClip, BottomClip, LeftClip RightClip - WORD - Define the clipping\r
 284        rectangle for Linear and Video clipped bitmap put functions. Set\r
 285        either manually or by "x_set_cliprect". Note X coordinates are in\r
 286        bytes as all clip functions clip to byte boundaries.\r
 287 \r
 288   PhysicalStartPixelX - WORD - X pixel Offset of physical (visible) screen\r
 289        relative to the upper left hand corner (0,0) of the virtual screen.\r
 290 \r
 291   PhysicalStartByteX - WORD - X byte Offset of physical (visible) screen\r
 292        relative to the upper left hand corner (0,0) of the virtual screen.\r
 293 \r
 294   PhysicalStartY - WORD - Y pixel Offset of physical (visible) screen\r
 295        relative to the upper left hand corner (0,0) of the virtual screen.\r
 296 \r
 297 EXPORTED FUNCTIONS\r
 298 \r
 299   x_set_mode\r
 300   ----------\r
 301     C Prototype:  extern WORD x_set_mode(WORD mode,WORD WidthInPixels);\r
 302 \r
 303      mode          - The required mode as defined by the "Available X Mode\r
 304                      resolutions" set of defines in the xlib.h header file.\r
 305      WidthInPixels - The required virtual screen width.\r
 306      Returns       - The actual width in pixels of the allocated virtual\r
 307                      screen\r
 308 \r
 309   This function initialises the graphics system, setting the apropriate\r
 310   screen resolution and allocating a virtual screen. The virtual screen\r
 311   allocated may not necessarily be of the same size as specified in the\r
 312   "WidthInPixels" parameter as it is rounded down to the nearest\r
 313   multiple of 4.\r
 314 \r
 315   The function returns the actual width of the allocated virtual screen\r
 316   in pixels if a valid mode was selected otherwise returns\r
 317   X_MODE_INVALID.\r
 318 \r
 319   Saves virtual screen pixel width in "ScrnLogicalPixelWidth".\r
 320   Saves virtual screen byte  width in "ScrnLogicalByteWidth".\r
 321   Physical screen dimensions are set in "ScrnPhysicalPixelWidth".\r
 322   "ScrnPhysicalByteWidth" and "ScrnPhysicalHeight". Other global\r
 323   variables set are "CurrXMode","MaxScrollX", "MaxScrollY",\r
 324   "InGraphics". The variable "SplitScrnScanline" is also initialized\r
 325   to zero.\r
 326 \r
 327   See also:\r
 328      Available X Mode resolutions\r
 329      What is Mode X\r
 330 \r
 331   x_select_default_plane\r
 332   ----------------------\r
 333 \r
 334     C Prototype:  void x_select_default_plane(BYTE plane);\r
 335 \r
 336     Enables default Read/Write access to a specified plane\r
 337 \r
 338 \r
 339   x_set_splitscreen\r
 340   -----------------\r
 341 \r
 342     C Prototype:  extern void x_set_splitscreen(WORD line);\r
 343 \r
 344     line - The starting scan line of the required split screen.\r
 345 \r
 346   This function activates Mode X split screen and sets starting scan\r
 347   line. The split screen resides on the bottom half of the screen and has\r
 348   a starting address of A000:0000 in video RAM.\r
 349 \r
 350   It also Updates Page0_Offs to reflect the existence of the split screen\r
 351   region ie "MainScrnOffset" is set to the offset of the first pixel\r
 352   beyond the split screen region. Other variable set are "Page1_Offs" which\r
 353   is set to the same value as "Page0_Offs" (see graphics call sequence\r
 354   below), "ScrnLogicalHeight","ScrnPhysicalHeight", "SplitScrnScanLine" and\r
 355   "MaxScrollY".\r
 356 \r
 357   This function cannot be called after double buffering has been activated,\r
 358   it will return an error. To configure your graphics environment the\r
 359   sequence of graphics calls is as follows although either or both steps b\r
 360   and c may be omitted:\r
 361     a) x_set_mode\r
 362     b) x_set_splitscreen\r
 363     c) x_set_doublebuffer\r
 364   Thus when you call this function successfully, double buffering is not\r
 365   active so "Page1_Offs" is set to the same address as "Page0_Offs".\r
 366 \r
 367   WARNING: If you use one of the high resolution modes (376x564 as an\r
 368     extreme example) you may not have enough video ram for split screen\r
 369     and double buffering options since VGA video RAM is restricted to\r
 370     64K.\r
 371 \r
 372   See Also:\r
 373     What is a Split Screen ?\r
 374     What is double buffering ?\r
 375 \r
 376   x_set_doublebuffer\r
 377   ------------------\r
 378 \r
 379   C Prototype: extern WORD x_set_doublebuffer(WORD PageHeight);\r
 380 \r
 381   PageHeight - The height of the two double buffering virtual screens.\r
 382   Returns    - The closest possible height to the specified.\r
 383 \r
 384   This function sets up two double buffering virtual pages. 'ErrorValue"\r
 385   is set according to the success or failure of this command.\r
 386 \r
 387   Other variables set are:\r
 388 \r
 389     _Page1_Offs              Offset of second virtual page\r
 390     _NonVisual_Offs          Offset of first non visible video ram byte\r
 391     _DoubleBufferActive      Flag\r
 392     _PageAddrTable           Table of Double buffering pages start offsets\r
 393     _ScrnLogicalHeight       Logical height of the double buffering pages\r
 394     _MaxScrollY              Max vertical start address of physical screen\r
 395                              within the virtual screen\r
 396 \r
 397   WARNING: If you use one of the high resolution modes (376x564 as an\r
 398     extreme example) you may not have enough video ram for split screen\r
 399     and double buffering options since VGA video RAM is restricted to\r
 400     64K.\r
 401 \r
 402   See Also:\r
 403     What is double buffering ?\r
 404 \r
 405   x_hide_splitscreen\r
 406   ------------------\r
 407 \r
 408   C Prototype: extern void x_hide_splitscreen(void);\r
 409 \r
 410 \r
 411   This function hides an existing split screen by setting its starting\r
 412   scan line to the last physical screen scan line.\r
 413   "ScreenPhysicalHeight" is adjusted but the "SplitScreenScanLine" is not\r
 414   altered as it is required for restoring the split screen at a later stage.\r
 415 \r
 416   WARNING: Only to be used if SplitScrnLine has been previously called\r
 417            Disabled for mode 5-11 (320x400-376x564). The memory for\r
 418            the initial split screen is reserved and the size limitations\r
 419            of these modes means any change in the split screen scan line\r
 420            will encroach on the split screen ram\r
 421            Update: Now disabled for these modes\r
 422 \r
 423   See Also:\r
 424 \r
 425     What is a split screen ?\r
 426 \r
 427   x_show_splitscreen\r
 428   ------------------\r
 429 \r
 430   C Prototype: extern void x_show_splitscreen(void);\r
 431 \r
 432   Restores split screen start scan line to the initial split screen\r
 433   starting scan line as set by "SplitScrnScanLine".\r
 434   "ScreenPhysicalHeight" is adjusted.\r
 435 \r
 436   WARNING: Only to be used if SplitScrnLine has been previously called\r
 437            Disabled for mode 4-10 (320x400-376x564). The memory for\r
 438            the initial split screen is reserved and the size limitations\r
 439            of these modes means any change in the split screen scan line\r
 440            will encroach on the split screen ram\r
 441 \r
 442 \r
 443   x_adjust_splitscreen\r
 444   --------------------\r
 445 \r
 446   C Prototype: extern void x_adjust_splitscreen(WORD line);\r
 447 \r
 448   line - The scan line at which the split screen is to start.\r
 449 \r
 450   Sets the split screen start scan line to a new scan line. Valid scan lines\r
 451   are between the initial split screen starting scan line and the last\r
 452   physical screen scan line. "ScreenPhysicalHeight" is also adjusted.\r
 453 \r
 454   WARNING: Only to be used if SplitScrnLine has been previously called\r
 455            Disabled for mode 4-10 (320x400-376x564). The memory for\r
 456            the initial split screen is reserved and the size limitations\r
 457            of these modes means any change in the split screen scan line\r
 458            will encroach on the split screen ram\r
 459 \r
 460   x_set_start_addr\r
 461   ----------------\r
 462 \r
 463   C Prototype: extern void x_set_start_addr(WORD X,WORD Y);\r
 464 \r
 465     X,Y - coordinates of top left corner of physical screen within current\r
 466           virtual screen.\r
 467 \r
 468   Set Mode X non split screen physical start address within current virtual\r
 469   page.\r
 470 \r
 471   X must not exceed (Logical screen width - Physical screen width)\r
 472   ie "MaxScrollX" and Y must not exceed (Logical screen height -\r
 473   Physical screen height) ie "MaxScrollY"\r
 474 \r
 475   x_page_flip\r
 476   -----------\r
 477 \r
 478   C Prototype: extern void x_page_flip(WORD X,WORD Y);\r
 479 \r
 480     X,Y - coordinates of top left corner of physical screen within the\r
 481           the hidden virtual screen if double buffering is active, or\r
 482           the current virtual screen otherwise.\r
 483 \r
 484   Sets the physical screen start address within currently hidden virtual\r
 485   page and then flips pages. If double buffering is not active then this\r
 486   function is functionally equivalent to "x_set_start_addr".\r
 487 \r
 488   X must not exceed (Logical screen width - Physical screen width)\r
 489   ie "MaxScrollX" and Y must not exceed (Logical screen height -\r
 490   Physical screen height) ie "MaxScrollY"\r
 491 \r
 492   x_text_mode\r
 493   -----------\r
 494 \r
 495   C Prototype: extern void x_text_mode(void);\r
 496 \r
 497   Disables graphics mode.\r
 498 \r
 499   x_set_cliprect\r
 500   --------------\r
 501 \r
 502   C Prototype: extern void x_set_cliprect(WORD left,WORD top,WORD right,\r
 503                 WORD bottom);\r
 504 \r
 505   Defines the clipping rectangle for clipping versions of planar and video\r
 506   bitmap puts.\r
 507 \r
 508   NOTE: Compiled bitmaps cannot be clipped.\r
 509 \r
 510 \r
 511 --------------------------------------------------------------------------\r
 512 MODULE XPOINT\r
 513 --------------------------------------------------------------------------\r
 514 \r
 515   Point functions all MODE X 256 Color resolutions\r
 516 \r
 517   ASM SOURCES\r
 518 \r
 519     xpoint.asm xpoint.inc xlib.inc model.inc\r
 520 \r
 521   C HEADER FILE\r
 522 \r
 523    xpoint.h\r
 524 \r
 525   EXPORTED FUNCTIONS\r
 526 \r
 527   x_put_pix\r
 528   ---------\r
 529 \r
 530   C Prototype: extern void x_put_pix(WORD X,WORD Y,WORD PageOffset,\r
 531                                      WORD Color);\r
 532 \r
 533   Draw a point of specified colour at coordinates X,Y\r
 534   within the virtual page starting at offset PageOffset.\r
 535 \r
 536   x_get_pix\r
 537   ---------\r
 538 \r
 539   C Prototype: extern WORD x_get_pix(WORD X, WORD Y, WORD PageBase);\r
 540 \r
 541   Read a point of at coordinates X,Y within the virtual page starting\r
 542   at offset PageOffset.\r
 543 \r
 544 \r
 545 --------------------------------------------------------------------------\r
 546 MODULE XRECT\r
 547 --------------------------------------------------------------------------\r
 548 \r
 549   Screen rectangle display and manipulation functions\r
 550 \r
 551   ASM SOURCES\r
 552 \r
 553     xrect.asm xrect.inc xlib.inc model.inc\r
 554 \r
 555   C HEADER FILE\r
 556 \r
 557     xrect.h\r
 558 \r
 559 \r
 560   EXPORTED FUNCTIONS\r
 561 \r
 562   x_rect_pattern\r
 563   --------------\r
 564 \r
 565   C Prototype: extern void x_rect_pattern(WORD StartX, WORD StartY,\r
 566                                           WORD EndX, WORD EndY,\r
 567                                           WORD PageBase,BYTE far *Pattern);\r
 568 \r
 569   StartX,StartY - Coordinates of upper left hand corner of rectangle\r
 570   EndX,EndY     - Coordinates of lower right hand corner of rectangle\r
 571   PageBase      - Offset of virtual screen\r
 572   *Pattern      - Pointer to the user defined pattern (16 bytes)\r
 573 \r
 574 \r
 575   Mode X rectangle 4x4 pattern fill routine.\r
 576 \r
 577   Upper left corner of pattern is always aligned to a multiple-of-4\r
 578   row and column. Works on all VGAs. Uses approach of copying the\r
 579   pattern to off-screen display memory, then loading the latches with\r
 580   the pattern for each scan line and filling each scan line four\r
 581   pixels at a time. Fills up to but not including the column at EndX\r
 582   and the row at EndY. No clipping is performed.\r
 583 \r
 584   Based on code originally published in DDJ Mag by M. Abrash\r
 585 \r
 586   Warning the VGA memory locations PATTERN_BUFFER (A000:FFFc) to\r
 587   A000:FFFF are reserved for the pattern buffer\r
 588 \r
 589 \r
 590   See Also:\r
 591     Doctor Dobbs Journal references.\r
 592 \r
 593 \r
 594   x_rect_pattern_clipped\r
 595   ----------------------\r
 596 \r
 597   As above but clipped.\r
 598 \r
 599   x_rect_fill\r
 600   -----------\r
 601 \r
 602   C Prototype: extern void x_rect_fill(WORD StartX,WORD StartY,\r
 603                                        WORD EndX,WORD EndY,\r
 604                                        WORD PageBase,WORD color);\r
 605 \r
 606   StartX,StartY - Coordinates of upper left hand corner of rectangle\r
 607   EndX,EndY - Coordinates of lower right hand corner of rectangle\r
 608   PageBase - Offset of virtual screen\r
 609   Color -color to use for fill\r
 610 \r
 611   Mode X rectangle solid color fill routine.\r
 612   Based on code originally published in DDJ Mag by M. Abrash\r
 613 \r
 614   See Also:\r
 615     Doctor Dobbs Journal references.\r
 616 \r
 617   x_rect_fill_clipped\r
 618   -------------------\r
 619 \r
 620   as above but clipped.\r
 621 \r
 622 \r
 623   x_cp_vid_rect\r
 624   -------------\r
 625 \r
 626   C Prototype: extern void x_cp_vid_rect(WORD SourceStartX,WORD SourceStartY,\r
 627                           WORD SourceEndX,WORD SourceEndY,\r
 628                           WORD DestStartX,WORD DestStartY,\r
 629                           WORD SourcePageBase,WORD DestPageBase,\r
 630                           WORD SourceBitmapWidth,WORD DestBitmapWidth);\r
 631 \r
 632   StartX,StartY- Coordinates of upper left hand corner of source rectangle\r
 633   EndX,EndY    - Coordinates of lower right hand corner of source rectangle\r
 634   DestStartX,DestStartY - Coordinates of rectangle destination\r
 635   SourcePageBase        - source rectangle page offset\r
 636   DestPageBase          - destination rectangles page offset\r
 637   SourceBitmapWidth     - width of bitmap within the source virtual screen\r
 638                           containing the source rectangle\r
 639   DestBitmapWidth       - width of bitmap within the dest. virtual screen\r
 640                           containing the destination rectangle\r
 641 \r
 642   Mode X display memory to display memory copy\r
 643   routine. Left edge of source rectangle modulo 4 must equal left edge\r
 644   of destination rectangle modulo 4. Works on all VGAs. Uses approach\r
 645   of reading 4 pixels at a time from the source into the latches, then\r
 646   writing the latches to the destination. Copies up to but not\r
 647   including the column at SrcEndX and the row at SrcEndY. No\r
 648   clipping is performed. Results are not guaranteed if the source and\r
 649   destination overlap.\r
 650 \r
 651 \r
 652   Based on code originally published in DDJ Mag by M. Abrash\r
 653 \r
 654   See Also:\r
 655     Doctor Dobbs Journal references.\r
 656 \r
 657   x_shift_rect\r
 658   ------------\r
 659 \r
 660   C Prototype:\r
 661   extern void x_shift_rect (WORD SrcLeft, WORD SrcTop,\r
 662                         WORD SrcRight, WORD SrcBottom,\r
 663                         WORD DestLeft, WORD DestTop, WORD ScreenOffs);\r
 664 \r
 665   SrcLeft, SrcTop - Coordinates of upper left hand corner of rectangle\r
 666   SrcRight, SrcBottom - Coordinates of lower right hand corner of rectangle\r
 667   DestLeft, DestTop - Coordinates of upper left corner of destination\r
 668   ScreenOffs    - Offset of virtual screen\r
 669 \r
 670   This function copies a rectangle of VRAM onto another area of VRAM,\r
 671   even if the destination overlaps with the source.  It is designed\r
 672   for scrolling text up and down, and for moving large areas of screens\r
 673   around in tiling systems.  It rounds all horizontal coordinates to\r
 674   the nearest byte (4-column chunk) for the sake of speed.  This means\r
 675   that it can NOT perform smooth horizontal scrolling.  For that,\r
 676   either scroll the whole screen (minus the split screen), or copy\r
 677   smaller areas through system memory using the functions in the\r
 678   XPBITMAP module.\r
 679 \r
 680   SrcRight is rounded up, and the left edges are rounded down, to\r
 681   ensure that the pixels pointed to by the arguments are inside the\r
 682   the rectangle.  That is, SrcRight is treated as (SrcRight+3) >> 2,\r
 683   and SrcLeft as SrcLeft >> 2.\r
 684 \r
 685   The width of the rectangle in bytes (width in pixels / 4)\r
 686   cannot exceed 255.\r
 687 \r
 688 ---------------------------------------------------------------------------\r
 689 MODULE XPAL\r
 690 ---------------------------------------------------------------------------\r
 691 \r
 692     Palette functions for VGA 256 color modes.\r
 693 \r
 694     All the functions in this module operate on two variations of the\r
 695     pallete buffer, the raw and annotated buffers.\r
 696 \r
 697     All those functions ending in "raw" operate on the following palette\r
 698     structure:\r
 699 \r
 700        BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn\r
 701 \r
 702     No reference to the starting colour index or number of colours stored\r
 703     is contained in the structure.\r
 704 \r
 705     All those functions ending in "struc" operate on the following palette\r
 706     structure:\r
 707 \r
 708        BYTE:c,BYTE:n,BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn\r
 709 \r
 710     where c is the starting colour and n is the number of colours stored\r
 711 \r
 712 \r
 713     WARNING: There is no validity checking in these functions. The onus is\r
 714     on the user to supply valid parameters to the functions.\r
 715 \r
 716 \r
 717   ASM SOURCES\r
 718 \r
 719     xpal.asm xpal.inc xlib.inc model.inc\r
 720 \r
 721   C HEADER FILE:\r
 722 \r
 723     xpal.h\r
 724 \r
 725   EXPORTED FUNCTIONS\r
 726 \r
 727   x_get_pal_raw\r
 728   -------------\r
 729 \r
 730   C Prototype: extern void x_get_pal_raw(BYTE far * pal,WORD num_colrs,\r
 731                                          WORD start_index);\r
 732 \r
 733   Read DAC palette into raw buffer with interrupts disabled\r
 734   ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn\r
 735 \r
 736   WARNING: Memory for the palette buffers must all be pre-allocated.\r
 737 \r
 738   x_get_pal_struc\r
 739   ---------------\r
 740 \r
 741   C Prototype: extern void x_get_pal_struc(BYTE far * pal,WORD num_colrs,\r
 742                                               WORD start_index);\r
 743 \r
 744   Read DAC palette into annotated type buffer with interrupts disabled\r
 745   ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn\r
 746 \r
 747   WARNING: memory for the palette buffers must all be pre-allocated\r
 748 \r
 749   x_put_pal_raw\r
 750   -------------\r
 751 \r
 752   C Prototype: extern void x_put_pal_raw(BYTE far * pal,WORD num_colrs,\r
 753                                          WORD start_index);\r
 754 \r
 755   Write DAC palette from raw buffer with interrupts disabled\r
 756   ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn\r
 757 \r
 758   x_put_pal_struc\r
 759   --------------\r
 760 \r
 761   C Prototype: extern void x_put_pal_struc(BYTE far * pal);\r
 762 \r
 763   Write DAC palette from annotated type buffer with interrupts disabled\r
 764   ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn\r
 765 \r
 766   x_set_rgb\r
 767   ---------\r
 768 \r
 769   C Prototype: extern x_set_rgb(BYTE color,BYTE red_c,BYTE green_c,\r
 770                                BYTE blue_c);\r
 771 \r
 772   Set the RGB components of a vga color\r
 773 \r
 774   x_rot_pal_struc\r
 775   ---------------\r
 776 \r
 777   C Prototype: extern void x_rot_pal_struc(BYTE far * pal,WORD direction);\r
 778 \r
 779   Rotate annotated palette buffer entries. Direction 0 = backward,\r
 780   1 = forward.\r
 781 \r
 782   x_rot_pal_raw\r
 783   -------------\r
 784 \r
 785   C Prototype: extern x_rot_pal_raw(BYTE far * pal,WORD direction,\r
 786                                     WORD num_colrs);\r
 787 \r
 788   Rotate a raw palette buffer. Direction 0 = backward,\r
 789   1 = forward.\r
 790 \r
 791   x_put_contrast_pal_struc\r
 792   ------------------------\r
 793 \r
 794   C Prototype: extern  void x_put_contrast_pal_struc(BYTE far * pal,\r
 795                BYTE  intensity);\r
 796 \r
 797   Write DAC palette from annotated type buffer with specified intensity\r
 798   adjustment (ie palette entries are decremented where possible by\r
 799   "intensity" units).\r
 800 \r
 801   Designed for fading in or out a palette without using an intermediate\r
 802   working palette buffer ! (Slow but memory efficient ... OK for small\r
 803   pal strucs}\r
 804 \r
 805 \r
 806   x_transpose_pal_struc\r
 807   ---------------------\r
 808 \r
 809   C Prototype: extern void x_transpose_pal_struc(BYTE far * pal,\r
 810                                                  WORD StartColor);\r
 811 \r
 812   Write DAC palette from annotated type buffer with interrupts disabled\r
 813   starting at a new palette index.\r
 814 \r
 815 \r
 816   x_cpcontrast_pal_struc\r
 817   ----------------------\r
 818 \r
 819   C Prototype: extern WORD x_cpcontrast_pal_struc(BYTE far *src_pal,\r
 820                                 BYTE far *dest_pal,BYTE Intensity);\r
 821 \r
 822   Copy one annotated palette buffer to another making the intensity\r
 823   adjustment. Used in fading in and out fast and smoothly.\r
 824 \r
 825 ---------------------------------------------------------------------------\r
 826 MODULE XLINE\r
 827 ---------------------------------------------------------------------------\r
 828 \r
 829   Line Drawing functions.\r
 830 \r
 831   ASM SOURCES\r
 832 \r
 833     xline.asm xline.inc xlib.inc model.inc\r
 834 \r
 835   C HEADER FILE\r
 836 \r
 837     xline.h\r
 838 \r
 839   EXPORTED FUNCTIONS\r
 840 \r
 841   x_line\r
 842   ------\r
 843 \r
 844   C Prototype: extern void x_line(WORD x0,WORD y0,WORD x1,WORD y1,\r
 845                                   WORD color,WORD PageBase);\r
 846 \r
 847   Draw a line with the specified end points in the page starting at\r
 848   offset "PageBase".\r
 849 \r
 850   No Clipping is performed.\r
 851 \r
 852 ---------------------------------------------------------------------------\r
 853 MODULE XTEXT\r
 854 ---------------------------------------------------------------------------\r
 855 \r
 856   ASM SOURCES\r
 857 \r
 858     xtext.asm xtext.inc xlib.inc model.inc\r
 859 \r
 860   C HEADER FILE\r
 861 \r
 862     xtext.h\r
 863 \r
 864   MACROS\r
 865 \r
 866    FONT_8x8  0\r
 867    FONT_8x15 1\r
 868    FONT_USER 2\r
 869 \r
 870   EXPORTED VARIABLES\r
 871 \r
 872     NOTE: All variables are read only. I you modify them the results may\r
 873     be unpredictable.\r
 874 \r
 875     CharHeight - BYTE - Height of current inbuilt character set\r
 876 \r
 877     CharWidth  - BYTE - Width of current inbuilt character set\r
 878 \r
 879     FirstChar  - BYTE - First character of current inbuilt character set\r
 880 \r
 881     UserCharHeight - BYTE - Height of current user character set\r
 882 \r
 883     UserCharWidth - BYTE - Width of current user character set\r
 884 \r
 885     UserFirstCh - BYTE - First character of current user character set\r
 886 \r
 887 \r
 888   EXPORTED FUNCTIONS\r
 889 \r
 890   x_text_init\r
 891   -----------\r
 892 \r
 893   C Prototype: extern WORD x_text_init(void);\r
 894 \r
 895   Initializes the Mode X text driver and sets the default font (VGA ROM 8x8)\r
 896 \r
 897   x_set_font\r
 898   ----------\r
 899 \r
 900   C Prototype: extern void x_set_font(WORD FontId);\r
 901 \r
 902   Select the working font where 0 = VGA ROM 8x8, 1 = VGA ROM 8x14\r
 903   2 = User defined bitmapped font.\r
 904 \r
 905   WARNING: A user font must be registered before setting FontID 2\r
 906 \r
 907   See Also:\r
 908 \r
 909     Defines for this module\r
 910 \r
 911   x_register_userfont\r
 912   -------------------\r
 913 \r
 914   C Prototype: extern void x_register_userfont(char far *UserFontPtr);\r
 915 \r
 916 \r
 917   Register a user font for later selection. Only one user font can be\r
 918   registered at any given time. Registering a user font deregisters the\r
 919   previous user font. User fonts may be at most 8 pixels wide.\r
 920 \r
 921   USER FONT STRUCTURE\r
 922 \r
 923   Word:  ascii code of first char in font\r
 924   Byte:  Height of chars in font\r
 925   Byte:  Width of chars in font\r
 926   n*h*Byte: the font data where n = number of chars and h = height\r
 927           of chars\r
 928 \r
 929   WARNING: The onus is on the program to ensure that all characters\r
 930            drawn whilst this font is active, are within the range of\r
 931            characters defined.\r
 932 \r
 933   x_put_char\r
 934   ----------\r
 935 \r
 936   C Prototype: extern void x_put_char(char ch,WORD X,WORD Y,WORD PgOffs,\r
 937                                       WORD Color);\r
 938 \r
 939   Draw a text character at the specified location with the specified\r
 940   color.\r
 941 \r
 942   ch       -  char to draw\r
 943   x,y      -  screen coords at which to draw ch\r
 944   ScrnOffs -  Starting offset of page on whih to draw\r
 945   Color    -  Color of the text\r
 946 \r
 947   WARNING: InitTextDriver must be called before using this function\r
 948 \r
 949 \r
 950   **** NOTE ****\r
 951 \r
 952   The file "xprintf.c" implements a printf style formatted output function\r
 953 \r
 954   x_printf\r
 955   --------\r
 956 \r
 957   C Prototype: void x_printf(int x,int y,unsigned ScrnOffs,int color,\r
 958                char *ln,...);\r
 959 \r
 960   x,y      -  screen coords at which to draw ch\r
 961   ScrnOffs -  Starting offset of page on whih to draw\r
 962   Color    -  Color of the text\r
 963 \r
 964   Parameters beyond Color conform to the standard printf parameters.\r
 965 \r
 966   x_bgprintf\r
 967   ----------\r
 968 \r
 969   C Prototype: void x_bgprintf(int x,int y,unsigned ScrnOffs,int fgcolor,\r
 970                int bgcolor, char *ln,...);\r
 971 \r
 972   x,y      -  screen coords at which to draw ch\r
 973   ScrnOffs -  Starting offset of page on whih to draw\r
 974   fgcolor    -  Color of the text foreground\r
 975   bgcolor    -  Color of the text background\r
 976 \r
 977   Parameters beyond bgolor conform to the standard printf parameters.\r
 978 \r
 979 \r
 980   x_get_char_width\r
 981   ----------------\r
 982 \r
 983   C Prototype: unsigned int x_get_char_width(char ch)\r
 984 \r
 985   ch - character to get width of\r
 986 \r
 987 --------------------------------------------------------------------------\r
 988 MODULE XPBITMAP\r
 989 --------------------------------------------------------------------------\r
 990 \r
 991   This module implements a set of functions to operate on planar bitmaps.\r
 992   Planar bitmaps as used by these functions have the following structure:\r
 993 \r
 994   BYTE 0                 The bitmap width in bytes (4 pixel groups) range 1..255\r
 995   BYTE 1                 The bitmap height in rows range 1..255\r
 996   BYTE 2..n1             The plane 0 pixels width*height bytes\r
 997   BYTE n1..n2            The plane 1 pixels width*height bytes\r
 998   BYTE n2..n3            The plane 2 pixels width*height bytes\r
 999   BYTE n3..n4            The plane 3 pixels width*height bytes\r
1000 \r
1001   These functions provide the fastest possible bitmap blts from system ram to\r
1002   to video and further, the single bitmap is applicable to all pixel\r
1003   allignments. The masked functions do not need separate masks since all non\r
1004   zero pixels are considered to be masking pixels, hence if a pixel is 0 the\r
1005   corresponding screen destination pixel is left unchanged.\r
1006 \r
1007 \r
1008   ASM SOURCES\r
1009 \r
1010     xpbitmap.asm xpbitmap.inc xlib.inc model.inc\r
1011 \r
1012   C HEADER FILE\r
1013 \r
1014     xpbitmap.h\r
1015 \r
1016   EXPORT FUNCTIONS\r
1017 \r
1018   x_put_masked_pbm\r
1019   ----------------\r
1020 \r
1021   C Prototype: extern void x_put_masked_pbm(WORD X,WORD Y,WORD ScrnOffs,\r
1022                  BYTE far * Bitmap);\r
1023 \r
1024   Mask write a planar bitmap from system ram to video ram. All zero source\r
1025   bitmap bytes indicate destination byte to be left unchanged.\r
1026 \r
1027   Source Bitmap structure:\r
1028 \r
1029   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,\r
1030   Bitmap data (plane 2)..,Bitmap data (plane 3)..\r
1031 \r
1032   NOTE: width is in bytes ie lots of 4 pixels\r
1033 \r
1034   LIMITATIONS: No clipping is supported\r
1035                Only supports bitmaps with widths which are a multiple of\r
1036                4 pixels\r
1037 \r
1038   See Also: XBMTOOLS module for linear <-> planar bitmap conversion\r
1039      functions.\r
1040 \r
1041   x_put_pbm\r
1042   ---------\r
1043 \r
1044   C Prototype: extern void x_put_pbm(WORD X, WORD Y, WORD ScrnOffs,\r
1045                  BYTE far * Bitmap);\r
1046 \r
1047   Write a planar bitmap from system ram to video ram.\r
1048 \r
1049   Source Bitmap structure:\r
1050 \r
1051   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,\r
1052   Bitmap data (plane 2)..,Bitmap data (plane 3)..\r
1053 \r
1054   NOTE: width is in bytes ie lots of 4 pixels\r
1055 \r
1056   LIMITATIONS: No clipping is supported\r
1057                Only supports bitmaps with widths which are a multiple of\r
1058                4 pixels\r
1059 \r
1060 \r
1061   See Also: XBMTOOLS module for linear <-> planar bitmap conversion\r
1062      functions.\r
1063 \r
1064   x_get_pbm\r
1065   ---------\r
1066 \r
1067   C Prototype: extern void x_get_pbm(WORD X, WORD Y,BYTE Bw,BYTE Bh,\r
1068                WORD ScrnOffs, BYTE far * Bitmap);\r
1069 \r
1070   Read a planar bitmap to system ram from video ram.\r
1071 \r
1072   Source Bitmap structure:\r
1073 \r
1074   Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,\r
1075   Bitmap data (plane 2)..,Bitmap data (plane 3)..\r
1076 \r
1077   NOTE: width is in bytes ie lots of 4 pixels\r
1078 \r
1079   LIMITATIONS: No clipping is supported\r
1080                Only supports bitmaps with widths which are a multiple of\r
1081                4 pixels\r
1082 \r
1083 \r
1084   See Also: XBMTOOLS module for linear <-> planar bitmap conversion\r
1085      functions.\r
1086 \r
1087 --------------------------------------------------------------------------\r
1088 MODULE XPBMCLIP\r
1089 --------------------------------------------------------------------------\r
1090 \r
1091   This module implements a similar set of functions to operate on planar\r
1092   bitmaps as "XPBITMAP" but incorporates clipping to a user defined\r
1093   clipping rectangle (which is set by "x_set_cliprect" in module xmain).\r
1094 \r
1095   The planar bitmap format is identical to the above module\r
1096 \r
1097   There are three variations of the functions in XPBITMAP in this module\r
1098   identified by the three function name extensions: _clipx, _clipy _clipxy.\r
1099   Because speed is critical in games programming you do not want to be\r
1100   checking for clipping if not necessary thus for sprites that move only\r
1101   horizontally you would use the _clipx version of the put function,\r
1102   for sprites that move vertically you would use the _clipy version and for\r
1103   sprites that move both directions you would use the clipxy version.\r
1104   Keep in mind also that the clipping components of these functions assume\r
1105   that the clipping rectangle is equal to or larger than the size of the\r
1106   bitmap ie. if a bitmap is top clipped, it is assumed that the bitmap's\r
1107   bottom is not also clipped. Similarly with horizontal clipping.\r
1108 \r
1109   Note: performance in decreasing order is as follows.\r
1110         _clipy,_clipx,_clipxy with masked puts being slower than unmasked\r
1111         puts\r
1112 \r
1113   Horizontal clipping is performed to byte boundaries (4 pixels) rather than\r
1114   pixels. This allows for the fastest implementation of the functions. It is\r
1115   not such a handicap because for one, your screen width a multiple of 4\r
1116   pixels wide and  for most purposes it is the screen edges that form the\r
1117   clipping rectangle.\r
1118 \r
1119   Following is an example of setting a clipping rectangle to the logical\r
1120   screen edges:\r
1121 \r
1122   x_set_cliprect(0,0,ScrnLogicalByteWidth,ScrnLogicalHeight)\r
1123 \r
1124    NOTE: the functions now return a value;\r
1125       1 if clipped image is fully clipped (ie no portion of it\r
1126       appears on the screen) otherwise it returns 0\r
1127 \r
1128 \r
1129   ASM SOURCES\r
1130 \r
1131     xpbmclip.asm xpbmclip.inc xlib.inc model.inc\r
1132 \r
1133   C HEADER FILE\r
1134 \r
1135     xpbmclip.h\r
1136 \r
1137   EXPORT FUNCTIONS\r
1138 \r
1139   x_put_pbm_clipx\r
1140   ---------------\r
1141   x_put_pbm_clipy\r
1142   ---------------\r
1143   x_put_pbm_clipxy\r
1144   ----------------\r
1145   x_put_masked_pbm_clipx\r
1146   ----------------------\r
1147   x_put_masked_pbm_clipy\r
1148   ----------------------\r
1149   x_put_masked_pbm_clipxy\r
1150   -----------------------\r
1151 \r
1152   For a detailed description of parameters etc. see equivalent functions\r
1153   in module "XPBITMAP".\r
1154 \r
1155 \r
1156 --------------------------------------------------------------------------\r
1157 MODULE  XCBITMAP\r
1158 --------------------------------------------------------------------------\r
1159 \r
1160                                  XCBITMAP:\r
1161                The Care and Feeding of Compiled Masked Blits\r
1162                            by Matthew MacKenzie\r
1163 \r
1164 The XCBITMAP module of the Xlib library is made up of the files\r
1165 XCBITMAP.ASM, XCBITMAP.INC, and XCBITMAP.H.\r
1166 \r
1167 The XCBITMAP module is small, containing only three procedures:\r
1168   o  x_compile_bitmap compiles your bitmap into native code which writes\r
1169      to the VGA screen in an X mode.\r
1170   o  x_put_cbitmap converts X and Y coordinates into a location on the\r
1171      screen, sets up the necessary VGA registers, and executes the compiled\r
1172      bitmap as a subroutine.\r
1173   o  x_sizeof_cbitmap takes a planar bitmap and returns an integer equal to\r
1174      the size of the compiled bitmap which the planar bitmap would produce.\r
1175          It is essentially a lobotomized version of x_compile_bitmap, with all\r
1176      the code generation replaced with a size counter.\r
1177 \r
1178     x_compile_bitmap scans through a source bitmap and generates 8086\r
1179 instructions to plot every nonzero pixel.  It is designed to be used\r
1180 before the action begins rather than on-the-fly.  The compiled bitmap\r
1181 contains no branches, and no reference to the zero (transparent) pixels.\r
1182 Where two pixels are exactly four columns apart they are plotted with a\r
1183 single 16-bit store, and the VGA MAP_MASK register will be set at most\r
1184 four times.  As a result your bitmap may run several times faster than a\r
1185 traditional memory-to-VGA masked blit routine.\r
1186     There is no way to perform clipping on these bitmaps, or to plot a\r
1187 pixel of color zero.\r
1188         x_compile_bitmap works with bitmaps in the standard Xlib planar bitmap\r
1189 format.  On a time scale of 60 frames per second, it is actually relatively\r
1190 slow.  Since a compiled bitmap is relocatable you may just want to have it\r
1191 saved to disk, and not include the source bitmap in your program at all.\r
1192     The source bitmap format is an array of bytes, a little like this:\r
1193 \r
1194 char eye[] ={4, 7,  /* four byte columns across, seven rows tall */\r
1195            0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0, 0, 0, 0,\r
1196            0, 0, 9, 9, 1, 1, 1, 4, 4, 9, 9, 0, 0, 0, 0, 0,\r
1197            0, 9, 9, 1, 2, 0, 0, 4, 4, 1, 9, 9, 0, 0, 0, 0,\r
1198            9, 9, 9, 1, 0, 0, 0, 0, 1, 1, 9, 9, 9, 0, 0, 0,\r
1199            0, 9, 9, 1, 2, 0, 0, 2, 1, 1, 9, 9, 0, 0, 0, 0,\r
1200            0, 0, 9, 9, 1, 1, 1, 1, 1, 9, 9, 0, 0, 0, 0, 0,\r
1201            0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0, 0, 0, 0};\r
1202 \r
1203     This is actually a linear bitmap, which is the wrong format for\r
1204 compilation, but is easier on human eyes.  Use the module XBMTOOLS to\r
1205 convert linear bitmaps into planar bitmaps, and vice-versa.\r
1206     To compile this image for a mode 360 pixels (90 byte columns) across:\r
1207 \r
1208 char planar_eye[4*7 + 2];\r
1209 char far * EyeSize;\r
1210 \r
1211 (void) x_bm_to_pbm((char far *) eye, (char far *) planar_eye);\r
1212 EyeSize = x_sizeof_cbitmap((far char *) planar_eye);\r
1213 CompiledEye = farmalloc(EyeSize);\r
1214 (void) x_compile_bitmap(90, (far char *) planar_eye, CompiledEye);\r
1215 \r
1216     Notice that both buffers must exist beforehand.  Since x_compile_bitmap\r
1217 returns the size of the compiled code, in bytes, you can reallocate the\r
1218 bitmap immediately to the right size if using x_sizeof_xbitmap seems\r
1219 inconvenient (reallocation may even be faster, though using the function is\r
1220 cleaner).  The pointers are 32-bit because compiled bitmaps take so much\r
1221 space: they are at one end of the speed-versus-memory spectrum.  A good\r
1222 rule of thumb is to allocate (3.5 x buffer-height x buffer-width) + 25\r
1223 bytes (rounding up ;-), then pare your bitmap down when you find out how\r
1224 much space you've actually used.\r
1225         Since the compiled bitmap has to fit within one segment of memory, it\r
1226 cannot contain more than about 19,000 pixels.  This will not be a\r
1227 limitation for most sane programmers.  If you are not a sane programmer try\r
1228 splitting your huge, unwieldy image up into smaller parts -- you can use\r
1229 the same gigantic bitmap if you divide it into horizontal slices for\r
1230 compilation.  For that matter, dividing the source up that way will let\r
1231 you use a source bitmap large than 64K, which is an even sicker idea...\r
1232     Back to business.  A bitmap is compiled for only one width of screen.\r
1233 If you are using a logical screen larger than your physical screen, call\r
1234 the bitmap compiler with the logical width -- the important thing is the\r
1235 number of bytes per line.  Notice that you do not have to be in a graphics\r
1236 mode to use this routine.  This allows you to develop and compile bitmaps\r
1237 separately, with whatever utility programs you might cook up.\r
1238 \r
1239     The final function is x_put_cbitmap.  To plot our eye at (99,4), on\r
1240 the page which starts at location 0:\r
1241 x_put_cbitmap(99, 4, 0, CompiledEye);\r
1242         This function depends on the global variable ScrnLogicalByteWidth from\r
1243 the module XMAIN, which should be the same number as the column parameter\r
1244 you used to compile your bitmap.\r
1245     The XCBITMAP module supports memory-to-VGA blits only.  Xlib also\r
1246 includes non-masking routines which can quickly save and restore the\r
1247 background screen behind your bitmap, using fast string operations.\r
1248 \r
1249    This module is part of the Xlib package, and is in the public domain.\r
1250 If you write something which uses it, though, please send me a copy as a\r
1251 courtesy -- if for no other reason so I can tilt my chair back and reflect\r
1252 that it may have been worth the trouble after all.\r
1253 \r
1254 The included program DEMO2.C demonstrates the performance difference\r
1255 between planar bitmap masked blits and compiled bitmap blits.\r
1256 \r
1257 --------------------------------------------------------------------------\r
1258 MODULE XCOMPPBM\r
1259 --------------------------------------------------------------------------\r
1260 \r
1261 Identical to XCBITMAP except that the source bitmaps are the PBM form\r
1262 rather than LBM.\r
1263 \r
1264 FUNCTIONS\r
1265 \r
1266 x_compile_pbm\r
1267 -------------\r
1268 x_sizeof_cpbm\r
1269 -------------\r
1270 \r
1271 See XCBITMAP module\r
1272 \r
1273 --------------------------------------------------------------------------\r
1274 MODULE XVBITMAP\r
1275 --------------------------------------------------------------------------\r
1276 \r
1277 The XVBITMAP module implements yet another type of bitmap to complement\r
1278 planar and compiled bitmaps, VRAM based bitmaps. If a 4 cylinder car is\r
1279 analagous to planar bitmaps, that is thrifty on memory consumption but low\r
1280 performance and and a V8 is analagous to Compiled bitmaps, memory guzzlers\r
1281 that really fly, then VRAM based bitmaps are the 6 cylinder modest performers\r
1282 with acceptable memory consumption.\r
1283 \r
1284 To summarise their selling points, VBM's are moderately fast with fair memory\r
1285 consumption, and unlike compiled bitmaps, can be clipped. The disadvantages\r
1286 are that they are limited by the amount of free video ram and have a complex\r
1287 structure.\r
1288 \r
1289 The VRAM bitmap format is rather complex consisting of components stored in\r
1290 video ram and components in system ram working together. This complexity\r
1291 necessitates the existence of a creation function "x_make_vbm" which takes\r
1292 an input linear bitmap and generates the equivalent VBM (VRAM Bit Map).\r
1293 \r
1294 VBM structure:\r
1295 \r
1296       WORD  0   Size          Total size of this VBM structure in bytes\r
1297       WORD  1   ImageWidth    Width in bytes of the image (for all alignments)\r
1298       WORD  2   ImageHeight   Height in scan lines of the image\r
1299 \r
1300       WORD  3 Alignment 0  ImagePtr   Offset in VidRAM of this aligned image\r
1301    +--WORD  4              MaskPtr    Offset (within this structure's DS) of\r
1302    |   .                               alignment masks\r
1303    |   .\r
1304    |   .\r
1305    |  WORD  9 Alignment 3  ImagePtr   Offset in VidRAM of this aligned image\r
1306   +|--WORD 10              MaskPtr    Offset (within this structure's DS) of\r
1307   ||                                   alignment masks\r
1308   ||\r
1309   |+->BYTE 21 (WORD 11)                -------+-- Image masks for alignment 0\r
1310   |   .                                       |\r
1311   |   .                                       |\r
1312   |   BYTE  21 + ImageWidth*ImageHeight  -----+\r
1313   |\r
1314   |   .\r
1315   |   . (similaly for alignments 1 - 2 )\r
1316   |   .\r
1317   |\r
1318   +-->BYTE  21 + 3*ImageWidth*ImageHeight + 1-+-- Image masks for alignment 3\r
1319       .                                       |\r
1320       .                                       |\r
1321       BYTE  21 + 4*(ImageWidth*ImageHeight) --+\r
1322 \r
1323       .\r
1324       .\r
1325       << Similarly for alignments 2 and 3 >>\r
1326       .\r
1327       .\r
1328       BYTE 21 + 4*(ImageWidth*ImageHeight)\r
1329   -------------\r
1330 \r
1331   (And dont forget the corresponding data in video ram)\r
1332 \r
1333 You can see for yourself the complexity of this bitmap format. The image\r
1334 is stored in video ram in its 4 different alignments with pointers to these\r
1335 alignments in the VBM. Similarly there are 4 alignments of the corresponding\r
1336 masks within the VBM itself (towards the end). The mask bytes contain the\r
1337 plane settings for the corresponding video bytes so that one memory move can\r
1338 move up to 4 pixels at a time (depending on the mask settings) using the\r
1339 VGA's latches, theoretically giving you a 4x speed improvement over\r
1340 conventional blits like the ones implemented in "XPBITMAP". In actual fact\r
1341 its anywhere between 2 and 3 due to incurred overheads.\r
1342 \r
1343 These bitmaps are more difficult to store in files than PBM'S and CBM's but\r
1344 still posible with a bit of work, so do not dismiss these as too difficult\r
1345 to use. Consider all the bitmap formats carefully before deciding on which\r
1346 to use. There may even be situations that a careful application of all three\r
1347 types would be most effective ie. compiled bitmaps for Background tiles and\r
1348 the main game character (which never need clipping), VRAM based bitmaps for\r
1349 the most frequently occuring (oponent, alien etc) characters which get\r
1350 clipped as they come into and leave your current location and planar bitmaps\r
1351 for smaller or less frequently encountered characters.\r
1352 \r
1353 ASM SOURCES\r
1354 \r
1355     xvbitmap.asm xvbitmap.inc xlib.inc model.inc\r
1356     xmakevbm.c  - Additional C module implementing creation function\r
1357 \r
1358   C HEADER FILE\r
1359 \r
1360     xvbitmap.h\r
1361 \r
1362   EXPORTED FUNCTIONS\r
1363 \r
1364   x_make_vbm\r
1365   ----------\r
1366 \r
1367   C Prototype: extern char far * x_make_vbm(char far *lbm, WORD *VramStart);\r
1368 \r
1369   Create the VBM from the given linear bitmap and place the image alignments\r
1370   in video ram starting at the offset in the variable pointed to by\r
1371   "VramStart". "VramStart" is then updated to point to the next free VRAM byte\r
1372   (just after the last byte of the image alignments). Usually you will point\r
1373   "VramStart" to "NonVisual_Offs".\r
1374 \r
1375    lbm         Pointer to the input linear bitmap\r
1376    VramStart   Pointer to variable containing Offset of first free VRAM byte\r
1377 \r
1378    x_put_masked_vbm\r
1379    ----------------\r
1380 \r
1381    C Prototype: extern int x_put_masked_vbm(int X, int Y, WORD ScrnOffs,\r
1382               BYTE far * VBitmap);\r
1383 \r
1384    Draw a VRAM based bitmap at (X,Y) relative to the screen with starting\r
1385    offset "ScrnOffs".\r
1386 \r
1387    Returns 1 if clipped image is fully clipped (ie no portion of it\r
1388    appears on the screen) otherwise it returns 0\r
1389 \r
1390    x_put_masked_vbm_clipx\r
1391    ----------------------\r
1392    x_put_masked_vbm_clipy\r
1393    ----------------------\r
1394    x_put_masked_vbm_clipxy\r
1395    -----------------------\r
1396 \r
1397      Clipping versions of "x_put_masked_vbm".\r
1398 \r
1399    See XPBMCLIP for more details on the type of clipping used as it is\r
1400    identical to XVBITMAP.\r
1401 \r
1402 --------------------------------------------------------------------------\r
1403 MODULE  XMOUSE\r
1404 --------------------------------------------------------------------------\r
1405 The XMOUSE module implements very basic mouse handling functions. The way\r
1406 in which it operates is by installing an event handler function during\r
1407 initialization which subsequently intercepts and processes mouse events and\r
1408 automatically updates status variables such as mouse position and button\r
1409 pressed status. It does not support the full functionality of:\r
1410 \r
1411   SPLIT SCREENS\r
1412   SCROLLED WINDOWS\r
1413   VIRTUAL WINDOWS\r
1414 \r
1415 This was done to primarily prevent unecessary impedences to performance,\r
1416 since the mouse handler function has the potential to degrade performance.\r
1417 It also saves me alot of coding which I was too lazy to do.\r
1418 \r
1419 Programs communicate with the mouse driver as with other devices, through\r
1420 an interrupt vector namely 33h. On generating an interrupt, the mouse driver\r
1421 expects a function number in AX and possibly other parameters in other\r
1422 registers and returns information via the registers. A brief description\r
1423 of the mouse functions follows:\r
1424 \r
1425               --------------------------------------\r
1426 \r
1427               MS Mouse Driver Functions\r
1428 \r
1429               Mouse Initialization                 0\r
1430               Show Cursor                          1\r
1431               Hide Cursor                          2\r
1432               Get Mouse Position & Button Status   3\r
1433               Set Mouse Cursor Position            4\r
1434               Get Button Press Information         5\r
1435               Get Button Release Information       6\r
1436               Set Min/Max Horizontal Position      7\r
1437               Set Min/Max Vertical Position        8\r
1438               Define Graphics Cursor Block         9\r
1439               Define Text Cursor                  10\r
1440               Read Mouse Motion Counters          11\r
1441               Define Event Handler                12\r
1442               Light Pen Emulation Mode ON         13\r
1443               Light Pen Emulation Mode OFF        14\r
1444               Set Mouse Mickey/Pixel Ratio        15\r
1445               Conditional Hide Cursor             16\r
1446               Set Double-Speed Threshold          19\r
1447               --------------------------------------\r
1448 \r
1449 In practice only afew of these functions are used and even fewer when the\r
1450 mouse status is monitored by an event handler function such as is used in\r
1451 this module.\r
1452 \r
1453 The most important thing to note when using the mouse module is that the\r
1454 mouse event handler must be removed before exiting the program. It is a good\r
1455 idea to have an exit function (see the C "atexit" function) and include the\r
1456 line "x_mouse_remove();" along with any other pre-exit cleanup code.\r
1457 \r
1458 \r
1459   ASM SOURCES\r
1460 \r
1461     xmouse.asm xlib.inc model.inc\r
1462 \r
1463   C HEADER FILE\r
1464 \r
1465     xmouse.h\r
1466 \r
1467   EXPORTED VARIABLES\r
1468 \r
1469    MouseInstalled    - WORD - Indicates whether mouse handler installed\r
1470    MouseHidden       - WORD - Indicates whether mouse cursor is hidden\r
1471    MouseButtonStatus - WORD - Holds the mouse button status\r
1472    MouseX            - WORD - Current X position of mouse cursor\r
1473    MouseY            - WORD - Current Y position of mouse cursor\r
1474    MouseFrozen       - WORD - Disallows position updates if TRUE\r
1475    MouseColor        - BYTE - The mouse cursors colour\r
1476 \r
1477   EXPORTED FUNCTIONS\r
1478 \r
1479   x_mouse_init\r
1480   ------------\r
1481 \r
1482     C Prototype:  int x_mouse_init()\r
1483 \r
1484   Initialize the mouse driver functions and install the mouse event handler\r
1485   function. This is the first function you must call before using any of the\r
1486   mouse functions. This mouse code uses the fastest possible techniques to\r
1487   save and restore mouse backgrounds and to draw the mouse cursor.\r
1488 \r
1489   WARNING: This function uses and updates "NonVisual_Offset" to allocate\r
1490            video ram for the saved mouse background.\r
1491 \r
1492   LIMITATIONS: No clipping is supported horizontally for the mouse cursor\r
1493                No validity checking is performed for NonVisual_Offs\r
1494 \r
1495   **WARNING** You must Hide or at least Freeze the mouse cursor while drawing\r
1496               using any of the other XLIB modules since the mouse handler may\r
1497               modify vga register settings at any time. VGA register settings\r
1498               are not preserved which will result in unpredictable drawing\r
1499               behavior. If you know the drawing will occur away from the\r
1500               mouse cursor set MouseFrozen to TRUE (1), do your drawing\r
1501               then set it to FALSE (0). Alternatively call "x_hide_mouse",\r
1502               perform your drawing and then call "x_show_mouse". Another\r
1503               alternative is to disable interrupts while drawing but usually\r
1504               drawing takes up alot of time and having interrupts disabled\r
1505               for too long is not a good idea.\r
1506 \r
1507   x_define_mouse_cursor\r
1508   ---------------------\r
1509 \r
1510   C Prototype:\r
1511     void x_define_mouse_cursor(char far *MouseDef, unsigned char MouseColor)\r
1512 \r
1513     MouseDef - a pointer to 14 characters containing a bitmask for all the\r
1514                cursor's rows.\r
1515     MouseColor - The colour to use when drawing the mouse cursor.\r
1516 \r
1517   Define a mouse cursor shape for use in subsequent cursor redraws. XMouse\r
1518   has a hardwired mouse cursor size of 8 pixels across by 14 pixels down.\r
1519 \r
1520   WARNING: This function assumes MouseDef points to 14 bytes.\r
1521 \r
1522   Note: Bit order is in reverse. ie bit 7 represents pixel 0 ..\r
1523         bit 0 represents pixel 7 in each "MouseDef" byte.\r
1524 \r
1525   x_show_mouse\r
1526   ------------\r
1527 \r
1528   C Prototype:  void x_show_mouse()\r
1529 \r
1530   Makes the cursor visible if it was previously hidden.\r
1531   See Also: "x_hide_mouse".\r
1532 \r
1533   x_hide_mouse\r
1534   ------------\r
1535 \r
1536   C Prototype:  void x_hide_mouse()\r
1537 \r
1538   Makes the cursor hidden if it was previously visible.\r
1539   See Also: "x_show_mouse".\r
1540 \r
1541   x_mouse_remove\r
1542   --------------\r
1543 \r
1544   C Prototype:  void x_mouse_remove()\r
1545 \r
1546   Stop mouse event handling and remove the mouse handler.\r
1547 \r
1548   NOTE: This function MUST be called before quitting the program if\r
1549        a mouse handler has been installed\r
1550 \r
1551   x_position_mouse\r
1552   ----------------\r
1553 \r
1554   C Prototype  void x_position_mouse(int x, int y)\r
1555 \r
1556   Positions the mouse cursor at the specified location\r
1557 \r
1558   x_mouse_window\r
1559   ------------\r
1560 \r
1561   C Prototype:  void x_mouse_window(int x0, int y0, int x1, int y1)\r
1562 \r
1563   Defines a mouse window.\r
1564 \r
1565   x_update_mouse\r
1566   --------------\r
1567 \r
1568   C Prototype:  void x_update_mouse()\r
1569 \r
1570   Forces the mouse position to be updated and cursor to be redrawn.\r
1571   Note: this function is useful when you have set "MouseFrozen" to true.\r
1572   Allows the cursor position to be updated manually rather than\r
1573   automatically by the installed handler.\r
1574 \r
1575 \r
1576 --------------------------------------------------------------------------\r
1577 MODULE XBMTOOLS\r
1578 --------------------------------------------------------------------------\r
1579 \r
1580   This module implements a set of functions to convert between planar\r
1581   bitmaps and linear bitmaps.\r
1582 \r
1583   PLANAR BITMAPS\r
1584 \r
1585   Planar bitmaps as used by these functions have the following structure:\r
1586 \r
1587   BYTE 0                 The bitmap width in bytes (4 pixel groups) range 1..255\r
1588   BYTE 1                 The bitmap height in rows range 1..255\r
1589   BYTE 2..n1             The plane 0 pixels width*height bytes\r
1590   BYTE n1..n2            The plane 1 pixels width*height bytes\r
1591   BYTE n2..n3            The plane 2 pixels width*height bytes\r
1592   BYTE n3..n4            The plane 3 pixels width*height bytes\r
1593 \r
1594   as used by x_put_pbm, x_get_pbm, x_put_masked_pbm.\r
1595 \r
1596   LINEAR BITMAPS\r
1597 \r
1598   Linear bitmaps have the following structure:\r
1599 \r
1600   BYTE 0                 The bitmap width in pixels  range 1..255\r
1601   BYTE 1                 The bitmap height in rows   range 1..255\r
1602   BYTE 2..n              The width*height bytes of the bitmap\r
1603 \r
1604   ASM SOURCES\r
1605 \r
1606     xbmtools.asm xpbmtools.inc model.inc\r
1607 \r
1608   C HEADER FILE\r
1609 \r
1610     xbmtools.h\r
1611 \r
1612   MACROS\r
1613 \r
1614     BM_WIDTH_ERROR\r
1615 \r
1616     LBMHeight(lbitmap)         - Height of linear bitmap "lbitmap"\r
1617     LBMWidth(lbitmap)          - Width of linear bitmap  "lbitmap"\r
1618     PBMHeight(pbitmap)         - Height of planar bitmap "pbitmap"\r
1619     PBMWidth(pbitmap)          - Width of planar bitmap "pbitmap"\r
1620 \r
1621     LBMPutPix(x,y,lbitmap,color)  - set pixel (x,y) colour in linear bitmap\r
1622     LBMGetPix(x,y,lbitmap)        - colour of pixel (x,y) in linear bitmap\r
1623 \r
1624   EXPORT FUNCTIONS\r
1625 \r
1626   x_pbm_to_bm\r
1627   ------------\r
1628   C Prototype:  extern int x_pbm_to_bm(char far * source_pbm,\r
1629                                        char far * dest_bm);\r
1630 \r
1631   This function converts a bitmap in the planar format to the linear format\r
1632   as used by x_compile_bitmap.\r
1633 \r
1634   WARNING: the source and destination bitmaps must be pre - allocated\r
1635 \r
1636   NOTE: This function can only convert planar bitmaps that are suitable.\r
1637         If the source planar bitmap's width (per plane) is >= 256/4\r
1638         it cannot be converted. In this situation an error code\r
1639         BM_WIDTH_ERROR. On successful conversion 0 is returned.\r
1640 \r
1641   x_bm_to_pbm\r
1642   ------------\r
1643   C Prototype:  extern int x_bm_to_pbm(char far * source_pbm,\r
1644                                        char far * dest_bm);\r
1645 \r
1646   This function converts a bitmap in the linear format as used by\r
1647   x_compile_bitmap to the planar formap.\r
1648 \r
1649   WARNING: the source and destination bitmaps must be pre - allocated\r
1650 \r
1651   NOTE: This function can only convert linear bitmaps that are suitable.\r
1652         If the source linear bitmap's width is not a multiple of 4\r
1653         it cannot be converted. In this situation an error code\r
1654         BM_WIDTH_ERROR. On successful conversion 0 is returned.\r
1655 \r