XR_EXT_spatial_plane_tracking

Name String

XR_EXT_spatial_plane_tracking

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

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

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

742

Revision

1

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

Ратифицировано

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

XR_EXT_spatial_entity

Авторы

Нихав Джайн (Nihav Jain), Google
Натали Флери (Natalie Fleury), Meta
Юичи Тагучи (Yuichi Taguchi), Meta
Рон Бессемс (Ron Bessems), Meta
Инь Ли (Yin Li), Microsoft
Джимми Алампарамбил (Jimmy Alamparambil), ByteDance
Чжипэн Лю (Zhipeng Liu), ByteDance
Цзюнь Янь (Jun Yan), ByteDance

Обзор

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

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

Если среда выполнения поддерживает отслеживание плоскостей, она должна указать это, перечислив XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT в xrEnumerateSpatialCapabilitiesEXT .

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

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

typedef struct XrSpatialCapabilityConfigurationPlaneTrackingEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationPlaneTrackingEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• capability – это XrSpatialCapabilityEXT, и его значение должно быть XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .
• enabledComponentCount – это uint32_t, описывающий количество элементов в массиве enabledComponents.
• enabledComponents – указатель на массив XrSpatialComponentTypeEXT .

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

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если capability не равно XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .

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

• Расширение XR_EXT_spatial_plane_tracking должно быть включено до использования XrSpatialCapabilityConfigurationPlaneTrackingEXT.
• type должно быть XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• capability должно быть допустимым значением XrSpatialCapabilityEXT.
• enabledComponents должен быть указателем на массив из enabledComponentCount допустимых значений XrSpatialComponentTypeEXT.
• Значение параметра enabledComponentCount должно быть больше 0.

Гарантированные компоненты

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

• XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
• XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Ограниченный двухмерный компонент

Ограниченный 2D-компонент предоставляет центр и границы плоскости, представленной объектом, на котором он находится. Подробнее об ограниченных 2D-объектах…

Компонент выравнивания плоскости

Данные компонента

typedef enum XrSpatialPlaneAlignmentEXT {
    XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_UPWARD_EXT = 0,
    XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_DOWNWARD_EXT = 1,
    XR_SPATIAL_PLANE_ALIGNMENT_VERTICAL_EXT = 2,
    XR_SPATIAL_PLANE_ALIGNMENT_ARBITRARY_EXT = 3,
    XR_SPATIAL_PLANE_ALIGNMENT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPlaneAlignmentEXT;

Перечисление XrSpatialPlaneAlignmentEXT описывает выравнивание плоскости, связанной с пространственным объектом, с компонентом XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT.

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

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

XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_UPWARD_EXT

Объект расположен горизонтально и обращен вверх (например, пол).

XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_DOWNWARD_EXT

Объект расположен горизонтально и обращен вниз (например, потолок).

XR_SPATIAL_PLANE_ALIGNMENT_VERTICAL_EXT

Объект вертикальный (например, стена).

XR_SPATIAL_PLANE_ALIGNMENT_ARBITRARY_EXT

Объект имеет произвольную ориентацию, не являющуюся ни вертикальной, ни горизонтальной.

Структура списка компонентов для запроса данных

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

typedef struct XrSpatialComponentPlaneAlignmentListEXT {
    XrStructureType                type;
    void*                          next;
    uint32_t                       planeAlignmentCount;
    XrSpatialPlaneAlignmentEXT*    planeAlignments;
} XrSpatialComponentPlaneAlignmentListEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• planeAlignmentCount – это uint32_t, описывающий количество элементов в массиве planeAlignments.
• planeAlignments – массив XrSpatialPlaneAlignmentEXT .

Чтобы запросить компонент выравнивания плоскости пространственных объектов в XrSpatialSnapshotEXT , включите XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT в XrSpatialComponentDataQueryConditionEXT :: componentTypes и добавьте XrSpatialComponentPlaneAlignmentListEXT в цепочку XrSpatialComponentDataQueryResultEXT :: next.

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

Среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT, если planeAlignmentCount меньше XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

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

• Расширение XR_EXT_spatial_plane_tracking должно быть включено до использования XrSpatialComponentPlaneAlignmentListEXT.
• type должно быть XR_TYPE_SPATIAL_COMPONENT_PLANE_ALIGNMENT_LIST_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• planeAlignments должен быть указателем на массив значений planeAlignmentCount XrSpatialPlaneAlignmentEXT.
• Значение параметра planeAlignmentCount должно быть больше 0.

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

Если XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT перечисляется в XrSpatialCapabilityComponentTypesEXT :: componentTypes для определенной функции, приложение может включить ее, добавив перечисляемый тип в список XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents производной структуры XrSpatialCapabilityConfigurationBaseHeaderEXT функции, которая поддерживает этот компонент.

Для включения этого компонента в цепочку XrSpatialCapabilityConfigurationBaseHeaderEXT :: next не требуется специальная конфигурация.

Дополнительные компоненты

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

Компонент Mesh 2D

Данные компонента

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT использует для своих данных структуру XrSpatialMeshDataEXT.

Структура списка компонентов для запроса данных

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

typedef struct XrSpatialComponentMesh2DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh2DListEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• meshCount – это uint32_t, описывающий количество элементов в массиве meshes.
• meshes – массив XrSpatialMeshDataEXT .

Чтобы запросить двухмерный компонент сетки пространственных объектов в XrSpatialSnapshotEXT , включите XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT в XrSpatialComponentDataQueryConditionEXT :: componentTypes и добавьте XrSpatialComponentMesh2DListEXT в цепочку XrSpatialComponentDataQueryResultEXT :: next.

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

Среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT, если meshCount меньше XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Для XrSpatialMeshDataEXT, заполненного средой выполнения в массиве meshes, XrSpatialBufferEXT :: bufferType для XrSpatialMeshDataEXT :: vertexBuffer должно быть XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT, а XrSpatialBufferEXT :: bufferType для XrSpatialMeshDataEXT :: indexBuffer должно быть XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

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

• Расширение XR_EXT_spatial_plane_tracking должно быть включено до использования XrSpatialComponentMesh2DListEXT.
• type должно быть XR_TYPE_SPATIAL_COMPONENT_MESH_2D_LIST_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• meshes должен быть указателем на массив структур meshCount XrSpatialMeshDataEXT.
• Значение параметра meshCount должно быть больше 0.

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

Если XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT перечисляется в XrSpatialCapabilityComponentTypesEXT :: componentTypes для определенной функции, приложение может включить ее, добавив перечисляемый тип в список XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents производной структуры XrSpatialCapabilityConfigurationBaseHeaderEXT функции, которая поддерживает этот компонент.

Для включения этого компонента в цепочку XrSpatialCapabilityConfigurationBaseHeaderEXT :: next не требуется специальная конфигурация.

Компонент "Многоугольник 2D"

Данные компонента

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

typedef struct XrSpatialPolygon2DDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
} XrSpatialPolygon2DDataEXT;

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

• origin – это XrPosef, определяющий начало координат многоугольника. Все вершины многоугольника задаются относительно этой точки в плоскости XY.
• vertexBuffer – это XrSpatialBufferEXT, который предоставляет идентификатор для буфера типа XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT и представляет буфер вершин объекта, на котором находится этот компонент. Вершины должны возвращаться в порядке против часовой стрелки. Многоугольник, образованный этими вершинами, не должен пересекать сам себя и может быть вогнутым.

XrSpatialBufferEXT :: bufferType для vertexBuffer должно быть XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

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

• Перед использованием XrSpatialPolygon2DDataEXT необходимо включить расширение XR_EXT_spatial_plane_tracking.
• vertexBuffer должен быть допустимой структурой XrSpatialBufferEXT.

Структура списка компонентов для запроса данных

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

typedef struct XrSpatialComponentPolygon2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      polygonCount;
    XrSpatialPolygon2DDataEXT*    polygons;
} XrSpatialComponentPolygon2DListEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• polygonCount – это uint32_t, описывающий количество элементов в массиве polygons.
• polygons – массив XrSpatialPolygon2DDataEXT .

Чтобы запросить двухмерный компонент многоугольника пространственных объектов в XrSpatialSnapshotEXT , включите XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT в XrSpatialComponentDataQueryConditionEXT :: componentTypes и добавьте XrSpatialComponentPolygon2DListEXT в цепочку XrSpatialComponentDataQueryResultEXT :: next.

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

Среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT, если polygonCount меньше XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

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

• Расширение XR_EXT_spatial_plane_tracking должно быть включено до использования XrSpatialComponentPolygon2DListEXT.
• type должно быть XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• polygons должен быть указателем на массив структур polygonCount XrSpatialPolygon2DDataEXT.
• Значение параметра polygonCount должно быть больше 0.

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

Если XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT перечисляется в XrSpatialCapabilityComponentTypesEXT :: componentTypes для определенной функции, приложение может включить ее, добавив перечисляемый тип в список XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents производной структуры XrSpatialCapabilityConfigurationBaseHeaderEXT функции, которая поддерживает этот компонент.

Для включения этого компонента в цепочку XrSpatialCapabilityConfigurationBaseHeaderEXT :: next не требуется специальная конфигурация.

Семантический ярлык самолета

Данные компонента

typedef enum XrSpatialPlaneSemanticLabelEXT {
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT = 2,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT = 3,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT = 4,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT = 5,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPlaneSemanticLabelEXT;

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

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

XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT

Среде выполнения не удалось классифицировать этот объект.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT

Объект – это этаж.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT

Объект – стена.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT

Объект – потолок.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT

Объект является таблицей.

Структура списка компонентов для запроса данных

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

typedef struct XrSpatialComponentPlaneSemanticLabelListEXT {
    XrStructureType                    type;
    void*                              next;
    uint32_t                           semanticLabelCount;
    XrSpatialPlaneSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentPlaneSemanticLabelListEXT;

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

• type – это XrStructureType этой структуры.
• next – это NULL или указатель на следующую структуру в цепочке.
• semanticLabelCount – это uint32_t, описывающий количество элементов в массиве semanticLabels.
• semanticLabels – это массив XrSpatialPlaneSemanticLabelEXT .

Чтобы запросить компонент семантического ярлыка плоскости пространственных объектов в XrSpatialSnapshotEXT , включите XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT в XrSpatialComponentDataQueryConditionEXT :: componentTypes и добавьте XrSpatialComponentPlaneSemanticLabelListEXT в цепочку XrSpatialComponentDataQueryResultEXT :: next.

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

Среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT, если semanticLabelCount меньше XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

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

• Расширение XR_EXT_spatial_plane_tracking должно быть включено до использования XrSpatialComponentPlaneSemanticLabelListEXT.
• type должно быть XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• semanticLabels должен быть указателем на массив значений semanticLabelCount XrSpatialPlaneSemanticLabelEXT.
• Значение параметра semanticLabelCount должно быть больше 0.

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

Если XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT перечисляется в XrSpatialCapabilityComponentTypesEXT :: componentTypes для определенной функции, приложение может включить ее, добавив перечисляемый тип в список XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents производной структуры XrSpatialCapabilityConfigurationBaseHeaderEXT функции, которая поддерживает этот компонент.

Для включения этого компонента в цепочку XrSpatialCapabilityConfigurationBaseHeaderEXT :: next не требуется специальная конфигурация.

Пример кода

Настройка функции отслеживания плоскостей

В примере кода ниже показано, как настроить отслеживание плоскостей при создании пространственного контекста.

// Check if plane tracking capability is supported
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_PLANE_TRACKING_EXT) == capabilities.end()) {
  return;
}

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

// Check if polygon 2D and plane semantic labels optional components are supported
const auto supportsComponent = [&planeCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(planeCapabilityComponents.begin(), planeCapabilityComponents.end(), component) != planeCapabilityComponents.end();
};

const bool supportsPolygon2DComponent = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
const bool supportsSemanticLabelComponent = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the 2 guaranteed components of the plane tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};
// Optionally enable polygon2D if it is supported
if (supportsPolygon2DComponent) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
}
// Optionally enable semantic labels if it is supported
if (supportsSemanticLabelComponent) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);
}

XrSpatialCapabilityConfigurationPlaneTrackingEXT planeConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT};
planeConfig.capability = XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT;
planeConfig.enabledComponentCount = enabledComponents.size();
planeConfig.enabledComponents = enabledComponents.data();

std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
  reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&planeConfig),
};

XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
XrFutureEXT createContextFuture;
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) {
  return;
}

spatialContext = completion.spatialContext;

// ...
// Discover entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Обнаружение пространственных объектов и запрос данных компонентов

В примере кода ниже показано, как обнаружить пространственные объекты для контекста, настроенного с помощью XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, и запросить данные его компонентов.

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};
if (supportsPolygon2DComponent) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
}
if (supportsSemanticLabelComponent) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

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

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    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.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

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

    std::vector<XrSpatialPolygon2DDataEXT> polygons;
    XrSpatialComponentPolygon2DListEXT polygonList{XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT};
    if (supportsPolygon2DComponent) {
      polygons.resize(queryResult.entityIdCountOutput);
      polygonList.polygonCount = polygons.size();
      polygonList.polygons = polygons.data();
      polygonList.next = queryResult.next;
      queryResult.next = &polygonList;
    }

    std::vector<XrSpatialPlaneSemanticLabelEXT> semanticLabels;
    XrSpatialComponentPlaneSemanticLabelListEXT semanticLabelsList{XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT};
    if (supportsSemanticLabelComponent) {
      semanticLabels.resize(queryResult.entityIdCountOutput);
      semanticLabelsList.semanticLabelCount = semanticLabels.size();
      semanticLabelsList.semanticLabels = semanticLabels.data();
      semanticLabelsList.next = queryResult.next;
      queryResult.next = &semanticLabelsList;
    }

    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) {
        continue;
      }

      // 2D bounds for entity entityIds[i] is bounded2D[i].extents centered on bounded2D[i].center.

      if (supportsPolygon2DComponent) {
        // 2D polygon for entity entityIds[i] is the buffer represented by polygons[i].bufferId.
        // Application uses flink:xrGetSpatialBufferVector2fEXT to get the buffer data.
      }

      if (supportsSemanticLabelComponent) {
        // semantic label for entity entityIds[i] is semanticLabels[i].
      }
    }

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

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

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

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

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

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

• XrSpatialCapabilityConfigurationPlaneTrackingEXT
• XrSpatialPolygon2DDataEXT

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

  • XrSpatialComponentMesh2DListEXT
  • XrSpatialComponentPlaneAlignmentListEXT
  • XrSpatialComponentPlaneSemanticLabelListEXT
  • XrSpatialComponentPolygon2DListEXT

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

• XrSpatialPlaneAlignmentEXT
• XrSpatialPlaneSemanticLabelEXT

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

• XR_EXT_SPATIAL_PLANE_TRACKING_EXTENSION_NAME
• XR_EXT_spatial_plane_tracking_SPEC_VERSION

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

  • XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

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

  • XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT
  • XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT
  • XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

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

  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT
  • XR_TYPE_SPATIAL_COMPONENT_MESH_2D_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_PLANE_ALIGNMENT_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT

Проблемы

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

• Версия 1, 2 июля 2024 г. (Нихав Джайн, Google)

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