XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

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

Instance extension

Registered Extension Number

719

Пересмотр

3

Ratification Status

Not ratified

Extension and Version Dependencies

OpenXR 1.0

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

2025-05-15

IP Status

No known IP claims.

Авторы

Spencer Quin, Google
Jared Finder, Google
Antonio Fontan, Google
Cairn Overturf, Google
Нихав Джайн, Google
Салар Хан, 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 считается конфиденциальным, поскольку позволяет среде выполнения изучать окружение пользователя.

Для использования этих функций приложение должно запросить разрешение во время выполнения:

(protection level: dangerous)

Inspect system capability

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

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

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

  • type is the XrStructureType of this structure.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • supportsSceneMeshing — это тип данных XrBool32 , указывающий, поддерживает ли система создание сетки сцены.

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

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

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

Valid Usage (Implicit)

Перечисление 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_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

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

Enum Description

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

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

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

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

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

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

Parameter Descriptions

  • 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 , поскольку значение этого перечисления не указывает на наличие набора семантических меток и может использоваться в случае, если приложению не требуется вершинная семантика.

Valid Usage (Implicit)

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

Return Codes

Успех

  • 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

Create a scene meshing tracker handle 

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

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

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

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

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

Parameter Descriptions

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

Valid Usage (Implicit)

Return Codes

Успех

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

Member Descriptions

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

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

Valid Usage (Implicit)

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

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Parameter Descriptions

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

Valid Usage (Implicit)

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

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

Return Codes

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Create a scene mesh snapshot handle 

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

Дескриптор XrSceneMeshSnapshotANDROID представляет собой снимок сетки сцены. Этот снимок создается с помощью функции xrCreateSceneMeshSnapshotANDROID , которая делает снимок данных сетки сцены в момент вызова функции.

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

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

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

Parameter Descriptions

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

Valid Usage (Implicit)

Return Codes

Успех

  • 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 is the XrStructureType of this structure.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • baseSpace — это XrSpace , внутри которого представлена ​​информация о положении подсетки сцены.
  • time — это объект XrTime , описывающий время обработки или отображения сетки сцены, обычно это XrFrameState :: predictedDisplayTime .
  • boundingBox — это объект XrBoxf , описывающий ограничивающий прямоугольник, внутри которого будет получена сетка сцены.

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

Valid Usage (Implicit)

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

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • snapshot — это дескриптор XrSceneMeshSnapshotANDROID, созданный средой выполнения.
  • trackingState — это объект XrSceneMeshTrackingStateANDROID , описывающий состояние трекера сетки сцены на момент создания снимка.

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

Valid Usage (Implicit)

Перечисление 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;

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

Enum Description

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

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

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

The tracker is actively tracking.

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);

Parameter Descriptions

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

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

Valid Usage (Implicit)

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

Return Codes

Успех

  • 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 is the XrStructureType of this structure.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • submeshId is an XrUuid identifying the submesh.
  • lastUpdatedTime — это объект XrTime , представляющий время последнего обновления подсетки.
  • submeshPoseInBaseSpace — это объект XrPosef , представляющий позу подсетки в базовом пространстве, используемом для создания снимка сетки сцены. Поза также является центром ограничивающего параллелепипеда подсетки.
  • bounds — это объект XrExtent3Df , описывающий размеры ограничивающего параллелепипеда, который охватывает подсетку. Эти границы определены в базовом пространстве, которое использовалось для создания дескриптора сетки сцены.

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

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

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

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

Parameter Descriptions

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

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

Valid Usage (Implicit)

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

Return Codes

Успех

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • submeshId is an XrUuid identifying the submesh.
  • 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 см. в главе « Параметры размера буфера» .

Valid Usage (Implicit)

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

Перечисление 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;

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

Enum Description

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

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

Destroy a scene mesh snapshot

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

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Parameter Descriptions

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

Valid Usage (Implicit)

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

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

Return Codes

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Example code for scene meshing

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

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));

New Object Types

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

New Structures

New Enums

New Enum Constants

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • Extending XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

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

Проблемы

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

  • Revision 3, 2025-05-15 (Salar Khan)

    • Initial extension description