docs/README.WINDML

                        WindML Driver for Mesa 4.0


Requirements
------------

Tornado 2 + WindML, Cumulative Patchs are recommended. 
  
I suppose you have a valid WindML installation. Double buffer hardware
gives better performance than double buffer software so if you can
compile your WindML driver with this option, just do it. I/O
redirection is adviced in target server.


Tested on
---------

During the development, my main target was a CoolMonster:
- Video card: CT69000
- CPU: PENTIUM 266MHz

and my host a Windows NT + Tornado 2.


Installation
------------

1. Mesa sources must be in root directory (C:\)

2. Add the following line to your torVars.bat:
set MESA_BASE=C:\Mesa

OR copy the new torVars.bat in your bin path:
c:/Mesa/src/ugl/tornado/torVars.sample -> 
/mnt/nt/Tornado/host/x86-win32/bin/torVars (for example)

3. In a command prompt:
$ torVars
$ cd c:\Mesa
$ make -f Makefile.ugl CPU=PENTIUM

Take a long while...

5. Include all the files from ugldemos folder to build some downloadable
   application modules

4. Download UGL/Mesa object files on target

For example via the WindShell:
ld < c:\Tornado\target\lib\objMesaGL.o
ld < c:\Tornado\target\lib\objMesaUGL.o
ld < c:\Tornado\target\lib\objMesaGLU.o
ld < c:\Tornado\target\lib\objGLUTshapes.o
ld < c:\Tornado\target\lib\objMesaOS.o

You can put the previous lines in a file and use:
< filename

6. Download the application modules.

7. In WindShell, run:
-> uglalldemos

During the show some messages will appear, it provides some useful
information on key management.


Coding
------

Sample Usage:

In addition to the usual ugl calls to initialize UGL, (may be find an
input driver), you must do the following to use the UGL/Mesa interface:

1. Call uglMesaCreateContext() to create a UGL/Mesa rendering context,
   given the display format.

2. Call uglMesaMakeCurrent() to bind the UGL/Mesa buffers to an
   UGL/Mesa Context and to make the context the current one.

3. Make gl* calls to render your graphics.

4. Use uglMesaSwapBuffers() when double buffering to swap front/back buffers.

5. Before the UGL is destroyed, call MesaDestroyContext().

6. Before exiting, call if required uglEventQDestroy and then
   uglDeinitialize();

Limitations
-----------

I found the following limitations in my driver :
 - Color Indexed management is only in 8 bits
 - It's possible to mix UGL/OpenGL application with a software
   double buffer

Modifications
------------

New files in Mesa:
- Makefile.ugl
- rules.windmlmesa
- docs/README.UGL
- include/GL/uglmesa.h
- si-glu/Makefile.ugl
- src/Makefile.ugl
- src/ugl/torGLUTShapesInit.c
- src/ugl/torMesaUGLInit.c
- src/ugl/ugl_api.c
- src/ugl/ugl_dd.c
- src/ugl/ugl_glutshapes.c
- src/ugl/ugl_line.c
- src/ugl/ugl_span.c
- src/ugl/ugl_tri.c
- src/ugl/uglmesaP.h
- ugldemos/*

Modified files in Tornado 2.0:
- c:\Tornado\host\x86-win32\bin\torVars.bat
rem Command line build environments
set WIND_HOST_TYPE=x86-win32
set WIND_BASE=C:\Tornado
set MESA_BASE=C:\Mesa
set PATH=%WIND_BASE%\host\%WIND_HOST_TYPE%\bin;%PATH%
- c:\Tornado\target\config\comps\VxWorks\01uglmesa.cdf
- c:\Tornado\target\h\GL\*

Todo
----
- GCC 2.96, ASM compilation

Thanks to:
----------

Precision Insight team for their great job around Mesa, XFree, and DRI.
Wind River Systems to take me as an intern.


Stephane Raimbault
<stephane.raimbault@windriver.com>
<stephane.raimbault@deesse.univ-lemans.fr>

July 24, 2001