--- /dev/null
+PART 1 of 2\r
+-----------------------------------------------------------------------------\r
+\r
+ ********* XLIB - Mode X graphics library ****************\r
+ ********* ****************\r
+ ********* Written By Themie Gouthas ****************\r
+ ********* ****************\r
+ ********* egg@dstos3.dsto.gov.au ****************\r
+ ********* teg@bart.dsto.gov.au ****************\r
+\r
+ Some of the code in this library has been contributed by :\r
+\r
+ Matthew MacKenzie - matm@eng.umd.edu\r
+\r
+ and others. See individual modules.\r
+\r
+ I informally reserve all rights to the code in XLIB\r
+ Rights to contributed code is also assumed to be reserved by\r
+ the original authors.\r
+-----------------------------------------------------------------------------\r
+\r
+DISCLAIMER\r
+\r
+ This library is distributed AS IS. The author/s specifically disclaim\r
+ any responsibility for any loss of profit or any incidental, consequen-\r
+ tial or other damages.\r
+\r
+---------------------------------------------------------------------------\r
+INTRODUCTION\r
+---------------------------------------------------------------------------\r
+\r
+XLIB is a "user supported freeware" graphics library specifically designed\r
+with game programming in mind.\r
+\r
+It has been placed in the public domain for the benefit of all, and\r
+represents *MANY* hours of work so it is requested that all users comply\r
+with the the wishes of the author/s as specified in the individual modules\r
+and:\r
+a) To leave the code in the public domain\r
+b) Not distribute any modified or incomplete versions of this library\r
+\r
+New contribution and comments are welcome and hopefully there will be\r
+more releases as the code evolves.\r
+\r
+Finally, do not trust this excuse for a manual if in doubt, as this code has\r
+undergone several revisions. The place to get the answers is in the code\r
+itself.\r
+\r
+REQUIREMENTS\r
+\r
+Minimum requirements\r
+ 286 processor,\r
+ Turbo C 2.0 or higher, or BORLANDC\r
+ MAKE 2.0 or higher\r
+ TLIB 2.0 or higher\r
+ Turbo Assembler 1.01 or higher\r
+\r
+\r
+GENERAL FEATURES\r
+\r
+ Support for a number of 256 colour tweaked graphics mode resolutions\r
+ 320x200 320x240 360x200 360x240 376x282 320x400 320x480 360x400 360x480\r
+ 360x360 376x308 376x564\r
+\r
+ Please note that some of the new resolutions best suit monitors with\r
+ adjustable vertical height.\r
+\r
+ Virtual screens larger than the physical screen (memory\r
+ permitting) that can be panned at pixel resolution in all directions\r
+\r
+ A split screen capability for status displays etc.\r
+\r
+ Text functions supporting 8x8 and 8x14 ROM fonts and user defined fonts\r
+\r
+ Support for page flipping\r
+\r
+ Graphics primitives such as line and rectangle drawing functions and\r
+ of course bit block manipulation functions\r
+\r
+MODULES COMPRISING XLIB\r
+ XMAIN - Main module containig mode setting code and basic functions\r
+ XPOINT - Pixel functions\r
+ XRECT - Filled Rectangle and VRAM to VRAM block move functions\r
+ XPAL - Palette functions\r
+ XLINE - Line Functions\r
+ XTEXT - Text and Font Functions\r
+ XPRINTF - Printf style string output\r
+ XPBITMAP - Planar Bitmap functions\r
+ XCBITMAP - Compiled Bitmap functions\r
+ XVBITMAP - Video Bitmap functions\r
+ XPBMCLIP - Clipped Planar Bitmap functions\r
+ XMAKEVBM - Support module for video bitmaps\r
+ XBMTOOLS - Bitmap format conversion tools\r
+ XDETECT - Hardware detection module\r
+ XFILEIO - File I/O functions\r
+ XRLETOOL - RLE encoding/decoding functions\r
+ XMOUSE - Mouse functions\r
+ XBEZIER - Bezier curve drawing\r
+\r
+-------------------------------------------------------------------------\r
+BUILDING THE LIBRARIES\r
+-------------------------------------------------------------------------\r
+\r
+Building the library had been made simple through the use of make.\r
+\r
+To build and examples for one of the two models:\r
+\r
+a) edit the makefile for the apropriate model (see note in the makefile)\r
+b) edit the makefile for the apropriate compiler (again see note in the\r
+ makefile)\r
+c) type "make" at the dos prompt.\r
+\r
+It should be as simple as that. If problems are encountered then check\r
+to see if tasm, make, tlib, link and bcc (or tcc) are withinin your path.\r
+If not either change your path or specify the full path for these programs\r
+in the makefile. It is preferrable to have your path set correctly.\r
+\r
+Individual Compilation\r
+----------------------\r
+\r
+each ASM module can be compiled with the following commandline:\r
+\r
+tasm /ml /d<model> <asm module name>\r
+\r
+where <model> is s c or l. Where s = small model, c = compact model and\r
+l = large model.\r
+\r
+The resulting libraries are:\r
+\r
+ xlib<version>s.lib - small model library\r
+ xlib<version>c.lib - large model library\r
+ xlib<version>l.lib - large model library\r
+\r
+To link the library with your programs just include the apropriate .lib\r
+file in your project file or on the BCC or TCC command line.\r
+\r
+Using the library with your programs\r
+------------------------------------\r
+\r
+Using the XLIB library in your programs is simple. Knowing the particular\r
+modules you require, just include the associated header files in your program\r
+and link your program modules with the library. If you don't want to wory\r
+about selecting the apropriate header file then just include "XLIB_ALL.H"\r
+which automatically includes all XLIB header files in your program.\r
+\r
+For example compilations see the supplied makefile.\r
+\r
+--------------------------------------------------------------------------\r
+GLOBAL DEFINES (xlib.inc)\r
+--------------------------------------------------------------------------\r
+\r
+Types\r
+\r
+ BYTE unsigned char\r
+ WORD unsigned int\r
+\r
+Available X mode resolutions\r
+\r
+ X_MODE_320x200 0\r
+ X_MODE_320x240 1\r
+ X_MODE_360x200 2\r
+ X_MODE_360x240 3\r
+ X_MODE_360x282 4\r
+ X_MODE_320x400 5\r
+ X_MODE_320x480 6\r
+ X_MODE_360x400 7\r
+ X_MODE_360x480 8\r
+ X_MODE_360x360 9\r
+ X_MODE_376x308 10\r
+ X_MODE_376x564 11\r
+\r
+Palette rotation direction directiion\r
+\r
+ BACKWARD 0\r
+ FORWARD 1\r
+\r
+\r
+ X_MODE_INVALID -1\r
+ ERROR 1\r
+ OK 0\r
+\r
+\r
+--------------------------------------------------------------------------\r
+MODULE XMAIN\r
+--------------------------------------------------------------------------\r
+\r
+The Xmain module is the base module of the XLIB library. It contains the\r
+essential functions that initialize and customize the graphic environment.\r
+\r
+\r
+ASM SOURCES\r
+\r
+ xmain.asm xmain.inc xlib.inc model.inc\r
+\r
+C HEADER FILE\r
+\r
+ xlib.h\r
+\r
+EXPORTED VARIABLES\r
+\r
+ NOTE: All variables are read only unless otherwise specified. If you modify\r
+ them manually, the results may be unpredictable.\r
+\r
+ InGraphics - BYTE - Flag indicating that the xlib graphics system is\r
+ active. Set by function "x_set_mode".\r
+\r
+ CurrXMode - WORD - If the xlib graphics system is active, contains the id\r
+ of the x mode. Set by function "x_set_mode".\r
+ See also defines (ie X_MODE_320x200 ... )\r
+\r
+ ScrnPhysicalByteWidth - WORD - Physical screen width in bytes. Set by\r
+ function "x_set_mode"\r
+\r
+ ScrnPhysicalPixelWidth - WORD - Physical screen width in pixels. Set by\r
+ function "x_set_mode"\r
+\r
+ ScrnPhysicalHeight - WORD - Physical screen height in pixels. Set by\r
+ function "x_set_mode".\r
+\r
+ ErrorValue - WORD - Contains error value. General use variable to\r
+ communicate the error status from several functions. The value\r
+ in this variable usually is only valid for the the last\r
+ function called that sets it.\r
+\r
+ SplitScrnOffs - WORD - Offset in video ram of split screen. Set by\r
+ function "x_set_splitscrn". The value is only valid if a split\r
+ screen is active. See also global variable "SplitScrnActive".\r
+\r
+ SplitScrnScanLine - WORD - Screen Scan Line the Split Screen starts at\r
+ initially when set by function "x_set_splitscrn". The value is only\r
+ valid if a split screen is active. See also global variable\r
+ "SplitScrnActive".This variable is not updated by "x_hide_splitscrn",\r
+ "x_adjust_splitscrn".\r
+\r
+ SplitScrnVisibleHeight - WORD - The number of rows of the initial split\r
+ screen which are currently displayed. Modified by "x_hide_splitscrn",\r
+ "x_adjust_splitscrn" and "x_show_splitscrn".\r
+\r
+ Page0_Offs - WORD - Offset in video ram of main virtual screen. Initially\r
+ set by function "x_set_mode" but is updated by functions\r
+ "x_set_splitscrn" and "x_set_doublebuffer".\r
+\r
+ Page1_Offs - WORD - Offset in video ram of second virtual screen. Set by\r
+ and only is valid after a call to "x_set_doublebuffer".\r
+\r
+ ScrnLogicalByteWidth - WORD - Virtual screen width in bytes. Set by\r
+ function "x_set_mode".\r
+\r
+ ScrnLogicalPixelWidth - WORD - Virtual screen width in pixels. Set\r
+ by function "x_set_mode".\r
+\r
+ ScrnLogicalHeight - WORD - Virtual screen height in pixels. Set\r
+ initially by function "x_set_mode" but is updated by functions\r
+ "x_set_splitscrn" and "x_set_doublebuffer".\r
+\r
+ MaxScrollX - WORD - Max X pixel position of physical screen within\r
+ virtual screen. Set by function "x_set_mode".\r
+\r
+ MaxScrollY - WORD - Max Y position of physical screen within virtual\r
+ screen. Set initially by function "x_set_mode" but is updated by\r
+ functions "x_set_splitscrn" and "x_set_doublebuffer".\r
+\r
+ DoubleBufferActive - WORD - Indicates whether double-buffering is on. Set\r
+ by function "x_set_doublebuffer".\r
+\r
+ VisiblePageIdx - WORD - Index number of current visible page. Initially\r
+ set by function "x_set_doublebuffer" but is updated by "x_page_flip".\r
+ This variable is only used while double buffering is on.\r
+\r
+ HiddenPageOffs - WORD - Offset of hidden page. Initially set by function\r
+ "x_set_doublebuffer" but is updated by "x_page_flip". This variable\r
+ is only used while double buffering is on.\r
+\r
+ VisiblePageOffs - WORD - Offset of visible page. Initially set by function\r
+ "x_set_doublebuffer" but is updated by "x_page_flip". This variable\r
+ is only used while double buffering is on.\r
+\r
+ NonVisual_Offs - WORD - Offset of first byte of non-visual ram, the ram\r
+ that is available for bitmap storage etc. Set initially by function\r
+ "x_set_mode" but is updated by functions "x_set_splitscrn" and\r
+ "x_set_doublebuffer".\r
+\r
+ TopClip, BottomClip, LeftClip RightClip - WORD - Define the clipping\r
+ rectangle for Linear and Video clipped bitmap put functions. Set\r
+ either manually or by "x_set_cliprect". Note X coordinates are in\r
+ bytes as all clip functions clip to byte boundaries.\r
+\r
+ PhysicalStartPixelX - WORD - X pixel Offset of physical (visible) screen\r
+ relative to the upper left hand corner (0,0) of the virtual screen.\r
+\r
+ PhysicalStartByteX - WORD - X byte Offset of physical (visible) screen\r
+ relative to the upper left hand corner (0,0) of the virtual screen.\r
+\r
+ PhysicalStartY - WORD - Y pixel Offset of physical (visible) screen\r
+ relative to the upper left hand corner (0,0) of the virtual screen.\r
+\r
+EXPORTED FUNCTIONS\r
+\r
+ x_set_mode\r
+ ----------\r
+ C Prototype: extern WORD x_set_mode(WORD mode,WORD WidthInPixels);\r
+\r
+ mode - The required mode as defined by the "Available X Mode\r
+ resolutions" set of defines in the xlib.h header file.\r
+ WidthInPixels - The required virtual screen width.\r
+ Returns - The actual width in pixels of the allocated virtual\r
+ screen\r
+\r
+ This function initialises the graphics system, setting the apropriate\r
+ screen resolution and allocating a virtual screen. The virtual screen\r
+ allocated may not necessarily be of the same size as specified in the\r
+ "WidthInPixels" parameter as it is rounded down to the nearest\r
+ multiple of 4.\r
+\r
+ The function returns the actual width of the allocated virtual screen\r
+ in pixels if a valid mode was selected otherwise returns\r
+ X_MODE_INVALID.\r
+\r
+ Saves virtual screen pixel width in "ScrnLogicalPixelWidth".\r
+ Saves virtual screen byte width in "ScrnLogicalByteWidth".\r
+ Physical screen dimensions are set in "ScrnPhysicalPixelWidth".\r
+ "ScrnPhysicalByteWidth" and "ScrnPhysicalHeight". Other global\r
+ variables set are "CurrXMode","MaxScrollX", "MaxScrollY",\r
+ "InGraphics". The variable "SplitScrnScanline" is also initialized\r
+ to zero.\r
+\r
+ See also:\r
+ Available X Mode resolutions\r
+ What is Mode X\r
+\r
+ x_select_default_plane\r
+ ----------------------\r
+\r
+ C Prototype: void x_select_default_plane(BYTE plane);\r
+\r
+ Enables default Read/Write access to a specified plane\r
+\r
+\r
+ x_set_splitscreen\r
+ -----------------\r
+\r
+ C Prototype: extern void x_set_splitscreen(WORD line);\r
+\r
+ line - The starting scan line of the required split screen.\r
+\r
+ This function activates Mode X split screen and sets starting scan\r
+ line. The split screen resides on the bottom half of the screen and has\r
+ a starting address of A000:0000 in video RAM.\r
+\r
+ It also Updates Page0_Offs to reflect the existence of the split screen\r
+ region ie "MainScrnOffset" is set to the offset of the first pixel\r
+ beyond the split screen region. Other variable set are "Page1_Offs" which\r
+ is set to the same value as "Page0_Offs" (see graphics call sequence\r
+ below), "ScrnLogicalHeight","ScrnPhysicalHeight", "SplitScrnScanLine" and\r
+ "MaxScrollY".\r
+\r
+ This function cannot be called after double buffering has been activated,\r
+ it will return an error. To configure your graphics environment the\r
+ sequence of graphics calls is as follows although either or both steps b\r
+ and c may be omitted:\r
+ a) x_set_mode\r
+ b) x_set_splitscreen\r
+ c) x_set_doublebuffer\r
+ Thus when you call this function successfully, double buffering is not\r
+ active so "Page1_Offs" is set to the same address as "Page0_Offs".\r
+\r
+ WARNING: If you use one of the high resolution modes (376x564 as an\r
+ extreme example) you may not have enough video ram for split screen\r
+ and double buffering options since VGA video RAM is restricted to\r
+ 64K.\r
+\r
+ See Also:\r
+ What is a Split Screen ?\r
+ What is double buffering ?\r
+\r
+ x_set_doublebuffer\r
+ ------------------\r
+\r
+ C Prototype: extern WORD x_set_doublebuffer(WORD PageHeight);\r
+\r
+ PageHeight - The height of the two double buffering virtual screens.\r
+ Returns - The closest possible height to the specified.\r
+\r
+ This function sets up two double buffering virtual pages. 'ErrorValue"\r
+ is set according to the success or failure of this command.\r
+\r
+ Other variables set are:\r
+\r
+ _Page1_Offs Offset of second virtual page\r
+ _NonVisual_Offs Offset of first non visible video ram byte\r
+ _DoubleBufferActive Flag\r
+ _PageAddrTable Table of Double buffering pages start offsets\r
+ _ScrnLogicalHeight Logical height of the double buffering pages\r
+ _MaxScrollY Max vertical start address of physical screen\r
+ within the virtual screen\r
+\r
+ WARNING: If you use one of the high resolution modes (376x564 as an\r
+ extreme example) you may not have enough video ram for split screen\r
+ and double buffering options since VGA video RAM is restricted to\r
+ 64K.\r
+\r
+ See Also:\r
+ What is double buffering ?\r
+\r
+ x_hide_splitscreen\r
+ ------------------\r
+\r
+ C Prototype: extern void x_hide_splitscreen(void);\r
+\r
+\r
+ This function hides an existing split screen by setting its starting\r
+ scan line to the last physical screen scan line.\r
+ "ScreenPhysicalHeight" is adjusted but the "SplitScreenScanLine" is not\r
+ altered as it is required for restoring the split screen at a later stage.\r
+\r
+ WARNING: Only to be used if SplitScrnLine has been previously called\r
+ Disabled for mode 5-11 (320x400-376x564). The memory for\r
+ the initial split screen is reserved and the size limitations\r
+ of these modes means any change in the split screen scan line\r
+ will encroach on the split screen ram\r
+ Update: Now disabled for these modes\r
+\r
+ See Also:\r
+\r
+ What is a split screen ?\r
+\r
+ x_show_splitscreen\r
+ ------------------\r
+\r
+ C Prototype: extern void x_show_splitscreen(void);\r
+\r
+ Restores split screen start scan line to the initial split screen\r
+ starting scan line as set by "SplitScrnScanLine".\r
+ "ScreenPhysicalHeight" is adjusted.\r
+\r
+ WARNING: Only to be used if SplitScrnLine has been previously called\r
+ Disabled for mode 4-10 (320x400-376x564). The memory for\r
+ the initial split screen is reserved and the size limitations\r
+ of these modes means any change in the split screen scan line\r
+ will encroach on the split screen ram\r
+\r
+\r
+ x_adjust_splitscreen\r
+ --------------------\r
+\r
+ C Prototype: extern void x_adjust_splitscreen(WORD line);\r
+\r
+ line - The scan line at which the split screen is to start.\r
+\r
+ Sets the split screen start scan line to a new scan line. Valid scan lines\r
+ are between the initial split screen starting scan line and the last\r
+ physical screen scan line. "ScreenPhysicalHeight" is also adjusted.\r
+\r
+ WARNING: Only to be used if SplitScrnLine has been previously called\r
+ Disabled for mode 4-10 (320x400-376x564). The memory for\r
+ the initial split screen is reserved and the size limitations\r
+ of these modes means any change in the split screen scan line\r
+ will encroach on the split screen ram\r
+\r
+ x_set_start_addr\r
+ ----------------\r
+\r
+ C Prototype: extern void x_set_start_addr(WORD X,WORD Y);\r
+\r
+ X,Y - coordinates of top left corner of physical screen within current\r
+ virtual screen.\r
+\r
+ Set Mode X non split screen physical start address within current virtual\r
+ page.\r
+\r
+ X must not exceed (Logical screen width - Physical screen width)\r
+ ie "MaxScrollX" and Y must not exceed (Logical screen height -\r
+ Physical screen height) ie "MaxScrollY"\r
+\r
+ x_page_flip\r
+ -----------\r
+\r
+ C Prototype: extern void x_page_flip(WORD X,WORD Y);\r
+\r
+ X,Y - coordinates of top left corner of physical screen within the\r
+ the hidden virtual screen if double buffering is active, or\r
+ the current virtual screen otherwise.\r
+\r
+ Sets the physical screen start address within currently hidden virtual\r
+ page and then flips pages. If double buffering is not active then this\r
+ function is functionally equivalent to "x_set_start_addr".\r
+\r
+ X must not exceed (Logical screen width - Physical screen width)\r
+ ie "MaxScrollX" and Y must not exceed (Logical screen height -\r
+ Physical screen height) ie "MaxScrollY"\r
+\r
+ x_text_mode\r
+ -----------\r
+\r
+ C Prototype: extern void x_text_mode(void);\r
+\r
+ Disables graphics mode.\r
+\r
+ x_set_cliprect\r
+ --------------\r
+\r
+ C Prototype: extern void x_set_cliprect(WORD left,WORD top,WORD right,\r
+ WORD bottom);\r
+\r
+ Defines the clipping rectangle for clipping versions of planar and video\r
+ bitmap puts.\r
+\r
+ NOTE: Compiled bitmaps cannot be clipped.\r
+\r
+\r
+--------------------------------------------------------------------------\r
+MODULE XPOINT\r
+--------------------------------------------------------------------------\r
+\r
+ Point functions all MODE X 256 Color resolutions\r
+\r
+ ASM SOURCES\r
+\r
+ xpoint.asm xpoint.inc xlib.inc model.inc\r
+\r
+ C HEADER FILE\r
+\r
+ xpoint.h\r
+\r
+ EXPORTED FUNCTIONS\r
+\r
+ x_put_pix\r
+ ---------\r
+\r
+ C Prototype: extern void x_put_pix(WORD X,WORD Y,WORD PageOffset,\r
+ WORD Color);\r
+\r
+ Draw a point of specified colour at coordinates X,Y\r
+ within the virtual page starting at offset PageOffset.\r
+\r
+ x_get_pix\r
+ ---------\r
+\r
+ C Prototype: extern WORD x_get_pix(WORD X, WORD Y, WORD PageBase);\r
+\r
+ Read a point of at coordinates X,Y within the virtual page starting\r
+ at offset PageOffset.\r
+\r
+\r
+--------------------------------------------------------------------------\r
+MODULE XRECT\r
+--------------------------------------------------------------------------\r
+\r
+ Screen rectangle display and manipulation functions\r
+\r
+ ASM SOURCES\r
+\r
+ xrect.asm xrect.inc xlib.inc model.inc\r
+\r
+ C HEADER FILE\r
+\r
+ xrect.h\r
+\r
+\r
+ EXPORTED FUNCTIONS\r
+\r
+ x_rect_pattern\r
+ --------------\r
+\r
+ C Prototype: extern void x_rect_pattern(WORD StartX, WORD StartY,\r
+ WORD EndX, WORD EndY,\r
+ WORD PageBase,BYTE far *Pattern);\r
+\r
+ StartX,StartY - Coordinates of upper left hand corner of rectangle\r
+ EndX,EndY - Coordinates of lower right hand corner of rectangle\r
+ PageBase - Offset of virtual screen\r
+ *Pattern - Pointer to the user defined pattern (16 bytes)\r
+\r
+\r
+ Mode X rectangle 4x4 pattern fill routine.\r
+\r
+ Upper left corner of pattern is always aligned to a multiple-of-4\r
+ row and column. Works on all VGAs. Uses approach of copying the\r
+ pattern to off-screen display memory, then loading the latches with\r
+ the pattern for each scan line and filling each scan line four\r
+ pixels at a time. Fills up to but not including the column at EndX\r
+ and the row at EndY. No clipping is performed.\r
+\r
+ Based on code originally published in DDJ Mag by M. Abrash\r
+\r
+ Warning the VGA memory locations PATTERN_BUFFER (A000:FFFc) to\r
+ A000:FFFF are reserved for the pattern buffer\r
+\r
+\r
+ See Also:\r
+ Doctor Dobbs Journal references.\r
+\r
+\r
+ x_rect_pattern_clipped\r
+ ----------------------\r
+\r
+ As above but clipped.\r
+\r
+ x_rect_fill\r
+ -----------\r
+\r
+ C Prototype: extern void x_rect_fill(WORD StartX,WORD StartY,\r
+ WORD EndX,WORD EndY,\r
+ WORD PageBase,WORD color);\r
+\r
+ StartX,StartY - Coordinates of upper left hand corner of rectangle\r
+ EndX,EndY - Coordinates of lower right hand corner of rectangle\r
+ PageBase - Offset of virtual screen\r
+ Color -color to use for fill\r
+\r
+ Mode X rectangle solid color fill routine.\r
+ Based on code originally published in DDJ Mag by M. Abrash\r
+\r
+ See Also:\r
+ Doctor Dobbs Journal references.\r
+\r
+ x_rect_fill_clipped\r
+ -------------------\r
+\r
+ as above but clipped.\r
+\r
+\r
+ x_cp_vid_rect\r
+ -------------\r
+\r
+ C Prototype: extern void x_cp_vid_rect(WORD SourceStartX,WORD SourceStartY,\r
+ WORD SourceEndX,WORD SourceEndY,\r
+ WORD DestStartX,WORD DestStartY,\r
+ WORD SourcePageBase,WORD DestPageBase,\r
+ WORD SourceBitmapWidth,WORD DestBitmapWidth);\r
+\r
+ StartX,StartY- Coordinates of upper left hand corner of source rectangle\r
+ EndX,EndY - Coordinates of lower right hand corner of source rectangle\r
+ DestStartX,DestStartY - Coordinates of rectangle destination\r
+ SourcePageBase - source rectangle page offset\r
+ DestPageBase - destination rectangles page offset\r
+ SourceBitmapWidth - width of bitmap within the source virtual screen\r
+ containing the source rectangle\r
+ DestBitmapWidth - width of bitmap within the dest. virtual screen\r
+ containing the destination rectangle\r
+\r
+ Mode X display memory to display memory copy\r
+ routine. Left edge of source rectangle modulo 4 must equal left edge\r
+ of destination rectangle modulo 4. Works on all VGAs. Uses approach\r
+ of reading 4 pixels at a time from the source into the latches, then\r
+ writing the latches to the destination. Copies up to but not\r
+ including the column at SrcEndX and the row at SrcEndY. No\r
+ clipping is performed. Results are not guaranteed if the source and\r
+ destination overlap.\r
+\r
+\r
+ Based on code originally published in DDJ Mag by M. Abrash\r
+\r
+ See Also:\r
+ Doctor Dobbs Journal references.\r
+\r
+ x_shift_rect\r
+ ------------\r
+\r
+ C Prototype:\r
+ extern void x_shift_rect (WORD SrcLeft, WORD SrcTop,\r
+ WORD SrcRight, WORD SrcBottom,\r
+ WORD DestLeft, WORD DestTop, WORD ScreenOffs);\r
+\r
+ SrcLeft, SrcTop - Coordinates of upper left hand corner of rectangle\r
+ SrcRight, SrcBottom - Coordinates of lower right hand corner of rectangle\r
+ DestLeft, DestTop - Coordinates of upper left corner of destination\r
+ ScreenOffs - Offset of virtual screen\r
+\r
+ This function copies a rectangle of VRAM onto another area of VRAM,\r
+ even if the destination overlaps with the source. It is designed\r
+ for scrolling text up and down, and for moving large areas of screens\r
+ around in tiling systems. It rounds all horizontal coordinates to\r
+ the nearest byte (4-column chunk) for the sake of speed. This means\r
+ that it can NOT perform smooth horizontal scrolling. For that,\r
+ either scroll the whole screen (minus the split screen), or copy\r
+ smaller areas through system memory using the functions in the\r
+ XPBITMAP module.\r
+\r
+ SrcRight is rounded up, and the left edges are rounded down, to\r
+ ensure that the pixels pointed to by the arguments are inside the\r
+ the rectangle. That is, SrcRight is treated as (SrcRight+3) >> 2,\r
+ and SrcLeft as SrcLeft >> 2.\r
+\r
+ The width of the rectangle in bytes (width in pixels / 4)\r
+ cannot exceed 255.\r
+\r
+---------------------------------------------------------------------------\r
+MODULE XPAL\r
+---------------------------------------------------------------------------\r
+\r
+ Palette functions for VGA 256 color modes.\r
+\r
+ All the functions in this module operate on two variations of the\r
+ pallete buffer, the raw and annotated buffers.\r
+\r
+ All those functions ending in "raw" operate on the following palette\r
+ structure:\r
+\r
+ BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn\r
+\r
+ No reference to the starting colour index or number of colours stored\r
+ is contained in the structure.\r
+\r
+ All those functions ending in "struc" operate on the following palette\r
+ structure:\r
+\r
+ BYTE:c,BYTE:n,BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn\r
+\r
+ where c is the starting colour and n is the number of colours stored\r
+\r
+\r
+ WARNING: There is no validity checking in these functions. The onus is\r
+ on the user to supply valid parameters to the functions.\r
+\r
+\r
+ ASM SOURCES\r
+\r
+ xpal.asm xpal.inc xlib.inc model.inc\r
+\r
+ C HEADER FILE:\r
+\r
+ xpal.h\r
+\r
+ EXPORTED FUNCTIONS\r
+\r
+ x_get_pal_raw\r
+ -------------\r
+\r
+ C Prototype: extern void x_get_pal_raw(BYTE far * pal,WORD num_colrs,\r
+ WORD start_index);\r
+\r
+ Read DAC palette into raw buffer with interrupts disabled\r
+ ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn\r
+\r
+ WARNING: Memory for the palette buffers must all be pre-allocated.\r
+\r
+ x_get_pal_struc\r
+ ---------------\r
+\r
+ C Prototype: extern void x_get_pal_struc(BYTE far * pal,WORD num_colrs,\r
+ WORD start_index);\r
+\r
+ Read DAC palette into annotated type buffer with interrupts disabled\r
+ ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn\r
+\r
+ WARNING: memory for the palette buffers must all be pre-allocated\r
+\r
+ x_put_pal_raw\r
+ -------------\r
+\r
+ C Prototype: extern void x_put_pal_raw(BYTE far * pal,WORD num_colrs,\r
+ WORD start_index);\r
+\r
+ Write DAC palette from raw buffer with interrupts disabled\r
+ ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn\r
+\r
+ x_put_pal_struc\r
+ --------------\r
+\r
+ C Prototype: extern void x_put_pal_struc(BYTE far * pal);\r
+\r
+ Write DAC palette from annotated type buffer with interrupts disabled\r
+ ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn\r
+\r
+ x_set_rgb\r
+ ---------\r
+\r
+ C Prototype: extern x_set_rgb(BYTE color,BYTE red_c,BYTE green_c,\r
+ BYTE blue_c);\r
+\r
+ Set the RGB components of a vga color\r
+\r
+ x_rot_pal_struc\r
+ ---------------\r
+\r
+ C Prototype: extern void x_rot_pal_struc(BYTE far * pal,WORD direction);\r
+\r
+ Rotate annotated palette buffer entries. Direction 0 = backward,\r
+ 1 = forward.\r
+\r
+ x_rot_pal_raw\r
+ -------------\r
+\r
+ C Prototype: extern x_rot_pal_raw(BYTE far * pal,WORD direction,\r
+ WORD num_colrs);\r
+\r
+ Rotate a raw palette buffer. Direction 0 = backward,\r
+ 1 = forward.\r
+\r
+ x_put_contrast_pal_struc\r
+ ------------------------\r
+\r
+ C Prototype: extern void x_put_contrast_pal_struc(BYTE far * pal,\r
+ BYTE intensity);\r
+\r
+ Write DAC palette from annotated type buffer with specified intensity\r
+ adjustment (ie palette entries are decremented where possible by\r
+ "intensity" units).\r
+\r
+ Designed for fading in or out a palette without using an intermediate\r
+ working palette buffer ! (Slow but memory efficient ... OK for small\r
+ pal strucs}\r
+\r
+\r
+ x_transpose_pal_struc\r
+ ---------------------\r
+\r
+ C Prototype: extern void x_transpose_pal_struc(BYTE far * pal,\r
+ WORD StartColor);\r
+\r
+ Write DAC palette from annotated type buffer with interrupts disabled\r
+ starting at a new palette index.\r
+\r
+\r
+ x_cpcontrast_pal_struc\r
+ ----------------------\r
+\r
+ C Prototype: extern WORD x_cpcontrast_pal_struc(BYTE far *src_pal,\r
+ BYTE far *dest_pal,BYTE Intensity);\r
+\r
+ Copy one annotated palette buffer to another making the intensity\r
+ adjustment. Used in fading in and out fast and smoothly.\r
+\r
+---------------------------------------------------------------------------\r
+MODULE XLINE\r
+---------------------------------------------------------------------------\r
+\r
+ Line Drawing functions.\r
+\r
+ ASM SOURCES\r
+\r
+ xline.asm xline.inc xlib.inc model.inc\r
+\r
+ C HEADER FILE\r
+\r
+ xline.h\r
+\r
+ EXPORTED FUNCTIONS\r
+\r
+ x_line\r
+ ------\r
+\r
+ C Prototype: extern void x_line(WORD x0,WORD y0,WORD x1,WORD y1,\r
+ WORD color,WORD PageBase);\r
+\r
+ Draw a line with the specified end points in the page starting at\r
+ offset "PageBase".\r
+\r
+ No Clipping is performed.\r
+\r
+---------------------------------------------------------------------------\r
+MODULE XTEXT\r
+---------------------------------------------------------------------------\r
+\r
+ ASM SOURCES\r
+\r
+ xtext.asm xtext.inc xlib.inc model.inc\r
+\r
+ C HEADER FILE\r
+\r
+ xtext.h\r
+\r
+ MACROS\r
+\r
+ FONT_8x8 0\r
+ FONT_8x15 1\r
+ FONT_USER 2\r
+\r
+ EXPORTED VARIABLES\r
+\r
+ NOTE: All variables are read only. I you modify them the results may\r
+ be unpredictable.\r
+\r
+ CharHeight - BYTE - Height of current inbuilt character set\r
+\r
+ CharWidth - BYTE - Width of current inbuilt character set\r
+\r
+ FirstChar - BYTE - First character of current inbuilt character set\r
+\r
+ UserCharHeight - BYTE - Height of current user character set\r
+\r
+ UserCharWidth - BYTE - Width of current user character set\r
+\r
+ UserFirstCh - BYTE - First character of current user character set\r
+\r
+\r
+ EXPORTED FUNCTIONS\r
+\r
+ x_text_init\r
+ -----------\r
+\r
+ C Prototype: extern WORD x_text_init(void);\r
+\r
+ Initializes the Mode X text driver and sets the default font (VGA ROM 8x8)\r
+\r
+ x_set_font\r
+ ----------\r
+\r
+ C Prototype: extern void x_set_font(WORD FontId);\r
+\r
+ Select the working font where 0 = VGA ROM 8x8, 1 = VGA ROM 8x14\r
+ 2 = User defined bitmapped font.\r
+\r
+ WARNING: A user font must be registered before setting FontID 2\r
+\r
+ See Also:\r
+\r
+ Defines for this module\r
+\r
+ x_register_userfont\r
+ -------------------\r
+\r
+ C Prototype: extern void x_register_userfont(char far *UserFontPtr);\r
+\r
+\r
+ Register a user font for later selection. Only one user font can be\r
+ registered at any given time. Registering a user font deregisters the\r
+ previous user font. User fonts may be at most 8 pixels wide.\r
+\r
+ USER FONT STRUCTURE\r
+\r
+ Word: ascii code of first char in font\r
+ Byte: Height of chars in font\r
+ Byte: Width of chars in font\r
+ n*h*Byte: the font data where n = number of chars and h = height\r
+ of chars\r
+\r
+ WARNING: The onus is on the program to ensure that all characters\r
+ drawn whilst this font is active, are within the range of\r
+ characters defined.\r
+\r
+ x_put_char\r
+ ----------\r
+\r
+ C Prototype: extern void x_put_char(char ch,WORD X,WORD Y,WORD PgOffs,\r
+ WORD Color);\r
+\r
+ Draw a text character at the specified location with the specified\r
+ color.\r
+\r
+ ch - char to draw\r
+ x,y - screen coords at which to draw ch\r
+ ScrnOffs - Starting offset of page on whih to draw\r
+ Color - Color of the text\r
+\r
+ WARNING: InitTextDriver must be called before using this function\r
+\r
+\r
+ **** NOTE ****\r
+\r
+ The file "xprintf.c" implements a printf style formatted output function\r
+\r
+ x_printf\r
+ --------\r
+\r
+ C Prototype: void x_printf(int x,int y,unsigned ScrnOffs,int color,\r
+ char *ln,...);\r
+\r
+ x,y - screen coords at which to draw ch\r
+ ScrnOffs - Starting offset of page on whih to draw\r
+ Color - Color of the text\r
+\r
+ Parameters beyond Color conform to the standard printf parameters.\r
+\r
+ x_bgprintf\r
+ ----------\r
+\r
+ C Prototype: void x_bgprintf(int x,int y,unsigned ScrnOffs,int fgcolor,\r
+ int bgcolor, char *ln,...);\r
+\r
+ x,y - screen coords at which to draw ch\r
+ ScrnOffs - Starting offset of page on whih to draw\r
+ fgcolor - Color of the text foreground\r
+ bgcolor - Color of the text background\r
+\r
+ Parameters beyond bgolor conform to the standard printf parameters.\r
+\r
+\r
+ x_get_char_width\r
+ ----------------\r
+\r
+ C Prototype: unsigned int x_get_char_width(char ch)\r
+\r
+ ch - character to get width of\r
+\r
+--------------------------------------------------------------------------\r
+MODULE XPBITMAP\r
+--------------------------------------------------------------------------\r
+\r
+ This module implements a set of functions to operate on planar bitmaps.\r
+ Planar bitmaps as used by these functions have the following structure:\r
+\r
+ BYTE 0 The bitmap width in bytes (4 pixel groups) range 1..255\r
+ BYTE 1 The bitmap height in rows range 1..255\r
+ BYTE 2..n1 The plane 0 pixels width*height bytes\r
+ BYTE n1..n2 The plane 1 pixels width*height bytes\r
+ BYTE n2..n3 The plane 2 pixels width*height bytes\r
+ BYTE n3..n4 The plane 3 pixels width*height bytes\r
+\r
+ These functions provide the fastest possible bitmap blts from system ram to\r
+ to video and further, the single bitmap is applicable to all pixel\r
+ allignments. The masked functions do not need separate masks since all non\r
+ zero pixels are considered to be masking pixels, hence if a pixel is 0 the\r
+ corresponding screen destination pixel is left unchanged.\r
+\r
+\r
+ ASM SOURCES\r
+\r
+ xpbitmap.asm xpbitmap.inc xlib.inc model.inc\r
+\r
+ C HEADER FILE\r
+\r
+ xpbitmap.h\r
+\r
+ EXPORT FUNCTIONS\r
+\r
+ x_put_masked_pbm\r
+ ----------------\r
+\r
+ C Prototype: extern void x_put_masked_pbm(WORD X,WORD Y,WORD ScrnOffs,\r
+ BYTE far * Bitmap);\r
+\r
+ Mask write a planar bitmap from system ram to video ram. All zero source\r
+ bitmap bytes indicate destination byte to be left unchanged.\r
+\r
+ Source Bitmap structure:\r
+\r
+ Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,\r
+ Bitmap data (plane 2)..,Bitmap data (plane 3)..\r
+\r
+ NOTE: width is in bytes ie lots of 4 pixels\r
+\r
+ LIMITATIONS: No clipping is supported\r
+ Only supports bitmaps with widths which are a multiple of\r
+ 4 pixels\r
+\r
+ See Also: XBMTOOLS module for linear <-> planar bitmap conversion\r
+ functions.\r
+\r
+ x_put_pbm\r
+ ---------\r
+\r
+ C Prototype: extern void x_put_pbm(WORD X, WORD Y, WORD ScrnOffs,\r
+ BYTE far * Bitmap);\r
+\r
+ Write a planar bitmap from system ram to video ram.\r
+\r
+ Source Bitmap structure:\r
+\r
+ Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,\r
+ Bitmap data (plane 2)..,Bitmap data (plane 3)..\r
+\r
+ NOTE: width is in bytes ie lots of 4 pixels\r
+\r
+ LIMITATIONS: No clipping is supported\r
+ Only supports bitmaps with widths which are a multiple of\r
+ 4 pixels\r
+\r
+\r
+ See Also: XBMTOOLS module for linear <-> planar bitmap conversion\r
+ functions.\r
+\r
+ x_get_pbm\r
+ ---------\r
+\r
+ C Prototype: extern void x_get_pbm(WORD X, WORD Y,BYTE Bw,BYTE Bh,\r
+ WORD ScrnOffs, BYTE far * Bitmap);\r
+\r
+ Read a planar bitmap to system ram from video ram.\r
+\r
+ Source Bitmap structure:\r
+\r
+ Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,\r
+ Bitmap data (plane 2)..,Bitmap data (plane 3)..\r
+\r
+ NOTE: width is in bytes ie lots of 4 pixels\r
+\r
+ LIMITATIONS: No clipping is supported\r
+ Only supports bitmaps with widths which are a multiple of\r
+ 4 pixels\r
+\r
+\r
+ See Also: XBMTOOLS module for linear <-> planar bitmap conversion\r
+ functions.\r
+\r
+--------------------------------------------------------------------------\r
+MODULE XPBMCLIP\r
+--------------------------------------------------------------------------\r
+\r
+ This module implements a similar set of functions to operate on planar\r
+ bitmaps as "XPBITMAP" but incorporates clipping to a user defined\r
+ clipping rectangle (which is set by "x_set_cliprect" in module xmain).\r
+\r
+ The planar bitmap format is identical to the above module\r
+\r
+ There are three variations of the functions in XPBITMAP in this module\r
+ identified by the three function name extensions: _clipx, _clipy _clipxy.\r
+ Because speed is critical in games programming you do not want to be\r
+ checking for clipping if not necessary thus for sprites that move only\r
+ horizontally you would use the _clipx version of the put function,\r
+ for sprites that move vertically you would use the _clipy version and for\r
+ sprites that move both directions you would use the clipxy version.\r
+ Keep in mind also that the clipping components of these functions assume\r
+ that the clipping rectangle is equal to or larger than the size of the\r
+ bitmap ie. if a bitmap is top clipped, it is assumed that the bitmap's\r
+ bottom is not also clipped. Similarly with horizontal clipping.\r
+\r
+ Note: performance in decreasing order is as follows.\r
+ _clipy,_clipx,_clipxy with masked puts being slower than unmasked\r
+ puts\r
+\r
+ Horizontal clipping is performed to byte boundaries (4 pixels) rather than\r
+ pixels. This allows for the fastest implementation of the functions. It is\r
+ not such a handicap because for one, your screen width a multiple of 4\r
+ pixels wide and for most purposes it is the screen edges that form the\r
+ clipping rectangle.\r
+\r
+ Following is an example of setting a clipping rectangle to the logical\r
+ screen edges:\r
+\r
+ x_set_cliprect(0,0,ScrnLogicalByteWidth,ScrnLogicalHeight)\r
+\r
+ NOTE: the functions now return a value;\r
+ 1 if clipped image is fully clipped (ie no portion of it\r
+ appears on the screen) otherwise it returns 0\r
+\r
+\r
+ ASM SOURCES\r
+\r
+ xpbmclip.asm xpbmclip.inc xlib.inc model.inc\r
+\r
+ C HEADER FILE\r
+\r
+ xpbmclip.h\r
+\r
+ EXPORT FUNCTIONS\r
+\r
+ x_put_pbm_clipx\r
+ ---------------\r
+ x_put_pbm_clipy\r
+ ---------------\r
+ x_put_pbm_clipxy\r
+ ----------------\r
+ x_put_masked_pbm_clipx\r
+ ----------------------\r
+ x_put_masked_pbm_clipy\r
+ ----------------------\r
+ x_put_masked_pbm_clipxy\r
+ -----------------------\r
+\r
+ For a detailed description of parameters etc. see equivalent functions\r
+ in module "XPBITMAP".\r
+\r
+\r
+--------------------------------------------------------------------------\r
+MODULE XCBITMAP\r
+--------------------------------------------------------------------------\r
+\r
+ XCBITMAP:\r
+ The Care and Feeding of Compiled Masked Blits\r
+ by Matthew MacKenzie\r
+\r
+The XCBITMAP module of the Xlib library is made up of the files\r
+XCBITMAP.ASM, XCBITMAP.INC, and XCBITMAP.H.\r
+\r
+The XCBITMAP module is small, containing only three procedures:\r
+ o x_compile_bitmap compiles your bitmap into native code which writes\r
+ to the VGA screen in an X mode.\r
+ o x_put_cbitmap converts X and Y coordinates into a location on the\r
+ screen, sets up the necessary VGA registers, and executes the compiled\r
+ bitmap as a subroutine.\r
+ o x_sizeof_cbitmap takes a planar bitmap and returns an integer equal to\r
+ the size of the compiled bitmap which the planar bitmap would produce.\r
+ It is essentially a lobotomized version of x_compile_bitmap, with all\r
+ the code generation replaced with a size counter.\r
+\r
+ x_compile_bitmap scans through a source bitmap and generates 8086\r
+instructions to plot every nonzero pixel. It is designed to be used\r
+before the action begins rather than on-the-fly. The compiled bitmap\r
+contains no branches, and no reference to the zero (transparent) pixels.\r
+Where two pixels are exactly four columns apart they are plotted with a\r
+single 16-bit store, and the VGA MAP_MASK register will be set at most\r
+four times. As a result your bitmap may run several times faster than a\r
+traditional memory-to-VGA masked blit routine.\r
+ There is no way to perform clipping on these bitmaps, or to plot a\r
+pixel of color zero.\r
+ x_compile_bitmap works with bitmaps in the standard Xlib planar bitmap\r
+format. On a time scale of 60 frames per second, it is actually relatively\r
+slow. Since a compiled bitmap is relocatable you may just want to have it\r
+saved to disk, and not include the source bitmap in your program at all.\r
+ The source bitmap format is an array of bytes, a little like this:\r
+\r
+char eye[] ={4, 7, /* four byte columns across, seven rows tall */\r
+ 0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0, 0, 0, 0,\r
+ 0, 0, 9, 9, 1, 1, 1, 4, 4, 9, 9, 0, 0, 0, 0, 0,\r
+ 0, 9, 9, 1, 2, 0, 0, 4, 4, 1, 9, 9, 0, 0, 0, 0,\r
+ 9, 9, 9, 1, 0, 0, 0, 0, 1, 1, 9, 9, 9, 0, 0, 0,\r
+ 0, 9, 9, 1, 2, 0, 0, 2, 1, 1, 9, 9, 0, 0, 0, 0,\r
+ 0, 0, 9, 9, 1, 1, 1, 1, 1, 9, 9, 0, 0, 0, 0, 0,\r
+ 0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0, 0, 0, 0};\r
+\r
+ This is actually a linear bitmap, which is the wrong format for\r
+compilation, but is easier on human eyes. Use the module XBMTOOLS to\r
+convert linear bitmaps into planar bitmaps, and vice-versa.\r
+ To compile this image for a mode 360 pixels (90 byte columns) across:\r
+\r
+char planar_eye[4*7 + 2];\r
+char far * EyeSize;\r
+\r
+(void) x_bm_to_pbm((char far *) eye, (char far *) planar_eye);\r
+EyeSize = x_sizeof_cbitmap((far char *) planar_eye);\r
+CompiledEye = farmalloc(EyeSize);\r
+(void) x_compile_bitmap(90, (far char *) planar_eye, CompiledEye);\r
+\r
+ Notice that both buffers must exist beforehand. Since x_compile_bitmap\r
+returns the size of the compiled code, in bytes, you can reallocate the\r
+bitmap immediately to the right size if using x_sizeof_xbitmap seems\r
+inconvenient (reallocation may even be faster, though using the function is\r
+cleaner). The pointers are 32-bit because compiled bitmaps take so much\r
+space: they are at one end of the speed-versus-memory spectrum. A good\r
+rule of thumb is to allocate (3.5 x buffer-height x buffer-width) + 25\r
+bytes (rounding up ;-), then pare your bitmap down when you find out how\r
+much space you've actually used.\r
+ Since the compiled bitmap has to fit within one segment of memory, it\r
+cannot contain more than about 19,000 pixels. This will not be a\r
+limitation for most sane programmers. If you are not a sane programmer try\r
+splitting your huge, unwieldy image up into smaller parts -- you can use\r
+the same gigantic bitmap if you divide it into horizontal slices for\r
+compilation. For that matter, dividing the source up that way will let\r
+you use a source bitmap large than 64K, which is an even sicker idea...\r
+ Back to business. A bitmap is compiled for only one width of screen.\r
+If you are using a logical screen larger than your physical screen, call\r
+the bitmap compiler with the logical width -- the important thing is the\r
+number of bytes per line. Notice that you do not have to be in a graphics\r
+mode to use this routine. This allows you to develop and compile bitmaps\r
+separately, with whatever utility programs you might cook up.\r
+\r
+ The final function is x_put_cbitmap. To plot our eye at (99,4), on\r
+the page which starts at location 0:\r
+x_put_cbitmap(99, 4, 0, CompiledEye);\r
+ This function depends on the global variable ScrnLogicalByteWidth from\r
+the module XMAIN, which should be the same number as the column parameter\r
+you used to compile your bitmap.\r
+ The XCBITMAP module supports memory-to-VGA blits only. Xlib also\r
+includes non-masking routines which can quickly save and restore the\r
+background screen behind your bitmap, using fast string operations.\r
+\r
+ This module is part of the Xlib package, and is in the public domain.\r
+If you write something which uses it, though, please send me a copy as a\r
+courtesy -- if for no other reason so I can tilt my chair back and reflect\r
+that it may have been worth the trouble after all.\r
+\r
+The included program DEMO2.C demonstrates the performance difference\r
+between planar bitmap masked blits and compiled bitmap blits.\r
+\r
+--------------------------------------------------------------------------\r
+MODULE XCOMPPBM\r
+--------------------------------------------------------------------------\r
+\r
+Identical to XCBITMAP except that the source bitmaps are the PBM form\r
+rather than LBM.\r
+\r
+FUNCTIONS\r
+\r
+x_compile_pbm\r
+-------------\r
+x_sizeof_cpbm\r
+-------------\r
+\r
+See XCBITMAP module\r
+\r
+--------------------------------------------------------------------------\r
+MODULE XVBITMAP\r
+--------------------------------------------------------------------------\r
+\r
+The XVBITMAP module implements yet another type of bitmap to complement\r
+planar and compiled bitmaps, VRAM based bitmaps. If a 4 cylinder car is\r
+analagous to planar bitmaps, that is thrifty on memory consumption but low\r
+performance and and a V8 is analagous to Compiled bitmaps, memory guzzlers\r
+that really fly, then VRAM based bitmaps are the 6 cylinder modest performers\r
+with acceptable memory consumption.\r
+\r
+To summarise their selling points, VBM's are moderately fast with fair memory\r
+consumption, and unlike compiled bitmaps, can be clipped. The disadvantages\r
+are that they are limited by the amount of free video ram and have a complex\r
+structure.\r
+\r
+The VRAM bitmap format is rather complex consisting of components stored in\r
+video ram and components in system ram working together. This complexity\r
+necessitates the existence of a creation function "x_make_vbm" which takes\r
+an input linear bitmap and generates the equivalent VBM (VRAM Bit Map).\r
+\r
+VBM structure:\r
+\r
+ WORD 0 Size Total size of this VBM structure in bytes\r
+ WORD 1 ImageWidth Width in bytes of the image (for all alignments)\r
+ WORD 2 ImageHeight Height in scan lines of the image\r
+\r
+ WORD 3 Alignment 0 ImagePtr Offset in VidRAM of this aligned image\r
+ +--WORD 4 MaskPtr Offset (within this structure's DS) of\r
+ | . alignment masks\r
+ | .\r
+ | .\r
+ | WORD 9 Alignment 3 ImagePtr Offset in VidRAM of this aligned image\r
+ +|--WORD 10 MaskPtr Offset (within this structure's DS) of\r
+ || alignment masks\r
+ ||\r
+ |+->BYTE 21 (WORD 11) -------+-- Image masks for alignment 0\r
+ | . |\r
+ | . |\r
+ | BYTE 21 + ImageWidth*ImageHeight -----+\r
+ |\r
+ | .\r
+ | . (similaly for alignments 1 - 2 )\r
+ | .\r
+ |\r
+ +-->BYTE 21 + 3*ImageWidth*ImageHeight + 1-+-- Image masks for alignment 3\r
+ . |\r
+ . |\r
+ BYTE 21 + 4*(ImageWidth*ImageHeight) --+\r
+\r
+ .\r
+ .\r
+ << Similarly for alignments 2 and 3 >>\r
+ .\r
+ .\r
+ BYTE 21 + 4*(ImageWidth*ImageHeight)\r
+ -------------\r
+\r
+ (And dont forget the corresponding data in video ram)\r
+\r
+You can see for yourself the complexity of this bitmap format. The image\r
+is stored in video ram in its 4 different alignments with pointers to these\r
+alignments in the VBM. Similarly there are 4 alignments of the corresponding\r
+masks within the VBM itself (towards the end). The mask bytes contain the\r
+plane settings for the corresponding video bytes so that one memory move can\r
+move up to 4 pixels at a time (depending on the mask settings) using the\r
+VGA's latches, theoretically giving you a 4x speed improvement over\r
+conventional blits like the ones implemented in "XPBITMAP". In actual fact\r
+its anywhere between 2 and 3 due to incurred overheads.\r
+\r
+These bitmaps are more difficult to store in files than PBM'S and CBM's but\r
+still posible with a bit of work, so do not dismiss these as too difficult\r
+to use. Consider all the bitmap formats carefully before deciding on which\r
+to use. There may even be situations that a careful application of all three\r
+types would be most effective ie. compiled bitmaps for Background tiles and\r
+the main game character (which never need clipping), VRAM based bitmaps for\r
+the most frequently occuring (oponent, alien etc) characters which get\r
+clipped as they come into and leave your current location and planar bitmaps\r
+for smaller or less frequently encountered characters.\r
+\r
+ASM SOURCES\r
+\r
+ xvbitmap.asm xvbitmap.inc xlib.inc model.inc\r
+ xmakevbm.c - Additional C module implementing creation function\r
+\r
+ C HEADER FILE\r
+\r
+ xvbitmap.h\r
+\r
+ EXPORTED FUNCTIONS\r
+\r
+ x_make_vbm\r
+ ----------\r
+\r
+ C Prototype: extern char far * x_make_vbm(char far *lbm, WORD *VramStart);\r
+\r
+ Create the VBM from the given linear bitmap and place the image alignments\r
+ in video ram starting at the offset in the variable pointed to by\r
+ "VramStart". "VramStart" is then updated to point to the next free VRAM byte\r
+ (just after the last byte of the image alignments). Usually you will point\r
+ "VramStart" to "NonVisual_Offs".\r
+\r
+ lbm Pointer to the input linear bitmap\r
+ VramStart Pointer to variable containing Offset of first free VRAM byte\r
+\r
+ x_put_masked_vbm\r
+ ----------------\r
+\r
+ C Prototype: extern int x_put_masked_vbm(int X, int Y, WORD ScrnOffs,\r
+ BYTE far * VBitmap);\r
+\r
+ Draw a VRAM based bitmap at (X,Y) relative to the screen with starting\r
+ offset "ScrnOffs".\r
+\r
+ Returns 1 if clipped image is fully clipped (ie no portion of it\r
+ appears on the screen) otherwise it returns 0\r
+\r
+ x_put_masked_vbm_clipx\r
+ ----------------------\r
+ x_put_masked_vbm_clipy\r
+ ----------------------\r
+ x_put_masked_vbm_clipxy\r
+ -----------------------\r
+\r
+ Clipping versions of "x_put_masked_vbm".\r
+\r
+ See XPBMCLIP for more details on the type of clipping used as it is\r
+ identical to XVBITMAP.\r
+\r
+--------------------------------------------------------------------------\r
+MODULE XMOUSE\r
+--------------------------------------------------------------------------\r
+The XMOUSE module implements very basic mouse handling functions. The way\r
+in which it operates is by installing an event handler function during\r
+initialization which subsequently intercepts and processes mouse events and\r
+automatically updates status variables such as mouse position and button\r
+pressed status. It does not support the full functionality of:\r
+\r
+ SPLIT SCREENS\r
+ SCROLLED WINDOWS\r
+ VIRTUAL WINDOWS\r
+\r
+This was done to primarily prevent unecessary impedences to performance,\r
+since the mouse handler function has the potential to degrade performance.\r
+It also saves me alot of coding which I was too lazy to do.\r
+\r
+Programs communicate with the mouse driver as with other devices, through\r
+an interrupt vector namely 33h. On generating an interrupt, the mouse driver\r
+expects a function number in AX and possibly other parameters in other\r
+registers and returns information via the registers. A brief description\r
+of the mouse functions follows:\r
+\r
+ --------------------------------------\r
+\r
+ MS Mouse Driver Functions\r
+\r
+ Mouse Initialization 0\r
+ Show Cursor 1\r
+ Hide Cursor 2\r
+ Get Mouse Position & Button Status 3\r
+ Set Mouse Cursor Position 4\r
+ Get Button Press Information 5\r
+ Get Button Release Information 6\r
+ Set Min/Max Horizontal Position 7\r
+ Set Min/Max Vertical Position 8\r
+ Define Graphics Cursor Block 9\r
+ Define Text Cursor 10\r
+ Read Mouse Motion Counters 11\r
+ Define Event Handler 12\r
+ Light Pen Emulation Mode ON 13\r
+ Light Pen Emulation Mode OFF 14\r
+ Set Mouse Mickey/Pixel Ratio 15\r
+ Conditional Hide Cursor 16\r
+ Set Double-Speed Threshold 19\r
+ --------------------------------------\r
+\r
+In practice only afew of these functions are used and even fewer when the\r
+mouse status is monitored by an event handler function such as is used in\r
+this module.\r
+\r
+The most important thing to note when using the mouse module is that the\r
+mouse event handler must be removed before exiting the program. It is a good\r
+idea to have an exit function (see the C "atexit" function) and include the\r
+line "x_mouse_remove();" along with any other pre-exit cleanup code.\r
+\r
+\r
+ ASM SOURCES\r
+\r
+ xmouse.asm xlib.inc model.inc\r
+\r
+ C HEADER FILE\r
+\r
+ xmouse.h\r
+\r
+ EXPORTED VARIABLES\r
+\r
+ MouseInstalled - WORD - Indicates whether mouse handler installed\r
+ MouseHidden - WORD - Indicates whether mouse cursor is hidden\r
+ MouseButtonStatus - WORD - Holds the mouse button status\r
+ MouseX - WORD - Current X position of mouse cursor\r
+ MouseY - WORD - Current Y position of mouse cursor\r
+ MouseFrozen - WORD - Disallows position updates if TRUE\r
+ MouseColor - BYTE - The mouse cursors colour\r
+\r
+ EXPORTED FUNCTIONS\r
+\r
+ x_mouse_init\r
+ ------------\r
+\r
+ C Prototype: int x_mouse_init()\r
+\r
+ Initialize the mouse driver functions and install the mouse event handler\r
+ function. This is the first function you must call before using any of the\r
+ mouse functions. This mouse code uses the fastest possible techniques to\r
+ save and restore mouse backgrounds and to draw the mouse cursor.\r
+\r
+ WARNING: This function uses and updates "NonVisual_Offset" to allocate\r
+ video ram for the saved mouse background.\r
+\r
+ LIMITATIONS: No clipping is supported horizontally for the mouse cursor\r
+ No validity checking is performed for NonVisual_Offs\r
+\r
+ **WARNING** You must Hide or at least Freeze the mouse cursor while drawing\r
+ using any of the other XLIB modules since the mouse handler may\r
+ modify vga register settings at any time. VGA register settings\r
+ are not preserved which will result in unpredictable drawing\r
+ behavior. If you know the drawing will occur away from the\r
+ mouse cursor set MouseFrozen to TRUE (1), do your drawing\r
+ then set it to FALSE (0). Alternatively call "x_hide_mouse",\r
+ perform your drawing and then call "x_show_mouse". Another\r
+ alternative is to disable interrupts while drawing but usually\r
+ drawing takes up alot of time and having interrupts disabled\r
+ for too long is not a good idea.\r
+\r
+ x_define_mouse_cursor\r
+ ---------------------\r
+\r
+ C Prototype:\r
+ void x_define_mouse_cursor(char far *MouseDef, unsigned char MouseColor)\r
+\r
+ MouseDef - a pointer to 14 characters containing a bitmask for all the\r
+ cursor's rows.\r
+ MouseColor - The colour to use when drawing the mouse cursor.\r
+\r
+ Define a mouse cursor shape for use in subsequent cursor redraws. XMouse\r
+ has a hardwired mouse cursor size of 8 pixels across by 14 pixels down.\r
+\r
+ WARNING: This function assumes MouseDef points to 14 bytes.\r
+\r
+ Note: Bit order is in reverse. ie bit 7 represents pixel 0 ..\r
+ bit 0 represents pixel 7 in each "MouseDef" byte.\r
+\r
+ x_show_mouse\r
+ ------------\r
+\r
+ C Prototype: void x_show_mouse()\r
+\r
+ Makes the cursor visible if it was previously hidden.\r
+ See Also: "x_hide_mouse".\r
+\r
+ x_hide_mouse\r
+ ------------\r
+\r
+ C Prototype: void x_hide_mouse()\r
+\r
+ Makes the cursor hidden if it was previously visible.\r
+ See Also: "x_show_mouse".\r
+\r
+ x_mouse_remove\r
+ --------------\r
+\r
+ C Prototype: void x_mouse_remove()\r
+\r
+ Stop mouse event handling and remove the mouse handler.\r
+\r
+ NOTE: This function MUST be called before quitting the program if\r
+ a mouse handler has been installed\r
+\r
+ x_position_mouse\r
+ ----------------\r
+\r
+ C Prototype void x_position_mouse(int x, int y)\r
+\r
+ Positions the mouse cursor at the specified location\r
+\r
+ x_mouse_window\r
+ ------------\r
+\r
+ C Prototype: void x_mouse_window(int x0, int y0, int x1, int y1)\r
+\r
+ Defines a mouse window.\r
+\r
+ x_update_mouse\r
+ --------------\r
+\r
+ C Prototype: void x_update_mouse()\r
+\r
+ Forces the mouse position to be updated and cursor to be redrawn.\r
+ Note: this function is useful when you have set "MouseFrozen" to true.\r
+ Allows the cursor position to be updated manually rather than\r
+ automatically by the installed handler.\r
+\r
+\r
+--------------------------------------------------------------------------\r
+MODULE XBMTOOLS\r
+--------------------------------------------------------------------------\r
+\r
+ This module implements a set of functions to convert between planar\r
+ bitmaps and linear bitmaps.\r
+\r
+ PLANAR BITMAPS\r
+\r
+ Planar bitmaps as used by these functions have the following structure:\r
+\r
+ BYTE 0 The bitmap width in bytes (4 pixel groups) range 1..255\r
+ BYTE 1 The bitmap height in rows range 1..255\r
+ BYTE 2..n1 The plane 0 pixels width*height bytes\r
+ BYTE n1..n2 The plane 1 pixels width*height bytes\r
+ BYTE n2..n3 The plane 2 pixels width*height bytes\r
+ BYTE n3..n4 The plane 3 pixels width*height bytes\r
+\r
+ as used by x_put_pbm, x_get_pbm, x_put_masked_pbm.\r
+\r
+ LINEAR BITMAPS\r
+\r
+ Linear bitmaps have the following structure:\r
+\r
+ BYTE 0 The bitmap width in pixels range 1..255\r
+ BYTE 1 The bitmap height in rows range 1..255\r
+ BYTE 2..n The width*height bytes of the bitmap\r
+\r
+ ASM SOURCES\r
+\r
+ xbmtools.asm xpbmtools.inc model.inc\r
+\r
+ C HEADER FILE\r
+\r
+ xbmtools.h\r
+\r
+ MACROS\r
+\r
+ BM_WIDTH_ERROR\r
+\r
+ LBMHeight(lbitmap) - Height of linear bitmap "lbitmap"\r
+ LBMWidth(lbitmap) - Width of linear bitmap "lbitmap"\r
+ PBMHeight(pbitmap) - Height of planar bitmap "pbitmap"\r
+ PBMWidth(pbitmap) - Width of planar bitmap "pbitmap"\r
+\r
+ LBMPutPix(x,y,lbitmap,color) - set pixel (x,y) colour in linear bitmap\r
+ LBMGetPix(x,y,lbitmap) - colour of pixel (x,y) in linear bitmap\r
+\r
+ EXPORT FUNCTIONS\r
+\r
+ x_pbm_to_bm\r
+ ------------\r
+ C Prototype: extern int x_pbm_to_bm(char far * source_pbm,\r
+ char far * dest_bm);\r
+\r
+ This function converts a bitmap in the planar format to the linear format\r
+ as used by x_compile_bitmap.\r
+\r
+ WARNING: the source and destination bitmaps must be pre - allocated\r
+\r
+ NOTE: This function can only convert planar bitmaps that are suitable.\r
+ If the source planar bitmap's width (per plane) is >= 256/4\r
+ it cannot be converted. In this situation an error code\r
+ BM_WIDTH_ERROR. On successful conversion 0 is returned.\r
+\r
+ x_bm_to_pbm\r
+ ------------\r
+ C Prototype: extern int x_bm_to_pbm(char far * source_pbm,\r
+ char far * dest_bm);\r
+\r
+ This function converts a bitmap in the linear format as used by\r
+ x_compile_bitmap to the planar formap.\r
+\r
+ WARNING: the source and destination bitmaps must be pre - allocated\r
+\r
+ NOTE: This function can only convert linear bitmaps that are suitable.\r
+ If the source linear bitmap's width is not a multiple of 4\r
+ it cannot be converted. In this situation an error code\r
+ BM_WIDTH_ERROR. On successful conversion 0 is returned.\r
+\r
projects / 16.git / blobdiff