Função SetDIBitsToDevice (wingdi.h)

Artigo
03/08/2023

A função SetDIBitsToDevice define os pixels no retângulo especificado no dispositivo associado ao contexto do dispositivo de destino usando dados de cor de uma imagem DIB, JPEG ou PNG.

Sintaxe

int SetDIBitsToDevice(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] DWORD            w,
  [in] DWORD            h,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] UINT             StartScan,
  [in] UINT             cLines,
  [in] const VOID       *lpvBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             ColorUse
);

Parâmetros

[in] hdc

Um identificador para o contexto do dispositivo.

[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] w

A largura, em unidades lógicas, da imagem.

[in] h

A altura, em unidades lógicas, da imagem.

[in] xSrc

A coordenada x, em unidades lógicas, do canto inferior esquerdo da imagem.

[in] ySrc

A coordenada y, em unidades lógicas, do canto inferior esquerdo da imagem.

[in] StartScan

A linha de verificação inicial na imagem.

[in] cLines

O número de linhas de verificação DIB contidas na matriz apontada pelo parâmetro lpvBits .

[in] lpvBits

Um ponteiro para os dados de cor armazenados como uma matriz de bytes. Para obter mais informações, consulte a seção Comentários a seguir.

[in] lpbmi

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

[in] ColorUse

Indica se o membro bmiColors da estrutura BITMAPINFO contém valores ou índices vermelhos, verdes, azuis (RGB) explícitos em uma paleta. Para obter mais informações, consulte a seção Comentários a seguir.

O parâmetro fuColorUse deve ser um dos valores a seguir.

Valor	Significado
DIB_PAL_COLORS	A tabela de cores consiste em uma matriz de índices de 16 bits na paleta lógica selecionada no momento.
DIB_RGB_COLORS	A tabela de cores contém valores RGB literais.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o número de linhas de verificação definidas.

Se nenhuma linha de verificação for definida (como quando dwHeight for 0) ou a função falhar, a função retornará zero.

Se o driver não puder dar suporte à imagem de arquivo JPEG ou PNG passada para SetDIBitsToDevice, 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 SetDIBitsToDevice.

Comentários

A velocidade ideal de desenho de bitmap é obtida quando os bits de bitmap são índices na paleta do sistema.

Os aplicativos podem recuperar as cores e índices da paleta do sistema chamando a função GetSystemPaletteEntries . Depois que as cores e índices forem recuperados, o aplicativo poderá criar o DIB. Para obter mais informações sobre a paleta do sistema, consulte Cores.

As linhas de verificação devem ser alinhadas em um DWORD , exceto para bitmaps compactados por RLE.

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

Para reduzir a quantidade de memória necessária para definir bits de um DIB grande em uma superfície de dispositivo, um aplicativo pode agrupar a saída chamando repetidamente SetDIBitsToDevice, colocando uma parte diferente do bitmap na matriz lpvBits a cada vez. Os valores dos parâmetros uStartScan e cScanLines identificam a parte do bitmap contido na matriz lpvBits .

A função SetDIBitsToDevice retornará um erro se for chamada por um processo em execução em segundo plano enquanto uma sessão MS-DOS de tela inteira é executada em primeiro plano.

Se o membro biCompression de BITMAPINFOHEADER for BI_JPEG ou BI_PNG, lpvBits apontará para um buffer que contém uma imagem JPEG ou PNG. O membro biSizeImage de especifica o tamanho do buffer. O parâmetro fuColorUse deve ser definido como DIB_RGB_COLORS.
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 SetDIBitsToDevice.

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 lpbmi tiver um BITMAPV4HEADER que especifica os membros gama e de pontos de extremidade, ou um BITMAPV5HEADER que especifica os membros gama e 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 Testando uma impressora para suporte a 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