This file will give a brief description of how to use the gtkglarea-- widget
in your own project.

BASIC USAGE:
For starters you will need the glarea.h and gtkglarea.h file found in the 
include directory.  You should include glarea.h in all files using the 
gtkglarea widget.

The base widget is named Gtk_GLArea.  You can either derive another widget 
from it or simply use it directly.  For most cases it is probably
better to derive.

Example derived

class MyGLWindow: public Gtk_GLArea
	{ initgl():
	  setupgl();
	  drawgl();

    	  gint expose(GdkEventExpose* expose);
    	  gint resize(GdkEventConfigure *event);

	  Public:
		MyGLWindow(int *attrib);
	};

(setupgl, initgl, and drawgl are just arbitrary functions that I use for my 
windows. ) 

Whereever there is a call to GL functions,  a call must be made to change the 
context to that of the gl widget.  This is done with begingl.  The context
should be switch back when done with endgl.  Begingl returns true if
the glarea is initialed properly, so it should be wrapped in an if
statement.

MyGLWindow::initgl()
  {
   if (begingl())
     {
      //setup the projection and create some GL lists

      endgl();
     }
   return;
  }

Then when it comes time to display the widget use swapbuffers to
bring the rendering to the screen.  (For the time being there
is some bug in gtkglarea that calling swapbuffers inside a 
begingl/endgl pair, so always call swapbuffer after the endgl.)

USING EVENTS:
As Gtk_GLArea is derived from Gtk_Widget it has a window and 
can therefore capture events.  However, GL commands can only
be issued once that window has been mapped.  This means
that no GL commands can be called prior to mapping the
window.  That rules out creating your GL list objects in the
constructor.  

Therefore you should create an initialization routine (initgl in
my case)  that is connected to the realize signal.  Connecting
to any signal prior to that (show for example)  will result in
an error and could cause the program to crash.

Beyond that any other events are fair game.  The motion
event is good to grab mouse motions to manipulate the GL object.
The expose event to decide to draw the object for the first time 
and redraw the window at later times.  And it is good to
place a resize event handler to resetup the projection matrix.

LINKING:
The entire Gtk_GLArea widget and its gtk equivelent are included
in one library libgtkglamm.a which should be linked with the
-lgtkglamm switch.  The libgtkgla.a contains only the gtk portion
and is not necessary for gtk--.  

QUESTIONS?:
I hope that this answers most of your questions regarding the
use of Gtk_GLArea.  I lurk arround on the gtk maillist so
if you have a question you can hit me there.  If you mail me
directly be sure to put a "gtk" somewhere in the subject line
so that it makes it through my filters properly.  (Without
"gtk" in the subject your message will be put through my
anti-spam filters which is known to eat messages.)   No guarentees
that I will have an answer though.  

Bug reports for the gtkglarea widget should go to Jof,
as I only handle gtk-- stuff.

--Karl
