XR_ANDROID_spatial_annotation_tracking

Строка имени

XR_ANDROID_spatial_annotation_tracking

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

795

Пересмотр

1

Статус ратификации

Не ратифицировано

Зависимости расширений и версий

XR_EXT_spatial_entity
и
XR_EXT_spatial_image_tracking

Дата последнего изменения

2026-01-12

Статус IP

Известных претензий на интеллектуальную собственность нет.

Авторы

Левана Чен, Google
Кристофер Фейл, Google
Мартин Сундермейер, Google
Дэвид Джозеф Тан, Google
Джаред Финдер, Google
Нихав Джайн, Google

Обзор

Это расширение обеспечивает возможность отслеживания аннотаций для расширения XR_EXT_spatial_entity , позволяя отслеживать различные аннотации в сцене. Оно дает приложениям возможность накладывать наложения на физические или виртуальные объекты, определенные ссылками во время выполнения.

Это расширение предоставляет базовый тип аннотации «Квадрат», представляющий собой многоугольник, имеющий ровно 4 стороны, то есть выпуклый четырехугольник, который является обобщенным двумерным ограничивающим прямоугольником в рамках временной привязки. Отслеживаемая аннотация в виде четырехугольника представляется как пространственный объект, имеющий (или «обладающий») следующие компоненты:

• XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Расширение для отслеживания пространственных аннотаций обычно можно использовать в следующих сценариях:

• Сначала приложение создает дескриптор объекта XrSpatialReferenceCacheANDROID , который начинает запись ссылок во время выполнения из указанного источника.
• Затем приложение захватывает во время выполнения ссылку на XrSpatialReferenceImageEXT и определяет необходимую аннотацию внутри этой ссылки в течение периода времени, охватываемого кэшем ссылок.
• Затем приложение создает дескриптор XrSpatialContextEXT на основе XrSpatialReferenceImageEXT , предоставленного параметром XrSpatialCapabilityConfigurationAnnotationTrackingANDROID .
• Приложение может уничтожить дескриптор XrSpatialReferenceCacheANDROID , чтобы прекратить запись ссылок во время выполнения и уменьшить использование памяти, или дождаться события XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID для подтверждения результата инициализации.
• Затем приложение запрашивает событие XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID , чтобы подтвердить результат инициализации аннотации.
• Если инициализация прошла успешно, приложение может затем запросить событие XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT для отслеживания аннотации.
• Если инициализация не удалась, приложение может использовать код ошибки, возвращаемый в событии, чтобы определить причину сбоя и уничтожить существующий дескриптор XrSpatialContextEXT для начала новой аннотации.
• Независимо от результата инициализации, приложение может освободить буфер изображения, чтобы уменьшить использование памяти после получения события.
• Приложение обнаруживает и запрашивает аннотации в соответствии с шаблонами доступа к пространственным объектам.
• Приложение может создать дополнительный дескриптор XrSpatialContextEXT для отслеживания аннотаций в новой ссылке в течение периода действия действительного XrSpatialReferenceCacheANDROID .
• Приложение может динамически уничтожать дескрипторы XrSpatialContextEXT во время выполнения, чтобы уменьшить набор обнаруживаемых и отслеживаемых аннотаций.

Поддержка во время выполнения

Среда выполнения должна заявить о поддержке возможности отслеживания аннотаций с помощью xrEnumerateSpatialCapabilitiesEXT , указав следующую возможность:

• XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Если среда выполнения поддерживает функцию отслеживания аннотаций:

• Он должен поддерживать как минимум один компонент аннотации, список поддерживаемых компонентов аннотации можно получить с помощью функции xrEnumerateSpatialCapabilityComponentTypesEXT .
• Он должен поддерживать как минимум один из форматов XrSpatialReferenceImageFormatEXT , перечисляя поддерживаемые форматы ссылок с помощью xrEnumerateSpatialReferenceImageFormatsEXT с параметром capability , установленным на XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .
• Он должен поддерживать как минимум один из XrSpatialAnnotationReferenceSourceANDROID , путем перечисления поддерживаемых источников ссылок с помощью xrEnumerateSpatialAnnotationReferenceSourcesANDROID с параметром capability XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .

Функция xrEnumerateSpatialAnnotationReferenceSourcesANDROID определена следующим образом:

XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    sourceCapacityInput,
    uint32_t*                                   sourceCountOutput,
    XrSpatialAnnotationReferenceSourceANDROID*  sources);

Описание параметров

• instance — это дескриптор объекта XrInstance .
• systemId — это XrSystemId , источники ссылок которого будут перечислены.
• capability является XrSpatialCapabilityEXT, для которого будут перечислены источники ссылок.
• sourceCapacityInput — это емкость массива sources , или 0, указывающее на запрос на получение требуемой емкости.
• sourceCountOutput — это количество источников или требуемая мощность в случае, если sourceCapacityInput недостаточен.
• sources — это массив объектов XrSpatialAnnotationReferenceSourceANDROID . Он может быть NULL если sourceCapacityInput равен 0.
• Подробное описание получения необходимого размера sources см. в разделе « Параметры размера буфера» .

Приложение может перечислить список источников ссылок, поддерживаемых заданным XrSystemId , используя функцию xrEnumerateSpatialAnnotationReferenceSourcesANDROID .

Среда выполнения не должна перечислять источники ссылок, расширение которых, instance , не включено.

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед вызовом функции xrEnumerateSpatialAnnotationReferenceSourcesANDROID.
• instance должен быть допустимым дескриптором XrInstance.
• Значение capability должно быть допустимым значением XrSpatialCapabilityEXT.
• sourceCountOutput должен быть указателем на значение типа uint32_t
• Если sourceCapacityInput не равен 0 , sources должен быть указателем на массив значений sourceCapacityInput XrSpatialAnnotationReferenceSourceANDROID.

Коды возврата

Успех

• 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

typedef enum XrSpatialAnnotationReferenceSourceANDROID {
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationReferenceSourceANDROID;

Перечисление XrSpatialAnnotationReferenceSourceANDROID описывает источник ссылки, предоставляющий метаданные для аннотации.

Перечисления имеют следующие значения:

Описание перечисления

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

В качестве эталонного изображения используется необрезанное изображение, полученное из API камеры Android, например, изображение из ImageReader, связанного с Camera2 CameraDevice, или ImageProxy из ImageAnalysis, связанного с CameraX. Обычно это одна из RGB-камер, направленных вперед.

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID

В качестве эталонного изображения используется необрезанное изображение, полученное с помощью API Android MediaProjection, например, изображение из ImageReader, связанного с виртуальным дисплеем MediaProjection. Оно может содержать как виртуальный, так и реальный контент.

Структура XrSystemSpatialAnnotationPropertiesANDROID определяется следующим образом:

typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           referenceCacheTimespan;
    uint32_t           maxReferencePixelWidth;
    uint32_t           maxReferencePixelHeight;
    uint32_t           maxReferenceCount;
    uint32_t           maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;

Описание участников

• type — это XrStructureType данной структуры.
• next — это NULL или указатель на следующую структуру в цепочке структур.
• referenceCacheTimespan указывает временной интервал в секундах для действительного дескриптора XrSpatialReferenceCacheANDROID .
• maxReferencePixelWidth указывает максимальную ширину края эталонных изображений в пикселях.
• maxReferencePixelHeight указывает максимальную высоту края эталонных изображений в пикселях.
• maxReferenceCount указывает максимальное количество эталонных изображений, которые могут быть выделены одновременно.
• maxAnnotationCount указывает максимальное количество аннотаций, которые могут отслеживаться одновременно.

Если среда выполнения поддерживает возможность отслеживания аннотаций, приложение может проверять соответствующие свойства системы, связывая структуру XrSystemSpatialAnnotationPropertiesANDROID со структурой XrSystemProperties при вызове метода xrGetSystemProperties .

Если значение XrSpatialReferenceImageEXT :: width из XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference превышает maxReferencePixelWidth , среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE при вызове xrCreateSpatialContextAsyncEXT .

Если значение XrSpatialReferenceImageEXT :: height из XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference превышает maxReferencePixelHeight , среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE при вызове xrCreateSpatialContextAsyncEXT .

Если значение XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time выходит за пределы временного интервала XrSpatialReferenceCacheANDROID :: cache , среда выполнения должна вернуть XR_ERROR_TIME_INVALID при вызове xrCreateSpatialContextAsyncEXT . Приложение может пересоздать дескриптор XrSpatialContextEXT с новой ссылкой в ​​течение временного интервала XrSpatialReferenceCacheANDROID .

Если количество выделенных эталонных изображений превышает maxReferenceCount , среда выполнения должна вернуть XR_ERROR_LIMIT_REACHED и указать на ошибку инициализации через XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult . Приложение может уничтожить дескриптор XrSpatialContextEXT и повторить попытку после завершения инициализации.

Если количество активных аннотаций превышает maxAnnotationCount , среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE при вызове xrCreateSpatialContextAsyncEXT .

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед использованием XrSystemSpatialAnnotationPropertiesANDROID.
• type должен быть XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID
• next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.

кэш ссылок времени выполнения

XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)

Дескриптор XrSpatialReferenceCacheANDROID представляет собой кэш ссылок времени выполнения, записанных из заданного источника.

Функция xrCreateSpatialReferenceCacheAsyncANDROID определена следующим образом:

XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
    XrSession                                   session,
    const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

Описание параметров

• session — это объект XrSession , в котором будет активен кэш ссылок.
• createInfo — это указатель на объект XrSpatialReferenceCacheCreateInfoANDROID , используемый для указания параметров кэша ссылок.
• future — это указатель на выходной дескриптор объекта ` XrFutureEXT .

Приложение может создать дескриптор XrSpatialReferenceCacheANDROID , вызвав метод xrCreateSpatialReferenceCacheAsyncANDROID . Инициализация служб отслеживания может занять некоторое время. Затем приложение может многократно вызывать метод xrCreateSpatialReferenceCacheCompleteANDROID для проверки завершения этой асинхронной операции.

Если параметр XrSpatialReferenceCacheCreateInfoANDROID :: capability не указан в параметре xrEnumerateSpatialCapabilitiesEXT , среда выполнения должна вернуть XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

Если параметр XrSpatialReferenceCacheCreateInfoANDROID :: source не указан в параметре xrEnumerateSpatialAnnotationReferenceSourcesANDROID для данной возможности, среда выполнения должна вернуть XR_ERROR_FEATURE_UNSUPPORTED

Приложение может создать только один дескриптор для каждого источника для заданной возможности. В противном случае среда выполнения должна вернуть XR_ERROR_LIMIT_REACHED .

Затем приложение может перехватывать ссылки во время выполнения в течение периода действия дескриптора XrSpatialReferenceCacheANDROID для настройки нового дескриптора XrSpatialContextEXT .

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед вызовом функции xrCreateSpatialReferenceCacheAsyncANDROID.
• session должна быть действительным дескриптором XrSession.
• createInfo должна быть указателем на допустимую структуру XrSpatialReferenceCacheCreateInfoANDROID.
• future должен быть указателем на значение XrFutureEXT

Коды возврата

Успех

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Отказ

• XR_ERROR_FEATURE_UNSUPPORTED
• 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_CAPABILITY_UNSUPPORTED_EXT
• XR_ERROR_VALIDATION_FAILURE

Структура XrSpatialReferenceCacheCreateInfoANDROID определяется следующим образом:

typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialCapabilityEXT                       capability;
    XrSpatialAnnotationReferenceSourceANDROID    source;
} XrSpatialReferenceCacheCreateInfoANDROID;

Описание участников

• type — это XrStructureType данной структуры.
• next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
• capability — это объект XrSpatialCapabilityEXT, описывающий, для какой возможности создается эталонный кэш.
• source — это объект XrSpatialAnnotationReferenceSourceANDROID , описывающий источник кэша ссылок.

Структура XrSpatialReferenceCacheCreateInfoANDROID описывает информацию, необходимую для создания дескриптора XrSpatialReferenceCacheANDROID .

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед использованием XrSpatialReferenceCacheCreateInfoANDROID.
• type должен быть XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
• next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.
• Значение capability должно быть допустимым значением XrSpatialCapabilityEXT.
• source должен быть допустимым значением XrSpatialAnnotationReferenceSourceANDROID.

Функция xrCreateSpatialReferenceCacheCompleteANDROID определена следующим образом:

XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialReferenceCacheCompletionANDROID* completion);

Описание параметров

• session — это объект XrSession, ранее переданный в функцию xrCreateSpatialReferenceCacheAsyncANDROID :: session .
• future — это объект XrFutureEXT полученный из xrCreateSpatialReferenceCacheAsyncANDROID :: future .
• completion — это указатель на объект XrCreateSpatialReferenceCacheCompletionANDROID .

Приложение может вызвать метод xrCreateSpatialReferenceCacheCompleteANDROID , чтобы дождаться завершения асинхронной операции, начатой ​​методом xrCreateSpatialReferenceCacheAsyncANDROID .

Если future не находится в состоянии готовности, среда выполнения должна вернуть XR_ERROR_FUTURE_PENDING_EXT . Если future уже завершен или отменен, среда выполнения должна вернуть XR_ERROR_FUTURE_INVALID_EXT .

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед вызовом функции xrCreateSpatialReferenceCacheCompleteANDROID.
• session должна быть действительным дескриптором XrSession.
• completion должна быть указателем на структуру XrCreateSpatialReferenceCacheCompletionANDROID.

Коды возврата

Успех

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Отказ

• XR_ERROR_FEATURE_UNSUPPORTED
• 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

Структура XrCreateSpatialReferenceCacheCompletionANDROID определяется следующим образом:

typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
    XrStructureType                   type;
    void*                             next;
    XrResult                          futureResult;
    XrSpatialReferenceCacheANDROID    referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;

Описание участников

• type — это XrStructureType данной структуры.
• next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
• futureResult — это объект XrResult операции создания кэша ссылок.
• В случае успешного выполнения операции referenceCache — это дескриптор XrSpatialReferenceCacheANDROID .

Будущие коды возврата

Значения futureResult :

Успех

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Отказ

• XR_ERROR_FEATURE_UNSUPPORTED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED

Если futureResult является кодом успешного выполнения, среда выполнения должна вернуть действительный дескриптор referenceCache . Если referenceCache действителен, он остается таковым только в течение времени жизни xrCreateSpatialReferenceCacheAsyncANDROID :: session или до тех пор, пока приложение не уничтожит дескриптор с помощью xrDestroySpatialReferenceCacheANDROID, в зависимости от того, что произойдет раньше.

Если referenceCache действителен, он записывает данные о кэше в XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan .

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед использованием XrCreateSpatialReferenceCacheCompletionANDROID.
• type должен быть XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
• next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.
• futureResult должно быть допустимым значением XrResult.
• referenceCache должен быть допустимым дескриптором XrSpatialReferenceCacheANDROID.

Функция xrDestroySpatialReferenceCacheANDROID определена следующим образом:

XrResult xrDestroySpatialReferenceCacheANDROID(
    XrSpatialReferenceCacheANDROID              cacheHandle);

Описание параметров

• cacheHandle — это объект XrSpatialReferenceCacheANDROID, ранее созданный с помощью xrCreateSpatialReferenceCacheAsyncANDROID .

Приложение может вызвать функцию xrDestroySpatialReferenceCacheANDROID для освобождения дескриптора cacheHandle и базовых ресурсов после завершения создания пространственного контекста.

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед вызовом функции xrDestroySpatialReferenceCacheANDROID.
• cacheHandle должен быть допустимым дескриптором XrSpatialReferenceCacheANDROID.

Безопасность резьбы

• Доступ к cacheHandle и любым дочерним дескрипторам должен осуществляться посредством внешней синхронизации.

Коды возврата

Успех

• XR_SUCCESS

Отказ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

Конфигурация

Структура XrSpatialCapabilityConfigurationAnnotationTrackingANDROID определяется следующим образом:

typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialReferenceCacheANDROID      cache;
    XrTime                              time;
    XrSpatialReferenceImageEXT          reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;

Описание участников

• type — это XrStructureType данной структуры.
• next — это NULL или указатель на следующую структуру в цепочке структур.
• capability представляет собой объект `XrSpatialCapabilityEXT` и должна иметь значение XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .
• enabledComponentCount — это тип uint32_t , описывающий количество элементов в массиве enabledComponents .
• enabledComponents — это указатель на массив XrSpatialComponentTypeEXT .
• cache — это объект XrSpatialReferenceCacheANDROID, созданный ранее для записи ссылок на конфигурацию во время reference .
• time — это значение XrTime , в которое был захвачен reference .
• reference представляет собой XrSpatialReferenceImageEXT, к которому привязаны аннотации, следующие за его указателем next.

Приложения могут включить пространственную возможность XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID , добавив указатель на структуру XrSpatialCapabilityConfigurationAnnotationTrackingANDROID в XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Если capability XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID не равно XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID , среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE .

Если reference не содержит аннотаций, среда выполнения должна вернуть XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT .

Если компонент аннотации указан в enabledComponents , но с reference не связаны соответствующие аннотации, среда выполнения должна вернуть XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

Если cache не принадлежит тому же XrSession, который передается в xrCreateSpatialContextAsyncEXT , среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE

Если time выходит за пределы временного диапазона cache , среда выполнения должна вернуть XR_ERROR_TIME_INVALID .

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед использованием XrSpatialCapabilityConfigurationAnnotationTrackingANDROID.
• type должен быть XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
• next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.
• Значение capability должно быть допустимым значением XrSpatialCapabilityEXT.
• enabledComponents должен быть указателем на массив допустимых значений XrSpatialComponentTypeEXT, равных enabledComponentCount .
• cache должен быть действительным дескриптором XrSpatialReferenceCacheANDROID.
• reference должна представлять собой допустимую структуру XrSpatialReferenceImageEXT.
• Параметр enabledComponentCount должен быть больше 0

События отслеживания аннотаций

Структура XrEventDataSpatialAnnotationTrackingANDROID определяется следующим образом:

typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
    uint32_t               annotationIndex;
    XrResult               initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;

Описание участников

• type — это XrStructureType данной структуры.
• next — это NULL или указатель на следующую структуру в цепочке структур.
• spatialContext — это объект XrSpatialContextEXT , для которого активировано отслеживание аннотаций.
• annotationIndex соответствует индексу из массива аннотаций, связанного с XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference .
• initializationResult указывает результат инициализации аннотации. Если он не равен XR_SUCCESS , приложение может уничтожить и заново создать дескриптор XrSpatialContextEXT для повторной инициализации аннотации или продолжить использование spatialContext для отслеживания других аннотаций.

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед использованием XrEventDataSpatialAnnotationTrackingANDROID.
• type должен быть XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
• next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.

Для каждой аннотации среда выполнения должна заполнить поле XrEventDataSpatialAnnotationTrackingANDROID , чтобы указать на завершение ее инициализации. Независимо от результата инициализации, приложение может освободить буфер изображения, чтобы уменьшить использование памяти после получения события.

Если инициализация аннотации прошла успешно, среда выполнения должна заполнить initializationResult значением XR_SUCCESS . После этого приложение может запросить событие XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT для отслеживания аннотации.

В противном случае среда выполнения должна заполнить initializationResult соответствующим кодом ошибки, указывающим на причину сбоя. Приложение может уничтожить дескриптор XrSpatialContextEXT , чтобы начать новую аннотацию, или продолжить использование spatialContext для отслеживания других аннотаций.

Квадратная аннотация

Среда выполнения должна заявить о поддержке аннотаций в виде четырехугольников, используя xrEnumerateSpatialCapabilityComponentTypesEXT , указав следующий тип компонента:

• XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Квадратная ссылка

Структура XrSpatialAnnotationQuadReferenceANDROID определяется следующим образом:

typedef struct XrSpatialAnnotationQuadReferenceANDROID {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 quadCount;
    const XrSpatialAnnotationQuadANDROID*    quads;
} XrSpatialAnnotationQuadReferenceANDROID;

Описание участников

• type — это XrStructureType данной структуры.
• next — это NULL или указатель на следующую структуру в цепочке структур.
• quadCount — это тип данных uint32_t , описывающий количество элементов в массиве quads .
• quads — это указатель на массив XrSpatialAnnotationQuadANDROID .

Если среда выполнения поддерживает аннотации в виде четырехугольников, приложение может настроить аннотации, связав структуру XrSpatialAnnotationQuadReferenceANDROID со структурой XrSpatialReferenceImageEXT :: next и установив ссылку в XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference при создании дескриптора XrSpatialContextEXT .

Если quadCount равно 0, среда выполнения должна возвращать XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT из функции xrCreateSpatialContextAsyncEXT .

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед использованием XrSpatialAnnotationQuadReferenceANDROID.
• type должен быть XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
• next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.
• quads должен быть указателем на массив допустимых структур XrSpatialAnnotationQuadANDROID, равных quadCount
• Параметр quadCount должен быть больше 0

Структура XrSpatialAnnotationQuadANDROID определяется следующим образом:

typedef struct XrSpatialAnnotationQuadANDROID {
    XrSpatialAnnotationQuadAlignmentANDROID    alignment;
    XrVector2f                                 upperLeft;
    XrVector2f                                 upperRight;
    XrVector2f                                 lowerRight;
    XrVector2f                                 lowerLeft;
} XrSpatialAnnotationQuadANDROID;

Описание участников

• alignment — это XrSpatialAnnotationQuadAlignmentANDROID квадра.
• upperLeft — это объект XrVector2f , описывающий координаты верхнего левого угла четырехугольника относительно начала координат.
• upperRight — это объект XrVector2f , описывающий координаты верхнего правого угла четырехугольника относительно начала координат.
• lowerRight — это объект XrVector2f , описывающий координаты нижнего правого угла четырехугольника относительно начала координат.
• lowerLeft — это объект XrVector2f , описывающий координаты нижнего левого угла четырехугольника относительно начала координат.

Четырехугольник в двумерном пространстве — это выпуклый четырехугольник, вращающийся по часовой стрелке. Значение 4 углов связано с началом координат (0, 0), к которому относится этот четырехугольник.

• Когда объект связан с XrSpatialReferenceImageEXT , начало координат находится в верхнем левом углу изображения, где X соответствует пикселю по ширине, а Y — пикселю по высоте.
• Когда объект связан с XrSpatialAnnotationQuadDataANDROID , точка отсчета указывается с помощью XrSpaceLocationData :: pose of XrSpatialAnnotationQuadDataANDROID :: origin .

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед использованием XrSpatialAnnotationQuadANDROID.
• Значение alignment должно быть допустимым значением XrSpatialAnnotationQuadAlignment ANDROID.

typedef enum XrSpatialAnnotationQuadAlignmentANDROID {
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;

Перечисление XrSpatialAnnotationQuadAlignmentANDROID описывает выравнивание аннотации в виде четырехугольника.

Перечисления имеют следующие значения:

Описание перечисления

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID

Квадрат аннотации параллелен плоскости экрана, а его вращение в плоскости остается неизменным и зависит от гравитации окружающего мира. В результате отображается обычный вертикальный ограничивающий прямоугольник.

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID

Аннотационный четырехугольник привязан непосредственно к объекту, соответствуя выравниванию, определенному на эталонном изображении. В результате получается выпуклый четырехугольник, форма которого корректируется в соответствии с перспективой объекта.

Четырехкомпонентные

Структура XrSpatialAnnotationQuadDataANDROID определяется следующим образом:

typedef struct XrSpatialAnnotationQuadDataANDROID {
    uint32_t                          annotationIndex;
    XrSpaceLocationData               origin;
    XrSpatialAnnotationQuadANDROID    quad;
} XrSpatialAnnotationQuadDataANDROID;

Описание участников

• annotationIndex — это индекс, сопоставляющий массив XrSpatialAnnotationQuadReferenceANDROID :: quads , связанный со ссылкой, переданной в XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference .
• origin представляет собой XrSpaceLocationData , описывающий начало координат двумерной плоскости, в которой находится корневой узел четырехугольника. Среда выполнения должна установить XrSpaceLocationData :: locationFlags чтобы указать допустимые биты положения начала координат.
• quad — это объект XrSpatialAnnotationQuadANDROID, представляющий собой квадранта в локальном пространстве. Используйте origin для преобразования квадранта в пространство поз.

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед использованием XrSpatialAnnotationQuadDataANDROID.
• origin должен представлять собой допустимую структуру XrSpaceLocationData.
• quad должен быть допустимой структурой XrSpatialAnnotationQuadANDROID.

Структура XrSpatialComponentAnnotationQuadListANDROID определяется следующим образом:

typedef struct XrSpatialComponentAnnotationQuadListANDROID {
    XrStructureType                        type;
    void*                                  next;
    uint32_t                               quadCount;
    XrSpatialAnnotationQuadDataANDROID*    quads;
} XrSpatialComponentAnnotationQuadListANDROID;

Описание участников

• type — это XrStructureType данной структуры.
• next — это NULL или указатель на следующую структуру в цепочке структур.
• quadCount — это тип данных uint32_t , описывающий количество элементов в массиве quads .
• quads — это массив объектов XrSpatialAnnotationQuadDataANDROID .

Приложение может запрашивать компонент аннотации четырехугольников пространственных объектов в XrSpatialSnapshotEXT , добавив XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID в XrSpatialComponentDataQueryConditionEXT :: componentTypes и добавив XrSpatialComponentAnnotationQuadListANDROID в следующую цепочку указателей XrSpatialComponentDataQueryResultEXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrQuerySpatialComponentDataEXT , если XrSpatialComponentAnnotationQuadListANDROID находится в следующей цепочке XrSpatialComponentDataQueryResultEXT :: next , но XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID не включен в XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Если quadCount меньше, чем XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput , среда выполнения должна вернуть XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT .

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_annotation_tracking необходимо включить перед использованием XrSpatialComponentAnnotationQuadListANDROID.
• type должен быть XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
• next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.
• quads должен быть указателем на массив структур quadCount XrSpatialAnnotationQuadDataANDROID.
• Параметр quadCount должен быть больше 0

Пример кода

Проверьте поддержку во время выполнения.

Приведенный ниже пример кода демонстрирует, как проверить, поддерживает ли среда выполнения функцию отслеживания аннотаций.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrEnumerateSpatialCapabilitiesEXT xrEnumerateSpatialCapabilitiesEXT;
PFN_xrEnumerateSpatialAnnotationReferenceSourcesANDROID xrEnumerateSpatialAnnotationReferenceSourcesANDROID;
PFN_xrEnumerateSpatialReferenceImageFormatsEXT xrEnumerateSpatialReferenceImageFormatsEXT;
PFN_xrEnumerateSpatialCapabilityComponentTypesEXT xrEnumerateSpatialCapabilityComponentTypesEXT;

// Check spatial annotation tracking capability
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0,
                                         &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount,
                                         &capabilityCount,
                                         capabilities.data()));
if (std::find(capabilities.begin(), capabilities.end(),
              XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID) ==
    capabilities.end()) {
  // System does not support spatial annotation tracking.
  return;
}

// Inspect system properties for annotation tracking variables
XrSystemSpatialAnnotationPropertiesANDROID annotationSystemProperties{
    XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{.type = XR_TYPE_SYSTEM_PROPERTIES,
                                    .next = &annotationSystemProperties,
                                    .systemId = systemId};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (annotationSystemProperties.maxAnnotationCount == 0) {
  // System does not support any active annotations.
  return;
}

// Enumerate supported reference sources
uint32_t sourceCountOutput = 0;
XrSpatialAnnotationReferenceSourceANDROID desiredSource =
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID;
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    0, &sourceCountOutput, nullptr));
std::vector<XrSpatialAnnotationReferenceSourceANDROID> sources(sourceCountOutput);
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    sourceCountOutput, &sourceCountOutput, sources.data()));
if (std::find(sources.begin(), sources.end(), desiredSource) == sources.end()) {
  // The desired source is not supported.
  return;
}

// Enumerate supported reference image formats, provided by XR_EXT_spatial_image_tracking.
uint32_t formatCountOutput = 0;
XrSpatialReferenceImageFormatEXT desiredFormat =
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT; // Or XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT for screenshot.
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, 0,
    &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), desiredFormat) == formats.end()) {
  // The desired format is not supported
  return;
}

// Enumerate supported components for annotation tracking capability.
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes{
    XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));
std::vector<XrSpatialComponentTypeEXT>
    annotationTypes(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = annotationTypes.size();
capabilityComponentTypes.componentTypes = annotationTypes.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));

// Check supported annotation components.
XrSpatialComponentTypeEXT desiredComponent =
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID;
const auto supportedComponent = [&annotationTypes](
                                    XrSpatialComponentTypeEXT component) {
  return std::find(annotationTypes.begin(), annotationTypes.end(), component) !=
         annotationTypes.end();
};
if (!supportedComponent(desiredComponent)) {
  // The desired annotation is not supported.
  return;
}

Настройка аннотации квадрата

Приведенный ниже пример кода демонстрирует, как настроить аннотацию квадов.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrCreateSpatialReferenceCacheAsyncANDROID xrCreateSpatialReferenceCacheAsyncANDROID;
PFN_xrCreateSpatialReferenceCacheCompleteANDROID xrCreateSpatialReferenceCacheCompleteANDROID;
PFN_xrDestroySpatialReferenceCacheANDROID xrDestroySpatialReferenceCacheANDROID;
PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialReferenceImageFormatEXT desiredFormat;
XrSpatialAnnotationReferenceSourceANDROID desiredSource;
XrSpatialComponentTypeEXT desiredComponent;

// Create and start reference cache to prepare for capturing reference images.
XrSpatialReferenceCacheANDROID referenceCache;
XrSpatialReferenceCacheCreateInfoANDROID cacheCreateInfo{
  .type = XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
  .source = desiredSource,
};
XrFutureEXT cacheFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialReferenceCacheAsyncANDROID(session, &cacheCreateInfo, &cacheFuture));

waitUntilReady(cacheFuture);

XrCreateSpatialReferenceCacheCompletionANDROID cacheCompletion{
    XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID};
CHK_XR(xrCreateSpatialReferenceCacheCompleteANDROID(session, cacheFuture,
                                                     &cacheCompletion));
if (cacheCompletion.futureResult != XR_SUCCESS) {
  // Error, reference cache creation failed
  return;
}

referenceCache = cacheCompletion.referenceCache;

// Create the reference image with quad annotations

//  YUV 4:2:0 Planar:
// ----------------------
// |     Y      |Cb |Cr |
// ----------------------
XrSpatialReferenceImagePlaneEXT cameraImagePlanes[3];
// for each plane (0=Y, 1=U(cb), 2=V(Cr)) return by Image#getPlanes().
for (int i = 0; i < 3; ++i) {
  cameraImagePlanes[i].buffer; // read from Plane#getBuffer().
  cameraImagePlanes[i].bufferSize; // set each buffer size. Y = width * height (bytes); U = Y / 4 (bytes); V = Y / 4 (bytes).
  cameraImagePlanes[i].rowStride; // read from Plane#getRowStride().
  cameraImagePlanes[i].pixelStride; // read from Plane#getPixelStride().
}
XrSpatialReferenceImageEXT referenceImage{
      XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
referenceImage.width = 640;
referenceImage.height = 480;
referenceImage.format = desiredFormat;
referenceImage.planeCount = 3;
referenceImage.planes = cameraImagePlanes;

XrSpatialAnnotationQuadANDROID
    quad; // quad coordinates within the reference image.
quad.alignment = XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID;
// Set unnormalized pixel coordinates of 4 corners.
quad.upperLeft = {0.0, 0.0};
quad.upperRight = {0.0, 100.0};
quad.lowerRight = {100.0, 100.0};
quad.lowerLeft = {0.0, 100.0};

XrSpatialAnnotationQuadReferenceANDROID quadReference{
    XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID};
quadReference.quads = &quad;
quadReference.quadCount = 1;
referenceImage.next = &quadReference;

// Create the spatial context with annotation configuration.
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
      desiredComponent,
  };

  // Configure annotation tracking
  XrSpatialCapabilityConfigurationAnnotationTrackingANDROID annotationConfig{
      XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID};
  annotationConfig.capability =
      XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID;
  annotationConfig.enabledComponentCount = enabledComponents.size();
  annotationConfig.enabledComponents = enabledComponents.data();
  annotationConfig.cache = referenceCache;
  annotationConfig.time; // The time when this reference image is captured.
  annotationConfig.reference = referenceImage;

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

  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
    return;
  }

  spatialContext = completion.spatialContext;
  CHK_XR(xrDestroySpatialReferenceCacheANDROID(referenceCache));
}

Откройте для себя активные аннотации

Приведенный ниже пример кода демонстрирует, как обнаруживать и запрашивать аннотации.

XrInstance instance;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL
XrSpatialContextEXT spatialContext; // previously created

PFN_xrCreateSpatialDiscoverySnapshotAsyncEXT xrCreateSpatialDiscoverySnapshotAsyncEXT;
PFN_xrCreateSpatialDiscoverySnapshotCompleteEXT xrCreateSpatialDiscoverySnapshotCompleteEXT;
PFN_xrQuerySpatialComponentDataEXT xrQuerySpatialComponentDataEXT;
PFN_xrDestroySpatialSnapshotEXT xrDestroySpatialSnapshotEXT;
PFN_xrPollEvent xrPollEvent;
PFN_xrDestroySpatialContextEXT xrDestroySpatialContextEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialComponentTypeEXT desiredComponent; // e.g. XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

auto discoverAnnotations = [&](XrSpatialContextEXT spatialContext, XrTime time,
                               XrSpace baseSpace) {
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{desiredComponent};
  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 = baseSpace;
  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 desired annotation data, e.g. quad.
    XrSpatialComponentTypeEXT componentsToQuery[] = {
        XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID};
    XrSpatialComponentDataQueryConditionEXT queryCond{
        XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = 1;
    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<XrSpatialAnnotationQuadDataANDROID> quads(
        queryResult.entityIdCountOutput);
    XrSpatialComponentAnnotationQuadListANDROID quadList{
        XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID};
    quadList.quadCount = quads.size();
    quadList.quads = quads.data();
    queryResult.next = &quadList;

    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 XrSpatialAnnotationQuadDataANDROID &currentQuad = quads[i];
        // Rendering quad in the view.
      }
    }

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

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

  XrSpace space;           // Application's play space.
  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_ANNOTATION_TRACKING_ANDROID: {
      const XrEventDataSpatialAnnotationTrackingANDROID &eventdata =
          *reinterpret_cast<XrEventDataSpatialAnnotationTrackingANDROID *>(
              &event);
      if (eventdata.initializationResult != XR_SUCCESS) {
        // handle initialization failure.
        // e.g. CHK_XR(xrDestroySpatialContextEXT(spatialContext));
      }
      break;
    }
    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, space);
      break;
    }
    }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Новые типы объектов

• XrSpatialReferenceCacheANDROID

Новые команды

• xrCreateSpatialReferenceCacheAsyncANDROID
• xrCreateSpatialReferenceCacheCompleteANDROID
• xrDestroySpatialReferenceCacheANDROID
• xrEnumerateSpatialAnnotationReferenceSourcesANDROID

Новые сооружения

• XrCreateSpatialReferenceCacheCompleteANDROID
• XrEventDataSpatialAnnotationTrackingANDROID
• XrSpatialAnnotationQuadANDROID
• XrSpatialAnnotationQuadDataANDROID
• XrSpatialCapabilityConfigurationAnnotationTrackingANDROID
• XrSpatialReferenceCacheCreateInfoANDROID

• Расширение XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentAnnotationQuadList ANDROID

• Расширение XrSpatialReferenceImageEXT :

  • XrSpatialAnnotationQuadReferenceANDROID

• Расширение XrSystemProperties :

  • XrSystemSpatialAnnotationProperties ANDROID

Новые перечисления

• XrSpatialAnnotationQuadAlignment ANDROID
• XrSpatialAnnotationReferenceSourceANDROID

Новые константы перечислений

• XR_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAME
• XR_ANDROID_spatial_annotation_tracking_SPEC_VERSION

• Расширение XrObjectType :

  • XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID

• Расширение XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

• Расширение XrSpatialComponentTypeEXT :

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

• Расширение XrStructureType :

  • XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
  • XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
  • XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
  • XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
  • XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
  • XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID

Проблемы

История версий

• Редакция 1, 17 сентября 2025 г. (Левана Чен)

  • Первоначальное описание расширения.