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

Статья
08/27/2023

Функция CreateDIBSection создает DIB, в который приложения могут выполнять запись напрямую. Функция предоставляет указатель на расположение битовых значений растрового изображения. Вы можете предоставить дескриптор объекту сопоставления файлов, который функция будет использовать для создания растрового изображения, или позволить системе выделить память для растрового изображения.

Синтаксис

HBITMAP CreateDIBSection(
  [in]  HDC              hdc,
  [in]  const BITMAPINFO *pbmi,
  [in]  UINT             usage,
  [out] VOID             **ppvBits,
  [in]  HANDLE           hSection,
  [in]  DWORD            offset
);

Параметры

[in] hdc

Дескриптор для контекста устройства. Если значение iUsage равно DIB_PAL_COLORS, функция использует логическую палитру этого контекста устройства для инициализации цветов DIB.

[in] pbmi

Указатель на структуру BITMAPINFO , которая задает различные атрибуты DIB, включая размеры и цвета растрового изображения.

[in] usage

Тип данных, содержащихся в элементе массива bmiColors структуры BITMAPINFO , на которую указывает pbmi (индексы логической палитры или литеральные значения RGB). Определены следующие значения.

Значение	Значение
DIB_PAL_COLORS	Элемент bmiColors представляет собой массив 16-разрядных индексов в логической палитре контекста устройства, указанного в hdc.
DIB_RGB_COLORS	Структура BITMAPINFO содержит массив литеральных значений RGB.

[out] ppvBits

Указатель на переменную, которая получает указатель на расположение битовых значений DIB.

[in] hSection

Дескриптор объекта сопоставления файлов, который функция будет использовать для создания DIB. Этот параметр может принимать значение NULL.

Если hSection не равно NULL, это должен быть дескриптор объекта сопоставления файлов, созданного путем вызова функции CreateFileMapping с флагом PAGE_READWRITE или PAGE_WRITECOPY. Разделы DIB, доступные только для чтения, не поддерживаются. Дескрипторы, созданные другими средствами, приведут к сбою CreateDIBSection .

Если hSection не равно NULL, функция CreateDIBSection находит битовые значения растрового изображения в смещении dwOffset в объекте сопоставления файлов, на который ссылается hSection. Позже приложение может получить дескриптор hSection , вызвав функцию GetObject с HBITMAP , возвращенным CreateDIBSection.

Если hSection имеет значение NULL, система выделяет память для DIB. В этом случае функция CreateDIBSection игнорирует параметр dwOffset . Приложение не может позже получить дескриптор для этой памяти. Элемент dshSection структуры DIBSECTION , заполненный вызовом функции GetObject , будет иметь значение NULL.

[in] offset

Смещение от начала объекта сопоставления файлов, на который ссылается hSection , где начинается хранение битовых значений растрового изображения. Это значение игнорируется, если hSection имеет значение NULL. Битовые значения растрового изображения выравниваются по границам двойных слов, поэтому dwOffset должен быть кратным размеру DWORD.

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

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

Если функция завершается сбоем, возвращаемое значение равно NULL, а *ppvBits — NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

GetLastError может возвращать следующее значение:

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

Как отмечалось выше, если hSection имеет значение NULL, система выделяет память для DIB. Система закрывает дескриптор в этой памяти при последующем удалении DIB путем вызова функции DeleteObject . Если значение hSection не равно NULL, необходимо закрыть дескриптор памяти hSection самостоятельно после вызова DeleteObject , чтобы удалить растровое изображение.

Невозможно вставить раздел DIB из одного приложения в другое приложение.

CreateDIBSection не использует параметры BITMAPINFOHEADERbiXPelsPerMeter или biYPelsPerMeter и не предоставляет сведения о разрешении в структуре BITMAPINFO .

Необходимо гарантировать, что подсистема GDI выполнила рисование на точечный рисунок, созданный с помощью CreateDIBSection , прежде чем выполнять рисование на растровом рисунке самостоятельно. Доступ к точечным рисункам должен быть синхронизирован. Для этого вызовите функцию GdiFlush . Это относится к любому использованию указателя на битовые значения растрового изображения, включая передачу указателя в вызовах таких функций, как SetDIBits.

ICM: Управление цветом не выполняется.

Требования

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