Função ChoosePixelFormat (wingdi.h)

Artigo
08/27/2023

A função ChoosePixelFormat tenta corresponder a um formato de pixel apropriado compatível com um contexto de dispositivo com uma especificação de formato de pixel específica.

Sintaxe

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

Parâmetros

hdc

Especifica o contexto do dispositivo que a função examina para determinar a melhor correspondência para o descritor de formato de pixel apontado pelo ppfd.

ppfd

Ponteiro para uma estrutura PIXELFORMATDESCRIPTOR que especifica o formato de pixel solicitado. Nesse contexto, os membros da estrutura PIXELFORMATDESCRIPTOR para a qual ppfd aponta são usados da seguinte maneira:

nSize	Especifica o tamanho da estrutura de dados PIXELFORMATDESCRIPTOR . Defina esse membro como `sizeof(PIXELFORMATDESCRIPTOR)`.
nVersion	Especifica o número de versão da estrutura de dados PIXELFORMATDESCRIPTOR . Defina esse membro como 1.
dwFlags	Um conjunto de sinalizadores de bits que especificam propriedades do buffer de pixel. Você pode combinar as seguintes constantes de sinalizador de bit usando OR bit a bit. Se qualquer um dos sinalizadores a seguir estiver definido, a função ChoosePixelFormat tentará corresponder aos formatos de pixel que também têm esse sinalizador ou sinalizador definido. Caso contrário, ChoosePixelFormat ignorará esse sinalizador nos formatos de pixel: PFD_DRAW_TO_WINDOW, PFD_DRAW_TO_BITMAP, PFD_SUPPORT_GDIPFD_SUPPORT_OPENGL Se qualquer um dos sinalizadores a seguir estiver definido, ChoosePixelFormat tentará corresponder aos formatos de pixel que também têm esse sinalizador ou sinalizador definido. Caso contrário, ele tentará corresponder aos formatos de pixel sem esse sinalizador definido: PFD_DOUBLEBUFFER PFD_STEREO Se o seguinte sinalizador estiver definido, a função ignorará o sinalizador PFD_DOUBLEBUFFER nos formatos de pixel: PFD_DOUBLEBUFFER_DONTCARE Se o seguinte sinalizador estiver definido, a função ignorará o sinalizador PFD_STEREO nos formatos de pixel: PFD_STEREO_DONTCARE
iPixelType	Especifica o tipo de formato de pixel para a função a ser considerada: PFD_TYPE_RGBA, PFD_TYPE_COLORINDEX
cColorBits	Zero ou maior.
cRedBits	Não usado.
cRedShift	Não usado.
cGreenBits	Não usado.
cGreenShift	Não usado.
cBlueBits	Não usado.
cBlueShift	Não usado.
cAlphaBits	Zero ou maior.
cAlphaShift	Não usado.
cAccumBits	Zero ou maior.
cAccumRedBits	Não usado.
cAccumGreenBits	Não usado.
cAccumBlueBits	Não usado.
cAccumAlphaBits	Não usado.
cDepthBits	Zero ou maior.
cStencilBits	Zero ou maior.
cAuxBuffers	Zero ou maior.
iLayerType	Especifica um dos seguintes valores de tipo de camada: PFD_MAIN_PLANE, PFD_OVERLAY_PLANEPFD_UNDERLAY_PLANE
bReserved	Não usado.
dwLayerMask	Não usado.
dwVisibleMask	Não usado.
dwDamageMask	Não usado.

Valor retornado

Se a função for bem-sucedida, o valor retornado será um índice de formato de pixel (baseado em um) que é a correspondência mais próxima do descritor de formato de pixel fornecido.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Você deve garantir que o formato de pixel correspondido pela função ChoosePixelFormat atenda aos seus requisitos. Por exemplo, se você solicitar um formato de pixel com um buffer de cores RGB de 24 bits, mas o contexto do dispositivo oferecer apenas buffers de cores RGB de 8 bits, a função retornará um formato de pixel com um buffer de cores RGB de 8 bits.

Exemplos

O exemplo de código a seguir mostra como usar ChoosePixelFormat para corresponder a um formato de pixel especificado.

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);

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wingdi.h
Biblioteca	Gdi32.lib
DLL	Gdi32.dll