

                           MaLiCe VeSa LiBrARy 
                                    v 1.0 

                            by MaLiCe / WitchCraft

                                 August 1998 






        This library is donated to the public domain, wich means you can
        do whatever you want with it, as long as all files are distributed
        together and kept unmodified.


        I assume no responsibility for whatever damage the info contained
        in this file (or the files wich accompany it) could cause on you or
        your computer.



  ʹ INDEX     

           1. Introduction

           2. Getting started
                2.1 Linking with Watcom
                2.2 General use
                2.3 An example

           3. Functions description
                3.1 Introduction
                3.2 Implemented functions

           4. Contacting






  ʹ 1. Introduction     

        The purpose of this library is to provide an interface to handle
        VBE 2.0 standard functions.
        The library is 100% asm but is thought to be used with Watcom.
        It supports linear frame buffer and 256 & Direct Color modes
        (High Color and True Color). It doesn't support banks as any
        video hardware supports lfb nowadays.
        Appart from the basic functions, it also offers support for virtual
        screens and handling display windows (see vbeSetStart).
        For a detailed description of each function, refer to section 3.



  ʹ 2. Getting started     

        2.1 Linking with Watcom

        If you wanna be able to use the functions in this library, you must
        include the file VESA.H in each of your modules that will use
        the library functions.
        Then, at linking time, simply join the file VESA.OBJ to your own
        modules.
        It's that easy.


        2.2 General use

        To use this library in your own productions is really simple.
        Before all, on startup, you must call vbeInit function, wich will
        fill up VbeInfoBlock with data from video hardware, etc.
        When done this, just init a video mode calling vbeSetMode function.
        This will get info about the asked mode and store it in the
        ModeInfoBlock struct. It also will init the mode, if the hardware
        supports it.

        Both structs (VbeInfoBlock & ModeInfoBlock) are public, so you can
        access them anywhere in your program. If you wanna know the format
        of these structs, take a look at VESA.H.

        The vbeSetMode function will also set up an VBESCREEN struct passed
        to it via a pointer.
        This type of struct contains data about the physical screen, as
        width and height, as well as LFB address.
        Appart from the physical screen, every virtual screen will also have
        associated an structure of this type.
        This way, if you want to have a virtual screen, you only have to
        declare an struct of type VBESCREEN and pass a pointer to this struct
        to the vbeSetVirtual function. Don't forget to free up the allocated
        memory calling vbeFreeVirtual at the end of your program.

        Inside your proggy, you may use vbeFlip function to copy a screen
        (either virtual or physical) onto another. Note that vbeFlip uses
        current video mode attributes to fill up the struct you are passing
        to it. You shouldn't flip between screens that were allocated when
        different modes were on. Free up screens and allocate them again
        with the new video mode instead.

        Appart from this, 4bpp modes are not well supported (try to select
        a 4bpp mode in the sample prog VESA.EXE and you'll notice that the
        proggy fails when trying to allocate a virtual screen). Personally,
        I've never used them and won't ever do it, so don't expect this
        problem to be solved soon. :)


        2.3 An example

        If you wanna see an example on the use of this library, take a look
        at the file VESATEST.CPP.

        However, I will briefly list the steps you must follow to use this
        lib correctly.

                1. Declare a VBESCREEN structure for your physical (and
                   logical, if any) screen

                2. Call vbeInit

                3. Call vbeSetMode with whatever mode you want

                4. If you are to use virtual screens, call vbeSetVirtual
                   with each virtual screen

                5. Do your stuff...

                6. Deallocate virtual screens (if any) calling vbeFreeVirtual
                   with each screen

                7. If you want to use another mode, repeat from step #3



  ʹ 3. Functions description     

        3.1 Introduction

        As you may have realised, every function name starts with 'vbe'.
        This was made this way to avoid possible coincidences with your
        functions, and as a way to identify all the functions belonging
        to this library.

        Secondly, most of the functions return 0 if success, except those
        functions wich are expected to return an specific value (like
        vbeGetScanWidth), or those functions wich are not expected to fail
        in any way (like vbeWR).


        3.2 Implemented functions

        - vbeInit               Inits Vesa BIOS Extentions and fills up
                                VbeInfoBlock structure with the hardware
                                info, a list of supported modes and the
                                current VBE version.
                In:             None
                Out:            Error code
                        00 - Ok
                        01 - VBE not installed
                        02 - Not enough memory
                        03 - DPMI error

        - vbeGetModeInfo        Gets info about a certain video mode and
                                fills up ModeInfoBlock structure with info
                                about it.
                In:             short mode
                Out:            Error code
                        00 - Ok
                        01 - VBE not installed
                        02 - Not enough memory
                        03 - DPMI error

        - vbeSetMode            Sets asked video mode by calling
                                vbeGetModeInfo to check out that the mode
                                exists and it's supported by hardware.
                                Fills up the VBESCREEN structure.
                In:             short Xres, short Yres, char Bpp,
                                VBESCREEN *screen
                Out:            Error code
                        00 - Ok
                        02 - Not enough memory
                        04 - Mode not supported

        - vbeSetVirtual         Allocates memory for a virtual screen with
                                the asked size and fills up the VBESCREEN
                                struct.
                In:             short Xres, short Yres, VBESCREEN *screen
                Out:            Error code
                        00 - Ok
                        02 - Not enough memory

        - vbeFreeVirtual        Frees the memory allocated by vbeSetVirtual
                                for the asked screen.
                In:             VBESCREEN *screen
                Out:            Error code
                        00 - Ok
                        05 - Memory error

        - vbeFlip               Copies a screen (either physical or virtual)
                                to another. This function only considers the
                                size of the destination screen.
                In:             VBESCREEN *org, VBESCREEN *dst
                Out:            None

        - vbeClearScreen        Clears a screen with the background color
                                in 256 color modes or with black in
                                Direct Color modes.
                In:             VBESCREEN *screen
                Out:            None

        - vbePutPixel           Plots a pixel at the specified coordinates
                                with the specified color. Note that in 256
                                color modes the first color parameter should
                                be used as the pallete index. Both g and b
                                won't be considered.
                In:             short Xpos, short Ypos, VBESCREEN *screen,
                                char r, char g, char b
                Out:            None

        - vbeSetScanWidth       Sets scanline width to specified width.
                In:             short width
                Out:            Error code
                        00 - Ok
                        01 - VBE error

        - vbeGetScanWidth       Returns current scanline width.
                In:             None
                Out:            short width
                        00 - Error

        - vbeSetStart           Sets display start position at specified
                                coordinates.
                In:             short Xcoord, short Ycoord
                Out:            Error code
                        00 - Ok
                        01 - VBE error

        - vbeGetStart           Gets current display start position and
                                returns coordinates at specified pointers.
                In:             short *Xcoord, short *Ycoord
                Out:            Error code
                        00 - Ok
                        01 - VBE error

        - vbeSetVGAMode         Sets a VGA compatible video mode, calling
                                BIOS 00h function.
                In:             char mode
                Out:            None

        - vbeGetVGAMode         Returns current VGA compatible mode.
                In:             None
                Out:            char mode

        - vbeWR                 Wais for vertical retrace.
                In:             None
                Out:            None



  ʹ 4. Contacting     

        If you wanna contact me for any reason, to make any question, spot
        any bug or whatever, drop me an email at this address:

                MaLiCe@SoftHome.net

        You may also find me at IRC, on #coders (Efnet).

        Well, thats all folks. I hope this will be enough to start yourself
        with this library. I know it is not complete at all, but is more
        than enough for my purposes, so don't expect new versions. Anyway,
        if you end up using this in your productions, it would be nice if
        you mentioned me anywhere (you know, give credit where credit is due).

        Greetz to Vertigo for their tut on VESA. It helped a lot.


                        MaLiCe
