Função StretchBlt (wingdi.h)

Artigo
03/04/2024

A função StretchBlt copia um bitmap de um retângulo de origem em um retângulo de destino, alongando ou compactando o bitmap para ajustar as dimensões do retângulo de destino, se necessário. O sistema alonga ou compacta o bitmap de acordo com o modo de alongamento definido atualmente no contexto do dispositivo de destino.

Sintaxe

BOOL StretchBlt(
  [in] HDC   hdcDest,
  [in] int   xDest,
  [in] int   yDest,
  [in] int   wDest,
  [in] int   hDest,
  [in] HDC   hdcSrc,
  [in] int   xSrc,
  [in] int   ySrc,
  [in] int   wSrc,
  [in] int   hSrc,
  [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] wDest

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

[in] hDest

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

[in] hdcSrc

Um identificador para o contexto do dispositivo de origem.

[in] xSrc

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

[in] ySrc

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

[in] wSrc

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

[in] hSrc

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

[in] rop

A operação de varredura a ser executada. Os códigos de operação de varredura definem como o sistema combina cores em operações de saída que envolvem um pincel, um bitmap de origem e um bitmap de destino.

Consulte BitBlt para obter uma lista de ROPs (códigos de operação de varredura comuns). 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

StretchBlt alonga ou compacta o bitmap de origem na memória e copia o resultado para o retângulo de destino. Esse bitmap pode ser um DDB (bitmap) compatível ou a saída de CreateDIBSection. Os dados de cor para pixels de padrão ou de destino são mesclados após a ocorrência do alongamento ou compactação.

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.

Se a operação de varredura especificada exigir um pincel, o sistema usará o pincel atualmente selecionado no contexto do dispositivo de destino.

As coordenadas de destino são transformadas usando a transformação especificada atualmente para o contexto do dispositivo de destino; as coordenadas de origem são transformadas usando a transformação especificada atualmente para o contexto do dispositivo de origem.

Se a transformação de origem tiver uma rotação ou uma tesoura, ocorrerá um erro.

Se os bitmaps de destino, origem e padrão não tiverem o mesmo formato de cor, o StretchBlt converterá os bitmaps de origem e padrão para corresponder ao bitmap de destino.

Se StretchBlt precisar converter um bitmap monocromático em um bitmap de cor, ele definirá bits brancos (1) para a cor da tela de fundo e os bits pretos (0) para a cor de primeiro plano. Para converter um bitmap de cor em um bitmap monocromático, ele define pixels que correspondem à cor da tela de fundo como branco (1) e define todos os outros pixels como preto (0). As cores do primeiro plano e do plano de fundo do contexto do dispositivo com cor são usadas.

O StretchBlt criará uma imagem espelho de um bitmap se os sinais dos parâmetros nWidthSrc e nWidthDest ou se os parâmetros nHeightSrc e nHeightDest forem diferentes. Se nWidthSrc e nWidthDest tiverem sinais diferentes, a função criará uma imagem espelho do bitmap ao longo do eixo x. Se nHeightSrc e nHeightDest tiverem sinais diferentes, a função criará uma imagem espelho do bitmap ao longo do eixo y.

Nem todos os dispositivos dão suporte à função StretchBlt . Para obter mais informações, consulte GetDeviceCaps.

ICM: Nenhum gerenciamento de cores é executado quando ocorre uma operação blit.

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 em um DIB chamando GetDIBits. Para exibir o DIB para o segundo dispositivo, chame SetDIBits ou StretchDIBits.

Exemplos

Para obter um exemplo, consulte Dimensionando 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