XR_ANDROID_spatial_anchor_space

이름 문자열

XR_ANDROID_spatial_anchor_space

확장 프로그램 유형

인스턴스 확장 프로그램

등록된 내선 번호

796

버전

1

승인 상태

비준되지 않음

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

XR_EXT_spatial_anchor

최종 수정일

2025-09-15

IP 상태

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

도움을 주신 분들

YuSheng Chang, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

개요

XR_EXT_spatial_anchor 확장 프로그램에 정의된 xrCreateSpatialAnchorEXT 함수를 사용하면 애플리케이션에서 이를 나타내는 XrSpatialEntityEXT 핸들로 공간 앵커를 만들 수 있습니다. 반면 이 확장 프로그램은 대신 XrSpace 핸들로 표현되는 공간 앵커를 만듭니다. 이는 애플리케이션이 다음을 수행하려는 경우에 유용합니다.

  • xrLocateSpaces를 사용하여 앵커의 위치를 가져옵니다.
  • 앵커를 기준으로 다른 공간을 찾습니다.
  • XR_ANDROID_anchor_sharing_export를 사용하여 앵커를 내보냅니다.
  • 애플리케이션이 앵커를 배치했으며 이제 앵커의 위치 (가상 콘텐츠를 연결할 위치)에만 관심이 있고 앵커를 만드는 데 사용된 XrSpatialContextEXT를 통해 발견된 다른 항목의 다른 구성요소에는 관심이 없으므로 애플리케이션이 공간 컨텍스트를 소멸시킬 수 있습니다.

이 확장 프로그램으로 만든 앵커는 XR_ANDROID_device_anchor_persistence 확장 프로그램을 사용하여 유지할 수 없으며 애플리케이션은 대신 XR_EXT_spatial_persistence_operations를 사용해야 합니다. XrPersistedAnchorSpaceInfoANDROID :: anchor가 xrCreateSpatialAnchorSpaceANDROID 또는 xrCreateSpatialAnchorSpaceFromIdANDROID를 사용하여 생성된 경우 런타임은 xrPersistAnchorANDROID에서 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다(must).

공간 앵커의 XrSpace 만들기

공간 앵커 및 공간 만들기

xrCreateSpatialAnchorSpaceANDROID 함수는 다음과 같이 정의됩니다.

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

파라미터 설명

xrCreateSpatialAnchorSpaceANDROID 함수는 XrSpatialEntityIdEXT 및 XrSpace 핸들을 출력하는 앵커를 만듭니다. xrCreateSpatialAnchorSpaceANDROID에는 xrCreateSpatialAnchorEXT와 동일한 유효성 검사 요구사항이 있습니다.

xrCreateSpatialAnchorSpaceANDROID에 전달된 XrSpatialContextEXT가 XR_SPATIAL_CAPABILITY_ANCHOR_EXT로 구성되지 않은 경우 런타임은 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다(must).

xrCreateSpatialAnchorSpaceANDROID로 생성된 앵커의 검색 가능성과 관련하여 xrCreateSpatialAnchorEXT 사양의 마지막 단락이 적용됩니다.

올바른 사용 (암시적)

  • xrCreateSpatialAnchorSpaceANDROID를 호출하기 전에 XR_ANDROID_spatial_anchor_space 확장 프로그램을 사용 설정해야 합니다.
  • session는 유효한 XrSession 핸들이어야 합니다.
  • spatialContext는 유효한 XrSpatialContextEXT 핸들이어야 합니다.
  • createInfo는 유효한 XrSpatialAnchorCreateInfoEXT 구조에 대한 포인터여야 합니다(must).
  • anchorEntityId는 XrSpatialEntityIdEXT 값에 대한 포인터여야 합니다.
  • anchorSpace는 XrSpace 핸들에 대한 포인터여야 합니다.
  • spatialContext는 session에서 생성, 할당 또는 검색되어야 합니다.

반품 코드

성공

  • 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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

기존 공간 앵커에서 XrSpace 만들기

xrCreateSpatialAnchorSpaceFromIdANDROID 함수는 다음과 같이 정의됩니다.

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

파라미터 설명

공간 앵커 엔티티가 이미 존재하는 경우 (예: 지속성으로 인해) 애플리케이션은 공간 엔티티 ID를 제공하여 이러한 공간 앵커에서 XrSpace를 만들 수 있습니다.

xrCreateSpatialAnchorSpaceFromIdANDROID 함수는 XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId 필드에 XrSpatialEntityIdEXT를 제공하여 XrSpace 핸들을 만듭니다.

xrCreateSpatialAnchorSpaceFromIdANDROID에 전달된 XrSpatialContextEXT가 XR_SPATIAL_CAPABILITY_ANCHOR_EXT로 구성되지 않은 경우 런타임은 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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialAnchorSpaceFromIdCreateInfoANDROID 구조는 다음과 같이 정의됩니다.

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • anchorEntityId는 XrSpace를 만들 기존 공간 앵커의 XrSpatialEntityIdEXT입니다.

XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId가 spatialContext의 유효한 ID가 아닌 경우 런타임은 XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT를 반환해야 합니다(must).

XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId가 앵커의 유효한 항목 ID가 아닌 경우 런타임은 XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID를 반환해야 합니다(MUST).

올바른 사용 (암시적)

앵커 수명 주기

XrSpace 핸들의 상위 요소는 XrSession입니다. 즉, 앵커를 나타내는 XrSpace 핸들은 xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext 또는 xrCreateSpatialAnchorSpaceANDROID :: spatialContext가 소멸된 후에도 유효하게 유지됩니다. 공간 엔티티 앵커를 나타내는 XrSpace를 만들면 애플리케이션은 XR_SPATIAL_CAPABILITY_ANCHOR_EXT로 구성된 XrSpatialContextEXT를 소멸시키면서도 xrLocateSpaces를 사용하여 XrSpace를 통해 앵커의 최신 포즈를 계속 가져올 수 있습니다. 즉, 런타임은 이를 나타내는 모든 XrSpace 핸들이 소멸될 때까지 앵커를 계속 추적해야 합니다.

예시 코드

XrSpace로 공간 앵커 만들기

다음 예시 코드는 공간 앵커를 만들고 XrSpace로 반환하는 방법을 보여줍니다.

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

앵커 항목 ID에서 XrSpace 만들기

다음 예시 코드는 기존 앵커 엔티티 ID에서 XrSpace를 만드는 방법을 보여줍니다.

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

새 명령어

새로운 구조

새 enum 상수

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • XrResult 확장:

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • XrStructureType 확장:

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

문제

버전 기록

  • 버전 1, 2025년 9월 15일 (YuSheng Chang, Kyle Chen)

    • 초기 확장 프로그램 설명입니다.