IDCompositionSurface：：BeginDraw 方法 (dcomp.h)

  • 项目

启动在此 Microsoft DirectComposition 图面对象上的绘图。 更新矩形必须位于图面的边界内;否则，此方法将失败。

语法

HRESULT BeginDraw(
  [in, optional] const RECT *updateRect,
  [in]           REFIID     iid,
  [out]          void       **updateObject,
  [out]          POINT      *updateOffset
);

参数

[in, optional] updateRect

类型： const RECT*

要更新的矩形。 如果此参数为 NULL，则更新整个位图。

[in] iid

类型： REFIID

要检索的接口的标识符。

[out] updateObject

类型： void**

接收 iid 参数中指定的类型的接口指针。 此参数不能为 NULL。

注意在 Windows 8 中，此参数为 surface。
 

[out] updateOffset

类型： POINT*

应用程序应在其中绘制更新内容的图面的偏移量。 此偏移量将引用更新矩形的左上角。

返回值

类型： HRESULT

如果函数成功，则返回S_OK。 否则，将返回 HRESULT 错误代码。

注解

此方法使应用程序能够以增量方式更新 DirectComposition 图面对象的内容。 应用程序必须使用以下顺序：

  1. 调用 BeginDraw 以启动增量更新。
  2. 使用检索到的图面作为呈现目标，并在检索到的偏移量处绘制更新的内容。
  3. 调用 IDCompositionSurface：：EndDraw 方法以完成更新。
此方法返回的更新对象是 Direct2D 设备上下文或 DXGI 图面，具体取决于 iid 参数的值以及 DirectComposition surface 对象的创建方式。 如果 iid 参数__uuidof (ID2D1DeviceContext) ，则返回的对象是已选择 DirectComposition 图面作为呈现目标的 Direct2D 设备上下文。 否则，它是一个 DXGI 表面，应用程序可以使用它作为呈现目标。 在任一情况下，返回的对象都与应用程序传递到 DCompositionCreateDevice2 函数或 IDCompositionDevice2：：CreateSurfaceFactory 方法的 Direct2D 或 DXGI 设备相关联。

如果 DirectComposition surface 对象是从 DirectComposition 设备或 Surface 工厂创建的（本身是使用关联的 Direct2D 设备创建的）创建的，则 iid 参数只能__uuidof (ID2D1DeviceContext) 。 具体而言，应用程序必须调用 DCompositionCreateDevice2 函数或 IDCompositionDevice2：：CreateSurfaceFactory 方法，并将 Direct2D 设备用作 renderingDevice 参数。 如果 DirectComposition 图面是通过未与 Direct2D 设备关联的 Surface 工厂创建的，或者如果它是通过 IDCompositionDevice2 接口直接创建的，并且设备未直接与 Direct2D 设备关联，则传递 __uuidof (ID2D1DeviceContext) ，因为 iid 参数会导致此方法返回E_INVALIDARG。

如果应用程序成功检索 Direct2D 设备上下文作为更新对象，则应用程序不应在返回的 Direct2D 设备上下文上调用 ID2D1DeviceContext：：BeginDraw 或 ID2D1DeviceContext：：EndDraw 方法。

检索到的偏移量不一定与请求的更新矩形的左上角相同。 应用程序必须转换其呈现基元，以在宽度和高度与输入矩形相同的矩形内绘制，但以给定的偏移量绘制。 应用程序不应在此矩形之外绘制。

如果 updateRectangle 参数为 NULL，则会更新整个图面。 在这种情况下，由于检索到的偏移量可能仍不能 (0,0) ，因此应用程序仍需要相应地转换其呈现基元。

如果图面不是虚拟表面，则应用程序首次为特定非虚拟表面调用此方法时，更新矩形必须覆盖整个表面，方法是在请求的更新矩形中指定完整表面，或者将 NULL 指定为 updateRectangle 参数。 对于虚拟图面，第一次调用可以是图面的任何子矩形。

由于每次调用此方法可能会检索 updateObject 图面中的不同对象，因此应用程序不应缓存检索到的 surface 指针。 应用程序应在完成绘图后立即释放检索到的指针。

检索到的图面矩形不包含位图的先前内容。 应用程序必须通过首先清除呈现目标或发出足够的呈现基元来完全覆盖更新矩形来更新矩形中的每个像素。 由于更新图面的初始内容未定义，因此未能更新每个像素会导致未定义的行为。

一次只能更新一个 DirectComposition 图面。 应用程序必须在一个图面上暂停绘图，然后才能开始或恢复在另一个图面上绘图。 如果应用程序针对同一图面或属于同一 DirectComposition 设备的另一个图面调用 BeginDraw 两次，但没有对 IDCompositionSurface：：EndDraw 进行干预调用，则第二次调用将失败。 如果应用程序调用 IDCompositionDevice2：：Commit 而不调用 EndDraw，则更新将保持挂起状态。 只有在应用程序调用 EndDraw ，然后调用 IDCompositionDevice2：：Commit 方法后，更新才会生效。

要求

要求 值
最低受支持的客户端 Windows 8 [仅限桌面应用]
最低受支持的服务器 Windows Server 2012 [仅限桌面应用]
目标平台 Windows
标头 dcomp.h
Library Dcomp.lib
DLL Dcomp.dll

另请参阅

IDCompositionSurface

IDCompositionSurface：：EndDraw