                                   UGL Manual version 0.22a

            Let me start by saying how much I hate writing manuals. I hate it
            thiiiis much. Now, I myself am the kind of person who never reads
            a manual or book from the first page to the last. It's just too,
            well it's too boring. I like to get to the good stuff right away. So
            I'm going to do  you guys a favor and split this manual in two parts,
            one that is a quick guide to UGL. It will tell you what you need to
            know to get  started with the library. Then once you think you need
            to know more details or want to do more complex tasks you can start
            checking through the rest of the manual.

            Maybe you're wondering what UGL really is? It's a library programmed
            in pure x86 assembly for game development in Microsoft QuickBasic 4.x
            or better (including Visual Basic for DOS) and Borland C. The minimum
            requirements are at least a 386, although this library uses MMX
            intensely so for best performance a MMX capable processor is recommended.
            A VESA compatible video card is also required for resolutions other
            then 320x200x8. And of course you will need dos, but fortunately it works
            equally as well with  Windows 9.x , Windows NT/2K/XP DOS emulation.
            We haven't tried it with Windows 3.x nor have we tried it with older
            versions. So we  can't say if it works well with them or not.

            So what can UGL do you ask?
            Here is a list of some of the things it offers.
            - Performance
            - Protection against crashes through incorrect coding
            - A set of 2D sprite routines
            - A set of polygon routines (complex, convex)
            - A simple but powerful interface
            - Infinite number of timers running in parallel
            - A sound module with infinite channels and more
            - The ability to play 1-64 channel mod files in the background
            - Debugging features that will reports mistakes in your
              code to help you remove bugs at the same time they occur.

            Big thanks to Joakim A-R and Mr. Moose for helping me with writing this
            so called "manual".

            Visit us at http://dotnet.zext.net

                               Table of Contents

    1.0 - Getting Started
        1.1   The difference between debug
              and release builds
        1.2   How to load UGL
        1.3   What is a handle?
        1.4   What is a DC?
        1.5   What's so special about them?
        1.6   Initializing UGL
        1.7   Setting up the video mode
        1.8   Creating a new DC
        1.9   Using basic primitives
        1.10  Using uglGet and uglPut
        1.11  What's UAR and how do i use it?
        1.12  What's the difference between
              UBF and UVF fonts?
        1.13  Version History

    2.0 - UGL Functions
        2.1 - Initilization and finalization
            2.1.1   uglInit
            2.1.2   uglEnd
            2.1.3   uglSetVideoDC
            2.1.4   uglGetVideoDC
            2.1.5   uglGetClipRect
            2.1.6   uglSetClipRect
            2.1.7   uglGetSetClipRect
            2.1.8   uglRestore
            2.1.9   uglNew
            2.1.10  uglNewMult
            2.1.11  uglDel
            2.1.12  uglDelMult

        2.2 Primitives and sprite routines
            2.2.1   uglRect
            2.2.2   uglRectF
            2.2.3   uglCircle
            2.2.4   uglCircleF
            2.2.5   uglClear
            2.2.6   uglCubicBez
            2.2.7   uglQuadricBez
            2.2.8   uglGet
            2.2.9   uglPut
            2.2.10  uglPutMsk
            2.2.11  uglHLine
            2.2.12  uglVLine
            2.2.13  uglLine
            2.2.14  uglPSet
            2.2.15  uglPGet
            2.2.16  uglPoly
            2.2.17  uglPolyF
            2.2.18  uglPolyPoly
            2.2.19  uglPolyPolyF
            2.2.20  uglEllipse
            2.2.21  uglEllipseF
            2.2.22  uglPutFlip
            2.2.23  uglPutMskFlip
            2.2.24  uglPutRot
            2.2.25  uglPutScl
            2.2.26  uglPutRotScl
            2.2.27  uglPutMskRot
            2.2.28  uglPutMskScl
            2.2.29  uglPutMskRotScl

        2.3 Paging
            2.3.1   uglSetVisPage
            2.3.2   uglSetWrkPage

        2.4 Conversion routines
            2.4.1   uglColor
            2.4.2   uglColor8
            2.4.3   uglColor15
            2.4.4   uglColor16
            2.4.5   uglColor32
            2.4.6   uglGetConv
            2.4.7   uglPutConv
            2.4.8   uglRowRead
            2.4.9   uglRowReadEx
            2.4.10  uglRowWrite
            2.4.11  uglRowWriteEx
            2.4.12  uglRowSetPal

        2.5 Image loading
            2.5.1   uglNewBMP
            2.5.2   uglPutBMP
            2.5.3   uglNewBMPEx
            2.5.4   uglPutBMPEx

        2.6 Information routines
            2.6.1   uglColors
            2.6.2   uglColorsEx
            2.6.3   uglDCget
            2.6.4   uglDCAccessRd
            2.6.5   uglDCAccessWr
            2.6.6   uglDCAccessRdWr

        2.7 Convex Polygons
            2.7.1   uglTriF
            2.7.2   uglQuadF
            2.7.3   uglTriT
            2.7.4   uglQuadT
            2.7.5   uglTriG

        2.8 Palette
            2.8.1   uglPalGet
            2.8.2   uglPalSet
            2.8.3   uglPalGetBuff
            2.8.4   uglPalSetBuff
            2.8.5   uglPalLoad

    3.0 - UGL Utility functions
        3.1 Splines
            3.1.1   ugluCubicBez
            3.1.2   ugluCubicBez3D
            3.1.3   ugluQuadricBez
            3.1.4   ugluQuadricBez3D

        3.2 Keyboard
            3.2.1   kbdInit
            3.2.2   kbdEnd
            3.2.3   kbdPause
            3.2.4   kbdResume

        3.3 Mouse
            3.3.1   mouseInit
            3.3.2   mouseReset
            3.3.3   mouseEnd
            3.3.4   mouseCursor
            3.3.5   mouseShow
            3.3.6   mouseHide
            3.3.7   mouseRange
            3.3.8   mousePos
            3.3.9   mouseRatio

        3.4 Fonts
            3.4.1   fontNew
            3.4.2   fontDel
            3.4.3   fontSetAlign
            3.4.4   fontGetAlign
            3.4.5   fontHAlign
            3.4.6   fontSetHAlign
            3.4.7   fontVAlign
            3.4.8   fontSetVAlign
            3.4.9   fontExtraspc
            3.4.10  fontSetExtraspc
            3.4.11  fontGetExtraspc
            3.4.12  fontUnderline
            3.4.13  fontSetUnderline
            3.4.14  fontGetUnderline
            3.4.15  fontStrikeOut
            3.4.16  fontSetStrikeOut
            3.4.17  fontGetStrikeOut
            3.4.18  fontOutline
            3.4.19  fontSetOutline
            3.4.20  fontGetOutline
            3.4.21  fontBGMode
            3.4.22  fontSetBGMode
            3.4.23  fontGetBGMode
            3.4.24  fontBGColor
            3.4.25  fontSetBGColor
            3.4.26  fontGetBGColor
            3.4.27  fontSize
            3.4.28  fontSetSize
            3.4.29  fontGetSize
            3.4.30  fontAngle
            3.4.31  fontSetAngle
            3.4.32  fontGetAngle
            3.4.33  fontWidth
            3.4.34  fontTextOut

        3.5 Timer
            3.5.1   tmrInit
            3.5.2   tmrEnd
            3.5.3   tmrNew
            3.5.4   tmrDel
            3.5.5   tmrPause
            3.5.6   tmrResume
            3.5.7   tmrUs2Freq
            3.5.8   tmrMs2Freq
            3.5.9   tmrTick2Freq
            3.5.10  tmrSec2Freq
            3.5.11  tmrMin2Freq
            3.5.12  tmrCallbkSet
            3.5.13  tmrCallbkCancel

        3.6 Sound
            3.6.1   sndInit
            3.6.2   sndEnd
            3.6.3   sndOpenOutPut
            3.6.4   sndPlay
            3.6.5   sndPlayEx
            3.6.6   sndPause
            3.6.7   sndResume
            3.6.8   sndStop
            3.6.9   sndNewWav
            3.6.10  sndNewRaw
            3.6.11  sndNewWavEx
            3.6.12  sndDel
            3.6.13  sndSetInterp
            3.6.14  sndMasterSetPan
            3.6.15  sndVoiceSetDefault
            3.6.16  sndVoiceSetSample
            3.6.17  sndVoiceSetDir
            3.6.18  sndVoiceSetLoopMode
            3.6.19  sndVoiceSetLoopPoints
            3.6.20  sndVoiceSetVol
            3.6.21  sndVoiceSetPan
            3.6.22  sndVoiceSetRate

        3.7 Music
            3.7.1   modInit
            3.7.2   modEnd
            3.7.3   modNew
            3.7.4   modDel
            3.7.5   modPlay
            3.7.6   modPause
            3.7.7   modResume
            3.7.8   modStop
            3.7.9   modGetChanVU
            3.7.10  modGetPlayState
            3.7.11  modGetVolume
            3.7.12  modSetVolume
            3.7.13  modSetStereo
            3.7.14  modSetCacheSize
            3.7.15  modFadeOut
            3.7.16  modFadeIn
            3.7.17  modFadeToVol

        3.8 UAR - UGL Archive
            3.8.1   uarOpen
            3.8.2   uarClose
            3.8.3   uarRead
            3.8.4   uarReadH
            3.8.5   uarEOF
            3.8.6   uarPos
            3.8.7   uarSize
            3.8.8   uarSeek
            3.8.9   uarbOpen
            3.8.10  uarbClose
            3.8.11  uarbRead
            3.8.12  uarbEOF
            3.8.13  uarbPos
            3.8.14  uarbSize
            3.8.15  uarbSeek
            3.8.16  uarFileFind
            3.8.17  uarFileSeek
            3.8.18  uarFileExtract
            3.8.19  uarFileAdd
            3.8.20  uarFileDel
            3.8.21  uarCreate

        3.9 Dos
            3.9.1   bfileOpen
            3.9.2   bfileClose
            3.9.3   bfileBegin
            3.9.4   bfileEnd
            3.9.5   bfileRead
            3.9.6   bfileRead1
            3.9.7   bfileRead2
            3.9.8   bfileRead4
            3.9.9   bfileWrite
            3.9.10  bfileWrite1
            3.9.11  bfileWrite2
            3.9.12  bfileWrite4
            3.9.13  bfileEOF
            3.9.14  bfilePos
            3.9.15  bfileSize
            3.9.16  bfileSeek
            3.9.17  fileOpen
            3.9.18  fileClose
            3.9.19  fileRead
            3.9.20  fileWrite
            3.9.21  fileEOF
            3.9.22  filePos
            3.9.23  fileSize
            3.9.24  fileSeek
            3.9.25  memAlloc
            3.9.26  memAvail
            3.9.27  memCAlloc
            3.9.28  memFree
            3.9.29  memFill
            3.9.30  memFill
            3.9.31  memFillEx
            3.9.32  memCopy
            3.9.33  memCopyEx

        3.10 Ems
            3.10.1  emsAlloc
            3.10.1  emsCalloc
            3.10.2  emsAvail
            3.10.3  emsFree
            3.10.4  emsMap
            3.10.5  emsSave
            3.10.7  emsRestore
            3.10.8  emsCheck

    ====================================
    1.1 - The difference between debug
          and release builds
    ====================================

        The debug build of the library is for the development period of
        your program while the release build should only be used when you're
        compiling the release version of your program. The debug build has
        crash protection, it doesn't crash by incorrect use of UGL and helps
        you find bugs. It does so by logging its startup and shutdown activity
        in a log file called ugl.log. It also reports incorrect use of the
        routines. Of course, we can't guarantee that UGL will never crash with
        the debug builds. But we can guarantee that it will be very stable. It
        is strongly recommended that the debug builds are always used in the
        IDE and during development. It doesn't give any worse performance except
        when an error is detected. And then only for a very short period of time.
        This is because it has to log the error, and writing to the log means
        disk access.

        The release build should only be used for the release version of your
        program because it doesn't use any sort of checking at all. Thus you
        have to had eliminated all the errors that are reported in ugl.log by
        the debug build of UGL. It does offer a slight increase in performance
        and is smaller in size.

    ====================================
       1.2 - How to load UGL
    ====================================

        When you unpack the library you will see a directory called lib.
        Under this directory you have two sub directories, debug and release.
        And under each of those you have three sub directories called qb,
        pds, vbd and bc. The depending on what compiler you're using copy the
        files under the sub directory from both debug and release to the library
        directory of qb/pds/vbdos/bc. If you don't have a library directory and
        everything is just under one directory then simply copy the files to
        that directory. Then copy the files in the bi directory to the include
        directory for qb, or if all files are just stored in the main qb
        directory simply copy it over. Now, to load up the library you have to
        type this:

        Qb debug:           qb /Lugld
        Qb release:         qb /Lugl
        PDS debug:          qbx /Es /Luglpd
        PDS release:        qbx /Es /Luglp
        VBDos debug:        vbdos /Es /Luglvd
        VBDos release:      vbdos /Es /Luglv

    ====================================
       1.3 - What is a handle?
    ====================================

        A handle is an alias for something. In UGL handles are used quite a
        bit to keep you from messing with things you're not suppose to mess
        with. The handles returned by UGL are only known by guess what, UGL.
        A handle is always 32 bits, therefore you always have to declare
        handles as LONG. If you forget and declare it as integer or any other
        type that is less then 32 bits the handle will be lost and if you're
        using the release build there will be a crash when you attempt to use
        the handle. In the debug build it will just be logged.

    ====================================
       1.4 - What is a DC?
    ====================================

        A DC is short for Device Context, a concept borrowed from windows.
        A DC is a surface for storing image/sprites/textures. It's similar
        to the array you create to hold a sprite that you want to GET or PUT
        in QB/VBDOS.

    ====================================
       1.5 - What's so special about them?
    ====================================

        You never have to worry about low-level things such as how to allocate
        a DC for a certain memory type, you don't have to allocate it yourself
        and you refer to it only by its handle. You just have to tell UGL what
        resolutions and bit depth it should have. To UGL all DC's are the same.
        It doesn't matter if it's the Video DC, Conventional memory DC or an
        EMS DC. All UGL routines accept any DC as its destination or source.
        So you never have to write one line of code different because you want
        to use some other kind of memory to store your sprite.

    ====================================
       1.6 - Initializing UGL
    ====================================

        To Initializing UGL we have to call uglInit. uglInit returns True (-1)
        if it was successful and False (0) if it wasn't. Example:

        if not uglInit then
            print "Error: Could not Init UGL"
            end
        end if

    ====================================
       1.7 - Setting up the video mode
    ====================================

        To set the video mode we need to use the function uglSetVideoDC.
        It returns a handle to the video if it was successful and if not
        it returns False. Its in parameters are format, xRes, yRes and
        Pages. Format can be UGL.8BIT, UGL.15BIT, UGL.16BIT and UGL.32BIT
        for 8, 15, 16 or 32 bit mode. xRes is the desired x resolution of
        the mode you want yRes is the desired y resolution of the mode you
        want pages are the number of pages you want.
        Example:

        defint a-z
        '$include: 'ugl.bi'

        '' Create a handle holder
        dim videoHandle as long

        '' Init ugl
        if not uglInit then
            print "Error: Could not Initializing UGL"
            end
        end if

        '' Set mode 640x480x16 with 1 page
        videoHandle = uglSetVideoDC(UGL.16BIT, 640, 480, 1)
        if videoHandle = False then
            print "Error: Could not set the video mode"
            uglEnd
        end if

        '' It succeeded
        '' Now to reset ugl and set the video mode back
        '' to what it was before we changed it
        '' uglRestore restores the video mode
        '' uglEnd resets ugl, don't forget to call it
        '' when you're in the IDE
        uglRestore
        uglEnd

    ====================================
       1.8 - Creating a new DC
    ====================================

        One of the things i particularly like about UGL is the DC system.
        It makes everything so much simpler for the programmer and at a
        low level it enables more efficient handling of Bank/EMS/Segments.
        To UGL all DCs are the same, this means that unlike other libraries
        that are available for qb you don't need to handle a sprite stored
        in ems any differently then one stored in conventional memory. You
        can use the same routines on all kind of DCs. Now, let's get to how
        to actually create one. You need to know a few things, like how big
        it should be, where you want it etc. Using the uglNew you can allocate
        it in either conventional memory or ems by setting the typ argument to
        either UGL.MEM or UGL.EMS. The fmt argument tells is what bitdepth it
        should have (UGL.8BIT, UGL.15BIT, UGL.16BIT, UGL.32BIT) and the xRes
        and yRes arguments tell the routine what dimensions it should have.
        So let's say we want to create a DC that is 320 pixels wide, 240 pixels
        high, has bit depth of 8 (256 colors) and is allocated in conventional
        memory. Here is what the code could look like:

        defint a-z
        '$include: 'ugl.bi'

        const xRes = 320
        const yRes = 240
        const bpp  = UGL.8BIT

        '' Create a 32 bit variable to store
        '' it's handle
        dim MyDC as long

        '' Now attempt to allocate the DC
        MyDC = uglNew(UGL.MEM, bpp, xRes, yRes)

        '' Now we have to check it could be
        '' allocated or not. This is done by
        '' checking if the handle is false or
        '' zero.
        if MyDC = False then
            print "Error!: Could not allocate DC"
            end
        end if

    ====================================
       1.9 - Using basic primitives
    ====================================

        The most basic drawing primitives of ugl include line, pset, and circle.
        They all require a DC to draw to, which can be a video DC or a memory DC,
        They all can draw in any bit depth, and in any screen resolution.
        Here is an example to show you how to set the screen and use the drawing
        Primitives on the screen:

        defint a-z
        '$include: 'ugl.bi'

        const xRes = 320
        const yRes = 240
        const bpp  = UGL.8BIT

        '' Initialize
        if not uglInit then
            print "Error!: Could not initialize library!"
            end
        end if

        '' Create a variable to store the video DC
        dim video as long

        '' Now attempt to set the screen mode with one video page
        video = uglSetVideoDC(bpp, xRes, yRes, 1)
        if video = 0 then
            print "Error!: Could not set screen mode!"
            end
        end if

        '' uglColors gives us the biggest color value
        '' for the bitdepth bpp
        colors& = uglColors(bpp)

        do
            for i = 1 to 100
                uglPset video, rnd * xRes, rnd * yRes, rnd * colors&
                uglLine video, rnd * xRes, rnd * yRes, rnd * xRes, rnd * yRes,_
                               rnd * colors&

                uglCircle video, rnd * xRes, rnd * yRes, rnd * 100, rnd * colors&
            next i
        loop while inkey$ = ""

        ''Close down library
        uglRestore
        uglEnd
        end

    ====================================
       1.10 - Using uglGet and uglPut
    ====================================

        This is probably the routines you use most.
        They both require a DC to draw to/get from, which can be
        a video DC or a memory DC, plus a DC for itself to read
        from/wite to. They can only draw/get in the bit depth their
        own DC is, but in any screen resolution.
        Here is an example to show you how to set the screen and use
        the blitting on the screen:

        defint a-z
        '$include: 'ugl.bi'

        const xRes = 320
        const yRes = 240
        const bpp  = UGL.8BIT

        '' Initialize
        if not uglInit then
            print "Error!: Could not initialize library!"
            end
        end if

        '' Create a 32 bit variables to store
        '' the handles
        dim MyDC as long
        dim video as long

        '' Now attempt to set the screen mode with one video page
        video = uglSetVideoDC(bpp, xRes, yRes, 1)
        if video = False then
            print "Error!: Could not set screen mode"
            end
        end if

        '' Now attempt to allocate the DC
        MyDC = uglNew(UGL.MEM, bpp, 10, 10)

        '' Now we have to check if it could be
        '' allocated or not. This is done by
        '' checking if the handle is false (zero).
        if MyDC = False then
            print "Error!: Could not allocate DC"
            end
        end if

        '' Make some random graphics on a 10x10 field
        for i = 1 to 100
            uglPset video, rnd * 10, rnd * yRes, i
        next i

        '' Get the 10x10 field into MyDC.
        '' We don't need to specify the ending coordinats,
        '' as the DC has a defined with already.
        uglGet video, 0, 0, MyDC

        '' Blit (put) the sprite from MyDC to the
        '' screen at random coordinates
        do
            uglPut video, rnd * xRes, rnd * yRes, MyDC
        loop while inkey$ = ""

        ''Close down library
        uglRestore
        uglEnd

    ====================================
       1.11  What's UAR and how do i use it?
    ====================================

        UAR stands for UGL Archive, it's an archive system that is tightly
        interigated with UGL. It's purpose is to put many files into one and
        be able to access that one file as if it was a complete filesystem.
        So in other words an UAR is like a TAR/ZIP/RAR file. UAR works in
        layers. In the bottom layer you'll find the actual driver which creates,
        reads and writes to a specific archive format. And in the top layer
        you'll find a sort of a wrapper which gives you an interface that enables
        you to access any file in an archive as if it was an ordinary file.
        Currently the bottom layer is for Quake I/II PAK archives, this format
        is very simple and does not use compression. But becuase there is
        already a great tool for creating and modifying PAK archives (PAKExplorer
        can be found under tools\pakexplr) we decided that's the format we'll
        use for now. The great thing about UAR is that any routine in UGL which
        loads files can load files from an UAR without having to change a line
        code. For instance if i were loading a bmp like this

        bmp = uglNewBMP(UGL.EMS, UGL.16BIT, "gfx\characters\mario.bmp")

        and later decide that i don't want million files lying around and
        put the bmp in a pak file i would load it like this

        bmp = uglNewBMP(UGL.EMS, UGL.16BIT, "gfx\gfx.pak::characters/mario.bmp")

        uglNewBMP will know that the bmp is in the pak file gfx.pak and under
        the directory characters and will load it directly from there.
        If you want to directly access files in a UAR check out section
        3.2 UAR - UGL Archive. There you'll find routines that are similar to
        qb's and C's file routines.

    ====================================
        1.12  What's the difference between UBF and UVF fonts?
    ====================================

        UGL has two type of fonts. UBF and UVF fonts, UBF
        stands for "UGL Bitmap Font" and UVF stands for
        "UGL Vector Font".

        UBF fonts are as the name says, bitmap fonts. They
        are loaded and used just like UVF fonts. The difference
        is that they're bitmaps, images. They're faster to render but
        get blocky when they're scaled and rotated. Since UVF fonts
        don't look all that good when they're small its recomended to
        use UBF fonts where small fonts are needed. For the time being
        there is no UBF support in ugl. But in the future you'll be
        able to convert windows fonts with TTF2UVF (should change that
        name) to UBF and load them up in UGL jus as you do with UVF ones.

        UVF fonts are Vector fonts. They're like the ttf fonts in windows
        and we made infact a little utility to convert windows ttf fonts
        to UVF ones. There are both advantages and disadvantages with UVF.
        UVF fonts look smooth even when you scale and rotate them, but
        they don't look very well when they're small and are slow to render.

        To use UVF fonts you'll have to convert the ttf font you like to
        UVF with a utility called TTF2UVF which you will find under
        tools/ttf2uvf. This utility needs the MFC runtimes which you can
        download from http://www.winsite.com/bin/Info?500000031712. Once
        you've converted the TTF font load it up in UGL and it'll do the
        rest.

    ====================================
        1.13  Version history
    ====================================
    .....
    build 0.22a
        Added:
            - A mod player. Yepp, you read correctly. However, as
              it's summer i'm not going to waste time coding. So
              vibrato, tremolo and arpegio aren't implemented.
              But other then that it works perfect.

    .....
    build 0.21d
        Added:
            - snd.h, the C header for the sound module.
              Forgot to add that before, sorry guys.

            - palette.bas, an example on how to use the
              palette.

        Fixed:
            - Fixed a bug in uglPalGet and uglPalGetBuff

            - ugl.bi and snd.bi, there was some missdeclarations
              there. Blame that lazy son of a gun v1ctor, he never
              tests anything he codes! %#&

    .....
    build 0.21c
        Added:
            - The ability to add your own objs/libs to the builder.

        Fixed:
            - A few bugs in the library builder

            - A bug in the sound module which caused it not to use the
              beats per second setting.

    .....
    build 0.21b
        Added:
            - sound module! yeah babe, did you hear that? sound!

            - ems save & restore, context saving stuff for use on ISR's

        Fixed:
            - Updated a manual a bit, still not 100% complete though

            - ems mapping was buggy, was always starting the map at lpage 0.
              now multiple page mapping is used too, should be much faster if
              mapping more than one page at time

            - pget had a bug! omfg, can you believe that? are we lazy c0derz
              or what? :P

            - a bunch of things i didn't document and that i don't remember now!
              note to self: change logs must be updated or they are otherwise
              pretty much useless [period]

    .....
    build 0.20c

        Fixed:
            - A bug in the memory allocation routine made it impossible to even
              init the lib. Seems to be fixed now. Though noone complained, i guess
              noone tried 0.20b :p

    .....
    build 0.20b
        Added:
            - palette set/get/load functions, don't expect routines that need
              a 332 (rgb) fixed palette to work, they won't :P

            - uglNewEx/PutBMPEx routines, added options to not convert to 332
              palette when loading 8-bit BMPs and to do masking (setting a
              mask value for 8-bit bitmaps)

            - uglRowWriteEx & uglPutMskConv, can do masking now when converting
              between DCs with different bpp's

        Fixed:
            - tmapper crashing 'cause too tiny polygons

            - tri/quad not filling the whole destine dc (last col and row)

            - uglDCAccess# routines had stupid and er, invisible, er bugs...

            - mouseCursor will handle the conversion from cursors of lower
              bpp's to higher ones (no mask will be lost)

    .....
    build 0.19b
        Added:
            - support for Borland/Turbo C/C++ real-mode compiler (medium memory
              model), including libs (both for release and debug modes), headers
              and some examples (headers are probably compatible with M$-C/QuickC
              and Watcom-C compilers, but calls to non ansi-c functions like
              farmalloc, farfree and farcoreleft are done, that may be a problem
              with other C real-mode DOS compilers than BC).

            - DOS memory allocation strategy is changed to include UMBs in the
              DOS memory chain (not when NT is detected, seems like adding
              UMBs doesn't work right in NT DOS boxes; can give up to 100K of
              memory depending on OS, EMS manager and TSRs loaded)

            - uglDCAccessRd, uglDCAccessWr and uglDCAccessRdWr functions, for
              direct DC frame-buffer access (warning: seem to not work in
              QB/PDS/VBD probably 'cause yet-another-QB-bug; when used in C,
              all seems fine)

        Fixed:
            - no more holes between triangles/quadrangles when using uglTri# and
              uglQuad# routines

            - tmapper (TriT/QuadT) no more crashes when handling too tiny polys

            - no more crashes when there isn't EMS or VESA support

            - vga mode 13h will always be used if setting 320x200x8 + 1 page

    .....
    build 0.18b
        Added:
            - uglPutRot, uglPutScl, uglPutRotScl,
              uglPutMskRot, uglPutMskScl, uglPutMskRotScl

            - uglTriF, uglTriG, uglTriT, uglQuadF, uglQuadT

            - 4-bit RLE support for uglNewBMP and uglPutBMP routines

            - AUTOINIT operation mode for timers

    .....
    build 0.17b
        Note:
            - There's a problem with Viper III cards, all modes but 320x200x8
              and 320x240x8 work. It's seems that this is a hardware problem.
              When trying to change the bytes per scanline in these modes the
              computer hangs. This was partially fixed by not changing bytes
              per scanline in 320x200x8 since it's under 64 KB anyway. But for
              320x240x8 more testing is needed to find the exact problem, if
              this is a hardware problem there is nothing we can do. If you
              have a Viper III and have this problem you should try the univbe
              driver or a firmware update.

        Changed:
            - all routines for direct access to archives (Quake I/II's PAK)
              are now at arch module (protos at bi/arch.bi include file)

            - all routines that load files (ie: fontLoad, uglNewBMP, uglPutBMP)
              now support archives directly

            - no more limits on number of files on an archive when using
              the uarFileAdd and uarFileDel routines (the recommendation to
              use an extern tool (ie, PAKExplorer) to change/update your
              archives still applying, as no temp file is used, if any error
              occur while updating the archives, the archive would be
              inaccessible next time you 'd try loading files from it;
              resuming: if you do some mistake using the Add and/or Del
              routines and your archive get screwed and somehow you don't have
              backups of the files that were added to it... don't blame us :P;
              use the uarCreate, uarFileAdd and uarFileDel routines with care!)

    .....
    build 0.16a
        Added:
            - Ported PAK routines from C to assembly to get the size down.
              Didn't make allot of difference but it's 50% smaller now

            - Quake I/II PAK archive routines added:
                ugluFindFile, ugluExtractFile, ugluExtractFileEx
                ugluAddFile, ugluAddFileEx, ugluDelFile, ugluCreate

            - uglEllipse and uglEllipseF: unfilled and filled ellipses drawing
              routines

        Fixed:
            - uglCubicBez now draws correctly for levels above 16

        Note:
            - I would recomend you to only use Find and Extract routines
              because AddFile and DelFile loads the whole PAK archive
              "FAT" into memory. Thus the "FAT" can't be bigger then 64 KB
              which is about 1024 files. So use Pak Explorer for
              creation and maintanence of the archives and ugl's
              routines for reading.

    .....
    build 0.15a
        Added:
            - uglPutFlip and uglPutMskFlip: horizontally and/or vertically
              flipped bitmaps/sprites blting

            - documentation for the font module, the module stills not
              complete (ie, fontPrint and fontDraw routines aren't yet
              finished and there's no bitmapped font support), but for
              UVF (vector fonts) and printing a line at time, it's working
              fine (until some beta-tester find some nasty bug on it :D)

        Changed:
            - a "smarter" building system: after hours trying to get m$ make
              utility (nmake) to work (it's too dumb to understand that when
              you define a dir to where search for dependencies, that means
              _all_ dependencies are assumed to be there, not only the first
              one in the list... grr!!!) and having no luck with borland's
              make (it's not so stupid as m$ ones, tho, there is a bug with
              the partial-filename macros when the ! command modifier is used
              that makes it useless... grr^2), i (v1ctor) decided to try another
              make tool: DMAKE, that is a bit more difficult to setup and to
              convert/port to (it's like 10% m$' make-file compatible) but that
              can do the work fine (win32 gnu-make 'd work nicelly, tho... bah...
              too lazy to read more 500K of docs :P)... obs: dmake 4.1 is case-
              sensitive and as LINK & LIB 16-bit don't (and cause the way used
              to build the lib based on make-files' names), the make-files names
              have to be UPPERCASE (with the `mk' extension in lowercase), or
              the build will fail (all the rest, obj/asm/inc files plus dirs,
              must be in lowercase).

    .....
    build 0.14a
        Added:
            - 4 new routines for curves added: uglQuadricBez, ugluQuadricBez,
              ugluQuadricBez3D and ugluCubicBez3D.

            - uglPolyPoly and uglPolyPolyF for draw multiple polygons at the
              same call plus uglPoly: same as uglPolyF but draws only the
              polygon's outlines.

    .....
    build 0.13a
        Changed:
            - The uglBox and uglBoxF routines are now called uglRect and
              uglRectF as we "found" `rectangle' a bit more clear than 'box',
              sorry :P.

            - Surprise, the set clipping area function also changed (both name
              and parameters) and there's now one to get the clipping rectangle
              and set plus get the current one (uglSetClipRect, uglGetClipRect
              and guess what... uglGetSetClipRect! :P), sorry again (that's
              what you get by beta-testing :D).

        Added:
            - Logging for visual/working page setting routines

    .....
    build 0.12a
        Added:
            - By request we added more logging to UGL. So now when some routine
              detects an invalid DC it logs that. This'll look like:

              uglClear: Invalid DC
              uglPut: Invalid src DC

              This is somewhat slower because of disk access, but it's only for
              the debug versions and when an error occurs.

    .....
    build 0.11a
        Added:
            - We noticed people making mistakes like sending an invalid DC to
              some routines which made their programs crashed. So we decided to
              "fix" that. The debug versions of the lib is now very safe and
              pretty much impossible to crash (by the user, that is). So, our
              tip is to use the debug libs in the IDE during development and use
              the release when you're about to make a public release. But don't
              be surprised if your program worked perfect with the debug libs
              since the start and now all the suddenly crashes when you use the
              release version. So be sure to fix any bugs you have immediately
              so you don't have 10K bugs to fix just before you planned to
              release your game or whatever.

        Fixed:
            - The 332 palette used in 8-bit video modes is now more accurate.

    .....
    build 0.10a
        Fixed:
            - The problem with Voodoo cards and win2k is fixed. Even though
              this had nothing to do with UGL we decided that we needed to do
              something about it. So you can use mode 320x200x8 with voodoo
              cards, it can only have one page. In other words:
              uglSetVideoDC(UGL.8BIT, 320, 200, 1).

    .....
    build 0.09a
        Added:
            - There are now debug versions of the lib. If you look under the
              directory lib you'll see that there are two directories, debug and
              release. And under them you have sub directories called qb4x, qb7x
              and vb1x. The debug versions of the library create a log file
              called ugl.log where you can exactly see where an error occurred.
              So when you post a bug report don't forget to include ugl.log

    ======================================================
      2.1.1 - uglInit
    ======================================================

        Prototype:
            declare function uglInit% ()

        Arguments:
            None

        Returns:
            True if initalization went ok, if not it returns False

        Description:
            Inits the library, this routine Has to be called
            before anything else.

        Example:
            Any of the examples

    ======================================================
      2.1.2 - uglEnd
    ======================================================

        Prototype:
            declare sub uglEnd ()

        Arguments:
            None

        Returns:
            Nothing

        Description:
            Finalizes the library, has to be called when runing
            directly from the IDE. Not needed when compiled.

        Example:
            Any of the examples

    ======================================================
      2.1.3 - uglSetVideoDC
    ======================================================

        Prototype:
            declare function uglSetVideoDC& (byval fmt as integer, byval xRes as integer,_
                                             byval yRes as integer, byval vidPages as integer)

        Arguments:
            [in] fmt                - Requested bitdepth UGL.8BIT,  UGL.15BIT
                                                         UGL.16BIT, UGL.32BIT
                 xRes               - X Resolution
                 yRes               - Y Resolution
             vidPages               - Reuested video pages, only relavent for
                                      paging. Should be 1 if you're not going
                                      to use paging.

        Returns:
            The handle to the video DC if succesful, if not it
            returns False (zero).

        Description:
            Sets the video in the requested mode if it's available.
            Remember that all DC handles are of the type LONG.

        Example:
            Any of the examples

    ======================================================
       2.1.4 - uglGetVideoDC
    ======================================================

        Prototype:
            declare function uglGetVideoDC& ()

        Arguments:
            None

        Returns:
            The handle to the video DC if succesful, if not it
            returns False (zero).

        Description:
            If you for some wierd reason that i can't imagine why, have
            lost the handle to the video dc you can get it with this
            function. assuming that there actually is one.
            Remember that all DC handles are of the type LONG.

        Example:
            None

    ======================================================
       2.1.5 - uglGetClipRect
    ======================================================

        Prototype:
            declare sub uglGetClipRect (byval dc as long, seg cr as CLIPRECT)

        Arguments:
            [in]  dc                - DC to set
            [out] cr                - clipping rectangle

        Returns:
            Nothing

        Description:
            Gets the clipping boundries of the requested DC.

        Example:
            None

    ======================================================
       2.1.6 - uglSetClipRect
    ======================================================

        Prototype:
            declare sub uglSetClipRect (byval dc as long, seg cr as CLIPRECT)

        Arguments:
            [in] dc                 - DC to set
                 cr                 - clipping rectangle, where:
                                      xMin (>= 0; <= xMax)
                                      yMin (>= 0; <= yMax)
                                      xMax (>= xMin; < dc.xRes)
                                      yMax (>= yMin; < dc.yRes)

        Returns:
            Nothing

        Description:
            Set the clipping boundries of the requested DC.

        Example:
            None

    ======================================================
       2.1.7 - uglGetSetClipRect
    ======================================================

        Prototype:
            declare sub uglGetSetClipRect (byval dc as long, seg inCr as CLIPRECT,_
                                           seg outCr as CLIPRECT)

        Arguments:
            [out] outCr             - Old Clipping rectangle
            [in]  dc                - DC to set
                  inCr              - New clipping rectangle, where:
                                      xMin (>= 0; <= xMax)
                                      yMin (>= 0; <= yMax)
                                      xMax (>= xMin; < dc.xRes)
                                      yMax (>= yMin; < dc.yRes)

        Returns:
            Nothing

        Description:
            Get the old clipping rectangle and sets the
            new one.

        Example:
            None

    ======================================================
       2.1.8 - uglRestore
    ======================================================

        Prototype:
            declare sub uglRestore ()

        Arguments:
            None

        Returns:
            Nothing

        Description:
            Restores the video mode.

        Example:
            Any of the examples

    ======================================================
       2.1.9 - uglNew
    ======================================================

        Prototype:
            declare function uglNew& (byval typ as integer, byval fmt as integer,_
                                      byval xRes as integer, byval yRes as integer)

        Arguments:
            [in]  typ               - DC Type, can be UGL.MEM or UGL.EMS
                  cfmt              - Bitdepth, can be UGL.8BIT,  UGL.15BIT
                                                       UGL.16BIT, UGL.32BIT
                  xRes              - The Width of the DC  (> 0; <= 16384)
                  yRes              - The Height of the DC (> 0)

        Returns:
            The handle to the video DC if succesful, if not it
            returns False (zero).

        Description:
            Allocates a new DC. The DC can be allocated in
            conventional memory where it can be up to 640 KB
            or in EMS where it can be up to 4 MB.
            Remember that all DC handles are of the type LONG.

        Example:
            offscr.bas

    ======================================================
       2.1.10 - uglNewMult
    ======================================================

        Prototype:
            declare function uglNewMult% (dcArray() as long, byval dcs as integer,_
                                          byval typ as integer, byval fmt as integer,_
                                          byval xRes as integer, byval yRes as integer)

        Arguments:
             [out] dcArray          - Array to hold the pointers to the DCs
             [in]  dcs              - Number of DCs to allocate
                   typ              - DC Type, can be UGL.MEM or UGL.EMS
                   fmt              - Bitdepth, can be UGL.8BIT,  UGL.15BIT
                                                       UGL.16BIT, UGL.32BIT
                   xRes             - The Widths of the DCs  (> 0; <= 16384)
                   yRes             - The Heights of the DCs (> 0)

    Returns:
        True if succesful, False if not

    Description:
        Like uglNew except it's allocates multiple DC's at
        once and stores their handles in an array of the
        type LONG. The array has to have as many elements
        as the numbers of requested DCs.

    Example:
        put.bas

    ======================================================
    2.1.11 - uglDel
    ======================================================

    Prototype:
        declare sub uglDel (seg dc as long)

    Arguments:
         [in/out] dc            - Handle to DC to be freed

    Returns:
        Nothing

    Description:
        Frees the memory allocated by a DC and sets the
        handle to NULL. Worth to notice is that you don't
        have to actually delete any of the DC's you create.
        This is there only becuase you might be running out
        memory and don't need a certain DC anymore.

    Example:
        None

    ======================================================
    2.1.12 - uglDelMult
    ======================================================

    Prototype:
        declare sub uglDelMult (seg dcArray() as long)

    Arguments:
         [in/out] dcArray()     - Array to the DCs

    Returns:
        Nothing

    Description:
        Same as uglDel except it's for mulitple DCs.
        The first handle in the array will be set to NULL.

    Example:
        None

    ======================================================
    2.2.1 - uglRect
    ======================================================

    Prototype:
        declare sub uglRect (byval dc as long, byval x1 as integer,_
                             byval y1 as integer, byval x2 as integer,_
                             byval y2 as integer, byval clr as long)

    Arguments:
         [in] dc                - Destination DC
              x1                - Left X
              y1                - Top Y
              x2                - Right X
              y2                - Bottom Y
              clr               - Color

    Returns:
        Nothing

    Description:
        Draws the outline of a rectangle on the requested DC

    Example:
        rect.bas

    ======================================================
    2.2.2 - uglRectF
    ======================================================

    Prototype:
        declare sub uglRectF (byval dc as long, byval x1 as integer,_
                              byval y1 as integer, byval x2 as integer,_
                              byval y2 as integer, byval clr as long)

    Arguments:
         [in] dc                - Destination DC
              x1                - Left X
              y1                - Top Y
              x2                - Right X
              y2                - Bottom Y
              clr               - Color

    Returns:
        Nothing

    Description:
        Draws a filled rectangle on the requested DC

    Example:
        rectf.bas

    ======================================================
    2.2.3 - uglCircle
    ======================================================

    Prototype:
        declare sub uglCircle (byval dc as long, byval cx as integer,_
                               byval cy as integer, byval rad as integer,_
                               byval clr as long)

    Arguments:
         [in] dc                - Destination DC
              cx                - Center, X coordinate
              cy                - Center, Y coordinate
              r                 - Radius
              clr               - Color

    Returns:
        Nothing

    Description:
        Draws the outline of a Circle on the requested DC

    Example:
        circle.bas

    ======================================================
    2.2.4 - uglCircleF
    ======================================================

    Prototype:
        declare sub uglCircleF (byval dc as long, byval cx as integer,_
                                byval cy as integer, byval rad as integer,_
                                byval clr as long)

    Arguments:
         [in] dc                - Destination DC
              cx                - Center, X coordinate
              cy                - Center, Y coordinate
              r                 - Radius
              clr               - Color

    Returns:
        Nothing

        Description:
            Draws a filled Circle on the requested DC

        Example:
            circlef.bas

    ======================================================
       2.2.5 - uglClear
    ======================================================

        Prototype:
            declare sub uglClear (byval dc as long, byval clr as long)

        Arguments:
             [in] dc                - Destination DC
                  clr               - Color

        Returns:
            Nothing

        Description:
            Clears the requested DC with the desied color. Considers the
            clipping rectange and pages.

        Example:
            clear.bas

    ======================================================
       2.2.6 - uglCubicBez
    ======================================================

        Prototype:
            declare sub uglCubicBez (byval dc as long, seg cbz as CUBICBEZ,_
                                     byval levels as integer, byval clr as long)

        Arguments:
            [in] dc                 - Destination DC
                 cbz                - The stucture containing the control
                                      points of the curve, 4 in this case
                 levels             - Level of detail
                 clr                - Color

        Returns:
            Nothing

        Description:
            Draws a cubic bezier on the requested DC. Optimal level of
            detail is between 8-20.
            Uses forward differencing + fixed point.

        Example:
            cbez.bas

    ======================================================
       2.2.7 - uglQuadricBez
    ======================================================

        Prototype:
            declare sub uglQuadricBez (byval dc as long, seg qbz as QUADBEZ,_
                                       byval levels as integer, byval clr as long)

        Arguments:
            [in] dc                 - Destination DC
                 qbz                - The stucture containing the control
                                      points of the curve, 3 in this case
                 levels             - Level of detail
                 clr                - Color

        Returns:
            Nothing

        Description:
            Draws a quadric bezier on the requested DC. Optimal level
            of detail is between 8-20.
            Uses forward differencing + fixed point.

        Example:
            qbez.bas

    ======================================================
       2.2.8 - uglGet
    ======================================================

        Prototype:
            declare sub uglGet (byval src as long, byval x as integer,_
                                byval y as integer, byval dst as long)

        Arguments:
            [in]  src               - Source DC
                  x                 - Start X on source DC
                  y                 - Start Y on source DC
                  dst               - Destination DC

        Returns:
            Nothing

        Description:
            Gets an image from the source DC onto the destination DC.
            The size of the image is the same as the size of the
            destination DC. It starts getting from the cooridnates
            x and y on the source DC.

        Example:
            None

    ======================================================
       2.2.9 - uglPut
    ======================================================

        Prototype:
            declare sub uglPut (byval dst as long, byval x as integer,_
                                byval y as integer, byval src as long)

        Arguments:
            [in]  dst               - Destination DC
                  x                 - Start X on the destination DC
                  y                 - Start Y on the destination DC
                  src               - Source DC

        Returns:
            Nothing

        Description:
            Blits (copies) the source DC onto the destination DC.
            Starts at x and y on the destination DC.

        Example:
            put.bas

    ======================================================
       2.2.10 - uglPutMsk
    ======================================================

        Prototype:
            declare sub uglPutMsk (byval dst as long, byval x as integer,_
                                   byval y as integer, byval src as long)

        Arguments:
            [in]  dst               - Destination DC
                  x                 - Start X on the destination DC
                  y                 - Start Y on the destination DC
                  src               - Source DC

        Returns:
            Nothing

        Description:
            Same as uglPut except it does a transparent blit. Masks
            out the RGB color (1.0, 0.0, 1.0).

        Example:
            putmsk.bas

    ======================================================
       2.2.11 - uglHLine
    ======================================================

        Prototype:
            declare sub uglHLine (byval dc as long, byval x1 as integer,_
                                  byval y as integer, byval x2 as integer,_
                                  byval clr as long)

        Arguments:
            [in] dc                 - Destination DC
                 x1, y, x2          - Coordinates
                 clr                - Color

        Returns:
            Nothing

        Description:
            Draws a horizontal line on the requested DC.

        Example:
            hline.bas

    ======================================================
       2.2.12 - uglVLine
    ======================================================

        Prototype:
            declare sub uglVLine (byval dc as long, byval x as integer,_
                                  byval y1 as integer, byval y2 as integer,_
                                  byval clr as long)

        Arguments:
            [in] dc                 - Destination DC
                 x, y1, y2          - Coordinates
                 clr                - Color

        Returns:
            Nothing

        Description:
            Draws a vertical line on the requested DC.

        Example:
            vline.bas

    ======================================================
       2.2.13 - uglLine
    ======================================================

        Prototype:
            declare sub uglLine (byval dc as long, byval x1 as integer,_
                                 byval y1 as integer, byval x2 as integer,_
                                 byval y2 as integer, byval clr as long)

        Arguments:
            [in] dc                 - Destination DC
                 x1, y1, x2, y2     - Coordinates
                 clr                - Color

        Returns:
            Nothing

        Description:
        Draws a line on the requested DC.

        Example:
            line.bas

    ======================================================
       2.2.14 - uglPSet
    ======================================================

        Prototype:
            declare sub uglPSet (byval dc as long, byval x as integer,_
                                 byval y as integer, byval clr as long)

        Arguments:
            [in] dc                 - Destination DC
                 x, y               - Coorindates
                 clr                - Color

        Returns:
            Nothing

        Description:
            Plots a pixel on the requested DC.

        Example:
            None

    ======================================================
       2.2.15 - uglPGet
    ======================================================

        Prototype:
            declare function uglPGet (byval dc as long, byval x as integer,_
                                      byval y as integer)

        Arguments:
            [in] dc                 - Destination DC
                 x, y               - Coorindates

        Returns:
            The color value of the desired pixel

        Description:
            Get the color of a certain pixel in a DC.

        Example:
            None

    ======================================================
       2.2.16 - uglPoly
    ======================================================

        Prototype:
            declare sub uglPoly (byval dc as long, seg pntArray as PNT2D,_
                                 byval points as integer, byval clr as long)

        Arguments:
            [in] dc                 - Destination DC
                 pntArray           - An array of points that define the
                                      polygon
                 points             - Number of points in the array
                 clr                - Color

        Returns:
            Nothing

        Description:
            Draws the outline of a complex polygon on the
            requested DC.

        Example:
            poly.bas

    ======================================================
       2.2.17 - uglPolyF
    ======================================================

        Prototype:
            declare sub uglPolyF (byval dc as long, seg pntArray as PNT2D,_
                                  byval points as integer, byval clr as long)

        Arguments:
            [in] dc                 - Destination DC
                 pntArray           - An array of points that define the
                                      polygon
                 points             - Number of points in the array
                 clr                - Color

        Returns:
            Nothing

        Description:
            Same as uglPoly except it fills the polygon with a
            solid color.

        Example:
            polyf.bas

    ======================================================
       2.2.18 - uglPolyPoly
    ======================================================

        Prototype:
            declare sub uglPolyPoly (byval dc as long, seg pntArray as PNT2D,_
                                     cntArray as PNT2D, byval polygons as integer,_
                                     byval clr as long)

        Arguments:
            [in] dc                 - Destination DC
                 pntArray           - Array of the type PNT2D where the points
                                      for each polygon is stored
                 cntArray           - Array that describes how many points each
                                      polygon has
                 polygons           - Tells the routine how many polygons
                                      there are
                 clr                - Color

        Returns:
            Nothing

        Description:
            Draws the outlines of several complex polygons on
            the requested DC. Yes, it's a stupid name :)

        Example:
            polypoly.bas

    ======================================================
       2.2.19 - uglPolyPolyF
    ======================================================

        Prototype:
            declare sub uglPolyPolyF (byval dc as long, seg pntArray as PNT2D,_
                                      cntArray as PNT2D, byval polygons as integer,_
                                      byval clr as long)

        Arguments:
            [in] dc                 - Destination DC
                 pntArray           - Array of the type PNT2D where the points
                                      for each polygon is stored
                 cntArray           - Array that describes how many points each
                                      polygon has
                 polygons           - Tells the routine how many polygons
                                      there are
                 clr                - Color

        Returns:
            Nothing

        Description:
            Same as uglPolyPoly except it fills the polygons with a
            solid color.

        Example:
            polypolyf.bas

    ======================================================
       2.2.20 - uglEllipse
    ======================================================

        Prototype:
            declare sub uglEllipse (byval dc as long, byval cx as integer,_
                                    byval cy as integer, byval rx as integer,_
                                    byval ry as integer, byval clr as long)

        Arguments:
            [in]  dc                - Destination DC
                  cx, cy            - Start x,y on the destination DC
                  rx, ry            - x, y radius
                  clr               - Color

        Returns:
            Nothing

        Description:
            Draws the outline of an ellipse on a DC

        Example:
            ellip.bas

    ======================================================
       2.2.21 - uglEllipseF
    ======================================================

        Prototype:
            declare sub uglEllipseF (byval dc as long, byval cx as integer,_
                                     byval cy as integer, byval rx as integer,_
                                     byval ry as integer, byval clr as long)

        Arguments:
            [in]  dc                - Destination DC
                  cx, cy            - Start x,y on the destination DC
                  rx, ry            - x, y radius
                  clr               - Color

        Returns:
            Nothing

        Description:
            Draws a filled ellipse on a DC

        Example:
            ellipf.bas

    ======================================================
       2.2.22 - uglPutFlip
    ======================================================

        Prototype:
            declare sub uglPutFlip (byval dst as long, byval x as integer,_
                                    byval y as integer,byval mode as integer,_
                                    byval src as long)

        Arguments:
            [in]  dst               - Destination DC
                  x, y              - Start x,y on the destination DC
                  mode              - Flip mode to use flip
                                        UGL.VFLIP  (flipped vertically),
                                        UGL.HFLIP  (flipped horizontally),
                                        UGL.VHFLIP (both)
                  src               - Source DC

        Returns:
            Nothing

        Description:
            Same as uglPut except it can flip the image.

        Example:
            putf.bas

    ======================================================
       2.2.23 - uglPutMskFlip
    ======================================================

        Prototype:
            declare sub uglPutMskFlip (byval dst as long, byval x as integer,_
                                       byval y as integer,byval mode as integer,_
                                       byval src as long)

        Arguments:
            [in]  dst               - Destination DC
                  x, y              - Start x,y on the destination DC
                  mode              - Flip mode to use flip
                                        UGL.VFLIP  (flipped vertically),
                                        UGL.HFLIP  (flipped horizontally),
                                        UGL.VHFLIP (both)
                  src               - Source DC

        Returns:
            Nothing

        Description:
            Same as uglPutMsk except it can flip the image.

        Example:
            putmskf.bas

    ======================================================
       2.2.24 - uglPutRot
    ======================================================

       desc: draws a rotated image on destine dc

       args: [in] dst:long,         | destine dc
                  x:integer,        | center col
                  y:integer,        | /      row
                  angle:single,     | angle (in degrees)
                  src:long          | source dc (max 64k)
       retn: none

       decl: uglPutRot (byval dst as long,_
                        byval x as integer, byval y as integer,_
                        byval angle as single,_
                        byval src as long)

       chng: aug/02 written [Blitz]
       obs.: none

    ======================================================
       2.2.25 - uglPutScl
    ======================================================

       desc: draws a scaled image on destine dc

       args: [in] dst:long,         | destine dc
                  x:integer,        | center col
                  y:integer,        | /      row
                  xScale:single,    | horz scale (1 = 100%?)
                  yScale:single,    | vert scale (/)
                  src:long          | source dc (max 64k)
       retn: none

       decl: uglPutScl (byval dst as long,_
                        byval x as integer, byval y as integer,_
                        byval xScale as single, byval yScale as single,_
                        byval src as long)

       chng: aug/02 written [Blitz]
       obs.: none

    ======================================================
       2.2.26 - uglPutRotScl
    ======================================================

       desc: draws a rotated and scaled image on destine dc

       args: [in] dst:long,         | destine dc
                  x:integer,        | center col
                  y:integer,        | /      row
                  angle:single,     | angle (in degrees)
                  xScale:single,    | horz scale (1 = 100%?)
                  yScale:single,    | vert scale (/)
                  src:long          | source dc (max 64k)
       retn: none

       decl: uglPutRotScl (byval dst as long,_
                           byval x as integer, byval y as integer,_
                           byval angle as single,_
                           byval xScale as single, byval yScale as single,_
                           byval src as long)

       chng: aug/02 written [Blitz]
       obs.: none

    ======================================================
       2.2.27 - uglPutMskRot
    ======================================================

       desc: draws a rotated sprite on destine dc

       args: [in] dst:long,         | destine dc
                  x:integer,        | center col
                  y:integer,        | /      row
                  angle:single,     | angle (in degrees)
                  src:long          | source dc (max 64k)
       retn: none

       decl: uglPutMskRot (byval dst as long,_
                           byval x as integer, byval y as integer,_
                           byval angle as single,_
                           byval src as long)

       chng: aug/02 written [Blitz]
       obs.: none

    ======================================================
       2.2.28 - uglPutMskScl
    ======================================================

       desc: draws a scaled sprite on destine dc

       args: [in] dst:long,         | destine dc
                  x:integer,        | center col
                  y:integer,        | /      row
                  xScale:single,    | horz scale (1 = 100%?)
                  yScale:single,    | vert scale (/)
                  src:long          | source dc (max 64k)
       retn: none

       decl: uglPutMskScl (byval dst as long,_
                           byval x as integer, byval y as integer,_
                           byval xScale as single, byval yScale as single,_
                           byval src as long)

       chng: aug/02 written [Blitz]
       obs.: none

    ======================================================
       2.2.29 - uglPutMskRotScl
    ======================================================

       desc: draws a rotated and scaled sprite on destine dc

       args: [in] dst:long,         | destine dc
                  x:integer,        | center col
                  y:integer,        | /      row
                  angle:single,     | angle (in degrees)
                  xScale:single,    | horz scale (1 = 100%?)
                  yScale:single,    | vert scale (/)
                  src:long          | source dc (max 64k)
       retn: none

       decl: uglPutMskRotScl (byval dst as long,_
                              byval x as integer, byval y as integer,_
                              byval angle as single,_
                              byval xScale as single, byval yScale as single,_
                              byval src as long)

       chng: aug/02 written [Blitz]
       obs.: none

    ======================================================
       2.3.1 - uglSetVisPage
    ======================================================

        Prototype:
            declare sub uglSetVisPage (byval visPg as integer)

        Arguments:
            [in] vidPg              - The page to make visible

        Returns:
            Nothing

        Description:
            This routine is used for paging. It set's the page that
            should be viewed on screen.

        Example:
            flip.bas

    ======================================================
       2.3.2 - uglSetWrkPage
    ======================================================

        Prototype:
            declare sub uglSetWrkPage (byval wrkPg as integer)

        Arguments:
            [in] wrkPg              - The page to be written to when
                                      refering to the video DC.

        Returns:
            Nothing

        Description:
            Used for paging. It sets the page that is should to be written
            to when using the video DC as destination.

        Example:
            flip.bas

    ======================================================
       2.4.1 - uglColor
    ======================================================

        Prototype:
            declare function uglColor& (byval fmt as integer, byval red as integer,_
                                        byval green as integer, byval blue as integer)

        Arguments:
            [in] fmt                - Color format
                 red                - Red component   => 0 <= 255
                 green              - Green component => 0 <= 255
                 blue               - Blue component  => 0 <= 255

        Returns:
            The packed color value

        Description:
            Converts RGB to the packed color value used, the destination
            color format can be UGL.8BIT, UGL.15BIT, UGL.16BIT or UGL.32BIT

        Example:
            None

    ======================================================
       2.4.2 - uglColor8
    ======================================================

        Prototype:
            declare function uglColor8& (byval red as integer, byval green as integer,_
                                         byval blue as integer)

        Arguments:
            [in] red                - Red component   => 0 <= 7
                 green              - Green component => 0 <= 7
                 blue               - Blue component  => 0 <= 3

        Returns:
            The packed color value

        Description:
            Same as uglColor except it target bitdepth is for 8 bit
            color modes only.

        Example:
            None

    ======================================================
       2.4.3 - uglColor15
    ======================================================

        Prototype:
            declare function uglColor15& (byval red as integer, byval green as integer,_
                                          byval blue as integer)

        Arguments:
            [in] red                - Red component   => 0 <= 31
                 green              - Green component => 0 <= 31
                 blue               - Blue component  => 0 <= 31

        Returns:
            The packed color value

        Description:
            Same as uglColor except it target bitdepth is for 15 bit
            color modes only.

        Example:
            None

    ======================================================
       2.4.4 - uglColor16
    ======================================================

        Prototype:
            declare function uglColor16& (byval red as integer, byval green as integer,_
                                          byval blue as integer)

        Arguments:
            [in] red                - Red component   => 0 <= 31
                 green              - Green component => 0 <= 63
                 blue               - Blue component  => 0 <= 31

        Returns:
            The packed color value

        Description:
            Same as uglColor except it target bitdepth is for 16 bit
            color modes only.

        Example:
            None

    ======================================================
       2.4.5 - uglColor32
    ======================================================

        Prototype:
            declare function uglColor32& (byval red as integer, byval green as integer,_
                                          byval blue as integer)

        Arguments:
            [in] red                - Red component   => 0 <= 255
                 green              - Green component => 0 <= 255
                 blue               - Blue component  => 0 <= 255

        Returns:
            The packed color value

        Description:
            Same as uglColor except it target bitdepth is for 32 bit
            color modes only.

        Example:
            None

    ======================================================
       2.4.6 - uglGetConv
    ======================================================

        Prototype:
            declare sub uglGetConv (byval src as long, byval x as integer,_
                                    byval y as integer, byval dst as long)

        Arguments:
            [in]  src               - Source DC
                  x                 - Start X on source DC
                  y                 - Start Y on source DC
                  dst               - Destination DC

        Returns:
            Nothing

        Description:
            Does the same as uglGet except it does color conversion if
            it's needed.

        Example:
            none

    ======================================================
       2.4.7 - uglPutConv
    ======================================================

        Prototype:
            declare sub uglPutConv (byval dst as long, byval x as integer,_
                                    byval y as integer, byval src as long)

        Arguments:
            [in]  dst               - Destination DC
                  x                 - Start X on source DC
                  y                 - Start Y on source DC
                  src               - Source DC

        Returns:
            Nothing

        Description:
            Does the same as uglPut except it does color conversion if
            it's needed.

        Example:
            putconv.bas

    ======================================================
       2.4.8 - uglRowRead
    ======================================================

        Prototype:
            declare sub uglRowRead (byval dc as long, byval x as integer,_
                                    byval y as integer, byval pixels as integer,_
                                    byval bufferFormat as integer, byval buffer as long)

        Arguments:
            [in] dc                 - Source DC
                 x, y               - Coordinates to start reading from
                 pixels             - Number of pixels to read
                 bufferFormat       - The color format of the destination buffer
            [out] buffer            - A far pointer to the destination buffer,
                                      where the upper 16 bits is segment and lower
                                      16 bits is the offset (seg:off)

        Returns:
            Nothing

        Description:
            This routine should be used when you want to copy pixels
            from a DC to a self defined buffer. The buffer could be a
            a qb array or some other area in memory, as long as it's
            within the 1 MB memory limit of realmode. It also does color
            conversion if it's needed.

        Example:
            row.bas

    ======================================================
       2.4.9 - uglRowReadEx
    ======================================================

        Prototype:
            declare sub uglRowReadEx alias "uglRowRead"_
                         (byval dc as long, byval x as integer,_
                          byval y as integer, byval pixels as integer,_
                          byval bufferFormat as integer, seg buffer as any)

        Arguments:
            [in] dc                 - Source DC
                 x, y               - Coordinates to start reading from
                 pixels             - Number of pixels to read
                 bufferFormat       - The color format of the destination buffer
            [out] buffer            - The array or variable you want to use as
                                      destination

        Returns:
            Nothing

        Description:
            Same as uglRowRead except the argument buffer is no
            longer a far pointer to the buffer, it's the actual
            buffer.

        Example:
            None

    ======================================================
       2.4.10 - uglRowWrite
    ======================================================

        Prototype:
            declare sub uglRowWrite (byval dc as long, byval x as integer,_
                                     byval y as integer, byval pixels as integer,_
                                     byval bufferFormat as integer, byval buffer as long)

        Arguments:
            [in] dc                 - Source DC
                 x, y               - Coordinates to start reading from
                 pixels             - Number of pixels to write
                 bufferFormat       - The color format of the source buffer
                 buffer             - A far pointer to the destination buffer,
                                      where the upper 16 bits is segment and lower
                                      16 bits is the offset (seg:off)

        Returns:
            Nothing

        Description:
            This routine should be used when you want to copy pixels
            from a self defined buffer to a DC. The buffer could be a
            a qb array or some other area in memory, as long as it's
            within the 1 MB memory limit of realmode. It also does color
            conversion if it's needed.

        Example:
            row.bas

    ======================================================
       2.4.11 - uglRowWriteEx
    ======================================================

        Prototype:
            declare sub uglRowWriteEx alias "uglRowWrite"_
                                (byval dc as long, byval x as integer,_
                                 byval y as integer, byval pixels as integer,_
                                 byval bufferFormat as integer, seg buffer as any)

        Arguments:
            [in] dc                 - Destination DC
                 x, y               - Coordinates to start reading from
                 pixels             - Number of pixels to write
                 bufferFormat       - The color format of the source buffer
                 buffer             - The array or variable you want to use as
                                      source

        Returns:
            Nothing

        Description:
            Same as uglRowWrite except the argument buffer is no
            longer a far pointer to the buffer, it's the actual
            buffer.

        Example:
            None

    ======================================================
       2.4.12 - uglRowSetPal
    ======================================================

        Prototype:
            declare sub uglRowSetPal (byval dcFmt as integer, byval bufferFmt as integer,_
                                      byval pallete as long, byval entries as integer)

        Arguments:
            [in] dcType             - The color format of the
                                      source/destination DC
                 bufferFmt          - The color format of the buffer
                 pallete            - A far pointer to the pallete (ARGB)
                 entries            - Number of entries in the palette, if the
                                      you set this argument to 0 it will use all
                                      255 entries

        Returns:
            Nothing

        Description:
            This routine set's the pallete used for color conversion
            with the uglRowRead and uglRowWrite routines. If the argument
            bufferFmt is other then UGL.8BIT it will just be ignored. Only
            one palette can be used at the same time for conversion between
            8 <-> 8, 8 <-> 15, 8 <-> 16 and 8 <-> 32.

        Example:
            None

    ======================================================
       2.5.1 - uglNewBMP
    ======================================================

        Prototype:
            declare sub uglNewBMP& (byval typ as integer, byval fmt as integer, _
                                    flname as string)

        Arguments:
            [in] typ                - What kind of DC to allocate MEM/EMS
                 fmt                - The color format of the allocated dc
                                      UGL.8BIT, UGL.15BIT, UGL.16BIT, UGL.32BIT
                 flname             - Path and filename of the bitmap

        Returns:
            Handle to the DC that contains the Bitmap if the call was
            successful, if not it's returns False

        Description:
            This routine creates a DC with same dimensions as the bitmap
            and loads the bitmap onto the DC. The bitmap can be 1, 4, 8,
            15, 16, 24 & 32-bit non-compressed and 4-/8-bit RLE compressed
            Microsoft Windows BMP file.

        Example:
            bmp.bas

    ======================================================
       2.5.2 - uglPutBMP
    ======================================================

        Prototype:
            declare sub uglPutBMP% (byval dc as long, byval x as integer,_
                                    byval y as integer, flname as string)

        Arguments:
            [in] dc                 - Handle to the DC to blit the bmp
                 x, y               - Coordinates on the DC to start
                                      blitting to
                 flname             - Path and filename of the bitmap

        Returns:
            True if it was able to perform the task, False otherwise

        Description:
            Same as for uglNewBMP.

        Example:
            putbmp.bas

    ======================================================
       2.5.3 - uglNewBMPEx
    ======================================================

        Prototype:
            declare sub uglNewBMPEx& (byval typ as integer, byval fmt as integer, _
                                      flname as string, byval opt as integer
        Arguments:
            [in] typ                - What kind of DC to allocate MEM/EMS
                 fmt                - The color format of the allocated dc
                                      UGL.8BIT, UGL.15BIT, UGL.16BIT, UGL.32BIT
                 flname             - Path and filename of the bitmap
                 opt                - BMPOPT.NO332, BMPOPT.MASK

        Returns:
            Handle to the DC that contains the Bitmap if the call was
            successful, if not it's returns False

        Description:
            Same as uglNew, except BMPOPT.NO332 will tell it not to
            convert the colors to the 332 palette for 8 bit dcs. And
            BMPOPT.MASK will filter out the mask color (1.0, 0.0, 1.0).

        Example:
            none

    ======================================================
       2.5.4 - uglPutBMPEx
    ======================================================

        Prototype:
            declare sub uglPutBMPEx% (byval dc as long, _
                                      byval x as integer, byval y as integer, _
                                      flname as string, byval opt as integer)

        Arguments:
            [in] dc                 - Handle to the DC to blit the bmp
                 x, y               - Coordinates on the DC to start
                                      blitting to
                 flname             - Path and filename of the bitmap
                 opt                - BMPOPT.NO332, BMPOPT.MASK

        Returns:
            True if it was able to perform the task, False otherwise

        Description:
            Same as uglPut, except BMPOPT.NO332 will tell it not to
            convert the colors to the 332 palette for 8 bit dcs. And
            BMPOPT.MASK will filter out the mask color (1.0, 0.0, 1.0).

        Example:
            none

    ======================================================
       2.6.1 - uglColors
    ======================================================

        Prototype:
            declare sub uglColors& (byval fmt as integer)

        Arguments:
            [in] fmt                - The target bit depth

        Returns:
            Number of colors available for that specific
            color format

        Description:
        Returns the number of colors available for a
        specific color format.

        Example:
            None

    ======================================================
       2.6.2 - uglColorsEx
    ======================================================

        Prototype:
            declare sub uglColorsEx& (byval dc as long)

        Arguments:
            [in] dc                - The target DC

        Returns:
            Number of colors available for that
            specific DC.

        Description:
        Returns the number of colors available for a
        specific DC.

        Example:
            None

    ======================================================
       2.6.3 - uglDCget
    ======================================================

        Prototype:
            declare sub uglDCget (byval dc as long, seg dcInfo as TDC)

        Arguments:
            [in] dc                - The target DC
           [out] dcInfo            - A variable of the type TDC

        Returns:
        Nothing

        Description:
        This routine should be used to get information
        about a certain DC.

        Example:
            None

    ======================================================
       2.6.4 - uglDCAccessRd
    ======================================================

       desc: returns a pointer to a dc scanline (for read access)

       args: [in]  dc:long,         | DC to access
                   y:integer        | scanline
       retn: far pointer to scanline

       decl: uglDCAccessRd (byval dc as long,_
                            byval y as integer)

       chng: sep/02 [v1ctor]
       obs.: no clipping is done

    ======================================================
       2.6.5 - uglDCAccessWr
    ======================================================

       desc: returns a pointer to a dc scanline (for write access)

       args: [in]  dc:long,         | DC to access
                   y:integer        | scanline
       retn: far pointer to scanline

       decl: uglDCAccessWr (byval dc as long,_
                            byval y as integer)

       chng: sep/02 [v1ctor]
       obs.: no clipping is done

    ======================================================
       2.6.6 - uglDCAccessRdWr
    ======================================================

       desc: returns pointers to a dc scanline (for read and write access)

       args: [in]  dc:long,         | DC to access
                   y:integer,       | scanline
                   rdPtr:*long      | read access far pointer
       retn: far pointer to scanline

       decl: uglDCAccessRdWr (byval dc as long,_
                              byval y as integer,_
                              rdPtr as long)

       chng: sep/02 [v1ctor]
       obs.: no clipping is done

    ======================================================
       2.7.1 - uglTriF
    ======================================================

        Prototype:
            declare sub uglTriF (byval dc as long, _
                                 seg vtx as TriType, _
                                 byval clr as long)

        Arguments:
            [in] dc               - The destination DC
                 vtx              - The tri coordinates
                 clr              - the color
        Returns:
            nothing

        Description:
            Draws a flat shaded triangle on the
            destination DC. Meant to be used by 3D
            applications and has sub pixel accuracy. No
            specific vertex order is required. However,
            clock wise order is recomended.

        Example:
            trif.bas

    ======================================================
       2.7.2 - uglQuadF
    ======================================================

        Prototype:
            declare sub uglQuadF (byval dc as long, _
                                  seg vtx as QuadType, _
                                  byval clr as long)

        Arguments:
            [in] dc               - The destination DC
                 vtx              - The quad coordinates
                 clr              - the color
        Returns:
            nothing

        Description:
            Draws a flat shaded quadrangle on the
            destination DC. Meant to be used by 3D
            applications and has sub pixel accuracy.
            Clockwise vertex order is required.

        Example:
            quadf.bas

    ======================================================
       2.7.3 - uglTriT
    ======================================================

        Prototype:
            declare sub uglTriT (byval dstDC as long, _
                                 seg vtx as TriType, _
                                 byval mask as integer, _
                                 byval srcDC as long)

        Arguments:
            [in] dstDC            - The destination DC
                 vtx              - The tri coordinates and
                                    texture coordinates
                 mask             - Wether or not to filter out the
                                    color (1.0, 0.0, 1.0), can be:
                                        UGL.MASK.FALSE
                                        UGL.MASK.TRUE
                 srcDC            - The DC where the texture is

        Returns:
            nothing

        Description:
            Draws an affine textured triangle on the destination
            DC. Meant to be used by 3D applications and has sub
            pixel & texel accuracy. No specific vertex order is
            required. However, clockwise is recomended.

            A few rules:
                - The texture has to have power of two width and
                  height. This means the it's width and height
                  should be numbers like, 1, 2, 4, 8, 16, 32, 64
                  128, 256 etc etc.

                - If the DC is allocated in UGL.MEM it can be up
                  to 64 KB.

                - If the DC is allocated in UGL.EMS it can be up
                  to 16 KB. Although this will change in the near
                  future to 64 KB too.

                - Don't be afraid of using EMS DCs as textures.
                  The way this works in UGL virtually eliminates
                  performance loss between UGL.MEM and UGL.EMS DCs
                  for textures.

                - If the srcDC is allocated in UGL.EMS the dstDC
                  cannot be allocated in UGL.EMS and vice versa.

                - The texture coordinates are in the range
                  0.0-1.0, this makes them independant of the
                  size of the actual texture. It also makes it
                  possible for us to add mip-mapping in the future.
                  As pretty much all modellers return the texture
                  coordinates as normalized coordinates ( 0.0 - 1.0 )
                  too this shouldn't be a problem for anyone.

                - To calculate the size of an DC you do this:
                      8  bpp = 1 bytes_per_pixel
                      15 bpp = 2 bytes_per_pixel
                      16 bpp = 2 bytes_per_pixel
                      32 bpp = 4 bytes_per_pixel

                      size_in_bytes  = xRes*yRes*bytes_per_pixel
                      size_in_kbytes = size_in_bytes / 1024

                  In practice this means that if have a dc that is
                  128x128x16 it would be 128*128*2 (32768) bytes.
                  or 32768/1024 (32) kilo bytes.

                - Texturing polygons doesn't get faster then this
                  in software. So enjoy...

        Example:
            trit.bas

    ======================================================
       2.7.4 - uglQuadT
    ======================================================

        Prototype:
            declare sub uglQuadT (byval dstDC as long, _
                                  seg vtx as QuadType, _
                                  byval mask as integer, _
                                  byval srcDC as long)

        Arguments:
            [in] dstDC            - The destination DC
                 vtx              - The quad coordinates and
                                    texture coordinates
                 mask             - Wether or not to filter out the
                                    color (1.0, 0.0, 1.0), can be:
                                        UGL.MASK.FALSE
                                        UGL.MASK.TRUE
                 srcDC            - The DC where the texture is

        Returns:
            nothing

        Description:
            Draws an affine textured triangle on the destination
            DC. Meant to be used by 3D applications and has sub
            pixel & texel accuracy. Clockwise vertex order is
            required.

            A few rules:
                - The texture has to have power of two width and
                  height. This means the it's width and height
                  should be numbers like, 1, 2, 4, 8, 16, 32, 64
                  128, 256 etc etc.

                - If the DC is allocated in UGL.MEM it can be up
                  to 64 KB.

                - If the DC is allocated in UGL.EMS it can be up
                  to 16 KB. Although this will change in the near
                  future to 64 KB too.

                - Don't be afraid of using EMS DCs as textures.
                  The way this works in UGL virtually eliminates
                  performance loss between UGL.MEM and UGL.EMS DCs
                  for textures.

                - If the srcDC is allocated in UGL.EMS the dstDC
                  cannot be allocated in UGL.EMS and vice versa.

                - The texture coordinates are in the range
                  0.0-1.0, this makes them independant of the
                  size of the actual texture. It also makes it
                  possible for us to add mip-mapping in the future.
                  As pretty much all modellers return the texture
                  coordinates as normalized coordinates ( 0.0 - 1.0 )
                  too this shouldn't be a problem for anyone.

                - To calculate the size of an DC you do this:
                      8  bpp = 1 bytes_per_pixel
                      15 bpp = 2 bytes_per_pixel
                      16 bpp = 2 bytes_per_pixel
                      32 bpp = 4 bytes_per_pixel

                      size_in_bytes  = xRes*yRes*bytes_per_pixel
                      size_in_kbytes = size_in_bytes / 1024

                  In practice this means that if have a dc that is
                  128x128x16 it would be 128*128*2 (32768) bytes.
                  or 32768/1024 (32) kilo bytes.

                - Texturing polygons doesn't get faster then this
                  in software. So enjoy...

        Example:
            quadt.bas

    ======================================================
       2.7.5 - uglTriG
    ======================================================

        Prototype:
            declare sub uglTriF (byval dc as long, _
                                 seg vtx as TriType)

        Arguments:
            [in] dc               - The destination DC
                 vtx              - The tri coordinates

        Returns:
            nothing

        Description:
            Draws a gouraud shaded triangle on the
            destination DC. Meant to be used by 3D
            applications and has sub pixel accuracy. No
            specific vertex order is required. However,
            clock wise order is recomended.

        Example:
            trig.bas

    ======================================================
       2.8.1 - uglPalGet
    ======================================================

        Prototype:
            declare sub uglPalGet ( byval idx as integer, _
                                    byval entries as integer, _
                                    byval pal as long )

        Arguments:
            [in] idx              - Index of the first color to get
                 entries          - Number of colors to get
                 pal              - a far pointer to the palette

        Returns:
            nothing

        Description:
            Fetches the palette starting at the color specified
            as the idx argument and getting as many colors as
            specified as the entries argument.

            NOTE: The color components are in the range 0-255
                  and not 0-63 which you might used to. This
                  is becuase many VESA cards support higher
                  precision palettes.

                  To convert a palette with components in the
                  range 0-63 to one with the range 0-255, just
                  take each component and multiply it with four.

        Example:
            none

    ======================================================
       2.8.2 - uglPalSet
    ======================================================

        Prototype:
            declare sub uglPalSet ( byval idx as integer, _
                                    byval entries as integer, _
                                    byval pal as long )

        Arguments:
            [in] idx              - Index of the first color to change
                 entries          - Number of colors to change
                 pal              - a far pointer to the palette

        Returns:
            nothing

        Description:
            Changes the palette starting at the color specified
            as the idx argument and setting as many colors as
            specified as the entries argument.

            NOTE: The color components are in the range 0-255
                  and not 0-63 which you might used to. This
                  is becuase many VESA cards support higher
                  precision palettes.

                  To convert a palette with components in the
                  range 0-63 to one with the range 0-255, just
                  take each component and multiply it with four.

        Example:
            none

    ======================================================
       2.8.3 - uglPalGetBuff
    ======================================================

        Prototype:
            declare sub uglPalGetBuff ( byval idx as integer, _
                                        byval entries as integer, _
                                        seg pal as TRGB )

        Arguments:
            [in] idx              - Index of the first color to change
                 entries          - Number of colors to change
                 pal              - an array of the type TRGB which
                                    contains the palette

        Returns:
            nothing

        Description:
            Fetches the palette starting at the color specified
            as the idx argument and getting as many colors as
            specified as the entries argument.

            NOTE: The color components are in the range 0-255
                  and not 0-63 which you might used to. This
                  is becuase many VESA cards support higher
                  precision palettes.

                  To convert a palette with components in the
                  range 0-63 to one with the range 0-255, just
                  take each component and multiply it with four.

        Example:
            none

    ======================================================
       2.8.4 - uglPalSetBuff
    ======================================================

        Prototype:
            declare sub uglPalSetBuff ( byval idx as integer, _
                                        byval entries as integer, _
                                        seg pal as TRGB )

        Arguments:
            [in] idx              - Index of the first color to change
                 entries          - Number of colors to change
                 pal              - an array of the type TRGB which
                                    contains the palette

        Returns:
            nothing

        Description:
            Sets the palette starting at the color specified
            as the idx argument and setting as many colors as
            specified as the entries argument.

            NOTE: The color components are in the range 0-255
                  and not 0-63 which you might used to. This
                  is becuase many VESA cards support higher
                  precision palettes.

                  To convert a palette with components in the
                  range 0-63 to one with the range 0-255, just
                  take each component and multiply it with four.

        Example:
            none

    ======================================================
       2.8.5 - uglPalLoad
    ======================================================

        Prototype:
            declare function uglPalLoad& (flname as string, _
                                          byval fmt as integer)

        Arguments:
            [in] filename         - Filename of the palette to load
                 fmt              - The format which the palette is
                                    stored in the file, either PALRGB
                                    or PALBGR

        Returns:
            nothing

        Description:
            Loads a file containing a palette into memory and
            returns a far pointer to it.

            Use uglPalSet to set the palette and free the memory
            with memFree

        Example:
            none

    ======================================================
       3.1.1 - ugluCubicBez
    ======================================================

        Prototype:
          declare sub ugluCubicBez (SEG storage as PNT2D, SEG cbz as CUBICBEZ,_
                                    BYVAL levels as integer)

        Arguments:
          [in]  cbz                 - Cubic bezier struct with the 4 control
                                      points
                levels              - Level of detail, has to be bigger then one
          [out] storage             - Array of the type PNT2D to store the curve
                                      points. The size of the array has to be
                                      levels + 1.

        Returns:
            Nothing

        Description:
            This is basically the same routine as uglCubicBez except instead
            of drawing the curve on screen it stores the curve points in an
            array of the type PNT2D. The size of array has to be levels + 1.
            The argument levels tells routine how much detail it should
            create the curve with. The more detail the curve has the nicer it
            looks and the longer it takes to compute. A good balance is between
            16-32 points for the detail. It should be noted that this routine
            uses a technique called forward differencing, instead of using
            zillions of multiplications to compute each point on the curve it
            uses just 3 adds per component. Also to be noted is that it uses
            fixed point all the way so it's friendly to use on cpu's that have
            weak or no fpu's.

        Example:
            ucbez.bas

    ======================================================
      3.1.2 - ugluCubicBez3D
    ======================================================

        Prototype:
          declare sub ugluCubicBez3D (SEG storage as PNT3D, SEG cbz as CUBICBEZ3D_
                                      BYVAL levels as integer)

        Arguments:
          [in]  cbz                 - Cubic bezier struct with the 4 control
                                      points
                levels              - Level of detail, has to be bigger then one
          [out] storage             - Array of the type PNT3D to store the curve
                                      points. The size of the array has to be
                                      levels + 1.

        Returns:
            Nothing

        Description:
            This is basically the same routine as ugluCubicBez except instead
            except it uses the fpu and considers the Z coordinate and not just
            X and Y. The size of array has to be levels + 1.
            The argument levels tells routine how much detail it should
            create the curve with. The more detail the curve has the nicer
            it looks and the longer it takes to compute. A good balance is
            between 16-32 points for the detail. It should be noted that this
            routine uses a technique called forward differencing, instead of
            using zillions of multiplications to compute each point on the
            curve it uses just 3 adds per component. Becuase floating point
            it used all through the 3D pipeline i decided that this routine
            should work with floating point. Thus it uses the fpu.

        Example:
            ucbez3d.bas

    ======================================================
       3.1.3 - ugluQuadricBez
    ======================================================

        Prototype:
          declare sub ugluQuadricBez (SEG storage as PNT2D, SEG qbz as QUADBEZ,_
                                      BYVAL levels as integer)

        Arguments:
          [in]  qbz                 - Quadric bezier struct with the 3 control
                                      points
                levels              - Level of detail, has to be bigger then one
          [out] storage             - Array of the type PNT2D to store the curve
                                      points. The size of the array has to be
                                      levels + 1.

        Returns:
            Nothing

        Description:
            This is basically the same routine as uglQuadricBez except instead
            of drawing the curve on screen it stores the curve points in an
            array of the type PNT2D. The size of array has to be levels + 1.
            The argument levels tells routine how much detail it should
            create the curve with. The more detail the curve has the nicer it
            looks and the longer it takes to compute. A good balance is between
            12-20 points for the detail. It should be noted that this routine
            uses a technique called forward differencing, instead of using
            zillions of multiplications to compute each point on the curve it
            uses just 2 adds per component. Also to be noted is that it uses
            fixed point all the way so it's friendly to use on cpu's that have
            weak or no fpu's.

        Example:
            uqbez.bas

    ======================================================
       3.1.4 - ugluQuadricBez3D
    ======================================================

        Prototype:
          declare sub ugluQuadricBez3D (SEG storage as PNT3D, SEG qbz as QUADBEZ3D_
                                        BYVAL levels as integer)

        Arguments:
          [in]  qbz                 - Quadric bezier struct with the 3 control
                                      points
                levels              - Level of detail, has to be bigger then one
          [out] storage             - Array of the type PNT2D to store the curve
                                      points. The size of the array has to be
                                      levels + 1.

        Returns:
            Nothing

        Description:
            This is basically the same routine as ugluQuadricBez except instead
            except it uses the fpu and considers the Z coordinate and not just
            X and Y. The size of array has to be levels + 1.
            The argument levels tells routine how much detail it should
            create the curve with. The more detail the curve has the nicer
            it looks and the longer it takes to compute. A good balance is
            between 12-20 points for the detail. It should be noted that this
            routine uses a technique called forward differencing, instead of
            using zillions of multiplications to compute each point on the
            curve it uses just 2 adds per component. Becuase floating point
            it used all through the 3D pipeline i decided that this routine
            should work with floating point. Thus it uses the fpu.

        Example:
            uqbez3d.bas

    ======================================================
       3.2.1 - kbdInit
    ======================================================

        Prototype:
            declare sub kbdInit (seg kbd as TKBD)

        Arguments:
            [in/out] kbd           - A structure that holds the
                                     state of the keys
        Returns:
        Nothing

        Description:
        Installs a new keyboard ISR that enables multiple
        key presses at the same time. When you're creating
        the keyboard stucture you have to think about the
        fact that it cannot be dynamic. If it's dynamic qb
        might move it and you'll end up with a crash. Also
        important to think about is that once this ISR is
        running none of the old key board routines like
        inkey$ will work. When you're running in the IDE
        you have to make sure you deinstall this ISR before
        returning to the IDE or nothing will work.

        Example:
            kbd.bas

    ======================================================
       3.2.2 - kbdEnd
    ======================================================

        Prototype:
            declare sub kbdEnd ()

        Arguments:
            None

        Returns:
        Nothing

        Description:
        Removes the keyboard ISR installed by kbdInit
        and restores the old one. It will be called
        automatically when the program is compiled.

        Example:
            kbd.bas

    ======================================================
       3.2.3 - kbdPause
    ======================================================

        Prototype:
            declare sub kbdPause ()

        Arguments:
            None

        Returns:
        Nothing

        Description:
        Gives the control of the keyboard back to BIOS
        until kbdResume is called.

        Example:
            kbd.bas

    ======================================================
       3.2.4 - kbdResume
    ======================================================

        Prototype:
            declare sub kbdResume ()

        Arguments:
            None

        Returns:
        Nothing

        Description:
        Get the control of the keyboard back from the
        BIOS.

        Example:
            kbd.bas

    ======================================================
       3.3.1 - mouseInit
    ======================================================

        Prototype:
            declare function mouseInit% (byval dc as long, seg ms as MOUSEINF)

        Arguments:
            [in] dc:long            - The DC where the mouse cursor
                                      will be shown
        [in/out] ms                 - Structure to hold the position
                                      of the cursor and the state of
                                      the mouse buttons

        Returns:
        Returns True if everything went ok and False
        if not

        Description:
        This routine installs the device driver for the
        mouse. It's important that the ms variable is not
        dynamic. A few facts:
        - A default cursor is created
        - The range of the cursor is set to the DCs clipping
          rectangle
        - The ratio (sensitivity) is set to 8 for both
          x and y
        - The cursor is turned off

        Example:
            mouse.bas

    ======================================================
       3.3.2 - mouseReset
    ======================================================

        Prototype:
            declare function mouseReset% (byval dc as long, seg ms as MOUSEINF)

        Arguments:
            [in] dc:long            - The DC where the mouse cursor
                                      will be shown
        [in/out] ms                 - Structure to hold the position
                                      of the cursor and the state of
                                      the mouse buttons

        Returns:
        Returns True if everything went ok and False
        if not

        Description:
        Soft resets the driver, thus it assumes that
        there is a mouse. In a nutshell it does the
        same thing as mouseInit

        Example:
            mouse.bas

    ======================================================
       3.3.3 - mouseEnd
    ======================================================

        Prototype:
            declare sub mouseEnd ()

        Arguments:
        None

        Returns:
        Nothing

        Description:
        Restores the old mouse driver, will be called
        automatically when the program is compiled but
        has to be called from the IDE.

        Example:
            mouse.bas

    ======================================================
       3.3.4 - mouseCursor
    ======================================================

        Prototype:
            declare sub mouseCursor (byval cursor as long, byval xSpot as integer,_
                                     byval ySpot as integer)

        Arguments:
        [in] cursor                 - The handle to the DC that you want
                                      to use as replacement of the default
                                      cursor
             xSpot                  - ?
             ySpot                  - ?

        Returns:
        Nothing

        Description:
        Used to define a new cursor for the mouse, can be any
        color format and doesn't have to be the same as the
        destination DC.

        Example:
            mouse.bas

    ======================================================
       3.3.5 - mouseShow
    ======================================================

        Prototype:
            declare sub mouseShow ()

        Arguments:
            None

        Returns:
        Nothing

        Description:
        Makes the mouse cursor visible.

        Example:
            mouse.bas

    ======================================================
       3.3.6 - mouseHide
    ======================================================

        Prototype:
            declare sub mouseHide ()

        Arguments:
            None

        Returns:
        Nothing

        Description:
        Hides the mouse cursor.

        Example:
            mouse.bas

    ======================================================
       3.3.7 - mouseRange
    ======================================================

        Prototype:
            declare sub mouseRange (byval xmin as integer, byval ymin as integer,_
                                    byval xmax as integer, byval ymax as integer)

        Arguments:
            [in] xmin, ymin,
                 xmax, ymax         - Coordinates

        Returns:
        Nothing

        Description:
        Defines the range of the mouse cursor.

        Example:
            mouse.bas

    ======================================================
       3.3.8 - mousePos
    ======================================================

        Prototype:
            declare sub mousePos (byval x as integer, byval y as integer)

        Arguments:
            [in] x, y               - Coordinates

        Returns:
        Nothing

        Description:
        Set the position of the cursor.

        Example:
            mouse.bas

    ======================================================
       3.3.9 - mouseRatio
    ======================================================

        Prototype:
            declare sub mouseRatio (byval hMickeys as integer,_
                                    byval vMickeys as integer)

        Arguments:
            [in] hMickeys           - Mickeys per pixels (X)
                 vMickeys           - Mickeys per pixels (Y)

        Returns:
        Nothing

        Description:
        Sets the sensitivity of the mouse,
        mickeys > 0 and < 256; big values, less precision.

        Example:
            mouse.bas

    ======================================================
       3.4.1 - fontNew
    ======================================================

        Prototype:
            declare function fontNew& (fileName as string)

        Arguments:
            [in] fileName           - Font path & name

        Returns:
        A handle for the font, this handle will be used
        to refer to it. The handle is as all other UGL
        handles 32 bit (long integer). If 0 (false) is
        returned the routine failed to load the font.

        Description:
        Loads a UVF/UBF font. But for the moment only
        UVF fonts are supported.

        Example:
            uvf.bas / uvf2.bas

    ======================================================
       3.4.2 - fontDel
    ======================================================

        Prototype:
            declare sub fontDel (seg uFont as long)

        Arguments:
            [in] uFont          - Font handle

        Returns:
        Nothing

        Description:
        Frees up the memory allocated by a UVF/UBF font
        and set the handle to NULL (0). Deallocation of
        fonts is done automatically and this routine should
        only be used when you really need the memory.

        Example:
            uvf.bas / uvf2.bas

    ======================================================
       3.4.3 - fontSetAlign
    ======================================================

        Prototype:
            declare sub fontSetAlign (byval horz as integer, _
                                      byval vert as integer)

        Arguments:
            [in] horz           - horizontal alignment (FONT.HALIGN.LEFT,
                                                        FONT.HALIGN.RIGHT,
                                                        FONT.HALIGN.CENTER)
                 vert           - vertical alignment   (FONT.VALIGN.TOP,
                                                        FONT.VALIGN.BOTTOM,
                                                        FONT.VALIGN.BASELINE)

        Returns:
        Nothing

        Description:
        Sets the horizontal and vertical aligment of
        font drawn using fontTextOut

        Example:
            uvf.bas / uvf2.bas

    ======================================================
       3.4.4 - fontGetAlign
    ======================================================

        Prototype:
            declare sub fontGetAlign (horz as integer, _
                                      vert as integer)

        Arguments:
           [out] horz           - horizontal alignment
                 vert           - vertical alignment

        Returns:
        Nothing

        Description:
        Gets the horizontal and vertical aligment of
        font drawn using fontTextOut

        Example:
            none

    ======================================================
       3.4.5 - fontHAlign
    ======================================================

        Prototype:
            declare function fontHAlign% (byval mode as integer)

        Arguments:
            [in] mode           - horizontal alignment (FONT.HALIGN.LEFT,
                                                        FONT.HALIGN.RIGHT,
                                                        FONT.HALIGN.CENTER)

        Returns:
        The previous horizontal alignment

        Description:
        Sets the horizontal aligment and returns the
        current horizontal aligment.

        Example:
            none

    ======================================================
       3.4.6 - fontSetHAlign
    ======================================================

        Prototype:
            declare sub fontSetHAlign alias "fontHAlign" _
                                 (byval mode as integer)

        Arguments:
            [in] mode           - horizontal alignment (FONT.HALIGN.LEFT,
                                                        FONT.HALIGN.RIGHT,
                                                        FONT.HALIGN.CENTER)

        Returns:
        Nothing

        Description:
            Same as fontHAlign except it doesn't return
            the current setting.

        Example:
            none

    ======================================================
       3.4.7 - fontVAlign
    ======================================================

        Prototype:
            declare function fontVAlign% (byval mode as integer)

        Arguments:
            [in] mode           - vertical alignment   (FONT.VALIGN.TOP,
                                                        FONT.VALIGN.BOTTOM,
                                                        FONT.VALIGN.BASELINE)

        Returns:
        The previous vertical alignment

        Description:
        Sets the vertical aligment and returns the
        current vertical aligment.

        Example:
            none

    ======================================================
       3.4.8 - fontSetVAlign
    ======================================================

        Prototype:
            declare sub fontSetVAlign alias "fontVAlign" _
                                 (byval mode as integer)

        Arguments:
            [in] mode           - vertical alignment   (FONT.VALIGN.TOP,
                                                        FONT.VALIGN.BOTTOM,
                                                        FONT.VALIGN.BASELINE)

        Returns:
        Nothing

        Description:
        Same as fontVAlign except it doesn't return
        the current setting.

        Example:
            none

    ======================================================
       3.4.9 - fontExtraspc
    ======================================================

        Prototype:
            declare function fontExtraSpc% (byval extra as integer)

        Arguments:
            [in] extra          - Extra spacing in pixels

        Returns:
        Current spacing in pixels

        Description:
        Sets the extra spacing between the glyphs and
        returns the current setting.

        Example:
            none

    ======================================================
       3.4.10 - fontSetExtraspc
    ======================================================

        Prototype:
            declare sub fontSetExtraSpc alias "fontExtraSpc"_
                                     (byval extra as integer)

        Arguments:
            [in] extra          - Extra spacing in pixels

        Returns:
        Nothing

        Description:
        Same as fontExtraSpc except it doesn't return
        the current setting

        Example:
            none

    ======================================================
       3.4.11 - fontGetExtraspc
    ======================================================

        Prototype:
            declare function fontGetExtraspc% ()

        Arguments:
            none

        Returns:
        Current spacing in pixels

        Description:
        Returns the current spacing setting

        Example:
            none

    ======================================================
       3.4.12 - fontUnderline
    ======================================================

        Prototype:
            declare function fontUnderline% (byval underlined as integer)

        Arguments:
            [in] underlined     - true (-1), false (0)

        Returns:
        Returns the current setting

        Description:
        Sets wether or not to underline text drawn
        using fontTextOut and returns the current setting.

        Example:
            none

    ======================================================
       3.4.13 - fontSetUnderline
    ======================================================

        Prototype:
            declare sub fontSetUnderline alias "fontUnderline" _
                                 (byval underlined as integer)

        Arguments:
            [in] underlined     - true (-1), false (0)

        Returns:
        Nothing

        Description:
        Same as fontUnderline except it doesn't
        return the current setting.

        Example:
            none

    ======================================================
       3.4.14 - fontGetUnderline
    ======================================================

        Prototype:
            declare function fontGetUnderline% ()

        Arguments:
            none

        Returns:
        Returns the current setting

        Description:
        Returns the current underline setting.

        Example:
            none

    ======================================================
       3.4.15 - fontStrikeOut
    ======================================================

        Prototype:
            declare function fontStrikeOut% (byval strikedout as integer)

        Arguments:
            [in] strikedout     - true (-1), false (0)

        Returns:
        Returns the current setting

        Description:
        Sets wether or not to strikeout text drawn
        using fontTextOut and returns the current setting.

        Example:
            none

    ======================================================
       3.4.16 - fontSetStrikeOut
    ======================================================

        Prototype:
            declare sub fontSetStrikeOut alias "fontStrikeOut" _
                                 (byval strikedout as integer)

        Arguments:
            [in] strikedout     - true (-1), false (0)

        Returns:
        Nothing

        Description:
        Same as fontStrikeOut except it doesn't
        return the current setting.

        Example:
            none

    ======================================================
       3.4.17 - fontGetStrikeOut
    ======================================================

        Prototype:
            declare function fontGetStrikeOut% ()

        Arguments:
            none

        Returns:
            Returns the current setting

        Description:
            Returns the current strikeout setting.

        Example:
            none

    ======================================================
       3.4.18 - fontOutline
    ======================================================

        Prototype:
            declare function fontOutline% (byval outline as integer)

        Arguments:
            [in] outline     - true (-1), false (0)

        Returns:
            Returns the current setting

        Description:
            Sets wether or not to outline text drawn
            using fontTextOut and returns the current setting.

        Example:
            none

    ======================================================
       3.4.19 - fontSetOutline
    ======================================================

        Prototype:
            declare sub fontSetOutline alias "fontOutline" _
                                 (byval outline as integer)

        Arguments:
            [in] outline      - true (-1), false (0)

        Returns:
            Nothing

        Description:
            Same as fontOutline except it doesn't
            return the current setting.

        Example:
            none

    ======================================================
       3.4.20 - fontGetOutline
    ======================================================

        Prototype:
            declare function fontGetOutline% ()

        Arguments:
            none

        Returns:
            Returns the current setting

        Description:
            Returns the current outline setting.

        Example:
            none

    ======================================================
       3.4.21 - fontBGMode
    ======================================================

        Prototype:
            declare function fontBGMode% (byval bgmode as integer)

        Arguments:
            [in] bgmode     - bg mode (FONT.BG.TRANSPARENT or
                                       FONT.BG.OPAQUE)

        Returns:
            Returns the current setting

        Description:
            Set the text background mode to use and returns
            the current setting.

        Example:
            none

    ======================================================
       3.4.22 - fontSetBGMode
    ======================================================

        Prototype:
            declare sub fontSetBGMode alias "fontBGMode" _
                              (byval bgmode as integer)

        Arguments:
            [in] bgmode     - bg mode (FONT.BG.TRANSPARENT or
                                       FONT.BG.OPAQUE)

        Returns:
            Nothing

        Description:
            Same as fontBGMode except it doesn't
            return the current setting.

        Example:
            none

    ======================================================
       3.4.23 - fontGetBGMode
    ======================================================

        Prototype:
            declare function fontGetBGMode% ()

        Arguments:
            none

        Returns:
            Returns the current setting

        Description:
            Returns the current font background setting.

        Example:
            none

    ======================================================
       3.4.24 - fontBGColor
    ======================================================

        Prototype:
            declare function fontBGColor& (byval bgcol as long)

        Arguments:
            [in] bgcol      - background color to use

        Returns:
            Returns the current background color

        Description:
            Set the text background color to use and returns
            the current setting.

        Example:
            none

    ======================================================
       3.4.25 - fontSetBGColor
    ======================================================

        Prototype:
            declare sub fontSetBGColor alias "fontBGColor" _
                                     (byval bgcol as long)

        Arguments:
            [in] bgcol      - background color to use

        Returns:
            Nothing

        Description:
            Same as fontBGColor except it doesn't
            return the current setting.

        Example:
            none

    ======================================================
       3.4.26 - fontGetBGColor
    ======================================================

        Prototype:
            declare function fontGetBGColor& ()

        Arguments:
            none

        Returns:
            Returns the current setting

        Description:
            Returns the current font background color.

        Example:
            none

    ======================================================
       3.4.27 - fontSize
    ======================================================

        Prototype:
            declare function fontSize% (byval size as integer)

        Arguments:
            [in] size      - size in points of the glyphs

        Returns:
            Returns the current glyph size

        Description:
            Set the glyph size to use and returns
            the current setting.

        Example:
            none

    ======================================================
       3.4.28 - fontSetSize
    ======================================================

        Prototype:
            declare sub fontSetSize alias "fontSize" _
                             (byval size as integer)

        Arguments:
            [in] size      - size in points of the glyphs

        Returns:
            Nothing

        Description:
            Same as fontSize except it doesn't
            return the current setting.

        Example:
            none

    ======================================================
       3.4.29 - fontGetSize
    ======================================================

        Prototype:
            declare function fontGetSize% ()

        Arguments:
            none

        Returns:
            Returns the current setting

        Description:
            Returns the current glyph size.

        Example:
            none

    ======================================================
       3.4.30 - fontAngle
    ======================================================

        Prototype:
            declare function fontAngle% (byval angle as integer)

        Arguments:
            [in] angle      -  0 >= angle <= 359

        Returns:
            Returns the current angle

        Description:
            Set the angle to draw the text and returns
            the current setting.

        Example:
            none

    ======================================================
       3.4.31 - fontSetAngle
    ======================================================

        Prototype:
            declare sub fontSetAngle alias "fontAngle" _
                               (byval angel as integer)

        Arguments:
            [in] angle      -  0 >= angle <= 359

        Returns:
            Nothing

        Description:
            Same as fontAngle except it doesn't
            return the current setting.

        Example:
            none

    ======================================================
       3.4.32 - fontGetAngle
    ======================================================

        Prototype:
            declare function fontGetAngle% ()

        Arguments:
            none

        Returns:
            Returns the current setting

        Description:
            Returns the current angle.

        Example:
            none

    ======================================================
       3.4.33 - fontWidth
    ======================================================

        Prototype:
            declare function fontWidth% (text as string, _
                                         byval uFont as long)

        Arguments:
            [in] text       - Text to measure
                 uFont      - Handle to font

        Returns:
            The width of the text in pixels

        Description:
            This routine is used to find out how many
            pixels wide the text will be when it's drawn.

        Example:
            none

    ======================================================
       3.4.34 - fontTextOut
    ======================================================

        Prototype:
            declare sub fontTextOut (byval dc as long, byval x as long, _
                                     byval y as long, byval clr as long, _
                                     byval uFont as long, text as string)

        Arguments:
            [in] dc         - Destination DC
                 x, y       - Destination coords
                 clr        - Color to draw the text in
                 uFont      - Handle to font
                 text       - The text to draw

        Returns:
            Nothing

        Description:
            Draws text using a UVF/UBF font on a DC.

        Example:
            none

    ======================================================
       3.5.1 - tmrInit
    ======================================================

        Prototype:
            declare sub tmrInit ()

        Arguments:
            none

        Returns:
            Nothing

        Description:
            Sets up the timer ISR, has to be called before
            trying to use a UGL timer. Do _not_ use QB's PLAY
            routine or the PIT will be reprogrammed and the ISR
            won't stay in control of this module.

        Example:
            timer.bas

    ======================================================
       3.5.2 - tmrEnd
    ======================================================

        Prototype:
            declare sub tmrEnd ()

        Arguments:
            none

        Returns:
            Nothing

        Description:
            This routine removes the UGL timer ISR and
            restores the old one. Once the program is
            compiled it's no longer needed to call this
            routine. It will be invoked automatically.

        Example:
            timer.bas

    ======================================================
       3.5.3 - tmrNew
    ======================================================

        Prototype:
            declare sub tmrNew (seg t as TMR, byval mode as integer,_
                                byval rate as long)

        Arguments:
           [out] t                 - TMR struct to add to queue
            [in] mode              - Timer mode (AUTOINIT, ONESHOT)
                 rate              - The timer rate in Hertz

        Returns:
            Nothing

        Description:
            Creates a new timer, but there are few things you
            should consider.

            - Never declare the struct using redim or $dynamic.
              You should only declare it with dim and put $static
              before it if you've declared $dynamic before.

            - Never access TMR's fields but the 'state' one (for
              read-only), and the 'counter' field (for AUTOINIT
              timers); messing with other fields can leave the
              system unstable.

            - If the TMR struct is already active it will be
              deleted from the queue and readded.

            - How timers will operate, depending on 'mode' selected:
                * ONESHOT: when the timer expires, its deleted
                  from active timers queue and its state field
                  is changed to TMR.OFF; to reactive it again,
                  a new call to tmrNew must to be done.

                * AUTOINIT: when the timer expires, its re-added
                  to active timers queue and its counter field
                  is incremented by 1; that keeps going until the
                  timer is delete or paused.

        Example:
            timer.bas

    ======================================================
       3.5.4 - tmrDel
    ======================================================

        Prototype:
            declare sub tmrDel (seg t as TMR)

        Arguments:
            [in] t                 - TMR struct to delete
                                     from the queue

        Returns:
            Nothing

        Description:
            Deletes a timer that was created with tmrNew.

        Example:
            none

    ======================================================
       3.5.5 - tmrPause
    ======================================================

        Prototype:
            declare sub tmrPause alias "tmrDel" (seg t as TMR)

        Arguments:
            [in] t                 - TMR struct to delete
                                     from the queue

        Returns:
            Nothing

        Description:
            Pauses (deletes) a timer.

        Example:
            none

    ======================================================
       3.5.6 - tmrResume
    ======================================================

        Prototype:
            declare sub tmrResume (seg t as TMR)

        Arguments:
            [in] t                  - TMR struct to resume

        Returns:
            Nothing

        Description:
            Resumes a paused timer.

        Example:
            none

    ======================================================
       3.5.7 - tmrUs2Freq
    ======================================================

        Prototype:
            declare function tmrUs2Freq& (byval microsecs as long)

        Arguments:
            [in] microsecs          - microseconds to convert

        Returns:
            The equalent to the PIT rate (Hertz)

        Description:
            Converts micro-seconds to the PIT rate which
            is in hertz.

        Example:
            timer.bas

    ======================================================
       3.5.8 - tmrMs2Freq
    ======================================================

        Prototype:
            declare function tmrMs2Freq& (byval millisecs as long)

        Arguments:
            [in] millisecs          - milliseconds to convert

        Returns:
            The equalent to the PIT rate (Hertz)

        Description:
            Converts milli-seconds to the PIT rate which
            is in hertz.

        Example:
            timer.bas

    ======================================================
       3.5.9 - tmrTick2Freq
    ======================================================

        Prototype:
            declare function tmrTick2Freq& (byval ticks as long)

        Arguments:
            [in] ticks              - ticks to convert

        Returns:

            The equalent to the PIT rate (Hertz)

        Description:
            Converts ticks (55ms) to the PIT rate which
            is in hertz.

        Example:
            timer.bas

    ======================================================
       3.5.10 - tmrSec2Freq
    ======================================================

        Prototype:
            declare function tmrSec2Freq& (byval secs as long)

        Arguments:
            [in] secs              - seconds to convert

        Returns:
            The equalent to the PIT rate (Hertz)

        Description:
            Converts seconds to the PIT rate which
            is in hertz.

        Example:
            timer.bas

    ======================================================
       3.5.11 - tmrMin2Freq
    ======================================================

        Prototype:
            declare function tmrMin2Freq& (byval mins as long)

        Arguments:
            [in] mins              - minutes to convert

        Returns:
            The equalent to the PIT rate (Hertz)

        Description:
            Converts minutes to the PIT rate which
            is in hertz.

        Example:
            timer.bas

    ======================================================
       3.6.1 - sndInit
    ======================================================

        Prototype:
            declare function sndInit% (byval port as integer, _
                                       byval irq as integer, _
                                       byval ldma as integer, _
                                       byval hdma as integer)

        Arguments:
            [in] port              - SB base port
                 irq               - SB Irq
                 ldma              - SB 8 bit dma channel
                 hdma              - SB 16 bit dma channel

        Returns:
            false (0) if failed, true (-1) for OK.

        Description:
            Inits the sound module.
            If you pass false (0) as the port argument it
            will try to autodetect. However, this only works
            on SB 16 (or compatibles) and better.

            The standard way of getting the sb settings is
            through the BLASTER enviroment variable. There's
            a routine for doing this in the sound.bas example.

        Headerfile:
            inc\snd.bi

        Example:
            exs\sound.bas

    ======================================================
       3.6.2 - sndEnd
    ======================================================

        Prototype:
            declare sub sndEnd ()

        Arguments:
            none

        Returns:
            nothing

        Description:
            Deinits the sound module, if you're calling uglEnd
            already you don't have to call sndEnd.

        Headerfile:
            inc\snd.bi

        Example:
            exs\sound.bas

    ======================================================
       3.6.3 - sndOpenOutput
    ======================================================

        Prototype:
            declare function sndOpenOutput% ( byval frmt as integer, _
                                              byval freq as long, _
                                              byval bps as integer )

        Arguments:
            [in] frmt              - The output format
                                        snd.s8.mono
                                        snd.s8.stereo
                                        snd.s16.mono
                                        snd.s16.stereo
                 freq              - The output frequency
                 bps               - The beats per second setting,
                                     usally 50 is good

        Returns:
            true (-1) if everything ok, false (0) otherwise

        Description:
            Sets the soundblaster up for output. The output
            format and rate is in no way dependent on the samples
            you playback rate and format.

            Here's what each SB series supports:
                SB 1.0 - 2.0:       8 bit,  mono,   4000Hz-23000Hz
                SB 2.01:            8 bit,  mono,   4000Hz-44100Hz
                SB Pro:             8 bit,  mono,   4000Hz-44100Hz
                                    8 bit,  stereo, 11025Hz-22050Hz
                SB 16:              8 bit,  mono,   5000Hz-44100Hz
                                    8 bit,  stereo, 5000Hz-44100Hz
                                    16 bit, mono,   5000Hz-44100Hz
                                    16 bit, stereo, 5000Hz-44100Hz
        Headerfile:
            inc\snd.bi

        Example:
            exs\sound.bas

    ======================================================
       3.6.4 - sndPlay
    ======================================================

        Prototype:
            declare sub sndPlay ( seg voice as sndvoice, _
                                  byval sample as long )

        Arguments:
            [in] voice            - The voice to start playback on
                 sample           - The sample to playback

        Returns:
            nothing

        Description:
            Start playback of a sample on a voice. A voice
            is just another word for a channel. So don't get
            confused here :)

            You are not restricted to any fixed number of
            voices, the only limit is memory.

        Headerfile:
            inc\snd.bi

        Example:
            exs\sound.bas

    ======================================================
       3.6.5 - sndPlayEx
    ======================================================

        Prototype:
            declare sub sndPlayEx ( seg voice as sndvoice, _
                                    byval sample as long, _
                                    byval smprate as long, _
                                    byval pan as integer, _
                                    byval vol as integer, _
                                    byval direction as integer, _
                                    byval mode as integer )

        Arguments:
            [in] voice            - The voice to start playback on
                 sample           - The sample to playback
                 smprate          - Frequency to playback at (pitch)
                 pan              - The voice pan
                                        -256 is completly left
                                         256 is completly righ
                 vol              - The volume (0-256)
                 direction        - Playback direction
                                        snd.up,   forward
                                        snd.down, backward
                 mode             - Loop mode
                                        snd.onetime, play once
                                        snd.repeat,  restart once played
                                        snd.pingpong,backward once played

        Returns:
            nothing

        Description:
            As sndPlay but with more options

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.6 - sndPause
    ======================================================

        Prototype:
            declare sub sndPause ( seg voice as sndvoice )

        Arguments:
            [in] voice            - The voice to pause

        Returns:
            nothing

        Description:
            Pauses the playback of a voice.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.7 - sndResume
    ======================================================

        Prototype:
            declare sub sndResume ( seg voice as sndvoice )

        Arguments:
            [in] voice            - The voice to resume

        Returns:
            nothing

        Description:
            Resumes playback of a paused voice.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.8 - sndStop
    ======================================================

        Prototype:
            declare sub sndStop ( seg voice as sndvoice )

        Arguments:
            [in] voice            - The voice to stop

        Returns:
            nothing

        Description:
            Stops playback of a voice.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.9 - sndNewWav
    ======================================================

        Prototype:
            declare function sndNewWav& ( byval bufftype as integer, _
                                          filename as string )

        Arguments:
            [in] bufftype         - snd.mem or snd.ems
                 filename         - path and filename of wave file

        Returns:
            A 32-bit (4 bytes/long) handle to the sample.
            If the handle is equal to false (0) it failed to load it.

        Description:
            Loads a wave file. As any other UGL routine, it loads
            directly from archives as well.

        Headerfile:
            inc\snd.bi

        Example:
            exs\sound.bas

    ======================================================
       3.6.10 - sndNewRaw
    ======================================================

        Prototype:
            declare function sndNewRaw& ( byval bufftype as integer, _
                                          byval smpfrmt as integer, _
                                          byval smprate as long, _
                                          byval sign as integer, _
                                          filename as string, _
                                          byval offset as long, _
                                          byval length as long )

        Arguments:
            [in] bufftype         - snd.mem (mas 640 KB) or snd.ems (max 4MB)
                 smpfrmt          - The format of the raw sound
                                        snd.s8.mono
                                        snd.s8.stereo
                                        snd.s16.mono
                                        snd.s16.stereo
                 smprate          - The sample rate of the raw sound
                 sign             - Tells if the sound data is signed or not
                                        snd.signed
                                        snd.unsigned
                 filename         - path and filename of wave file
                 offset           - The offset the sound data start at in
                                    the file
                 length           - Number of bytes to read from the offset.

        Returns:
            A 32-bit (4 bytes/long) handle to the sample.
            If the handle is equal to false (0) it failed to load it.

        Description:
            Loads a raw sound file. As any other UGL routine, it loads
            directly from archives as well.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.11 - sndNewRawEx
    ======================================================

        Prototype:
            declare function sndNewRawEx& ( byval bufftype as integer, _
                                            byval smpfrmt as integer, _
                                            byval smprate as long, _
                                            byval sign as integer, _
                                            seg hFile as UAR, _
                                            byval offset as long, _
                                            byval length as long )

        Arguments:
            [in] bufftype         - snd.mem (mas 640 KB) or snd.ems (max 4MB)
                 smpfrmt          - The format of the raw sound
                                        snd.s8.mono
                                        snd.s8.stereo
                                        snd.s16.mono
                                        snd.s16.stereo
                 smprate          - The sample rate of the raw sound
                 sign             - Tells if the sound data is signed or not
                                        snd.signed
                                        snd.unsigned
                 hFile            - The handle of a file opened with fileOpen()
                 offset           - The offset the sound data start at in
                                    the file
                 length           - Number of bytes to read from the offset.

        Returns:
            A 32-bit (4 bytes/long) handle to the sample.
            If the handle is equal to false (0) it failed to load it.

        Description:
            Same as sndRaw except instead of the filename you give it
            the handle of a file which has already been opened with
            fileOpen() in the dos module.

            NOTE: It preserves the file cursor, so the file cursor
                  won't have changed after it has been loaded.

            As any other UGL routine, it loads directly from archives
            as well.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.12 - sndDel
    ======================================================

        Prototype:
            declare sub sndDel ( byval sample as long )

        Arguments:
            [in] sample           - Handle to sample to unload

        Returns:
            nothing

        Description:
            Unloads a sample.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.13 - sndSetInterp
    ======================================================

        Prototype:
            declare sub sndSetInterp ( byval mode as integer )

        Arguments:
            [in] mode             - Interpolation method
                                        snd.nearest (default)
                                        snd.linear
                                        snd.cubic

        Returns:
            nothing

        Description:
            Sets the intepolation mode.
            At the moment only snd.nearest is supported.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.14 - sndMasterSetPan
    ======================================================

        Prototype:
            declare sub sndMasterSetPan ( byval pan as integer )

        Arguments:
            [in] mode             - Pan setting of the output
                                        -256 completly left
                                         256 completly right

        Returns:
            nothing

        Description:
            Sets the pan setting of the output.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.15 - sndVoiceSetDefault
    ======================================================

        Prototype:
            declare sub sndMasterSetPan ( seg voice as sndvoice )

        Arguments:
            [in] voice            - The voice to init

        Returns:
            nothing

        Description:
            Inits a voice, a voice has to be init before it
            can be used.

            A voice is just another word for a channel if you
            were wondering.

        Headerfile:
            inc\snd.bi

        Example:
            exs\sound.bas

    ======================================================
       3.6.16 - sndVoiceSetSample
    ======================================================

        Prototype:
            declare sub sndVoiceSetSample ( seg voice as sndvoice, _
                                            byval sample as long )

        Arguments:
            [in] voice            - The voice to set the sample for
                 sample           - The sample which will be played
                                    back on the voice.

        Returns:
            nothing

        Description:
            Set the sample which will be played back on the voice.
            Has no real use right now :)

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.17 - sndVoiceSetDir
    ======================================================

        Prototype:
            declare sub sndVoiceSetDir ( seg voice as sndvoice, _
                                         byval direction as long )

        Arguments:
            [in] voice            - The voice which the playback direction
                                    will be set for.
                 direction        - The playback direction
                                        snd.up,   forward
                                        snd.down, backward

        Returns:
            nothing

        Description:
            Set the playback direction of a voice.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.18 - sndVoiceSetLoopMode
    ======================================================

        Prototype:
            declare sub sndVoiceSetLoopMode ( seg voice as sndvoice, _
                                              byval mode as integer )

        Arguments:
            [in] voice            - The voice which the loop mode will
                                    be set for
                 mode             - The loop mode
                                        snd.onetime,  play once
                                        snd.repeat,   repeat
                                        snd.pingpong, play the other direction
                                                      once the start/end has been
                                                      reached

        Returns:
            nothing

        Description:
            Set the loop mode of a voice.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.19 - sndVoiceSetLoopPoints
    ======================================================

        Prototype:
            declare sub sndVoiceSetLoopPoints ( seg voice as sndvoice, _
                                                byval lstr as integer, _
                                                byval lend as integer )

        Arguments:
            [in] voice            - The voice which the loop points for.
                 lstr             - Loop start offset
                 lend             - Loop end offset

        Returns:
            nothing

        Description:
            Set the loop points of a voice.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.20 - sndVoiceSetVol
    ======================================================

        Prototype:
            declare sub sndVoiceSetVol ( seg voice as sndvoice, _
                                         byval vol as integer )

        Arguments:
            [in] voice            - The voice which the volume will
                                    be set for.
                 vol              - 0-256

        Returns:
            nothing

        Description:
            Set the volume of a voice.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.21 - sndVoiceSetPan
    ======================================================

        Prototype:
            declare sub sndVoiceSetPan ( seg voice as sndvoice, _
                                         byval pan as integer )

        Arguments:
            [in] voice            - The voice which the volume will
                                    be set for.
                 pan              - The pan of the voice
                                        -256 completly left
                                         256 completly right

        Returns:
            nothing

        Description:
            Set the pan of a voice.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.6.22 - sndVoiceSetRate
    ======================================================

        Prototype:
            declare sub sndVoiceSetRate ( seg voice as sndvoice, _
                                          byval rate as long )

        Arguments:
            [in] voice            - The voice which the frequency will
                                    be set for.
                 rate             - The playback frequency (pitch) of the voice
                                        4000-48000

        Returns:
            nothing

        Description:
            Set the playback frequency of a voice.

        Headerfile:
            inc\snd.bi

        Example:
            none

    ======================================================
       3.10.1 - emsAlloc
    ======================================================

        Prototype:
            declare function emsAlloc% ( byval bytes as long )

        Arguments:
            [in] bytes            - Bytes to allocate

        Returns:
            The ems handle on succses and false (0) oterwise

        Description:
            Allocates ems memory.

            Note:
                The handle returned can not be used with the
                ems interrupt. Or other non UGL ems routines.

        Headerfile:
            inc\ems.bi

        Example:
            none

    ======================================================
       3.10.2 - emsCalloc
    ======================================================

        Prototype:
            declare function emsCalloc% ( byval bytes as long )

        Arguments:
            [in] bytes            - Bytes to allocate

        Returns:
            The ems handle on succses and false (0) oterwise

        Description:
            Does the same thing as emsAlloc, except that it
            clears the allocated ems memory with the value
            zero.

            Note:
                The handle returned can not be used with the
                ems interrupt. Or other non UGL ems routines.

        Headerfile:
            inc\ems.bi

        Example:
            none

    ======================================================
       3.10.3 - emsAvail
    ======================================================

        Prototype:
            declare function emsAvail& ( )

        Arguments:
            none

        Returns:
            The size of the largest free ems block

        Description:
            This is used to check how large the biggest free
            ems block is.

        Headerfile:
            inc\ems.bi

        Example:
            none

    ======================================================
       3.10.4 - emsFree
    ======================================================

        Prototype:
            declare sub emsFree ( byval handle as integer )

        Arguments:
            [in] handle           - Handle of an allocated ems
                                    block

        Returns:
            nothing

        Description:
            Frees allocated ems memory.

        Headerfile:
            inc\ems.bi

        Example:
            none

    ======================================================
       3.10.5 - emsMap
    ======================================================

        Prototype:
            declare function emsMap% ( byval hnd as integer, _
                                       byval offs as long, _
                                       byval bytes as long )

        Arguments:
            [in] hnd              - Handle to the ems block
                 offs             - The offset in bytes on where to
                                    start mapping
                 bytes            - Bytes to map 16384 - 65536 bytes

        Returns:
            The segment of the mapped memory on success
            and false (0) if the map failed.

        Description:
            This routine maps ems memory.

            Notes:
                EMS works in pages, each page is 16384 byte or 16 kb
                in otherwords. So when you map memory you always have
                to map starting on the first byte on a page.

                This sounds tricky, but it's not. To calculate what
                page the offset you want to access is on you have to
                divide the offset with 16384. But emsMap needs the offset
                in bytes on a page boundry. And not the actual page number.
                So you have to turn the page number to an offset. This is
                done by multiplying with 16384. Now you have the offset on
                page boundry.

                Basically what you've done is clear the low 14 bits of the
                offset. A simpler way to do the same thing is to AND the
                offset with &hffff4000. This will also give you the offset
                on page boundry.

                So how will you know if the last byte you want to access is
                on the same page as the mapped page? Simple, just add the
                number of bytes you want to read/write to the offset and
                AND it with &hffff4000. If this adress is the same as the
                last page you're mapping then you're safe. If it's not you
                need to map the next page as well. But remember that you
                can map only a maximum of 4 pages (64 kb).

                Now, if you're mapping on page boundry. Then the first mapped
                byte isn't the first byte you wanted is it? No it isn't.
                You get the offset you need to start reading at by subtracting
                the original offset in the ems memory to the offset of the
                first page you mapped.

                So how do you convert all this to a dos (real mode) memory
                adress? You calculate the physical adress then convert it
                back to the a dos (real mode) far pointer.

                Here a short example

                dim pagea as long
                dim pageb as long
                dim linear as long
                dim offset as long
                dim mapseg as integer
                dim datseg as integer, datofs as integer

                ''
                '' Just making an offset up
                ''
                offset = 567434&

                ''
                '' We want to map 15000 bytes, so calculate
                '' the offsets (on page boundry) of the first
                '' and last byte we want to map.
                ''
                pagea = offset and &hffff4000
                pageb = (offset+15000) and &hffff4000

                ''
                '' Now to map the memory, if the first and
                '' last byte aren't on the same page we need
                '' to map one extra page. In this case we're only
                '' mapping one page. So with the extra page it'll
                '' be two pages.
                ''
                if ( pagea = pageb ) then
                    mapseg = emsMap( emshndl, pagea, 16384 )
                else
                    mapseg = emsMap( emshndl, pagea, 32768 )
                end if

                ''
                '' Check if we were able to map
                ''
                if ( mapseg = false ) then
                    ''
                    '' Map failed, do error handling
                    ''
                end if

                ''
                '' Calculate the normalized adress
                ''
                linear = mapseg * 16& + (offset-pagea)
                datseg = linear \ 16&
                datofs = linear and 15&

                ''
                '' Now we can do whatever we want with those
                '' 15000 bytes that we mapped :)
                ''
                def seg = datseg
                for  i = 0 to 15000
                    poke datofs+i, 0
                next i

        Headerfile:
            inc\ems.bi

        Example:
            none

    ======================================================
       3.10.6 - emsSave
    ======================================================

        Prototype:
            declare function emsSave% ( seg ctx as EMSSAVECTX )

        Arguments:
            [in] ctx              - The ems save context

        Returns:
            false (0) if save failed.

        Description:
            This routine is used for saving the state of the
            ems context. It can later be restored with emsRestore.

            Now, you might wonder what this could be good for.
            Well, sometimes you code things such as interrupts
            which will be called and interrupt the cpu with what
            it's doing. Once the cpu returns from the interrupt it
            will go back doing what it did last. And if this happens
            to be something that had to do with ems it won't have
            the slighest idea that the mapped page has been changed.
            So it will go on using the data that the interrupt
            mapped thinking it's what it mapped. So this is why
            you sometimes have to save the ems context.

        Headerfile:
            inc\ems.bi

        Example:
            none

    ======================================================
       3.10.7 - emsRestore
    ======================================================

        Prototype:
            declare function emsRestore% ( seg ctx as EMSSAVECTX )

        Arguments:
            [in] ctx              - The ems save context

        Returns:
            false (0) if restore failed.

        Description:
            Restores a saved ems context.

        Headerfile:
            inc\ems.bi

        Example:
            none

    ======================================================
       3.10.8 - emsCheck
    ======================================================

        Prototype:
            declare function emsCheck% ()

        Arguments:
            none

        Returns:
            true (-1) if there is an ems driver, false (0)
            oterwise.

        Description:
            Checks for a ems driver.

        Headerfile:
            inc\ems.bi

        Example:
            none