Section 8.4. Microsoft Windows

8.4. Microsoft Windows

Microsoft Windows uses an interface called WGL to provide OpenGL support in Windows. The WGL functions connect OpenGL to the Microsoft Windows windowing system.

WGL doesn't have a formal specification. Although the Microsoft Developer Network (http://msdn.microsoft.com) has some documentation, many WGL developers obtain information from WGL extension specifications at the OpenGL Extension Registry (http://oss.sgi.com/projects/ogl-sample/registry/). Because the WGL interface is very similar to GLX, you can also refer to the GLX specification and reinterpret it as though it were referring to WGL. Finally, OpenGL vendors typically provide additional documentation to describe their Microsoft Windows implementations. Check with your OpenGL vendor for more information.

Microsoft Windows supports rendering OpenGL to onscreen windows (as created with the Win32 CreateWindow() function) and to DIBs resident in system memory. Many OpenGL hardware vendors support pbuffers through an extension to WGL called WGL_ARB_pbuffer. This section discusses only rendering to a window.

8.4.1. Creating the Window

To create a window for OpenGL rendering, your application should set the WS_CLIPCHILDREN and WS_CLIPSIBLINGS window style bits in the third parameter (dwStyle) to CreateWindow(). This prevents OpenGL from rendering into child and sibling windows. Not setting these bits could cause SetPixelFormat() to fail. See the next section for information on SetPixelFormat().

8.4.2. Creating Contexts

To create a rendering context for rendering to a window, OpenGL applications typically wait for a WM_CREATE event on the window and then perform the following steps:

1.	Obtain the index of an appropriate pixel format.
2.	Set the pixel format in the device context for the window.
3.	Create a rendering context from the device context.

The pixel format specifies properties of an OpenGL drawing surface, such as the number of color and depth buffer bits and whether it supports double-buffered rendering. To obtain an appropriate pixel format for your application, fill in a PIXELFORMATDESCRIPTOR struct and then call ChoosePixelFormat().

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

Returns the 1-based index of a pixel format supported by hdc that best matches the specifications in ppfd. hdc is the device context handle for the window (or other drawing surface) your application will be rendering to, and ppfd contains pixel-format specification information.

If ChoosePixelFormat() is unable to find a matching pixel format or fails for any other reason, it returns zero. Call GetLastError() for failure information.

Set values in the PIXELFORMATDESCRIPTOR struct to request an appropriate pixel format for your application. The following code segment, for example, shows how to request a pixel format for rendering to a double-buffered RGBA window with 24 color buffer bits and 24 depth buffer bits:

 PIXELFORMATDESCRIPTOR pfd; memset( &pfd, 0, sizeof( PIXELFORMATDESCRIPTOR ) ); pfd.nSize = sizeof( PIXELFORMATDESCRIPTOR ); pfd.nVersion = 1; pfd.dwFlags = PFD_SUPPORT_OPENGL | PFD_DRAW_TO_WINDOW |         PFD_DOUBLEBUFFER; pfd.iPixelType = PFD_TYPE_RGBA; pfd.cColorBits = 24; pfd.cDepthBits = 24; pfd.iLayerType = PFD_MAIN_PLANE; int iPixelFormat = ChoosePixelFormat( hDC, &pfd ); 

For complete details on the PIXELFORMATDESCRIPTOR struct, see the Microsoft Developer Network documentation.

Because the return value is merely an index into the list of pixel formats supported by hdc, your application can't examine pixel-format attributes directly. Use DescribePixelFormat() to examine a pixel format to ensure that it's suitable for your application. For information on DescribePixelFormat(), see the Microsoft Developer Network documentation.

After obtaining the index of an appropriate pixel format, set it as the current pixel format of the device context by using SetPixelFormat().

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

Sets the specified pixel format on the device context. hdc is the device context handle for the window (or other drawing surface) your application will be rendering to. iPixelFormat is the 1-based index of a pixel format supported by hdc.

ppfd is used by the system metafile component and otherwise doesn't affect the behavior of SetPixelFormat(). Pass the same PIXELFORMATDESCRIPTOR for ppfd as you pass to ChoosePixelFormat().

SetPixelFormat() returns trUE on success and FALSE if it fails. Call GetLastError() for failure information.

After setting the pixel format in the device context, create a rendering context from the device context. The rendering context inherits the pixel format from the device context.

To create a rendering context, call wglCreateContext().

HGLRC wglCreateContext( HDC hdc );

Creates a new rendering context capable of rendering to the window (or other device) referenced by hdc. hdc is the device context handle for the window (or other drawing surface) your application will be rendering to.

If wglCreateContext() succeeds, it returns the handle of the new rendering context; otherwise, it returns NULL. Call GetLastError() for failure information.

After creating the context, make it current, and render OpenGL commands.

8.4.3. Using Contexts

Before issuing OpenGL commands, your application needs to make the rendering context current for the active thread. To make the context current, call wglMakeCurrent().

BOOL wglMakeCurrent( HDC hdc, HGLRC hglrc );

Makes hglrc current on the specified device context in the current thread. hdc is the device context handle for the window (or other drawing surface) your application will be rendering to. hglrc is the handle of the rendering context. hdc must have the same pixel format as hglrc.

If the calling thread already has a current context, wglMakeCurrent() flushes its buffered OpenGL commands and then makes it noncurrent. To make the current context noncurrent without setting a new current context, call wglMakeCurrent() with NULL for hglrc.

wglMakeCurrent() returns trUE if it succeeds; otherwise, it returns FALSE. Call GetLastError() for failure information.

If wglMakeCurrent() returns trUE, subsequent OpenGL calls affect state in hglrc and render to the device specified by hdc.

A thread can have only one current rendering context, and a rendering context can be current to only one thread at a time.

Multiple rendering contexts can share the same set of OpenGL display lists, texture objects, and buffer objects. To share display lists and objects between contexts, call wglShareLists().

BOOL wglShareLists( HGLRC hglrc1, HGLRC hglrc2 );

Specifies rendering contexts that should share display lists and other OpenGL objects. hglrc1 is a rendering context that stores display lists, texture objects, and buffer objects. hglrc1 shares those lists and objects with hglrc2, which does not have a display list or object store of its own. If your application has already created display lists or objects using hglrc2, wglShareLists() implicitly destroys them.

wglShareLists() returns trUE on success and FALSE if it fails. Call GetLastError() for failure information.

Note

The Microsoft Developer Network documentation states that wglShareLists() shares only display lists. This information doesn't reflect the current state of OpenGL implementations in Windows. Current OpenGL implementations share texture objects and buffer objects in the same way that they share display lists.

Not all rendering contexts can share display lists and objects. See wglShareLists() in the Microsoft Developer Network documentation for details concerning sharing.

8.4.4. Swapping Buffers

If your pixel format is double buffered (that is, if the dwFlags field of the PIXELFORMATDESCRIPTOR has the PFD_DOUBLEBUFFER bit set), you must swap buffers after rendering a frame to display the contents of the back buffer. To swap buffers, call SwapBuffers().

BOOL SwapBuffers( HDC hDC );

Makes the back buffer associated with hDC visible. hDC is the device context handle. If the pixel format isn't double buffered, SwapBuffers() has no effect.

SwapBuffers() returns trUE on success and FALSE if it fails. Call GetLastError() for failure information.

After successfully swapping buffers, SwapBuffers() leaves the contents of the new back buffer undefined.

8.4.5. Deleting Contexts

To delete a rendering context and free its resources, call wglDeleteContext().

BOOL wglDeleteContext( HGLRC hglrc );

Deletes the specified rendering context. hglrc is the rendering context to be deleted.

wglDeleteContext() returns trUE on success and FALSE if it fails. Call GetLastError() for failure information.

If hglrc is current in the calling thread, wglDeleteContext() makes it noncurrent first and then deletes it. If hglrc is current in another thread, however, wglDeleteContext() returns FALSE.