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

Статья
03/08/2023

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

Синтаксис

int StretchDIBits(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] int              DestWidth,
  [in] int              DestHeight,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] int              SrcWidth,
  [in] int              SrcHeight,
  [in] const VOID       *lpBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             iUsage,
  [in] DWORD            rop
);

Параметры

[in] hdc

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

[in] xDest

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

[in] yDest

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

[in] DestWidth

Ширина (в логических единицах) целевого прямоугольника.

[in] DestHeight

Высота (в логических единицах) целевого прямоугольника.

[in] xSrc

Координата X (в пикселях) исходного прямоугольника на изображении.

[in] ySrc

Координата Y (в пикселях) исходного прямоугольника на изображении.

[in] SrcWidth

Ширина исходного прямоугольника на изображении (в пикселях).

[in] SrcHeight

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

[in] lpBits

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

[in] lpbmi

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

[in] iUsage

Указывает, был ли предоставлен член bmiColors структуры BITMAPINFO и, если да, содержит ли bmiColors явные красные, зеленые, синие (RGB) значения или индексы. Параметр iUsage должен иметь одно из следующих значений.

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

Дополнительные сведения см. в разделе «Примечания».

[in] rop

Код растровой операции, указывающий способ объединения исходных пикселей, текущей кисти контекста конечного устройства и конечных пикселей для формирования нового изображения. Список некоторых распространенных кодов растровых операций см. в разделе BitBlt.

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

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

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

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

StretchDIBits создает зеркало изображение битового изображения, если признаки параметров nSrcWidth и nDestWidth или если параметры nSrcHeight и nDestHeight отличаются. Если nSrcWidth и nDestWidth имеют разные знаки, функция создает зеркало изображение растрового изображения вдоль оси X. Если nSrcHeight и nDestHeight имеют разные знаки, функция создает зеркало изображение растрового изображения вдоль оси Y.

StretchDIBits создает изображение сверху вниз, если знак элемента biHeight структуры BITMAPINFOHEADER для DIB является отрицательным. Пример кода см. в разделе Определение размера изображения JPEG или PNG.

Эта функция позволяет передавать изображения JPEG или PNG в качестве исходного изображения. Способ использования каждого параметра остается прежним, за исключением:

Если элемент biCompressionbitMAPINFOHEADER BI_JPEG или BI_PNG, lpBits указывает на буфер, содержащий изображение JPEG или PNG соответственно. Элемент biSizeImage структуры BITMAPINFOHEADER определяет размер буфера. Параметру iUsage необходимо задать значение DIB_RGB_COLORS. Параметру dwRop необходимо задать значение SRCCOPY.
Чтобы обеспечить правильное распуляние метафайлов во время печати, приложения должны вызвать escape-экранирование CHECKJPEGFORMAT или CHECKPNGFORMAT, чтобы убедиться, что принтер распознает изображение JPEG или PNG соответственно, прежде чем вызывать StretchDIBits.

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

Примеры

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

Требования

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