src/glx/mini/NOTES

Getting MiniGLX up and running
------------------------------

It's necessary to do a bit of work to set up an environment to run miniglx. 

For the radeon driver, it's necessary to get the right set of kernel
modules installed before attempting to run any programs:

    rmmod radeon agpgart;
    insmod agpgart;
    insmod $(MESA)/src/kernel/radeonfb/radeonfb.o;
    insmod $(MESA)/src/kernel/radeon/radeon.o;

For all drivers, its necessary to reach the compiled libraries, and
tell MiniGLX where to find it's configuration file:

    export LD_LIBRARY_PATH=$(MESA)/lib;
    export MINIGLX_CONF=$(MESA)/lib/miniglx.conf

------------------------------------------------------------

MiniGLX Example Programs
------------------------

The following programs will work with miniglx:
	
	$(MESA)/tests/miniglx
	$(MESA)/xdemos/glxgears  

Thanks to the miniglut stub library, most of the mesa glut demos will
work.  In particular, the following have been tested.  (Note there is
no keyboard or mouse interaction with these demos).

	$(MESA)/demos/gears
	$(MESA)/demos/geartrain
	$(MESA)/demos/morph3d
	$(MESA)/demos/isosurf
	$(MESA)/demos/texobj
	$(MESA)/demos/texcyl
	$(MESA)/demos/gloss
	$(MESA)/demos/fire
	$(MESA)/demos/tunnel
	$(MESA)/demos/teapot
	$(MESA)/samples/prim
	$(MESA)/samples/olympic
	$(MESA)/samples/star
	$(MESA)/samples/wave
	...etc

In fact most of the glut demos seem to work within the constraints of
having no keyboard/mouse interactivity.  Furthermore, the use of the
glut wrapper means that these programs don't require recompilation to
run under MiniGLX -- the same binary works with both regular GLX and
MiniGLX.


------------------------------------------------------------

Porting GLX apps to MiniGLX
---------------------------

A quick list of issues encountered in porting existing GLX apps to
MiniGLX.  Listed in no particular order.

1) No input events

MiniGLX doesn't provide an input layer, so any X11 input event
handling in the existing app will have to be redone for whatever
input devices exist on the target.

2) No configuration, expose events

Many GLX and Xlib programs wait on an event to ensure the window has
become visible after being mapped.  MiniGLX provides no equivalent
facility.

3) Different headers

X11/Xlib.h, GL/GLX.h, etc must not be used if the program is being
compiled against MiniGLX.

The equivalent header is GL/MiniGLX.h.

4) Different library

It may be necessary to link directly against the minGLX libGL.so.

5) Reduced number of Xlib and GLX entrypoints.

By definition (MiniGLX is a subset of GLX), many Xlib and GLX
entrypoints, structures and macros are not present in MiniGLX.  It
will be necessary to find and eliminate all references to
non-supported entrypoints.


---------------------------------------------------------------

Bugs in radeonfb.o -- the radeon framebuffer driver.
----------------------------------------------------

Several bugs have been found in the radeonfb.o framebuffer driver.
Most of these are resolved in the version included in the MiniGLX
sources, but some remain:

1) Occasionally, after entering graphics mode, colors appear 'shifted'
or 'translated', particularly in higher resolution modes.  This is
definitely a bug in radeonfb.o as this can be provoked even when using
the software dri driver (fb_dri.so).  Importance: High.  Workaround:
Use 800x600 as it seems to be less frequent at this resolution,
otherwise, restart the application.