XR_ANDROID_scene_meshing

String de nome

XR_ANDROID_scene_meshing

Tipo de extensão

Extensão de instância

Número de ramal registrado

719

Revisão

3

Status da ratificação

Não ratificado

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

2025-05-15

Status do IP

Não há reivindicações de IP conhecidas.

Colaboradores

Spencer Quin, Google
Jared Finder, Google
Antonio Fontan, Google
Cairn Overturf, Google
Nihav Jain, Google
Salar Khan, Google
Sebastian Klose, Google
Jürgen Sturm, Google
Vinny DaSilva, Google
Ricardo Campbell, Google

Visão geral

Essa extensão foi criada para fornecer malhas que representam aproximadamente os objetos físicos no ambiente do usuário.

Os aplicativos podem usar essa extensão para visualizar a cena e permitir que objetos virtuais interajam com objetos físicos, como colisões.

Os dados da malha de cena são gerados pelo tempo de execução e compartilhados com o aplicativo usando XrSceneMeshingTrackerANDROID e XrSceneMeshSnapshotANDROID . Os aplicativos podem acessar os valores nas informações de submalha da cena usando XrSceneSubmeshStateANDROID retornado de xrGetAllSubmeshStatesANDROID . Os aplicativos podem acessar os valores nos dados de submalha da cena usando XrSceneSubmeshDataANDROID retornado de xrGetSubmeshDataANDROID .

Os dados de fusão de cenas são informações pessoais sensíveis e estão intimamente ligados à privacidade e integridade pessoal. É altamente recomendável que os aplicativos que armazenam ou transferem dados de fusão de cenas sempre peçam ao usuário uma aceitação ativa e específica para fazer isso.

Permissões

Os aplicativos Android precisam ter a permissão android.permission.SCENE_UNDERSTANDING_FINE listada no manifesto. A permissão android.permission.SCENE_UNDERSTANDING_FINE é considerada uma permissão sensível porque permite que o ambiente de execução estude o ambiente do usuário.

O aplicativo precisa solicitar a permissão no momento da execução para usar estas funções:

(nível de proteção: perigoso)

Inspecionar a capacidade do sistema

A estrutura XrSystemSceneMeshingPropertiesANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.
  • supportsSceneMeshing é um XrBool32 que indica se o sistema é compatível com a fusão de cenas.

Um aplicativo pode inspecionar se o sistema é capaz de fazer a fusão de cenas encadeando uma estrutura XrSystemSceneMeshingPropertiesANDROID à XrSystemProperties ao chamar xrGetSystemProperties .

Se um tempo de execução retornar XR_FALSE para supportsSceneMeshing , o sistema não vai oferecer suporte à fusão de cenas. Portanto, deve retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateSceneMeshingTrackerANDROID. O aplicativo deve evitar usar a funcionalidade de malha de cena quando supportsSceneMeshing for XR_FALSE .

Se um ambiente de execução retornar XR_TRUE para supportsSceneMeshing , o sistema vai oferecer suporte à fusão de cenas.

Uso válido (implícito)

A enumeração XrSceneMeshSemanticLabelSetANDROID descreve os conjuntos de rótulos semânticos para malha de cena. Cada valor nesse tipo enumerado representa outro tipo enumerado que contém os rótulos semânticos. Por exemplo, o valor XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID representa o conjunto XrSceneMeshSemanticLabelANDROID .

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

Os valores de enumeração têm os seguintes significados:

Descrição da enumeração

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Esse conjunto representa a ausência de rótulos semânticos.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

Esse conjunto de rótulos semânticos representa XrSceneMeshSemanticLabelANDROID.

A função xrEnumerateSupportedSemanticLabelSetsANDROID é definida como:

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

Descrições dos parâmetros

  • instance é um XrInstance criado pelo aplicativo.
  • systemId é um XrSystemId que foi repetido de xrGetSystem .
  • supportedSemanticLabelSetsInputCapacity é a capacidade de supportedSemanticLabelSets ou 0 para recuperar a capacidade necessária.
  • supportedSemanticLabelSetsOutputCount é um ponteiro para a contagem de supportedSemanticLabelSets gravados ou para a capacidade necessária caso supportedSemanticLabelSetsInputCapacity seja insuficiente.
  • supportedSemanticLabelSets é um ponteiro para uma matriz de XrSceneMeshSemanticLabelSetANDROID . Ele pode ser NULL se supportedSemanticLabelSetsInputCapacity for 0.
  • Consulte o capítulo Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho supportedSemanticLabelSets necessário.

O aplicativo pode enumerar conjuntos de rótulos semânticos compatíveis com o sistema usando a função xrEnumerateSupportedSemanticLabelSetsANDROID.

Todo sistema precisa oferecer suporte a XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID, porque esse valor de enumeração representa nenhum conjunto de rótulos semânticos e pode ser usado caso o aplicativo não precise de semântica de vértice.

Uso válido (implícito)

  • A extensão XR_ANDROID_scene_meshing precisa ser ativada antes de chamar xrEnumerateSupportedSemanticLabelSetsANDROID
  • instance precisa ser um identificador XrInstance válido
  • supportedSemanticLabelSetsOutputCount precisa ser um ponteiro para um valor uint32_t.
  • Se supportedSemanticLabelSetsInputCapacity não for 0 , supportedSemanticLabelSets precisa ser um ponteiro para uma matriz de valores supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID.

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

Criar um handle para o rastreador da malha do ambiente

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

O handle XrSceneMeshingTrackerANDROID representa um rastreador de malha de ambiente para malha de ambiente e gerenciamento dos recursos relacionados.

Esse identificador pode ser usado para criar um snapshot de malha de cena usando xrCreateSceneMeshSnapshotANDROID nesta extensão.

A função xrCreateSceneMeshingTrackerANDROID é definida como:

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

Descrições dos parâmetros

Um aplicativo pode criar um identificador XrSceneMeshingTrackerANDROID usando a função xrCreateSceneMeshingTrackerANDROID.

Se o sistema não for compatível com a malha de cena, o tempo de execução deverá retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateSceneMeshingTrackerANDROID . Nesse caso, o tempo de execução precisa retornar XR_FALSE para XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing quando a função xrGetSystemProperties é chamada. Assim, o aplicativo pode evitar a criação de um rastreador de malha de cena.

O aplicativo precisa usar apenas os conjuntos de rótulos semânticos compatíveis com o sistema em XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet ao criar um rastreador de malha de cena. Se o aplicativo usar um conjunto de rótulos semânticos de vértices de malha de cena não compatível, o tempo de execução deverá retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateSceneMeshingTrackerANDROID .

O aplicativo pode enumerar a lista de conjuntos de rótulos semânticos compatíveis com a função xrEnumerateSupportedSemanticLabelSetsANDROID.

O identificador xrCreateSceneMeshingTrackerANDROID é proprietário de todos os recursos para a malha de cena. Quando terminar de usar a experiência de malha de cena, o aplicativo precisa destruir o identificador usando a função xrDestroySceneMeshingTrackerANDROID.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

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

A estrutura XrSceneMeshingTrackerCreateInfoANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.
  • semanticLabelSet é um XrSceneMeshSemanticLabelSetANDROID usado para especificar o conjunto de rótulos semânticos a ser usado para a malha de cena. Se definido como XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , o tempo de execução vai ignorar o campo de buffer vertexSemantics de XrSceneSubmeshDataANDROID.
  • enableNormals é um XrBool32 usado para especificar se as normais de vértice dos vértices da malha devem ser incluídas no buffer de malha da cena ao receber os dados da malha da cena.

A estrutura XrSceneMeshingTrackerCreateInfoANDROID descreve as informações para criar um identificador XrSceneMeshingTrackerANDROID.

Uso válido (implícito)

A função xrDestroySceneMeshingTrackerANDROID é definida como:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Descrições dos parâmetros

A função xrDestroySceneMeshingTrackerANDROID libera o tracker e os recursos subjacentes quando as experiências de malha de cena são concluídas.

Uso válido (implícito)

Concorrência segura

  • O acesso a tracker 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

Criar um handle para snapshot da malha do ambiente

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

O handle XrSceneMeshSnapshotANDROID representa um snapshot da malha do ambiente. Esse snapshot é criado usando xrCreateSceneMeshSnapshotANDROID, que faz um snapshot dos dados da malha da cena no momento da chamada da função.

Esse identificador pode ser usado para recuperar informações e dados de submalhas usando xrGetAllSubmeshStatesANDROID e xrGetSubmeshDataANDROID .

A função xrCreateSceneMeshSnapshotANDROID é definida como:

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

Descrições dos parâmetros

O aplicativo pode usar a função xrCreateSceneMeshSnapshotANDROID para criar um snapshot de malha de cena do rastreador de malha de cena. Essa função retorna um handle XrSceneMeshSnapshotANDROID junto com XrSceneMeshTrackingStateANDROID encapsulado em uma estrutura XrSceneMeshSnapshotCreationResultANDROID. Tecnicamente, o handle é um snapshot dos dados da malha do ambiente no momento da criação. Esse identificador pode ser usado para consultar as informações e os dados da malha de cena usando xrGetAllSubmeshStatesANDROID e xrGetSubmeshDataANDROID, respectivamente.

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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID

A estrutura XrSceneMeshSnapshotCreateInfoANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.
  • baseSpace é um XrSpace em que as informações de postura da submalha da cena são representadas.
  • time é o XrTime que descreve o momento em que a malha de cena será processada ou exibida, geralmente XrFrameState :: predictedDisplayTime .
  • boundingBox é um XrBoxf que descreve a caixa delimitadora em que a malha da cena será adquirida.

A estrutura XrSceneMeshSnapshotCreateInfoANDROID descreve as informações para criar um identificador XrSceneMeshSnapshotANDROID.

Uso válido (implícito)

A estrutura XrSceneMeshSnapshotCreationResultANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.
  • snapshot é um handle XrSceneMeshSnapshotANDROID criado pelo ambiente de execução.
  • trackingState é um XrSceneMeshTrackingStateANDROID que descreve o estado do rastreador de malha de cena no momento da criação do snapshot.

A estrutura XrSceneMeshSnapshotCreationResultANDROID armazena o resultado de uma criação de snapshot de malha de cena retornada de xrCreateSceneMeshSnapshotANDROID .

Uso válido (implícito)

A enumeração XrSceneMeshTrackingStateANDROID descreve o estado de rastreamento de um rastreador de malha de cena. Cada valor nesse enum representa um estado do rastreador de malha da cena.

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

Os valores de enumeração têm os seguintes significados:

Descrição da enumeração

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

A planilha de controle ainda não está pronta para fornecer dados de malha.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

O rastreador está monitorando ativamente.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

O tracker está aguardando medições válidas para integrar desde a última atualização da malha.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

O rastreador não recebeu medições válidas em vários ciclos e está em estado de erro.

Esse estado serve apenas como informação adicional para o aplicativo. Na ausência de outras fontes de erros, o ambiente de execução precisa continuar permitindo que o aplicativo crie snapshots e recupere dados deles, independente do XrSceneMeshTrackingStateANDROID atual do rastreador. Se o estado não for XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID , os snapshots poderão não estar atualizados ou estar vazios.

Adquirir dados da malha do ambiente a partir do snapshot da malha do ambiente

A função xrGetAllSubmeshStatesANDROID é definida como:

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

Descrições dos parâmetros

  • snapshot é um identificador XrSceneMeshSnapshotANDROID criado anteriormente com xrCreateSceneMeshSnapshotANDROID .
  • submeshStateCapacityInput é a capacidade de submeshStates ou 0 para recuperar a capacidade necessária.
  • submeshStateCountOutput é um ponteiro para a contagem de submeshStates gravados ou para a capacidade necessária caso submeshStateCapacityInput seja insuficiente.
  • submeshStates é um ponteiro para uma matriz de estruturas XrSceneSubmeshStateANDROID em que o tempo de execução vai gerar o estado de todas as submalhas na malha da cena. Ele pode ser NULL se submeshStateCapacityInput for 0.
  • Consulte o capítulo Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho submeshStates necessário.

O aplicativo pode usar a função xrGetAllSubmeshStatesANDROID para receber o estado de todas as submalhas na malha da cena. Contém informações básicas para permitir que o aplicativo selecione submalhas para as quais ele quer dados.

Uso válido (implícito)

  • A extensão XR_ANDROID_scene_meshing precisa ser ativada antes de chamar xrGetAllSubmeshStatesANDROID.
  • snapshot precisa ser um identificador XrSceneMeshSnapshotANDROID válido
  • submeshStateCountOutput precisa ser um ponteiro para um valor uint32_t.
  • Se submeshStateCapacityInput não for 0 , submeshStates precisa ser um ponteiro para uma matriz de estruturas submeshStateCapacityInput XrSceneSubmeshStateANDROID.

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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrSceneSubmeshStateANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.
  • submeshId é um XrUuid que identifica a submalha.
  • lastUpdatedTime é um XrTime que representa o horário em que a submalha foi atualizada pela última vez.
  • submeshPoseInBaseSpace é um XrPosef que representa a postura da submalha no espaço de base usado para criar o snapshot da malha da cena. A postura também é o centro da caixa delimitadora da submalha.
  • bounds é um XrExtent3Df que descreve as dimensões da caixa delimitadora que envolve a submalha. Esses limites são definidos no espaço base usado para criar o identificador de malha da cena.

O tempo de execução faz o possível para mapear submeshId com a região do espaço físico ocupado pela submalha. Os tempos de execução podem perder esse mapeamento a qualquer momento e atribuir um novo UUID a qualquer subconjunto das submalhas detectadas. Em particular, os runtimes não precisam reutilizar os mesmos UUIDs para as mesmas malhas em instâncias de aplicativos subsequentes.

Uso válido (implícito)

A função xrGetSubmeshDataANDROID é definida como:

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

Descrições dos parâmetros

O aplicativo pode usar a função xrGetSubmeshDataANDROID para receber lotes de submalhas ou todas as submalhas de uma só vez. Para isso, transmita uma lista de XrSceneSubmeshDataANDROID com cada XrSceneSubmeshDataANDROID :: submeshId definido como o ID respectivo da submalha a ser recuperada.

O XrSceneSubmeshDataANDROID :: submeshId precisa ser exclusivo para cada elemento em inoutSubmeshData e recuperável por xrGetAllSubmeshStatesANDROID para o mesmo snapshot . Se o ID da submalha for inválido ou mais de um elemento em inoutSubmeshData tiver o mesmo ID de submalha, o ambiente de execução deverá retornar XR_ERROR_VALIDATION_FAILURE .

submeshDataCount precisa ser igual ou menor que o valor retornado por xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput. Caso contrário , o tempo de execução precisa retornar XR_ERROR_VALIDATION_FAILURE.

Isso pode ser usado em uma expressão de duas chamadas para consultar a contagem de vértices e índices de todas as submalhas selecionadas.

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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrSceneSubmeshDataANDROID é definida como:

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

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.
  • submeshId é um XrUuid que identifica a submalha.
  • vertexCapacityInput é a capacidade de vertexPositions, vertexNormals e vertexSemantics ou 0 para recuperar a capacidade necessária.
  • vertexCountOutput é um ponteiro para a contagem de vertexPositions, vertexNormals e vertexSemantics gravados ou para a capacidade necessária caso vertexCapacityInput seja insuficiente.
  • vertexPositions é uma matriz de XrVector3f em que o tempo de execução vai gerar as posições dos vértices da submalha.
  • vertexNormals é uma matriz de XrVector3f em que o tempo de execução vai gerar as normais de vértice da submalha. Esse campo pode ser deixado NULL se o aplicativo tiver criado um rastreador com normais desativados.
  • vertexSemantics é uma matriz de uint8_t em que o ambiente de execução vai gerar a semântica de vértice da submalha. Este campo pode ser deixado NULL se o aplicativo tiver criado um rastreador com o conjunto de rótulos semânticos XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID.
  • indexCapacityInput é a capacidade de indices ou 0 para recuperar a capacidade necessária.
  • indexCountOutput é um ponteiro para a contagem de indices gravados ou para a capacidade necessária caso vertexCapacityInput seja insuficiente.
  • indices é uma matriz de uint32_t em que o ambiente de execução vai gerar os índices da submalha.
  • Consulte o capítulo Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho necessário de vertexPositions, vertexNormals, vertexSemantics e indices.

Uso válido (implícito)

  • A extensão XR_ANDROID_scene_meshing precisa ser ativada antes de usar XrSceneSubmeshDataANDROID.
  • type precisa ser XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
  • Se vertexCapacityInput não for 0 , vertexPositions precisa ser um ponteiro para uma matriz de estruturas XrVector3f de vertexCapacityInput.
  • Se vertexCapacityInput não for 0 , vertexNormals precisa ser um ponteiro para uma matriz de estruturas XrVector3f de vertexCapacityInput.
  • Se vertexCapacityInput não for 0 , vertexSemantics precisa ser um ponteiro para uma matriz de valores vertexCapacityInput uint8_t.
  • Se indexCapacityInput não for 0 , indices precisa ser um ponteiro para uma matriz de valores indexCapacityInput uint32_t.

A enumeração XrSceneMeshSemanticLabelANDROID é o conjunto padrão de rótulos semânticos que podem ser usados para rotular vértices de malha e descrever em qual superfície do ambiente físico o vértice está. Esse conjunto de enumeração é representado pelo valor XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID em XrSceneMeshSemanticLabelSetANDROID .

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

Os enums têm os seguintes significados:

Descrição da enumeração

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

Esse rótulo semântico indica que o elemento de malha correspondente representa um objeto desconhecido.

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

Esse rótulo semântico indica que o elemento de malha correspondente representa um piso.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

Esse rótulo semântico indica que o elemento de malha correspondente representa um teto.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

Esse rótulo semântico indica que o elemento de malha correspondente representa uma parede.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

Esse rótulo semântico indica que o elemento de malha correspondente representa uma tabela.

Destruir um snapshot da malha do ambiente

A função xrDestroySceneMeshSnapshotANDROID é definida como:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Descrições dos parâmetros

O aplicativo pode usar a função xrDestroySceneMeshSnapshotANDROID para destruir um snapshot de malha de cena. Depois que o identificador é destruído, o aplicativo não pode mais usá-lo para receber informações ou dados da submalha. O identificador é destruído automaticamente quando o rastreador é destruído, porque o identificador do rastreador é o pai do identificador do snapshot da malha da cena.

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

Exemplo de código para malha do ambiente

O exemplo de código a seguir demonstra como acessar dados de malha de cena para renderização.

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

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

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

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

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

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

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

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

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

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

  // ...

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

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

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

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

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

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

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

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

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

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

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

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

Novos tipos de objeto

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de tipo enumerado

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • Extensão de XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • Extensão de XrStructureType :

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

Problemas

Histórico de versões

  • Revisão 3, 15/05/2025 (Salar Khan)

    • Descrição inicial da extensão