Appendix C
WGL: OpenGL Extension for Microsoft Windows NT and Windows 95

OpenGL rendering is supported on systems that run Microsoft Windows NT and Windows 95. The functions and routines of the Win32 library are necessary to initialize the pixel format and control rendering for OpenGL. Some routines, which are prefixed by wgl, extend Win32 so that OpenGL can be fully supported.

For Win32/WGL, the PIXELFORMATDESCRIPTOR is the key data structure to maintain pixel format information about the OpenGL window. A variable of data type PIXELFORMATDESCRIPTOR keeps track of pixel information, including pixel type (RGBA or color index), single- or double- buffering, resolution of colors, and presence of depth, stencil, and accumulation buffers.

To get more information about WGL, you may want to start with technical articles available through the Microsoft Developer Network at

http://www.microsoft.com/msdn/

Initialization

Use GetVersion() or the newer GetVersionEx() to determine version information. ChoosePixelFormat() tries to find a PIXELFORMATDESCRIPTOR with specified attributes. If a good match for the requested pixel format is found, then SetPixelFormat() should be called to actually use the pixel format. You should select a pixel format in the device context before calling wglCreateContext().

If you want to find out details about a given pixel format, use DescribePixelFormat() or, for overlays or underlays, wglDescribeLayerPlane().

Controlling Rendering

Several WGL routines are provided for creating and managing an OpenGL rendering context, rendering to a bitmap, swapping front and back buffers, finding a color palette, and using either bitmap or outline fonts.

Managing an OpenGL Rendering Context

wglCreateContext() creates an OpenGL rendering context for drawing on the device in the selected pixel format of the device context. (To create an OpenGL rendering context for overlay or underlay windows, use wglCreateLayerContext() instead.) To make a rendering context current, use wglMakeCurrent(); wglGetCurrentContext() returns the current context. You can also obtain the current device context with wglGetCurrentDC(). You can copy some OpenGL state variables from one context to another with wglCopyContext() or make two contexts share the same display lists and texture objects with wglShareLists(). When you're finished with a particular context, destroy it with wglDestroyContext().

OpenGL Rendering to a Bitmap

Win32 has a few routines to allocate (and deallocate) bitmaps, to which you can render OpenGL directly. CreateDIBitmap() creates a device-dependent bitmap (DDB) from a device-independent bitmap (DIB). CreateDIBSection() creates a device-independent bitmap (DIB) that applications can write to directly. When finished with your bitmap, you can use DeleteObject() to free it up.

Synchronizing Execution

If you want to combine GDI and OpenGL rendering, be aware there are no equivalents to functions like glXWaitGL(), glXWaitX(), or pglWaitGL() in Win32. Although glXWaitGL() has no equivalent in Win32, you can achieve the same effect by calling glFinish(), which waits until all pending OpenGL commands are executed, or by calling GdiFlush(), which waits until all GDI drawing has completed.

Swapping Buffers

For windows that are double-buffered, the front and back buffers can be exchanged by calling SwapBuffers() or wglSwapLayerBuffers(); the latter for overlays and underlays.

Finding a Color Palette

To access the color palette for the standard (non-layer) bitplanes, use the standard GDI functions to set the palette entries. For overlay or underlay layers, use wglRealizeLayerPalette(), which maps palette entries from a given color-index layer plane into the physical palette or initializes the palette of an RGBA layer plane. wglGetLayerPaletteEntries() is used to query the entries in palettes of layer planes.

Using a Bitmap or Outline Font

WGL has two routines, wglUseFontBitmaps() and wglUseFontOutlines(), for converting system fonts to use with OpenGL. Both routines build a display list for each requested character from the specified font and font size.

WGL Prototypes

Initialization

Determine version information:

BOOL GetVersion ( LPOSVERSIONINFO lpVersionInformation );

BOOL GetVersionEx ( LPOSVERSIONINFO lpVersionInformation );

Pixel format availability, selection, and capability:

int ChoosePixelFormat ( HDC hdc,
CONST PIXELFORMATDESCRIPTOR * ppfd );

BOOL SetPixelFormat ( HDC hdc, int iPixelFormat,
CONST PIXELFORMATDESCRIPTOR * ppfd );

int DescribePixelFormat ( HDC hdc, int iPixelFormat, UINT nBytes,
LPPIXELFORMATDESCRIPTOR ppfd );

BOOL wglDescribeLayerPlane ( HDC hdc, int iPixelFormat,
int iLayerPlane, UINT nBytes, LPLAYERPLANEDESCRIPTOR plpd );

Controlling Rendering

Manage or query an OpenGL rendering context:

HGLRC wglCreateContext ( HDC hdc );

HGLRC wglCreateLayerContext ( HDC hdc, int iLayerPlane );

BOOL wglShareLists ( HGLRC hglrc1, HGLRC hglrc2 );

BOOL wglDeleteContext ( HGLRC hglrc );

BOOL wglCopyContext ( HGLRC hglrcSource, HGLRC hlglrcDest,
UINT mask );

BOOL wglMakeCurrent ( HDC hdc, HGLRC hglrc );

HGLRC wglGetCurrentContext (VOID) ;

HDC wglGetCurrentDC (VOID);

Access and release the bitmap of the front buffer:

HBITMAP CreateDIBitmap ( HDC hdc,
CONST BITMAPINFOHEADER *lpbmih, DWORD fdwInit,
CONST VOID *lpbInit, CONST BITMAPINFO *lpbmi, UINT fuUsage );

HBITMAP CreateDIBSection ( HDC hdc, CONST BITMAPINFO *pbmi,
UINT iUsage, VOID *ppvBits, HANDLE hSection, DWORD dwOffset );

BOOL DeleteObject ( HGDIOBJ hObject );

Exchange front and back buffers:

BOOL SwapBuffers ( HDC hdc );

BOOL wglSwapLayerBuffers ( HDC hdc, UINT fuPlanes );

Finding a color palette for overlay or underlay layers:

int wglGetLayerPaletteEntries ( HDC hdc, int iLayerPlane, int iStart,
int cEntries, CONST COLORREF *pcr );

BOOL wglRealizeLayerPalette ( HDC hdc, int iLayerPlane,
BOOL bRealize );

Use a bitmap or an outline font:

BOOL wglUseFontBitmaps ( HDC hdc, DWORD first, DWORD count,
DWORD listBase );

BOOL wglUseFontOutlines ( HDC hdc, DWORD first, DWORD count,
DWORD listBase, FLOAT deviation, FLOAT extrusion, int format,
LPGLYPHMETRICSFLOAT lpgmf );