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 介面物件的建立方式而定。 如果 iid 參數__uuidof (ID2D1DeviceContext) ，則傳回的物件是已選取 DirectComposition 表面做為轉譯目標的 Direct2D 裝置內容。 否則，這是應用程式可用來作為轉譯目標的 DXGI 表面。 不論是哪一種情況，傳回的物件都與應用程式傳遞至 DCompositionCreateDevice2 函式或 IDCompositionDevice2：：CreateSurfaceFactory 方法的 Direct2D 或 DXGI 裝置相關聯。

如果 DirectComposition 介面對像是從 DirectComposition 裝置建立，或是使用相關聯 Direct2D 裝置建立的 Surface Factory 本身， iid 參數只能__uuidof (ID2D1DeviceContext) 。 特別是，應用程式必須呼叫 DCompositionCreateDevice2 函式或 IDCompositionDevice2：：CreateSurfaceFactory 方法，並將 Direct2D 裝置當做 renderingDevice 參數。 如果 DirectComposition 介面是透過未與 Direct2D 裝置相關聯的 Surface Factory 建立，或直接透過 IDCompositionDevice2 介面建立，且裝置未直接與 Direct2D 裝置相關聯，則傳遞 __uuidof (ID2D1DeviceContext) ，因為 iid 參數會導致此方法傳回E_INVALIDARG。

如果應用程式成功擷取 Direct2D 裝置內容做為更新物件，則應用程式不應該在傳回的 Direct2D 裝置內容上呼叫 ID2D1DeviceContext：：BeginDraw 或 ID2D1DeviceContext：：EndDraw 方法。

擷取的位移不一定與要求的更新矩形左上角相同。 應用程式必須轉換其呈現基本類型，以在與輸入矩形相同的寬度和高度的矩形內繪製，但在指定的位移中。 應用程式不應該在此矩形外部繪製。

如果 updateRectangle 參數為 NULL，則會更新整個介面。 在此情況下，由於擷取的位移可能尚未 (0,0) ，因此應用程式仍然需要據以轉換其轉譯基本類型。

如果介面不是虛擬表面，則應用程式第一次針對特定非虛擬表面呼叫此方法時，更新矩形必須透過在要求的更新矩形中指定完整表面，或將 NULL 指定為 updateRectangle 參數，來涵蓋整個表面。 對於虛擬表面，第一次呼叫可能是表面的任何子矩形。

因為每次呼叫這個方法可能會擷取 updateObject 介面中的不同物件，所以應用程式不應該快取所擷取的介面指標。 應用程式在完成繪圖時，應該立即釋放擷取的指標。

擷取的介面矩形不包含先前的點陣圖內容。 應用程式必須先清除轉譯目標，或發出足夠的轉譯基本類型，以完整涵蓋更新矩形，來更新矩形中的每個圖元。 因為未定義更新介面的初始內容，所以無法更新每個圖元會導致未定義的行為。

一次只能更新一個 DirectComposition 介面。 應用程式必須在一個介面上暫停繪圖，才能開始或繼續在另一個介面上繪製。 如果應用程式針對相同表面或屬於相同 DirectComposition 裝置的另一個表面呼叫 BeginDraw 兩次，而不需要對 IDCompositionSurface：：EndDraw 進行插播呼叫，第二次呼叫就會失敗。 如果應用程式呼叫 IDCompositionDevice2：：Commit 而不呼叫 EndDraw，則更新會保持擱置中。 更新只有在應用程式呼叫 EndDraw 之後才會生效，然後呼叫 IDCompositionDevice2：：Commit 方法。

規格需求

需求 值
最低支援的用戶端 Windows 8 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2012 [僅限傳統型應用程式]
目標平台 Windows
標頭 dcomp.h
程式庫 Dcomp.lib
Dll Dcomp.dll

另請參閱

IDCompositionSurface

IDCompositionSurface：：EndDraw