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

Статья
03/08/2023

Функция CreateBitmap создает растровое изображение с указанной шириной, высотой и цветовым форматом (цветовые плоскости и биты на пиксель).

Синтаксис

HBITMAP CreateBitmap(
  [in] int        nWidth,
  [in] int        nHeight,
  [in] UINT       nPlanes,
  [in] UINT       nBitCount,
  [in] const VOID *lpBits
);

Параметры

[in] nWidth

Ширина растрового изображения в пикселях.

[in] nHeight

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

[in] nPlanes

Количество цветовых плоскостей, используемых устройством.

[in] nBitCount

Количество битов, необходимых для идентификации цвета одного пикселя.

[in] lpBits

Указатель на массив цветовых данных, используемый для задания цветов в прямоугольнике пикселей. Каждая строка сканирования в прямоугольнике должна быть выровнена по словам (строки сканирования, которые не выровнены по словам, должны быть заполнены нулями). Ожидаемый размер буфера ( cj) можно вычислить с помощью формулы:

cj = (((nWidth * nPlanes * nBitCount + 15) >> 4) << 1) * nHeight;

Если этот параметр имеет значение NULL, содержимое нового растрового изображения не определено.

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

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

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

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

Код возврата	Описание
ERROR_INVALID_BITMAP	Вычисляемый размер растрового изображения меньше нуля.

После создания растрового изображения его можно выбрать в контексте устройства, вызвав функцию SelectObject . Однако растровое изображение можно выбрать в контексте устройства, только если растровое изображение и контроллер домена имеют одинаковый формат.

Функцию CreateBitmap можно использовать для создания цветных растровых изображений. Однако для повышения производительности приложения должны использовать CreateBitmap для создания монохромных растровых изображений и CreateCompatibleBitmap для создания цветных растровых изображений. Всякий раз, когда цветовое растровое изображение, возвращаемое из CreateBitmap , выбирается в контексте устройства, система проверяет, соответствует ли растровое изображение формату контекста устройства, в который он выбирается. Так как CreateCompatibleBitmap принимает контекст устройства, он возвращает растровое изображение, формат которого совпадает с заданным контекстом устройства. Таким образом, последующие вызовы SelectObject выполняются быстрее с цветным растровым изображением из CreateCompatibleBitmap , чем с цветным растровым изображением, возвращенным из CreateBitmap.

Если растровое изображение является монохромным, нули представляют цвет переднего плана, а другие — цвет фона для контекста целевого устройства.

Если приложение задает для параметров nWidth или nHeight нулевое значение, CreateBitmap возвращает дескриптор монохромного растрового изображения 1 на 1 пикселя.

Если растровое изображение больше не требуется, вызовите функцию DeleteObject , чтобы удалить его.

Требования


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