XR_EXT_spatial_entity

String de nome

XR_EXT_spatial_entity

Tipo de extensão

Extensão de instância

Número de ramal registrado

741

Revisão

1

Status de ratificação

Ratified

Dependências de extensão e versão

XR_EXT_future

Colaboradores

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Karthik Kadappan, Magic Leap
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Visão geral

Essa extensão apresenta os conceitos e as bases para a compreensão de cenas e o raciocínio espacial no OpenXR. Isso unifica várias áreas de funcionalidade relacionadas, mas distintas, que são enumeradas, configuradas e interagem de maneira amplamente uniforme, conforme definido por essa extensão. Como essa extensão não tem definições concretas de nenhuma dessas áreas funcionais, o texto da especificação formal tende a ser um pouco abstrato. Os exemplos incluídos neste texto de especificação de extensão se referem, às vezes, à funcionalidade definida em uma extensão relacionada futura ou hipotética para fins de ilustração, sem limitar ou especificar inerentemente essa funcionalidade adicional.

As partes gerais dessa extensão são as seguintes:

  • Entidades espaciais : a funcionalidade é centrada em entidades , que oferecem pouca funcionalidade por conta própria.
  • Componentes espaciais : essas entidades têm componentes associados que fornecem dados e comportamentos.
  • Tipos de componentes espaciais : cada componente espacial é de um tipo de componente específico, e qualquer entidade tem no máximo um único componente de qualquer tipo de componente .
  • Contexto espacial : todas as interações de entidades espaciais ocorrem em um contexto após uma fase de inicialização e configuração.
  • Recursos espaciais : a manipulação de entidades espaciais é amplamente fornecida por recursos . Uma capacidade é uma unidade de funcionalidade, por exemplo (sem limitação), âncoras definidas pelo aplicativo, detecção de plano ou rastreamento de imagens. Cada recurso geralmente é definido em uma extensão separada (ativada na criação da instância, como de costume) e é ativado para um contexto específico no momento da criação.
  • Cada recurso está associado a um conjunto de tipos de componentes para os quais os componentes estão presentes em cada entidade exposta por esse recurso . A extensão que define uma capacidade especifica quais tipos de componente são obrigatórios para a capacidade ("garantidos"), enquanto essa mesma extensão ou outras podem especificar tipos de componente opcionais fornecidos por algumas implementações em potencial. Qualquer número de recursos pode fornecer entidades com componentes de um determinado tipo de componente, que são utilizáveis de maneira uniforme, independentemente do recurso que o produziu.
  • Recursos de capacidade espacial : além disso, algumas capacidades exigem configuração e, portanto, são parametrizadas por recursos de capacidade .

Essa extensão fornece um mecanismo para enumerar os componentes fornecidos por cada recurso compatível com o sistema atual, tanto os obrigatórios quanto os componentes opcionais.

Como algumas implementações podem exigir diferentes graus de parametrização para recursos , essa extensão fornece um mecanismo para enumerar os recursos de capacidade compatíveis associados a um determinado recurso no sistema atual.

Essa extensão também define vários componentes comuns que devem ser usados em uma ampla variedade de recursos .

Entidade espacial

As entidades espaciais são entidades que existem em algum espaço e têm vários dados associados organizados em componentes. Eles podem ser:

  • Físico (por exemplo, superfícies planas, como paredes e pisos, objetos como cadeiras e estantes etc.)
  • Virtual (por exemplo, conteúdo colocado e compartilhado por outro aplicativo ou usuário)
  • Definido pelo app (por exemplo, o aplicativo marca uma área como "sala de estar" ou "cozinha" ou marca um ponto como o local para colocar a TV etc.)

Os elementos expostos pelo sistema de ações, como controles ou olhar, não devem ser modelados como entidades espaciais.

As entidades espaciais no OpenXR são modeladas como um sistema de componentes de entidade . Cada entidade espacial tem um conjunto de componentes, e cada componente fornece um conjunto exclusivo de dados e comportamentos para essa entidade.

As entidades espaciais são representadas por um átomo XrSpatialEntityIdEXT ou um identificador XrSpatialEntityEXT. Os detalhes são fornecidos na seção Representações de entidades espaciais.

Tipos de componentes espaciais

Uma entidade espacial tem um ou mais componentes que fornecem dados ou comportamentos para essa entidade. Consulte Componentes comuns para ver alguns componentes comuns definidos por essa extensão.

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID = 1000803000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1 = 1000808000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

A enumeração XrSpatialComponentTypeEXT identifica os diferentes tipos de componentes que o ambiente de execução pode aceitar.

Nem todos os tipos de componentes listados são fornecidos por essa extensão por conta própria: alguns exigem que outras extensões sejam ativadas no momento da criação da instância, conforme documentado.

Os enumeradores têm os seguintes valores:

Descrição do tipo enumerado

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Componente que fornece os limites 2D para uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentBounded2DListEXT. A estrutura de dados correspondente é XrSpatialBounded2DDataEXT.

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

Componente que fornece os limites 3D de uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentBounded3DListEXT. A estrutura de dados correspondente é XrBoxf.

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

Componente que fornece o XrSpatialEntityIdEXT do pai para uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentParentListEXT. A estrutura de dados correspondente é XrSpatialEntityIdEXT.

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

Componente que fornece uma malha 3D para uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentMesh3DListEXT. A estrutura de dados correspondente é XrSpatialMeshDataEXT.

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Componente que fornece o tipo enumerado de alinhamento de plano para uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentPlaneAlignmentListEXT. A estrutura de dados correspondente é XrSpatialPlaneAlignmentEXT (adicionada pela extensão XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

Componente que fornece uma malha 2D para uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentMesh2DListEXT. A estrutura de dados correspondente é XrSpatialMeshDataEXT (adicionada pela extensão XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

Componente que fornece um polígono de limite 2D para uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentPolygon2DListEXT. A estrutura de dados correspondente é XrSpatialPolygon2DDataEXT (adicionada pela extensão XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

Componente que fornece um rótulo semântico para um plano. A estrutura de lista correspondente é XrSpatialComponentPlaneSemanticLabelListEXT. A estrutura de dados correspondente é XrSpatialPlaneSemanticLabelEXT (adicionada pela extensão XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

Um componente que descreve o tipo, o ID e o local do marcador. A estrutura de lista correspondente é XrSpatialComponentMarkerListEXT. A estrutura de dados correspondente é XrSpatialMarkerDataEXT (adicionada pela extensão XR_EXT_spatial_marker_tracking).

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

Componente que fornece um rótulo semântico para uma cena. A estrutura de lista correspondente é XrSpatialComponentObjectSemanticLabelListEXT. A estrutura de dados correspondente é XrSpatialObjectSemanticLabelEXT . (Adicionado pela extensão XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

Componente que fornece um rótulo semântico para um teclado. A estrutura de lista correspondente é XrSpatialComponentKeyboardSemanticLabelListEXT. A estrutura de dados correspondente é XrSpatialKeyboardSemanticLabelEXT (adicionada pela extensão XR_EXT_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

Componente que fornece um rótulo semântico para um mouse. A estrutura de lista correspondente é XrSpatialComponentMouseSemanticLabelListEXT. A estrutura de dados correspondente é XrSpatialMouseSemanticLabelEXT (adicionada pela extensão XR_EXT_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Componente que fornece o local de uma âncora. A estrutura de lista correspondente é XrSpatialComponentAnchorListEXT. A estrutura de dados correspondente é XrPosef (adicionada pela extensão XR_EXT_spatial_anchor).

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

Componente que fornece o UUID persistente para uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentPersistenceListEXT. A estrutura de dados correspondente é XrSpatialPersistenceDataEXT (adicionada pela extensão XR_EXT_spatial_persistence).

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

Um componente que descreve o tipo de imagem planar. A estrutura de lista correspondente é XrSpatialComponentImage2DListEXT. A estrutura de dados correspondente é XrSpatialImageSizeEXT. (Adicionado pela extensão XR_EXT_spatial_image_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

Componente que fornece as normais para a malha 3D de uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentMesh3DNormalsListEXT. A estrutura de dados correspondente é XrSpatialBufferEXT (adicionada pela extensão XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

Componente que fornece os rótulos semânticos por vértice para a malha 3D de uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentMesh3DVertexSemanticLabelsListEXT. A estrutura de dados correspondente é XrSpatialBufferEXT. Os dados no buffer são mapeados para XrSpatialMeshSemanticLabelEXT (adicionado pela extensão XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

Componente que fornece os rótulos semânticos por face triangular para a malha 3D de uma entidade espacial. A estrutura de lista correspondente é XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT. A estrutura de dados correspondente é XrSpatialBufferEXT. Os dados no buffer são mapeados para XrSpatialMeshSemanticLabelEXT (adicionado pela extensão XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

Componente que fornece um rótulo semântico para um objeto. A estrutura de lista correspondente é XrSpatialComponentObjectSemanticLabelListANDROID. A estrutura de dados correspondente é XrSpatialObjectSemanticLabelANDROID (adicionada pela extensão XR_ANDROID_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Componente que fornece a pose de um hit de raycast em uma entidade. A estrutura de lista correspondente é XrSpatialComponentRaycastResultListANDROID. A estrutura de dados correspondente é XrSpatialRaycastResultDataANDROID (adicionada pela extensão XR_ANDROID_spatial_discovery_raycast).

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

Componente que fornece o ID da entidade que inclui a entidade anexada. A estrutura de lista correspondente é XrSpatialComponentSubsumedByListANDROID. A estrutura de dados correspondente é XrSpatialEntityIdEXT (adicionada pela extensão XR_ANDROID_spatial_component_subsumed_by).

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

Componente que fornece as dimensões e o tipo de quarto de uma caixa de sapatos. A estrutura de lista correspondente é XrSpatialComponentRoomListANDROIDSYS. A estrutura de dados correspondente é XrSpatialRoomDataANDROIDSYS (adicionada pela extensão XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

Componente que fornece o tipo de material de uma superfície de limite. A estrutura de lista correspondente é XrSpatialComponentMaterialTypeListANDROIDSYS. A estrutura de dados correspondente é XrSpatialMaterialTypeANDROIDSYS (adicionada pela extensão XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

Componente que fornece a confiança de um rastreável. A estrutura de lista correspondente é XrSpatialComponentConfidenceListANDROIDSYS. A estrutura de dados correspondente é float (adicionada pela extensão XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

Componente que indica se um quarto está vazio. A estrutura de lista correspondente é XrSpatialComponentRoomEmptinessListANDROIDSYS. A estrutura de dados correspondente é float (adicionada pela extensão XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

Componente que fornece informações sobre a grade de ocupação na entidade anexada. A estrutura de lista correspondente é XrSpatialComponentOccupancyGridListANDROIDX1. A estrutura de dados correspondente é XrSpatialOccupancyGridDataANDROIDX1 (adicionada pela extensão XR_ANDROIDX1_spatial_occupancy_grid).

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Um componente que descreve uma anotação quádrupla. A estrutura de lista correspondente é XrSpatialComponentAnnotationQuadListANDROID. A estrutura de dados correspondente é XrSpatialAnnotationQuadDataANDROID (adicionada pela extensão XR_ANDROID_spatial_annotation_tracking).

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

Componente que fornece os metadados de uma geometria de paisagem urbana. A estrutura de lista correspondente é XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2. A estrutura de dados correspondente é XrSpatialStreetscapeGeometryMetadataANDROIDX2 (adicionada pela extensão XR_ANDROIDX2_geospatial_streetscape).

XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID

Componente que identifica uma entidade como um ponto de geometria. Não há uma lista ou estrutura de dados correspondente para esse tipo de componente. A presença desse componente indica apenas que uma entidade pode ser anexada a uma âncora. (Adicionado pela extensão XR_ANDROID_spatial_geometry_point)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1

Um componente que descreve os escopos de persistência em que a entidade é mantida. Se o ambiente de execução for compatível com XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT, ele precisa também ser compatível com esse componente. A estrutura de dados correspondente é XrSpatialBufferEXT . A estrutura de lista correspondente é XrSpatialComponentPersistenceScopeDataListANDROIDX1 . (Adicionado pela extensão XR_ANDROIDX1_spatial_anchor_cloud_sharing)

Configuração e recursos espaciais

Os recursos espaciais definem as habilidades de um ambiente de execução para descobrir entidades que têm um conjunto garantido de componentes. Os aplicativos ativam os componentes de um recurso espacial ao criar o XrSpatialContextEXT, e o ambiente de execução precisa fornecer apenas os componentes ativados nas entidades descobertas. Por exemplo, se um ambiente de execução informar que um dos componentes de um determinado recurso é "rótulos semânticos", isso significa que o aplicativo pode ativar rótulos semânticos pela configuração desse recurso, e o ambiente de execução precisa fornecer apenas o componente de rótulo semântico se ele estiver configurado.

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

A enumeração XrSpatialCapabilityEXT identifica os diferentes tipos de recursos que o ambiente de execução pode oferecer.

Os enumeradores têm os seguintes valores:

Descrição do tipo enumerado

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

Rastreamento de plano (adicionado pela extensão XR_EXT_spatial_plane_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

Capacidade de detectar e rastrear QR codes. (Adicionado pela extensão XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

Capacidade de detectar e rastrear Micro QR codes. (Adicionado pela extensão XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

Capacidade de detectar e rastrear marcadores ArUco. (Adicionado pela extensão XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

Capacidade de detectar e rastrear AprilTags. (Adicionado pela extensão XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

Rastreamento de objetos (adicionado pela extensão XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

Capacidade de criar âncoras espaciais (adicionada pela extensão XR_EXT_spatial_anchor)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Capacidade de detectar e rastrear imagens de referência planas. (Adicionado pela extensão XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

Capacidade de rastrear a malha de um ambiente. (Adicionado pela extensão XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

Rastreamento de objetos (adicionado pela extensão XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Raycast em relação ao buffer de profundidade (adicionado pela extensão XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

Capacidade de rastrear uma sala (adicionada pela extensão XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

Capacidade de rastrear o limite de uma sala (adicionada pela extensão XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Rastreamento de anotações (adicionado pela extensão XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

Geometria da paisagem urbana (adicionada pela extensão XR_ANDROIDX2_geospatial_streetscape)

A função xrEnumerateSpatialCapabilitiesEXT é definida como:

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

Descrições dos parâmetros

  • instance é um identificador para uma XrInstance .
  • systemId é o XrSystemId com os recursos espaciais que serão enumerados.
  • capabilityCapacityInput é a capacidade da matriz capabilities ou 0 para indicar uma solicitação de recuperação da capacidade necessária.
  • capabilityCountOutput é o número de recursos ou a capacidade necessária caso capabilityCapacityInput seja insuficiente.
  • capabilities é uma matriz de XrSpatialCapabilityEXT . Pode ser NULL se capabilityCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de capabilities necessário.

O aplicativo pode enumerar a lista de recursos espaciais compatíveis com um determinado XrSystemId usando xrEnumerateSpatialCapabilitiesEXT .

O ambiente de execução não pode enumerar os recursos espaciais cuja extensão não está ativada para instance .

Uso válido (implícito)

  • A extensão XR_EXT_spatial_entity precisa ser ativada antes de chamar xrEnumerateSpatialCapabilitiesEXT
  • instance precisa ser um identificador XrInstance válido
  • capabilityCountOutput precisa ser um ponteiro para um valor uint32_t
  • Se capabilityCapacityInput não for 0 , capabilities precisa ser um ponteiro para uma matriz de valores capabilityCapacityInput XrSpatialCapabilityEXT

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • 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

A função xrEnumerateSpatialCapabilityComponentTypesEXT é definida como:

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

Descrições dos parâmetros

  • instance é um identificador para uma XrInstance .
  • systemId é o XrSystemId cujos componentes de capacidade espacial serão enumerados.
  • capability é o XrSpatialCapabilityEXT para o qual os componentes serão enumerados.
  • capabilityComponents é um ponteiro para um XrSpatialCapabilityComponentTypesEXT , que é uma estrutura de entrada/saída em que uma matriz alocada pelo aplicativo é preenchida.

Essa função enumera os tipos de componentes que o recurso fornecido oferece nas entidades no sistema, conforme configurado.

O aplicativo pode usar os tipos de componente enumerados em XrSpatialCapabilityComponentTypesEXT :: componentTypes para entender o conjunto completo de componentes que o systemId oferece para capability e pode usar essa lista para determinar qual é uma configuração válida para capability ao criar um XrSpatialContextEXT para ele.

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se capability não for enumerado por xrEnumerateSpatialCapabilitiesEXT .

O ambiente de execução não pode enumerar os tipos de componentes espaciais cuja extensão não está ativada para instance .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

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

A estrutura XrSpatialCapabilityComponentTypesEXT é definida como:

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • componentTypeCapacityInput é a capacidade da matriz ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • componentTypeCountOutput é o número de tipos de componentes ou a capacidade necessária caso componentTypeCapacityInput seja insuficiente.
  • componentTypes é uma matriz de XrSpatialComponentTypeEXT . Pode ser NULL se componentTypeCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de componentTypes necessário.

Uso válido (implícito)

Recursos de capacidade espacial

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

Alguns recursos têm parâmetros expostos ao aplicativo para configurar como os dados do componente são calculados pelo ambiente de execução. Essas dimensões de parametrização/configurabilidade são conhecidas como recursos de capacidade. Por exemplo, para um recurso de rastreamento de imagens, um ambiente de execução pode oferecer suporte a um recurso para que o aplicativo especifique se as imagens rastreadas são estacionárias ou não.

Fornecer essas informações ao ambiente de execução por uma estrutura de configuração não pode mudar o conjunto de tipos de componentes presentes nas entidades associadas, por exemplo, na imagem rastreada. No entanto, o ambiente de execução pode otimizar, por exemplo, os recursos de rastreamento de imagens e oferecer uma experiência melhor ao aplicativo.

Esses recursos são representados por XrSpatialCapabilityFeatureEXT, e o aplicativo os enumera usando xrEnumerateSpatialCapabilityFeaturesEXT .

Cada recurso de capacidade tem uma estrutura de configuração correspondente para ser ativado. Essas estruturas de configuração precisam ser encadeadas a XrSpatialCapabilityConfigurationBaseHeaderEXT :: next da capacidade correspondente.

Os enumeradores têm os seguintes valores:

Descrição do tipo enumerado

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

Recurso de capacidade para permitir que os aplicativos especifiquem o tamanho dos marcadores. A estrutura de configuração correspondente é XrSpatialMarkerSizeEXT (adicionada pela extensão XR_EXT_spatial_marker_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

Recurso de capacidade para permitir que os aplicativos especifiquem se os marcadores são estáticos. A estrutura de configuração correspondente é XrSpatialMarkerStaticOptimizationEXT (adicionada pela extensão XR_EXT_spatial_marker_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Recurso espacial que permite que os aplicativos especifiquem um subconjunto de rótulos de XrSpatialObjectSemanticLabelEXT para o ambiente de execução rastrear. A estrutura de configuração correspondente é XrSpatialFeatureObjectSemanticLabelSubsetEXT . (Adicionado pela extensão XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

O ambiente de execução oferece suporte ao filtro XrSpatialBoundsSpherefANDROID para XrSpatialDiscoverySnapshotCreateInfoEXT. Isso não exige que nenhuma estrutura de configuração seja incluída durante a criação do contexto espacial. (Adicionado pela extensão XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

O ambiente de execução oferece suporte ao filtro XrSpatialBoundsBoxfANDROID para XrSpatialDiscoverySnapshotCreateInfoEXT. Isso não exige que nenhuma estrutura de configuração seja incluída durante a criação do contexto espacial. (Adicionado pela extensão XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

O ambiente de execução oferece suporte ao filtro XrSpatialBoundsFrustumfANDROID para XrSpatialDiscoverySnapshotCreateInfoEXT. Isso não exige que nenhuma estrutura de configuração seja incluída durante a criação do contexto espacial. (Adicionado pela extensão XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

O ambiente de execução é compatível com a dedução automática do tamanho físico das imagens detectadas e rastreadas. A estrutura de configuração correspondente é XrSpatialImageSizeEXT (adicionada pela extensão XR_EXT_spatial_image_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

O ambiente de execução é compatível com XrSpatialImageStaticOptimizationEXT . A estrutura de configuração correspondente é XrSpatialImageStaticOptimizationEXT . (Adicionado pela extensão XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

O ambiente de execução é compatível com XrSpatialImageSizeEXT . A estrutura de configuração correspondente é XrSpatialImageSizeEXT (adicionada pela extensão XR_EXT_spatial_image_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

Recurso de capacidade para rastrear uma malha estanque do ambiente. A estrutura de configuração correspondente é XrSpatialFeatureTrackWatertightMeshEXT . (Adicionado pela extensão XR_EXT_spatial_mesh_tracking)

A função xrEnumerateSpatialCapabilityFeaturesEXT é definida como:

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

Descrições dos parâmetros

  • instance é um identificador para uma XrInstance .
  • systemId é o XrSystemId cujos recursos de capacidade espacial serão enumerados.
  • capability é o XrSpatialCapabilityEXT para o qual os recursos serão enumerados.
  • capabilityFeatureCapacityInput é a capacidade da matriz ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • capabilityFeatureCountOutput é o número de recursos ou a capacidade necessária caso capabilityFeatureCapacityInput seja insuficiente.
  • capabilityFeatures é uma matriz de XrSpatialCapabilityFeatureEXT . Pode ser NULL se capabilityFeatureCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de capabilityFeatures necessário.

O aplicativo descobre os recursos compatíveis com um determinado sistema para um XrSpatialCapabilityEXT usando xrEnumerateSpatialCapabilityFeaturesEXT .

Para capabilities que têm recursos expostos, o aplicativo seleciona os recursos que serão ativados e fornece a estrutura de configuração correspondente na próxima cadeia de estruturas de configuração de capability em XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Se capability não for um recurso enumerado por xrEnumerateSpatialCapabilitiesEXT , o ambiente de execução precisará retornar XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

O ambiente de execução não pode enumerar os recursos de capacidade espacial cuja extensão não está ativada para instance .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

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

Contexto espacial

Criar um contexto espacial

XR_DEFINE_HANDLE(XrSpatialContextEXT)

O identificador XrSpatialContextEXT representa os recursos para descobrir e atualizar um número de entidades espaciais no ambiente do usuário. O aplicativo pode usar esse identificador para descobrir e atualizar entidades espaciais usando outras funções nessa extensão.

A função xrCreateSpatialContextAsyncEXT é definida como:

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

Descrições dos parâmetros

  • session é uma XrSession em que o contexto espacial estará ativo.
  • createInfo é o XrSpatialContextCreateInfoEXT usado para especificar os parâmetros de contexto espacial.
  • future é um ponteiro para um XrFutureEXT .

O aplicativo pode criar um identificador XrSpatialContextEXT:

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT se XrSpatialContextCreateInfoEXT ::capabilityConfigCount for 0. Um identificador de contexto espacial precisa de pelo menos um recurso.

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se algum recurso na matriz XrSpatialContextCreateInfoEXT :: capabilityConfigs não for enumerado por xrEnumerateSpatialCapabilitiesEXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT se qualquer XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount em XrSpatialContextCreateInfoEXT :: capabilityConfigs for 0. Uma configuração de recurso fica incompleta sem uma lista de tipos de componentes para ativar esse recurso.

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT se algum tipo de componente listado em XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents não estiver enumerado para XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability em xrEnumerateSpatialCapabilityComponentTypesEXT .

Se alguma das estruturas na próxima cadeia de XrSpatialContextCreateInfoEXT :: capabilityConfigs corresponder a um XrSpatialCapabilityFeatureEXT que não esteja enumerado para esse recurso em xrEnumerateSpatialCapabilityFeaturesEXT , o ambiente de execução precisa ignorar essa estrutura XrSpatialCapabilityFeatureEXT.

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT se XrSpatialContextCreateInfoEXT :: capabilityConfigs contiver várias estruturas com o mesmo XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability .

Para garantir o uso ideal dos recursos do sistema, o ambiente de execução pode usar as configurações fornecidas na matriz XrSpatialContextCreateInfoEXT para se preparar para as solicitações espaciais que vão chegar. Por exemplo, um ambiente de execução que oferece suporte ao recurso de rastreamento de plano pode iniciar o pipeline de rastreamento de plano somente se um identificador de contexto espacial que contém o recurso de rastreamento de plano for criado pelo aplicativo. Se os recursos configurados tiverem um tempo de aquecimento longo, as chamadas para xrCreateSpatialDiscoverySnapshotAsyncEXT podem resultar em um snapshot vazio. O aplicativo pode esperar por XrEventDataSpatialDiscoveryRecommendedEXT antes de usar xrCreateSpatialDiscoverySnapshotAsyncEXT para garantir que os serviços de rastreamento subjacentes tenham sido inicializados.

Se um ambiente de execução aplicar um sistema de permissões para controlar o acesso do aplicativo aos recursos espaciais que estão sendo configurados para o XrSpatialContextEXT , ele precisará retornar XR_ERROR_PERMISSION_INSUFFICIENT se essas permissões não tiverem sido concedidas ao aplicativo.

Essa função inicia uma operação assíncrona e cria um XrFutureEXT correspondente, que pode ser usado com xrPollFutureEXT e funções relacionadas. O valor de retorno dessa função indica apenas se os parâmetros eram aceitáveis para programar a operação assíncrona. A função de conclusão correspondente é xrCreateSpatialContextCompleteEXT , que pode ser usada quando um futuro dessa função está no estado READY, com saídas preenchidas por essa função na estrutura de conclusão XrCreateSpatialContextCompletionEXT .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_TIME_INVALID (se XR_ANDROID_spatial_annotation_tracking estiver ativado)

A estrutura XrSpatialContextCreateInfoEXT é definida como:

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • capabilityConfigCount é um uint32_t que descreve a contagem de elementos na matriz capabilityConfigs.
  • capabilityConfigs é um ponteiro para uma matriz de ponteiros XrSpatialCapabilityConfigurationBaseHeaderEXT.

A estrutura XrSpatialContextCreateInfoEXT descreve as informações para criar um identificador XrSpatialContextEXT.

Uso válido (implícito)

A estrutura XrSpatialCapabilityConfigurationBaseHeaderEXT é definida como:

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

Essa estrutura não é usada diretamente na API, mas as estruturas filhas dela podem ser usadas com XrSpatialContextCreateInfoEXT para configurar recursos espaciais.

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • capability é um XrSpatialCapabilityEXT .
  • enabledComponentCount é um uint32_t que descreve a contagem de elementos na matriz enabledComponents.
  • enabledComponents é um ponteiro para uma matriz de XrSpatialComponentTypeEXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se capability não for enumerado por xrEnumerateSpatialCapabilitiesEXT . O ambiente de execução precisa retornar XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT se algum tipo de componente listado em enabledComponents não estiver enumerado para capability em xrEnumerateSpatialCapabilityComponentTypesEXT .

Uso válido (implícito)

A função xrCreateSpatialContextCompleteEXT é definida como:

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

Descrições dos parâmetros

xrCreateSpatialContextCompleteEXT conclui a operação assíncrona iniciada por xrCreateSpatialContextAsyncEXT . O ambiente de execução precisa retornar XR_ERROR_FUTURE_PENDING_EXT se future não estiver no estado pronto. O ambiente de execução precisa retornar XR_ERROR_FUTURE_INVALID_EXT se future já tiver sido concluído ou cancelado.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrCreateSpatialContextCompletionEXT é definida como:

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

Descrições dos membros

Códigos de retorno futuros

Valores de futureResult:

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

Se futureResult for um código de sucesso, spatialContext precisa ser válido. Se spatialContext for válido, ele vai permanecer assim apenas no ciclo de vida de xrCreateSpatialContextAsyncEXT :: session ou até que o aplicativo destrua o spatialContext com xrDestroySpatialContextEXT , o que ocorrer primeiro.

Uso válido (implícito)

Destruir o contexto espacial

A função xrDestroySpatialContextEXT é definida como:

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

Descrições dos parâmetros

O aplicativo pode chamar a função xrDestroySpatialContextEXT para liberar o identificador spatialContext e os recursos subjacentes quando terminar as tarefas de descoberta e atualização de entidades espaciais. Se não houver outro XrSpatialContextEXT válido criado com os mesmos recursos espaciais que spatialContext , essa chamada serve como uma sugestão para o ambiente de execução desativar os serviços de rastreamento necessários para que esses recursos economizem recursos do sistema.

Uso válido (implícito)

Concorrência segura

  • O acesso a spatialContext e a qualquer identificador filho precisa ser sincronizado externamente.

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Representações de entidades espaciais

ID da entidade espacial

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT é usado para representar qualquer tipo de entidade descoberta pelo ambiente de execução no ambiente espacial do usuário. Um XrSpatialEntityIdEXT é válido para o XrSpatialContextEXT em que é descoberto, e o ambiente de execução não pode reutilizar o mesmo XrSpatialEntityIdEXT para entidades diferentes no mesmo XrSpatialContextEXT . Além disso, o ambiente de execução não pode reutilizar o mesmo XrSpatialEntityIdEXT em vários XrSpatialContextEXT na mesma XrSession, mesmo que represente a mesma entidade ou entidades diferentes.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT é um valor reservado que representa um XrSpatialEntityIdEXT inválido. Ele pode ser transmitido e retornado de funções de API somente quando permitido especificamente.

Identificador de entidade espacial

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

O identificador XrSpatialEntityEXT representa uma entidade espacial. Um aplicativo pode criar esse identificador para expressar ao ambiente de execução o interesse em uma entidade específica.

Criar identificador de entidade espacial com base no ID

A função xrCreateSpatialEntityFromIdEXT é definida como:

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

Descrições dos parâmetros

O aplicativo pode usar xrCreateSpatialEntityFromIdEXT para criar um identificador XrSpatialEntityEXT, que é uma referência a uma entidade que existe no ambiente do usuário.

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT se XrSpatialEntityFromIdCreateInfoEXT :: entityId não for um ID válido para spatialContext .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrSpatialEntityFromIdCreateInfoEXT é definida como:

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • entityId é o XrSpatialEntityIdEXT da entidade para que o aplicativo quer criar um identificador.

Uso válido (implícito)

Destruir identificador de entidade espacial

A função xrDestroySpatialEntityEXT é definida como:

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

Descrições dos parâmetros

O aplicativo pode usar xrDestroySpatialEntityEXT para liberar o identificador spatialEntity quando não estiver mais interessado na entidade referenciada por ele.

Uso válido (implícito)

Concorrência segura

  • O acesso a spatialEntity e a qualquer identificador filho precisa ser sincronizado externamente.

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Snapshot espacial

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

O aplicativo pode criar snapshots espaciais para descobrir entidades espaciais ou atualizar as informações sobre entidades espaciais conhecidas. O identificador XrSpatialSnapshotEXT representa os dados imutáveis das entidades espaciais descobertas ou atualizadas e um subconjunto dos componentes delas, conforme selecionado pelo aplicativo. O snapshot espacial representa uma visualização coerente das entidades e dos dados dos componentes delas. Depois que um snapshot é criado, os dados dele precisam permanecer constantes enquanto o snapshot for válido.

O aplicativo pode criar quantos snapshots quiser, mas precisa considerar a memória alocada para cada novo snapshot e precisa destruir os snapshots quando não forem mais necessários.

Criar snapshot de descoberta

A função xrCreateSpatialDiscoverySnapshotAsyncEXT é definida como:

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Descrições dos parâmetros

O aplicativo pode descobrir entidades espaciais criando um snapshot de descoberta com xrCreateSpatialDiscoverySnapshotAsyncEXT .

Essa função inicia uma operação assíncrona e cria um XrFutureEXT correspondente, que pode ser usado com xrPollFutureEXT e funções relacionadas. O valor de retorno dessa função indica apenas se os parâmetros eram aceitáveis para programar a operação assíncrona. A função de conclusão correspondente é xrCreateSpatialDiscoverySnapshotCompleteEXT , que pode ser usada quando um futuro dessa função está no estado READY, com saídas preenchidas por essa função na estrutura de conclusão XrCreateSpatialDiscoverySnapshotCompletionEXT .

O aplicativo pode enviar várias solicitações de criação de snapshot de descoberta sem precisar esperar que a anterior seja concluída. O ambiente de execução pode processar e concluir a criação do snapshot em qualquer ordem. O ambiente de execução pode atrasar a conclusão da criação do snapshot de descoberta para limitar o aplicativo se precisar reduzir o uso de recursos do sistema devido a políticas de energia, térmicas ou outras do dispositivo.

O aplicativo pode usar XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes para filtrar a lista de entidades e os componentes com dados que o ambiente de execução precisa incluir no snapshot. Se o aplicativo fornecer uma lista válida de tipos de componentes espaciais em XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , o ambiente de execução precisará incluir apenas entidades espaciais no snapshot que tenham pelo menos um dos componentes fornecidos em XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Além disso, o ambiente de execução precisa incluir apenas dados para os componentes no snapshot.

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT se algum dos XrSpatialComponentTypeEXT em XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes não estiver ativado para os recursos espaciais transmitidos para XrSpatialContextCreateInfoEXT :: capabilityConfigs ao criar spatialContext .

Se o aplicativo não fornecer uma lista de tipos de componentes espaciais em XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , o ambiente de execução precisará incluir todas as entidades espaciais no snapshot que tenham o conjunto de componentes enumerados em XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents para os recursos configurados para spatialContext . O ambiente de execução precisa incluir os dados de todos os componentes ativados dos recursos configurados para spatialContext .

Se XrEventDataReferenceSpaceChangePending for colocado na fila antes da conclusão de future e XrEventDataReferenceSpaceChangePending :: poseValid for falso, o ambiente de execução poderá criar um XrSpatialSnapshotEXT que não tenha entidades ou definir o XrSpatialEntityTrackingStateEXT das entidades que não são mais localizáveis em XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace em XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time como XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT ou XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . O ambiente de execução não pode definir XrCreateSpatialContextCompletionEXT :: futureResult como um código de erro devido a XrEventDataReferenceSpaceChangePending .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrSpatialDiscoverySnapshotCreateInfoEXT é definida como:

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • componentTypeCount é um uint32_t que descreve a contagem de elementos na matriz componentTypes.
  • componentTypes é uma matriz de XrSpatialComponentTypeEXT .

A estrutura XrSpatialDiscoverySnapshotCreateInfoEXT descreve as informações para criar um identificador XrSpatialSnapshotEXT ao descobrir entidades espaciais.

Uso válido (implícito)

A função xrCreateSpatialDiscoverySnapshotCompleteEXT é definida como:

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

Descrições dos parâmetros

xrCreateSpatialDiscoverySnapshotCompleteEXT conclui a operação assíncrona iniciada por xrCreateSpatialDiscoverySnapshotAsyncEXT . O ambiente de execução precisa retornar XR_ERROR_FUTURE_PENDING_EXT se XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future não estiver no estado pronto. O ambiente de execução precisa retornar XR_ERROR_FUTURE_INVALID_EXT se XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future já tiver sido concluído ou cancelado.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrCreateSpatialDiscoverySnapshotCompletionInfoEXT é definida como:

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

Descrições dos membros

Os locais nos vários dados de componentes incluídos no snapshot criado serão representados em baseSpace , localizado em time .

Uso válido (implícito)

A estrutura XrCreateSpatialDiscoverySnapshotCompletionEXT é definida como:

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • futureResult é o XrResult da operação de criação do snapshot de descoberta espacial.
  • snapshot é um XrSpatialSnapshotEXT que pode ser usado para consultar os dados de componentes das entidades espaciais descobertas.

Códigos de retorno futuros

Valores de futureResult:

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Uso válido (implícito)

Evento de recomendação de descoberta

A estrutura XrEventDataSpatialDiscoveryRecommendedEXT é definida como:

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • spatialContext é o XrSpatialContextEXT para o qual a descoberta está sendo recomendada pelo ambiente de execução.

O aplicativo pode recuperar esse evento usando xrPollEvent . O aplicativo pode evitar chamadas excessivas para xrCreateSpatialDiscoverySnapshotAsyncEXT para descobrir entidades espaciais aguardando esse evento. Se o aplicativo criar vários snapshots de descoberta com o mesmo XrSpatialDiscoverySnapshotCreateInfoEXT entre dois eventos XrEventDataSpatialDiscoveryRecommendedEXT, os snapshots resultantes poderão conter as mesmas entidades. Portanto, a criação de snapshots e as consultas de dados seriam desnecessárias.

Aguardar esse evento para criar um novo snapshot de descoberta garante que o aplicativo não sobrecarregue o sistema com solicitações de descoberta para as quais o ambiente de execução pode não retornar novos dados. Isso ajuda a evitar o risco de uso excessivo dos recursos do sistema e de limitação devido às políticas de energia ou térmicas do dispositivo. Isso também ajuda a criar paridade entre os ambientes de execução que estão descobrindo entidades espaciais em tempo real com rastreamento ao vivo e os ambientes de execução que estão fornecendo entidades espaciais de um estado gravado anteriormente (em que o ambiente de execução pode colocar o evento de recomendação de descoberta na fila apenas uma vez para cada XrSpatialContextEXT).

O ambiente de execução não pode colocar esse evento em fila para notificar o aplicativo sobre mudanças ou ajustes feitos nos dados de componentes de entidades espaciais atuais. O aplicativo pode usar xrCreateSpatialUpdateSnapshotEXT para acompanhar as atualizações de dados de componentes das entidades espaciais de interesse.

Um ambiente de execução pode colocar um evento de recomendação de descoberta em fila sem esperar que o aplicativo chame xrCreateSpatialDiscoverySnapshotAsyncEXT primeiro. Por exemplo, um ambiente de execução pode basear a decisão de colocar o evento de recomendação de descoberta em fila na configuração do XrSpatialContextEXT, na própria compreensão do ambiente ao redor do usuário (descoberta de novas entidades ou perda de entidades existentes) ou para sugerir uma cadência de solicitação de descoberta adequada ao aplicativo para não sobrecarregar os recursos do sistema. O ambiente de execução pode optar por nunca colocar esse evento em fila para um XrSpatialContextEXT se nenhuma entidade for encontrada no ambiente do usuário durante o ciclo de vida desse XrSpatialContextEXT .

O ambiente de execução não pode colocar esse evento em fila para um determinado spatialContext até que o aplicativo conclua a criação usando xrCreateSpatialContextCompleteEXT .

Depois que o aplicativo chama xrDestroySpatialContextEXT , o ambiente de execução não pode colocar mais eventos de recomendação de descoberta na fila para esse contexto espacial nem retornar esses eventos para esse contexto de xrPollEvent .

Uso válido (implícito)

Dados do componente de consulta

A função xrQuerySpatialComponentDataEXT é definida como:

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

Descrições dos parâmetros

O aplicativo pode usar xrQuerySpatialComponentDataEXT para consultar os dados de componente das entidades no snapshot anexando uma estrutura de lista a XrSpatialComponentDataQueryResultEXT :: next correspondente a cada XrSpatialComponentTypeEXT em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Se o aplicativo anexar uma estrutura de lista a XrSpatialComponentDataQueryResultEXT :: next que não corresponda a nenhum dos componentes listados em XrSpatialComponentDataQueryConditionEXT :: componentTypes , o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE .

O aplicativo pode anexar as estruturas de lista correspondentes a apenas um subconjunto de componentes listados em XrSpatialComponentDataQueryConditionEXT :: componentTypes . O aplicativo pode omitir as estruturas de lista se quiser saber apenas os IDs e o estado de rastreamento das entidades espaciais que atendem ao queryCondition . O ambiente de execução não pode tratar a ausência de estruturas de lista da cadeia XrSpatialComponentDataQueryResultEXT :: next como uma falha.

Se XrEventDataReferenceSpaceChangePending estiver na fila e XrEventDataReferenceSpaceChangePending :: changeTime tiver decorrido enquanto o aplicativo está consultando dados de componentes de um XrSpatialSnapshotEXT , o aplicativo pode usar os dados do evento para ajustar as poses de acordo.

O ambiente de execução precisa preencher XrSpatialComponentDataQueryResultEXT :: entityIds apenas com entidades que tenham todos os componentes especificados em XrSpatialComponentDataQueryConditionEXT :: componentTypes . Se XrSpatialComponentDataQueryConditionEXT :: componentTypeCount for 0, o ambiente de execução precisa preencher queryResult com todas as entidades (e os estados de rastreamento delas) que estão no snapshot. Se outras condições de consulta forem adicionadas a XrSpatialComponentDataQueryConditionEXT :: next, o ambiente de execução precisará tratá-las como um "AND" com a disponibilidade dos tipos de componente, ou seja, o ambiente de execução precisará preencher XrSpatialComponentDataQueryResultEXT ::entityIds apenas com entidades que atendam a todas as condições fornecidas. O ambiente de execução precisa preencher os dados do componente nas estruturas de lista na mesma ordem que as entidades em XrSpatialComponentDataQueryResultEXT :: entityIds, ou seja, os dados do componente em um determinado índice na matriz de estrutura de lista precisam corresponder à entidade no mesmo índice.

Se o estado de rastreamento de uma entidade não for XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT , o ambiente de execução não pode mudar os dados no índice correspondente a essa entidade na matriz contida nas estruturas de lista anexadas a XrSpatialComponentDataQueryResultEXT .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

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

Por exemplo, o aplicativo cria um XrSpatialSnapshotEXT que contém cinco entidades, em que:

  • As entidades 1 e 2 têm os componentes XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT e XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT.
  • As entidades 3 e 4 têm os componentes XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT e XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
  • A entidade 5 tem os componentes XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT e XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

Sim

Sim

Sim

Sim

Não

Não

Não

Não

Sim

Sim

Pai

Pai

Sim

Sim

Sim

Sim

Não

Não

Não

Não

Não

Não

Mesh3D

Mesh3D

Não

Não

Não

Não

Sim

Sim

Sim

Sim

Sim

Sim

Bounded3D

Bounded3D

Não

Não

Não

Não

Sim

Sim

Sim

Sim

Não

Não O texto não é SVG, não é possível exibir

Figura 20. Exemplo de snapshot

xrQuerySpatialComponentDataEXT no snapshot acima com XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT listado na condição de consulta vai resultar no retorno das entidades #1, #2 e #5 para o aplicativo, e o aplicativo pode anexar uma matriz de XrSpatialBounded2DDataEXT como parte da estrutura XrSpatialComponentBounded2DListEXT à próxima cadeia de XrSpatialComponentDataQueryResultEXT para receber os dados bounded2D.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

Dados para entityId nº 1

Dados para entid...

Dados para entityId #2

Dados para entid...

Dados para entityId #5

Dados para entid...

entityIds

entityIds

próxima

próxima

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

bounds

bounds

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... O texto não é SVG, não é possível exibir

Figura 21. Exemplo de resultado de consulta

xrQuerySpatialComponentDataEXT no snapshot acima com os componentes XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT e XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT listados na condição de consulta vai resultar no retorno das entidades 3 e 4 para o aplicativo, e o aplicativo pode anexar matrizes de XrBoxf e XrSpatialMeshDataEXT como parte das estruturas XrSpatialComponentBounded3DListEXT e XrSpatialComponentMesh3DListEXT, respectivamente, à próxima cadeia de XrSpatialComponentDataQueryResultEXT para receber os dados do componente.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

Dados para entityId #3

Dados para entid...

Dados para entityId nº 4

Dados para entid...

Mesh3D

Mesh3D

Dados para entityId #3

Dados para entid...

Dados para entityId nº 4

Dados para entid...

entityIds

entityIds

próxima

próxima

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

bounds

bounds

próxima

próxima

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

malhas

meshes Text is not SVG - cannot display

Figura 22. Exemplo de resultado de consulta

A estrutura XrSpatialComponentDataQueryConditionEXT é definida como:

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • componentTypeCount é um uint32_t que descreve a contagem de elementos na matriz componentTypes.
  • componentTypes é uma matriz de XrSpatialComponentTypeEXT para receber os dados do snapshot.

Uso válido (implícito)

A estrutura XrSpatialComponentDataQueryResultEXT é definida como:

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • entityIdCapacityInput é a capacidade da matriz entityIds ou 0 para indicar uma solicitação de recuperação da capacidade necessária.
  • entityIdCountOutput é o número de XrSpatialEntityIdEXT em entityIds ou a capacidade necessária caso entityIdCapacityInput seja insuficiente.
  • entityIds é uma matriz de XrSpatialEntityIdEXT . Pode ser NULL se entityIdCapacityInput for 0.
  • entityStateCapacityInput é a capacidade da matriz entityStates ou 0 para indicar uma solicitação de recuperação da capacidade necessária.
  • entityStateCountOutput é o número de XrSpatialEntityTrackingStateEXT em entityStates ou a capacidade necessária caso entityStateCapacityInput seja insuficiente. Ele precisa ser sempre igual a entityIdCountOutput .
  • entityStates é uma matriz de XrSpatialEntityTrackingStateEXT . Pode ser NULL se entityStateCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de entityIds necessário.

Um aplicativo pode usar o entityIds com xrCreateSpatialEntityFromIdEXT para criar identificadores XrSpatialEntityEXT para as entidades que ele quer receber atualizações regulares. O aplicativo pode usar esses identificadores XrSpatialEntityEXT com xrCreateSpatialUpdateSnapshotEXT para criar um snapshot de atualização que tenha os dados mais recentes conhecidos do ambiente de execução dos componentes para as entidades fornecidas.

Uso válido (implícito)

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

O XrSpatialEntityTrackingStateEXT enumera os possíveis estados de rastreamento de entidades espaciais:

Os tipos enumerados têm os seguintes significados:

Descrição do tipo enumerado

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

O ambiente de execução parou de rastrear essa entidade e não vai retomar o rastreamento.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

O ambiente de execução pausou o rastreamento dessa entidade, mas pode retomá-lo no futuro.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

O ambiente de execução está rastreando essa entidade, e os dados do componente dela são válidos.

ACOMPANHAMENTO

PAUSADO

PARADO

Figura 23. XrSpatialEntityTrackingStateEXT

  • O ambiente de execução pode mudar o estado da entidade espacial de XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT para XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT se suspender o rastreamento dessa entidade, mas tiver a possibilidade de retomá-lo no futuro. Alguns exemplos de quando o ambiente de execução pode fazer isso incluem (mas não se limitam a) se o aplicativo perder o foco de entrada, se a entidade espacial fornecida estiver muito longe do usuário para ser rastreada com precisão ou se houver muitas entidades sendo rastreadas e o ambiente de execução quiser reduzir o custo do rastreamento. O XrSpatialEntityTrackingStateEXT ajuda o aplicativo a se isolar das diferentes políticas de rastreamento de cada ambiente de execução.
  • O ambiente de execução pode mudar o estado de uma entidade de XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT para XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT ou XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
  • O ambiente de execução precisa mudar o estado da entidade espacial de XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT ou XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT para XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT se a entidade espacial for perdida e o rastreamento dela nunca for recuperado ou retomado. Um exemplo desse caso seria se o dispositivo perdesse o rastreamento, reiniciasse a sessão de rastreamento, mas não conseguisse se relocalizar no ambiente e, portanto, tratasse as entidades descobertas dessa sessão de rastreamento como novas entidades.
  • Depois que o estado de rastreamento de uma entidade é definido como XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , o ambiente de execução nunca pode mudar para outro estado.
  • Ao consultar os dados do componente de uma entidade espacial usando xrQuerySpatialComponentDataEXT , o ambiente de execução precisa definir dados válidos no conteúdo dos buffers fornecidos pelo aplicativo na próxima cadeia de XrSpatialComponentDataQueryResultEXT se o estado da entidade for XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . Se o estado da entidade for XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT ou XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , o ambiente de execução não pode mudar o conteúdo dos buffers.

Idioma de duas chamadas para dados de componentes

A estrutura XrSpatialBufferEXT é definida como:

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

Descrições dos membros

  • bufferId o XrSpatialBufferIdEXT dos dados do buffer.
  • bufferType é o XrSpatialBufferTypeEXT para indicar o tipo de dados em bufferId . O aplicativo pode usar bufferType para determinar qual função usar para recuperar os dados reais do buffer.

Alguns componentes espaciais têm dados de tamanho variável e, portanto, exigem o uso do idioma de duas chamadas para recuperar os dados. Nesses casos, a estrutura de dados do componente espacial fornece um XrSpatialBufferEXT para cada buffer de tamanho variável necessário nos dados desse componente.

Para o mesmo bufferId , o ambiente de execução precisa fornecer os mesmos dados de uma consulta de dados de componente para outra, mesmo entre um snapshot e outro. Um bufferId diferente entre as chamadas de consulta de dados do componente indica ao aplicativo que os dados desse componente podem ter mudado.

Uso válido (implícito)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT é usado para representar qualquer tipo de dados de tamanho variável para um componente espacial.

O ambiente de execução precisa manter o XrSpatialBufferIdEXT e os dados dele na memória pelo menos durante o ciclo de vida do XrSpatialSnapshotEXT que o contém. O ambiente de execução pode manter o XrSpatialBufferIdEXT e os dados dele na memória por mais tempo do que o ciclo de vida do XrSpatialSnapshotEXT para retornar o mesmo ID como parte dos snapshots criados posteriormente pelo aplicativo. Para o mesmo XrSpatialBufferIdEXT , o ambiente de execução precisa sempre retornar os mesmos dados usando a função xrGetSpatialBuffer* adequada.

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

A enumeração XrSpatialBufferTypeEXT identifica os diferentes tipos de dados do buffer representado XrSpatialBufferIdEXT .

Descrições de enumerantes

A função xrGetSpatialBufferStringEXT é definida como:

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Descrições dos parâmetros

  • snapshot é um identificador para um XrSpatialSnapshotEXT .
  • info contém as informações sobre o buffer a ser consultado.
  • bufferCapacityInput é a capacidade da matriz ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • bufferCountOutput é o número de caracteres ou a capacidade necessária caso bufferCapacityInput seja insuficiente.
  • buffer é uma matriz de char . Pode ser NULL se bufferCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de buffer necessário.

O aplicativo pode receber os dados de um XrSpatialBufferEXT fornecido por um componente, em que XrSpatialBufferEXT :: bufferType é XR_SPATIAL_BUFFER_TYPE_STRING_EXT usando xrGetSpatialBufferStringEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se o XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId não for XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId não pertencer a snapshot .

buffer preenchido pelo ambiente de execução precisa ser uma string UTF-8 terminada em nulo.

Uso válido (implícito)

  • A extensão XR_EXT_spatial_entity precisa ser ativada antes de chamar xrGetSpatialBufferStringEXT.
  • snapshot precisa ser um identificador XrSpatialSnapshotEXT válido
  • info precisa ser um ponteiro para uma estrutura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput precisa ser um ponteiro para um valor uint32_t
  • Se bufferCapacityInput não for 0 , buffer precisa ser um ponteiro para uma matriz de valores de caracteres bufferCapacityInput.

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

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

A função xrGetSpatialBufferUint8EXT é definida como:

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

Descrições dos parâmetros

  • snapshot é um identificador para um XrSpatialSnapshotEXT .
  • info contém as informações sobre o buffer a ser consultado.
  • bufferCapacityInput é a capacidade da matriz ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • bufferCountOutput é o número de elementos na matriz buffer ou a capacidade necessária caso bufferCapacityInput seja insuficiente.
  • buffer é uma matriz de uint8_t . Pode ser NULL se bufferCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de buffer necessário.

O aplicativo pode receber os dados de um XrSpatialBufferEXT fornecido por um componente, em que XrSpatialBufferEXT :: bufferType é XR_SPATIAL_BUFFER_TYPE_UINT8_EXT usando xrGetSpatialBufferUint8EXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se o XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId não for XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId não pertencer a snapshot .

Uso válido (implícito)

  • A extensão XR_EXT_spatial_entity precisa ser ativada antes de chamar xrGetSpatialBufferUint8EXT.
  • snapshot precisa ser um identificador XrSpatialSnapshotEXT válido
  • info precisa ser um ponteiro para uma estrutura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput precisa ser um ponteiro para um valor uint32_t
  • Se bufferCapacityInput não for 0 , buffer precisa ser um ponteiro para uma matriz de valores bufferCapacityInput uint8_t

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

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

A função xrGetSpatialBufferUint16EXT é definida como:

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

Descrições dos parâmetros

  • snapshot é um identificador para um XrSpatialSnapshotEXT .
  • info contém as informações sobre o buffer a ser consultado.
  • bufferCapacityInput é a capacidade da matriz ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • bufferCountOutput é o número de elementos na matriz buffer ou a capacidade necessária caso bufferCapacityInput seja insuficiente.
  • buffer é uma matriz de uint16_t . Pode ser NULL se bufferCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de buffer necessário.

O aplicativo pode receber os dados de um XrSpatialBufferEXT fornecido por um componente, em que XrSpatialBufferEXT :: bufferType é XR_SPATIAL_BUFFER_TYPE_UINT16_EXT usando xrGetSpatialBufferUint16EXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se o XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId não for XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId não pertencer a snapshot .

Uso válido (implícito)

  • A extensão XR_EXT_spatial_entity precisa ser ativada antes de chamar xrGetSpatialBufferUint16EXT.
  • snapshot precisa ser um identificador XrSpatialSnapshotEXT válido
  • info precisa ser um ponteiro para uma estrutura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput precisa ser um ponteiro para um valor uint32_t
  • Se bufferCapacityInput não for 0 , buffer precisa ser um ponteiro para uma matriz de valores bufferCapacityInput uint16_t

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

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

A função xrGetSpatialBufferUint32EXT é definida como:

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

Descrições dos parâmetros

  • snapshot é um identificador para um XrSpatialSnapshotEXT .
  • info contém as informações sobre o buffer a ser consultado.
  • bufferCapacityInput é a capacidade da matriz ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • bufferCountOutput é o número de elementos na matriz buffer ou a capacidade necessária caso bufferCapacityInput seja insuficiente.
  • buffer é uma matriz de uint32_t . Pode ser NULL se bufferCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de buffer necessário.

O aplicativo pode receber os dados de um XrSpatialBufferEXT fornecido por um componente, em que XrSpatialBufferEXT :: bufferType é XR_SPATIAL_BUFFER_TYPE_UINT32_EXT usando xrGetSpatialBufferUint32EXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se o XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId não for XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId não pertencer a snapshot .

Uso válido (implícito)

  • A extensão XR_EXT_spatial_entity precisa ser ativada antes de chamar xrGetSpatialBufferUint32EXT.
  • snapshot precisa ser um identificador XrSpatialSnapshotEXT válido
  • info precisa ser um ponteiro para uma estrutura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput precisa ser um ponteiro para um valor uint32_t
  • Se bufferCapacityInput não for 0 , buffer precisa ser um ponteiro para uma matriz de valores bufferCapacityInput uint32_t

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

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

A função xrGetSpatialBufferFloatEXT é definida como:

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

Descrições dos parâmetros

  • snapshot é um identificador para um XrSpatialSnapshotEXT .
  • info contém as informações sobre o buffer a ser consultado.
  • bufferCapacityInput é a capacidade da matriz ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • bufferCountOutput é o número de elementos na matriz buffer ou a capacidade necessária caso bufferCapacityInput seja insuficiente.
  • buffer é uma matriz de float . Pode ser NULL se bufferCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de buffer necessário.

O aplicativo pode receber os dados de um XrSpatialBufferEXT fornecido por um componente, em que XrSpatialBufferEXT :: bufferType é XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT usando xrGetSpatialBufferFloatEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se o XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId não for XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId não pertencer a snapshot .

Uso válido (implícito)

  • A extensão XR_EXT_spatial_entity precisa ser ativada antes de chamar xrGetSpatialBufferFloatEXT.
  • snapshot precisa ser um identificador XrSpatialSnapshotEXT válido
  • info precisa ser um ponteiro para uma estrutura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput precisa ser um ponteiro para um valor uint32_t
  • Se bufferCapacityInput não for 0 , buffer precisa ser um ponteiro para uma matriz de valores bufferCapacityInput float

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

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

A função xrGetSpatialBufferVector2fEXT é definida como:

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

Descrições dos parâmetros

  • snapshot é um identificador para um XrSpatialSnapshotEXT .
  • info contém as informações sobre o buffer a ser consultado.
  • bufferCapacityInput é a capacidade da matriz ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • bufferCountOutput é o número de elementos na matriz buffer ou a capacidade necessária caso bufferCapacityInput seja insuficiente.
  • buffer é uma matriz de XrVector2f . Pode ser NULL se bufferCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de buffer necessário.

O aplicativo pode receber os dados de um XrSpatialBufferEXT fornecido por um componente, em que XrSpatialBufferEXT :: bufferType é XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT usando xrGetSpatialBufferVector2fEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se o XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId não for XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId não pertencer a snapshot .

Uso válido (implícito)

  • A extensão XR_EXT_spatial_entity precisa ser ativada antes de chamar xrGetSpatialBufferVector2fEXT.
  • snapshot precisa ser um identificador XrSpatialSnapshotEXT válido
  • info precisa ser um ponteiro para uma estrutura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput precisa ser um ponteiro para um valor uint32_t
  • Se bufferCapacityInput não for 0 , buffer precisa ser um ponteiro para uma matriz de estruturas bufferCapacityInput XrVector2f.

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

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

A função xrGetSpatialBufferVector3fEXT é definida como:

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

Descrições dos parâmetros

  • snapshot é um identificador para um XrSpatialSnapshotEXT .
  • info contém as informações sobre o buffer a ser consultado.
  • bufferCapacityInput é a capacidade da matriz ou 0 para indicar uma solicitação para recuperar a capacidade necessária.
  • bufferCountOutput é o número de elementos na matriz buffer ou a capacidade necessária caso bufferCapacityInput seja insuficiente.
  • buffer é uma matriz de XrVector3f . Pode ser NULL se bufferCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de buffer necessário.

O aplicativo pode receber os dados de um XrSpatialBufferEXT fornecido por um componente, em que XrSpatialBufferEXT :: bufferType é XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT usando xrGetSpatialBufferVector3fEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE se o XrSpatialBufferTypeEXT para XrSpatialBufferGetInfoEXT :: bufferId não for XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT se XrSpatialBufferGetInfoEXT :: bufferId não pertencer a snapshot .

Uso válido (implícito)

  • A extensão XR_EXT_spatial_entity precisa ser ativada antes de chamar xrGetSpatialBufferVector3fEXT.
  • snapshot precisa ser um identificador XrSpatialSnapshotEXT válido
  • info precisa ser um ponteiro para uma estrutura XrSpatialBufferGetInfoEXT válida.
  • bufferCountOutput precisa ser um ponteiro para um valor uint32_t
  • Se bufferCapacityInput não for 0 , buffer precisa ser um ponteiro para uma matriz de estruturas bufferCapacityInput XrVector3f.

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

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

A estrutura XrSpatialBufferGetInfoEXT é definida como:

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • bufferId um XrSpatialBufferIdEXT para o buffer que contém os dados a serem recuperados.

Uso válido (implícito)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT é um valor reservado que representa um XrSpatialBufferIdEXT inválido. Ele pode ser transmitido e retornado de funções de API somente quando permitido especificamente.

Criar snapshot de atualização

A função xrCreateSpatialUpdateSnapshotEXT é definida como:

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

Descrições dos parâmetros

O aplicativo pode usar xrCreateSpatialUpdateSnapshotEXT para criar um snapshot e receber os dados de componentes mais recentes para entidades específicas, conforme conhecido pelo ambiente de execução. Os aplicativos podem fornecer os identificadores XrSpatialEntityEXT e os tipos de componente de interesse ao criar o snapshot.

O aplicativo pode usar XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes para filtrar a lista de componentes com dados que precisam ser incluídos no snapshot. Se o aplicativo fornecer uma lista válida de tipos de componentes espaciais em XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , o ambiente de execução precisará incluir apenas entidades espaciais no snapshot que tenham pelo menos um dos componentes fornecidos em XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Além disso, o ambiente de execução precisa incluir apenas dados para esses componentes no snapshot.

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT se algum dos XrSpatialComponentTypeEXT em XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes não estiver ativado para os recursos espaciais transmitidos para XrSpatialContextCreateInfoEXT :: capabilityConfigs ao criar spatialContext .

Se o aplicativo não fornecer uma lista de tipos de componentes espaciais em XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , o ambiente de execução precisa incluir todas as entidades espaciais listadas em XrSpatialUpdateSnapshotCreateInfoEXT :: entities no snapshot e precisa incluir os dados de todos os componentes ativados dos recursos configurados para spatialContext .

O ambiente de execução não pode incluir entidades espaciais que não estejam listadas em XrSpatialUpdateSnapshotCreateInfoEXT :: entities em snapshot .

O aplicativo pode criar quantos snapshots quiser, mas precisa considerar a memória alocada para cada novo snapshot e precisa destruir os snapshots quando não forem mais necessários.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrSpatialUpdateSnapshotCreateInfoEXT é definida como:

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • entityCount é um uint32_t que descreve a contagem de elementos na matriz entities.
  • entities é uma matriz de XrSpatialEntityEXT para que o ambiente de execução precise incluir os dados do componente no snapshot.
  • componentTypeCount é um uint32_t que descreve a contagem de elementos na matriz componentTypes.
  • componentTypes é uma matriz de XrSpatialComponentTypeEXT para que o ambiente de execução precise incluir os dados no snapshot.
  • baseSpace é o XrSpace em relação ao qual todos os locais do XrSpatialSnapshotEXT atualizado serão localizados.
  • time é o XrTime em que todos os locais da atualização XrSpatialSnapshotEXT vão estar.

Uso válido (implícito)

  • A extensão XR_EXT_spatial_entity precisa ser ativada antes de usar XrSpatialUpdateSnapshotCreateInfoEXT.
  • type precisa ser XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
  • next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
  • entities precisa ser um ponteiro para uma matriz de identificadores entityCount válidos de XrSpatialEntityEXT
  • Se componentTypeCount não for 0 , componentTypes precisa ser um ponteiro para uma matriz de valores componentTypeCount válidos de XrSpatialComponentTypeEXT.
  • baseSpace precisa ser um identificador XrSpace válido
  • O parâmetro entityCount precisa ser maior que 0.
  • baseSpace e os elementos de entities precisam ter sido criados, alocados ou recuperados da mesma XrSession.

Destruir snapshot

A função xrDestroySpatialSnapshotEXT é definida como:

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

Descrições dos parâmetros

O aplicativo pode chamar xrDestroySpatialSnapshotEXT para destruir o identificador XrSpatialSnapshotEXT e os recursos associados a ele.

Uso válido (implícito)

Concorrência segura

  • O acesso a snapshot e a qualquer identificador filho precisa ser sincronizado externamente.

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Componentes comuns

2D limitado

Dados do componente

A estrutura XrSpatialBounded2DDataEXT é definida como:

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

Descrições dos membros

  • center é um XrPosef que define o centro geométrico do componente 2D limitado.
  • extents são as extensões do componente 2D limitado ao longo do eixo x (extents.width) e do eixo y (extents.height), centralizado em center .

O extents do XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT se refere ao tamanho da entidade no plano x-y do sistema de coordenadas do plano. Um plano com uma posição de {0, 0, 0}, rotação de {0, 0, 0, 1} (sem rotação) e uma extensão de {1, 1} se refere a um plano de 1 metro x 1 metro centralizado em {0, 0, 0} com o vetor normal da face frontal apontando para a direção +Z no espaço do componente.

X X Y Y Z Z Altura Altura Y Y Z Z X X Plano vertical Plano vertical Plano horizontal Plano horizontal Largura Largura Largura Largura Altura Altura

Figura 24. Sistema de coordenadas de componentes Bounded2D

Observação

O OpenXR usa um plano X-Y com +Z como normal do plano, mas outras APIs podem usar um plano X-Z com +Y como normal do plano. O plano X-Y pode ser convertido em um plano X-Z girando -π/2 radianos em torno do eixo +X.

Uso válido (implícito)

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentBounded2DListEXT é definida como:

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • boundCount é um uint32_t que descreve a contagem de elementos na matriz bounds.
  • bounds é uma matriz de XrSpatialBounded2DDataEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentBounded2DListEXT estiver na próxima cadeia de XrSpatialComponentDataQueryResultEXT :: next, mas XrSpatialComponentDataQueryConditionEXT ::componentTypeCount não for zero e XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se boundCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Se xrQuerySpatialComponentDataEXT :: snapshot foi criado com base em xrCreateSpatialDiscoverySnapshotCompleteEXT , o ambiente de execução precisa fornecer XrSpatialBounded2DDataEXT :: center em XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace e XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Se xrQuerySpatialComponentDataEXT :: snapshot tiver sido criado de xrCreateSpatialUpdateSnapshotEXT , o ambiente de execução precisará fornecer XrSpatialBounded2DDataEXT :: center em XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace e XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Uso válido (implícito)

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, o aplicativo poderá ativá-lo incluindo o valor do tipo enumerado na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Esse componente não requer nenhuma configuração especial para ser incluído na próxima cadeia de XrSpatialCapabilityConfigurationBaseHeaderEXT .

3D limitado

Dados do componente

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT usa XrBoxf para os dados.

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentBounded3DListEXT é definida como:

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • boundCount é um uint32_t que descreve a contagem de elementos na matriz bounds.
  • bounds é uma matriz de XrBoxf .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentBounded3DListEXT estiver na próxima cadeia de XrSpatialComponentDataQueryResultEXT :: next, mas XrSpatialComponentDataQueryConditionEXT ::componentTypeCount não for zero e XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se boundCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Se xrQuerySpatialComponentDataEXT :: snapshot tiver sido criado de xrCreateSpatialDiscoverySnapshotCompleteEXT , o ambiente de execução precisará fornecer XrBoxf :: center em XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace em XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Se xrQuerySpatialComponentDataEXT :: snapshot foi criado de xrCreateSpatialUpdateSnapshotEXT , o ambiente de execução precisa fornecer XrBoxf :: center em XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace em XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Uso válido (implícito)

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, o aplicativo poderá ativá-lo incluindo o tipo enumerado na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Esse componente não requer nenhuma configuração especial para ser incluído na próxima cadeia de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Pai

Dados do componente

O XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT usa o XrSpatialEntityIdEXT para os dados.

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentParentListEXT é definida como:

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • parentCount é um uint32_t que descreve a contagem de elementos na matriz parents.
  • parents é uma matriz de XrSpatialEntityIdEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentParentListEXT estiver na próxima cadeia de XrSpatialComponentDataQueryResultEXT :: next, mas XrSpatialComponentDataQueryConditionEXT ::componentTypeCount não for zero e XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se parentCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

  • A extensão XR_EXT_spatial_entity precisa ser ativada antes de usar XrSpatialComponentParentListEXT.
  • type precisa ser XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
  • next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
  • parents precisa ser um ponteiro para uma matriz de valores parentCount XrSpatialEntityIdEXT
  • O parâmetro parentCount precisa ser maior que 0.
Configuração

Se XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, o aplicativo poderá ativá-lo incluindo o tipo enumerado na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Esse componente não requer nenhuma configuração especial para ser incluído na próxima cadeia de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Malha 3D

Dados do componente

A estrutura XrSpatialMeshDataEXT é definida como:

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

Descrições dos membros

  • origin é um XrPosef que define a origem da malha. Todos os vértices da malha precisam ser relativos a essa origem.
  • vertexBuffer é um XrSpatialBufferEXT que fornece o ID de um buffer que representa o buffer de vértice da entidade em que esse componente está. A posição dos vértices precisa ser relativa a origin .
  • indexBuffer é um XrSpatialBufferEXT que fornece o ID de um buffer que representa uma matriz de índices de triângulo, especificando os índices dos vértices da malha no vertexBuffer . Os índices de triângulo precisam ser retornados em sentido anti-horário, e três índices indicam um triângulo.

O tipo de componente que usa XrSpatialMeshDataEXT precisa especificar o XrSpatialBufferTypeEXT de vertexBuffer e indexBuffer .

Uso válido (implícito)

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentMesh3DListEXT é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • meshCount é um uint32_t que descreve a contagem de elementos na matriz meshes.
  • meshes é uma matriz de XrSpatialMeshDataEXT .

O aplicativo pode consultar o componente de malha 3D das entidades espaciais em um XrSpatialSnapshotEXT adicionando XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT em XrSpatialComponentDataQueryConditionEXT :: componentTypes e adicionando XrSpatialComponentMesh3DListEXT à próxima cadeia de ponteiros de XrSpatialComponentDataQueryResultEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentMesh3DListEXT estiver na próxima cadeia de XrSpatialComponentDataQueryResultEXT :: next, mas XrSpatialComponentDataQueryConditionEXT ::componentTypeCount não for zero e XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se meshCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Para o XrSpatialMeshDataEXT preenchido pelo ambiente de execução na matriz meshes, o XrSpatialBufferEXT :: bufferType para XrSpatialMeshDataEXT :: vertexBuffer precisa ser XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT e XrSpatialBufferEXT :: bufferType para XrSpatialMeshDataEXT :: indexBuffer precisa ser XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Uso válido (implícito)

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, o aplicativo poderá ativá-lo incluindo o tipo enumerado na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura derivada XrSpatialCapabilityConfigurationBaseHeaderEXT do recurso que oferece suporte a esse componente.

Esse componente não requer nenhuma configuração especial para ser incluído na próxima cadeia de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Filtros de estado de rastreamento

A estrutura XrSpatialFilterTrackingStateEXT é definida como:

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

Descrições dos membros

O aplicativo pode usar XrSpatialFilterTrackingStateEXT na próxima cadeia de XrSpatialDiscoverySnapshotCreateInfoEXT para limitar a descoberta apenas às entidades com o estado de rastreamento trackingState .

O aplicativo pode usar XrSpatialFilterTrackingStateEXT na próxima cadeia de XrSpatialComponentDataQueryConditionEXT para definir o escopo da consulta de dados do componente de um snapshot apenas para entidades com o estado de rastreamento trackingState .

Uso válido (implícito)

Exemplo de código

Uso do aplicativo

Os aplicativos normalmente usam a extensão de entidade espacial no seguinte padrão:

Descobrir entidades espaciais e consultar dados de componentes

O exemplo de código a seguir demonstra como descobrir entidades espaciais para a capacidade "Foo" e consultar os dados do componente.

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

auto waitUntilReady = [](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

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

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

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components.
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT future = XR_NULL_FUTURE_EXT;
  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 bounded2d component data
    XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT;
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = &componentToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

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

    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) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

    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
  // ...
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Consultar dados do buffer

O exemplo de código a seguir demonstra como receber os dados de um componente que fornece um XrSpatialBufferEXT .

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

Diretrizes para extensões

  • Se uma extensão estiver definindo um novo XrSpatialComponentTypeEXT que fornece dados adicionais sobre uma entidade espacial,

  • As extensões podem definir estruturas que estendem XrSpatialDiscoverySnapshotCreateInfoEXT para fornecer mais filtros para descoberta. Os filtros para criar o snapshot não podem afetar a configuração do contexto espacial. Em vez disso, eles devem ser usados para fornecer dicas ao ambiente de execução sobre quais entidades e dados devem ser incluídos no snapshot, conforme rastreado pela configuração atual do contexto espacial (e, portanto, pela configuração atual dos serviços subjacentes).

  • Se uma extensão definir um novo XrSpatialCapabilityEXT ,

  • Se uma extensão definir um novo XrSpatialCapabilityFeatureEXT , ela precisará definir também uma estrutura de configuração correspondente que possa ser encadeada ao próximo ponteiro de XrSpatialCapabilityConfigurationBaseHeaderEXT , que o aplicativo pode usar para ativar o recurso ao criar um XrSpatialContextEXT .

  • Uma extensão que define um novo XrSpatialCapabilityEXT precisa seguir este modelo para a especificação:

    • Visão geral
    • Suporte ao ambiente de execução
    • Configuração
    • Componentes garantidos
    • Código de exemplo

  • Uma extensão que define um novo XrSpatialComponentTypeEXT precisa seguir este modelo para a especificação:

    • Dados do componente
    • Estrutura de lista de componentes para consultar dados
    • Configuração

  • Ao escrever uma API que fornece um XrSpatialBufferIdEXT ao aplicativo, ela precisa ser acompanhada por um XrSpatialBufferTypeEXT para informar ao aplicativo qual é o tipo de dados do buffer. O aplicativo pode usar uma função xrGetSpatialBuffer* adequada para recuperar o conteúdo real do buffer.

Diretrizes de design e extensão de rótulos semânticos

Embora essa extensão não defina nenhum componente para transmitir as informações de rótulo semântico de uma entidade, ela estabelece as regras e diretrizes de design para todas as extensões que definem esse componente. No texto a seguir, "deve " e "precisa " restringem os autores dessa funcionalidade, em vez de restringir uma implementação de ambiente de execução ou um aplicativo que usa a API.

  • Se uma extensão estiver definindo rótulos semânticos para qualquer XrSpatialCapabilityEXT, ela precisa fazer isso definindo um novo XrSpatialComponentTypeEXT, bem como uma nova enumeração com um conjunto de rótulos (um "conjunto de rótulos semânticos") para ser os dados desse componente.
  • Uma enumeração que representa um conjunto de rótulos semânticos precisa ter um valor para indicar que a entidade não está categorizada em nenhum dos rótulos desse conjunto. O nome desse enumerador precisa incluir "UNCATEGORIZED", por exemplo, XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT. Esse valor indica aos aplicativos que o ambiente de execução reconhece essa entidade, mas que há outros conjuntos de rótulos semânticos em que ela é categorizada.
  • A enumeração desse XrSpatialComponentTypeEXT recém-definido em xrEnumerateSpatialCapabilityComponentTypesEXT implica que o ambiente de execução oferece suporte ao conjunto de rótulos semânticos (e, portanto, aos rótulos definidos no conjunto) correspondente a esse tipo de componente.
  • Os aplicativos expressam o desejo de descobrir entidades que têm rótulos pertencentes a esse conjunto de rótulos semânticos incluindo o XrSpatialComponentTypeEXT correspondente na matriz XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura de configuração para o recurso em que o tipo de componente é enumerado.
  • É possível que uma única entidade espacial tenha vários componentes, cada um com um rótulo do próprio conjunto de rótulos semânticos. Considere o exemplo a seguir com alguns conjuntos de rótulos semânticos hipotéticos: XrSpatialObjectSemanticLabel, que podem ter valores como cadeira, sofá, mesa etc. XrSpatialSofaBrand, que pode ter valores como IKEA, Wayfair etc., e XrSpatialIkeaSofa, que pode ter nomes de modelos de sofás específicos da IKEA. Nesse cenário, a mesma entidade de sofá tem os três componentes (rótulos dos três conjuntos de rótulos semânticos), cada um fornecendo uma granularidade diferente de informações sobre a entidade.
  • Se uma extensão estiver definindo um novo XrSpatialComponentTypeEXT que forneça um novo conjunto de rótulos semânticos contendo vários rótulos além do rótulo UNCATEGORIZED, a extensão precisa considerar a definição de um XrSpatialCapabilityFeatureEXT que permita que os aplicativos ativem apenas um subconjunto dos rótulos definidos no conjunto de rótulos semânticos correspondente a esse tipo de componente. Esse subconjunto, fornecido na próxima cadeia da configuração de recursos, atua como uma dica para que os ambientes de execução otimizem os pipelines de rastreamento e rastreiem apenas o subconjunto fornecido. Confira um exemplo de struct de atributo abaixo .
  • As extensões não podem adicionar rótulos à enumeração de conjuntos de rótulos semânticos. Em vez disso, eles precisam definir uma nova enumeração que contenha enumeradores equivalentes com semântica idêntica e valores iguais aos do outro conjunto, além dos enumeradores recém-adicionados. A especificação do grupo de rótulos semânticos recém-definido precisa estabelecer o mapeamento entre o grupo de rótulos antigo e o novo. Veja o exemplo abaixo .
Exemplo de definição de atributo espacial para subconjunto de rótulos semânticos
// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;
Exemplo de extensão de rótulo semântico espacial
typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

Considere o exemplo acima, em que uma extensão define uma enumeração XrSpatialExamplePlaneSemanticLabelExtensionEXT para estender o XrSpatialPlaneSemanticLabelEXT atual com valores para representar portas e janelas. A especificação da nova enumeração precisa incluir texto para o seguinte formulário:

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====

Novas macros

Novos tipos de base

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

Novos tipos de objeto

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de tipo enumerado

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • Estendendo XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • Estendendo XrResult :

    • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
    • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

  • Estendendo XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
    • XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
    • XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT

Problemas

  • Uma única entidade sempre deriva de uma única capacidade?

    • Resolvido
    • Resposta: não. Isso depende inteiramente do ambiente de execução, com base nos próprios recursos de rastreamento e em como ele quer representar uma entidade detectada. A especificação não prescreve nenhuma representação específica de entidade espacial, exceto pelos componentes garantidos de uma determinada capacidade para definir uma expectativa mínima. Um ambiente de execução pode mesclar entidades detectadas por recursos separados e representá-las como uma única entidade com os componentes garantidos de todos os recursos que ajudaram a identificá-la. Por exemplo, as mesas podem ser detectadas por um recurso de rastreamento de plano e um de rastreamento de objeto, em que o rastreamento de plano fornece o componente XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT na entidade e o rastreamento de objeto fornece XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT . Um determinado ambiente de execução pode fornecer a tabela como duas entidades separadas, cada uma com o próprio conjunto de componentes garantidos, enquanto outros ambientes de execução podem fornecer apenas uma entidade para representar a tabela e ter XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT e XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT na mesma entidade. É importante observar que uma determinada entidade espacial pode ter no máximo um único componente de qualquer tipo de componente . Portanto, se os dados de componentes produzidos pelos diferentes recursos entrarem em conflito para uma determinada entidade, o ambiente de execução precisa representá-los como duas entidades separadas.

Histórico de versões

  • Revisão 1, 12/04/2024 (Nihav Jain, Google)

    • Descrição inicial da extensão