Overview of GLX use
                ========================================

by Philip Brown  March 2003

       Disclaimer: The information in this file comes from reverse engineering
       code, not from sitting on any standards body or review board.


This file is meant to give people a code-level oriententation on how
utah-glx works.
At this point, it is really a quick refresher course on how the GLX
API is meant to operate

This file should give both a "GLX library use" overview, and also
a peek into how those features are implemented under the covers. However, 
apart from the reference to visuals.txt, there isnt too much utah-glx
internal info here.

Note: the Mesa "xdemos" directory is a better example of GLX interaction
than other Mesa demo directories, since it uses GLX 'raw', instead of
wrapping the interesting stuff in 'libglut' functions.


  ==================================================================

            List of typical GLX Client activities

Step 1: Open Connection
  Ignoring the posibility of 'direct rendering' for now, a client program
  calls the usual XOpen() routines, to talk to the server

Step 2: Query for GLX Extensions, and version
   Call glXQueryExtension(), and/or 
   Call glXQueryVersion()

   This lets the program know what extra features are available
   beyond the vanilla OpenGL 3d rendering API.

Step 3: Tell the GLX X server which general features are desired

   Call glXChooseVisual() with a list of features desired.
   Things like doublebuffering, stencil support, alpha blending,
   depth buffer, and so on.
   The client-side GL library determines the 'visual' with the best match
   to the requested set of features, based on multiple glXGetConfig()
   calls about each visual.

   The client then creates a 'normal' X window with that X VisualID.
   

   [see visuals.txt for detailed info about Visuals]


Step 4: Create a GL Context

   Call glXCreateContext()

   the GLX extension then looks at the VisualID of the window, and
   decodes back the relevant features that the client requested
   in step 3.

   Sometimes this means the client will get features available to them that
   they did not request. It is up to the specific 3d hardware driver.


Step 5: Set the 3d graphics context, and start drawing

   Call glXMakeCurrent()
   Start drawing!


   It is conceivable that the client could have created multiple contexts.
   So there is a separate call to tell the hardware which "context" should
   be used.