Drawing3d documented Class Library

FeaturesW32.ChoosePixelFormat Method

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

[Visual Basic]
<PreserveSig> _
<DllImport(EntryPoint:="ChoosePixelFormat", CharSet:=CharSet.None, SetLastError:=True, ExactSpelling:=False, PreserveSig:=True, CallingConvention:=CallingConvention.Winapi, BestFitMapping:=False, ThrowOnUnmappableChar:=False, Value:="gdi32.dll")> _
<SuppressUnmanagedCodeSecurity> _
Public Shared Sub ChoosePixelFormat( _
   ByVal deviceContext As IntPtr, _
   ByRef pixelFormatDescriptor As PIXELFORMATDESCRIPTOR _
)
[C#]
[PreserveSig]
[DllImport(EntryPoint="ChoosePixelFormat", CharSet=CharSet.None, SetLastError=True, ExactSpelling=False, PreserveSig=True, CallingConvention=CallingConvention.Winapi, BestFitMapping=False, ThrowOnUnmappableChar=False, Value="gdi32.dll")]
[SuppressUnmanagedCodeSecurity]
public static int ChoosePixelFormat(
   IntPtr deviceContext,
   ref PIXELFORMATDESCRIPTOR pixelFormatDescriptor
);

Parameters

deviceContext
Specifies the device context that the function examines to determine the best match for the pixel format descriptor pointed to by ppfd.
pixelFormatDescriptor

Pointer to a FeaturesW32.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.

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:

            HDC hdc;
            int pixelFormat;
            FeaturesW32.PIXELFORMATDESCRIPTOR pfd;

            // size of this pfd
            pfd.nSize = (ushort) sizeof(FeaturesW32.PIXELFORMATDESCRIPTOR);

            // version number
            pfd.nVersion = 1;

            // support window, support OpenGL, double buffered
            pfd.dwFlags = Gdi.PFD_DRAW_TO_WINDOW | Gdi.PFD_SUPPORT_OPENGL | Gdi.PFD_DOUBLEBUFFER;

            // RGBA type
            pfd.iPixelType = Gdi.PFD_TYPE_RGBA;

            // 24-bit color depth
            pfd.cColorBits = 24;

            // color bits and shift bits ignored
            pfd.cRedBits = 0;
            pfd.cRedShift = 0;
            pfd.cGreenBits = 0;
            pfd.cGreenShift = 0;
            pfd.cBlueBits = 0;
            pfd.cBlueShift = 0;
            pfd.cAlphaBits = 0;
            pfd.cAlphaShift = 0;

            // no accumulation buffer, accum bits ignored
            pfd.cAccumBits = 0;
            pfd.cAccumRedBits = 0;
            pfd.cAccumGreenBits = 0;
            pfd.cAccumBlueBits = 0;
            pfd.cAccumAlphaBits = 0;

            // no stencil buffer
            pfd.cStencilBits = 0;

            // no auxiliary buffer
            pfd.cAuxBuffers = 0;

            // main layer
            pfd.iLayerType = Gdi.PFD_MAIN_PLANE;

            // reserved
            pfd.bReserved = 0;

            // layer masks ignored
            pfd.dwLayerMask = 0;
            pfd.dwVisibleMask = 0;
            pfd.dwDamageMask = 0;

            pixelFormat = Gdi.ChoosePixelFormat(hdc, &pfd);
        

See Also

FeaturesW32 Class | Drawing3d.OS.Windows Namespace | SetPixelFormat