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

Статья
03/08/2023

Функция GetDIBits извлекает биты указанного совместимого растрового изображения и копирует их в буфер в виде DIB с использованием указанного формата.

Синтаксис

int GetDIBits(
  [in]      HDC          hdc,
  [in]      HBITMAP      hbm,
  [in]      UINT         start,
  [in]      UINT         cLines,
  [out]     LPVOID       lpvBits,
  [in, out] LPBITMAPINFO lpbmi,
  [in]      UINT         usage
);

Параметры

[in] hdc

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

[in] hbm

Дескриптор растрового изображения. Это должно быть совместимое растровое изображение (DDB).

[in] start

Первая извлекаемая строка сканирования.

[in] cLines

Количество извлекаемых строк сканирования.

[out] lpvBits

Указатель на буфер для получения данных растрового изображения. Если этот параметр имеет значение NULL, функция передает размеры и формат растрового изображения в структуру BITMAPINFO , на которую указывает параметр lpbmi .

[in, out] lpbmi

Указатель на структуру BITMAPINFO , которая задает требуемый формат для данных DIB.

[in] usage

Формат элемента bmiColors структуры BITMAPINFO . Это должно быть одно из следующих значений.

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

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

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

Если параметр lpvBits имеет значение NULL и GetDIBits успешно заполняет структуру BITMAPINFO , возвращаемое значение не равно нулю.

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

Эта функция может возвращать следующее значение.

Код возврата	Описание
ERROR_INVALID_PARAMETER	Один или несколько входных параметров недопустимы.

Если запрошенный формат для DIB соответствует внутреннему формату, то копируются значения RGB для растрового изображения. Если запрошенный формат не соответствует внутреннему формату, синтезируется таблица цветов. В следующей таблице описана таблица цветов, синтезируемая для каждого формата.

Значение	Значение
1_BPP	Таблица цветов состоит из черной и белой записей.
4_BPP	Таблица цветов состоит из сочетания цветов, идентичных стандартной палитре VGA.
8_BPP	Таблица цветов состоит из общего сочетания из 256 цветов, определенных GDI. (В эти 256 цветов входят 20 цветов, которые находятся в логической палитре по умолчанию.)
24_BPP	Таблица цветов не возвращается.

Если параметр lpvBits является допустимым указателем, необходимо инициализировать первые шесть элементов структуры BITMAPINFOHEADER , чтобы указать размер и формат DIB. Линии сканирования должны быть выровнены по DWORD , за исключением точечных изображений, сжатых RLE.

DiB снизу вверх задается путем установки положительного числа высоты, в то время как dib сверху вниз — путем установки отрицательного числа высоты. Таблица цветов точечных рисунков будет добавлена в структуру BITMAPINFO .

Если lpvBits имеет значение NULL, GetDIBits проверяет первый элемент первой структуры, на которую указывает lpbi. Этот элемент должен указывать размер структуры BITMAPCOREHEADER или BITMAPINFOHEADER в байтах. Функция использует указанный размер для определения способа инициализации остальных элементов.

Если параметр lpvBits имеет значение NULL и элемент bit count в BITMAPINFO инициализирован нулевым значением, GetDIBits заполняет структуру BITMAPINFOHEADER или BITMAPCOREHEADER без таблицы цветов. Этот метод можно использовать для запроса атрибутов растрового изображения.

Растровое изображение, определяемое параметром hbmp , не должно быть выбрано в контексте устройства, когда приложение вызывает эту функцию.

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

Примеры

Пример см. в разделе Запись изображения.

Требования


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