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
라이브러리	Dcomp.lib
DLL	Dcomp.dll