XR_ANDROID_trackables_image
이름 문자열
XR_ANDROID_trackables_image
확장 프로그램 유형
인스턴스 확장
등록된 확장 프로그램 번호
710
버전
1
비준 상태
비준되지 않음
확장 프로그램 및 버전 종속 항목
XR_EXT_future
및
XR_ANDROID_trackables
최종 수정일
2025-04-08
IP 상태
알려진 IP 소유권 주장이 없습니다.
도움을 주신 분들
크리스토퍼 도어(Google)
레바나 첸(Google)
제러드 파인더(Google)
스펜서 퀸(Google)
니하브 제인(Google)
디에고 티팔디(Google)
다니엘 구텐베르크(Qualcomm)
마크 바다시(Qualcomm)
마르쿠스 비르크너(Qualcomm)
막시밀리안 메이어(Qualcomm)
개요
이 확장 프로그램을 사용하면 입력 참조 이미지 세트로 지정된 평면 이미지를 추적할 수 있습니다.
권한
Android 애플리케이션은 이 확장 프로그램이 XR_ANDROID_trackables에 종속되고 환경의 지오메트리를 노출하므로 매니페스트에 android.permission.SCENE_UNDERSTANDING_COARSE 권한이 나열되어야 합니다. android.permission.SCENE_UNDERSTANDING_COARSE 권한은 위험한 권한으로 간주됩니다.
(보호 수준: 위험)
시스템 기능 검사
XrSystemImageTrackingPropertiesANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrSystemImageTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsImageTracking;
XrBool32 supportsPhysicalSizeEstimation;
uint32_t maxTrackedImageCount;
uint32_t maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;
회원 설명
type은 이 구조의 XrStructureType입니다.next는NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다. 구조 체인에 관한 자세한 내용은 확장되는 구조 ( XrSystemProperties)를 참고하세요.supportsImageTracking는 현재 시스템이 이미지 추적 기능을 제공하는지 나타내는XrBool32입니다.supportsPhysicalSizeEstimation는 현재 시스템에서 이미지 크기 추정치를 제공하는지 여부를 나타내는XrBool32입니다.maxTrackedImageCount은 동시에 추적할 수 있는 총 최대 이미지 수입니다.maxLoadedImageCount는 모든 데이터베이스에서 로드할 수 있는 총 최대 참조 이미지 수입니다.
애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemImageTrackingPropertiesANDROID 구조로 XrSystemProperties를 확장하여 시스템이 이미지 추적을 지원하는지 검사할 수 있습니다 . 런타임은 supportsImageTracking이 XR_FALSE인 경우에만 이미지 트래커 생성에 XR_ERROR_FEATURE_UNSUPPORTED를 반환해야 합니다 .
런타임이 이미지 추적을 지원하는 경우 언제든지 maxTrackedImageCount 추적 이미지를 지원해야 합니다.
런타임이 이미지 추적을 지원하는 경우 언제든지 로드된 maxLoadedImageCount 이미지를 지원해야 합니다.
런타임이 이미지 크기 추정을 지원하는 경우 애플리케이션은 XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0를 설정하여 크기 추정 사용을 나타낼 수 있습니다(있음). 그렇지 않으면 애플리케이션이 XrTrackableImageDatabaseEntryANDROID :: physicalWidth을 양수 값으로 설정해야 합니다. 그렇지 않으면 XR_ERROR_VALIDATION_FAILURE이 반환됩니다.
유효한 사용 (암시적)
-
XR_ANDROID_trackables_image확장 프로그램은 XrSystemImageTrackingPropertiesANDROID를 사용하기 전에 사용 설정해야 합니다. -
type은XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID이어야 합니다. -
next은NULL이거나 구조체 체인의 다음 구조체를 가리키는 유효한 포인터여야 합니다.
데이터베이스 만들기
애플리케이션은 하나 이상의 XrTrackableImageDatabaseEntryANDROID 구조를 만들고 XrTrackableImageDatabaseCreateInfoANDROID 구조를 통해 xrCreateTrackableImageDatabaseAsyncANDROID 함수에 전달하여 XrTrackableImageDatabaseANDROID 핸들을 만들 수 있습니다.
애플리케이션은 XrTrackableImageDatabaseANDROID 핸들을 만들 때 하나 이상의 XrTrackableImageDatabaseEntryANDROID를 제공해야 합니다.
XrTrackableImageDatabaseANDROID는 환경에서 검색하고 추적할 수 있는 처리된 참조 이미지 집합을 나타내는 핸들입니다.
XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)
XrTrackableImageDatabaseEntryANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrTrackableImageDatabaseEntryANDROID {
XrStructureType type;
const void* next;
XrTrackableImageTrackingModeANDROID trackingMode;
float physicalWidth;
uint32_t imageWidth;
uint32_t imageHeight;
XrTrackableImageFormatANDROID format;
uint32_t bufferSize;
const uint8_t* buffer;
} XrTrackableImageDatabaseEntryANDROID;
회원 설명
type은 이 구조의 XrStructureType입니다.next는NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.trackingMode는 추적에 원하는 모드를 나타내는 XrTrackableImageTrackingModeANDROID입니다.physicalWidth는 이미지의 너비를 미터 단위로 나타냅니다. 0인 경우 이미지 크기가 온라인으로 추정됩니다.imageWidth는 이미지의 너비를 픽셀 단위로 나타냅니다.imageHeight는 이미지의 높이를 픽셀 단위로 나타냅니다.format는buffer의 이미지 데이터 형식을 나타내는 XrTrackableImageFormatANDROID입니다 .bufferSize는buffer의 바이트 길이를 나타냅니다 .buffer은 참고 이미지 픽셀 데이터가 포함된uint8_t버퍼입니다.buffer의 콘텐츠는 xrCreateTrackableImageDatabaseAsyncANDROID로 시작되고 xrCreateTrackableImageDatabaseCompleteANDROID로 완료되는 데이터베이스 생성 비동기 작업 기간 동안 유효해야 합니다 .
XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation이 XR_TRUE인 경우 애플리케이션은 physicalWidth을 0으로 설정하여 온라인 크기 추정을 요청할 수 있습니다 .
런타임은 bufferSize이 항목의 imageWidth, imageHeight, format에 기반한 예상 크기와 일치하지 않는 경우 xrCreateTrackableImageDatabaseAsyncANDROID에서 XR_ERROR_VALIDATION_FAILURE를 반환할 수 있습니다 .
유효한 사용 (암시적)
- XrTrackableImageDatabaseEntryANDROID를 사용하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
type은XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID이어야 합니다. -
next은NULL이거나 구조체 체인의 다음 구조체를 가리키는 유효한 포인터여야 합니다. -
trackingMode은 유효한 XrTrackableImageTrackingModeANDROID 값이어야 합니다. -
format은(는) 유효한 XrTrackableImageFormatANDROID 값이어야 must 합니다. -
buffer은bufferSizeuint8_t값의 배열을 가리키는 포인터여야 합니다. -
bufferSize매개변수는0보다 커야 합니다.
XrTrackableImageDatabaseCreateInfoANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t entryCount;
const XrTrackableImageDatabaseEntryANDROID* entries;
} XrTrackableImageDatabaseCreateInfoANDROID;
회원 설명
type은 이 구조의 XrStructureType입니다.next는NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.entryCount는entries배열의 요소 수를 지정하는uint32_t입니다.entries은 XrTrackableImageDatabaseEntryANDROID 구조의 배열입니다.
유효한 사용 (암시적)
- XrTrackableImageDatabaseCreateInfoANDROID를 사용하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
type은XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID이어야 합니다. -
next은NULL이거나 구조체 체인의 다음 구조체를 가리키는 유효한 포인터여야 합니다. -
entries은 유효한 XrTrackableImageDatabaseEntryANDROID 구조의 배열을 가리키는 포인터여야 합니다.entryCount -
entryCount매개변수는0보다 커야 합니다.
XrCreateTrackableImageDatabaseCompletionANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
회원 설명
type은 이 구조의 XrStructureType입니다.next는NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.futureResult는 비동기 작업의 XrResult입니다.database은 생성된 XrTrackableImageDatabaseANDROID 핸들입니다.
향후 반환 코드
futureResult 값:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
유효한 사용 (암시적)
-
XR_ANDROID_trackables_image확장 프로그램은 XrCreateTrackableImageDatabaseCompletionANDROID를 사용하기 전에 사용 설정해야 합니다. -
type은XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID이어야 합니다. -
next은NULL이거나 구조체 체인의 다음 구조체를 가리키는 유효한 포인터여야 합니다. -
futureResult은 유효한 XrResult 값이어야 합니다. -
database은 유효한 XrTrackableImageDatabaseANDROID 핸들이어야 합니다.
xrCreateTrackableImageDatabaseAsyncANDROID 함수는 다음과 같이 정의됩니다.
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
매개변수 설명
session는 이전에 xrCreateSession으로 만든 XrSession의 핸들입니다 .createInfo는 XrTrackableImageDatabaseCreateInfoANDROID 구조체에 대한 포인터입니다.future은 생성된XrFutureEXT에 대한 포인터입니다 .
유효한 사용 (암시적)
- xrCreateTrackableImageDatabaseAsyncANDROID를 호출하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
session은 유효한 XrSession 핸들이어야 합니다. -
createInfo은 유효한 XrTrackableImageDatabaseCreateInfoANDROID 구조체를 가리키는 포인터여야 합니다. -
future은XrFutureEXT값에 대한 포인터여야 합니다.
반환 코드
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
xrCreateTrackableImageDatabaseCompleteANDROID 함수는 다음과 같이 정의됩니다.
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
매개변수 설명
session는 이전에 xrCreateSession으로 만든 XrSession의 핸들입니다 .future는 완료할 미래의XrFutureEXT입니다.completion은 작업 결과를 포함하는 XrCreateTrackableImageDatabaseCompletionANDROID 구조체에 대한 포인터입니다.
유효한 사용 (암시적)
- xrCreateTrackableImageDatabaseCompleteANDROID를 호출하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
session은 유효한 XrSession 핸들이어야 합니다. -
completion은 XrCreateTrackableImageDatabaseCompletionANDROID 구조체에 대한 포인터여야 합니다.
반환 코드
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
xrDestroyTrackableImageDatabaseANDROID 함수는 다음과 같이 정의됩니다.
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
매개변수 설명
database는 소멸시킬 XrTrackableImageDatabaseANDROID 핸들입니다.
유효한 사용 (암시적)
- xrDestroyTrackableImageDatabaseANDROID를 호출하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
database은 유효한 XrTrackableImageDatabaseANDROID 핸들이어야 합니다.
스레드 안전
database및 모든 하위 핸들에 대한 액세스는 외부에서 동기화해야 합니다.
반환 코드
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
추적 이미지
이 확장 프로그램은 XrTrackableTypeANDROID에 XR_TRACKABLE_TYPE_IMAGE_ANDROID를 추가합니다 .
애플리케이션은 xrCreateTrackableTrackerANDROID를 호출하고 XrTrackableTrackerCreateInfoANDROID :: trackableType에서 추적 가능 유형으로 XR_TRACKABLE_TYPE_IMAGE_ANDROID를 지정하여 XrTrackableTrackerANDROID를 만들 수 있습니다.
런타임은 XrTrackableTrackerCreateInfoANDROID :: trackableType이 XR_TRACKABLE_TYPE_IMAGE_ANDROID이고 XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking이 xrGetSystemProperties를 통해 XR_FALSE를 반환하는 경우 XR_ERROR_FEATURE_UNSUPPORTED를 반환해야 합니다 .
XrTrackableImageConfigurationANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrTrackableImageConfigurationANDROID {
XrStructureType type;
const void* next;
uint32_t databaseCount;
const XrTrackableImageDatabaseANDROID* databases;
} XrTrackableImageConfigurationANDROID;
회원 설명
type은 이 구조의 XrStructureType입니다.next는NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.databaseCount는databases의 요소 수를 지정하는uint32_t입니다.databases는 트래커를 만들 데이터베이스를 지정하는 XrTrackableImageDatabaseANDROID 배열입니다.
애플리케이션은 XrTrackableTrackerCreateInfoANDROID의 next 체인에 XrTrackableImageConfigurationANDROID를 추가하여 유효한 구성을 설정해야 합니다 . 그렇지 않으면 런타임은 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다 .
애플리케이션은 추적기를 만드는 데 사용할 XrTrackableImageDatabaseANDROID 구조를 하나 이상 제공해야 합니다.
유효한 사용 (암시적)
- XrTrackableImageConfigurationANDROID를 사용하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
type은XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID이어야 합니다. -
next은NULL이거나 구조체 체인의 다음 구조체를 가리키는 유효한 포인터여야 합니다. -
databases은(는) 유효한 XrTrackableImageDatabaseANDROID 핸들의databaseCount배열을 가리키는 포인터여야 합니다. -
databaseCount매개변수는0보다 커야 합니다.
XrTrackableImageTrackingModeANDROID 열거형은 지원되는 이미지 추적 모드를 설명합니다.
typedef enum XrTrackableImageTrackingModeANDROID {
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;
열거형 설명
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID— 이 모드는 정확도가 가장 높으며 움직이는 이미지를 짧은 지연 시간으로 추적할 수 있습니다. 전력 소비도 가장 높습니다.XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID- 정적이거나 반정적인 것으로 알려진 이미지에 이 모드를 사용해야 합니다. 이 모드는 동적 모드에 비해 전력 소비가 적습니다. 정적 이미지가 이동 중인 경우 동적 모드를 사용하는 것보다 훨씬 높은 지연 시간으로 업데이트됩니다.
XrTrackableImageFormatANDROID 열거형은 지원되는 이미지 형식을 설명합니다.
typedef enum XrTrackableImageFormatANDROID {
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;
열거형 설명
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID: 채널당 8비트 색상 및 투명도 데이터가 있는 RGBA 이미지 형식입니다.
xrAddTrackableImageDatabaseANDROID 함수는 다음과 같이 정의됩니다.
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
매개변수 설명
tracker는database을 추가할 XrTrackableTrackerANDROID 핸들입니다.database는tracker에 추가할 XrTrackableImageDatabaseANDROID 핸들입니다 .
XrTrackableImageDatabaseANDROID가 트래커에 추가되면 해당 데이터베이스의 참조 이미지는 트래커를 처음 만들 때 xrAddTrackableImageDatabaseANDROID를 사용하거나 XrTrackableImageConfigurationANDROID 구조를 통해 이전에 추가된 다른 데이터베이스와 함께 감지 및 추적에 고려해야 합니다.
유효한 사용 (암시적)
- xrAddTrackableImageDatabaseANDROID를 호출하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
tracker은 유효한 XrTrackableTrackerANDROID 핸들이어야 합니다. -
database은 유효한 XrTrackableImageDatabaseANDROID 핸들이어야 합니다. -
database와tracker모두 동일한 XrSession에서 생성, 할당 또는 검색되어야 합니다.
반환 코드
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
xrRemoveTrackableImageDatabaseANDROID 함수는 다음과 같이 정의됩니다.
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
매개변수 설명
tracker은database을 삭제할 XrTrackableTrackerANDROID 핸들입니다.database는tracker에서 삭제할 XrTrackableImageDatabaseANDROID 핸들입니다 .
XrTrackableImageDatabaseANDROID가 XrTrackableTrackerANDROID에서 삭제되면 해당 데이터베이스의 XrTrackableImageDatabaseEntryANDROID 구조는 더 이상 감지 및 추적에 고려되지 않아야 합니다. 해당 데이터베이스의 활성 추적 항목은 더 이상 보고해서는 안 됩니다. 삭제된 XrTrackableImageDatabaseANDROID 핸들은 이 작업의 일부로 암시적으로 소멸되어서는 안 됩니다.
유효한 사용 (암시적)
- xrRemoveTrackableImageDatabaseANDROID를 호출하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
tracker은 유효한 XrTrackableTrackerANDROID 핸들이어야 합니다. -
database은 유효한 XrTrackableImageDatabaseANDROID 핸들이어야 합니다. -
database와tracker모두 동일한 XrSession에서 생성, 할당 또는 검색되어야 합니다.
반환 코드
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
이미지 가져오기
xrGetTrackableImageANDROID 함수는 다음과 같이 정의됩니다.
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
매개변수 설명
tracker는 쿼리할 XrTrackableTrackerANDROID입니다.getInfo는 추적 가능한 QR 코드를 가져오는 데 사용되는 정보가 포함된 XrTrackableGetInfoANDROID입니다.trackable는 추적 가능한 이미지가 반환되는 XrTrackableImageANDROID 구조체에 대한 포인터입니다.
XrTrackableANDROID의 추적 가능 유형이 XR_TRACKABLE_TYPE_IMAGE_ANDROID이 아니거나 XrTrackableTrackerANDROID의 추적 가능 유형이 XR_TRACKABLE_TYPE_IMAGE_ANDROID이 아닌 경우 런타임은 XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID를 반환해야 합니다 .
유효한 사용 (암시적)
- xrGetTrackableImageANDROID를 호출하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
tracker은 유효한 XrTrackableTrackerANDROID 핸들이어야 합니다. -
getInfo은 유효한 XrTrackableGetInfoANDROID 구조체를 가리키는 포인터여야 합니다(must). -
trackable은 XrTrackableImageANDROID 구조체에 대한 포인터여야 합니다.
반환 코드
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_ERROR_VALIDATION_FAILURE
XrTrackableImageANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrTrackableImageANDROID {
XrStructureType type;
const void* next;
XrTrackingStateANDROID trackingState;
XrTime lastUpdatedTime;
XrTrackableImageDatabaseANDROID database;
uint32_t databaseEntryIndex;
XrPosef centerPose;
XrExtent2Df extents;
} XrTrackableImageANDROID;
회원 설명
type은 이 구조의 XrStructureType입니다.next는NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.trackingState은 이미지의 XrTrackingStateANDROID입니다.lastUpdatedTime은 이미지의 마지막 업데이트의XrTime입니다.database는 이 이미지가 추적된 XrTrackableImageDatabaseANDROID 핸들입니다.databaseEntryIndex는database의 XrTrackableImageDatabaseCreateInfoANDROID ::entries배열에 매핑되는 색인입니다 .centerPose는 XrTrackableGetInfoANDROID ::baseSpace에 있는 이미지의 XrPosef입니다 . 이미지는 XZ 평면에 있으며 X는 이미지의 오른쪽을 가리키고 Z는 이미지의 하단을 가리킵니다.extents는 이미지의 XrExtent2Df 크기입니다. 경계 상자의 경계는centerPose+/- (extents/ 2) 지점에 있습니다.
유효한 사용 (암시적)
- XrTrackableImageANDROID를 사용하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
type은XR_TYPE_TRACKABLE_IMAGE_ANDROID이어야 합니다. -
next은NULL이거나 구조체 체인의 다음 구조체를 가리키는 유효한 포인터여야 합니다. -
trackingState은(는) 유효한 XrTrackingStateANDROID 값이어야 합니다. -
database은 유효한 XrTrackableImageDatabaseANDROID 핸들이어야 합니다.
오류 처리
애플리케이션은 xrPollEvent를 사용하여 XrEventDataImageTrackingLostANDROID 이벤트를 폴링해야 합니다. 이를 무시해서는 안 됩니다.
XrEventDataImageTrackingLostANDROID 구조는 다음과 같이 정의됩니다.
typedef struct XrEventDataImageTrackingLostANDROID {
XrStructureType type;
const void* next;
XrTime time;
} XrEventDataImageTrackingLostANDROID;
회원 설명
type은 이 구조의 XrStructureType입니다.next는NULL이거나 구조체 체인의 다음 구조체에 대한 포인터입니다. 이러한 구조는 핵심 OpenXR이나 이 확장 프로그램에 정의되어 있지 않습니다.timeXrTime
XrEventDataImageTrackingLostANDROID 이벤트가 수신되면 이미지 추적이 손상되었으며 기존 리소스가 무효화되는 내부 오류가 발생했음을 나타냅니다. 애플리케이션은 이미지 추적을 계속하려면 모든 XrTrackableImageDatabaseANDROID 핸들을 소멸하고 다시 만들어야 합니다. 애플리케이션은 이미지 추적을 계속하려면 모든 이미지 추적 관련 XrTrackableTrackerANDROID 핸들을 소멸시키고 다시 만들어야 합니다.
유효한 사용 (암시적)
- XrEventDataImageTrackingLostANDROID를 사용하기 전에
XR_ANDROID_trackables_image확장 프로그램을 사용 설정해야 합니다. -
type은XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID이어야 합니다. -
next은NULL이거나 구조체 체인의 다음 구조체를 가리키는 유효한 포인터여야 합니다.
추적 가능한 이미지를 가져오는 예시 코드
다음 예제 코드는 추적 가능한 이미지를 가져오는 방법을 보여줍니다.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
XrSystemId systemId; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties; // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
// Inspect system capability
XrSystemImageTrackingPropertiesANDROID imageProperty {
.type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
.next = nullptr,
};
XrSystemProperties systemProperties {
.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
// image tracking is not supported.
return;
}
uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
{
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
.next = nullptr,
.trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
.physicalWidth = 0.1f, // The width of the image in meters.
.imageWidth = 640,
.imageHeight = 480,
.format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
.bufferSize = imageBufferSize, // RGBA buffer size in bytes.
.buffer = imageBuffer, // RGBA data.
}
};
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
futureReady = true;
keepLooping = false;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrTrackableImageDatabaseANDROID imageDatabase;
if (futureReady) {
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
}
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.
// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
while (1) {
uint32_t trackableCountOutput = 0;
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));
std::vector<XrTrackableANDROID> allImageTrackables;
allImageTrackables.resize(trackableCountOutput);
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));
for (XrTrackableANDROID trackable : allImageTrackables) {
XrTrackableGetInfoANDROID imageGetInfo {
.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
.next = nullptr,
.trackable = trackable,
.baseSpace = appSpace,
.time = updateTime
};
XrTrackableImageANDROID trackableImage{
.type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
};
CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));
// Use XrTrackableImageANDROID data.
(void)trackableImage.trackingState;
(void)trackableImage.lastUpdatedTime;
(void)trackableImage.centerPose;
(void)trackableImage.extents;
if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
// Knowing which image the index of 0 maps to, use the specific image database
// entry (e.g. rendering A for image A).
}
// indices 1+N comparisons for another specific image database entry.
}
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
런타임에 이미지 데이터베이스를 관리하는 예시 코드
다음 예시 코드는 추적되는 이미지 집합을 수정하는 방법을 보여줍니다.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.
// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 2,
.databases = imageDatabases
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.
// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &anotherImageDatabase
};
XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &anotherImageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));
// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.
이미지 추적 실패에 대응하는 예시 코드
다음 예시 코드는 XrEventDataImageTrackingLostANDROID 이벤트를 폴링하여 실패를 처리하는 방법을 보여줍니다.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.
// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
.type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
switch (event.type) {
case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
const XrEventDataImageTrackingLostANDROID& eventdata =
*reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);
// All existing databases and trackers need to be destroyed.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
// To resume image tracking, the database(s) and the tracker need to be re-created.
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
while (true) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
break;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
break;
}
}
}
새 객체 유형
새 명령어
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
새 구조
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
XrSystemProperties 확장 :
새 열거형
새 열거형 상수
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONXrObjectType 확장 :
XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
XrResult 확장 :
XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
XrStructureType 확장 :
XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
-
XR_TRACKABLE_TYPE_IMAGE_ANDROID
문제
버전 기록
버전 1, 2025년 4월 8일 (다니엘 구텐베르크)
- 초기 확장 프로그램 설명입니다.