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

Статья
03/04/2024

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

Синтаксис

BOOL DrvBitBlt(
  [in, out]      SURFOBJ  *psoTrg,
  [in, optional] SURFOBJ  *psoSrc,
  [in, optional] SURFOBJ  *psoMask,
  [in]           CLIPOBJ  *pco,
  [in, optional] XLATEOBJ *pxlo,
  [in]           RECTL    *prclTrg,
  [in, optional] POINTL   *pptlSrc,
  [in, optional] POINTL   *pptlMask,
  [in, optional] BRUSHOBJ *pbo,
  [in, optional] POINTL   *pptlBrush,
  [in]           ROP4     rop4
);

Параметры

[in, out] psoTrg

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

[in, optional] psoSrc

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

[in, optional] psoMask

Указатель на структуру SURFOBJ, которая описывает поверхность, используемую в качестве маски для параметра rop4 . Маска представляет собой растровое изображение с 1 битом на пиксель. Как правило, маска используется для ограничения области, которую необходимо изменить в области назначения. Маскирование выбирается путем присвоения параметру rop4 значения 0xAACC. Область назначения не затрагивается, если маска 0x0000.

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

Если этот параметр имеет значение NULL и для параметра rop4 требуется маска, используется неявная маска в кисти.

[in] pco

Указатель на структуру CLIPOBJ , ограничивающую область для изменения. Предоставляются службы GDI (CLIPOBJXxx), которые перечисляют обрезную область в виде набора прямоугольников. По возможности GDI упрощает обрезку; Например, эта функция никогда не вызывается с одним прямоугольником обрезки. GDI обрезает прямоугольник назначения перед вызовом этой функции, делая дополнительную обрезку ненужной.

[in, optional] pxlo

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

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

Ситуация сложнее, когда, например, источником является RGB, но назначение управляется палитрой. В этом случае наиболее близкое совпадение с каждым исходным RGB-значением должно находиться в конечной палитре. Драйвер может вызвать службу XLATEOBJ_iXlate для выполнения этой операции.

При необходимости драйвер устройства может сопоставлять цвета, если целевая палитра является палитрой устройств по умолчанию.

[in] prclTrg

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

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

[in, optional] pptlSrc

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

[in, optional] pptlMask

Указатель на структуру POINTL, которая определяет, какой пиксель в маске соответствует верхнему левому углу исходного прямоугольника, если источник существует. Этот параметр игнорируется, если параметр psoMask имеет значение NULL.

[in, optional] pbo

Указатель на структуру BRUSHOBJ , которая определяет шаблон для передачи битовых блоков. Службу BRUSHOBJ_pvGetRbrush GDI можно использовать для получения реализации кисти устройства. Этот параметр игнорируется, если для параметра rop4 не требуется шаблон.

[in, optional] pptlBrush

Указатель на структуру POINTL , которая определяет источник кисти в области назначения. Верхний левый пиксель кисти выравнивается в этом месте, и кисть повторяется в соответствии с ее размерами. Этот параметр игнорируется, если для параметра rop4 не требуется шаблон.

[in] rop4

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

Это кватернарная растровая операция, которая является расширением тернарной операции Rop3. Rop4 имеет 16 соответствующих битов, которые аналогичны 8 определяющим битам Rop3. Самый простой способ реализации Rop4 — рассмотреть 2 байта отдельно: низкий байт указывает Rop3, который следует вычислить, если маска является одной, а высокий байт — Rop3, который можно вычислить и применить, если маска имеет значение 0.

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

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

Если драйвер перехватчики DrvBitBlt, GDI вызывает эту функцию, когда необходимо выполнить операцию BitBlt, где одна из поверхностей является поверхностью, управляемой устройством. Если драйвер реализует непрозрачные точечные изображения, управляемые устройством, он должен перехватывать DrvBitBlt; В противном случае подключение DrvBitBlt является необязательным. Если драйвер не может обработать указанный вызов, он может выполнить обратный вызов к подсистеме DIB, вызвав EngBitBlt.

Службы CLIPOBJXxx GDI позволяют сократить обрезку до ряда прямоугольников обрезки. Вектор перевода помогает в переводе цветовых индексов для палитр.

Примечание Не разыменовывайте указатели параметров, если в ROP не указано, что они необходимы. Например, никогда не разыменуйте pbo-->iSolidColor , так как это для ROP, такого как BLACKNESS, может привести к нарушению доступа. (Это правило также применяется к любой функции, которая включает параметр MIX.)

Если драйвер получает вызов этой функции, в котором параметру rop4 задано значение 0XCCAA, драйвер должен преобразовывать вызов в EngBitBlt, предоставляя поверхности устройства соответствующим образом для вызова.

Дополнительные сведения о растровых операциях см. в документации по Microsoft Windows SDK.