Open GL Super Bible

Previous Table of Contents Next


Reference Section

ChoosePixelFormat

Purpose
Selects the pixel format closest to that specified by the PIXELFORMATDESCRIPTOR, and that can be supported by the given device context.
Include File
<wingdi.h>
Syntax
int ChoosePixelFormat(HDC hDC, CONST PIXELFORMATDESCRIPTOR *ppfd);
Description
This function is used to determine the best available pixel format for a given device context based on the desired characteristics described in the PIXELFORMATDESCRIPTOR structure. This returned format index is then used in the SetPixelFormat function.

Parameters

hDC
HDC: The device context for which this function seeks a best-match pixel format.
ppfd
PIXELFORMATDESCRIPTOR: Pointer to a structure that describes the ideal pixel format that is being sought. The entire contents of this structure are not pertinent to its future use. For a complete description of the PIXELFORMATDESCRIPTOR structure, see the DescribePixelFormat function. Here are the relevant members for this function:
nSize WORD: The size of the structure, usually set to sizeof(PIXELFORMATDESCRIPTOR).
nVersion WORD: The version number of this structure, set to 1.
dwFlag DWORD: A set of flags that specify properties of the pixel buffer.
iPixelType BYTE: The color mode (RGBA or color index) type.
cColorBits BYTE: The depth of the color buffer.
cAlphaBits BYTE: The depth of the alpha buffer.
cAccumBits BYTE: The depth of the accumulation buffer.
cDepthBits BYTE: The depth of the depth buffer.
cStencilBits BYTE: The depth of the stencil buffer.
cAuxBuffers BYTE: The number of auxiliary buffers (not supported by Microsoft).
iLayerType BYTE: The layer type (not supported by Microsoft).
Returns
The index of the nearest matching pixel format for the logical format specified, or zero if no suitable pixel format can be found.

Example

This code from the GLRECT example code in this chapter demonstrates a pixel format being selected:

    int nPixelFormat;

    static PIXELFORMATDESCRIPTOR pfd = {
            sizeof(PIXELFORMATDESCRIPTOR),  // Size of this structure
            1,
            …
            …
            };

    // Choose a pixel format that best matches that described in pfd
    nPixelFormat = ChoosePixelFormat(hDC, &pfd);

    // Set the pixel format for the device context
    SetPixelFormat(hDC, nPixelFormat, &pfd);
See Also
DescribePixelFormat, GetPixelFormat, SetPixelFormat

DescribePixelFormat

Purpose
Obtains detailed information about a pixel format.
Include File
<wingdi.h>
Syntax
int DescribePixelFormat(HDC hDC, int iPixelFormat, UINT nBytes, LPPIXELFORMATDESCRIPTOR ppfd);
Description
This function fills the PIXELFORMATDESCRIPTOR structure with information about the pixel format specified for the given device context. It also returns the maximum available pixel format for the device context. If ppfd is NULL, the function still returns the maximum valid pixel format for the device context. Some fields of the PIXELFORMATDESCRIPTOR are not supported by the Microsoft generic implementation of OpenGL, but these values may be supported by individual hardware manufacturers.

Parameters

hDC
HDC: The device context containing the pixel format of interest.
iPixelFormat
int: The pixel format of interest for the specified device context.
nBytes
UINT: The size of the structure pointed to by ppfd. If this value is zero, no data will be copied to the buffer. This should be set to sizeof(PIXELFORMATDESCRIPTOR).
ppfd
LPPIXELFORMATDESCRIPTOR: A pointer to the PIXELFORMATDESCRIPTOR that on return will contain the detailed information about the pixel format of interest. The PIXELFORMATDESCRIPTOR structure is defined as follows:
    typedef struct tagPIXELFORMATDESCRIPTOR {  
        WORD nSize;
        WORD nVersion;
        DWORD dwFlags;
        BYTE iPixelType;
        BYTE cColorBits;
        BYTE cRedBits;
        BYTE cRedShift;
        BYTE cGreenBits;
        BYTE cGreenShift;
        BYTE cBlueBits;
        BYTE cBlueShift;
        BYTE cAlphaBits;
        BYTE cAlphaShift;
        BYTE cAccumBits;
        BYTE cAccumRedBits;
        BYTE cAccumGreenBits;
        BYTE cAccumBlueBits;
        BYTE cAccumAlphaBits;
        BYTE cDepthBits;
        BYTE cStencilBits;
        BYTE cAuxBuffers;
        BYTE iLayerType;
        BYTE bReserved;
        DWORD dwLayerMask;
        DWORD dwVisibleMask;
        DWORD dwDamageMask;
   }   PIXELFORMATDESCRIPTOR;

nSize contains the size of the structure. It should always be set to sizeof(PIXELFORMATDESCRIPTOR).

nVersion holds the version number of this structure. It should always be set to 1.

dwFlags contains a set of bit flags (Table 4-2) that describe properties of the pixel format. Except as noted, these flags are not mutually exclusive.

Table 4-2 Flags for the dwFlags member of PIXELFORMATDESCRIPTOR

Flag Description

PFD_DRAW_TO_WINDOW The buffer is used to draw to a window or device surface such as a printer.
PFD_DRAW_TO_BITMAP The buffer is used to draw to a memory bitmap.
PFD_SUPPORT_GDI The buffer supporting GDI drawing. This flag is mutually exclusive with PFD_DOUBLEBUFFER.
PFD_SUPPORT_OPENGL The buffer supporting OpenGL drawing.
PFD_GENERIC_FORMAT The pixel format is a generic implementation (supported by GDI emulation). If this flag is not set, the pixel format is supported by hardware or a device driver.
PFD_NEED_PALETTE The pixel format requires the use of logical palettes.
PFD_NEED_SYSTEM_PALETTE Used for nongeneric implementations that support only one hardware palette. This function forces the hardware palette to a one-to-one mapping to the logical palette.
PFD_DOUBLEBUFFER The pixel format is double buffered. This flag is mutually exclusive with PFD_SUPPORT_GDI.
PFD_STEREO The buffer is stereoscopic. This is analogous to front and back buffers in double buffering, only there are left and right buffers. Not supported by Microsoft’s generic implementation of OpenGL.
PFD_DOUBLE_BUFFER_DONTCARE When choosing a pixel format, the format may be either single- or double-buffered, without preference.
PFD_STEREO_DONTCARE When choosing a pixel format, the view may be either stereoscopic or monoscopic, without preference.

iPixelType specifies the type of pixel data. More specifically, it specifies the color selection mode. It may be one of the values in Table 4-3.

Table 4-3 Flag values for iPixelType

Flag Description

PFD_TYPE_RGBA RGBA color mode. Each pixel color is selected by specifiying the red, blue, green, and alpha components.
PFD_TYPE_COLORINDEX Color index mode. Each pixel color is selected by an index into a palette (color table).


Previous Table of Contents Next