Função DrvStretchBlt (winddi.h)

Artigo
03/04/2024

A função DrvStretchBlt fornece recursos de transferência de bloco de bits estendidos entre qualquer combinação de superfícies gerenciadas por dispositivo e GDI.

Sintaxe

BOOL DrvStretchBlt(
  [in, out]      SURFOBJ         *psoDest,
  [in, out]      SURFOBJ         *psoSrc,
  [in, optional] SURFOBJ         *psoMask,
  [in]           CLIPOBJ         *pco,
  [in, optional] XLATEOBJ        *pxlo,
  [in, optional] COLORADJUSTMENT *pca,
  [in]           POINTL          *pptlHTOrg,
  [in]           RECTL           *prclDest,
  [in]           RECTL           *prclSrc,
  [in, optional] POINTL          *pptlMask,
  [in]           ULONG           iMode
);

Parâmetros

[in, out] psoDest

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

[in, out] psoSrc

Ponteiro para a estrutura SURFOBJ que define a origem da operação de transferência de bloco de bits.

[in, optional] psoMask

Ponteiro opcional para uma estrutura SURFOBJ que define uma superfície que fornece uma máscara para a origem. A máscara é definida por um mapa lógico, que é um bitmap com 1 bit por pixel.

A máscara limita a área da origem que é copiada. Se esse parâmetro for especificado, ele terá um rop4 implícito de 0xCCAA, o que significa que a origem deve ser copiada onde quer que a máscara seja uma, mas o destino deve ser deixado sozinho onde quer que a máscara seja zero.

Quando esse parâmetro é NULL, há um rop4 implícito de 0xCCCC, o que significa que a origem deve ser copiada em todos os lugares no retângulo de origem.

A máscara sempre será grande o suficiente para conter a fonte relevante; tiling é desnecessário.

[in] pco

Ponteiro para uma estrutura CLIPOBJ que limita a área a ser modificada no destino. Os serviços GDI são fornecidos para enumerar a região de clipe como um conjunto de retângulos.

Sempre que possível, a GDI simplifica o recorte envolvido. No entanto, ao contrário de DrvBitBlt, DrvStretchBlt pode ser chamado com um único retângulo de recorte. Isso impede erros de arredondamento ao recortar a saída.

[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.

A estrutura XLATEOBJ também pode ser consultada para localizar a cor RGB para qualquer índice de origem. Uma transferência de bloco de bits ampliada de alta qualidade precisará interpolar cores em alguns casos.

[in, optional] pca

Ponteiro para uma estrutura COLORADJUSTMENT que define os valores de ajuste de cor a serem aplicados ao bitmap de origem antes de alongar os bits. (Consulte a documentação do SDK do Microsoft Windows.)

[in] pptlHTOrg

Ponteiro para uma estrutura POINTL que especifica a origem do pincel de meio tom. Os drivers de dispositivo que usam pincéis de meio tom devem alinhar o pixel superior esquerdo do padrão do pincel com esse ponto na superfície do dispositivo.

[in] prclDest

Ponteiro para uma estrutura RECTL que define a área a ser modificada no sistema de coordenadas da superfície de destino. Esse retângulo é definido por dois pontos que não são necessariamente bem ordenados, o que significa que as coordenadas do segundo ponto não são necessariamente maiores do que as do primeiro ponto. O retângulo que eles descrevem não inclui as bordas inferior e direita. Essa função nunca é chamada com um retângulo de destino vazio.

DrvStretchBlt deve trocar os dois valores x e/ou os dois valores y quando o retângulo de destino não estiver bem ordenado.

[in] prclSrc

Ponteiro para uma estrutura RECTL que define a área que será copiada no sistema de coordenadas da superfície de origem. O retângulo é definido por dois pontos e será mapeado para o retângulo definido por prclDest. Os pontos do retângulo de origem são bem ordenados. Essa função nunca recebe um retângulo de origem vazio.

O mapeamento é definido por prclSrc e prclDest. Os pontos especificados em prclDest e prclSrc estão em coordenadas de inteiro, que correspondem aos centros de pixel. Um retângulo definido por dois desses pontos é considerado um retângulo geométrico com dois vértices cujas coordenadas são os pontos determinados, mas com 0,5 subtraído de cada coordenada. (As estruturas POINTL devem ser consideradas uma notação abreviada para especificar esses vértices de coordenadas fracionárias.)

As bordas de qualquer retângulo nunca cruzam um pixel, mas giram em torno de um conjunto de pixels. Os pixels dentro do retângulo são aqueles esperados para um retângulo "exclusivo inferior direito". DrvStretchBlt mapeará o retângulo de origem geométrico exatamente para o retângulo de destino geométrico.

[in, optional] pptlMask

Ponteiro para uma estrutura POINTL que especifica qual pixel na máscara fornecida corresponde ao pixel superior esquerdo no retângulo de origem. Ignore esse parâmetro se nenhuma máscara for especificada.

[in] iMode

Especifica como os pixels de origem são combinados para obter pixels de saída. O modo HALFTONE é mais lento do que os outros modos, mas produz imagens de maior qualidade.

Valor	Significado
BLACKONWHITE	Em uma transferência de bloco de bits reduzida, os pixels devem ser combinados com uma operação AND booliana. Em uma transferência de bloco de bits alongada, os pixels devem ser replicados.
COLORONCOLOR	Em uma transferência de bloco de bits reduzida, pixels suficientes devem ser ignorados para que os pixels não precisem ser combinados. Em uma transferência de bloco de bits alongada, os pixels devem ser replicados.
HALFTONE	O driver pode usar grupos de pixels na superfície de saída para aproximar melhor a cor ou o nível cinza da entrada.
WHITEONBLACK	Em uma transferência de bloco de bits reduzida, os pixels devem ser combinados com uma operação OR booliana. Em uma transferência de bloco de bits alongada, os pixels devem ser replicados.

Retornar valor

O valor retornado será TRUE se a função for bem-sucedida. Caso contrário, será FALSE e um código de erro será registrado.

Comentários

DrvStretchBlt permite que o driver de dispositivo escreva em bitmaps GDI, especialmente quando o driver pode executar o halftoning. Essa função permite que o mesmo algoritmo de halftoning seja aplicado a bitmaps GDI e superfícies de dispositivo.

Essa função pode ser fornecida para lidar apenas com determinadas formas de alongamento, como por múltiplos inteiros. Se o driver tiver conectado a chamada e for solicitado a executar uma operação à qual não dá suporte, o driver deverá encaminhar os dados para EngStretchBlt para que a GDI manipule.

Se o driver quiser que o GDI manipule o halftoning e queira garantir o valor iMode adequado, o driver poderá conectar DrvStretchBlt, definir iMode como HALFTONE e chamar de volta para GDI com EngStretchBlt com o valor iMode definido.

DrvStretchBlt é opcional para drivers de exibição.