Função DrvBitBlt (winddi.h)

Artigo
08/27/2023

A função DrvBitBlt fornece funcionalidades gerais de transferência de bloco de bits entre superfícies gerenciadas pelo dispositivo, entre bitmaps de formato padrão gerenciados por GDI ou entre uma superfície gerenciada pelo dispositivo e um bitmap de formato padrão gerenciado por GDI.

Sintaxe

BOOL DrvBitBlt(
  [in, out]      SURFOBJ  *psoTrg,
  [in, optional] SURFOBJ  *psoSrc,
  [in, optional] SURFOBJ  *psoMask,
  [in]           CLIPOBJ  *pco,
  [in, optional] XLATEOBJ *pxlo,
  [in]           RECTL    *prclTrg,
  [in, optional] POINTL   *pptlSrc,
  [in, optional] POINTL   *pptlMask,
  [in, optional] BRUSHOBJ *pbo,
  [in, optional] POINTL   *pptlBrush,
  [in]           ROP4     rop4
);

Parâmetros

[in, out] psoTrg

Ponteiro para a estrutura SURFOBJ que descreve a superfície na qual desenhar.

[in, optional] psoSrc

Ponteiro para uma estrutura SURFOBJ que descreve a origem da operação de transferência de bloco de bits, se exigido pelo parâmetro rop4 .

[in, optional] psoMask

Ponteiro para uma estrutura SURFOBJ que descreve uma superfície a ser usada como uma máscara para o parâmetro rop4 . A máscara é um bitmap com 1 bit por pixel. Normalmente, uma máscara é usada para limitar a área a ser modificada na superfície de destino. O mascaramento é selecionado definindo o parâmetro rop4 como o valor 0xAACC. A superfície de destino não será afetada se a máscara for 0x0000.

A máscara será grande o suficiente para cobrir o retângulo de destino.

Se esse parâmetro for NULL e uma máscara for exigida pelo parâmetro rop4 , a máscara implícita no pincel será usada.

[in] pco

Ponteiro para uma estrutura CLIPOBJ que limita a área a ser modificada. Serviços GDI (CLIPOBJXxx) que enumeram a região de clipe como um conjunto de retângulos são fornecidos. Sempre que possível, a GDI simplifica o recorte envolvido; por exemplo, essa função nunca é chamada com um único retângulo de recorte. A GDI corta o retângulo de destino antes de chamar essa função, tornando o recorte adicional desnecessário.

[in, optional] pxlo

Ponteiro para uma estrutura XLATEOBJ que especifica como os índices de cor devem ser convertidos entre as superfícies de origem e destino. Se pxlo for NULL, nenhuma tradução será necessária.

Se a superfície de origem for gerenciada pela paleta, suas cores serão representadas por índices em uma tabela de pesquisa de valores RGB. A estrutura XLATEOBJ pode ser consultada para um vetor de tradução que permitirá que o driver do dispositivo converta qualquer índice de origem em um índice de cores para o destino.

A situação é mais complicada quando, por exemplo, a origem é RGB, mas o destino é gerenciado por paleta. Nesse caso, a correspondência mais próxima de cada valor RGB de origem deve ser encontrada na paleta de destino. O driver pode chamar o serviço XLATEOBJ_iXlate para executar essa operação.

Opcionalmente, o driver de dispositivo pode corresponder às cores quando a paleta de destino é a paleta de dispositivos padrão.

[in] prclTrg

Ponteiro para uma estrutura RECTL que define a área a ser modificada. Essa estrutura usa o sistema de coordenadas da superfície de destino. As bordas inferior e direita desse retângulo não fazem parte da transferência de bloco de bits, o que significa que o retângulo é exclusivo inferior direito.

DrvBitBlt nunca é chamado com um retângulo de destino vazio. Os dois pontos que definem o retângulo são sempre bem ordenados. No entanto, em sistemas multimonitoramento, o retângulo pode definir uma região maior que a superfície de destino. Os drivers devem interseccionar esse retângulo com sua superfície.

[in, optional] pptlSrc

Ponteiro para uma estrutura POINTL que define o canto superior esquerdo do retângulo de origem, se houver uma fonte. Esse parâmetro será ignorado se não houver fonte.

[in, optional] pptlMask

Ponteiro para uma estrutura POINTL que define qual pixel na máscara corresponde ao canto superior esquerdo do retângulo de origem, se houver uma fonte. Esse parâmetro será ignorado se o parâmetro psoMask for NULL.

[in, optional] pbo

Ponteiro para uma estrutura BRUSHOBJ que define o padrão para a transferência de bloco de bits. O serviço de BRUSHOBJ_pvGetRbrush da GDI pode ser usado para recuperar a realização do pincel do dispositivo. Esse parâmetro será ignorado se o parâmetro rop4 não exigir um padrão.

[in, optional] pptlBrush

Ponteiro para uma estrutura POINTL que define a origem do pincel na superfície de destino. O pixel superior esquerdo do pincel é alinhado neste ponto e o pincel se repete de acordo com suas dimensões. Esse parâmetro será ignorado se o parâmetro rop4 não exigir um padrão.

[in] rop4

Especifica uma operação de varredura que define como os pixels de máscara, padrão, origem e destino são combinados para gravar na superfície de destino.

Esta é uma operação de varredura quaternária, que é uma extensão da operação Ternária Rop3. Um Rop4 tem 16 bits relevantes, que são semelhantes aos 8 bits definidos de um Rop3. A maneira mais simples de implementar um Rop4 é considerar seus 2 bytes separadamente: o byte baixo especifica um Rop3 que deve ser calculado se a máscara for um, e o byte alto especifica um Rop3 que pode ser calculado e aplicado se a máscara for 0.

Retornar valor

DrvBitBlt retornará TRUE se a operação de transferência de bloco de bits for bem-sucedida. Caso contrário, a função retornará FALSE e um código de erro será registrado.

Comentários

Se o driver conectar DrvBitBlt, a GDI chamará essa função quando precisar executar uma operação BitBlt em que uma das superfícies é uma superfície gerenciada pelo dispositivo. Se o driver implementar bitmaps opacos gerenciados por dispositivo, ele deverá conectar DrvBitBlt; caso contrário, conectar DrvBitBlt é opcional. Se o driver não puder lidar com a chamada especificada, ele poderá enviar o retorno de chamada para o mecanismo DIB chamando EngBitBlt.

Os serviços CLIPOBJXxx da GDI permitem que o recorte seja reduzido a uma série de retângulos de recorte. Um vetor de tradução auxilia na tradução de índice de cores para paletas.

Nota Não desreferenciar ponteiros de parâmetro, a menos que o ROP indique que eles são necessários. Por exemplo, nunca desnecessariamente desreferenciar pbo -->iSolidColor porque fazer isso para um ROP como BLACKNESS pode causar uma violação de acesso. (Essa regra também se aplica a qualquer função que inclua um parâmetro MIX.)

Se o driver receber uma chamada para essa função na qual o parâmetro rop4 está definido como 0XCCAA, o driver deverá enviar a chamada para EngBitBlt, expondo as superfícies do dispositivo conforme apropriado para a chamada.

Para obter mais informações sobre operações de varredura, consulte a documentação do SDK do Microsoft Windows.