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