what are overlays?
------------------
Some OpenGL implementations are capable of binding two OpenGL states to the
same window on the screen, in such a way that one appears to be "on top" of
the other. The OpenGL state on top is known as an overlay plane.

what are they for?
------------------
It can be useful to have an overlay plane if one wants to make small changes
to a frame buffer which is very expensive to render. Unfortunately, not all
graphics hardware/toolkits support overlays planes, but overlays can be 
emulated in a reasonable way using double buffering or some other auxiliary
buffer.

how does emulation work?
------------------------
There are several cases depending on what's available:
[1] with Mesa, using an aux buffer.
  Just before rendering the overlays, the contents of the current back buffer
  is copied to the aux buffer. The overlays are rendered into the back buffer
  and a glXSwapBuffers() is called to show them. To "clear the overlay" plane,
  the aux buffer is simply copied into the back buffer again. This is all fast
  because the aux buffer and the back buffer reside with the (X) client.
  Implemented by capes@robots.ox.ac.uk who knows the X/Mesa details better 
  than I do.
[2] with double buffering (no aux buffer).
  The current front buffer is copied to the current back buffer, and the
  current draw buffer is set to GL_FRONT. The overlays are rendered into
  the front buffer and to "clear the overlay plane", the back buffer is
  copied into the front buffer. Note that this may be slow as the front
  buffer resides on the (OpenGL)server.
[3] with OpenGL aux buffers.
  This is not implemented. It would be similar to the Mesa case, only the aux
  buffer must be filled with the contents of the current front buffer.

how do I use the overlay plane?
-------------------------------
In vgui, the overlay abstraction is described using the method
   void vgui_adaptor::post_overlay_redraw()
which is analogous to the post_redraw() method, except that it causes an
event of type vgui_DRAW_OVERLAY to be generated, rather than a plain vgui_DRAW.

That's (almost) all there is to using overlays in vgui; your tableaux should
just arrange to draw their overlays in response to vgui_DRAW_OVERLAY events.
  One slight caveat is that any tableau which maintains overlays should probably
always post an overlay redraw() upon receiving a vgui_DRAW, even if the tableau
performs no normal drawing. Because if the normal frame buffer is rerendered, 
e.g. due to a zoom, the overlays probably have to be rerendered too.

fsm
