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，则视觉对象不低于同级，因此它呈现在其所有同级之上。

视觉对象参数指定的 视觉对象 不能是其他单个视觉对象的子级，也不能是与组合目标关联的可视化树的根。如果 视觉对象 已经是另一个视觉对象的子级， 则 AddVisual 将失败。在将子视觉对象添加到新父级的子级列表中之前，必须先从其上一个父级的子级列表中删除子视觉对象。如果 视觉对象 是可视化树的根，则必须在将视觉对象添加到新父级的子列表中之前，将其与该视觉对象树取消关联。若要取消视觉对象与可视化树的关联，请调用 IDCompositionTarget：：SetRoot 方法，并指定其他视觉对象或 NULL 作为 视觉对象 参数。

子视觉对象不需要由与其父级相同的 IDCompositionDevice 接口创建。当来自不同设备的视觉对象组合在同一个可视化树中时，Microsoft DirectComposition 将像平常一样组合树，不同之处在于，仅当对创建视觉对象的设备对象调用 IDCompositionDevice：：Commit 时，对特定视觉对象的更改才会生效。合并来自不同设备的视觉对象的功能使多个线程能够创建和操作单个可视化树，同时维护可用于异步提交更改的独立设备

如果 visual 或 referenceVisual 是无效指针，或者 referenceVisual 参数引用的视觉对象不是父视觉对象的子视觉对象，则此方法失败。这些接口不能是自定义实现;只有 DirectComposition 创建的接口才能与此方法一起使用。

示例

有关示例，请参阅如何生成简单的可视化树。

要求


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