

                           MaLiCe VeSa LiBrARy 
                                    v 1.0 

                            by MaLiCe / WitchCraft

                                 Agosto 1998 






        Esta librera es de dominio pblico, lo que significa que puedes
        hacer con ella lo que quieras, siempre y cuando todos los archivos
        sean distribuidos conjuntamente y sin ninguna clase de modificacin.


        No me hago responsable de los daos que pueda causar el uso de lo
        que se dice en este texto o de los archivos que lo acompaan.




  ʹ INDICE     

           1. Introduccin

           2. Cmo usar esta librera
                2.1 Linkando con Watcom
                2.2 Uso general
                2.3 Un ejemplo

           3. Descripcin de las funciones
                3.1 Introduccin
                3.2 Funciones implementadas

           4. Contactando conmigo






  ʹ 1. Introduccin     

        El propsito de esta librera es ofrecer un soporte para el manejo
        de las funciones del estndar VBE 2.0.
        Est programada ntegramente en ensamblador, pero est pensada para
        usarse con Watcom.
        La librera tiene soporte para linear frame buffer y modos de 256
        colores y Direct Color (High Color y True Color). No tiene soporte
        para bancos, porque todas las tarjetas actuales soportan LFB.
        Aparte de las funciones bsicas, ofrece tambin soporte para
        pantallas virtuales y algunas funciones bsicas para el manejo de
        ventanas en videoram.
        Para una descripcin detallada de todas las funciones implementadas,
        puedes consultar la seccin 3.



  ʹ 2. Cmo usar esta librera     

        2.1 Linkando con Watcom

        Para poder utilizar las funciones de esta librera, lo nico que hay
        que hacer es incluir el fichero VESA.H en todos los mdulos que
        utilicen funciones de la misma.
        A la hora de linkar, simplemente une todos los mdulos con el
        mdulo VESA.OBJ que acompaa a este fichero.
        As de fcil.



        2.2 Uso general

        El uso de la librera dentro de un mdulo es realmente sencillo.
        Antes de nada, al comienzo del programa, es imprescindible llamar
        a la funcin vbeInit, que llenar la estructura VbeInfoBlock con
        datos de la tarjeta de vdeo, de la versin de VBE soportada, etc.
        Una vez hecho esto, basta con incializar un modo de vdeo llamando
        a la funcin vbeSetMode. Esta funcin llenar la estructura
        ModeInfoBlock con datos sobre el modo de vdeo pedido, y activar
        ese modo, si la tarjeta lo soporta.

        Ambas estructuras (VbeInfoBlock y ModeInfoBlock) son globales, por
        lo que puedes acceder a ellas en cualquier momento desde tu programa.
        Para conocer el formato de ambas estructuras puedes echarle un
        vistazo al archivo VESA.H.

        La funcin vbeSetMode llenar tambin una estructura de tipo
        VBESCREEN que le debes pasar al llamarla por medio de un puntero.

        Este tipo de estructura contiene datos sobre la pantalla fsica,
        como son el ancho y el alto, adems de la direccin del LFB.
        Aparte de la pantalla fsica, todas las pantallas virtuales tendrn
        tambin asociada una estructura de este tipo.
        De esta forma, si quieres usar una pantalla virtual, slo tienes que
        declarar una estructura tipo VBESCREEN y pasarle un puntero a la
        misma a la funcin vbeSetVirtual, que te devolver un puntero al
        bloque de memoria reservado para la pantalla. No olvides llamar a la
        funcin vbeFreeVirtual al final del programa para liberar la memoria
        reservada.

        Dentro del programa puedes utilizar la funcin vbeFlip para volcar
        el contenido entre pantallas virtuales o a la pantalla fsica.
        Debes tener en cuenta que la funcin vbeSetVirtual toma los datos
        del modo actual para rellenar la estructura que le pasas. No conviene
        que hagas volcados entre pantallas que han sido reservadas cuando
        haba un modo de video diferente. En lugar de esto, libera la
        pantalla y vuelve a reservarla una vez hayas cambiado el modo de
        video.

        Por otro lado, los modos de video de 4 bits por pixel no son
        soportados adecuadamente (prueba a elegir un modo de 4bpp en el
        programa VESA.EXE y vers que falla al intentar reservar una
        pantalla virtual). Personalmente no los he usado nunca ni los pienso
        usar, as que no creo que este problema se arregle pronto :)


        2.3 Un ejemplo

        Para ver un ejemplo de como utilizar muchas de las funciones de
        esta librera puedes consultar el fuente VESATEST.CPP.

        De todas formas, aqu pongo los principales pasos que hay que seguir
        en un programa para utilizarla correctamente.

                1. Declarar una estructura tipo VBESCREEN para la pantalla
                   fsica y, opcionalmente, otras para las pantallas
                   virtuales

                2. Llamar a la funcin vbeInit

                3. Llamar a vbeSetMode

                4. Si se van a utilizar pantallas virtuales, llamar a
                   vbeSetVirtual para cada una de las pantallas

                5. Aqu vendra el programa principal...

                6. Si se han usado pantallas virtuales, llamar a
                   vbeFreeVirtual para cada una de ellas

                7. En caso de querer usar otro modo de video ms, repetir
                   desde el paso n3



  ʹ 3. Descripcin de las funciones     

        3.1 Introduccin

        Como habrs podido observar todos los nombres de las funciones
        comienzan por 'vbe'. Esto se ha hecho as como medio para identificar
        las funciones y para evitar posibles coincidencias con los nombres
        de tus funciones.

        Por otro lado, la mayora de las funciones devuelven un 0 en caso
        de que todo haya ido bien, excepto aquellas funciones que tienen
        que devolver algn valor especfico (como vbeGetScanWidth o
        vbeGetVGAMode) o aquellas en las que no se espera que pueda haber
        ningn tipo de error (como vbeWR).


        3.2 Funciones implementadas

        - vbeInit               Inicializa el VBE y llena la estructura
                                VbeInfoBlock con informacin sobre la tarjeta
                                de video, los modos de vdeo que soporta, y
                                la versin de VBE.
                Entrada:        Ninguna
                Salida:         Cdigo de error
                        00 - Ok
                        01 - VBE 2.0 no instalado
                        02 - No hay suficiente memoria
                        03 - Error de DPMI

        - vbeGetModeInfo        Obtiene informacin acerca de un determinado
                                modo de vdeo y llena la estructura
                                ModeInfoBlock con informacin acerca de ste.
                Entrada:        short modo
                Salida:         Cdigo de error
                        00 - Ok
                        01 - VBE 2.0 no instalado
                        02 - No hay suficiente memoria
                        03 - Error de DPMI

        - vbeSetMode            Pone el modo de vdeo pedido llamando a
                                vbeGetModeInfo para comprobar que el modo
                                existe y es soportado por el hardware.
                                Llena la estructura tipo VBESCREEN.
                Entrada:        short Xres, short Yres, char Bpp,
                                VBESCREEN *pantalla
                Salida:         Cdigo de error
                        00 - Ok
                        02 - No hay suficiente memoria
                        04 - Modo no soportado

        - vbeSetVirtual         Reserva memoria para una pantalla virtual
                                del tamao indicado y llena la estructura
                                pasada.
                Entrada:        short Xres, short Yres, VBESCREEN *pantalla
                Salida:         Cdigo de error
                        00 - Ok
                        02 - No hay suficiente memoria

        - vbeFreeVirtual        Libera la memoria reservada por vbeSetVirtual
                                para la pantalla pasada.
                Entrada:        VBESCREEN *pantalla
                Salida:         Cdigo de error
                        00 - Ok
                        05 - Error de memoria

        - vbeFlip               Copia el contenido de una pantalla en otra
                                La funcin considera slo el tamao de la
                                pantalla de destino.
                Entrada:        VBESCREEN *origen, VBESCREEN *destino
                Salida:         Ninguna

        - vbeClearScreen        Borra un pantalla con el color de fondo en
                                modos de 256 colores o con negro en modos
                                Direct Color.
                Entrada:        VBESCREEN *pantalla
                Salida:         Ninguna

        - vbePutPixel           Pinta un pixel en las coordenadas dadas con
                                el color especificado. En modos de 256
                                colores, el primer parmetro del color (r)
                                ser el nico que se usar como ndice a la
                                paleta. Los otros dos no sern tenidos en
                                cuenta.
                Entrada:        short Xpos, short Ypos, VBESCREEN *pantalla,
                                char r, char g, char b
                Salida:         Ninguna

        - vbeSetScanWidth       Cambia el ancho de scanline al ancho
                                especificado.
                Entrada:        short ancho
                Salida:         Cdigo de error
                        00 - Ok
                        01 - Error de VBE

        - vbeGetScanWidth       Devuelve el ancho de scanline actual.
                Entrada:        Ninguna
                Salida:         short ancho
                        00 - Error

        - vbeSetStart           Cambia la posicin de la ventana en la
                                videoram a las coordenadas indicadas.
                Entrada:        short Xcoord, short Ycoord
                Salida:         Cdigo de error
                        00 - Ok
                        01 - Error de VBE

        - vbeGetStart           Obtiene la posicin actual de la ventana
                                en videoram, y copia las coordenadas al
                                lugar especificado.
                Entrada:        short *Xcoord, short *Ycoord
                Salida:         Cdigo de error
                        00 - Ok
                        01 - Error de VBE

        - vbeSetVGAMode         Pone un modo de vdeo compatible VGA,
                                llamando a la funcin 00 de la BIOS.
                Entrada:        char modo
                Salida:         Ninguna

        - vbeGetVGAMode         Obtiene el modo de vdeo compatible VGA
                                que est puesto actualmente.
                Entrada:        Ninguna
                Salida:         char modo

        - vbeWR                 Espera al retrazado vertical.
                Entrada:        Ninguna
                Salida:         Ninguna



  ʹ 4. Contactando conmigo     

        Si quieres contactar conmigo por cualquier razn, para consultarme
        una duda, hacerme alguna pregunta o para lo que sea, puedes hacerlo
        en la siguiente direccin de correo:

                MaLiCe@SoftHome.net

        Tambin puedes encontrarme por el IRC hispano en los canales #demos
        o #programacin, y tambin en #coders de Efnet.


        Bueno, pues esto es todo. Espero que con esto puedas sacarle todo el
        partido a esta librera. S que no est del todo completa, pero para
        mis propsitos es ms que suficiente, as que de momento no esperes
        nuevas versiones. De todas formas, si consigues sacarle algn
        provecho no estara de ms que me mencionases en tus producciones.

        Un saludo a la gente de Vertigo, su tutorial sobre el VESA me ha
        ayudado mucho a la hora de crear esta librera.


                        MaLiCe
