XR_EXT_spatial_image_tracking

이름 문자열

XR_EXT_spatial_image_tracking

확장 프로그램 유형

인스턴스 확장 프로그램

등록된 내선 번호

783

버전

1

승인 상태

비준되지 않음

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

XR_EXT_spatial_entity

도움을 주신 분들

다니엘 구텐베르크, Qualcomm
니하브 자인, Google
자레드 파인더, Google
지펑 리우, ByteDance

개요

이 확장 프로그램은 XR_EXT_spatial_entity 확장 프로그램에 이미지 추적 기능을 제공합니다. 애플리케이션이 입력 참고 이미지 세트로 지정된 특정 평면 이미지를 감지하고 추적할 수 있습니다.

추적된 이미지는 다음 구성요소를 포함하는 공간 항목으로 표현됩니다.

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

애플리케이션은 일반적으로 다음과 같은 패턴으로 공간 이미지 추적 확장 프로그램을 사용합니다.

  • 애플리케이션은 먼저 미리 로드된 참고 이미지 데이터 세트를 기반으로 하나 이상의 XrSpatialImageTrackingDatabaseEXT 핸들을 만듭니다.
  • 그런 다음 애플리케이션은 이전에 만든 XrSpatialImageTrackingDatabaseEXT 핸들을 기반으로 XrSpatialContextEXT 핸들을 만듭니다.
  • 그런 다음 애플리케이션은 참고 이미지 데이터를 해제하여 메모리 소비를 줄입니다.
  • 애플리케이션은 공간 항목 액세스 패턴에 따라 이미지를 검색하고 쿼리합니다.
  • 애플리케이션은 추가 참고 이미지 세트를 로드하고 추가 XrSpatialImageTrackingDatabaseEXT를 만든 후 이로부터 XrSpatialContextEXT를 만들어 런타임에 감지 및 추적 가능한 이미지 세트를 동적으로 확장할 수 있습니다.
  • 애플리케이션은 XrSpatialImageTrackingDatabaseEXT 핸들을 제거하여 런타임 시 감지 및 추적 가능한 이미지 집합을 동적으로 줄일 수 있습니다.
  • 애플리케이션은 XrSpatialContextEXT 핸들을 소멸시켜 런타임에 동적으로 감지 및 추적 가능한 이미지 집합을 줄일 수 있습니다.

런타임 지원

런타임은 다음 기능을 나열하여 xrEnumerateSpatialCapabilitiesEXT를 사용한 이미지 추적 기능 지원을 알려야 합니다(must).

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

구성

평면 이미지의 감지 및 추적을 사용 설정하려면 애플리케이션이 xrCreateSpatialContextAsyncEXT 함수를 호출할 때 XrSpatialContextCreateInfoEXT :: capabilityConfigs에서 XrSpatialCapabilityConfigurationImageTrackingEXT 구조를 전달하고 각 XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases에서< XrSpatialImageTrackingDatabaseEXT 구조의 배열을 전달할 수 있습니다.

입력 이미지 세트 생성

감지 및 추적할 참고 이미지를 지정하려면 애플리케이션이 입력 참고 이미지 세트를 하나 이상 만들어야 합니다. 입력 참고 이미지 집합은 XrSpatialImageTrackingDatabaseEXT 핸들로 표현되며 하나 이상의 이미지를 포함합니다.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

XrSpatialImageTrackingDatabaseEXT 핸들은 사용자 환경에서 여러 공간 이미지를 검색하고 업데이트하는 리소스를 나타냅니다. 애플리케이션은 이 핸들을 사용하여 이 확장 프로그램의 다른 함수를 통해 공간 이미지를 검색하고 업데이트할 수 있습니다.

공간 이미지 추적 데이터베이스 만들기

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

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

파라미터 설명

  • session는 공간 이미지 추적 데이터베이스가 활성화되는 XrSession입니다.
  • createInfo는 공간 이미지 추적 데이터베이스 매개변수를 지정하는 데 사용되는 XrSpatialImageTrackingDatabaseCreateInfoEXT입니다.
  • future는 XrFutureEXT에 대한 포인터입니다.

애플리케이션은 xrCreateSpatialImageTrackingDatabaseAsyncEXT 함수를 사용하여 XrSpatialImageTrackingDatabaseEXT 핸들을 만들고 createInfo를 사용하여 이미지 추적 데이터베이스의 입력 참고 이미지 집합을 구성할 수 있습니다.

입력 참고 이미지의 XrSpatialReferenceImageEXT :: format가 xrEnumerateSpatialReferenceImageFormatsEXT에 의해 열거되지 않는 경우 런타임은 XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT를 반환해야 합니다(must).

입력 참고 이미지의 XrSpatialReferenceImageEXT :: planes 배열을 XrSpatialReferenceImageEXT의 참고 이미지 메타데이터에 따라 평가할 수 없는 경우 런타임은 XR_ERROR_SPATIAL_IMAGE_INVALID_EXT를 반환해야 합니다(must).

입력 참고 이미지의 XrSpatialReferenceImageEXT :: planes 배열이 XrSpatialReferenceImageEXT :: format에 색상 채널이 있는 만큼의 평면을 정확하게 제공하지 않는 경우 런타임은 XR_ERROR_SPATIAL_IMAGE_INVALID_EXT를 반환해야 합니다(must).

런타임이 이미지 추적 기능에 대한 애플리케이션 액세스를 제어하는 권한 시스템을 적용하는 경우, 런타임은 이러한 권한이 이 애플리케이션에 부여되지 않은 경우 XR_ERROR_PERMISSION_INSUFFICIENT를 반환해야 합니다(must).

이 함수는 비동기 작업을 시작하고 xrPollFutureEXT 및 관련 함수와 함께 사용할 수 있는 상응하는 XrFutureEXT를 만듭니다. 이 함수의 반환 값은 매개변수가 비동기 작업을 예약하는 데 허용되는지 여부만 나타냅니다. 해당 완료 함수는 xrCreateSpatialImageTrackingDatabaseCompleteEXT이며, 이 함수의 Future가 READY 상태일 때 사용할 수 있습니다. 이 함수는 완료 구조 XrCreateSpatialImageTrackingDatabaseCompletionEXT에서 출력을 채웁니다.

올바른 사용 (암시적)

반품 코드

성공

  • 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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • spatialReferenceImageCount은 spatialReferenceImages 배열의 요소 수입니다.
  • spatialReferenceImages은 XrSpatialReferenceImageEXT의 배열입니다.

XrSpatialImageTrackingDatabaseCreateInfoEXT 구조는 XrSpatialImageTrackingDatabaseEXT 핸들을 만드는 정보를 설명합니다.

각 XrSpatialImageTrackingDatabaseEXT는 XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 배열에 하나 이상의 XrSpatialReferenceImageEXT를 사용하여 생성되어야 합니다.

올바른 사용 (암시적)

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

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

파라미터 설명

xrCreateSpatialImageTrackingDatabaseCompleteEXT는 xrCreateSpatialImageTrackingDatabaseAsyncEXT에서 시작한 비동기 작업을 완료합니다.

런타임은 완료된 후 이 xrCreateSpatialImageTrackingDatabaseAsyncEXT 호출의 XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 입력 배열에서 제공한 XrSpatialReferenceImagePlaneEXT :: buffer 포인터에 액세스하면 안 됩니다. 애플리케이션은 xrCreateSpatialImageTrackingDatabaseAsyncEXT가 완료된 후 XrSpatialReferenceImagePlaneEXT :: buffer 데이터를 확보하여 메모리 사용량을 줄일 수 있습니다.

future가 준비 상태가 아니면 런타임은 XR_ERROR_FUTURE_PENDING_EXT를 반환해야 합니다(MUST). future가 이미 완료되었거나 취소된 경우 런타임은 XR_ERROR_FUTURE_INVALID_EXT를 반환해야 합니다(MUST).

올바른 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • 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_VALIDATION_FAILURE

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

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

회원 설명

향후 반품 코드

futureResult 값:

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

futureResult가 성공 코드인 경우 database는 유효한 핸들이어야 합니다. database가 유효한 경우 xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session의 수명 주기 내에서만 또는 애플리케이션이 xrDestroySpatialImageTrackingDatabaseEXT를 사용하여 database를 소멸시킬 때까지(둘 중 먼저 발생하는 시점까지) 유효합니다.

올바른 사용 (암시적)

공간 이미지 추적 데이터베이스 폐기

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

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

파라미터 설명

애플리케이션은 공간 이미지 검색 및 업데이트 작업을 완료한 후 xrDestroySpatialImageTrackingDatabaseEXT 함수를 호출하여 database 핸들과 기본 리소스를 해제할 수 있습니다.

애플리케이션은 xrDestroySpatialContextEXT를 호출하기 전에 xrDestroySpatialImageTrackingDatabaseEXT 함수를 호출할 수 있습니다. 런타임은 이 소멸된 XrSpatialImageTrackingDatabaseEXT에서 관리하는 이미지를 더 이상 보고하지 않아야 합니다(MUST). 런타임은 다른 데이터베이스에서 관리하는 이미지를 계속 보고해야 합니다(MUST).

런타임은 xrCreateSpatialDiscoverySnapshotCompleteEXT에서 반환한 탐색 스냅샷에 소멸되었거나 유효하지 않은 XrSpatialImageTrackingDatabaseEXT 핸들과 관련된 이미지가 포함되지 않도록 해야 합니다. 이는 애플리케이션이 xrCreateSpatialDiscoverySnapshotAsyncEXT를 호출한 후 핸들이 소멸된 경우에도 마찬가지입니다. 공간 스냅샷의 데이터는 변경할 수 없으므로 애플리케이션은 database를 소멸시키기 전에 생성된 모든 XrSpatialSnapshotEXT 핸들을 소멸시켜야 합니다(should). 그렇지 않으면 애플리케이션은 xrQuerySpatialComponentDataEXT를 사용할 때 잘못된 XrSpatialImageTrackingDatabaseEXT 핸들을 수신할 수 있습니다(may).

애플리케이션은 xrDestroySpatialContextEXT 함수를 호출하여 XrSpatialContextEXT 핸들을 해제한 후 XrSpatialContextEXT가 생성된 XrSpatialImageTrackingDatabaseEXT 핸들을 소멸시킬 수 있습니다. 런타임은 XrSpatialContextEXT가 소멸될 때 이러한 XrSpatialImageTrackingDatabaseEXT 핸들을 암시적으로 소멸시키면 안 됩니다(MUST NOT).

XrSpatialContextEXT 및 XrSpatialImageTrackingDatabaseEXT의 전체 기간을 독립적으로 관리하면 애플리케이션에서 비용이 많이 드는 생성 절차를 다시 실행할 필요 없이 이전에 생성된 XrSpatialImageTrackingDatabaseEXT 핸들을 재사용할 수 있습니다.

예를 들어 XrSpatialContextEXT를 소멸시킨 후 동일한 XrSpatialImageTrackingDatabaseEXT를 사용하여 다른 XrSpatialContextEXT를 다시 만들면 다른 초기화 절차를 실행하지 않고도 이미지 추적을 일시중지하고 재개할 수 있습니다.

올바른 사용 (암시적)

스레드 안전

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

반품 코드

성공

  • XR_SUCCESS

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

입력 이미지 형식 지원

애플리케이션은 xrEnumerateSpatialReferenceImageFormatsEXT를 호출하여 지원되는 입력 참고 이미지 형식 목록을 가져와야 합니다(SHOULD).

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

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

파라미터 설명

  • instance은 XrInstance의 핸들입니다.
  • systemId는 입력 참고 이미지 형식이 열거되는 XrSystemId입니다.
  • capability는 입력 참고 이미지 형식이 열거되는 XrSpatialCapabilityEXT입니다.
  • formatCapacityInput는 formats 배열의 용량입니다. 필요한 용량을 가져오라는 요청을 나타내려면 0으로 설정합니다.
  • formatCountOutput은 형식 수 또는 formatCapacityInput가 부족한 경우 필요한 용량입니다.
  • formats은 XrSpatialReferenceImageFormatEXT의 배열입니다. formatCapacityInput가 0인 경우 NULL일 수 있습니다.
  • 필요한 formats 크기를 가져오는 방법에 관한 자세한 설명은 버퍼 크기 매개변수 섹션을 참고하세요.

애플리케이션은 xrEnumerateSpatialReferenceImageFormatsEXT를 사용하여 특정 XrSpatialCapabilityEXT에 대해 특정 XrSystemId에서 지원하는 입력 참고 이미지 형식 목록을 열거할 수 있습니다.

런타임은 instance에 사용 설정되지 않은 확장 프로그램의 형식을 열거하면 안 됩니다(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_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

모든 확장 프로그램에서 지원하는 모든 참고 이미지 형식의 전체 목록은 XrSpatialReferenceImageFormatEXT를 참고하세요.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

XrSpatialReferenceImageFormatEXT 열거형은 런타임에서 지원할 수 있는 입력 참고 이미지 형식을 식별합니다.

최소한 XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT 값과 XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT 값은 지원되어야 합니다.

열거형의 의미는 다음과 같습니다.

열거형 설명

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT: RGBA 버퍼입니다. 이 형식은 메모리의 픽셀 데이터 레이아웃을 보장하지 않습니다. 픽셀은 해당 XrSpatialReferenceImagePlaneEXT 구조에서 제공하는 메타데이터를 사용하여 액세스해야 합니다. 각 픽셀 색상 채널의 크기는 8비트이므로 각 픽셀의 크기는 32비트입니다.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT: RGB 버퍼입니다. 이 형식은 메모리의 픽셀 데이터 레이아웃을 보장하지 않습니다. 픽셀은 해당 XrSpatialReferenceImagePlaneEXT 구조에서 제공하는 메타데이터를 사용하여 액세스해야 합니다. 각 픽셀 색상 채널의 크기는 8비트이므로 각 픽셀의 크기는 24비트입니다.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT: 4:2:0 패턴 크로마 서브샘플링된 YUV 버퍼입니다. 이 형식은 메모리의 픽셀 데이터 레이아웃을 보장하지 않습니다. 픽셀은 해당 XrSpatialReferenceImagePlaneEXT 구조에서 제공하는 메타데이터를 사용하여 액세스해야 합니다. 디코딩된 각 RGB 픽셀 색상 채널의 크기는 8비트이므로 각 픽셀의 크기는 24비트입니다.

입체 이미지 추적 설정

이 확장 프로그램은 애플리케이션이 이미지 추적 기능을 구성하는 데 사용할 수 있는 선택적 구조를 제공합니다.

정적 이미지 최적화

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

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • optimizeForStaticImage는 이미지가 움직이는지 여부를 나타내는 XrBool32입니다. XR_TRUE 값은 이미지가 움직이지 않음을 나타냅니다.

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 기능에 대해 xrEnumerateSpatialCapabilityFeaturesEXT에서 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT를 열거하는 경우 애플리케이션은 XrSpatialImageStaticOptimizationEXT를 XrSpatialImageTrackingDatabaseCreateInfoEXT :: next 체인 또는 XrSpatialReferenceImageEXT :: next에 연결할 수 있습니다(can).

애플리케이션이 XrSpatialImageStaticOptimizationEXT를 XrSpatialImageTrackingDatabaseCreateInfoEXT 구조에 연결하는 경우 optimizeForStaticImage가 XR_TRUE로 설정되어 있으면 런타임은 해당 XrSpatialImageTrackingDatabaseEXT의 모든 이미지가 정적이라고 가정해야 합니다(must). 마찬가지로 optimizeForStaticImage가 XR_FALSE로 설정된 경우 런타임은 XrSpatialImageTrackingDatabaseEXT의 모든 이미지가 정적이지 않다고 가정해야 합니다(must).

애플리케이션이 XrSpatialImageStaticOptimizationEXT를 XrSpatialReferenceImageEXT 구조에 연결하는 경우 런타임은 optimizeForStaticImage가 XR_TRUE로 설정된 경우 이 참고 이미지가 정적이라고 가정해야 합니다(must). 따라서 optimizeForStaticImage가 XR_FALSE로 설정된 경우 런타임은 이 참고 이미지가 정적이지 않다고 가정해야 합니다(must). XrSpatialImageStaticOptimizationEXT 구조를 XrSpatialReferenceImageEXT 구조에 연결하는 것이 XrSpatialImageTrackingDatabaseCreateInfoEXT 구조에 연결하는 것보다 우선합니다.

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT가 XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 기능의 xrEnumerateSpatialCapabilityFeaturesEXT에 의해 열거되지 않고 애플리케이션이 XrSpatialImageStaticOptimizationEXT 구조를 적용 가능한 다음 체인에 연결하는 경우 런타임은 xrCreateSpatialImageTrackingDatabaseAsyncEXT에서 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다(must).

이렇게 하면 런타임에서 더 정확한 포즈와 크기를 생성할 수 있습니다.

이렇게 하면 런타임에서 전력 소비를 줄일 수 있습니다.

올바른 사용 (암시적)

참고 이미지 너비

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

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • physicalWidth는 설정할 실제 너비(미터)를 나타내는 float 값입니다.

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT 기능에 대해 xrEnumerateSpatialCapabilityFeaturesEXT에서 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT를 열거하는 경우 애플리케이션은 XrSpatialImageSizeEXT를 XrSpatialImageTrackingDatabaseCreateInfoEXT :: next 또는 XrSpatialReferenceImageEXT :: next에 연결할 수 있습니다.

애플리케이션이 XrSpatialImageSizeEXT를 XrSpatialImageTrackingDatabaseCreateInfoEXT 구조에 연결하는 경우 런타임은 해당 XrSpatialImageTrackingDatabaseEXT의 모든 이미지의 너비가 physicalWidth미터이고 높이가 XrSpatialReferenceImageEXT :: width 및 XrSpatialReferenceImageEXT :: height를 통해 암시적으로 제공된 가로세로 비율에 따른다고 가정해야 합니다(must).

애플리케이션이 XrSpatialImageSizeEXT를 XrSpatialReferenceImageEXT 구조에 연결하는 경우 런타임은 이 참고 이미지의 너비가 physicalWidth미터이고 XrSpatialReferenceImageEXT :: width 및 XrSpatialReferenceImageEXT :: height를 통해 암시적으로 제공된 가로세로 비율에 따른 높이를 갖는다고 가정해야 합니다(must). XrSpatialImageSizeEXT 구조를 XrSpatialReferenceImageEXT 구조에 연결하는 것이 XrSpatialImageTrackingDatabaseCreateInfoEXT 구조에 연결하는 것보다 우선합니다.

이렇게 하면 런타임에서 더 정확한 포즈와 크기를 반환할 수 있습니다.

런타임은 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT 또는 XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT 또는 둘 다를 열거해야 합니다(must).

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT가 xrEnumerateSpatialCapabilityFeaturesEXT로 열거되는 경우 런타임은 애플리케이션이 적용 가능한 다음 체인의 일부로 XrSpatialImageSizeEXT 구조를 제공하지 않은 이미지에 대해 이미지 크기를 자동으로 제공해야 합니다(must).

런타임에서 이미지 크기를 자동으로 정확하게 생성하려면 특정 기기 기능과 전제 조건이 필요할 수 있습니다(예: 스테레오 카메라, 정확하게 보정된 카메라 외부 및 내부 매개변수).

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT가 xrEnumerateSpatialCapabilityFeaturesEXT에 의해 열거되지 않는 경우 애플리케이션은 모든 이미지에 명시적인 크기가 제공되도록 XrSpatialImageSizeEXT 구조를 관련 다음 체인에 연결해야 합니다. 그렇지 않으면 런타임은 xrCreateSpatialImageTrackingDatabaseAsyncEXT에서 XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT를 반환해야 합니다.

올바른 사용 (암시적)

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

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

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • capability은 XrSpatialCapabilityEXT이며 XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT여야 합니다.
  • enabledComponentCount는 enabledComponents의 요소 수를 지정하는 uint32_t입니다.
  • enabledComponents는 이 기능에 사용 설정할 구성요소를 지정하는 XrSpatialComponentTypeEXT의 배열입니다.
  • imageTrackingDatabaseCount는 imageTrackingDatabases의 요소 수를 지정하는 unint32_t입니다.
  • imageTrackingDatabases는 공간 컨텍스트에 사용 설정할 이미지 추적 데이터베이스를 지정하는 XrSpatialImageTrackingDatabaseEXT 핸들의 배열입니다.

이미지 추적이 지원되는 경우 xrCreateSpatialContextAsyncEXT를 호출할 때 XrSpatialContextCreateInfoEXT :: capabilityConfigs에 XrSpatialCapabilityConfigurationImageTrackingEXT 구조가 전달되면 런타임은 이미지 추적을 사용 설정해야 합니다(must).

XrSpatialCapabilityConfigurationImageTrackingEXT 구조를 사용하면 애플리케이션이 imageTrackingDatabases의 XrSpatialImageTrackingDatabaseEXT 핸들로 표현되는 참고 이미지를 검색할 수 있습니다.

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT가 xrEnumerateSpatialCapabilitiesEXT에 의해 열거되지 않으면 런타임은 XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT를 반환해야 합니다(must).

올바른 사용 (암시적)

  • XR_EXT_spatial_image_tracking 확장 프로그램은 XrSpatialCapabilityConfigurationImageTrackingEXT를 사용하기 전에 사용 설정해야 합니다.
  • type은(는) XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT여야 합니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.
  • capability는 유효한 XrSpatialCapabilityEXT 값이어야 합니다.
  • enabledComponents는 유효한 XrSpatialComponentTypeEXT 값 enabledComponentCount개의 배열에 대한 포인터여야 합니다.
  • imageTrackingDatabases는 유효한 imageTrackingDatabaseCount XrSpatialImageTrackingDatabaseEXT 핸들 배열의 포인터여야 합니다.
  • enabledComponentCount 매개변수는 0보다 커야 합니다.
  • imageTrackingDatabaseCount 매개변수는 0보다 커야 합니다.

공간 참고 이미지

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

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

파라미터 설명

  • bufferSize는 buffer 배열의 크기입니다.
  • buffer는 평면 데이터를 나타내는 uint8_t 데이터의 배열입니다.
  • rowStride는 연속된 픽셀 데이터 행의 두 시작 위치 사이의 바이트 거리입니다.
  • pixelStride는 연속된 두 픽셀 사이의 바이트 거리입니다.

런타임은 rowStride 및 pixelStride 매개변수가 제공하는 패턴에 따라 buffer에 액세스해야 합니다(MUST).

애플리케이션은 이 XrSpatialReferenceImagePlaneEXT의 의미 있는 픽셀만 런타임에서 추출하도록 rowStride 및 pixelStride를 설정해야 합니다(must).

올바른 사용 (암시적)

  • XrSpatialReferenceImagePlaneEXT를 사용하기 전에 XR_EXT_spatial_image_tracking 확장 프로그램을 사용 설정해야 합니다.
  • buffer는 bufferSize uint8_t 값 배열에 대한 포인터여야 합니다.
  • bufferSize 매개변수는 0보다 커야 합니다.

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

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

파라미터 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • width는 참고 이미지의 픽셀 너비입니다.
  • height은 참고 이미지의 픽셀 높이입니다.
  • format은 이미지 형식을 나타내는 XrSpatialReferenceImageFormatEXT입니다.
  • planeCount은 planes 배열의 요소 수입니다.
  • planes는 이미지 데이터의 평면을 나타내는 XrSpatialReferenceImagePlaneEXT 구조의 배열입니다.

애플리케이션은 XrSpatialImageTrackingDatabaseEXT 핸들을 만들 때 XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages를 통해 xrCreateSpatialImageTrackingDatabaseAsyncEXT 함수에 전달할 단일 입력 참고 이미지를 각각 나타내는 XrSpatialReferenceImageEXT 구조를 하나 이상 만들 수 있습니다.

XrSpatialReferenceImagePlaneEXT :: buffer 데이터는 애플리케이션에서 왼쪽에서 오른쪽, 위에서 아래로 픽셀 순서로 제공되어야 합니다.

애플리케이션은 XrSpatialReferenceImageEXT :: format의 각 색상 채널에 대해 XrSpatialReferenceImageEXT :: planes 배열에 XrSpatialReferenceImagePlaneEXT 구조를 제공해야 합니다.

올바른 사용 (암시적)

보장 구성요소

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT를 지원하는 런타임은 다음 공간 구성요소를 이러한 기능으로 검색된 모든 항목의 보장된 구성요소로 제공해야 하며(must) xrEnumerateSpatialCapabilityComponentTypesEXT에서 열거해야 합니다.

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

이미지 2D 구성요소

데이터를 쿼리하는 구성요소 목록 구조체

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

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

파라미터 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • imageCount은 images 배열의 요소 수입니다.
  • images는 XrSpatialImage2DDataEXT의 배열입니다.

XrSpatialComponentImage2DListEXT가 XrSpatialComponentDataQueryResultEXT :: next 체인에 있지만 XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT가 XrSpatialComponentDataQueryConditionEXT :: componentTypes에 포함되지 않은 경우 런타임은 xrQuerySpatialComponentDataEXT에서 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다(must).

imageCount가 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput보다 작은 경우 런타임은 xrQuerySpatialComponentDataEXT에서 XR_ERROR_SIZE_INSUFFICIENT를 반환해야 합니다(must).

올바른 사용 (암시적)

  • XR_EXT_spatial_image_tracking 확장 프로그램은 XrSpatialComponentImage2DListEXT를 사용하기 전에 사용 설정해야 합니다.
  • type은(는) XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT여야 합니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.
  • images는 imageCount XrSpatialImage2DDataEXT 구조의 배열에 대한 포인터여야 합니다.
  • imageCount 매개변수는 0보다 커야 합니다.
구성요소 데이터

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

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

파라미터 설명

애플리케이션은 imageTrackingDatabase를 사용하여 이전에 생성된 XrSpatialImageTrackingDatabaseEXT 중 이 XrSpatialImage2DDataEXT 구조의 참고 이미지를 포함하는 항목을 식별할 수 있습니다. 해당 XrSpatialImageTrackingDatabaseEXT의 경우 애플리케이션은 referenceImageIndex를 사용하여 이 XrSpatialImage2DDataEXT 구조의 XrSpatialReferenceImageEXT를 XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages 배열의 입력 순서와 일치시켜 식별할 수 있습니다.

모든 활성 데이터베이스 집합으로 정의된 참고 이미지 집합에는 중복 이미지가 포함되어서는 안 됩니다. 중복 이미지를 포함하면 검색 또는 추적 동작에 부정적인 영향을 미칠 수 있습니다. 즉, 일관되지 않거나 여러 색인이 반환될 수 있습니다.

올바른 사용 (암시적)

구성

일부 기능의 XrSpatialCapabilityComponentTypesEXT :: componentTypes에 XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT가 열거된 경우 애플리케이션은 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 목록에 enum 값을 포함하여 이를 사용 설정할 수 있습니다. 이 구성요소는 XrSpatialCapabilityConfigurationBaseHeaderEXT의 다음 체인에 포함하기 위해 특별한 구성이 필요하지 않습니다.

제한된 2D 구성요소

경계가 지정된 2D 구성요소는 이 구성요소가 있는 항목으로 표현되는 공간 이미지의 중심과 범위를 제공합니다. 경계가 있는 2D 구성요소에 관한 자세한 내용은 경계가 있는 2D를 참고하세요.

예제 코드

공간 이미지 및 쿼리 구성요소 데이터 탐색

다음 예시 코드는 이미지 추적 기능의 공간 항목을 검색하고 구성요소 데이터를 쿼리하는 방법을 보여줍니다.

XrInstance instance; // Previously initialized
XrSystemId systemId; // Previously initialized
XrSession session; // Previously initialized

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrFrameState frameState;  // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

새 객체 유형

새 명령어

새로운 구조

새 enum

새 enum 상수

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION
  • XrObjectType 확장:

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT
  • XrResult 확장:

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XrSpatialCapabilityEXT 확장:

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT
  • XrSpatialCapabilityFeatureEXT 확장:

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT
  • XrSpatialComponentTypeEXT 확장:

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XrStructureType 확장:

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

문제

버전 기록

  • 버전 1, 2025년 4월 22일 (다니엘 구텐베르크, Qualcomm)

    • 초기 확장 프로그램 설명