6 Windows, Buffers, and Rendering Contexts

6.010 How do I use overlay planes?

Overlays planes allow layered rendering. They support a transparent color to let rendering in underlying planes show through. Any combination of overlay and underlay planes are possible, but a typical implementation consists of a single overlay plane along with the main framebuffer plane. It's common for overlay planes to be available only in color index mode, though RGB overlays are available on some devices. The transparent color is normally (0,0,0) for RGB overlays and index 0 for color index overlays. Rendering to the overlay plane is non-destructive to the main plane and vice versa.

How you access overlay planes depends on the windowing system interface. While GLUT 3.7 has entry points defined for the use of overlays, currently the entry points are disabled. To use overlays, your application needs to use WGL, GLX, or another platform-specific interface.

For both WGL and GLX, the basic idea is the same: Create two rendering contexts, one for the main plane and another for the overlay planes. Once they're created, make either context current, depending on whether your application needs to render to the overlay or the main plane.

In WGL, use ChoosePixelFormat() to select a pixel format with an overlay or underlay plane. When your application calls this function, use the bReserved field of the PIXELFORMATDESCRIPTOR to indicate the desired overlay or underlay plane. A value of 1 indicates one overlay plane. The iLayerType field needs to be set to PFD_MAIN_PLANE.

After setting the pixel format, create the rendering context for the main plane as usual, then create a second rendering context for the overlay plane as follows:

HGLRC hORC; hORC = wglCreateLayerContext (hDC, a);

Check the return value the same way you would for a call to wglCreateContext(). A value of NULL indicates failure.

In GLX, use glXChooseVisual() to obtain a list of visuals with overlays. Add GLX_LEVEL to the attribute list, followed by the fullword indication of the desired level. Positive values indicate overlay; negative values indicate underlay. A value of 0 indicates the main plane, which is the default. A typical application will call glXChooseVisual() twice, once with GLX_LEVEL set to 0, and again with GLX_LEVEL set to 1. After each call, choose one of the returned visuals to create a rendering context.

When your application can't find a pixel format or visual that supports overlay, there are two common causes. Overlay might not be available on your platform, or you could be asking for an RGB overlay when only color index is available.

Column Header
Column Footer