drvBitBlt 函数 (winddi.h)

项目
08/27/2023

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 结构的指针，该结构定义位块传输的模式。 GDI 的 BRUSHOBJ_pvGetRbrush 服务可用于检索设备的画笔实现。如果 rop4 参数不需要模式，则忽略此参数。

[in, optional] pptlBrush

指向 POINTL 结构的指针，该结构定义目标图面中画笔的原点。画笔的左上角像素在此点对齐，画笔会根据其尺寸重复。如果 rop4 参数不需要模式，则忽略此参数。

[in] rop4

指定一个光栅操作，该操作定义如何将掩码、图案、源和目标像素组合在一起以写入目标图面。

这是一个四元光栅运算，它是三元 Rop3 运算的扩展。 Rop4 有 16 个相关位，类似于 Rop3 的 8 个定义位。实现 Rop4 的最简单方法是单独考虑其 2 个字节：低字节指定在掩码为 1 时应计算的 Rop3，高字节指定可在掩码为 0 时计算和应用的 Rop3。

返回值

如果位块传输操作成功，DrvBitBlt 将返回 TRUE 。否则，函数返回 FALSE，并记录错误代码。

注解

如果驱动程序挂钩 DrvBitBlt，GDI 将在需要执行 BitBlt 操作时调用此函数，其中一个图面是设备管理的表面。如果驱动程序实现不透明的设备托管位图，则必须挂钩 DrvBitBlt;否则，挂钩 DrvBitBlt 是可选的。如果驱动程序无法处理指定的调用，它可能会通过调用 EngBitBlt 将回调指向 DIB 引擎。

GDI 的 CLIPOBJXxx 服务允许将剪裁减少为一系列剪裁矩形。转换向量有助于调色板的颜色索引转换。

注意除非 ROP 指示需要参数指针，否则不要取消引用参数指针。例如，切勿不必要地取消引用 pbo-->iSolidColor ，因为对 ROP（如 BLACKNESS）这样做可能会导致访问冲突。 (此规则也适用于包含 MIX 参数的任何函数。)

如果驱动程序收到对此函数的调用，其中 rop4 参数设置为 0XCCAA，则驱动程序应将调用 EngBitBlt 进行打断，从而根据调用情况公开设备图面 () 。

有关光栅操作的详细信息，请参阅Microsoft Windows SDK文档。