Função CreateDIBSection (wingdi.h)

Artigo
03/08/2023

A função CreateDIBSection cria um DIB no qual os aplicativos podem gravar diretamente. A função fornece um ponteiro para o local dos valores de bitmap. Você pode fornecer um identificador para um objeto de mapeamento de arquivo que a função usará para criar o bitmap ou permitir que o sistema aloque a memória para o bitmap.

Sintaxe

HBITMAP CreateDIBSection(
  [in]  HDC              hdc,
  [in]  const BITMAPINFO *pbmi,
  [in]  UINT             usage,
  [out] VOID             **ppvBits,
  [in]  HANDLE           hSection,
  [in]  DWORD            offset
);

Parâmetros

[in] hdc

Um identificador para um contexto de dispositivo. Se o valor de iUsage for DIB_PAL_COLORS, a função usará a paleta lógica desse contexto de dispositivo para inicializar as cores DIB.

[in] pbmi

Um ponteiro para uma estrutura BITMAPINFO que especifica vários atributos do DIB, incluindo as dimensões e cores do bitmap.

[in] usage

O tipo de dados contidos no membro da matriz bmiColors da estrutura BITMAPINFO apontada por pbmi (índices de paleta lógica ou valores RGB literais). Os valores a seguir são definidos.

Valor	Significado
DIB_PAL_COLORS	O membro bmiColors é uma matriz de índices de 16 bits na paleta lógica do contexto do dispositivo especificado pelo hdc.
DIB_RGB_COLORS	A estrutura BITMAPINFO contém uma matriz de valores RGB literais.

[out] ppvBits

Um ponteiro para uma variável que recebe um ponteiro para o local dos valores de bit DIB.

[in] hSection

Um identificador para um objeto de mapeamento de arquivo que a função usará para criar o DIB. Este parâmetro pode ser NULL.

Se hSection não for NULL, ele deverá ser um identificador para um objeto de mapeamento de arquivo criado chamando a função CreateFileMapping com o sinalizador PAGE_READWRITE ou PAGE_WRITECOPY. Não há suporte para seções DIB somente leitura. Os identificadores criados por outros meios farão com que CreateDIBSection falhe.

Se hSection não for NULL, a função CreateDIBSection localizará os valores de bitmap em offset dwOffset no objeto de mapeamento de arquivo referenciado por hSection. Posteriormente, um aplicativo pode recuperar o identificador hSection chamando a função GetObject com o HBITMAP retornado por CreateDIBSection.

Se hSection for NULL, o sistema alocará memória para o DIB. Nesse caso, a função CreateDIBSection ignora o parâmetro dwOffset . Um aplicativo não pode obter posteriormente um identificador para essa memória. O membro dshSection da estrutura DIBSECTION preenchida chamando a função GetObject será NULL.

[in] offset

O deslocamento do início do objeto de mapeamento de arquivo referenciado por hSection em que o armazenamento para os valores de bitmap deve começar. Esse valor será ignorado se hSection for NULL. Os valores de bitmap são alinhados em limites de palavra dupla, portanto, dwOffset deve ser um múltiplo do tamanho de um DWORD.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para o DIB recém-criado e *ppvBits apontará para os valores de bitmap.

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

GetLastError pode retornar o seguinte valor:

Código do erro	Descrição
ERROR_INVALID_PARAMETER	Um ou mais dos parâmetros de entrada são inválidos.

Comentários

Conforme observado acima, se hSection for NULL, o sistema alocará memória para o DIB. O sistema fecha o identificador dessa memória quando você exclui posteriormente o DIB chamando a função DeleteObject . Se hSection não for NULL, você deverá fechar o identificador de memória hSection depois de chamar DeleteObject para excluir o bitmap.

Não é possível colar uma seção DIB de um aplicativo em outro aplicativo.

CreateDIBSection não usa os parâmetros BITMAPINFOHEADERbiXPelsPerMeter ou biYPelsPerMeter e não fornecerá informações de resolução na estrutura BITMAPINFO .

Você precisa garantir que o subsistema GDI tenha concluído qualquer desenho para um bitmap criado por CreateDIBSection antes de desenhar para o bitmap por conta própria. O acesso ao bitmap deve ser sincronizado. Faça isso chamando a função GdiFlush . Isso se aplica a qualquer uso do ponteiro para os valores de bitmap, incluindo passar o ponteiro em chamadas para funções como SetDIBits.

ICM: Nenhum gerenciamento de cores é feito.

Requisitos

Requisito	Valor
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 (inclua Windows.h)
Biblioteca	Gdi32.lib
DLL	Gdi32.dll