Função BitBlt (wingdi.h)

Artigo
08/27/2023

A função BitBlt executa uma transferência de bloco de bits dos dados de cor correspondentes a um retângulo de pixels do contexto do dispositivo de origem especificado para um contexto de dispositivo de destino.

Sintaxe

BOOL BitBlt(
  [in] HDC   hdc,
  [in] int   x,
  [in] int   y,
  [in] int   cx,
  [in] int   cy,
  [in] HDC   hdcSrc,
  [in] int   x1,
  [in] int   y1,
  [in] DWORD rop
);

Parâmetros

[in] hdc

Um identificador para o contexto do dispositivo de destino.

[in] x

A coordenada x, em unidades lógicas, do canto superior esquerdo do retângulo de destino.

[in] y

A coordenada y, em unidades lógicas, do canto superior esquerdo do retângulo de destino.

[in] cx

A largura, em unidades lógicas, dos retângulos de origem e destino.

[in] cy

A altura, em unidades lógicas, da origem e dos retângulos de destino.

[in] hdcSrc

Um identificador para o contexto do dispositivo de origem.

[in] x1

A coordenada x, em unidades lógicas, do canto superior esquerdo do retângulo de origem.

[in] y1

A coordenada y, em unidades lógicas, do canto superior esquerdo do retângulo de origem.

[in] rop

Um código de operação de raster. Esses códigos definem como os dados de cor do retângulo de origem devem ser combinados com os dados de cor do retângulo de destino para obter a cor final.

A lista a seguir mostra alguns códigos de operação de raster comuns.

Valor	Significado
ESCURIDÃO	Preenche o retângulo de destino usando a cor associada ao índice 0 na paleta física. (Essa cor é preta para a paleta física padrão.)
CAPTUREBLT	Inclui todas as janelas em camadas na parte superior da janela na imagem resultante. Por padrão, a imagem contém apenas sua janela. Observe que isso geralmente não pode ser usado para contextos de dispositivo de impressão.
DSTINVERT	Inverte o retângulo de destino.
MERGECOPY	Mescla as cores do retângulo de origem com o pincel atualmente selecionado no hdcDest usando o operador AND booliano.
MERGEPAINT	Mescla as cores do retângulo de origem invertido com as cores do retângulo de destino usando o operador OR booliano.
NOMIRRORBITMAP	Impede que o bitmap seja espelhado.
NOTSRCCOPY	Copia o retângulo de origem invertido para o destino.
NOTSRCERASE	Combina as cores dos retângulos de origem e destino usando o operador OR booliano e inverte a cor resultante.
PATCOPY	Copia o pincel selecionado no momento no hdcDest no bitmap de destino.
PATINVERT	Combina as cores do pincel atualmente selecionadas no hdcDest, com as cores do retângulo de destino usando o operador XOR booliano.
PATPAINT	Combina as cores do pincel atualmente selecionado no hdcDest, com as cores do retângulo de origem invertido usando o operador OR booliano. O resultado dessa operação é combinado com as cores do retângulo de destino usando o operador OR booliano.
SRCAND	Combina as cores dos retângulos de origem e destino usando o operador AND booliano.
SRCCOPY	Copia o retângulo de origem diretamente para o retângulo de destino.
SRCERASE	Combina as cores invertidas do retângulo de destino com as cores do retângulo de origem usando o operador AND booliano.
SRCINVERT	Combina as cores dos retângulos de origem e destino usando o operador XOR booliano.
SRCPAINT	Combina as cores dos retângulos de origem e destino usando o operador OR booliano.
BRANCURA	Preenche o retângulo de destino usando a cor associada ao índice 1 na paleta física. (Essa cor é branca para a paleta física padrão.)

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

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

Comentários

BitBlt só faz recorte no DC de destino.

Se uma transformação de rotação ou de tesoura estiver em vigor no contexto do dispositivo de origem, BitBlt retornará um erro. Se houver outras transformações no contexto do dispositivo de origem (e uma transformação correspondente não estiver em vigor no contexto do dispositivo de destino), o retângulo no contexto do dispositivo de destino será estendido, compactado ou girado, conforme necessário.

Se os formatos de cor dos contextos do dispositivo de origem e de destino não corresponderem, a função BitBlt converterá o formato de cor de origem para corresponder ao formato de destino.

Quando um meta-arquivos aprimorado está sendo registrado, ocorre um erro se o contexto do dispositivo de origem identifica um contexto de dispositivo de meta-arquivo aprimorado.

Nem todos os dispositivos dão suporte à função BitBlt . Para obter mais informações, consulte a entrada de funcionalidade de RC_BITBLT raster na função GetDeviceCaps , bem como as seguintes funções: MaskBlt, PlgBlt e StretchBlt.

BitBlt retornará um erro se os contextos do dispositivo de origem e de destino representarem dispositivos diferentes. Para transferir dados entre DCs para dispositivos diferentes, converta o bitmap de memória em um DIB chamando GetDIBits. Para exibir o DIB para o segundo dispositivo, chame SetDIBits ou StretchDIBits.

ICM: Nenhum gerenciamento de cores é executado quando ocorrem blits.

Exemplos

O exemplo de código a seguir demonstra o uso de BitBlt.

if (!BitBlt(hdcMemDC,
    0, 0,
    rcClient.right - rcClient.left, rcClient.bottom - rcClient.top,
    hdcWindow,
    0, 0,
    SRCCOPY))
{
    MessageBox(hWnd, L"BitBlt has failed", L"Failed", MB_OK);
    goto done;
}

Para ver este exemplo no contexto, consulte Capturando uma imagem.

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