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 de 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

Nenhuma reivindicação de PI conhecida.

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 tem como objetivo fornecer malhas que representem 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 de malha de cena são gerados pelo ambiente de execução e compartilhados com o aplicativo usando XrSceneMeshingTrackerANDROID e XrSceneMeshSnapshotANDROID . Os aplicativos podem acessar os valores nas informações de submalha de 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 malha de cena 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 malha de cena sempre peçam ao usuário uma aceitação ativa e específica para fazer isso.

Permissões

Os apps 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 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.
  • supportsSceneMeshing é um XrBool32 , que indica se o sistema é compatível com a malha de cena.

Um aplicativo pode verificar se o sistema é capaz de criar malhas de cena encadeando uma estrutura XrSystemSceneMeshingPropertiesANDROID ao XrSystemProperties ao chamar xrGetSystemProperties .

Se um ambiente de execução retornar XR_FALSE para supportsSceneMeshing, o sistema não será compatível com a malha de cena e, portanto, precisará retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateSceneMeshingTrackerANDROID . O aplicativo não deve 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 será compatível com a malha de cena.

Uso válido (implícito)

A enumeração XrSceneMeshSemanticLabelSetANDROID descreve os conjuntos de rótulos semânticos para a 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_DEFAULT2_ANDROID = 1000801000,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

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

Descrição do tipo enumerado

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Esse conjunto de rótulos semânticos 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.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

Esse conjunto de rótulos semânticos representa XrSceneMeshSemanticLabel2ANDROID. (Adicionado pela extensão XR_ANDROID_scene_meshing_semantic_label2)

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 é uma XrInstance criada pelo aplicativo.
  • systemId é um XrSystemId 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 um ponteiro para a capacidade necessária caso supportedSemanticLabelSetsInputCapacity seja insuficiente.
  • supportedSemanticLabelSets é um ponteiro para uma matriz de XrSceneMeshSemanticLabelSetANDROID . 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 de 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 tipo enumerado 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 do ambiente para criar malhas e gerenciar os recursos relacionados.

Esse identificador pode ser usado para criar um snapshot da malha do ambiente 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 ambiente de execução precisa retornar XR_ERROR_FEATURE_UNSUPPORTED de xrCreateSceneMeshingTrackerANDROID . Nesse caso, o ambiente de execução precisa retornar XR_FALSE para XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing quando a função xrGetSystemProperties é chamada, para que o aplicativo possa 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értice de malha de cena sem suporte, o ambiente de execução precisará 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 é o proprietário de todos os recursos para a malha de cena. Depois de concluir 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 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.
  • semanticLabelSet é um XrSceneMeshSemanticLabelSetANDROID usado para especificar o conjunto de rótulos semânticos a ser usado na malha de cena. Se definido como XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , o ambiente de execução vai ignorar o campo de buffer XrSceneSubmeshDataANDROID :: vertexSemantics.
  • 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 relacionados 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 identificador XrSceneMeshSnapshotANDROID representa um snapshot da malha do ambiente. Esse snapshot é criado usando xrCreateSceneMeshSnapshotANDROID, que faz um snapshot dos dados da malha do ambiente no momento da chamada de 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 identificador XrSceneMeshSnapshotANDROID com XrSceneMeshTrackingStateANDROID encapsulado em uma estrutura XrSceneMeshSnapshotCreationResultANDROID. O handle é tecnicamente 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 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.
  • baseSpace é um XrSpace em que as informações de pose da submalha da cena são representadas.
  • time é o XrTime que descreve o momento em que a malha da cena será processada ou exibida, normalmente 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 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.
  • 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 da criação de um snapshot de malha de cena retornado 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 tipo enumerado representa um estado do rastreador de malha de 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 do tipo enumerado

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

O rastreador ainda não está pronto para fornecer dados de malha.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

O monitor fitness está monitorando ativamente.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

O rastreador 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 por vários ciclos e está em um 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, independentemente do XrSceneMeshTrackingStateANDROID atual do rastreador. Se o estado não for XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID , os snapshots podem 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 um ponteiro para a capacidade necessária caso submeshStateCapacityInput seja insuficiente.
  • submeshStates é um ponteiro para uma matriz de estruturas XrSceneSubmeshStateANDROID em que o ambiente de execução vai gerar o estado de todas as submalhas na malha da cena. 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 de submeshStates necessário.

O aplicativo pode usar a função xrGetAllSubmeshStatesANDROID para conferir o estado de todas as submalhas na malha da cena. Contém informações básicas para permitir que o aplicativo selecione as submalhas para as quais 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 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.
  • 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 pose da submalha no espaço de base usado para criar o snapshot da malha de cena. A pose também é o centro da caixa delimitadora da submalha.
  • bounds é um XrExtent3Df que descreve as dimensões da caixa delimitadora que envolve a submalha. Esse limite é definido no espaço base que foi usado para criar o identificador de malha de cena.

O ambiente de execução faz o possível para mapear submeshId com a região do espaço físico ocupado pela submalha. Os ambientes de execução podem perder esse mapeamento a qualquer momento e atribuir um novo UUID a qualquer subconjunto das submalhas detectadas. Em particular, os ambientes de execução não precisam reutilizar os mesmos UUIDs para as mesmas malhas em instâncias de aplicativo 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, transmitindo uma lista de XrSceneSubmeshDataANDROID com cada XrSceneSubmeshDataANDROID :: submeshId definido como o respectivo ID 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 precisará retornar XR_ERROR_VALIDATION_FAILURE .

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

Isso pode ser usado em um idioma 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 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.
  • 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 um ponteiro para a capacidade necessária caso vertexCapacityInput seja insuficiente.
  • vertexPositions é uma matriz de XrVector3f em que o ambiente de execução vai gerar as posições de vértice da submalha.
  • vertexNormals é uma matriz de XrVector3f em que o ambiente de execução vai gerar as normais de vértice da submalha. Este campo pode ser deixado NULL se o aplicativo tiver criado um rastreador com as normais desativadas.
  • vertexSemantics é uma matriz de uint8_t em que o ambiente de execução vai gerar a semântica de vértice da submalha. Esse 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 um ponteiro 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 vertexCapacityInput XrVector3f.
  • Se vertexCapacityInput não for 0 , vertexNormals precisa ser um ponteiro para uma matriz de estruturas vertexCapacityInput XrVector3f.
  • 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 física do ambiente o vértice de malha está. Esse conjunto de tipos enumerados é 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 tipos enumerados têm os seguintes significados:

Descrição do tipo enumerado

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

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 as informações ou os 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 de 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

  • Estendendo XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

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