Extensão OpenXR XR_ANDROID_scene_meshing

Name String XR_ANDROID_scene_meshing

Tipo de extensão Extensão de instância

Número de extensão registrado 464

Revisão 3

Dependências de extensão e versão OpenXR 1.0

Data da última modificação 15/05/2025

Status do IP Nenhuma reivindicação de IP 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 foi criada para fornecer dados de malha para as malhas que representam aproximadamente os objetos físicos no seu ambiente. Ele pode ser usado para visualizar sua cena em um aplicativo imersivo e permitir que objetos virtuais interajam com objetos físicos, como colisões.

Os dados de fusão de cenas podem ser informações pessoais sensíveis e estão intimamente ligados à privacidade e integridade pessoais. É 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 sensível porque permite que o tempo de execução estude o ambiente do usuário.

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

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

Inspecionar a capacidade do sistema

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

XrSystemSceneMeshingPropertiesANDROID

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 é definida no OpenXR principal ou nesta extensão.
  • supportsSceneMeshing é um XrBool32, indicando se o sistema é compatível com a malha de cena.

Se supportsSceneMeshing for XR_FALSE, o sistema não vai oferecer suporte à fusão de cenas. O aplicativo deve evitar usar a funcionalidade de malha de cena quando supportsSceneMeshing for XR_FALSE, já que as chamadas para xrCreateSceneMeshingTrackerANDROID vão falhar.

Se supportsSceneMeshing for XR_TRUE, o sistema vai oferecer suporte à malha de cena.

Uso válido (implícito)

XrSceneMeshSemanticLabelSetANDROID

A enumeração XrSceneMeshSemanticLabelSetANDROID descreve os conjuntos de rótulos semânticos para malha de cena. Cada valor nesse enum representa outro enum 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;

xrEnumerateSupportedSemanticLabelSetsANDROID

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

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 retentado de xrGetSystem.
  • supportedSemanticLabelSetsInputCapacity é o comprimento de supportedSemanticLabelSets.
  • supportedSemanticLabelSetsOutputCount é o número de elementos em supportedSemanticLabelSets modificados pelo ambiente de execução desde o início da matriz.
  • supportedSemanticLabelSets é uma matriz de XrSceneMeshSemanticLabelSetANDROID em que os conjuntos de rótulos semânticos compatíveis são gravados pelo ambiente de execução.

Espera-se que todos os sistemas ofereçam suporte a XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID, porque esse valor de enumeração não representa um conjunto de rótulos semânticos e pode ser usado caso o aplicativo não precise de semântica de vértice.

Criar um identificador de rastreador de fusão de cenas

XrSceneMeshingTrackerANDROID

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

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

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

xrCreateSceneMeshingTrackerANDROID

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

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

Descrições dos parâmetros

Se o sistema não for compatível com a fusão de cenas, xrCreateSceneMeshingTrackerANDROID vai retornar XR_ERROR_FEATURE_UNSUPPORTED. O aplicativo pode verificar o suporte do sistema chamando xrGetSystemProperties com a estrutura XrSystemSceneMeshingPropertiesANDROID.

Somente conjuntos de rótulos semânticos compatíveis com o sistema podem ser usados em XrSceneMeshingTrackerCreateInfoANDROID::semanticLabelSet ao criar um rastreador de malha de cena. A função xrEnumerateSupportedSemanticLabelSetsANDROID pode ser usada para receber a lista de conjuntos de rótulos semânticos compatíveis.

Se o aplicativo solicitar um semanticLabelSet não compatível, xrCreateSceneMeshingTrackerANDROID vai retornar XR_ERROR_FEATURE_UNSUPPORTED.

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

XrSceneMeshingTrackerCreateInfoANDROID

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

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 é 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 esse valor for definido como XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID, o tempo de execução vai ignorar o campo de buffer XrSceneSubmeshDataANDROID::vertexSemantics.
  • enableNormals é um XrBool32 usado para especificar se é necessário incluir normais de vértice para os vértices da malha no buffer de malha da cena ao receber os dados da malha da cena.

xrDestroySceneMeshingTrackerANDROID

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

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID          tracker);

Descrições dos parâmetros

Criar um identificador de snapshot de malha de cena

XrSceneMeshSnapshotANDROID

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

O identificador XrSceneMeshSnapshotANDROID representa um instantâneo de malha de cena. Ele é criado usando xrCreateSceneMeshSnapshotANDROID, que basicamente captura um snapshot dos dados de malha da cena no momento da chamada de função.

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

XrSceneMeshSnapshotCreateInfoANDROID

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

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 é definida no OpenXR principal ou nesta extensão.
  • baseSpace é um XrSpace usado para descrever o espaço de referência em que as informações de postura das submalhas da cena devem ser representadas.
  • time é o XrTime que descreve o momento em que a malha da cena será processada ou exibida.
  • boundingBox é um XrBoxf que descreve a caixa delimitadora em que a malha da cena será adquirida.

XrSceneMeshTrackingStateANDROID

A enumeração XrSceneMeshTrackingStateANDROID descreve o estado de rastreamento do rastreador de malha de cena. Cada valor nesse enum representa um estado do rastreador de malha de cena. Essa enumeração é encapsulada na estrutura XrSceneMeshSnapshotCreationResultANDROID, que é retornada de xrCreateSceneMeshSnapshotANDROID.

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;

XrSceneMeshSnapshotCreationResultANDROID

A estrutura XrSceneMeshSnapshotCreationResultANDROID armazena o resultado de uma criação de snapshot de malha de cena retornada de xrCreateSceneMeshSnapshotANDROID. O resultado inclui o identificador do snapshot e o estado de rastreamento do rastreador de malha da cena no momento da criação do snapshot.

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                  type;
    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 é definida no OpenXR principal ou nesta extensão.
  • snapshot é um identificador XrSceneMeshSnapshotANDROID criado pelo tempo de execução.
  • trackingState é um XrSceneMeshTrackingStateANDROID que descreve o estado do rastreador de malha de cena no momento da criação do snapshot.

xrCreateSceneMeshSnapshotANDROID

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 identificador é um snapshot dos dados da malha da cena 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.

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

Descrições dos parâmetros

Como adquirir dados de malha de cena do snapshot de malha de cena

XrSceneSubmeshStateANDROID

XrSceneSubmeshStateANDROID descreve uma submalha. Ele contém as informações básicas sobre a submalha (ID, postura, limites, hora da última atualização).

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 é 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 base usado para criar o snapshot da malha da cena. Essa também é a postura do centro da caixa delimitadora da submalha.
  • bounds é um XrExtent3Df que descreve as dimensões da caixa delimitadora que envolve a submalha. Esses limites estão no espaço de base usado para criar o identificador da malha de cena.

xrGetAllSubmeshStatesANDROID

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. Essa função pode ser usada em uma expressão de duas chamadas.

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 é o comprimento de submeshStates.
  • submeshStateCountOutput é o número de elementos em submeshStates que são modificados pelo ambiente de execução desde o início da matriz.
  • submeshStates é uma matriz de estruturas XrSceneSubmeshStateANDROID a que o tempo de execução vai gerar o estado de todas as submalhas na malha de cena.

XrSceneSubmeshDataANDROID

XrSceneSubmeshDataANDROID contém os dados de triângulo de uma submalha junto com o ID da submalha. Essa estrutura é usada em xrGetSubmeshDataANDROID para receber os dados da submalha. O aplicativo precisa definir o ID da submalha dessa struct e os ponteiros de buffer para buffers alocados para que os dados retornados da submalha possam ser preenchidos nos buffers alocados. O aplicativo pode usar xrGetSubmeshDataANDROID como um idioma de duas chamadas em que a primeira chamada exige que o aplicativo defina o ID da submalha e receba os tamanhos dos buffers necessários para os dados da submalha. Depois, o aplicativo pode alocar os buffers e receber os dados na segunda chamada.

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 é definida no OpenXR principal ou nesta extensão.
  • submeshId é um XrUuid que identifica a submalha.
  • vertexCapacityInput é o comprimento de vertexPositions, vertexNormals e vertexSemantics.
  • vertexCountOutput é o número de elementos em vertexPositions, vertexNormals e vertexSemantics que foram modificados pelo ambiente de execução desde o início da matriz.
  • 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 desativadas.
  • vertexSemantics é uma matriz de uint8_t em que o tempo 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 um conjunto de rótulos semânticos XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID.
  • indexCapacityInput é o comprimento de indices.
  • indexCountOutput é o número de elementos em indices que foram modificados pelo ambiente de execução desde o início da matriz.
  • indices é uma matriz de uint32_t em que o ambiente de execução vai gerar os índices da submalha.

xrGetSubmeshDataANDROID

O aplicativo pode usar a função xrGetSubmeshDataANDROID para receber os dados de uma lista selecionada de submalhas. Essa função pode ser usada em uma expressão de duas chamadas. Na primeira chamada, o aplicativo precisa definir um ID de submalha válido (ou seja, recuperável de xrGetAllSubmeshStatesANDROID com o mesmo snapshot de malha de cena) e capacidade zero para cada elemento na lista selecionada de submalhas para receber os tamanhos dos buffers necessários para os dados da submalha. Na segunda chamada, o aplicativo precisa definir os ponteiros de buffer para um buffer alocado para cada elemento na lista selecionada de submalhas, além da capacidade dos buffers para receber os dados das submalhas.

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

Descrições dos parâmetros

XrSceneMeshSemanticLabelANDROID

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;

Destruir um snapshot de malha de cena

xrDestroySceneMeshSnapshotANDROID

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

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID            snapshot);

Descrições dos parâmetros

Exemplo de código para malha de cena

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
  std::vector<XrSceneSubmeshStateANDROID> states;
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  states.resize(submeshCount);
  for (XrSceneSubmeshStateANDROID& state : states) {
    state = {.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.vertexCountOutput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCountOutput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCountOutput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCountOutput];
  }
  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 =
      reinterpret_cast<XrSceneMeshSemanticLabelANDROID*>(data.vertexSemantics);
    XrPosef pose = submeshesPoses[i];

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

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

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

Novos tipos de objetos

Novas constantes de enumeração

A enumeração XrObjectType é estendida com:

  • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
  • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

A enumeração XrStructureType é estendida com:

  • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID
  • 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_STATE_ANDROID
  • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID

Novos enums

Novas estruturas

Novas funções

Problemas

Histórico de versões

  • Revisão 3, 15/05/2025 (Salar Khan) ** Descrição inicial da extensão

OpenXR™ e o logotipo OpenXR são marcas registradas de propriedade da Khronos Group Inc. e estão registradas como marcas comerciais na China, na União Europeia, no Japão e no Reino Unido.