XR_EXT_spatial_container

이름 문자열

XR_EXT_spatial_container

확장 프로그램 유형

인스턴스 확장 프로그램

등록된 내선 번호

811

버전

1

승인 상태

비준되지 않음

확장 프로그램 및 버전 종속 항목

OpenXR 1.0

최종 수정일

2026-08-06

IP 상태

알려진 IP 소유권 주장이 없습니다.

도움을 주신 분들

Jared Finder, Google
Andreas Loeve Selvik, Meta Platforms
Lachlan Ford, Google
Cass Everitt, Meta Platforms
Adam Gousetis, Meta Platforms
Ankur Agrawal, Unity Technologies
Bjorn Swenson, LÖVR
Denny Rönngren, Varjo Technologies
Fredia Huya-Kouadio, Godot Engine
Guodong Rong, Meta Platforms
Jakob Bornecrantz, NVIDIA
Jian Zhang, ByteDance
John Kearney, Meta Platforms
Jonathan Wright, Meta Platforms
Junfeng She, ByteDance
Kenny Vercaemer, Google
Kurtis Eveleigh, Qualcomm
Mauricio Narvaez, Meta Platforms
Nathan Nuber, Valve Corporation
Nihav Jain, Google
Nikita Lutsenko, Meta Platforms
Praveen Babu J D, ByteDance
Rylie Pavlik, Collabora
Salar Khan, Google
Shuai Liu, ByteDance
Walter Luh, Meta Platforms
Yin Li, Microsoft
Zhipeng Liu, ByteDance

개요

이 확장 프로그램은 데스크톱 2D 윈도잉 시스템의 '창' 개념과 유사한 '공간 컨테이너'라는 새로운 표시 가능한 항목 클래스를 정의합니다.

OpenXR 1.x에서 앱은 사용자에게 표시되는 모든 항목과 이러한 항목이 사용자의 실제 또는 가상 환경 위에 혼합되는 방식을 독점적으로 제어합니다. 런타임은 사용자 안전을 위해 표시되는 내용을 약간만 수정합니다. 이 앱 모델은 사용자를 단일 환경에 몰입시키는 데는 좋지만 여러 동시 환경으로 확장되지는 않습니다. 특히 AR 및 혼합 현실 환경에서는 사용자가 여러 앱을 동시에 경험하고 싶어 하는 경우가 많습니다.

공간 컨테이너는 3D로 확장된 창과 같습니다. 사용자는 여러 공간 컨테이너를 동시에 볼 수 있으며 그중 일부에 입력을 제공합니다. 표시되는 공간 컨테이너는 서로 다른 앱에 속할 수 있으며 런타임은 사용자를 대신하여 크기와 배치를 관리합니다.

이 확장 프로그램은 기존의 몰입형 OpenXR 환경 외에도 공간적으로 제한된 새로운 유형의 환경을 지원합니다. 제한된 OpenXR 환경은 약간의 3D 콘텐츠 (깊이 오프셋이 작은 평면 패널) 또는 완전한 3D 콘텐츠를 호스팅하는 볼륨을 가질 수 있습니다. 몰입형 OpenXR 환경은 OpenXR 1.0부터 지원되는 기존의 전체 화면 몰입형 앱입니다. 앱은 원하는 경우 두 가지 유형의 콘텐츠 간에 전환할 수 있습니다.

이 확장 프로그램은 앱이 콘텐츠를 렌더링하는 메서드를 정의하지 않습니다. 콘텐츠를 그리는 방법은 다른 확장 프로그램(XR_EXT_spatial_container_self_rendering)에 정의되어 있습니다. .

공간 컨테이너 사용

XrSpatialContainerEXT는 공간 컨테이너를 나타내는 핸들입니다.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

애플리케이션은 다음 단계에 따라 공간 컨테이너를 통해 렌더링을 시작합니다.

  1. xrCreateSpatialContainerEXT를 사용하여 공간 컨테이너를 만듭니다.
  2. 초기 표시를 위해 컨테이너의 상태(예: 경계 모드)를 수정합니다.
  3. xrRequestSpatialContainerVisibleEXT를 사용하여 런타임에 컨테이너를 표시하도록 요청합니다.
  4. 런타임이 컨테이너를 표시할 준비가 될 때까지 기다립니다. 런타임이 준비되면 visible가 XR_TRUE로 설정된 XrEventDataSpatialContainerVisibleChangedEXT 이벤트를 큐에 추가합니다.
  5. 공간 컨테이너의 렌더링을 시작합니다.

공간 컨테이너를 해제하는 방법은 다음과 같습니다.

  1. xrRequestSpatialContainerVisibleEXT를 사용하여 런타임에 컨테이너를 숨기도록 요청합니다.
  2. 런타임이 컨테이너 숨기기를 완료할 때까지 기다립니다. 런타임이 컨테이너를 완전히 숨기면 visible가 XR_FALSE로 설정된 XrEventDataSpatialContainerVisibleChangedEXT 이벤트를 큐에 추가합니다.
  3. 공간 컨테이너의 렌더링을 종료합니다.
  4. xrDestroySpatialContainerEXT를 사용하여 컨테이너를 폐기합니다.

참고

이 확장 프로그램은 설계상 가시성 및 포커스 관리를 개별 공간 컨테이너에 위임합니다. 세션 전체가 더 이상 단일 표시 또는 포커스 객체를 나타내지 않으므로 세션은 표준 OpenXR 상태 머신 (READY, SYNCHRONIZED, VISIBLE, FOCUSED)을 통해 전환되지 않습니다. 대신 세션은 활성 수명 동안 XR_SESSION_STATE_IDLE 상태로 유지되며 세션 상태 변경의 규칙은 핵심 OpenXR 작업이 이 모드에 매핑되는 방식을 지정합니다.

공간 컨테이너 만들기

xrCreateSpatialContainerEXT 함수는 새 공간 컨테이너를 만듭니다.

XrResult xrCreateSpatialContainerEXT(
    XrSession                                   session,
    const XrSpatialContainerCreateInfoEXT*      createInfo,
    XrSpatialContainerEXT*                      spatialContainer);

파라미터 설명

새로 생성된 XrSpatialContainerEXT는 표시되지 않고 상호작용할 수 없으며 경계 모드 XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT에 있어야 합니다(must). 몰입형 모드에서 공간 컨테이너를 시작하려는 앱은 공간 컨테이너를 표시하도록 요청하기 전에 XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT의 경계 모드를 요청할 수 있습니다.

XrSpatialContainerCreateInfoEXT :: suggestedBounds의 측정기준이 음수, 무한대 또는 숫자가 아닌 경우 런타임은 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다(must). 앱이 XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount에 지정된 것보다 많은 공간 컨테이너를 만들려고 하면 런타임은 XR_ERROR_LIMIT_REACHED를 반환해야 합니다(must). 이 세션에 공간 컨테이너가 사용 설정되지 않은 경우 런타임은 XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT를 반환해야 합니다(MUST).

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerCreateInfoEXT는 xrCreateSpatialContainerEXT에 전달되어 공간 컨테이너를 만듭니다.

typedef struct XrSpatialContainerCreateInfoEXT {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialContainerGraphicsPresentationEXT    graphicsPresentation;
    XrExtent3Df                                  suggestedBounds;
} XrSpatialContainerCreateInfoEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • graphicsPresentation는 이 공간 컨테이너가 그래픽을 표시하는 방법을 설명하는 XrSpatialContainerGraphicsPresentationEXT입니다.
  • suggestedBounds는 요청된 공간 컨테이너의 크기를 미터 단위로 설명하는 XrExtent3Df입니다.

크기에 대한 환경설정이 없는 앱은 suggestedBounds를 {0, 0, 0}으로 설정할 수 있습니다. 런타임은 요청된 suggestedBounds를 무시할 수 있습니다(may).

공간 컨테이너가 방향 상자 이외의 도형으로 제한되도록 허용하는 런타임은 suggestedBounds를 다른 도형 주위의 경계 상자로 사용해야 합니다(MUST). 방향성 상자는 가장 일반적인 경계 도형입니다.

올바른 사용 (암시적)

공간 컨테이너를 더 이상 사용할 수 없는 경우 런타임은 XrEventDataSpatialContainerClosedEXT 이벤트를 큐에 추가해야 합니다(must).

typedef struct XrEventDataSpatialContainerClosedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerClosedEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • spatialContainer는 이 이벤트의 대상인 XrSpatialContainerEXT입니다.

XrEventDataSpatialContainerClosedEXT 이벤트를 수신하면 사용자가 '닫기' 버튼을 클릭하거나 세션이 XR_SESSION_STATE_LOSS_PENDING 상태로 전환되는 등의 이유로 런타임에서 더 이상 공간 컨테이너를 표시할 수 없음을 나타냅니다.

XrEventDataSpatialContainerClosedEXT 이벤트를 수신한 후 앱은 해당 공간 컨테이너 사용을 중지하고, 렌더링 루프와 같은 연결된 상태를 해제하고, 컨테이너를 폐기해야 합니다(should). 런타임은 xrDestroySpatialContainerEXT를 제외하고 해당 컨테이너에서 작동하는 모든 함수에서 XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT를 반환해야 합니다(must).

런타임이 닫기 이벤트를 큐에 추가할 때 공간 컨테이너가 표시되는 경우 런타임은 먼저 컨테이너를 표시되지 않도록 변경하고 XrEventDataSpatialContainerVisibleChangedEXT 이벤트를 큐에 추가해야 합니다(must).

올바른 사용 (암시적)

xrDestroySpatialContainerEXT 함수는 기존 공간 컨테이너를 소멸시킵니다.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

파라미터 설명

공간 컨테이너가 소멸된 후 런타임은 컨테이너의 콘텐츠를 더 이상 표시하지 않아야 하며(MUST) 컨테이너에 관한 추가 이벤트를 큐에 추가하지 않아야 합니다(MUST).

앱은 표시되는 공간 컨테이너를 소멸시키면(should) 안 됩니다. 소멸시키면 그래픽 아티팩트가 발생할 수 있기(may) 때문입니다. 대신 앱은 xrRequestSpatialContainerVisibleEXT를 사용하여 공간 컨테이너를 숨기도록 요청하고(should) XrEventDataSpatialContainerVisibleChangedEXT 이벤트를 기다린 후 컨테이너를 소멸시켜야 합니다(should).

올바른 사용 (암시적)

스레드 안전

  • spatialContainer 및 모든 하위 핸들에 대한 액세스는 외부에서 동기화되어야 합니다(must).

반품 코드

성공

  • XR_SUCCESS

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

공간 컨테이너 공간

xrCreateSpatialContainerSpaceEXT 함수는 특정 공간 컨테이너의 공간 컨테이너 공간에 대한 XrSpace 핸들을 만듭니다.

XrResult xrCreateSpatialContainerSpaceEXT(
    XrSession                                   session,
    const XrSpatialContainerSpaceCreateInfoEXT* createInfo,
    XrSpace*                                    space);

파라미터 설명

특정 공간 컨테이너의 '공간 컨테이너 공간'은 해당 공간 컨테이너 경계의 중심을 원점으로 하는 좌표계입니다. 이 공간은 일반적으로 xrLocateSpace와 같은 함수의 기본 공간으로 사용됩니다.

+X는 컨테이너의 오른쪽 면을 가리키고, +Y는 컨테이너의 상단 면을 가리키고, +Z는 컨테이너의 전면을 가리킵니다. 예를 들어 컨테이너가 중력 정렬되어 있고 뷰어 앞에 있으며 뷰어가 LOCAL 공간을 기준으로 ID 포즈에 있는 경우 런타임은 LOCAL 공간을 기준으로 ID 방향으로 컨테이너 공간의 방향을 지정해야 합니다(MUST). 런타임은 컨테이너가 표시될 때 LOCAL 공간을 기준으로 컨테이너 공간의 포즈를 임의의 포즈로 설정할 수 있습니다.

ext 공간 컨테이너 공간 규칙

그림 18. 공간 컨테이너 공간의 축 규칙

공간 컨테이너 공간은 월드 잠금이 아닌 원점입니다. 몰입형 모드에서 월드 잠금 원점을 원하는 앱은 XR_REFERENCE_SPACE_TYPE_LOCAL와 같은 월드 잠금 공간을 사용할 수 있습니다.

런타임은 언제든지 공간 컨테이너 공간의 포즈를 변경할 수 있습니다. 일반적으로 사용자가 공간 컨테이너를 다른 위치나 회전으로 이동할 수 있도록 지원하기 위해 변경합니다. 런타임은 XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT 및 XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT 경계 모드 간에 전환할 때 포즈를 변경할 수도 있습니다.

공간 컨테이너 공간은 공간 컨테이너가 xrDestroySpatialContainerEXT로 소멸되더라도 계속해서 유효한 핸들이어야 합니다. 공간 컨테이너가 표시되지 않거나 소멸된 동안에는 공간 컨테이너 공간이 다른 공간을 기준으로 위치를 찾을 수 없어야 합니다. XrSpaceLocation :: locationFlags 및 XrViewState ::viewStateFlags는 0입니다.

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerSpaceCreateInfoEXT는 xrCreateSpatialContainerSpaceEXT와 함께 사용하여 XrSpace 핸들을 만듭니다.

typedef struct XrSpatialContainerSpaceCreateInfoEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrSpatialContainerSpaceCreateInfoEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • spatialContainer는 스페이스를 만들 XrSpatialContainerEXT입니다.

올바른 사용 (암시적)

공간 컨테이너 표시

입체 컨테이너의 콘텐츠를 OpenXR에 제출하여 표시하는 작업은 다른 확장 프로그램(XR_EXT_spatial_container_self_rendering)에서 처리합니다.

다른 확장 프로그램이 공간 컨테이너의 그래픽 표시 방법을 지정할 수 있도록 이 확장 프로그램은 XrSpatialContainerGraphicsPresentationEXT enum을 정의합니다.

typedef enum XrSpatialContainerGraphicsPresentationEXT {
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT = 1000813000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT = 1000814000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1 = 1000815000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerGraphicsPresentationEXT;

enum 설명

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

공간 컨테이너는 OpenXR 컴포지션 레이어(XR_EXT_spatial_container_self_rendering 확장 프로그램에 의해 추가됨)를 사용합니다.

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

공간 컨테이너는 적합성 테스트를 위해 생성되며 렌더링 경로가 없습니다(XR_EXT_spatial_container_conformance_automation 확장 프로그램에 의해 추가됨).

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

공간 컨테이너는 OpenXR 시스템 렌더링을 사용합니다(XR_EXTX1_system_renderer 확장 프로그램에 의해 추가됨).

공간 컨테이너 상태

공간 컨테이너 상태는 앱 요청과 사용자의 요구사항을 모두 기반으로 런타임에서 관리합니다. 따라서 공간 컨테이너 상태의 각 측면은 다음을 문서화합니다.

  • 런타임이 공간 컨테이너 상태를 변경할 수 있는 경우 대부분의 공간 컨테이너 상태의 경우 런타임은 언제든지 상태를 변경할 수 있습니다.
  • 앱이 상태 변경을 요청하는 방법 런타임은 요청이 적합하다고 판단될 때까지 요청을 지연할 수 있습니다(may). 런타임은 요청이 지연될 때 이벤트를 큐에 추가하지 않으므로 앱은 관련 없는 로직에 대해 이러한 이벤트를 기다리지 않아야 합니다.
  • 공간 컨테이너 상태가 변경될 때 큐에 추가되는 이벤트 런타임입니다. 런타임은 앱에서 요청한 변경사항과 런타임에서 시작한 변경사항을 포함한 모든 변경사항에 관한 이벤트를 큐에 추가합니다. 런타임은 변경사항을 나타내지 않는 상태 변경 이벤트(예: 앱이 컨테이너를 숨기기 위해 연속으로 두 번 요청하는 경우)를 큐에 추가하면 안 됩니다.
  • 앱 변경 요청을 거부할 때 이벤트 런타임이 큐에 추가하는 항목입니다. 런타임은 어떤 이유로든 요청을 거부할 수 있습니다. 일반적으로 고품질 사용자 환경을 유지하는 것과 관련된 시스템 정책 때문입니다.

xrGetSpatialContainerStateEXT 함수는 공간 컨테이너의 현재 상태를 쿼리합니다.

XrResult xrGetSpatialContainerStateEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerStateGetInfoEXT*    getInfo,
    XrSpatialContainerStateEXT*                 state);

파라미터 설명

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerStateGetInfoEXT는 xrGetSpatialContainerStateEXT와 함께 사용하여 XrSpatialContainerStateEXT를 쿼리합니다.

typedef struct XrSpatialContainerStateGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerStateGetInfoEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.

올바른 사용 (암시적)

typedef struct XrSpatialContainerStateEXT {
    XrStructureType                    type;
    void*                              next;
    XrBool32                           visible;
    XrBool32                           interactable;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerStateEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • visible는 공간 컨테이너가 표시되는지 여부를 나타냅니다.
  • interactable는 공간 컨테이너가 현재 어떤 유형의 입력이든 수신할 수 있는지 여부를 나타냅니다. 이는 데스크톱 2D 윈도우 시스템의 '포커스'와 유사하지만, 여러 공간 컨테이너가 동시에 상호작용할 수 있다는 점이 다릅니다.
  • boundsMode는 공간 컨테이너의 현재 XrSpatialContainerBoundsModeEXT입니다.

공간 컨테이너 상태의 변경사항은 이벤트를 통해 전달됩니다.

필드 변경 이벤트

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

올바른 사용 (암시적)

  • XrSpatialContainerStateEXT를 사용하기 전에 XR_EXT_spatial_container 확장 프로그램을 사용 설정해야 합니다.
  • type은(는) XR_TYPE_SPATIAL_CONTAINER_STATE_EXT여야 합니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.

공개 상태

앱은 xrRequestSpatialContainerVisibleEXT를 사용하여 공간 컨테이너를 표시하거나 숨기도록 요청합니다.

XrResult xrRequestSpatialContainerVisibleEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerVisibleRequestInfoEXT* info);

파라미터 설명

공간 컨테이너를 표시하거나 숨기는 것은 비동기 작업입니다.

앱은 공간 컨테이너를 폐기하기 전에 숨기도록 요청하여 런타임이 원활한 전환을 표시할 수 있도록 해야 합니다. 런타임은 공간 컨테이너를 숨기라는 요청을 처리해야 합니다(should).

런타임은 공간 컨테이너를 표시하라는 요청을 거부할 수 있으며(may), 이 경우 런타임은 XrEventDataSpatialContainerVisibleRequestDeniedEXT 이벤트를 큐에 추가해야 합니다(must). 예를 들어 일부 런타임은 사용자가 시스템에서 제공하는 '최소화' 버튼과 상호작용하여 숨긴 공간 컨테이너를 표시하라는 요청을 거부합니다.

런타임은 앱이 공간 컨테이너를 표시하도록 요청하기 전에 공간 컨테이너를 표시하면 안 됩니다(must not). 앱이 공간 컨테이너를 표시하도록 처음 요청한 후 런타임은 앱의 요청과 관계없이 공간 컨테이너의 공개 상태를 변경할 수 있습니다. 이를 통해 앱은 공간 컨테이너의 초기 상태와 콘텐츠를 제어할 수 있으며, 런타임은 사용자가 표시할 공간 컨테이너를 선택할 수 있는 작업 표시줄과 같은 시스템 UI를 제공할 수 있습니다.

런타임은 XrSystemSpatialContainerPropertiesEXT :: supportsBounded 및 XrSystemSpatialContainerPropertiesEXT :: supportsImmersive에 따라 지원되지 않는 경계 모드에서 공간 컨테이너를 표시하라는 요청을 거부해야 합니다(must). 이는 지정된 시스템에서 기본 경계 모드인 XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT가 지원되지 않는 경우에 발생할 수 있습니다.

참고

일부 구현에서는 공간 컨테이너를 표시하거나 숨기려면 시스템 서비스와 통신해야 하며 사용자가 시스템 대화상자와 상호작용할 때까지 지연될 수 있습니다. 공개 상태 변경을 요청하는 비동기 설계는 런타임이 이 두 작업을 모두 완료할 수 있는 시간을 제공하기 위한 것입니다.

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerVisibleRequestInfoEXT는 xrRequestSpatialContainerVisibleEXT와 함께 사용하여 공간 컨테이너의 공개 상태를 변경합니다.

typedef struct XrSpatialContainerVisibleRequestInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           visible;
} XrSpatialContainerVisibleRequestInfoEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • visible는 공간 컨테이너를 표시하거나 숨기도록 요청되었는지 여부를 나타냅니다.

올바른 사용 (암시적)

런타임이 공간 컨테이너의 공개 상태를 변경할 때마다 런타임은 새 상태로 XrEventDataSpatialContainerVisibleChangedEXT 이벤트를 큐에 추가해야 합니다(must).

typedef struct XrEventDataSpatialContainerVisibleChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 visible;
} XrEventDataSpatialContainerVisibleChangedEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • spatialContainer는 이 이벤트의 대상인 XrSpatialContainerEXT입니다.
  • visible은 공간 컨테이너의 새로운 표시 상태입니다.

이 이벤트는 XR_SESSION_STATE_VISIBLE를 대체하여 컨테이너별로 값이 다를 수 있습니다. 이벤트는 앱 요청 변경사항 및 런타임 시작 변경사항을 포함한 모든 변경사항에 대해 큐에 추가되어야 합니다.

런타임은 빈 컨테이너가 표시되지 않도록 하고 앱이 초기 콘텐츠를 제출할 시간을 제공하기 위해 visible를 XR_TRUE로 설정하여 이 이벤트를 큐에 추가한 후 몇 프레임 동안 컨테이너 렌더링을 지연시킬 수 있습니다. 이 기간 동안 XrSpatialContainerStateEXT ::visible은 XR_TRUE입니다. 런타임은 컨테이너 렌더링을 0.5초 넘게 지연해서는 안 됩니다(should).

올바른 사용 (암시적)

런타임이 컨테이너 표시 요청을 거부할 때마다 런타임은 XrEventDataSpatialContainerVisibleRequestDeniedEXT 이벤트를 큐에 추가해야 합니다(must).

typedef struct XrEventDataSpatialContainerVisibleRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerVisibleRequestDeniedEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • spatialContainer는 이 이벤트의 대상인 XrSpatialContainerEXT입니다.

올바른 사용 (암시적)

상호작용 가능

앱은 공간 컨테이너를 상호작용 가능하도록 요청할 수 없습니다. 상호작용할 수 있는 공간 컨테이너는 런타임에 의해 완전히 제어됩니다. 상호작용할 수 있는 공간 컨테이너는 표시되어야 합니다(MUST).

런타임이 공간 컨테이너의 상호작용 가능 상태를 변경할 때마다 런타임은 새 상태와 함께 XrEventDataSpatialContainerInteractableChangedEXT 이벤트를 큐에 추가해야 합니다(must).

typedef struct XrEventDataSpatialContainerInteractableChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 interactable;
} XrEventDataSpatialContainerInteractableChangedEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • spatialContainer는 이 이벤트의 대상인 XrSpatialContainerEXT입니다.
  • interactable은 공간 컨테이너의 새로운 상호작용 가능 상태입니다.

이 이벤트는 XR_SESSION_STATE_FOCUSED를 대체하여 컨테이너별로 값이 다를 수 있습니다. 런타임에서 시작된 변경사항을 포함한 모든 변경사항에 대해 이벤트가 큐에 추가됩니다.

런타임은 언제든지 공간 컨테이너와의 상호작용을 사용 설정하거나 사용 중지할 수 있습니다. 런타임이 한 번에 최대 하나의 상호작용 가능한 공간 컨테이너만 지원하는 경우, 런타임이 상호작용 가능한 공간 컨테이너를 변경할 때 상호작용이 시작되는 컨테이너의 이벤트(interactable가 true로 설정됨)보다 상호작용이 중지되는 공간 컨테이너의 이벤트(interactable가 false로 설정됨)를 먼저 큐에 추가해야 합니다(must).

올바른 사용 (암시적)

경계

공간 컨테이너에는 경계 모드와 경계 상자가 있습니다. 공간 컨테이너의 경계 모드는 경계가 작동하는 방식을 설명합니다. 경계 상자는 공간 컨테이너가 내부에 그리는 것입니다.

XrSpatialContainerBoundsModeEXT 열거형은 공간 컨테이너의 경계가 있을 수 있는 다양한 모드를 식별합니다.

typedef enum XrSpatialContainerBoundsModeEXT {
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT = 1,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT = 2,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerBoundsModeEXT;

enum 설명

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

공간 컨테이너가 제한됩니다. 경계는 유한한 상자입니다. 공간 컨테이너는 이 지역에만 표시됩니다.

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

공간 컨테이너는 몰입형이며 경계가 무한합니다. 공간 컨테이너가 전체 화면에 표시됩니다.

경계 모드 XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT에 있는 공간 컨테이너에는 다음과 같은 추가 요구사항이 있습니다.

  • 런타임은 세션 상태 변경사항에 설명된 동작 변경사항을 제외하고 이러한 공간 컨테이너를 공간 컨테이너를 사용하지 않고 만든 전체 화면 및 몰입형 앱과 동일하게 취급해야 합니다(MUST).
  • 런타임은 몰입형 공간 컨테이너가 이 확장 프로그램 없이 생성된 전체 화면 및 몰입형 앱과 다르게 동작하도록 하는 추가 확장 프로그램을 제공할 수 있습니다(may).
  • 런타임은 이러한 공간 컨테이너의 무한 경계를 보고해야 합니다(must).
  • 런타임은 몰입형 공간 컨테이너가 표시되는 동안 다른 공간 컨테이너를 숨길 수 있습니다. 이는 런타임마다 다를 수 있으므로 앱은 몰입형 공간 컨테이너 공개 상태에 따라 공간 컨테이너가 자동으로 표시되거나 숨겨지는 것에 의존해서는 안 됩니다. 다른 모든 표시 상태 전환과 마찬가지로, 런타임은 몰입형 컨테이너가 표시되어 공간 컨테이너가 숨겨질 때 XrEventDataSpatialContainerVisibleChangedEXT 이벤트를 큐에 추가해야 합니다(must).

참고

위 요구사항은 모든 런타임이 이 확장 프로그램 없이도 공간 컨테이너를 암시적으로 만들고, 컨테이너의 경계 모드를 몰입형으로 설정하고, 표시되도록 요청하여 OpenXR 1.x 경로를 구현할 수 있음을 의미합니다.

앱은 xrRequestSpatialContainerBoundsModeEXT를 사용하여 공간 컨테이너의 경계 모드 변경을 요청합니다.

XrResult xrRequestSpatialContainerBoundsModeEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsModeRequestInfoEXT* info);

파라미터 설명

공간 컨테이너의 경계 모드를 변경하는 것은 비동기 작업이며, 앱이 변경을 요청한 후 몇 초 후에 런타임이 변경되거나 거부된 이벤트를 큐에 추가할 수 있습니다. 이를 통해 런타임은 사용자가 몰입형 모드에 안전하게 진입할 수 있도록 하는 데 필요한 UI를 표시할 수 있습니다.

런타임은 표시되지 않는 공간 컨테이너의 경계 모드를 변경해 달라는 요청을 처리해야 합니다(must). 런타임이 표시되지 않는 컨테이너의 경계 모드 요청을 거부하는 경우 대신 이러한 공간 컨테이너를 표시하는 요청을 거부하거나 지연할 수 있습니다. 이렇게 하면 앱이 컨테이너를 몰입형 컨테이너로 시작할 수 있습니다. 런타임은 표시되는 공간 컨테이너의 경계 모드를 변경하라는 요청을 거부할 수 있으며(may), 이 경우 런타임은 XrEventDataSpatialContainerBoundsModeRequestDeniedEXT 이벤트를 큐에 추가해야 합니다(must). 예를 들어 일부 런타임은 사용자가 적극적으로 상호작용하지 않는 표시되는 공간 컨테이너의 경계 모드를 변경하는 요청을 거부합니다.

앱이 XrSystemSpatialContainerPropertiesEXT :: supportsBounded 및 XrSystemSpatialContainerPropertiesEXT :: supportsImmersive에 따라 지원되지 않는 경계 모드를 요청하는 경우 런타임은 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다(must).

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerBoundsModeRequestInfoEXT는 xrRequestSpatialContainerBoundsModeEXT와 함께 사용하여 공간 컨테이너의 경계 모드를 변경합니다.

typedef struct XrSpatialContainerBoundsModeRequestInfoEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerBoundsModeRequestInfoEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • boundsMode는 공간 컨테이너에 원하는 XrSpatialContainerBoundsModeEXT입니다.

올바른 사용 (암시적)

런타임이 공간 컨테이너의 경계 또는 경계 모드를 변경할 때마다 런타임은 새 경계 정보가 포함된 XrEventDataSpatialContainerBoundsChangedEXT 이벤트를 큐에 추가해야 합니다.

typedef struct XrEventDataSpatialContainerBoundsChangedEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerEXT              spatialContainer;
    XrExtent3Df                        bounds;
    XrBool32                           infiniteBounds;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrEventDataSpatialContainerBoundsChangedEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • spatialContainer는 이 이벤트의 대상인 XrSpatialContainerEXT입니다.
  • bounds은 공간 컨테이너 경계의 새로운 너비, 높이, 깊이입니다.
  • infiniteBounds는 컨테이너에 무한 경계가 있는 경우 true입니다.
  • boundsMode은 공간 컨테이너의 새 XrSpatialContainerBoundsModeEXT입니다.

이벤트는 앱 요청 변경사항 및 런타임 시작 변경사항을 포함한 모든 변경사항에 대해 큐에 추가됩니다.

사용자가 공간 컨테이너의 크기를 대화형으로 조절하는 동안 런타임은 다음 중 한 가지 방식으로 작동해야 합니다(must).

  • 사용자가 공간 컨테이너의 크기를 조절할 때 프레임 속도로 많은 이벤트를 큐에 추가합니다.
  • 크기 조절이 끝날 때 단일 이벤트를 큐에 추가

런타임이 크기 조절이 끝날 때 단일 이벤트만 큐에 추가하는 경우 런타임은 런타임이 크기 조절 이벤트를 큐에 추가할 때까지 xrGetSpatialContainerBoundsEXT에서 이전 경계를 계속 보고해야 합니다(must). 런타임은 폴링되지 않은 여러 경계 변경 이벤트를 병합해야 합니다. 즉, XrEventDataSpatialContainerBoundsChangedEXT 이벤트가 아직 대기열에 있는 동안 경계 또는 경계 모드가 변경되면 런타임은 마지막으로 발생한 경계 변경사항이 포함된 단일 이벤트만 보고해야 합니다(must). 앱은 xrGetSpatialContainerBoundsEXT를 사용하여 공간 컨테이너의 경계를 직접 폴링할 수도 있으므로 이벤트의 경계 변경 횟수는 런타임 생성 경계 변경 타이밍, 앱의 xrPollEvent 호출, 앱의 xrGetSpatialContainerBoundsEXT 호출에 따라 폴링의 변경 횟수와 다를 수 있습니다.

공간 컨테이너의 경계가 변경되면 공간 컨테이너의 로컬 원점도 변경될 수 있습니다. 예를 들어 런타임에서 사용자가 컨테이너의 가장자리 중 하나를 드래그하여 공간 컨테이너의 경계 크기를 조절할 수 있는 경우 사용자가 단일 가장자리를 드래그하면 해당 컨테이너의 경계와 로컬 원점이 변경됩니다. 이러한 상황에서는 런타임이 경계와 로컬 원점을 동시에 변경해야 합니다.

런타임은 infiniteBounds를 XR_TRUE로 설정하고 너비, 높이, 깊이를 0.0으로 설정하여 무한 경계를 나타내야 합니다(must). 런타임은 infiniteBounds를 XR_FALSE로 설정하고 유한 경계의 너비, 높이, 깊이를 유한한 양수로 설정해야 합니다(must).

런타임은 XrSpatialContainerBoundsEXT와 동일한 규칙에 따라 bounds 및 infiniteBounds를 설정해야 합니다(must).

올바른 사용 (암시적)

런타임이 컨테이너의 경계 모드를 변경하라는 요청을 거부할 때마다 런타임은 XrEventDataSpatialContainerBoundsModeRequestDeniedEXT 이벤트를 큐에 추가해야 합니다(must).

typedef struct XrEventDataSpatialContainerBoundsModeRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerBoundsModeRequestDeniedEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • spatialContainer는 이 이벤트의 대상인 XrSpatialContainerEXT입니다.

올바른 사용 (암시적)

XrSpatialContainerBoundsEXT 구조는 공간 컨테이너의 경계 상자를 설명합니다.

typedef struct XrSpatialContainerBoundsEXT {
    XrStructureType    type;
    void*              next;
    XrExtent3Df        bounds;
    XrBool32           infiniteBounds;
} XrSpatialContainerBoundsEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • bounds는 공간 컨테이너 경계의 너비, 높이, 깊이입니다. 경계는 미터 단위입니다.
  • infiniteBounds는 컨테이너에 무한 경계가 있는 경우 true입니다.

런타임은 infiniteBounds를 XR_TRUE로 설정하고 너비, 높이, 깊이를 0.0으로 설정하여 무한 경계를 나타내야 합니다(must). 런타임은 infiniteBounds를 XR_FALSE로 설정하고 유한 경계의 너비, 높이, 깊이를 유한한 양수로 설정해야 합니다(must).

올바른 사용 (암시적)

  • XrSpatialContainerBoundsEXT를 사용하기 전에 XR_EXT_spatial_container 확장 프로그램을 사용 설정해야 합니다(MUST).
  • type은(는) XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT여야 합니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.

xrGetSpatialContainerBoundsEXT 함수는 공간 컨테이너의 현재 경계를 쿼리합니다.

XrResult xrGetSpatialContainerBoundsEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsGetInfoEXT*   getInfo,
    XrSpatialContainerBoundsEXT*                bounds);

파라미터 설명

공간 컨테이너가 제한된 경우 무한한 경계를 가져서는 안 되며, 공간 컨테이너가 몰입형인 경우 무한한 경계를 가져야 합니다.

런타임은 공간 컨테이너가 제한되어 있는 동안 언제든지 공간 컨테이너의 경계를 양의 유한 값으로 변경할 수 있습니다. 공간 컨테이너 경계의 변경사항은 XrEventDataSpatialContainerBoundsChangedEXT를 통해 전달됩니다.

이 확장 프로그램을 사용하면 앱은 xrRequestSpatialContainerBoundsModeEXT를 사용하여 경계 모드와 몰입형 모드 간에 전환하는 것 외에는 경계 변경을 요청할 수 없습니다. 향후 다른 확장 프로그램에서 이러한 방법을 제공할 수도 있습니다.

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerBoundsGetInfoEXT 구조는 향후 확장 목적으로 존재하는 입력 구조입니다.

typedef struct XrSpatialContainerBoundsGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerBoundsGetInfoEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.

올바른 사용 (암시적)

XrSpatialContainerVolumeClippingEXT 열거형은 공간 컨테이너의 다양한 볼륨 클리핑 동작을 식별합니다.

typedef enum XrSpatialContainerVolumeClippingEXT {
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT = 0,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT = 1,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerVolumeClippingEXT;

enum 설명

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

공간 컨테이너의 경계 볼륨에 콘텐츠가 잘리지 않습니다. 콘텐츠는 공간 컨테이너의 경계 외부에 그려질 수 있습니다.

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

콘텐츠는 공간 컨테이너의 경계 볼륨에 엄격하게 잘립니다.

이 확장 프로그램에서는 이 열거형을 사용하지 않습니다. 다른 확장 프로그램이 원하는 볼륨 클리핑 동작을 지정할 수 있도록 정의됩니다. 예를 들어 앱은 경계가 있는 공간 컨테이너의 배경을 그릴 수 있습니다. 모노 큐브맵은 배경을 지정하는 편리한 방법이지만, 모노 큐브맵은 개념적으로 컨테이너 외부에 있는 무한대에 위치합니다.

시스템 기능

앱은 xrGetSystemProperties를 호출할 때 XrSystemSpatialContainerPropertiesEXT 구조를 XrSystemProperties에 연결하여 시스템 기능을 검사할 수 있습니다.

typedef struct XrSystemSpatialContainerPropertiesEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSpatialContainerCount;
    XrBool32           supportsBounded;
    XrBool32           supportsImmersive;
} XrSystemSpatialContainerPropertiesEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • maxSpatialContainerCount는 생성할 수 있는 최대 공간 컨테이너 수입니다.
  • supportsBounded는 공간 컨테이너를 제한할 수 있는 경우 true입니다.
  • supportsImmersive는 공간 컨테이너가 몰입형일 수 있는 경우 true입니다.

이 확장 프로그램을 지원하는 런타임은 메모리 할당에 의해서만 제한되는 여러 공간 컨테이너를 만드는 앱을 지원해야 합니다(should). 런타임은 동시에 표시되는 공간 컨테이너 수에 대해 다른 제한을 둘 수 있습니다. 런타임은 실행 중인 모든 앱의 상태에 따라 개별 앱을 제한할 수 있으므로 이 확장 프로그램에서 동시에 표시되는 컨테이너 수를 쿼리할 방법이 없습니다. 제약이 많은 기기와 제약이 적은 기기는 동시에 표시되는 컨테이너 수에 대한 제한이 다를 것으로 가정합니다. 제약이 많은 기기는 한 번에 하나의 공간 컨테이너만 표시하도록 지원할 수 있고 제약이 적은 기기는 렌더링 컴퓨팅 제한에 따라 동시에 표시되는 많은 수의 공간 컨테이너를 지원할 수 있습니다.

이 확장 프로그램을 지원하는 런타임은 경계가 있는 공간 컨테이너 또는 몰입형 공간 컨테이너 중 하나 이상을 지원해야 합니다(must).

올바른 사용 (암시적)

xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT 함수는 시스템에서 지원되는 그래픽 프레젠테이션 메서드를 반환합니다.

XrResult xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    graphicsPresentationCapacityInput,
    uint32_t*                                   graphicsPresentationCountOutput,
    XrSpatialContainerGraphicsPresentationEXT*  graphicsPresentations);

파라미터 설명

  • instance은 systemId를 가져온 XrInstance입니다.
  • systemId는 쿼리되는 XrSystemId입니다.
  • graphicsPresentationCapacityInput는 graphicsPresentations 배열의 용량입니다. 필요한 용량을 가져오라는 요청을 나타내려면 0으로 설정합니다.
  • graphicsPresentationCountOutput는 작성된 그래픽 프레젠테이션 수에 대한 포인터이거나 graphicsPresentationCapacityInput가 0인 경우 필요한 용량에 대한 포인터입니다.
  • graphicsPresentations는 XrSpatialContainerGraphicsPresentationEXT 값 배열의 포인터이지만 graphicsPresentationCapacityInput가 0인 경우 null일 수 있습니다.
  • 필요한 graphicsPresentations 크기를 가져오는 방법에 관한 자세한 설명은 버퍼 크기 매개변수 섹션을 참고하세요.

런타임은 지정된 systemId 및 인스턴스 전체 기간에 대해 이 열거에서 항상 동일한 버퍼 콘텐츠를 반환해야 합니다(must).

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

세션 상태 변경

xrCreateSession을 호출할 때 XrSessionCreateInfoSpatialContainersEXT를 연결하여 세션에 공간 컨테이너 지원을 사용 설정합니다.

typedef struct XrSessionCreateInfoSpatialContainersEXT {
    XrStructureType    type;
    const void*        next;
} XrSessionCreateInfoSpatialContainersEXT;

공간 컨테이너 지원이 사용 설정되면 XrSession이 다르게 작동합니다. 공간 컨테이너를 사용할 때 세션은 더 이상 디스플레이에 이미지 콘텐츠를 표시하지 않고 공간 컨테이너가 대신 표시하기 때문입니다. 따라서 이 확장 프로그램이 사용 설정되면 세션은 사실상 '헤드리스' 상태가 됩니다. 다른 헤드리스 확장 프로그램과 달리 앱은 공간 컨테이너를 통해 이미지 데이터를 제출할 수 있습니다.

공간 컨테이너 지원을 사용 설정하면 다음과 같은 방식으로 핵심 OpenXR API가 변경됩니다.

런타임: 시스템 또는 기기 분실

런타임: 시스템 또는 기기 분실

xrDestroySession

xrDestroySession

IDLE
(실행 중)

IDLE…

xrGetSystem
xrCreateSession

xrGetSystem…

xrCreateInstance

xrCreateIn…

xrDestroySession

xrDestroySession

LOSS_PENDING
(실행 중 아님)

LOSS_PENDING…

xrDestroyInstance

xrDestroyInstance

앱: 선택적으로
XR 다시 실행

app: 선택사항…

그림 19: 새 세션 상태 시스템

  • 세션이 XR_SESSION_STATE_VISIBLE, XR_SESSION_STATE_FOCUSED 또는 XR_SESSION_STATE_EXITING 상태로 전환되지 않습니다. 런타임은 이러한 상태의 이벤트를 큐에 추가하면 안 됩니다. 이러한 상태는 각각 공간 컨테이너별 이벤트 XrEventDataSpatialContainerVisibleChangedEXT, XrEventDataSpatialContainerInteractableChangedEXT, XrEventDataSpatialContainerClosedEXT로 대체됩니다.
  • 또한 세션은 XR_SESSION_STATE_READY , XR_SESSION_STATE_SYNCHRONIZED , XR_SESSION_STATE_STOPPING 상태로 전환되지 않습니다. 런타임은 이러한 상태의 이벤트를 큐에 추가하면 안 됩니다. 이러한 상태는 대체할 수 없습니다.
  • 런타임은 세션이 XR_SESSION_STATE_IDLE 상태일 때 실행 중인 것으로 처리해야 합니다.
  • 런타임은 상태가 XR_SESSION_STATE_IDLE이고 상호작용 가능한 공간 컨테이너가 하나 이상 있는 경우 세션을 포커스가 있는 것으로 처리해야 합니다(MUST).
  • xrBeginSession 및 xrEndSession 함수는 더 이상 필요하지 않습니다. 런타임은 이러한 함수가 호출될 때 XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT를 반환해야 합니다(must). 다른 확장 프로그램에서 이러한 함수를 대체할 수 있습니다.
  • xrRequestExitSession 함수도 더 이상 필요하지 않습니다. 이 함수가 호출되면 런타임은 XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT를 반환해야 합니다(MUST). 실행 중인 세션을 종료하려는 앱은 xrRequestSpatialContainerVisibleEXT를 호출하여 컨테이너를 숨기고 모든 컨테이너가 더 이상 표시되지 않으면 세션을 소멸시킬 수 있습니다.

  • 세션이 실행되기 시작할 때 추가 이벤트를 큐에 추가하는 확장 프로그램은 이제 세션 생성 후에 해당 이벤트를 큐에 추가해야 합니다. 이러한 확장 프로그램은 아래에 설명되어 있습니다.

    확장 프로그램 이벤트

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

  • xrLocateViews 함수는 세션에 호출할 수 없습니다. 런타임은 xrLocateViews에서 XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT를 반환해야 합니다(must). 다른 확장 프로그램은 특정 공간 컨테이너의 뷰를 찾는 방법을 제공할 수 있습니다.
  • xrWaitFrame 함수는 항상 XrFrameState :: shouldRender를 false로 설정해야 합니다(must). 다른 확장 프로그램은 특정 공간 컨테이너가 컴포지션 레이어를 업데이트해야 하는지 알 수 있는 방법을 제공할 수 있습니다.
  • xrEndFrame 함수는 컴포지션 레이어를 제출하는 유효한 방법이 아닙니다. 앱이 설정하는 경우XrFrameEndInfo :: layerCount 0이 아닌 값으로, 실행 시간~ 해야 하다 반품XR_ERROR_VALIDATION_FAILURE . 다른 확장 프로그램은 특정 공간 컨테이너의 컴포지션 레이어를 제출하는 방법을 제공할 수 있습니다.
  • XR_SESSION_STATE_LOSS_PENDING 상태로 전환하면 모든 공간 컨테이너도 닫힙니다. 런타임은 XR_SESSION_STATE_LOSS_PENDING의 세션 상태 변경을 큐에 추가하기 전에 각 활성 공간 컨테이너의 XrEventDataSpatialContainerClosedEXT 이벤트를 큐에 추가해야 합니다.
  • xrCreateSession 함수에 더 이상 그래픽 API 결합 구조가 필요하지 않습니다. 다른 확장 프로그램은 그래픽 API를 사용하여 렌더링하는 공간 컨테이너와 같이 그래픽 결합이 필요할 수 있습니다.

위 동작은 XR_MND_headless의 동작과 약간 다릅니다. 런타임은 세션에 공간 컨테이너 지원이 사용 설정된 경우 XR_MND_headless의 헤드리스 세션 동작을 사용 설정하면 안 됩니다(MUST NOT).

참고

공간 컨테이너가 사용 설정되면 세션은 XR_SESSION_STATE_IDLE (실행 중) 및 XR_SESSION_STATE_LOSS_PENDING (실행 중 아님)의 두 가지 상태 간에만 전환됩니다. 따라서 런타임은 더 이상 XR_ERROR_SESSION_RUNNING 또는 XR_ERROR_SESSION_NOT_RUNNING를 반환하지 않습니다. 대신 세션이 실행되지 않는 경우 런타임은 OpenXR 핵심의 규칙에 따라 XR_ERROR_SESSION_LOST 또는 XR_SESSION_LOSS_PENDING를 반환합니다. 또한 XR_ERROR_SESSION_RUNNING를 반환하는 유일한 함수인 xrBeginSession은 이제 항상 XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT를 반환합니다.

올바른 사용 (암시적)

Android 매니페스트 항목

AOSP 기반 런타임은 앱 코드를 실행하기 전에 시작되는 초기 공간 컨테이너 상태를 기반으로 하는 맞춤 동작을 가질 수 있습니다. 예를 들어 런타임은 활동, 실행 애니메이션 또는 스플래시 화면 표시에 할당된 리소스를 변경할 수 있습니다(MAY). 이를 위해 다음 속성이 제공됩니다. 이 태그는 <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> 태그를 대체하며, 공간 컨테이너 기반 앱은 이전 AOSP 기반 런타임과의 호환성을 위한 경우를 제외하고는 이 태그를 지정하지 않아야 합니다.

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
          android:value="list of modes" />

이 속성은 활동에서 사용하는 경계 모드를 런타임에 힌트로 제공합니다. 기본적으로 빈 목록이며, 이는 힌트가 없음을 의미합니다.

다음 문자열은 이 속성에 유효합니다. 여러 값은 |로 구분됩니다(예: "bounded|immersive").

값

설명

"2d_panel"

활동은 Android의 2D 뷰 프레임워크를 사용하여 표시됩니다.

"bounded"

활동은 XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT를 사용합니다.

"immersive"

활동은 XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT를 사용합니다.

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
          android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED" />

이 속성은 활동이 처음 생성될 때 활동의 초기 XrSpatialContainerBoundsModeEXT를 런타임에 힌트로 제공합니다. 기본적으로 XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED 문자열이며, 이는 힌트가 없음을 의미합니다.

런타임은 앱이 이 사양에 따라 동작하기 위해 이러한 속성을 갖도록 요구해서는 안 됩니다. 런타임은 이러한 속성을 기반으로 앱의 표시되는 동작을 변경해서는 안 됩니다. 이러한 모든 메타데이터는 <activity> 수준 또는 <application> 수준에서 지정할 수 있어야 합니다(must). <application> 수준에서 지정하면 자체 값을 지정하지 않는 애플리케이션의 모든 활동에 적용됩니다.

예시 코드

다음 코드는 렌더링 없이 인식 전용 사용 사례에 이 확장 프로그램을 사용하는 방법을 보여줍니다.

XrInstance instance;    // Already initialized


// Create the session with spatial containers enabled
XrSession session;

XrSessionCreateInfoSpatialContainersEXT spatialContainerCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT,
};
XrSessionCreateInfo sessionCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO,
  .next = &spatialContainerCreateInfo,   // Enable spatial containers
};
(void)sessionCreateInfo.systemId;                             // Other create fields set in usual way

CHK_XR(xrCreateSession(instance, &sessionCreateInfo, &session));


// Because spatial containers are enabled, the session is considered
// running. App is able to query perception data such as head poses and hand
// poses.


// Based on app logic or when a system lost event happens, destroy the
// session
CHK_XR(xrDestroySession(session));

새 객체 유형

새 명령어

새로운 구조

새 enum

새 enum 상수

  • XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
  • XR_EXT_spatial_container_SPEC_VERSION

  • XrObjectType 확장:

    • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

  • XrResult 확장:

    • XR_ERROR_COMPATIBLE_SPATIAL_CONTAINER_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT

  • XrStructureType 확장:

    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_DENIED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_CLOSED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_INTERACTABLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_REQUEST_DENIED_EXT
    • XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_SPACE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VISIBLE_REQUEST_INFO_EXT
    • XR_TYPE_SYSTEM_SPATIAL_CONTAINER_PROPERTIES_EXT

문제

  • 해결되지 않은 여러 개의 표시 요청은 어떻게 처리하나요? 앱에 변경사항이 하나만 적용되거나 거부되나요, 아니면 여러 개가 적용되나요? 호출이 여러 프레임에 걸쳐 있는 경우 답이 다를 수 있습니다. 여러 요청이 noop을 초래하는 경우, 즉 공간 컨테이너를 표시하도록 요청한 후 표시되지 않는 상태로 시작하는 컨테이너를 표시하지 않도록 요청하는 경우에도 답변이 달라질 수 있습니다.

    • 해결됨. 변경 이벤트와 거부된 이벤트에 대한 다양한 선택지 Noop 요청은 변경 이벤트를 큐에 추가하지 않으며, 앱 개발자에게 노이즈를 생성할 뿐이고 런타임에서 쉽게 필터링할 수 있습니다. 표시되는 요청이 여러 개 거부되면 런타임은 각각에 해당하는 거부 이벤트를 생성해야 합니다(MUST).

  • 정책 동작의 모든 선택적 사양 텍스트를 CTS에서 테스트할 수 있도록 적합성 자동화 확장 프로그램을 정의하려면 어떻게 해야 하나요?

    • 해결됨. 별도의 테스트 확장 프로그램 CTS에서 모든 시스템 정책을 제어할 수 있도록 CTS 전용 테스트 확장 프로그램 런타임 구현이 있을 예정입니다.

  • 공간 컨테이너의 위치가 변경될 때 이벤트가 필요한가요?

    • 해결됨. 아니요. 공간 컨테이너 공간은 월드 잠금이 아니며 XR_REFERENCE_SPACE_TYPE_VIEW와 같은 다른 공간은 변경 시 이벤트가 없습니다.

  • 공간 컨테이너가 여러 개 있는 경우 xrSyncActions는 어떻게 작동하나요?

    • 해결됨. 변경할 필요가 없습니다. xrSyncActions는 세션의 모든 공간 컨테이너에 적용됩니다. 앱이 입력 작업을 특정 공간 컨테이너로 전달하려는 경우 컨테이너별 상호작용 가능 상태를 확인하여 유효한 타겟인 컨테이너를 선택할 수 있습니다. 앱이 단일 공간 컨테이너의 입력 작업 상태만 동기화하려는 경우 추가 확장 프로그램이 필요합니다. 대신 앱이 완전히 이벤트 기반으로 작동하고 프레임 루프에서 xrSyncActions 호출이 필요하지 않도록 하는 확장 프로그램에 집중할 계획입니다.

  • 업데이트 빈도가 낮은 앱은 입력을 어떻게 처리하나요?

    • 해결됨. 변경이 필요하지 않습니다. EXT_spatial_container에 유용하지만 공간 컨테이너 외부에서도 유용합니다. 이는 이벤트 채널 확장 프로그램을 통해 처리할 수 있으며 두 경우 모두에서 작동합니다. 공간 컨테이너의 경우 단일 공간 컨테이너의 이벤트를 필터링하는 추가 방법을 추가할 예정입니다.

  • 입력 루프와 렌더링 루프가 분리된 앱의 경우 입력 루프의 타이밍을 제한/제어하기 위해 대기가 필요한가요?

    • 해결됨. 변경이 필요하지 않습니다. 이는 이벤트 채널 및 현재 요청 확장 프로그램을 통해 처리될 것으로 예상됩니다. Present 요청 확장 프로그램을 사용하면 렌더링을 이벤트 기반으로 하고 프레임 루프에서 분리할 수 있습니다.

  • 공간 컨테이너가 다른 공간 컨테이너를 기준으로 포즈를 가져올 수 있나요? 여기서 핵심은 '이 기능의 사용 사례가 있는가?'입니다. 그렇다면 공간 컨테이너 공간은 LOCAL에 어떻게 연결되나요?

    • 해결됨. 예. 이는 XR_REFERENCE_SPACE_TYPE_VIEW를 통해 동일한 세션 내의 공간 컨테이너에 이미 가능하며 뷰 종속 콘텐츠를 지원하는 것이 바람직합니다. 세션 간에 공간 컨테이너 포즈를 공유하는 경우 (예: 다른 프로세스에 공유) 예상되는 경로는 XR_EXT_spatial_anchor 및 기존 지속성 및 공유 패턴을 활용하는 것입니다.

  • 공간 컨테이너의 공간이 보이지 않는 경우 위치를 찾을 수 있나요?

    • 해결됨. 아니요. 공간 컨테이너가 표시되지 않으면 공간 컨테이너의 공간을 찾을 수 없습니다. 즉, 공간 음향이 없으며 spatial_container가 표시되지 않을 때 앱이 뷰 종속 콘텐츠를 '준비'할 수 없습니다. 공간 컨테이너가 표시되지 않으면 앱이 해당 공간 컨테이너에 사용되는 CPU/GPU 로드를 중지할 것으로 예상되므로 둘 다 괜찮습니다.

  • 공간 컨테이너 공간은 공간 컨테이너의 어디에 배치될 것으로 예상되나요? 제안은 중심 또는 최소 지점 (minX, minY, minZ)입니다.

    • 해결됨. 중앙에 있습니다. 공간 컨테이너 크기 조절 UX가 예상되는 대부분의 방식 (가장자리 이동)으로 이동하지 않는 위치는 없습니다. Center는 OpenXR의 다른 부분에서 일반적으로 사용됩니다. 3D 모델 뷰어는 이 규칙을 따르지 않는 경우가 많기 때문에 최소 좌표를 사용하는 2D 컴퓨팅의 창과 정렬하지 않았습니다.

  • 런타임은 언제 공간 컨테이너의 기반이 되는 리소스를 생성해야 하나요? 여기에는 시스템 서비스와의 IPC가 포함되는 경우도 있습니다.

    • 해결됨. xrCreateSpatialContainerEXT의 일부로 동기식으로 실행됩니다. IPC가 관련될 수 있지만 컨테이너의 실제 생성은 일반적으로 비용이 적게 들 것으로 예상됩니다. 일부 공급업체에는 컨테이너 관리에 관한 전역 뮤텍스가 있지만 일반적으로 오래 기다리지 않아도 됩니다. 뮤텍스 경합 문제는 공급업체별 버그로, 각 공급업체에서 해결해야 합니다.

  • XrSession이 공간 컨테이너를 생성하므로 기존 렌더링 경로를 지원하지 않는다는 신호가 필요한가요?

    • 해결됨. 예. 세션 상태 머신을 근본적으로 변경합니다.

버전 기록

  • 버전 1, 2026년 8월 6일 (제러드 파인더, Google)

    • 초기 확장 프로그램 설명