+++ /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