ChoosePixelFormat

The ChoosePixelFormat function attempts to match an appropriate pixel format supported by a device context to a given pixel format specification.

int ChoosePixelFormat(
  HDC  hdc,  // device context to search for a best pixel format 
             // match
  CONST PIXELFORMATDESCRIPTOR *  ppfd 
             // pixel format for which a best match is sought
);

Parameters

• hdc
  Specifies the device context that the function examines to determine the best match for the pixel format descriptor pointed to by ppfd.
• ppfd
  Pointer to a PIXELFORMATDESCRIPTOR structure that specifies the requested pixel format. In this context, the members of the PIXELFORMATDESCRIPTOR structure that ppfd points to are used as follows:

  • nSize
    Specifies the size of the PIXELFORMATDESCRIPTOR data structure. Set this member to sizeof(PIXELFORMATDESCRIPTOR).

  • nVersion
    Specifies the version number of the PIXELFORMATDESCRIPTOR data structure. Set this member to 1.

  • dwFlags
    A set of bit flags that specify properties of the pixel buffer. You can combine the following bit flag constants by using bitwise-OR.

    If any of the following flags are set, the ChoosePixelFormat function attempts to match pixel formats that also have that flag or flags set. Otherwise, ChoosePixelFormat ignores that flag in the pixel formats:

    PFD_DRAW_TO_WINDOW
    PFD_DRAW_TO_BITMAP
    PFD_SUPPORT_GDI
    PFD_SUPPORT_OPENGL

    If any of the following flags are set, ChoosePixelFormat attempts to match pixel formats that also have that flag or flags set. Otherwise, it attempts to match pixel formats without that flag set:

    PFD_DOUBLEBUFFER
    PFD_STEREO

    If the following flag is set, the function ignores the PFD_DOUBLEBUFFER flag in the pixel formats:

    PFD_DOUBLEBUFFER_DONTCARE

    If the following flag is set, the function ignores the PFD_STEREO flag in the pixel formats:

    PFD_STEREO_DONTCARE

  • iPixelType
    Specifies the type of pixel format for the function to consider:

    PFD_TYPE_RGBA
    PFD_TYPE_COLORINDEX

  • cColorBits
    Zero or greater.

  • cRedBits
    Not used.

  • cRedShift
    Not used.

  • cGreenBits
    Not used.

  • cGreenShift
    Not used.

  • cBlueBits
    Not used.

  • cBlueShift
    Not used.

  • cAlphaBits
    Zero or greater.

  • cAlphaShift
    Not used.

  • cAccumBits
    Zero or greater.

  • cAccumRedBits
    Not used.

  • cAccumGreenBits
    Not used.

  • cAccumBlueBits
    Not used.

  • cAccumAlphaBits
    Not used.

  • cDepthBits
    Zero or greater.

  • cStencilBits
    Zero or greater.

  • cAuxBuffers
    Zero or greater.

  • iLayerType
    Specifies one of the following layer type values:

    PFD_MAIN_PLANE
    PFD_OVERLAY_PLANE
    PFD_UNDERLAY_PLANE

  • bReserved
    Not used.

  • dwLayerMask
    Not used.

  • dwVisibleMask
    Not used.

  • dwDamageMask
    Not used.

Return Values

If the function succeeds, the return value is a pixel format index (one-based) that is the closest match to the given pixel format descriptor.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

You must ensure that the pixel format matched by the ChoosePixelFormat function satisfies your requirements. For example, if you request a pixel format with a 24-bit RGB color buffer but the device context offers only 8-bit RGB color buffers, the function returns a pixel format with an 8-bit RGB color buffer.

The following code sample shows how to use ChoosePixelFormat to match a specified pixel format:

PIXELFORMATDESCRIPTOR pfd = { 
    sizeof(PIXELFORMATDESCRIPTOR),  //  size of this pfd 
    1,                     // version number 
    PFD_DRAW_TO_WINDOW |   // support window 
    PFD_SUPPORT_OPENGL |   // support OpenGL 
    PFD_DOUBLEBUFFER,      // double buffered 
    PFD_TYPE_RGBA,         // RGBA type 
    24,                    // 24-bit color depth 
    0, 0, 0, 0, 0, 0,      // color bits ignored 
    0,                     // no alpha buffer 
    0,                     // shift bit ignored 
    0,                     // no accumulation buffer 
    0, 0, 0, 0,            // accum bits ignored 
    32,                    // 32-bit z-buffer     
    0,                     // no stencil buffer 
    0,                     // no auxiliary buffer 
    PFD_MAIN_PLANE,        // main layer 
    0,                     // reserved 
    0, 0, 0                // layer masks ignored 
    }; 
    HDC  hdc;
    int  iPixelFormat; 
 
iPixelFormat = ChoosePixelFormat(hdc, &pfd);

Requirements

**  Windows NT/2000:** Requires Windows NT 3.5 or later.
**  Windows 95/98:** Requires Windows 95 or later. Available as a redistributable for Windows 95.
**  Header:** Declared in wingdi.h.
**  Import Library:** Use gdi32.lib.

See Also

OpenGL on Windows NT, Windows 2000, and Windows 95/98, Win32 Functions, DescribePixelFormat, GetPixelFormat, SetPixelFormat