2 -----------------------------------------------------------------------------
\r
4 ********* XLIB - Mode X graphics library ****************
\r
5 ********* ****************
\r
6 ********* Written By Themie Gouthas ****************
\r
7 ********* ****************
\r
8 ********* egg@dstos3.dsto.gov.au ****************
\r
9 ********* teg@bart.dsto.gov.au ****************
\r
11 Some of the code in this library has been contributed by :
\r
13 Matthew MacKenzie - matm@eng.umd.edu
\r
15 and others. See individual modules.
\r
17 I informally reserve all rights to the code in XLIB
\r
18 Rights to contributed code is also assumed to be reserved by
\r
19 the original authors.
\r
20 -----------------------------------------------------------------------------
\r
24 This library is distributed AS IS. The author/s specifically disclaim
\r
25 any responsibility for any loss of profit or any incidental, consequen-
\r
26 tial or other damages.
\r
28 ---------------------------------------------------------------------------
\r
30 ---------------------------------------------------------------------------
\r
32 XLIB is a "user supported freeware" graphics library specifically designed
\r
33 with game programming in mind.
\r
35 It has been placed in the public domain for the benefit of all, and
\r
36 represents *MANY* hours of work so it is requested that all users comply
\r
37 with the the wishes of the author/s as specified in the individual modules
\r
39 a) To leave the code in the public domain
\r
40 b) Not distribute any modified or incomplete versions of this library
\r
42 New contribution and comments are welcome and hopefully there will be
\r
43 more releases as the code evolves.
\r
45 Finally, do not trust this excuse for a manual if in doubt, as this code has
\r
46 undergone several revisions. The place to get the answers is in the code
\r
51 Minimum requirements
\r
53 Turbo C 2.0 or higher, or BORLANDC
\r
56 Turbo Assembler 1.01 or higher
\r
61 Support for a number of 256 colour tweaked graphics mode resolutions
\r
62 320x200 320x240 360x200 360x240 376x282 320x400 320x480 360x400 360x480
\r
63 360x360 376x308 376x564
\r
65 Please note that some of the new resolutions best suit monitors with
\r
66 adjustable vertical height.
\r
68 Virtual screens larger than the physical screen (memory
\r
69 permitting) that can be panned at pixel resolution in all directions
\r
71 A split screen capability for status displays etc.
\r
73 Text functions supporting 8x8 and 8x14 ROM fonts and user defined fonts
\r
75 Support for page flipping
\r
77 Graphics primitives such as line and rectangle drawing functions and
\r
78 of course bit block manipulation functions
\r
80 MODULES COMPRISING XLIB
\r
81 XMAIN - Main module containig mode setting code and basic functions
\r
82 XPOINT - Pixel functions
\r
83 XRECT - Filled Rectangle and VRAM to VRAM block move functions
\r
84 XPAL - Palette functions
\r
85 XLINE - Line Functions
\r
86 XTEXT - Text and Font Functions
\r
87 XPRINTF - Printf style string output
\r
88 XPBITMAP - Planar Bitmap functions
\r
89 XCBITMAP - Compiled Bitmap functions
\r
90 XVBITMAP - Video Bitmap functions
\r
91 XPBMCLIP - Clipped Planar Bitmap functions
\r
92 XMAKEVBM - Support module for video bitmaps
\r
93 XBMTOOLS - Bitmap format conversion tools
\r
94 XDETECT - Hardware detection module
\r
95 XFILEIO - File I/O functions
\r
96 XRLETOOL - RLE encoding/decoding functions
\r
97 XMOUSE - Mouse functions
\r
98 XBEZIER - Bezier curve drawing
\r
100 -------------------------------------------------------------------------
\r
101 BUILDING THE LIBRARIES
\r
102 -------------------------------------------------------------------------
\r
104 Building the library had been made simple through the use of make.
\r
106 To build and examples for one of the two models:
\r
108 a) edit the makefile for the apropriate model (see note in the makefile)
\r
109 b) edit the makefile for the apropriate compiler (again see note in the
\r
111 c) type "make" at the dos prompt.
\r
113 It should be as simple as that. If problems are encountered then check
\r
114 to see if tasm, make, tlib, link and bcc (or tcc) are withinin your path.
\r
115 If not either change your path or specify the full path for these programs
\r
116 in the makefile. It is preferrable to have your path set correctly.
\r
118 Individual Compilation
\r
119 ----------------------
\r
121 each ASM module can be compiled with the following commandline:
\r
123 tasm /ml /d<model> <asm module name>
\r
125 where <model> is s c or l. Where s = small model, c = compact model and
\r
128 The resulting libraries are:
\r
130 xlib<version>s.lib - small model library
\r
131 xlib<version>c.lib - large model library
\r
132 xlib<version>l.lib - large model library
\r
134 To link the library with your programs just include the apropriate .lib
\r
135 file in your project file or on the BCC or TCC command line.
\r
137 Using the library with your programs
\r
138 ------------------------------------
\r
140 Using the XLIB library in your programs is simple. Knowing the particular
\r
141 modules you require, just include the associated header files in your program
\r
142 and link your program modules with the library. If you don't want to wory
\r
143 about selecting the apropriate header file then just include "XLIB_ALL.H"
\r
144 which automatically includes all XLIB header files in your program.
\r
146 For example compilations see the supplied makefile.
\r
148 --------------------------------------------------------------------------
\r
149 GLOBAL DEFINES (xlib.inc)
\r
150 --------------------------------------------------------------------------
\r
157 Available X mode resolutions
\r
172 Palette rotation direction directiion
\r
183 --------------------------------------------------------------------------
\r
185 --------------------------------------------------------------------------
\r
187 The Xmain module is the base module of the XLIB library. It contains the
\r
188 essential functions that initialize and customize the graphic environment.
\r
193 xmain.asm xmain.inc xlib.inc model.inc
\r
201 NOTE: All variables are read only unless otherwise specified. If you modify
\r
202 them manually, the results may be unpredictable.
\r
204 InGraphics - BYTE - Flag indicating that the xlib graphics system is
\r
205 active. Set by function "x_set_mode".
\r
207 CurrXMode - WORD - If the xlib graphics system is active, contains the id
\r
208 of the x mode. Set by function "x_set_mode".
\r
209 See also defines (ie X_MODE_320x200 ... )
\r
211 ScrnPhysicalByteWidth - WORD - Physical screen width in bytes. Set by
\r
212 function "x_set_mode"
\r
214 ScrnPhysicalPixelWidth - WORD - Physical screen width in pixels. Set by
\r
215 function "x_set_mode"
\r
217 ScrnPhysicalHeight - WORD - Physical screen height in pixels. Set by
\r
218 function "x_set_mode".
\r
220 ErrorValue - WORD - Contains error value. General use variable to
\r
221 communicate the error status from several functions. The value
\r
222 in this variable usually is only valid for the the last
\r
223 function called that sets it.
\r
225 SplitScrnOffs - WORD - Offset in video ram of split screen. Set by
\r
226 function "x_set_splitscrn". The value is only valid if a split
\r
227 screen is active. See also global variable "SplitScrnActive".
\r
229 SplitScrnScanLine - WORD - Screen Scan Line the Split Screen starts at
\r
230 initially when set by function "x_set_splitscrn". The value is only
\r
231 valid if a split screen is active. See also global variable
\r
232 "SplitScrnActive".This variable is not updated by "x_hide_splitscrn",
\r
233 "x_adjust_splitscrn".
\r
235 SplitScrnVisibleHeight - WORD - The number of rows of the initial split
\r
236 screen which are currently displayed. Modified by "x_hide_splitscrn",
\r
237 "x_adjust_splitscrn" and "x_show_splitscrn".
\r
239 Page0_Offs - WORD - Offset in video ram of main virtual screen. Initially
\r
240 set by function "x_set_mode" but is updated by functions
\r
241 "x_set_splitscrn" and "x_set_doublebuffer".
\r
243 Page1_Offs - WORD - Offset in video ram of second virtual screen. Set by
\r
244 and only is valid after a call to "x_set_doublebuffer".
\r
246 ScrnLogicalByteWidth - WORD - Virtual screen width in bytes. Set by
\r
247 function "x_set_mode".
\r
249 ScrnLogicalPixelWidth - WORD - Virtual screen width in pixels. Set
\r
250 by function "x_set_mode".
\r
252 ScrnLogicalHeight - WORD - Virtual screen height in pixels. Set
\r
253 initially by function "x_set_mode" but is updated by functions
\r
254 "x_set_splitscrn" and "x_set_doublebuffer".
\r
256 MaxScrollX - WORD - Max X pixel position of physical screen within
\r
257 virtual screen. Set by function "x_set_mode".
\r
259 MaxScrollY - WORD - Max Y position of physical screen within virtual
\r
260 screen. Set initially by function "x_set_mode" but is updated by
\r
261 functions "x_set_splitscrn" and "x_set_doublebuffer".
\r
263 DoubleBufferActive - WORD - Indicates whether double-buffering is on. Set
\r
264 by function "x_set_doublebuffer".
\r
266 VisiblePageIdx - WORD - Index number of current visible page. Initially
\r
267 set by function "x_set_doublebuffer" but is updated by "x_page_flip".
\r
268 This variable is only used while double buffering is on.
\r
270 HiddenPageOffs - WORD - Offset of hidden page. Initially set by function
\r
271 "x_set_doublebuffer" but is updated by "x_page_flip". This variable
\r
272 is only used while double buffering is on.
\r
274 VisiblePageOffs - WORD - Offset of visible page. Initially set by function
\r
275 "x_set_doublebuffer" but is updated by "x_page_flip". This variable
\r
276 is only used while double buffering is on.
\r
278 NonVisual_Offs - WORD - Offset of first byte of non-visual ram, the ram
\r
279 that is available for bitmap storage etc. Set initially by function
\r
280 "x_set_mode" but is updated by functions "x_set_splitscrn" and
\r
281 "x_set_doublebuffer".
\r
283 TopClip, BottomClip, LeftClip RightClip - WORD - Define the clipping
\r
284 rectangle for Linear and Video clipped bitmap put functions. Set
\r
285 either manually or by "x_set_cliprect". Note X coordinates are in
\r
286 bytes as all clip functions clip to byte boundaries.
\r
288 PhysicalStartPixelX - WORD - X pixel Offset of physical (visible) screen
\r
289 relative to the upper left hand corner (0,0) of the virtual screen.
\r
291 PhysicalStartByteX - WORD - X byte Offset of physical (visible) screen
\r
292 relative to the upper left hand corner (0,0) of the virtual screen.
\r
294 PhysicalStartY - WORD - Y pixel Offset of physical (visible) screen
\r
295 relative to the upper left hand corner (0,0) of the virtual screen.
\r
301 C Prototype: extern WORD x_set_mode(WORD mode,WORD WidthInPixels);
\r
303 mode - The required mode as defined by the "Available X Mode
\r
304 resolutions" set of defines in the xlib.h header file.
\r
305 WidthInPixels - The required virtual screen width.
\r
306 Returns - The actual width in pixels of the allocated virtual
\r
309 This function initialises the graphics system, setting the apropriate
\r
310 screen resolution and allocating a virtual screen. The virtual screen
\r
311 allocated may not necessarily be of the same size as specified in the
\r
312 "WidthInPixels" parameter as it is rounded down to the nearest
\r
315 The function returns the actual width of the allocated virtual screen
\r
316 in pixels if a valid mode was selected otherwise returns
\r
319 Saves virtual screen pixel width in "ScrnLogicalPixelWidth".
\r
320 Saves virtual screen byte width in "ScrnLogicalByteWidth".
\r
321 Physical screen dimensions are set in "ScrnPhysicalPixelWidth".
\r
322 "ScrnPhysicalByteWidth" and "ScrnPhysicalHeight". Other global
\r
323 variables set are "CurrXMode","MaxScrollX", "MaxScrollY",
\r
324 "InGraphics". The variable "SplitScrnScanline" is also initialized
\r
328 Available X Mode resolutions
\r
331 x_select_default_plane
\r
332 ----------------------
\r
334 C Prototype: void x_select_default_plane(BYTE plane);
\r
336 Enables default Read/Write access to a specified plane
\r
342 C Prototype: extern void x_set_splitscreen(WORD line);
\r
344 line - The starting scan line of the required split screen.
\r
346 This function activates Mode X split screen and sets starting scan
\r
347 line. The split screen resides on the bottom half of the screen and has
\r
348 a starting address of A000:0000 in video RAM.
\r
350 It also Updates Page0_Offs to reflect the existence of the split screen
\r
351 region ie "MainScrnOffset" is set to the offset of the first pixel
\r
352 beyond the split screen region. Other variable set are "Page1_Offs" which
\r
353 is set to the same value as "Page0_Offs" (see graphics call sequence
\r
354 below), "ScrnLogicalHeight","ScrnPhysicalHeight", "SplitScrnScanLine" and
\r
357 This function cannot be called after double buffering has been activated,
\r
358 it will return an error. To configure your graphics environment the
\r
359 sequence of graphics calls is as follows although either or both steps b
\r
360 and c may be omitted:
\r
362 b) x_set_splitscreen
\r
363 c) x_set_doublebuffer
\r
364 Thus when you call this function successfully, double buffering is not
\r
365 active so "Page1_Offs" is set to the same address as "Page0_Offs".
\r
367 WARNING: If you use one of the high resolution modes (376x564 as an
\r
368 extreme example) you may not have enough video ram for split screen
\r
369 and double buffering options since VGA video RAM is restricted to
\r
373 What is a Split Screen ?
\r
374 What is double buffering ?
\r
379 C Prototype: extern WORD x_set_doublebuffer(WORD PageHeight);
\r
381 PageHeight - The height of the two double buffering virtual screens.
\r
382 Returns - The closest possible height to the specified.
\r
384 This function sets up two double buffering virtual pages. 'ErrorValue"
\r
385 is set according to the success or failure of this command.
\r
387 Other variables set are:
\r
389 _Page1_Offs Offset of second virtual page
\r
390 _NonVisual_Offs Offset of first non visible video ram byte
\r
391 _DoubleBufferActive Flag
\r
392 _PageAddrTable Table of Double buffering pages start offsets
\r
393 _ScrnLogicalHeight Logical height of the double buffering pages
\r
394 _MaxScrollY Max vertical start address of physical screen
\r
395 within the virtual screen
\r
397 WARNING: If you use one of the high resolution modes (376x564 as an
\r
398 extreme example) you may not have enough video ram for split screen
\r
399 and double buffering options since VGA video RAM is restricted to
\r
403 What is double buffering ?
\r
408 C Prototype: extern void x_hide_splitscreen(void);
\r
411 This function hides an existing split screen by setting its starting
\r
412 scan line to the last physical screen scan line.
\r
413 "ScreenPhysicalHeight" is adjusted but the "SplitScreenScanLine" is not
\r
414 altered as it is required for restoring the split screen at a later stage.
\r
416 WARNING: Only to be used if SplitScrnLine has been previously called
\r
417 Disabled for mode 5-11 (320x400-376x564). The memory for
\r
418 the initial split screen is reserved and the size limitations
\r
419 of these modes means any change in the split screen scan line
\r
420 will encroach on the split screen ram
\r
421 Update: Now disabled for these modes
\r
425 What is a split screen ?
\r
430 C Prototype: extern void x_show_splitscreen(void);
\r
432 Restores split screen start scan line to the initial split screen
\r
433 starting scan line as set by "SplitScrnScanLine".
\r
434 "ScreenPhysicalHeight" is adjusted.
\r
436 WARNING: Only to be used if SplitScrnLine has been previously called
\r
437 Disabled for mode 4-10 (320x400-376x564). The memory for
\r
438 the initial split screen is reserved and the size limitations
\r
439 of these modes means any change in the split screen scan line
\r
440 will encroach on the split screen ram
\r
443 x_adjust_splitscreen
\r
444 --------------------
\r
446 C Prototype: extern void x_adjust_splitscreen(WORD line);
\r
448 line - The scan line at which the split screen is to start.
\r
450 Sets the split screen start scan line to a new scan line. Valid scan lines
\r
451 are between the initial split screen starting scan line and the last
\r
452 physical screen scan line. "ScreenPhysicalHeight" is also adjusted.
\r
454 WARNING: Only to be used if SplitScrnLine has been previously called
\r
455 Disabled for mode 4-10 (320x400-376x564). The memory for
\r
456 the initial split screen is reserved and the size limitations
\r
457 of these modes means any change in the split screen scan line
\r
458 will encroach on the split screen ram
\r
463 C Prototype: extern void x_set_start_addr(WORD X,WORD Y);
\r
465 X,Y - coordinates of top left corner of physical screen within current
\r
468 Set Mode X non split screen physical start address within current virtual
\r
471 X must not exceed (Logical screen width - Physical screen width)
\r
472 ie "MaxScrollX" and Y must not exceed (Logical screen height -
\r
473 Physical screen height) ie "MaxScrollY"
\r
478 C Prototype: extern void x_page_flip(WORD X,WORD Y);
\r
480 X,Y - coordinates of top left corner of physical screen within the
\r
481 the hidden virtual screen if double buffering is active, or
\r
482 the current virtual screen otherwise.
\r
484 Sets the physical screen start address within currently hidden virtual
\r
485 page and then flips pages. If double buffering is not active then this
\r
486 function is functionally equivalent to "x_set_start_addr".
\r
488 X must not exceed (Logical screen width - Physical screen width)
\r
489 ie "MaxScrollX" and Y must not exceed (Logical screen height -
\r
490 Physical screen height) ie "MaxScrollY"
\r
495 C Prototype: extern void x_text_mode(void);
\r
497 Disables graphics mode.
\r
502 C Prototype: extern void x_set_cliprect(WORD left,WORD top,WORD right,
\r
505 Defines the clipping rectangle for clipping versions of planar and video
\r
508 NOTE: Compiled bitmaps cannot be clipped.
\r
511 --------------------------------------------------------------------------
\r
513 --------------------------------------------------------------------------
\r
515 Point functions all MODE X 256 Color resolutions
\r
519 xpoint.asm xpoint.inc xlib.inc model.inc
\r
530 C Prototype: extern void x_put_pix(WORD X,WORD Y,WORD PageOffset,
\r
533 Draw a point of specified colour at coordinates X,Y
\r
534 within the virtual page starting at offset PageOffset.
\r
539 C Prototype: extern WORD x_get_pix(WORD X, WORD Y, WORD PageBase);
\r
541 Read a point of at coordinates X,Y within the virtual page starting
\r
542 at offset PageOffset.
\r
545 --------------------------------------------------------------------------
\r
547 --------------------------------------------------------------------------
\r
549 Screen rectangle display and manipulation functions
\r
553 xrect.asm xrect.inc xlib.inc model.inc
\r
565 C Prototype: extern void x_rect_pattern(WORD StartX, WORD StartY,
\r
566 WORD EndX, WORD EndY,
\r
567 WORD PageBase,BYTE far *Pattern);
\r
569 StartX,StartY - Coordinates of upper left hand corner of rectangle
\r
570 EndX,EndY - Coordinates of lower right hand corner of rectangle
\r
571 PageBase - Offset of virtual screen
\r
572 *Pattern - Pointer to the user defined pattern (16 bytes)
\r
575 Mode X rectangle 4x4 pattern fill routine.
\r
577 Upper left corner of pattern is always aligned to a multiple-of-4
\r
578 row and column. Works on all VGAs. Uses approach of copying the
\r
579 pattern to off-screen display memory, then loading the latches with
\r
580 the pattern for each scan line and filling each scan line four
\r
581 pixels at a time. Fills up to but not including the column at EndX
\r
582 and the row at EndY. No clipping is performed.
\r
584 Based on code originally published in DDJ Mag by M. Abrash
\r
586 Warning the VGA memory locations PATTERN_BUFFER (A000:FFFc) to
\r
587 A000:FFFF are reserved for the pattern buffer
\r
591 Doctor Dobbs Journal references.
\r
594 x_rect_pattern_clipped
\r
595 ----------------------
\r
597 As above but clipped.
\r
602 C Prototype: extern void x_rect_fill(WORD StartX,WORD StartY,
\r
603 WORD EndX,WORD EndY,
\r
604 WORD PageBase,WORD color);
\r
606 StartX,StartY - Coordinates of upper left hand corner of rectangle
\r
607 EndX,EndY - Coordinates of lower right hand corner of rectangle
\r
608 PageBase - Offset of virtual screen
\r
609 Color -color to use for fill
\r
611 Mode X rectangle solid color fill routine.
\r
612 Based on code originally published in DDJ Mag by M. Abrash
\r
615 Doctor Dobbs Journal references.
\r
617 x_rect_fill_clipped
\r
618 -------------------
\r
620 as above but clipped.
\r
626 C Prototype: extern void x_cp_vid_rect(WORD SourceStartX,WORD SourceStartY,
\r
627 WORD SourceEndX,WORD SourceEndY,
\r
628 WORD DestStartX,WORD DestStartY,
\r
629 WORD SourcePageBase,WORD DestPageBase,
\r
630 WORD SourceBitmapWidth,WORD DestBitmapWidth);
\r
632 StartX,StartY- Coordinates of upper left hand corner of source rectangle
\r
633 EndX,EndY - Coordinates of lower right hand corner of source rectangle
\r
634 DestStartX,DestStartY - Coordinates of rectangle destination
\r
635 SourcePageBase - source rectangle page offset
\r
636 DestPageBase - destination rectangles page offset
\r
637 SourceBitmapWidth - width of bitmap within the source virtual screen
\r
638 containing the source rectangle
\r
639 DestBitmapWidth - width of bitmap within the dest. virtual screen
\r
640 containing the destination rectangle
\r
642 Mode X display memory to display memory copy
\r
643 routine. Left edge of source rectangle modulo 4 must equal left edge
\r
644 of destination rectangle modulo 4. Works on all VGAs. Uses approach
\r
645 of reading 4 pixels at a time from the source into the latches, then
\r
646 writing the latches to the destination. Copies up to but not
\r
647 including the column at SrcEndX and the row at SrcEndY. No
\r
648 clipping is performed. Results are not guaranteed if the source and
\r
649 destination overlap.
\r
652 Based on code originally published in DDJ Mag by M. Abrash
\r
655 Doctor Dobbs Journal references.
\r
661 extern void x_shift_rect (WORD SrcLeft, WORD SrcTop,
\r
662 WORD SrcRight, WORD SrcBottom,
\r
663 WORD DestLeft, WORD DestTop, WORD ScreenOffs);
\r
665 SrcLeft, SrcTop - Coordinates of upper left hand corner of rectangle
\r
666 SrcRight, SrcBottom - Coordinates of lower right hand corner of rectangle
\r
667 DestLeft, DestTop - Coordinates of upper left corner of destination
\r
668 ScreenOffs - Offset of virtual screen
\r
670 This function copies a rectangle of VRAM onto another area of VRAM,
\r
671 even if the destination overlaps with the source. It is designed
\r
672 for scrolling text up and down, and for moving large areas of screens
\r
673 around in tiling systems. It rounds all horizontal coordinates to
\r
674 the nearest byte (4-column chunk) for the sake of speed. This means
\r
675 that it can NOT perform smooth horizontal scrolling. For that,
\r
676 either scroll the whole screen (minus the split screen), or copy
\r
677 smaller areas through system memory using the functions in the
\r
680 SrcRight is rounded up, and the left edges are rounded down, to
\r
681 ensure that the pixels pointed to by the arguments are inside the
\r
682 the rectangle. That is, SrcRight is treated as (SrcRight+3) >> 2,
\r
683 and SrcLeft as SrcLeft >> 2.
\r
685 The width of the rectangle in bytes (width in pixels / 4)
\r
688 ---------------------------------------------------------------------------
\r
690 ---------------------------------------------------------------------------
\r
692 Palette functions for VGA 256 color modes.
\r
694 All the functions in this module operate on two variations of the
\r
695 pallete buffer, the raw and annotated buffers.
\r
697 All those functions ending in "raw" operate on the following palette
\r
700 BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn
\r
702 No reference to the starting colour index or number of colours stored
\r
703 is contained in the structure.
\r
705 All those functions ending in "struc" operate on the following palette
\r
708 BYTE:c,BYTE:n,BYTE:r0,g0,b0,r1,g1,b1,...rn,gn,bn
\r
710 where c is the starting colour and n is the number of colours stored
\r
713 WARNING: There is no validity checking in these functions. The onus is
\r
714 on the user to supply valid parameters to the functions.
\r
719 xpal.asm xpal.inc xlib.inc model.inc
\r
730 C Prototype: extern void x_get_pal_raw(BYTE far * pal,WORD num_colrs,
\r
733 Read DAC palette into raw buffer with interrupts disabled
\r
734 ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn
\r
736 WARNING: Memory for the palette buffers must all be pre-allocated.
\r
741 C Prototype: extern void x_get_pal_struc(BYTE far * pal,WORD num_colrs,
\r
744 Read DAC palette into annotated type buffer with interrupts disabled
\r
745 ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn
\r
747 WARNING: memory for the palette buffers must all be pre-allocated
\r
752 C Prototype: extern void x_put_pal_raw(BYTE far * pal,WORD num_colrs,
\r
755 Write DAC palette from raw buffer with interrupts disabled
\r
756 ie BYTE r1,g1,b1,r1,g2,b2...rn,gn,bn
\r
761 C Prototype: extern void x_put_pal_struc(BYTE far * pal);
\r
763 Write DAC palette from annotated type buffer with interrupts disabled
\r
764 ie BYTE colours to skip, BYTE colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn
\r
769 C Prototype: extern x_set_rgb(BYTE color,BYTE red_c,BYTE green_c,
\r
772 Set the RGB components of a vga color
\r
777 C Prototype: extern void x_rot_pal_struc(BYTE far * pal,WORD direction);
\r
779 Rotate annotated palette buffer entries. Direction 0 = backward,
\r
785 C Prototype: extern x_rot_pal_raw(BYTE far * pal,WORD direction,
\r
788 Rotate a raw palette buffer. Direction 0 = backward,
\r
791 x_put_contrast_pal_struc
\r
792 ------------------------
\r
794 C Prototype: extern void x_put_contrast_pal_struc(BYTE far * pal,
\r
797 Write DAC palette from annotated type buffer with specified intensity
\r
798 adjustment (ie palette entries are decremented where possible by
\r
799 "intensity" units).
\r
801 Designed for fading in or out a palette without using an intermediate
\r
802 working palette buffer ! (Slow but memory efficient ... OK for small
\r
806 x_transpose_pal_struc
\r
807 ---------------------
\r
809 C Prototype: extern void x_transpose_pal_struc(BYTE far * pal,
\r
812 Write DAC palette from annotated type buffer with interrupts disabled
\r
813 starting at a new palette index.
\r
816 x_cpcontrast_pal_struc
\r
817 ----------------------
\r
819 C Prototype: extern WORD x_cpcontrast_pal_struc(BYTE far *src_pal,
\r
820 BYTE far *dest_pal,BYTE Intensity);
\r
822 Copy one annotated palette buffer to another making the intensity
\r
823 adjustment. Used in fading in and out fast and smoothly.
\r
825 ---------------------------------------------------------------------------
\r
827 ---------------------------------------------------------------------------
\r
829 Line Drawing functions.
\r
833 xline.asm xline.inc xlib.inc model.inc
\r
844 C Prototype: extern void x_line(WORD x0,WORD y0,WORD x1,WORD y1,
\r
845 WORD color,WORD PageBase);
\r
847 Draw a line with the specified end points in the page starting at
\r
850 No Clipping is performed.
\r
852 ---------------------------------------------------------------------------
\r
854 ---------------------------------------------------------------------------
\r
858 xtext.asm xtext.inc xlib.inc model.inc
\r
872 NOTE: All variables are read only. I you modify them the results may
\r
875 CharHeight - BYTE - Height of current inbuilt character set
\r
877 CharWidth - BYTE - Width of current inbuilt character set
\r
879 FirstChar - BYTE - First character of current inbuilt character set
\r
881 UserCharHeight - BYTE - Height of current user character set
\r
883 UserCharWidth - BYTE - Width of current user character set
\r
885 UserFirstCh - BYTE - First character of current user character set
\r
893 C Prototype: extern WORD x_text_init(void);
\r
895 Initializes the Mode X text driver and sets the default font (VGA ROM 8x8)
\r
900 C Prototype: extern void x_set_font(WORD FontId);
\r
902 Select the working font where 0 = VGA ROM 8x8, 1 = VGA ROM 8x14
\r
903 2 = User defined bitmapped font.
\r
905 WARNING: A user font must be registered before setting FontID 2
\r
909 Defines for this module
\r
911 x_register_userfont
\r
912 -------------------
\r
914 C Prototype: extern void x_register_userfont(char far *UserFontPtr);
\r
917 Register a user font for later selection. Only one user font can be
\r
918 registered at any given time. Registering a user font deregisters the
\r
919 previous user font. User fonts may be at most 8 pixels wide.
\r
921 USER FONT STRUCTURE
\r
923 Word: ascii code of first char in font
\r
924 Byte: Height of chars in font
\r
925 Byte: Width of chars in font
\r
926 n*h*Byte: the font data where n = number of chars and h = height
\r
929 WARNING: The onus is on the program to ensure that all characters
\r
930 drawn whilst this font is active, are within the range of
\r
931 characters defined.
\r
936 C Prototype: extern void x_put_char(char ch,WORD X,WORD Y,WORD PgOffs,
\r
939 Draw a text character at the specified location with the specified
\r
943 x,y - screen coords at which to draw ch
\r
944 ScrnOffs - Starting offset of page on whih to draw
\r
945 Color - Color of the text
\r
947 WARNING: InitTextDriver must be called before using this function
\r
952 The file "xprintf.c" implements a printf style formatted output function
\r
957 C Prototype: void x_printf(int x,int y,unsigned ScrnOffs,int color,
\r
960 x,y - screen coords at which to draw ch
\r
961 ScrnOffs - Starting offset of page on whih to draw
\r
962 Color - Color of the text
\r
964 Parameters beyond Color conform to the standard printf parameters.
\r
969 C Prototype: void x_bgprintf(int x,int y,unsigned ScrnOffs,int fgcolor,
\r
970 int bgcolor, char *ln,...);
\r
972 x,y - screen coords at which to draw ch
\r
973 ScrnOffs - Starting offset of page on whih to draw
\r
974 fgcolor - Color of the text foreground
\r
975 bgcolor - Color of the text background
\r
977 Parameters beyond bgolor conform to the standard printf parameters.
\r
983 C Prototype: unsigned int x_get_char_width(char ch)
\r
985 ch - character to get width of
\r
987 --------------------------------------------------------------------------
\r
989 --------------------------------------------------------------------------
\r
991 This module implements a set of functions to operate on planar bitmaps.
\r
992 Planar bitmaps as used by these functions have the following structure:
\r
994 BYTE 0 The bitmap width in bytes (4 pixel groups) range 1..255
\r
995 BYTE 1 The bitmap height in rows range 1..255
\r
996 BYTE 2..n1 The plane 0 pixels width*height bytes
\r
997 BYTE n1..n2 The plane 1 pixels width*height bytes
\r
998 BYTE n2..n3 The plane 2 pixels width*height bytes
\r
999 BYTE n3..n4 The plane 3 pixels width*height bytes
\r
1001 These functions provide the fastest possible bitmap blts from system ram to
\r
1002 to video and further, the single bitmap is applicable to all pixel
\r
1003 allignments. The masked functions do not need separate masks since all non
\r
1004 zero pixels are considered to be masking pixels, hence if a pixel is 0 the
\r
1005 corresponding screen destination pixel is left unchanged.
\r
1010 xpbitmap.asm xpbitmap.inc xlib.inc model.inc
\r
1021 C Prototype: extern void x_put_masked_pbm(WORD X,WORD Y,WORD ScrnOffs,
\r
1022 BYTE far * Bitmap);
\r
1024 Mask write a planar bitmap from system ram to video ram. All zero source
\r
1025 bitmap bytes indicate destination byte to be left unchanged.
\r
1027 Source Bitmap structure:
\r
1029 Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
\r
1030 Bitmap data (plane 2)..,Bitmap data (plane 3)..
\r
1032 NOTE: width is in bytes ie lots of 4 pixels
\r
1034 LIMITATIONS: No clipping is supported
\r
1035 Only supports bitmaps with widths which are a multiple of
\r
1038 See Also: XBMTOOLS module for linear <-> planar bitmap conversion
\r
1044 C Prototype: extern void x_put_pbm(WORD X, WORD Y, WORD ScrnOffs,
\r
1045 BYTE far * Bitmap);
\r
1047 Write a planar bitmap from system ram to video ram.
\r
1049 Source Bitmap structure:
\r
1051 Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
\r
1052 Bitmap data (plane 2)..,Bitmap data (plane 3)..
\r
1054 NOTE: width is in bytes ie lots of 4 pixels
\r
1056 LIMITATIONS: No clipping is supported
\r
1057 Only supports bitmaps with widths which are a multiple of
\r
1061 See Also: XBMTOOLS module for linear <-> planar bitmap conversion
\r
1067 C Prototype: extern void x_get_pbm(WORD X, WORD Y,BYTE Bw,BYTE Bh,
\r
1068 WORD ScrnOffs, BYTE far * Bitmap);
\r
1070 Read a planar bitmap to system ram from video ram.
\r
1072 Source Bitmap structure:
\r
1074 Width:byte, Height:byte, Bitmap data (plane 0)...Bitmap data (plane 1)..,
\r
1075 Bitmap data (plane 2)..,Bitmap data (plane 3)..
\r
1077 NOTE: width is in bytes ie lots of 4 pixels
\r
1079 LIMITATIONS: No clipping is supported
\r
1080 Only supports bitmaps with widths which are a multiple of
\r
1084 See Also: XBMTOOLS module for linear <-> planar bitmap conversion
\r
1087 --------------------------------------------------------------------------
\r
1089 --------------------------------------------------------------------------
\r
1091 This module implements a similar set of functions to operate on planar
\r
1092 bitmaps as "XPBITMAP" but incorporates clipping to a user defined
\r
1093 clipping rectangle (which is set by "x_set_cliprect" in module xmain).
\r
1095 The planar bitmap format is identical to the above module
\r
1097 There are three variations of the functions in XPBITMAP in this module
\r
1098 identified by the three function name extensions: _clipx, _clipy _clipxy.
\r
1099 Because speed is critical in games programming you do not want to be
\r
1100 checking for clipping if not necessary thus for sprites that move only
\r
1101 horizontally you would use the _clipx version of the put function,
\r
1102 for sprites that move vertically you would use the _clipy version and for
\r
1103 sprites that move both directions you would use the clipxy version.
\r
1104 Keep in mind also that the clipping components of these functions assume
\r
1105 that the clipping rectangle is equal to or larger than the size of the
\r
1106 bitmap ie. if a bitmap is top clipped, it is assumed that the bitmap's
\r
1107 bottom is not also clipped. Similarly with horizontal clipping.
\r
1109 Note: performance in decreasing order is as follows.
\r
1110 _clipy,_clipx,_clipxy with masked puts being slower than unmasked
\r
1113 Horizontal clipping is performed to byte boundaries (4 pixels) rather than
\r
1114 pixels. This allows for the fastest implementation of the functions. It is
\r
1115 not such a handicap because for one, your screen width a multiple of 4
\r
1116 pixels wide and for most purposes it is the screen edges that form the
\r
1117 clipping rectangle.
\r
1119 Following is an example of setting a clipping rectangle to the logical
\r
1122 x_set_cliprect(0,0,ScrnLogicalByteWidth,ScrnLogicalHeight)
\r
1124 NOTE: the functions now return a value;
\r
1125 1 if clipped image is fully clipped (ie no portion of it
\r
1126 appears on the screen) otherwise it returns 0
\r
1131 xpbmclip.asm xpbmclip.inc xlib.inc model.inc
\r
1145 x_put_masked_pbm_clipx
\r
1146 ----------------------
\r
1147 x_put_masked_pbm_clipy
\r
1148 ----------------------
\r
1149 x_put_masked_pbm_clipxy
\r
1150 -----------------------
\r
1152 For a detailed description of parameters etc. see equivalent functions
\r
1153 in module "XPBITMAP".
\r
1156 --------------------------------------------------------------------------
\r
1158 --------------------------------------------------------------------------
\r
1161 The Care and Feeding of Compiled Masked Blits
\r
1162 by Matthew MacKenzie
\r
1164 The XCBITMAP module of the Xlib library is made up of the files
\r
1165 XCBITMAP.ASM, XCBITMAP.INC, and XCBITMAP.H.
\r
1167 The XCBITMAP module is small, containing only three procedures:
\r
1168 o x_compile_bitmap compiles your bitmap into native code which writes
\r
1169 to the VGA screen in an X mode.
\r
1170 o x_put_cbitmap converts X and Y coordinates into a location on the
\r
1171 screen, sets up the necessary VGA registers, and executes the compiled
\r
1172 bitmap as a subroutine.
\r
1173 o x_sizeof_cbitmap takes a planar bitmap and returns an integer equal to
\r
1174 the size of the compiled bitmap which the planar bitmap would produce.
\r
1175 It is essentially a lobotomized version of x_compile_bitmap, with all
\r
1176 the code generation replaced with a size counter.
\r
1178 x_compile_bitmap scans through a source bitmap and generates 8086
\r
1179 instructions to plot every nonzero pixel. It is designed to be used
\r
1180 before the action begins rather than on-the-fly. The compiled bitmap
\r
1181 contains no branches, and no reference to the zero (transparent) pixels.
\r
1182 Where two pixels are exactly four columns apart they are plotted with a
\r
1183 single 16-bit store, and the VGA MAP_MASK register will be set at most
\r
1184 four times. As a result your bitmap may run several times faster than a
\r
1185 traditional memory-to-VGA masked blit routine.
\r
1186 There is no way to perform clipping on these bitmaps, or to plot a
\r
1187 pixel of color zero.
\r
1188 x_compile_bitmap works with bitmaps in the standard Xlib planar bitmap
\r
1189 format. On a time scale of 60 frames per second, it is actually relatively
\r
1190 slow. Since a compiled bitmap is relocatable you may just want to have it
\r
1191 saved to disk, and not include the source bitmap in your program at all.
\r
1192 The source bitmap format is an array of bytes, a little like this:
\r
1194 char eye[] ={4, 7, /* four byte columns across, seven rows tall */
\r
1195 0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0, 0, 0, 0,
\r
1196 0, 0, 9, 9, 1, 1, 1, 4, 4, 9, 9, 0, 0, 0, 0, 0,
\r
1197 0, 9, 9, 1, 2, 0, 0, 4, 4, 1, 9, 9, 0, 0, 0, 0,
\r
1198 9, 9, 9, 1, 0, 0, 0, 0, 1, 1, 9, 9, 9, 0, 0, 0,
\r
1199 0, 9, 9, 1, 2, 0, 0, 2, 1, 1, 9, 9, 0, 0, 0, 0,
\r
1200 0, 0, 9, 9, 1, 1, 1, 1, 1, 9, 9, 0, 0, 0, 0, 0,
\r
1201 0, 0, 0, 0, 9, 1, 1, 1, 9, 0, 0, 0, 0, 0, 0, 0};
\r
1203 This is actually a linear bitmap, which is the wrong format for
\r
1204 compilation, but is easier on human eyes. Use the module XBMTOOLS to
\r
1205 convert linear bitmaps into planar bitmaps, and vice-versa.
\r
1206 To compile this image for a mode 360 pixels (90 byte columns) across:
\r
1208 char planar_eye[4*7 + 2];
\r
1209 char far * EyeSize;
\r
1211 (void) x_bm_to_pbm((char far *) eye, (char far *) planar_eye);
\r
1212 EyeSize = x_sizeof_cbitmap((far char *) planar_eye);
\r
1213 CompiledEye = farmalloc(EyeSize);
\r
1214 (void) x_compile_bitmap(90, (far char *) planar_eye, CompiledEye);
\r
1216 Notice that both buffers must exist beforehand. Since x_compile_bitmap
\r
1217 returns the size of the compiled code, in bytes, you can reallocate the
\r
1218 bitmap immediately to the right size if using x_sizeof_xbitmap seems
\r
1219 inconvenient (reallocation may even be faster, though using the function is
\r
1220 cleaner). The pointers are 32-bit because compiled bitmaps take so much
\r
1221 space: they are at one end of the speed-versus-memory spectrum. A good
\r
1222 rule of thumb is to allocate (3.5 x buffer-height x buffer-width) + 25
\r
1223 bytes (rounding up ;-), then pare your bitmap down when you find out how
\r
1224 much space you've actually used.
\r
1225 Since the compiled bitmap has to fit within one segment of memory, it
\r
1226 cannot contain more than about 19,000 pixels. This will not be a
\r
1227 limitation for most sane programmers. If you are not a sane programmer try
\r
1228 splitting your huge, unwieldy image up into smaller parts -- you can use
\r
1229 the same gigantic bitmap if you divide it into horizontal slices for
\r
1230 compilation. For that matter, dividing the source up that way will let
\r
1231 you use a source bitmap large than 64K, which is an even sicker idea...
\r
1232 Back to business. A bitmap is compiled for only one width of screen.
\r
1233 If you are using a logical screen larger than your physical screen, call
\r
1234 the bitmap compiler with the logical width -- the important thing is the
\r
1235 number of bytes per line. Notice that you do not have to be in a graphics
\r
1236 mode to use this routine. This allows you to develop and compile bitmaps
\r
1237 separately, with whatever utility programs you might cook up.
\r
1239 The final function is x_put_cbitmap. To plot our eye at (99,4), on
\r
1240 the page which starts at location 0:
\r
1241 x_put_cbitmap(99, 4, 0, CompiledEye);
\r
1242 This function depends on the global variable ScrnLogicalByteWidth from
\r
1243 the module XMAIN, which should be the same number as the column parameter
\r
1244 you used to compile your bitmap.
\r
1245 The XCBITMAP module supports memory-to-VGA blits only. Xlib also
\r
1246 includes non-masking routines which can quickly save and restore the
\r
1247 background screen behind your bitmap, using fast string operations.
\r
1249 This module is part of the Xlib package, and is in the public domain.
\r
1250 If you write something which uses it, though, please send me a copy as a
\r
1251 courtesy -- if for no other reason so I can tilt my chair back and reflect
\r
1252 that it may have been worth the trouble after all.
\r
1254 The included program DEMO2.C demonstrates the performance difference
\r
1255 between planar bitmap masked blits and compiled bitmap blits.
\r
1257 --------------------------------------------------------------------------
\r
1259 --------------------------------------------------------------------------
\r
1261 Identical to XCBITMAP except that the source bitmaps are the PBM form
\r
1271 See XCBITMAP module
\r
1273 --------------------------------------------------------------------------
\r
1275 --------------------------------------------------------------------------
\r
1277 The XVBITMAP module implements yet another type of bitmap to complement
\r
1278 planar and compiled bitmaps, VRAM based bitmaps. If a 4 cylinder car is
\r
1279 analagous to planar bitmaps, that is thrifty on memory consumption but low
\r
1280 performance and and a V8 is analagous to Compiled bitmaps, memory guzzlers
\r
1281 that really fly, then VRAM based bitmaps are the 6 cylinder modest performers
\r
1282 with acceptable memory consumption.
\r
1284 To summarise their selling points, VBM's are moderately fast with fair memory
\r
1285 consumption, and unlike compiled bitmaps, can be clipped. The disadvantages
\r
1286 are that they are limited by the amount of free video ram and have a complex
\r
1289 The VRAM bitmap format is rather complex consisting of components stored in
\r
1290 video ram and components in system ram working together. This complexity
\r
1291 necessitates the existence of a creation function "x_make_vbm" which takes
\r
1292 an input linear bitmap and generates the equivalent VBM (VRAM Bit Map).
\r
1296 WORD 0 Size Total size of this VBM structure in bytes
\r
1297 WORD 1 ImageWidth Width in bytes of the image (for all alignments)
\r
1298 WORD 2 ImageHeight Height in scan lines of the image
\r
1300 WORD 3 Alignment 0 ImagePtr Offset in VidRAM of this aligned image
\r
1301 +--WORD 4 MaskPtr Offset (within this structure's DS) of
\r
1302 | . alignment masks
\r
1305 | WORD 9 Alignment 3 ImagePtr Offset in VidRAM of this aligned image
\r
1306 +|--WORD 10 MaskPtr Offset (within this structure's DS) of
\r
1307 || alignment masks
\r
1309 |+->BYTE 21 (WORD 11) -------+-- Image masks for alignment 0
\r
1312 | BYTE 21 + ImageWidth*ImageHeight -----+
\r
1315 | . (similaly for alignments 1 - 2 )
\r
1318 +-->BYTE 21 + 3*ImageWidth*ImageHeight + 1-+-- Image masks for alignment 3
\r
1321 BYTE 21 + 4*(ImageWidth*ImageHeight) --+
\r
1325 << Similarly for alignments 2 and 3 >>
\r
1328 BYTE 21 + 4*(ImageWidth*ImageHeight)
\r
1331 (And dont forget the corresponding data in video ram)
\r
1333 You can see for yourself the complexity of this bitmap format. The image
\r
1334 is stored in video ram in its 4 different alignments with pointers to these
\r
1335 alignments in the VBM. Similarly there are 4 alignments of the corresponding
\r
1336 masks within the VBM itself (towards the end). The mask bytes contain the
\r
1337 plane settings for the corresponding video bytes so that one memory move can
\r
1338 move up to 4 pixels at a time (depending on the mask settings) using the
\r
1339 VGA's latches, theoretically giving you a 4x speed improvement over
\r
1340 conventional blits like the ones implemented in "XPBITMAP". In actual fact
\r
1341 its anywhere between 2 and 3 due to incurred overheads.
\r
1343 These bitmaps are more difficult to store in files than PBM'S and CBM's but
\r
1344 still posible with a bit of work, so do not dismiss these as too difficult
\r
1345 to use. Consider all the bitmap formats carefully before deciding on which
\r
1346 to use. There may even be situations that a careful application of all three
\r
1347 types would be most effective ie. compiled bitmaps for Background tiles and
\r
1348 the main game character (which never need clipping), VRAM based bitmaps for
\r
1349 the most frequently occuring (oponent, alien etc) characters which get
\r
1350 clipped as they come into and leave your current location and planar bitmaps
\r
1351 for smaller or less frequently encountered characters.
\r
1355 xvbitmap.asm xvbitmap.inc xlib.inc model.inc
\r
1356 xmakevbm.c - Additional C module implementing creation function
\r
1362 EXPORTED FUNCTIONS
\r
1367 C Prototype: extern char far * x_make_vbm(char far *lbm, WORD *VramStart);
\r
1369 Create the VBM from the given linear bitmap and place the image alignments
\r
1370 in video ram starting at the offset in the variable pointed to by
\r
1371 "VramStart". "VramStart" is then updated to point to the next free VRAM byte
\r
1372 (just after the last byte of the image alignments). Usually you will point
\r
1373 "VramStart" to "NonVisual_Offs".
\r
1375 lbm Pointer to the input linear bitmap
\r
1376 VramStart Pointer to variable containing Offset of first free VRAM byte
\r
1381 C Prototype: extern int x_put_masked_vbm(int X, int Y, WORD ScrnOffs,
\r
1382 BYTE far * VBitmap);
\r
1384 Draw a VRAM based bitmap at (X,Y) relative to the screen with starting
\r
1385 offset "ScrnOffs".
\r
1387 Returns 1 if clipped image is fully clipped (ie no portion of it
\r
1388 appears on the screen) otherwise it returns 0
\r
1390 x_put_masked_vbm_clipx
\r
1391 ----------------------
\r
1392 x_put_masked_vbm_clipy
\r
1393 ----------------------
\r
1394 x_put_masked_vbm_clipxy
\r
1395 -----------------------
\r
1397 Clipping versions of "x_put_masked_vbm".
\r
1399 See XPBMCLIP for more details on the type of clipping used as it is
\r
1400 identical to XVBITMAP.
\r
1402 --------------------------------------------------------------------------
\r
1404 --------------------------------------------------------------------------
\r
1405 The XMOUSE module implements very basic mouse handling functions. The way
\r
1406 in which it operates is by installing an event handler function during
\r
1407 initialization which subsequently intercepts and processes mouse events and
\r
1408 automatically updates status variables such as mouse position and button
\r
1409 pressed status. It does not support the full functionality of:
\r
1415 This was done to primarily prevent unecessary impedences to performance,
\r
1416 since the mouse handler function has the potential to degrade performance.
\r
1417 It also saves me alot of coding which I was too lazy to do.
\r
1419 Programs communicate with the mouse driver as with other devices, through
\r
1420 an interrupt vector namely 33h. On generating an interrupt, the mouse driver
\r
1421 expects a function number in AX and possibly other parameters in other
\r
1422 registers and returns information via the registers. A brief description
\r
1423 of the mouse functions follows:
\r
1425 --------------------------------------
\r
1427 MS Mouse Driver Functions
\r
1429 Mouse Initialization 0
\r
1432 Get Mouse Position & Button Status 3
\r
1433 Set Mouse Cursor Position 4
\r
1434 Get Button Press Information 5
\r
1435 Get Button Release Information 6
\r
1436 Set Min/Max Horizontal Position 7
\r
1437 Set Min/Max Vertical Position 8
\r
1438 Define Graphics Cursor Block 9
\r
1439 Define Text Cursor 10
\r
1440 Read Mouse Motion Counters 11
\r
1441 Define Event Handler 12
\r
1442 Light Pen Emulation Mode ON 13
\r
1443 Light Pen Emulation Mode OFF 14
\r
1444 Set Mouse Mickey/Pixel Ratio 15
\r
1445 Conditional Hide Cursor 16
\r
1446 Set Double-Speed Threshold 19
\r
1447 --------------------------------------
\r
1449 In practice only afew of these functions are used and even fewer when the
\r
1450 mouse status is monitored by an event handler function such as is used in
\r
1453 The most important thing to note when using the mouse module is that the
\r
1454 mouse event handler must be removed before exiting the program. It is a good
\r
1455 idea to have an exit function (see the C "atexit" function) and include the
\r
1456 line "x_mouse_remove();" along with any other pre-exit cleanup code.
\r
1461 xmouse.asm xlib.inc model.inc
\r
1467 EXPORTED VARIABLES
\r
1469 MouseInstalled - WORD - Indicates whether mouse handler installed
\r
1470 MouseHidden - WORD - Indicates whether mouse cursor is hidden
\r
1471 MouseButtonStatus - WORD - Holds the mouse button status
\r
1472 MouseX - WORD - Current X position of mouse cursor
\r
1473 MouseY - WORD - Current Y position of mouse cursor
\r
1474 MouseFrozen - WORD - Disallows position updates if TRUE
\r
1475 MouseColor - BYTE - The mouse cursors colour
\r
1477 EXPORTED FUNCTIONS
\r
1482 C Prototype: int x_mouse_init()
\r
1484 Initialize the mouse driver functions and install the mouse event handler
\r
1485 function. This is the first function you must call before using any of the
\r
1486 mouse functions. This mouse code uses the fastest possible techniques to
\r
1487 save and restore mouse backgrounds and to draw the mouse cursor.
\r
1489 WARNING: This function uses and updates "NonVisual_Offset" to allocate
\r
1490 video ram for the saved mouse background.
\r
1492 LIMITATIONS: No clipping is supported horizontally for the mouse cursor
\r
1493 No validity checking is performed for NonVisual_Offs
\r
1495 **WARNING** You must Hide or at least Freeze the mouse cursor while drawing
\r
1496 using any of the other XLIB modules since the mouse handler may
\r
1497 modify vga register settings at any time. VGA register settings
\r
1498 are not preserved which will result in unpredictable drawing
\r
1499 behavior. If you know the drawing will occur away from the
\r
1500 mouse cursor set MouseFrozen to TRUE (1), do your drawing
\r
1501 then set it to FALSE (0). Alternatively call "x_hide_mouse",
\r
1502 perform your drawing and then call "x_show_mouse". Another
\r
1503 alternative is to disable interrupts while drawing but usually
\r
1504 drawing takes up alot of time and having interrupts disabled
\r
1505 for too long is not a good idea.
\r
1507 x_define_mouse_cursor
\r
1508 ---------------------
\r
1511 void x_define_mouse_cursor(char far *MouseDef, unsigned char MouseColor)
\r
1513 MouseDef - a pointer to 14 characters containing a bitmask for all the
\r
1515 MouseColor - The colour to use when drawing the mouse cursor.
\r
1517 Define a mouse cursor shape for use in subsequent cursor redraws. XMouse
\r
1518 has a hardwired mouse cursor size of 8 pixels across by 14 pixels down.
\r
1520 WARNING: This function assumes MouseDef points to 14 bytes.
\r
1522 Note: Bit order is in reverse. ie bit 7 represents pixel 0 ..
\r
1523 bit 0 represents pixel 7 in each "MouseDef" byte.
\r
1528 C Prototype: void x_show_mouse()
\r
1530 Makes the cursor visible if it was previously hidden.
\r
1531 See Also: "x_hide_mouse".
\r
1536 C Prototype: void x_hide_mouse()
\r
1538 Makes the cursor hidden if it was previously visible.
\r
1539 See Also: "x_show_mouse".
\r
1544 C Prototype: void x_mouse_remove()
\r
1546 Stop mouse event handling and remove the mouse handler.
\r
1548 NOTE: This function MUST be called before quitting the program if
\r
1549 a mouse handler has been installed
\r
1554 C Prototype void x_position_mouse(int x, int y)
\r
1556 Positions the mouse cursor at the specified location
\r
1561 C Prototype: void x_mouse_window(int x0, int y0, int x1, int y1)
\r
1563 Defines a mouse window.
\r
1568 C Prototype: void x_update_mouse()
\r
1570 Forces the mouse position to be updated and cursor to be redrawn.
\r
1571 Note: this function is useful when you have set "MouseFrozen" to true.
\r
1572 Allows the cursor position to be updated manually rather than
\r
1573 automatically by the installed handler.
\r
1576 --------------------------------------------------------------------------
\r
1578 --------------------------------------------------------------------------
\r
1580 This module implements a set of functions to convert between planar
\r
1581 bitmaps and linear bitmaps.
\r
1585 Planar bitmaps as used by these functions have the following structure:
\r
1587 BYTE 0 The bitmap width in bytes (4 pixel groups) range 1..255
\r
1588 BYTE 1 The bitmap height in rows range 1..255
\r
1589 BYTE 2..n1 The plane 0 pixels width*height bytes
\r
1590 BYTE n1..n2 The plane 1 pixels width*height bytes
\r
1591 BYTE n2..n3 The plane 2 pixels width*height bytes
\r
1592 BYTE n3..n4 The plane 3 pixels width*height bytes
\r
1594 as used by x_put_pbm, x_get_pbm, x_put_masked_pbm.
\r
1598 Linear bitmaps have the following structure:
\r
1600 BYTE 0 The bitmap width in pixels range 1..255
\r
1601 BYTE 1 The bitmap height in rows range 1..255
\r
1602 BYTE 2..n The width*height bytes of the bitmap
\r
1606 xbmtools.asm xpbmtools.inc model.inc
\r
1616 LBMHeight(lbitmap) - Height of linear bitmap "lbitmap"
\r
1617 LBMWidth(lbitmap) - Width of linear bitmap "lbitmap"
\r
1618 PBMHeight(pbitmap) - Height of planar bitmap "pbitmap"
\r
1619 PBMWidth(pbitmap) - Width of planar bitmap "pbitmap"
\r
1621 LBMPutPix(x,y,lbitmap,color) - set pixel (x,y) colour in linear bitmap
\r
1622 LBMGetPix(x,y,lbitmap) - colour of pixel (x,y) in linear bitmap
\r
1628 C Prototype: extern int x_pbm_to_bm(char far * source_pbm,
\r
1629 char far * dest_bm);
\r
1631 This function converts a bitmap in the planar format to the linear format
\r
1632 as used by x_compile_bitmap.
\r
1634 WARNING: the source and destination bitmaps must be pre - allocated
\r
1636 NOTE: This function can only convert planar bitmaps that are suitable.
\r
1637 If the source planar bitmap's width (per plane) is >= 256/4
\r
1638 it cannot be converted. In this situation an error code
\r
1639 BM_WIDTH_ERROR. On successful conversion 0 is returned.
\r
1643 C Prototype: extern int x_bm_to_pbm(char far * source_pbm,
\r
1644 char far * dest_bm);
\r
1646 This function converts a bitmap in the linear format as used by
\r
1647 x_compile_bitmap to the planar formap.
\r
1649 WARNING: the source and destination bitmaps must be pre - allocated
\r
1651 NOTE: This function can only convert linear bitmaps that are suitable.
\r
1652 If the source linear bitmap's width is not a multiple of 4
\r
1653 it cannot be converted. In this situation an error code
\r
1654 BM_WIDTH_ERROR. On successful conversion 0 is returned.
\r
projects / 16.git / blob