Функция DrvStretchBlt (winddi.h)

Статья
08/27/2023

Функция DrvStretchBlt обеспечивает растягивание возможностей передачи битовых блоков между любым сочетанием управляемых устройством и GDI поверхностей.

Синтаксис

BOOL DrvStretchBlt(
  [in, out]      SURFOBJ         *psoDest,
  [in, out]      SURFOBJ         *psoSrc,
  [in, optional] SURFOBJ         *psoMask,
  [in]           CLIPOBJ         *pco,
  [in, optional] XLATEOBJ        *pxlo,
  [in, optional] COLORADJUSTMENT *pca,
  [in]           POINTL          *pptlHTOrg,
  [in]           RECTL           *prclDest,
  [in]           RECTL           *prclSrc,
  [in, optional] POINTL          *pptlMask,
  [in]           ULONG           iMode
);

Параметры

[in, out] psoDest

Указатель на структуру SURFOBJ , которая определяет поверхность, на которой выполняется рисование.

[in, out] psoSrc

Указатель на структуру SURFOBJ, которая определяет источник для операции передачи битового блока.

[in, optional] psoMask

Необязательный указатель на структуру SURFOBJ, которая определяет поверхность, предоставляющую маску для источника. Маска определяется схемой логики, которая представляет собой точечный рисунок с 1 битом на пиксель.

Маска ограничивает область копируемых источников. Если этот параметр указан, он имеет неявный rop4 0xCCAA, что означает, что источник должен быть скопирован там, где маска равна 1, но назначение должно оставаться в покое, где маска равна нулю.

Если этот параметр имеет значение NULL, существует неявное значение rop4 0xCCCC, что означает, что источник должен быть скопирован везде в исходном прямоугольнике.

Маска всегда будет достаточно большой, чтобы содержать соответствующий источник; плитка не требуется.

[in] pco

Указатель на структуру CLIPOBJ , ограничивающую область, которая должна быть изменена в назначении. Службы GDI предоставляются для перечисления обрезной области в виде набора прямоугольников.

По возможности GDI упрощает обрезку. Однако, в отличие от DrvBitBlt, DrvStretchBlt можно вызывать с помощью одного прямоугольника обрезки. Это предотвращает ошибки округления при обрезке выходных данных.

[in, optional] pxlo

Указатель на структуру XLATEOBJ , указывающую способ преобразования цветовых индексов между исходной и целевой поверхностями. Если pxlo имеет значение NULL, преобразование не требуется.

Также можно запросить структуру XLATEOBJ, чтобы найти цвет RGB для любого исходного индекса. В некоторых случаях для интерполяции цветов потребуется высококачественная растягивающая передача битовых блоков.

[in, optional] pca

Указатель на структуру COLORADJUSTMENT, которая определяет значения настройки цвета, применяемые к исходному растровом рисунку перед растяжением битов. (См. документацию по Microsoft Windows SDK.)

[in] pptlHTOrg

Указатель на структуру POINTL , которая указывает источник полутоновой кисти. Драйверы устройств, использующие полутоновые кисти, должны выравнивать верхний левый пиксель шаблона кисти с этой точкой на поверхности устройства.

[in] prclDest

Указатель на структуру RECTL , которая определяет область для изменения в системе координат целевой поверхности. Этот прямоугольник определяется двумя точками, которые не обязательно хорошо упорядочены, то есть координаты второй точки не обязательно больше координат первой точки. Прямоугольник, который они описывают, не включает нижний и правый края. Эта функция никогда не вызывается с пустым прямоугольником назначения.

DrvStretchBlt должен заменить два значения x и (или) два значения y , если прямоугольник назначения не упорядочен.

[in] prclSrc

Указатель на структуру RECTL, которая определяет область, которая будет скопирована в систему координат исходной поверхности. Прямоугольник определяется двумя точками и сопоставляется с прямоугольником, определенным prclDest. Точки исходного прямоугольника хорошо упорядочены. Этой функции никогда не присваивается пустой исходный прямоугольник.

Сопоставление определяется prclSrc и prclDest. Точки, указанные в prclDest и prclSrc , находятся на целочисленных координатах, которые соответствуют пиксельным центрам. Прямоугольник, определенный двумя такими точками, считается геометрическим прямоугольником с двумя вершинами, координатами которых являются заданные точки, но с 0,5, вычитаемыми из каждой координаты. (Структуры POINTL следует рассматривать как сокращенную нотацию для указания этих вершин дробной координаты.)

Края любого прямоугольника никогда не пересекаются с пикселем, а обходят набор пикселей. Пиксели внутри прямоугольника являются ожидаемыми для "нижнего правого монопольного" прямоугольника. DrvStretchBlt сопоставит геометрический прямоугольник источника точно с прямоугольником геометрического назначения.

[in, optional] pptlMask

Указатель на структуру POINTL, которая указывает, какой пиксель в заданной маске соответствует верхнему левому пикселю в исходном прямоугольнике. Игнорируйте этот параметр, если маска не указана.

[in] iMode

Указывает, как объединяются исходные пиксели для получения выходных пикселей. Режим HALFTONE медленнее, чем в других режимах, но создает изображения более высокого качества.

Значение	Значение
BLACKONWHITE	При сжатии битового блока пиксели должны быть объединены с операцией BOOLEAN AND. При растягивая передача битового блока пиксели должны быть реплицированы.
COLORONCOLOR	При сжимающейся передаче битового блока следует игнорировать достаточное количество пикселей, чтобы не нужно было объединять пиксели. При растягивая передача битового блока пиксели должны быть реплицированы.
ПОЛУТОНАХ	Драйвер может использовать группы пикселей на выходной поверхности, чтобы наилучшим образом приблизить цвет или серый уровень входных данных.
WHITEONBLACK	При сжатой передаче битового блока пиксели должны объединяться с логической операцией OR. При растягивая передача битового блока пиксели должны быть реплицированы.

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

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

DrvStretchBlt позволяет драйверу устройства записывать данные в растровые изображения GDI, особенно если драйвер может выполнять полутонирование. Эта функция позволяет применять один и тот же алгоритм полутонирования к растровым изображениям GDI и поверхностям устройств.

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

Если драйвер хочет, чтобы GDI обрабатывал полутоны и хочет обеспечить правильное значение iMode , драйвер может подключить DrvStretchBlt, установить для iMode значение HALFTONE и вызвать GDI с помощью EngStretchBlt с заданным значением iMode .

DrvStretchBlt является необязательным для драйверов дисплея.