XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

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

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

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

719

Revision

3

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

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

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

OpenXR 1.0

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

2025-05-15

Статус IP-адреса

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

Авторы

Спенсер Куин (Spencer Quin), Google
Джаред Финдер (Jared Finder), Google
Антонио Фонтан (Antonio Fontan), Google
Кэрн Овертурф (Cairn Overturf), Google
Нихав Джайн (Nihav Jain), Google
Салар Хан (Salar Khan), Google
Себастьян Клозе (Sebastian Klose), Google
Юрген Штурм (Jürgen Sturm), Google
Винни Да Силва (Vinny DaSilva), Google
Рикардо Кэмпбелл (Ricardo Campbell), Google

Обзор

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

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

Данные сетки сцены генерируются средой выполнения и передаются приложению с помощью XrSceneMeshingTrackerANDROID и XrSceneMeshSnapshotANDROID . Приложения могут получать доступ к значениям в информации о подсетке сцены через XrSceneSubmeshStateANDROID, возвращаемый из xrGetAllSubmeshStatesANDROID . Приложения могут получать доступ к значениям в данных о субмешах сцены через XrSceneSubmeshDataANDROID, возвращаемый из xrGetSubmeshDataANDROID .

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

Разрешения

В манифесте приложений для Android должно быть указано разрешение android.permission.SCENE_UNDERSTANDING_FINE. Разрешение android.permission.SCENE_UNDERSTANDING_FINE считается разрешением на доступ к конфиденциальной информации, поскольку позволяет среде выполнения изучать окружение пользователя.

Приложение должно запрашивать разрешение на использование следующих функций:

• xrCreateSceneMeshingTrackerANDROID
• xrDestroySceneMeshingTrackerANDROID
• xrCreateSceneMeshSnapshotANDROID
• xrDestroySceneMeshSnapshotANDROID
• xrGetAllSubmeshStatesANDROID
• xrGetSubmeshDataANDROID

(уровень защиты: опасный)

Проверка возможностей системы

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

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• supportsSceneMeshing – это XrBool32, указывающий, поддерживает ли система создание сетки сцены.

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

Если среда выполнения возвращает XR_FALSE для supportsSceneMeshing, система не поддерживает создание сетки сцены и поэтому должна возвращать XR_ERROR_FEATURE_UNSUPPORTED из xrCreateSceneMeshingTrackerANDROID . Приложение не должно использовать функцию создания сетки сцены, если для supportsSceneMeshing задано значение XR_FALSE .

Если среда выполнения возвращает XR_TRUE для supportsSceneMeshing , система поддерживает создание сетки сцены.

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

• Расширение XR_ANDROID_scene_meshing должно быть включено до использования XrSystemSceneMeshingPropertiesANDROID.
• type должно быть XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.

Перечисление XrSceneMeshSemanticLabelSetANDROID описывает наборы семантических ярлыков для мешинга сцены. Каждое значение в этом перечислении представляет собой другое перечисление, содержащее семантические метки. Например, значение XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID представляет набор XrSceneMeshSemanticLabelANDROID .

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID = 1000801000,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

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

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

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Этот набор семантических ярлыков представляет отсутствие семантических ярлыков.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

Этот набор семантических ярлыков представляет XrSceneMeshSemanticLabelANDROID.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

Этот набор семантических ярлыков представляет XrSceneMeshSemanticLabel2ANDROID. (Добавлено расширением XR_ANDROID_scene_meshing_semantic_label2)

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

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

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

• instance – это XrInstance, созданный приложением.
• systemId – это XrSystemId, полученный из xrGetSystem .
• supportedSemanticLabelSetsInputCapacity – емкость supportedSemanticLabelSets или 0 для получения требуемой емкости.
• supportedSemanticLabelSetsOutputCount – указатель на количество записанных supportedSemanticLabelSets или указатель на требуемую емкость, если supportedSemanticLabelSetsInputCapacity недостаточно.
• supportedSemanticLabelSets – указатель на массив XrSceneMeshSemanticLabelSetANDROID . Может быть NULL, если supportedSemanticLabelSetsInputCapacity равно 0.
• Подробное описание того, как получить нужный размер supportedSemanticLabelSets, приведено в разделе Параметры размера буфера.

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

Каждая система должна поддерживать как минимум XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID, поскольку это значение перечисления представляет собой набор семантических меток и может использоваться, если приложению не нужна семантика вершин.

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

• Расширение XR_ANDROID_scene_meshing должно быть включено до вызова xrEnumerateSupportedSemanticLabelSetsANDROID.
• instance должен быть действительным дескриптором XrInstance.
• supportedSemanticLabelSetsOutputCount должен быть указателем на значение uint32_t.
• Если supportedSemanticLabelSetsInputCapacity не равно 0 , supportedSemanticLabelSets должен быть указателем на массив значений supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID.

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

Выполнено

• XR_SUCCESS

Сбой

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

Создать дескриптор трекера сетки сцены

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

Дескриптор XrSceneMeshingTrackerANDROID представляет трекер для создания сетки сцены и управления связанными ресурсами.

Этот дескриптор можно использовать для создания снимка сетки сцены с помощью xrCreateSceneMeshSnapshotANDROID в этом расширении.

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

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

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

• session – это XrSession, в котором будет активен трекер сетки сцены.
• createInfo – указатель на структуру XrSceneMeshingTrackerCreateInfoANDROID, которая описывает создаваемый трекер.
• tracker – возвращенный дескриптор XrSceneMeshingTrackerANDROID.

Приложение может создать дескриптор XrSceneMeshingTrackerANDROID с помощью функции xrCreateSceneMeshingTrackerANDROID.

Если система не поддерживает мешинг сцены, среда выполнения должна возвращать XR_ERROR_FEATURE_UNSUPPORTED из xrCreateSceneMeshingTrackerANDROID . В этом случае среда выполнения должна возвращать XR_FALSE для XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing при вызове функции xrGetSystemProperties, чтобы приложение могло не создавать трекер разбиения сцены на полигоны.

При создании трекера сетки сцены приложение должно использовать только наборы семантических меток, поддерживаемые системой в XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet. Если приложение использует неподдерживаемый набор семантических меток вершин сетки сцены, среда выполнения должна возвращать XR_ERROR_FEATURE_UNSUPPORTED из xrCreateSceneMeshingTrackerANDROID .

Приложение может перечислить список поддерживаемых наборов семантических меток с помощью функции xrEnumerateSupportedSemanticLabelSetsANDROID.

Дескриптор xrCreateSceneMeshingTrackerANDROID владеет всеми ресурсами для создания сетки сцены. После завершения работы с сеткой сцены приложение должно удалить дескриптор с помощью функции xrDestroySceneMeshingTrackerANDROID.

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

• Расширение XR_ANDROID_scene_meshing должно быть включено до вызова xrCreateSceneMeshingTrackerANDROID.
• session должен быть действительным дескриптором XrSession.
• createInfo должен быть указателем на действительную структуру XrSceneMeshingTrackerCreateInfoANDROID.
• tracker должен быть указателем на дескриптор XrSceneMeshingTrackerANDROID.

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

Выполнено

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

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

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• semanticLabelSet – это XrSceneMeshSemanticLabelSetANDROID, который используется для указания набора семантических меток, используемых для создания сетки сцены. Если задано значение XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , среда выполнения будет игнорировать поле буфера XrSceneSubmeshDataANDROID :: vertexSemantics.
• enableNormals – это XrBool32, используемый для указания того, следует ли включать нормали вершин для вершин сетки в буфер сетки сцены при получении данных сетки сцены.

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

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

• Перед использованием XrSceneMeshingTrackerCreateInfoANDROID необходимо включить расширение XR_ANDROID_scene_meshing.
• type должно быть XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• semanticLabelSet должно быть допустимым значением XrSceneMeshSemanticLabelSetANDROID.

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

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

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

• tracker – это XrSceneMeshingTrackerANDROID, ранее созданный с помощью xrCreateSceneMeshingTrackerANDROID .

Функция xrDestroySceneMeshingTrackerANDROID освобождает tracker и базовые ресурсы после завершения работы с сеткой сцены.

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

• Расширение XR_ANDROID_scene_meshing должно быть включено до вызова xrDestroySceneMeshingTrackerANDROID.
• tracker должен быть действительным дескриптором XrSceneMeshingTrackerANDROID.

Потокобезопасность

• Доступ к tracker и любым дочерним дескрипторам должен быть синхронизирован извне.

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

Выполнено

• XR_SUCCESS

Сбой

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

Создать дескриптор снимка сетки сцены

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

Дескриптор XrSceneMeshSnapshotANDROID представляет снимок сетки сцены. Для этого используется функция xrCreateSceneMeshSnapshotANDROID, которая делает снимок данных сетки сцены в момент вызова функции.

Этот дескриптор можно использовать для получения информации и данных о подсетке с помощью xrGetAllSubmeshStatesANDROID и xrGetSubmeshDataANDROID .

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

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

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

• tracker – дескриптор XrSceneMeshingTrackerANDROID, ранее созданный с помощью xrCreateSceneMeshingTrackerANDROID .
• createInfo – указатель на структуру XrSceneMeshSnapshotCreateInfoANDROID, которая содержит информацию, необходимую для создания снимка сетки сцены.
• outSnapshotCreationResult – указатель на объект XrSceneMeshSnapshotCreationResultANDROID, который заполняется средой выполнения с результатом создания снимка.

Приложение может использовать функцию xrCreateSceneMeshSnapshotANDROID, чтобы создать снимок сетки сцены из трекера сетки сцены. Эта функция возвращает дескриптор XrSceneMeshSnapshotANDROID вместе с XrSceneMeshTrackingStateANDROID, упакованным в структуру XrSceneMeshSnapshotCreationResultANDROID. Технически дескриптор – это снимок данных сетки сцены на момент создания. Этот дескриптор можно использовать для запроса информации о сетке сцены и данных с помощью xrGetAllSubmeshStatesANDROID и xrGetSubmeshDataANDROID соответственно.

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

• Расширение XR_ANDROID_scene_meshing должно быть включено до вызова xrCreateSceneMeshSnapshotANDROID.
• tracker должен быть действительным дескриптором XrSceneMeshingTrackerANDROID.
• createInfo должен быть указателем на действительную структуру XrSceneMeshSnapshotCreateInfoANDROID.
• outSnapshotCreationResult должен быть указателем на структуру XrSceneMeshSnapshotCreationResultANDROID.

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

Выполнено

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Сбой

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_POSE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID

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

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• baseSpace – это XrSpace, в котором представлена информация о позе подсетки сцены.
• time – это XrTime, описывающий время, когда сетка сцены будет обработана или показана. Обычно это XrFrameState :: predictedDisplayTime .
• boundingBox – это XrBoxf, описывающий граничную рамку, в которой нужно получить сетку сцены.

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

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

• Расширение XR_ANDROID_scene_meshing должно быть включено до использования XrSceneMeshSnapshotCreateInfoANDROID.
• type должно быть XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• baseSpace должен быть действительным идентификатором XrSpace.

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

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• snapshot – дескриптор XrSceneMeshSnapshotANDROID, созданный средой выполнения.
• trackingState – это XrSceneMeshTrackingStateANDROID, описывающий состояние трекера сетки сцены на момент создания снимка.

Структура XrSceneMeshSnapshotCreationResultANDROID хранит результат создания снимка сетки сцены, возвращенный из xrCreateSceneMeshSnapshotANDROID .

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

• Перед использованием XrSceneMeshSnapshotCreationResultANDROID необходимо включить расширение XR_ANDROID_scene_meshing.
• type должно быть XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• snapshot должен быть действительным дескриптором XrSceneMeshSnapshotANDROID.
• trackingState должно быть допустимым значением XrSceneMeshTrackingStateANDROID.

Перечисление XrSceneMeshTrackingStateANDROID описывает состояние отслеживания для трекера сетки сцены. Каждое значение в этом перечислении представляет состояние трекера сетки сцены.

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

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

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

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

Трекер пока не готов предоставлять данные сетки.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

Трекер активно отслеживает.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

Трекер ожидает действительных измерений для интеграции с момента последнего обновления сетки.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

Трекер не получал действительных измерений в течение нескольких циклов и находится в состоянии ошибки.

Это состояние служит только дополнительной информацией для приложения. Если других источников ошибок нет, среда выполнения должна по-прежнему разрешать приложению создавать снимки и получать из них данные независимо от текущего значения XrSceneMeshTrackingStateANDROID трекера. Если статус не XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID , снимки могут быть неактуальными или пустыми.

Получение данных сетки сцены из ее снимка

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

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

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

• snapshot – дескриптор XrSceneMeshSnapshotANDROID, ранее созданный с помощью xrCreateSceneMeshSnapshotANDROID .
• submeshStateCapacityInput – емкость submeshStates или 0 для получения требуемой емкости.
• submeshStateCountOutput – указатель на количество записанных submeshStates или указатель на требуемую емкость, если submeshStateCapacityInput недостаточно.
• submeshStates – указатель на массив структур XrSceneSubmeshStateANDROID, в которые среда выполнения будет выводить состояние всех подсеток в сетке сцены. Может быть NULL, если submeshStateCapacityInput равно 0.
• Подробное описание того, как получить нужный размер submeshStates, приведено в разделе Параметры размера буфера.

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

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

• Расширение XR_ANDROID_scene_meshing должно быть включено до вызова xrGetAllSubmeshStatesANDROID.
• snapshot должен быть действительным дескриптором XrSceneMeshSnapshotANDROID.
• submeshStateCountOutput должен быть указателем на значение uint32_t.
• Если submeshStateCapacityInput не равно 0 , submeshStates должен быть указателем на массив структур submeshStateCapacityInput XrSceneSubmeshStateANDROID.

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

Выполнено

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Сбой

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• submeshId – это XrUuid, идентифицирующий подсетку.
• lastUpdatedTime – это XrTime, представляющий время последнего обновления подсетки.
• submeshPoseInBaseSpace – это XrPosef, представляющий позу подсетки в базовом пространстве, используемом для создания снимка сетки сцены. Поза также является центром ограничивающей рамки подсетки.
• bounds – это XrExtent3Df, описывающий размеры ограничивающей рамки, которая включает подсетку. Эти границы определяются в базовом пространстве, которое использовалось для создания дескриптора сетки сцены.

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

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

• Расширение XR_ANDROID_scene_meshing должно быть включено до использования XrSceneSubmeshStateANDROID.
• type должно быть XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.

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

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

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

• snapshot – дескриптор XrSceneMeshSnapshotANDROID, ранее созданный с помощью xrCreateSceneMeshSnapshotANDROID .
• submeshDataCount – длина inoutSubmeshData .
• inoutSubmeshData – это выделенный приложением массив XrSceneSubmeshDataANDROID, в котором среда выполнения заполняет каждый элемент данными сетки, связанными с идентификатором подсетки, переданным в XrSceneSubmeshDataANDROID :: submeshId .

Приложение может использовать функцию xrGetSubmeshDataANDROID, чтобы получить пакеты субмешей или все субмеши сразу. Для этого нужно передать список XrSceneSubmeshDataANDROID, в котором для каждого XrSceneSubmeshDataANDROID :: submeshId задан соответствующий идентификатор субмеша.

XrSceneSubmeshDataANDROID :: submeshId должен быть уникальным для каждого элемента в inoutSubmeshData и извлекаемым с помощью xrGetAllSubmeshStatesANDROID для того же snapshot . Если идентификатор подсетки недействителен или у нескольких элементов в inoutSubmeshData одинаковый идентификатор подсетки, то среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE .

submeshDataCount должно быть меньше или равно значению, возвращаемому xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput, иначе среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE .

Этот метод можно использовать в идиоме с двумя вызовами, чтобы запросить количество вершин и индексов для всех выбранных подсеток.

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

• Расширение XR_ANDROID_scene_meshing должно быть включено до вызова xrGetSubmeshDataANDROID.
• snapshot должен быть действительным дескриптором XrSceneMeshSnapshotANDROID.
• inoutSubmeshData должен быть указателем на массив структур submeshDataCount XrSceneSubmeshDataANDROID.
• Значение параметра submeshDataCount должно быть больше 0.

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

Выполнено

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Сбой

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
• submeshId – это XrUuid, идентифицирующий подсетку.
• vertexCapacityInput – емкость vertexPositions, vertexNormals и vertexSemantics или 0 для получения требуемой емкости.
• vertexCountOutput – указатель на количество записанных vertexPositions, vertexNormals и vertexSemantics или указатель на требуемую емкость, если vertexCapacityInput недостаточно.
• vertexPositions – массив XrVector3f, в который среда выполнения выведет позиции вершин подсетки.
• vertexNormals – массив XrVector3f, в который среда выполнения выведет нормали вершин подсетки. Это поле может быть пустым (NULL), если приложение создало трекер с отключенными нормалями.
• vertexSemantics – массив uint8_t, в который среда выполнения выводит семантику вершин подсетки. Это поле можно оставить NULL, если приложение создало трекер с набором семантических меток XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID.
• indexCapacityInput – емкость indices или 0 для получения требуемой емкости.
• indexCountOutput – указатель на количество записанных indices или указатель на требуемую емкость, если vertexCapacityInput недостаточно.
• indices – массив uint32_t, в который среда выполнения выведет индексы подсетки.
• Подробное описание того, как получить нужный размер vertexPositions, vertexNormals, vertexSemantics и indices, приведено в разделе Параметры размера буфера.

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

• Перед использованием XrSceneSubmeshDataANDROID необходимо включить расширение XR_ANDROID_scene_meshing.
• type должно быть XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• Если vertexCapacityInput не равно 0 , vertexPositions должен быть указателем на массив структур vertexCapacityInput XrVector3f.
• Если vertexCapacityInput не равно 0 , vertexNormals должен быть указателем на массив структур vertexCapacityInput XrVector3f.
• Если vertexCapacityInput не равно 0 , vertexSemantics должен быть указателем на массив значений vertexCapacityInput uint8_t.
• Если indexCapacityInput не равно 0 , indices должен быть указателем на массив значений indexCapacityInput uint32_t.

Перечисление XrSceneMeshSemanticLabelANDROID – это набор семантических меток по умолчанию, которые можно использовать для обозначения вершин сетки, чтобы описать, на какой поверхности физической среды находится вершина сетки. Этот набор перечислений представлен значением XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID в XrSceneMeshSemanticLabelSetANDROID .

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

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

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

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

Эта семантическая метка указывает, что соответствующий элемент сетки представляет неизвестный объект.

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

Этот семантический ярлык указывает, что соответствующий элемент сетки представляет собой пол.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

Эта семантическая метка указывает, что соответствующий элемент сетки представляет собой потолок.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

Эта семантическая метка указывает, что соответствующий элемент сетки представляет собой стену.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

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

Удалить снимок сетки сцены

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

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

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

• snapshot – дескриптор XrSceneMeshSnapshotANDROID, ранее созданный с помощью xrCreateSceneMeshSnapshotANDROID, который будет удален этой функцией.

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

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

• Расширение XR_ANDROID_scene_meshing должно быть включено до вызова xrDestroySceneMeshSnapshotANDROID.
• snapshot должен быть действительным дескриптором XrSceneMeshSnapshotANDROID.

Потокобезопасность

• Доступ к snapshot и любым дочерним дескрипторам должен быть синхронизирован извне.

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

Выполнено

• XR_SUCCESS

Сбой

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

Пример кода для создания сетки сцены

В примере кода ниже показано, как получить доступ к данным сетки сцены для рендеринга.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup
XrSpace appPlaySpace; // Created at app startup

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

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

• XrSceneMeshSnapshotANDROID
• XrSceneMeshingTrackerANDROID

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

• xrCreateSceneMeshSnapshotANDROID
• xrCreateSceneMeshingTrackerANDROID
• xrDestroySceneMeshSnapshotANDROID
• xrDestroySceneMeshingTrackerANDROID
• xrEnumerateSupportedSemanticLabelSetsANDROID
• xrGetAllSubmeshStatesANDROID
• xrGetSubmeshDataANDROID

Новые структуры

• XrSceneMeshSnapshotCreateInfoANDROID
• XrSceneMeshSnapshotCreationResultANDROID
• XrSceneMeshingTrackerCreateInfoANDROID
• XrSceneSubmeshDataANDROID
• XrSceneSubmeshStateANDROID

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

  • XrSystemSceneMeshingPropertiesANDROID

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

• XrSceneMeshSemanticLabelANDROID
• XrSceneMeshSemanticLabelSetANDROID
• XrSceneMeshTrackingStateANDROID

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

• XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
• XR_ANDROID_scene_meshing_SPEC_VERSION

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

  • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
  • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

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

  • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
  • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
  • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
  • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

Проблемы

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

• Версия 3, 15 мая 2025 г. (Салар Хан)

  • Описание расширения