StormMesa2010 2.5 beta (June 2012)

Short:        StormMesa2010 reworked sources
Author:       Sam Jordan & others
Uploader:     thellier free fr
Type:         util/libs
Version:      2.5 beta (June 2012)
Requires:     RTG system,68020-40,fpu
Architecture: m68k-amigaos >= 3.0.0

DESCRIPTION
=========== 
StormMesa is a 68020-40 OpenGL implementation that use hardware Warp3D 
So programs like glExcess,Cube,etc... may be hardware rendered in WinUAE/Wazp3D or on real Amiga/Warp3D
Now works also on OS4 as a 68k program
New in v2.5: if LibBase in A6 is lost then try to find it again with GetTaskLibBase();
New in v2.4: StormMesa2010-Prefs is now OS-friendly 
New in v2.3: Mipmapping is fixed (was crashing in Cube). Default setting is LOCKMODE2 + VERYFAST so faster
New in v2.2: Option "Use DrawArrray"
StormMesa2010 2.1b reworked sources :
This was an attempt to recompile the old StormMesa with GCC
This was very difficult and we are not sure that this version is better or usefull...
Sources changes & testing :  Alain THELLIER - 'Wawa' TOKARSKI - Bernd ROESCH - 'Kas1e' - Matt HEY - Philippe BOVIER
This is juste an update so see old StormMesa archives for more informations   
                                                                              
LICENSE
=======
StormMESA V3.1 
A freeware (GNU) 3D graphics library for 68K AMIGA's 
Almost completely OpenGL compatible 
Based on MESA V3.0 beta 8 by Brian Paul 
Based on AMESA V1.6 by Stefan Zivkovic 
StormMESA V3.0 is presented by HAAGE & PARTNER Computer Gmbh 
StormMESA V3.0 implementation maintained by Sam Jordan - 10.12.98

MOST IMPORTANT FEATURES
======================= 
o Now StormMesa sources can be recompiled with a standard GCC
o Old StormMesa binary compatibility
o Perhaps will works better now for some Warp3D-drivers 
                                                 
INSTALLATION 
============
copy agl.library TO LIBS:agl.library 

STORMMESA 2010 SPECIFICITY
==========================
We describe here how StormMesa sources were modified to be recompiled

1) MultiBase library
StormMesa never give the current GLcontext as a parameter
In fact there is a GLcontext per GL task
But Amiga libraries only know the LibraryBase in a6
So we need to have a new LibraryBase for each new task
Each LibraryBase contain a current GLcontext and a current Task
It give a LibraryBase chained list 
So for a given task we obtain a given LibraryBase that contain the current GLcontext

	MyTask = FindTask(NULL);
	ThisBase=FirstBase;
	while(ThisBase!=NULL)
	{
	if(ThisBase->Task==MyTask)
		return(ThisBase);

	ThisBase=ThisBase->ChildBase;
	}

When OpenGL is started the current GLcontext is stored in the current LibraryBase
So when a library function is called
void glPointSize( GLfloat size )		
{		
	GET_CONTEXT;
	PointSize(CC,size);
}

The GET_CONTEXT macro recover the current GLcontext 
It do LibraryBase=a6; then CC=LibraryBase->CurrentContext;

2) Standardized glue-functions
We removed all the compiler specific part inside the glue-functions in glapi.c
So we defined registers like this
#define FP0(var) register var	__asm("fp0")

and the glue functions like this one

void smglPointSize(GLfloat a)
{
FP0(GLfloat size);
glPointSize(size);
}

That give
void smglPointSize(GLfloat a)
{
register size __asm("fp0")
glPointSize(size);
}
So the "a" parameter is only a dummy one that allow the compiler to check the arguments 
and the real parameter "size" is directly read in the register fp0 in the Amiga way

3) StormMesa-Prefs
No more env/vars
Now there is a Gui to change the StormMesa settings

GCC OPTIONS FOR RECOMPILATION
=============================
We describe here the parameters to recompile the agl.library

CODEGEN = -m68020-40 -m68881 -noixemul

OPTIMIZATION = -O3

OPTIONS = -nostartfiles -w -DTHREADS -DAMIGA -DNOASM_68K -DNOASM_PPC -DDRIVEREXT

Warning: Most of those defines are already defined in the .h files

STORMMESA 1999 KNOWN BUGS
=========================
1)  a bug in stormesa's glut (found in 4dtris sources & wazp3d debugger) ==> will need a fix

glutInit(&argc, argv);
[...]
glutInitDisplayMode(GLUT_RGB | GLUT_DOUBLE | GLUT_DEPTH); 
glutCreateWindow("4D-TRIS"); 
[...]  
glutDisplayFunc(display); 
[...] 
glEnable(GL_DEPTH_TEST);

static void display(void)
{
[...]
 glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); [...] }

The "display" call-back function do a clear zbuffer (=depth buffer) but zbuffer is not enabled (yet) = no zbuffer at all 
Glut on other OS seems to handle that but StormMesa then try to fallback to software-functions for zbuffer :-(((

Errors in StormMesa or Glut or MiniGL:
2) glExcess : glut dont understand "Game Mode" (=full scren) it begin to start Wazp3D,create context,etc... ==> all works fine (no warp3d error) then glut decide itself (?) to fail and close all =strange Especially strange as StormMesa CAN do full-screen in other demos

3) 4Dtris: it dont use the hardware Zbuffer 
We see the error but we dont know yet where it happen in the StormMesa or Glut sources 
Seems related to others Zbuffer bugs
It seems that sometime StormMesa lost itself

4) PointBlast: ground should have a texture (?)

5) Oreilly-Cube: often crash at startup

STORMMESA 2010 OTHER KNOWN BUGS
===============================
PointBlast: dont use Zbuffer

STORMMESA PREFS
===============
Four new options in StormMesa2010 :
"Enable Debugger" "Debug Function" "Step Function" "Change Primitive Funcs"

Enable Debugger:
Enables the output of messages. This is used for debugging of OpenGL programs.
(need to close StormMesa-Prefs to make it works)

Debug Function:
Print all the GL functions names

Step Function:
Step before all GL functions

Change Primitive Funcs:
Usually old StormMesa test (query) all the time the hardware  and then choose to use
hardware or software for each Primitive Funcs. 
Defaut is Off : So StormMesa2010 just test & choose once for all  so can be
faster if the hardware can fully render the given program

Use DrawArray
If a GL program want to draw some GL_TRIANGLES then 
we use a fast call to W3D_DrawArray(context,W3D_PRIMITIVE_TRIANGLES,0,count);
So can speed up more when using Warp3D (or Wazp3D in hardware mode)
Badly there is not much existing GL programs that use GL_TRIANGLES
You can try it with starship (the gl one not starshipw3d) 
Glexcess  use draw GL_TRIANGLES only for the spaceship in the tunnel
This option still got bugs so the default is OFF

Other options were env/vars in the old StorMesa
Their old documentation is given again here

DIRECT:
Forces the application to run in 'direct render' mode,
even if the application attempted to run in the
'indirect render' mode. The use of 3D hardware is only
possible in 'direct render' mode.

NOHW:
Forces the graphics to be drawn by the CPU, the 3D
hardware is not touched.

SYNC:
Enforces synchronized refreshing of the graphics in window
mode. Since StormMesa 3.1 no synchronisation is done
by default in window mode.

TRIPLE:
Enables triple buffering. This leads for fast applications
to better performance in fullscreen mode and to a more
constant animation. The disadvantage is the much bigger
video memory usage.

NOCLAMP:
If this option is activated, then 'texture wrapping' is also used,
if the application wants to use 'texture clamping'. This option
should be used when a Virge 3D processor is used, because the
amount of demos capable of running 3D hardware accelerated grows
a lot.

NICETEX:
Cares, that the graphics quality concerning textures is as good as
possible, even if the overall graphics quality was reduced using
the variables FAST and VERYFAST.

NICEFOG:
Cares, that the graphics quality concerning fogging is as good as
possible, even if the overall graphics quality was reduced using
the variables FAST and VERYFAST.

NOHWLINES:
Forbids the use of 3D hardware rendering for line drawing.

LOCKMODE0:
Default. The graphics isn't drawn directly, an 'indirect context' of the
Warp3D software is used. The drawing operations are collected
in a buffer and drawn later, by enclosing such drawing operations
by an lock/unlock call.
This mode is the most system friendly mode and also works for
applications, that call system functions during OpenGL drawing
which might also cause graphical output.
The disadvantage of this mode is the low performance.

LOCKMODE1:
All objects are drawn directly and every begin-end-block is
enclosed by a lock/unlock call. This mode is right now useless,
since it's performance is very low due to massive lock/unlock
call overhead.

LOCKMODE2:
All objects are drawn directly and the lock is held during the
whole display function. This is the fastest mode, but very
system unfriendly, because it freezes the system very much.

LOCKMODE3:
This mode works very similar to mode 2, but here the lock is
broken in periodic intervals to let the system 'breathe air'.
Practice has shown, that the performance usually isn't
noticeable lower than for the mode 2, but the system
friendliness is much better.

FAST:
If this option is activated, the 3D hardware is also used when some
effects aren't supported completely by the hardware. But StormMesa
still tries to achieve an acceptable graphics quality.

VERYFAST:
If this option is activated, the 3D hardware is mostly used, but
the graphics quality might be unacceptable low.

STATS:
Some information is printed out into the shell after completion
of the application. First, the reasons are displayed, which were
responsible for not using the 3D hardware and second, the amount of
drawn primitives (points, lines, triangles, quads) are printed out.
If there is no statistical output after completion of the application,
then some of the mentioned conditions, which are necessary for 3D
hardware support, are not satisfied.

PROFILE:
Not documented

NORASTER:
Not documented

NODITHER:
Not documented

NOZB:
Not documented

NOZBU:
Not documented

LIN:
Not documented