Função StretchDIBits (wingdi.h)

Artigo
03/08/2023

A função StretchDIBits copia os dados de cor de um retângulo de pixels em uma imagem DIB, JPEG ou PNG para o retângulo de destino especificado. Se o retângulo de destino for maior que o retângulo de origem, essa função alonga as linhas e colunas de dados de cor para se ajustar ao retângulo de destino. Se o retângulo de destino for menor que o retângulo de origem, essa função compacta as linhas e colunas usando a operação de varredura especificada.

Sintaxe

int StretchDIBits(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] int              DestWidth,
  [in] int              DestHeight,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] int              SrcWidth,
  [in] int              SrcHeight,
  [in] const VOID       *lpBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             iUsage,
  [in] DWORD            rop
);

Parâmetros

[in] hdc

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] DestWidth

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

[in] DestHeight

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

[in] xSrc

A coordenada x, em pixels, do retângulo de origem na imagem.

[in] ySrc

A coordenada y, em pixels, do retângulo de origem na imagem.

[in] SrcWidth

A largura, em pixels, do retângulo de origem na imagem.

[in] SrcHeight

A altura, em pixels, do retângulo de origem na imagem.

[in] lpBits

Um ponteiro para os bits de imagem, que são armazenados como uma matriz de bytes. Para obter mais informações, consulte a seção Comentários.

[in] lpbmi

Um ponteiro para uma estrutura BITMAPINFO que contém informações sobre o DIB.

[in] iUsage

Especifica se o membro bmiColors da estrutura BITMAPINFO foi fornecido e, nesse caso, se bmiColors contém valores ou índices vermelhos, verdes, azuis explícitos (RGB). O parâmetro iUsage deve ser um dos valores a seguir.

Valor	Significado
DIB_PAL_COLORS	A matriz contém índices de 16 bits na paleta lógica do contexto do dispositivo de origem.
DIB_RGB_COLORS	A tabela de cores contém valores RGB literais.

Para obter mais informações, consulte a seção Comentários.

[in] rop

Um código de operação de varredura que especifica como os pixels de origem, o pincel atual do contexto do dispositivo de destino e os pixels de destino devem ser combinados para formar a nova imagem. Para obter uma lista de alguns códigos de operação de varredura comuns, consulte BitBlt.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o número de linhas de verificação copiadas. Observe que esse valor pode ser negativo para conteúdo espelhado.

Se a função falhar ou nenhuma linha de verificação for copiada, o valor retornado será 0.

Se o driver não puder dar suporte à imagem de arquivo JPEG ou PNG passada para StretchDIBits, a função falhará e retornará GDI_ERROR. Se ocorrer falha, o aplicativo deverá fazer fallback em seu próprio suporte a JPEG ou PNG para descompactar a imagem em um bitmap e, em seguida, passar o bitmap para StretchDIBits.

Comentários

A origem de um DIB de baixo para cima é o canto inferior esquerdo; a origem de um DIB de cima para baixo é o canto superior esquerdo.

StretchDIBits cria uma imagem espelho de um bitmap se os sinais dos parâmetros nSrcWidth e nDestWidth ou se os parâmetros nSrcHeight e nDestHeight forem diferentes. Se nSrcWidth e nDestWidth tiverem sinais diferentes, a função criará uma imagem espelho do bitmap ao longo do eixo x. Se nSrcHeight e nDestHeight tiverem sinais diferentes, a função criará uma imagem espelho do bitmap ao longo do eixo y.

StretchDIBits criará uma imagem de cima para baixo se o sinal do membro biHeight da estrutura BITMAPINFOHEADER para o DIB for negativo. Para obter um exemplo de código, consulte Dimensionando uma imagem JPEG ou PNG.

Essa função permite que uma imagem JPEG ou PNG seja passada como a imagem de origem. Como cada parâmetro é usado permanece o mesmo, exceto:

Se o membro biCompression de BITMAPINFOHEADER for BI_JPEG ou BI_PNG, lpBits apontará para um buffer que contém uma imagem JPEG ou PNG, respectivamente. O membro biSizeImage da estrutura BITMAPINFOHEADER especifica o tamanho do buffer. O parâmetro iUsage deve ser definido como DIB_RGB_COLORS. O parâmetro dwRop deve ser definido como SRCCOPY.
Para garantir o spool de meta-arquivo adequado durante a impressão, os aplicativos devem chamar o escape CHECKJPEGFORMAT ou CHECKPNGFORMAT para verificar se a impressora reconhece a imagem JPEG ou PNG, respectivamente, antes de chamar StretchDIBits.

ICM: O gerenciamento de cores será executado se o gerenciamento de cores tiver sido habilitado com uma chamada para SetICMMode com o parâmetro iEnableICM definido como ICM_ON. Se o bitmap especificado por lpBitsInfo tiver um BITMAPV4HEADER que especifica os membros gama e de pontos de extremidade, ou um BITMAPV5HEADER que especifica os membros gama e de pontos de extremidade ou os membros profileData e profileSize, a chamada tratará os pixels do bitmap como sendo expressos no espaço de cores descrito por esses membros, em vez de no espaço de cor de origem do contexto do dispositivo.

Exemplos

Para obter um exemplo, consulte Dimensionamento de uma imagem JPEG ou PNG.

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