Função CreateBitmap (wingdi.h)

Artigo
03/08/2023

A função CreateBitmap cria um bitmap com o formato de largura, altura e cor especificados (planos de cores e bits por pixel).

Sintaxe

HBITMAP CreateBitmap(
  [in] int        nWidth,
  [in] int        nHeight,
  [in] UINT       nPlanes,
  [in] UINT       nBitCount,
  [in] const VOID *lpBits
);

Parâmetros

[in] nWidth

A largura do bitmap, em pixels.

[in] nHeight

A altura do bitmap, em pixels.

[in] nPlanes

O número de planos de cores usados pelo dispositivo.

[in] nBitCount

O número de bits necessários para identificar a cor de um único pixel.

[in] lpBits

Um ponteiro para uma matriz de dados de cores usada para definir as cores em um retângulo de pixels. Cada linha de verificação no retângulo deve ser alinhada à palavra (linhas de verificação que não são alinhadas a palavras devem ser acolchoadas com zeros). O tamanho do buffer esperado, cj, pode ser calculado usando a fórmula:

cj = (((nWidth * nPlanes * nBitCount + 15) >> 4) << 1) * nHeight;

Se esse parâmetro for NULL, o conteúdo do novo bitmap será indefinido.

Valor retornado

Se a função for bem-sucedida, o valor retornado será um identificador para um bitmap.

Se a função falhar, o valor retornado será NULL.

Essa função pode retornar o valor a seguir.

Código de retorno	Descrição
ERROR_INVALID_BITMAP	O tamanho calculado do bitmap é menor que zero.

Comentários

A função CreateBitmap cria um bitmap dependente do dispositivo.

Depois que um bitmap é criado, ele pode ser selecionado em um contexto de dispositivo chamando a função SelectObject . No entanto, o bitmap só poderá ser selecionado em um contexto de dispositivo se o bitmap e o DC tiverem o mesmo formato.

A função CreateBitmap pode ser usada para criar bitmaps de cor. No entanto, por motivos de desempenho, os aplicativos devem usar CreateBitmap para criar bitmaps monocromáticos e CreateCompatibleBitmap para criar bitmaps de cor. Sempre que um bitmap de cor retornado de CreateBitmap é selecionado em um contexto de dispositivo, o sistema verifica se o bitmap corresponde ao formato do contexto do dispositivo no qual está sendo selecionado. Como CreateCompatibleBitmap usa um contexto de dispositivo, ele retorna um bitmap que tem o mesmo formato que o contexto do dispositivo especificado. Assim, as chamadas subsequentes para SelectObject são mais rápidas com um bitmap de cor de CreateCompatibleBitmap do que com um bitmap de cor retornado de CreateBitmap.

Se o bitmap for monocromático, zeros representarão a cor do primeiro plano e os representam a cor da tela de fundo para o contexto do dispositivo de destino.

Se um aplicativo definir os parâmetros nWidth ou nHeight como zero, CreateBitmap retornará o identificador para um bitmap monocromático de 1 por 1 pixel.

Quando você não precisar mais do bitmap, chame a função DeleteObject para excluí-la.

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