Video Drivers (QLIB v2.02+)

Header files:
  C: video.h
  ASM: video.inc

Notes:
  All functions can be used in ANY video mode except for the palette
    things in modes with bpp>8.
  t_setmode() and g_setmode() both will first call an uninit procedure
    to cleanup the current mode.  It will also disable the mouse if
    it is shown.
-----------------------------------------------------------------------------
Function: g_getmode(word x,word y,byte bpp)
Expects: x,y,bpp - x/y Res and BPP (bits per pixel) desired
Outputs:
  if successful the mode is available and one of the following is returned:
    G_VGA = the mode is a VGA mode (320x200x8bit)
    G_VESA = the mode is a VESA mode
    G_MODEX = the mode is a modeX mode
  if not successful
    AX = ERROR (-1)
Notes:
  If you are using these grafix routines do not call INT 10h to change the
  video mode at anytime, even to switch back to text mode.  See t_setmode().
-----------------------------------------------------------------------------
Function: g_setmode(void)
Expects: nothing.
Outputs: nothing.
Notes:
  Sets last mode successful tested by g_getmode()
-----------------------------------------------------------------------------
Function: g_waitvsync(void)
Expects: nothing.
Outputs: nothing.
Notes:
  Waits till there is a v sych (use this before palette changes etc.)
-----------------------------------------------------------------------------
--------------------------Text functions-------------------------------------
-----------------------------------------------------------------------------
Function: t_setmode(word x,word y)
Expects: (x,y) = text rows/columns
Outputs: nothing.
Notes:
  Sets the video mode to text mode with x,y.
  Currently only 80x25 and 80x50 are supported.
-----------------------------------------------------------------------------
Function: t_printf(word x,word y,char *string,...)
Expects: (x,y) = text rows/columns
Outputs: Formatted output to temp area (set by g_setbuf())
-----------------------------------------------------------------------------
Function: t_printxy(word x,word y,char *string)
Expects: (x,y) = text rows/columns
Outputs: Outputs string to temp area
-----------------------------------------------------------------------------
Function: t_box1(word x1,word y2,word x2,word y2)
Expects: (x1,y1)-(x2,y2) = box to draw
Outputs: Draws a single line box in temp area.
-----------------------------------------------------------------------------
Function: t_box2(word x1,word y2,word x2,word y2)
Expects: (x1,y1)-(x2,y2) = box to draw
Outputs: Draws a double line box in temp area.
-----------------------------------------------------------------------------
Function: t_boxfill(word x1,word y2,word x2,word y2,word char)
Expects: (x1,y1)-(x2,y2) = box to fill in with char
         char = char + color to draw
Outputs: Fills in box with char (with colour)
-----------------------------------------------------------------------------
Function: t_backboxfill(word x1,word y2,word x2,word y2,byte clr)
Expects: (x1,y1)-(x2,y2) = box to fill in with color
         clr = color to draw with
Outputs: Fills in box with colour
-----------------------------------------------------------------------------
Function: t_savestate(void)
Expects: nothing
Outputs: (void *)
Notes:
  Saves the entire state of the video card. For use in text mode only!
  This function will alloc RAM as needed using malloc()
-----------------------------------------------------------------------------
Function: t_restorestate(void *vstate)
Expects: vstate which was returned by t_savestate()
Outputs: nothing
Notes:
  Restores video state using vstate that was returned by t_savestate().
  Does NOT free memory malloc()'ed by t_savestate().
  Use free() to free the memory when you no longer need it.
-----------------------------------------------------------------------------
--------------------------VESA functions-------------------------------------
-----------------------------------------------------------------------------
These funcs are avail only if you want to view VESA info but it is not
necessary to use them to utilize VESA video modes.
-----------------------------------------------------------------------------
Function: vesa_init(void)
Expects: nothing.
Outputs:
  if successful
    AX = VESA version  (BCD coded ie: v2.00 = 200h and v1.20 = 102h)
  if not successful
    AX = ERROR (-1)
-----------------------------------------------------------------------------
Function: vesa_func06(void)
Expects:    BL   = 00h          Set Scan Line Length in Pixels
                 = 01h          Get Scan Line Length
                 = 02h          Set Scan Line Length in Bytes
                 = 03h          Get Maximum Scan Line Length
            CX   =         If BL=00h  Desired Width in Pixels
                           If BL=02h  Desired Width in Bytes
                           (Ignored for Get Functions)
Output:     AX   =         VBE Return Status
            BX   =         Bytes Per Scan Line
            CX   =         Actual Pixels Per Scan Line
                           (truncated to nearest complete pixel)
            DX   =         Maximum Number of Scan Lines
Notes:
  VBE Function 06h - Set/Get Logical Scan Line Length
  Directly calls INT 10h AX=4F06h;
  Calling this function saves the "Bytes Per Scan Line" returned
    in BX which is required for correct operation of vesa_setstart().
-----------------------------------------------------------------------------
Function: vesa_setstart(dword start,dword scan)
Expects:
  start = pixel start
  scan = scan line
Notes:
  This sets the starting position printed on screen (the physical upper-left
    corner of the screen within the logical video memory)
  Using this function will mess up most of the grafix functions provided
    by QLIB.
-----------------------------------------------------------------------------
Function: vesa_firstmode()
Expects:  nothing
Returns:  if successful:
             EAX = 0
             vesa_modeinfo struct holds info about first mode
          if unsuccessful:
             EAX = -1 (ERROR)
             vesa_modeinfo struct is undefined
Notes:
  Returns info about the 1st mode available.  If this fails
    there are NO available modes.
  Only modes that hareware supports shall be returned.
-----------------------------------------------------------------------------
Function: vesa_nextmode()
Expects:  nothing
Returns:  if successful:
             EAX = 0
             vesa_modeinfo struct holds info about mode
          if unsuccessful:
             EAX = -1 (ERROR)
             vesa_modeinfo struct is undefined
Notes:
  Returns info about next mode available.  If this fails
  there are no more available modes.
  Only modes that hareware supports shall be returned.
  You may use vesa_firstmode() and vesa_nextmode() as many times as
    you like to look thru the VESA modes.
-----------------------------------------------------------------------------
  Standard Video Routines
-----------------------------------------------------------------------------
Function: g_setbuf(void * temparea)
Expects: temparea - temp area for driver to use
Outputs: nothing.
Notes:
  Sets the block of RAM that is used to copy to video RAM by g_copy()
  See Appendix A below for explaintion of this function.
-----------------------------------------------------------------------------
Function: g_copy(void)
Expects: nothing.
Outputs: nothing.
Notes:
  Copys RAM from temparea to video RAM.
  This function can NOT be called during an IRQ handler.
  See Appendix A below for explaintion of this function.
-----------------------------------------------------------------------------
Function: g_setpal(void * pal)
Expects: pal - 768 bytes representing the data
Outputs: nothing.
Notes:
  Sets the entire 256 color palette of the VGA card.
-----------------------------------------------------------------------------
Function: g_setcol(byte c,byte r,byte g,byte b)
Expects: c - color # to change
         r,g,b - red/green/blue intensitys
Outputs: nothing.
Notes:
  Sets one color in the 256 color palette of the VGA card.
  The intensitys can be from 0 to 63 each.
-----------------------------------------------------------------------------
Function: g_cls(void)
Expects: nothing.
Outputs: nothing.
Notes:
  Clears the temp area with 0x00 and then calls g_copy().
-----------------------------------------------------------------------------
Function: g_get(byte * buf,word x1,word y1,word x2,word y2)
Expects: buf = RAM to store grafix image
         (x1,y1)-(x2-y2) = dimension of image to get
Outputs: nothing.
Notes:
  Copies a rectangle image from the temp area to buf. (NOT the video RAM)
  Full clipping is performed.
-----------------------------------------------------------------------------
Function: g_put(byte * buf,word x1,word y1,word x2,word y2)
Expects: buf = RAM to get grafix image from
         (x1,y1)-(x2-y2) = dimension of image to put
Outputs: nothing.
Notes:
  Copies a rectangle image from the buf to temp area. (NOT the video RAM)
  Full clipping is performed.
-----------------------------------------------------------------------------
Function: g_put0(byte * buf,word x1,word y1,word x2,word y2)
Expects: buf = RAM to get grafix image from
         (x1,y1)-(x2-y2) = dimension of image to put
Outputs: nothing.
Notes:
  Copies a rectangle image from the buf to temp area. (NOT the video RAM)
  Full clipping is performed.
  This call is identical to g_put() except this func will NTO plot color 0
  pixels.
-----------------------------------------------------------------------------
Function: g_putb0(byte * buf,word x1,word y1,word x2,word y2,dword clr)
Expects: buf = RAM to get grafix image from
         (x1,y1)-(x2-y2) = dimension of image to put
         clr = color to print
Outputs: nothing.
Notes:
  Copies a rectangle image from the buf to temp area. (NOT the video RAM)
  Full clipping is performed.
  This call is identical to g_put() except this func will be plot color 0
  pixels and the source (buf) must be bitpacked, which means that each
  pixel is represented by a bit, regardless of the current screens color
  depth.  This function is mainly used by the mouse/font routines and may
  provide little use to most users since there is no g_getb() function
  provided.
-----------------------------------------------------------------------------
Function: g_line(dword x1,dword y1,dword x2,dword y2,dword clr)
Expects: (x1,y1)-(x2-y2) = line
         clr = color to use
Outputs: nothing.
Notes:
  Draws a line that is clipped to viewport.
  This may be called when mouse cursor is visable.
-----------------------------------------------------------------------------
Function: g_getpixel(dword x,dword y)
Expects: (x,y) = point to get
Outputs:
  if (x,y) is within viewport
    Returns color of pixel
  else
    Returns 0
Notes:
  Reads a pixel's color.
  This may be called when mouse cursor is visable.
-----------------------------------------------------------------------------
Function: g_putpixel(dword x,dword y,dword clr)
Expects: (x1,y1) = point
         clr = color to use
Outputs: nothing.
Notes:
  Draws a pixel that is clipped to viewport.
  This may be called when mouse cursor is visable.
-----------------------------------------------------------------------------
Function: g_window(word x1,word y1,word x2,word y2)
Expects: (x1,y1)-(x2-y2) = viewport
Outputs: nothing.
Notes:
  Changes the current viewport to which all clipping is performed to.
  This effects : g_get(), g_put(), g_put0(), g_putb0() and the mouse.
  This may NOT be called when mouse cursor is visable.
-----------------------------------------------------------------------------
Mouse Services
  Make sure to read Appendix B to see how these functions work in text mode.
-----------------------------------------------------------------------------
Function: mouse_init(void)
Expects: nothing.
Outputs:
  if successful (mouse driver was detected)
    AX = 0
  if not successful (no mouse driver detected)
    AX = ERROR (-1)
-----------------------------------------------------------------------------
Function: mouse_loadcursor(char * filename)
Expects: filename = cursor filename (*.PTR)
Outputs: void * = cursor memory location
Notes:
  This may NOT be called when mouse cursor is visable.
  This func uses malloc() to reserve room for the cursor.  Use free() with
    the returned pointer to free the cursor when you no longer need it.
  The current cursor will be set to the cursor loaded if successful.
-----------------------------------------------------------------------------
Function: mouse_setcursor(void * cursor)
Expects: cursor = cursor returned from mouse_loadcursor()
Outputs: nothing.
Notes:
  This function must be called before using mouse_on().
  This may be called when mouse cursor is visable.
-----------------------------------------------------------------------------
Function: mouse_setcolor(dword color)
Expects: color = color of mouse cursor
Outputs: nothing.
Notes:
  This may be called when mouse cursor is visable.
  Text Modes:
    This function must be called before using mouse_on() in text mode.
    The color will simply be XORed into the text video memory on the char
      at that position.
    color = (colour_desired) << 4;
    Therefore the color_desired can be from 0-15.  If the other bits are
      set the mouse cursor may cause letters to blink, etc.
  Grafix Modes:
    Changes color of cursor when using bit-packed cursors.
    Has no effect on color cursors.
-----------------------------------------------------------------------------
Function: mouse_setspd(byte xratio,byte yratio)
Expects: xration = speed the cursor travels across screen
         yration = speed the cursor travels up-down screen
Outputs: nothing.
Notes:
  Valid speeds are (1=fastest ... 4=slowest)
  This may be called when mouse cursor is visable.
-----------------------------------------------------------------------------
Function: mouse_setwin(word x1,word y1,word x2,word y2)
Expects: (x1,y1)-(x2,y2) = rectangle box coords
Outputs: nothing.
Notes:
  Sets window that mouse is allowed to be in (with respect to hotspot).
  Mouse will be moved to within box and will not be able to leave area.
-----------------------------------------------------------------------------
Function: mouse_on(void)
Expects: nothing.
Outputs: nothing.
Notes:
  Shows the mouse on screen.
-----------------------------------------------------------------------------
Function: mouse_off(void)
Expects: nothing.
Outputs: nothing.
Notes:
  Hides the mouse.  You must call this before changing to another video
    mode if the mouse is currently shown.
  You do not need to call mouse_off() to edit the temparea or when using
    g_copy()
-----------------------------------------------------------------------------
Function: mouse_setuser(dword user,struct mouse_user *)
Expects: user = your function offset
         mouse_user = ptr to mouse_user struct
Outputs: nothing.
Notes:
  When ever the mouse is moved or a button is pushed/released the user
    function will be called.
  Your function will be executing in an IRQ handler so it must not
    call DOS or anything much else.
  The only thing you should do is use mouse_setcursor() and/or
    mouse_setcolor().
  The function is called with the following set with in mouse_user:
    mouse_user.x = X pos
    mouse_user.y = Y pos
    mouse_user.but = button status'   (bit 0=left  1=right)
  The function must return with 'RET'.
  You do not need to preserve registers.
-----------------------------------------------------------------------------
Function: mouse_setpos(word x,word y)
Expects:  (x,y) = new mouse position
Outputs: nothing.
Notes:
  Sets a new position of the mouse.  The mouse may be hidden or visible.
-----------------------------------------------------------------------------
Grafix Text Services
-----------------------------------------------------------------------------
Function: g_loadfnt(char * fntname)
Expects:
  fntname = filename of font file (*.FNT)
Outputs:
  if successful:
    EAX = address of FONT location.
  if not successful:
    EAX = -1 (ERROR)
Notes:
  g_loadfnt() will alloc RAM for the font and set it as the current font
    if successful.
  The DWORD returned can be used with g_setfnt() in case you have more
    than one font loaded.
  To free the font just call free() with the DWORD returned from g_loadfnt().
-----------------------------------------------------------------------------
Function: g_setfnt(void * buffer)
Expects:
  buffer = DWORD (or (void*) same thing!) that was returned from g_loadfnt()
Outputs: nothing.
Notes:
  Sets current font to what ever is in buffer.
-----------------------------------------------------------------------------
Function: g_putch(word x,word y,byte char)
Expects:
  (x,y) = top-left cord to print char
  char = char to print
Outputs: nothing.
Notes:
  Uses current font to print one char at (x,y).
-----------------------------------------------------------------------------
Function: g_printxy(word x,word y,byte * str1)
Expects:
  (x,y) = top-left cord to print string
  str1 = string to print (not formatted)
Outputs: nothing.
Notes:
  Uses current font to print string at (x,y).
-----------------------------------------------------------------------------
Function: g_printf(word x,word y,byte * str1,...)
Expects:
  (x,y) = top-left cord to print string
  str1 = string to print (formatted)
  ... = other paras needed by printf
Outputs: nothing.
Notes:
  Uses current font to print string at (x,y).
-----------------------------------------------------------------------------
Misc stuff
-----------------------------------------------------------------------------
Function: g_hline(word x1,word y1,word x2,dword col)
Expects:
  (x1,y1) = top-left pixel to start drawing horizontal line.
  x2 = right pixel to stop at
  col = color to draw
Outputs: nothing.
Notes:
  Supports multi-depth modes.
-----------------------------------------------------------------------------
Function: g_vline(word x1,word y1,word y2,dword col)
Expects:
  (x1,y1) = top-left pixel to start drawing vertical line.
  y2 = bottom pixel to stop at
  col = color to draw
Outputs: nothing.
Notes:
  Supports multi-depth modes.
-----------------------------------------------------------------------------

Appendix's

Appendix A:  How to use the grafix library.

     The basic idea behind these functions is that you create an image to
  be displayed on the screen and then have it copied to the video RAM with
  g_copy().  The driver will handle cases like keeping the mouse on the
  screen (which will not even blink during g_copy()).  First you setup
  the screen using g_getmode() and g_setmode().  Then alloc yourself enough
  RAM for the temparea where you will create images to be displayed.  Tell
  the video functions where this temparea is by using g_setbuf().  Then
  when ever you have an image ready to be displayed simply call g_copy().
  Make sure to use t_setmode() to return back to text mode so that
  the grafix functions can free any buffers used.

Appendix B: Using the mouse functions in text mode.

     Using the mouse driver in text mode is a little akward.  First call
  mouse_init() as you always should (do it only once ever time a program
  is used).  Then simply use t_setmode() to setup which mode you want to
  use.  Then use mouse_setcolor().  Now you can call mouse_on()
  and mouse_off().  When the callback feature (ie: mouse_setuser()) calls
  your function the (x,y) coords within the struct will NOT represent the
  current X,Y of the cursor in cel rows/columns.  Instead it represents
  the current pixel (x,y) assuming that each cell is 8x8 (regardless of
  what it really is).  So basically divide the X and Y by 8 to find
  it's cell value.

Keep in touch with my page at http://www.geocities.com/SiliconValley/Peaks/1231
E-Mail : sub_death@geocities.com

