Export (0) Print
Expand All

ChoosePixelFormat function

Applies to: desktop apps only

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

Syntax

int WINAPI 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:

nSizeSpecifies the size of the PIXELFORMATDESCRIPTOR data structure. Set this member to sizeof(PIXELFORMATDESCRIPTOR).
nVersionSpecifies the version number of the PIXELFORMATDESCRIPTOR data structure. Set this member to 1.
dwFlagsA 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
iPixelTypeSpecifies the type of pixel format for the function to consider: PFD_TYPE_RGBA PFD_TYPE_COLORINDEX
cColorBitsZero or greater.
cRedBitsNot used.
cRedShiftNot used.
cGreenBitsNot used.
cGreenShiftNot used.
cBlueBitsNot used.
cBlueShiftNot used.
cAlphaBitsZero or greater.
cAlphaShiftNot used.
cAccumBitsZero or greater.
cAccumRedBitsNot used.
cAccumGreenBitsNot used.
cAccumBlueBitsNot used.
cAccumAlphaBitsNot used.
cDepthBitsZero or greater.
cStencilBitsZero or greater.
cAuxBuffersZero or greater.
iLayerTypeSpecifies one of the following layer type values: PFD_MAIN_PLANE PFD_OVERLAY_PLANE PFD_UNDERLAY_PLANE
bReservedNot used.
dwLayerMaskNot used.
dwVisibleMaskNot used.
dwDamageMaskNot 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

Minimum supported server

Windows 2000 Server

Header

Wingdi.h

Library

Gdi32.lib

DLL

Gdi32.dll

See also

OpenGL on Windows
Windows Functions
DescribePixelFormat
GetPixelFormat
SetPixelFormat

 

 

Send comments about this topic to Microsoft

Build date: 3/6/2012

Community Additions

ADD
Show:
© 2015 Microsoft