Função MaskBlt (wingdi.h)

Artigo
03/13/2024

A função MaskBlt combina os dados de cor para os bitmaps de origem e destino usando a operação de máscara e varredura especificada.

Sintaxe

BOOL MaskBlt(
  [in] HDC     hdcDest,
  [in] int     xDest,
  [in] int     yDest,
  [in] int     width,
  [in] int     height,
  [in] HDC     hdcSrc,
  [in] int     xSrc,
  [in] int     ySrc,
  [in] HBITMAP hbmMask,
  [in] int     xMask,
  [in] int     yMask,
  [in] DWORD   rop
);

Parâmetros

[in] hdcDest

Um identificador para o contexto do dispositivo de destino.

[in] xDest

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

[in] yDest

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

[in] width

A largura, em unidades lógicas, do retângulo de destino e do bitmap de origem.

[in] height

A altura, em unidades lógicas, do retângulo de destino e do bitmap de origem.

[in] hdcSrc

Um identificador para o contexto do dispositivo do qual o bitmap deve ser copiado. Ele deverá ser zero se o parâmetro dwRop especificar uma operação de varredura que não inclua uma origem.

[in] xSrc

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

[in] ySrc

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

[in] hbmMask

Um identificador para o bitmap de máscara monocromática combinado com o bitmap de cor no contexto do dispositivo de origem.

[in] xMask

O deslocamento de pixel horizontal para o bitmap de máscara especificado pelo parâmetro hbmMask .

[in] yMask

O deslocamento de pixel vertical para o bitmap de máscara especificado pelo parâmetro hbmMask .

[in] rop

Os CÓDIGOS de operação de raster ternário em primeiro plano e em segundo plano (ROPs) que a função usa para controlar a combinação de dados de origem e de destino. O código de operação de varredura em segundo plano é armazenado no byte de alta ordem da palavra de alta ordem desse valor; o código de operação de varredura em primeiro plano é armazenado no byte de baixa ordem da palavra de alta ordem desse valor; a palavra de baixa ordem desse valor é ignorada e deve ser zero. A macro MAKEROP4 cria essas combinações de códigos de operação de raster em primeiro plano e em segundo plano.

Para obter uma discussão sobre o primeiro plano e a tela de fundo no contexto dessa função, consulte a seção Comentários a seguir.

Para obter uma lista de ROPs (códigos de operação de varredura comuns), consulte a função BitBlt . Observe que o ROP CAPTUREBLT geralmente não pode ser usado para imprimir contextos de dispositivo.

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.

Comentários

A função MaskBlt usa bitmaps dependentes do dispositivo.

Um valor de 1 na máscara especificada por hbmMask indica que o código de operação de varredura de primeiro plano especificado por dwRop deve ser aplicado nesse local. Um valor de 0 na máscara indica que o código de operação de varredura em segundo plano especificado por dwRop deve ser aplicado nesse local.

Se as operações de varredura exigirem uma origem, o retângulo da máscara deverá cobrir o retângulo de origem. Se isso não acontecer, a função falhará. Se as operações de varredura não exigirem uma origem, o retângulo da máscara deverá cobrir o retângulo de destino. Se isso não acontecer, a função falhará.

Se uma transformação de rotação ou de tesoura estiver vigente para o contexto do dispositivo de origem quando essa função for chamada, ocorrerá um erro. No entanto, outros tipos de transformação são permitidos.

Se os formatos de cor dos bitmaps de origem, padrão e destino forem diferentes, essa função converterá o padrão ou o formato de origem, ou ambos, para corresponder ao formato de destino.

Se o bitmap de máscara não for um bitmap monocromático, ocorrerá um erro.

Quando um meta-arquivo aprimorado está sendo registrado, ocorre um erro (e a função retorna FALSE) 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 MaskBlt . Um aplicativo deve chamar a função GetDeviceCaps com o parâmetro nIndex como RC_BITBLT para determinar se um dispositivo dá suporte a essa função.

Se nenhum bitmap de máscara for fornecido, essa função se comportará exatamente como BitBlt, usando o código de operação de varredura em primeiro plano.

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

Quando usados em um sistema de vários monitores, hdcSrc e hdcDest devem se referir ao mesmo dispositivo ou a função falhará. Para transferir dados entre DCs para diferentes dispositivos, converta o bitmap de memória (bitmap compatível ou DDB) em um DIB chamando GetDIBits. Para exibir o DIB para o segundo dispositivo, chame SetDIBits ou StretchDIBits.

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