Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD2.mdf / c / library / dos / grafik / xlib / xlibref1.doc < prev next >

Wrap

Text File | 1992-11-08 | 57.4 KB | 1,608 lines

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