Функция SetDIBitsToDevice (wingdi.h)

Статья
03/04/2024

Функция SetDIBitsToDevice задает пиксели в указанном прямоугольнике на устройстве, связанном с контекстом целевого устройства, с помощью цветовых данных из изображения DIB, JPEG или PNG.

Синтаксис

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
);

Параметры

[in] hdc

Дескриптор контекста устройства.

[in] xDest

Координата X в логических единицах верхнего левого угла прямоугольника назначения.

[in] yDest

Координата Y в логических единицах верхнего левого угла прямоугольника назначения.

[in] w

Ширина изображения в логических единицах.

[in] h

Высота изображения в логических единицах.

[in] xSrc

Координата X в логических единицах левого нижнего угла изображения.

[in] ySrc

Координата Y в логических единицах нижнего левого угла изображения.

[in] StartScan

Начальная строка сканирования на изображении.

[in] cLines

Количество строк сканирования DIB, содержащихся в массиве, на который указывает параметр lpvBits .

[in] lpvBits

Указатель на данные цвета, хранящиеся в виде массива байтов. Дополнительные сведения см. в разделе "Примечания".

[in] lpbmi

Указатель на структуру BITMAPINFO , содержащую сведения о DIB.

[in] ColorUse

Указывает, содержит ли элемент bmiColors структуры BITMAPINFO явные красные, зеленые, синие (RGB) значения или индексы в палитре. Дополнительные сведения см. в разделе "Примечания".

Параметр fuColorUse должен иметь одно из следующих значений.

Значение	Значение
DIB_PAL_COLORS	Таблица цветов состоит из массива 16-разрядных индексов в выбранной логической палитре.
DIB_RGB_COLORS	Таблица цветов содержит литеральные значения RGB.

Возвращаемое значение

Если функция выполняется успешно, возвращаемым значением будет количество заданных строк сканирования.

Если заданы нулевые строки сканирования (например, если значение dwHeight равно 0) или функция завершается сбоем, функция возвращает ноль.

Если драйвер не поддерживает изображение файла JPEG или PNG, переданное в SetDIBitsToDevice, функция завершится ошибкой и возвратит GDI_ERROR. В случае сбоя приложение должно использовать собственную поддержку JPEG или PNG, чтобы распаковывать изображение в растровое изображение, а затем передать его в SetDIBitsToDevice.

Приложения могут получать цвета и индексы системной палитры, вызывая функцию GetSystemPaletteEntries . После получения цветов и индексов приложение может создать DIB. Дополнительные сведения о системной палитре см. в разделе Цвета.

Линии сканирования должны быть выровнены по DWORD , за исключением растровых изображений, сжатых RLE.

Источником снизу вверх DIB является левый нижний угол растрового изображения; источником dib сверху вниз является левый верхний угол.

Чтобы уменьшить объем памяти, необходимый для задания битов из большого DIB на поверхности устройства, приложение может группировать выходные данные, многократно вызывая SetDIBitsToDevice, каждый раз помещая другую часть растрового изображения в массив lpvBits . Значения параметров uStartScan и cScanLines определяют часть растрового изображения, содержащегося в массиве lpvBits .

Функция SetDIBitsToDevice возвращает ошибку, если она вызывается процессом, выполняющимся в фоновом режиме, а полноэкранный сеанс MS-DOS выполняется на переднем плане.

Если элемент biCompressionbitMAPINFOHEADER BI_JPEG или BI_PNG, lpvBits указывает на буфер, содержащий изображение JPEG или PNG. Элемент biSizeImage указывает размер буфера. Параметр fuColorUse должен иметь значение DIB_RGB_COLORS.
Чтобы обеспечить правильную очередь метафайлов во время печати, приложения должны вызывать escape-экранирование CHECKJPEGFORMAT или CHECKPNGFORMAT, чтобы убедиться, что принтер распознает изображение JPEG или PNG, соответственно, перед вызовом SetDIBitsToDevice.

ICM: Управление цветом выполняется, если управление цветом было включено с помощью вызова SetICMMode с параметром iEnableICM , для которого задано значение ICM_ON. Если растровое изображение, заданное lpbmi , имеет BITMAPV4HEADER , указывающий элементы гамма-и конечных точек, или BITMAPV5HEADER , в котором указываются элементы гамма- и конечных точек или элементы profileData и profileSize, то вызов обрабатывает пиксели растрового изображения как выраженные в цветовом пространстве, описанном этими элементами, а не в исходном цветовом пространстве контекста устройства.

Примеры

Пример см. в разделе Тестирование принтера для поддержки JPEG или PNG.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	wingdi.h (включая Windows.h)
Библиотека	Gdi32.lib
DLL	Gdi32.dll