IDCompositionVisual：：AddVisual 方法 (dcomp.h)

發行項
08/23/2023

將新的子視覺效果新增至這個視覺效果的子系列表。

語法

HRESULT AddVisual(
  [in]           IDCompositionVisual *visual,
  [in]           BOOL                insertAbove,
  [in, optional] IDCompositionVisual *referenceVisual
);

參數

[in] visual

類型： IDCompositionVisual*

要加入的子視覺效果。此參數不得為 Null。

[in] insertAbove

類型： BOOL

TRUE 是表示將新的子視覺效果放在 referenceVisual 參數所指定的視覺效果前面，或 FALSE 將它放在 referenceVisual後面。

[in, optional] referenceVisual

類型： IDCompositionVisual*

應該在其中加入新視覺效果的現有子視覺效果。

傳回值

類型： HRESULT

如果函式成功，它會傳回S_OK。否則，它會傳回 HRESULT 錯誤碼。如需錯誤碼的清單，請參閱 DirectComposition 錯誤碼。

備註

子視覺效果會排列在已排序的清單中。子視覺效果的內容會在 (或更新版本之前繪製，) 其父視覺效果的內容，但在 (或下方) 其子系的內容。

referenceVisual參數必須是父視覺效果的現有子系，或者必須是 Null。 insertAbove參數會指出新子系是否應該緊接在 Z 順序的參考視覺效果上方，或緊接在參考視覺效果下方。

如果 referenceVisual 參數為 Null，則會根據 insertAbove 參數的值，在父視覺效果的所有子系上方或下方轉譯指定的視覺效果。如果 insertAbove 為 TRUE，則新的子視覺效果高於無同層級，因此會轉譯為其所有同層級。相反地，如果 insertAbove 為 FALSE，則視覺效果不會低於同層級，因此會呈現在其所有同層級之上。

visual參數指定的視覺效果不能是單一其他視覺效果的子系，或與組合目標相關聯的視覺化樹狀結構根目錄。如果 視覺效果 已經是另一個視覺效果的子系， AddVisual 就會失敗。子視覺效果必須先從上一個父系的子系列表中移除，再將其新增至新父系的子系列表。如果 visual 是視覺化樹狀結構的根目錄，則視覺效果必須先與該視覺化樹狀結構解除關聯，再將它新增至新父系的子系列表。若要將視覺效果與視覺化樹狀結構分離，請呼叫 IDCompositionTarget：：SetRoot 方法，並將不同的視覺效果或 Null 指定為 視覺化 參數。

子視覺效果不需要由與其父系相同的 IDCompositionDevice 介面所建立。當不同裝置的視覺效果結合在同一個視覺化樹狀結構中時，Microsoft DirectComposition 會像平常一樣撰寫樹狀結構，不同之處在于，只有在建立視覺效果的裝置物件上呼叫 IDCompositionDevice：：Commit 時，才會生效。結合不同裝置視覺效果的能力可讓多個執行緒建立及操作單一視覺化樹狀結構，同時維護可用來非同步認可變更的獨立裝置

如果 visual 或 referenceVisual 是不正確指標，或者 referenceVisual 參數所參考的視覺效果不是父視覺效果的子系，這個方法就會失敗。這些介面不能是自訂實作;只有 DirectComposition 所建立的介面可以搭配這個方法使用。

範例

如需範例，請參閱如何建置簡單的視覺化樹狀結構。

需求


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