Details on VisualID usage within X, and GLX/OpenGL
 by Philip Brown, March 2003

A high-level overview of the GLX client interaction can be found in
glx_overview.txt. This file spells out only the nitty-gritty of internal
handling of GLX visuals.

In regular X11 programming, a "Visual" normally is a way of telling the server
what kind of color depth  and support you'd like.
For example, 
 "Visual id #4"  might support  "24bit, TrueColor", whereas
 "Visual id #10" might support  "16bit, PseudoColor"

You can see normal visual properties using xdpyinfo.

GLX visuals server a similar, but much more detailed purpose.
As well as color depth, a GLX visual represents a particular combination
of doublebuffering, alphablending, stencil support, and depth buffering,
and potentially other features.


GLX visuals are hiddel overlays, on top of normal X11 visuals.
To pure X11 programs, a normal X11 Visual, and a Visual created by
the GLX extension will look identical. Only GLX enabled programs will
be able to see and use the hidden features.
You can see details on GLX visuals, using the glxinfo command.


For example, lets say an X server supported a single 24bit truecolor
display mode, with a single visual to represent that.
The GLX extension module may wish to offer a client its choice of
doublebuffering, alphablending, stencil support, and depth buffering,
or ANY COMBINATION of the above, for a 24bit truecolor window.

Using combinatorial math, we can figure out that is 2*2*2*2=16 combinations.
Which means that for the one original visual, the GLX extension may create
**16** new virtual visuals, around the single original X11 Visual

Regular X clients would see no difference between any of these visuals.
However, GLX clients tell the server with this one visualid number, all
of these special features that should be enabled.


   ************************************************************


DETAILED INTERNAL VISUAL CREATION FLOW (within utah-glx, server-side):


  GlxInitVisuals() calls either a generic routine [XSMesaInitVisuals]
    or a hardware specific routine, to fill out a global array,
    __glScreens[screennum].visuals[]
    Note that if there is 1 physical ("normal") visual, it generates
    potentially  16 different visuals, with variants on stencil_size, etc.
  GLFinalizeVisuals() then goes through this list, and translates it
    back into new plain X11-server Visuals that look just like the
    original, to the X11-server, and to normal X11 clients.

    Note: the method of inserting these new visuals into the server, is very
    yeukky. It directly manipulates global lists inside the X server.
    Unfortunatley, there is no clean API for doing this for Xfree86,
    at this time.
    

  NOTE!!! not all features may be hardware-accelerated.

  Which means if a client chooses one of those features that is not
  accelerated, everything may have to fall back to SOFTWARE RENDERING, which
  will kill speed.