ChoosePixelFormat function

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

Syntax

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

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 Value

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.

Examples

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

   
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header wingdi.h
Library Gdi32.lib
DLL Gdi32.dll

See Also

DescribePixelFormat

GetPixelFormat

OpenGL on Windows

SetPixelFormat

Windows Functions