XR_ANDROID_scene_meshing

Cadena de nombre

XR_ANDROID_scene_meshing

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

719

Revisión

3

Estado de ratificación

No se ratificó

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de la última modificación

2025-05-15

Estado de la IP

No hay reclamos conocidos por IP.

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

Descripción general

Esta extensión tiene como objetivo proporcionar mallas que representen aproximadamente los objetos físicos en el entorno del usuario.

Las aplicaciones pueden usar esta extensión para visualizar la escena y permitir que los objetos virtuales interactúen con los objetos físicos, como las colisiones.

El entorno de ejecución genera los datos de la malla de la escena y los comparte con la aplicación a través de XrSceneMeshingTrackerANDROID y XrSceneMeshSnapshotANDROID . Las aplicaciones pueden acceder a los valores de la información de la submalla de la escena a través de XrSceneSubmeshStateANDROID que se devuelve desde xrGetAllSubmeshStatesANDROID . Las aplicaciones pueden acceder a los valores en los datos de la submalla de la escena a través de XrSceneSubmeshDataANDROID que se devuelve desde xrGetSubmeshDataANDROID .

Los datos de la malla de la escena son información personal sensible y están estrechamente vinculados a la privacidad y la integridad personales. Se recomienda encarecidamente que las aplicaciones que almacenan o transfieren datos de malla de la escena siempre le pidan al usuario que acepte de forma activa y específica hacerlo.

Permisos

Las aplicaciones para Android deben tener el permiso android.permission.SCENE_UNDERSTANDING_FINE en su manifiesto. El permiso android.permission.SCENE_UNDERSTANDING_FINE se considera un permiso sensible, ya que permite que el tiempo de ejecución estudie el entorno del usuario.

La aplicación debe solicitar el permiso durante el tiempo de ejecución para usar estas funciones:

(nivel de protección: peligroso)

Inspecciona la capacidad del sistema

La estructura XrSystemSceneMeshingPropertiesANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • supportsSceneMeshing es un XrBool32 que indica si el sistema admite la generación de mallas de escenas.

Una aplicación puede inspeccionar si el sistema es capaz de realizar el mallado de la escena encadenando una estructura XrSystemSceneMeshingPropertiesANDROID a XrSystemProperties cuando se llama a xrGetSystemProperties .

Si un tiempo de ejecución devuelve XR_FALSE para supportsSceneMeshing, el sistema no admite el mallado de escenas y, por lo tanto, debe devolver XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateSceneMeshingTrackerANDROID . La aplicación debe evitar usar la función de malla de la escena cuando supportsSceneMeshing es XR_FALSE .

Si un tiempo de ejecución devuelve XR_TRUE para supportsSceneMeshing , el sistema admite el mallado de escenas.

Uso válido (implícito)

La enumeración XrSceneMeshSemanticLabelSetANDROID describe los conjuntos de etiquetas semánticas para la generación de mallas de escenas. Cada valor de este enum representa otro enum que contiene las etiquetas semánticas. Por ejemplo, el valor XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID representa el 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;

Los valores de enumeración tienen los siguientes significados:

Descripción de la enumeración

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Este conjunto de etiquetas semánticas representa la ausencia de etiquetas semánticas.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

Este conjunto de etiquetas semánticas representa XrSceneMeshSemanticLabelANDROID.

La función xrEnumerateSupportedSemanticLabelSetsANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

  • instance es un XrInstance creado por la aplicación.
  • systemId es un XrSystemId que se reintenta desde xrGetSystem .
  • supportedSemanticLabelSetsInputCapacity es la capacidad de supportedSemanticLabelSets o 0 para recuperar la capacidad requerida.
  • supportedSemanticLabelSetsOutputCount es un puntero al recuento de supportedSemanticLabelSets escritos o un puntero a la capacidad requerida en el caso de que supportedSemanticLabelSetsInputCapacity sea insuficiente.
  • supportedSemanticLabelSets es un puntero a un array de XrSceneMeshSemanticLabelSetANDROID . Puede ser NULL si supportedSemanticLabelSetsInputCapacity es 0.
  • Consulta el capítulo Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño supportedSemanticLabelSets requerido.

La aplicación puede enumerar los conjuntos de etiquetas semánticas compatibles con el sistema usando la función xrEnumerateSupportedSemanticLabelSetsANDROID.

Todos los sistemas deben admitir al menos XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID, ya que este valor de enumeración representa que no se estableció ninguna etiqueta semántica y se puede usar en el caso de que la aplicación no necesite semántica de vértices.

Uso válido (implícito)

  • La extensión XR_ANDROID_scene_meshing debe habilitarse antes de llamar a xrEnumerateSupportedSemanticLabelSetsANDROID.
  • instance debe ser un identificador de XrInstance válido
  • supportedSemanticLabelSetsOutputCount debe ser un puntero a un valor uint32_t
  • Si supportedSemanticLabelSetsInputCapacity no es 0 , supportedSemanticLabelSets debe ser un puntero a un array de valores XrSceneMeshSemanticLabelSetANDROID de supportedSemanticLabelSetsInputCapacity.

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • 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

Crea un identificador de seguimiento de unión de escenas

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

El controlador XrSceneMeshingTrackerANDROID representa un objeto de seguimiento de la malla de la escena para la malla de la escena y la administración de los recursos relacionados.

Este identificador se puede usar para crear una instantánea de la malla de la escena con xrCreateSceneMeshSnapshotANDROID en esta extensión.

La función xrCreateSceneMeshingTrackerANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

Una aplicación puede crear un controlador XrSceneMeshingTrackerANDROID con la función xrCreateSceneMeshingTrackerANDROID.

Si el sistema no admite la generación de mallas de la escena, el tiempo de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateSceneMeshingTrackerANDROID . En este caso, el tiempo de ejecución debe devolver XR_FALSE para XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing cuando se llama a la función xrGetSystemProperties, de modo que la aplicación pueda evitar la creación de un objeto de seguimiento de la malla de la escena.

La aplicación solo debe usar los conjuntos de etiquetas semánticas que admite el sistema en XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet cuando cree un objeto de seguimiento de malla de escena. Si la aplicación usa un conjunto de etiquetas semánticas de vértices de malla de escena no admitido, el tiempo de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateSceneMeshingTrackerANDROID .

La aplicación puede enumerar la lista de conjuntos de etiquetas semánticas admitidos con la función xrEnumerateSupportedSemanticLabelSetsANDROID.

El identificador xrCreateSceneMeshingTrackerANDROID posee todos los recursos para el mallado de la escena. Una vez que finalice la experiencia de generación de malla de la escena, la aplicación debe destruir el identificador a través de la función xrDestroySceneMeshingTrackerANDROID.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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

La estructura XrSceneMeshingTrackerCreateInfoANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • semanticLabelSet es un XrSceneMeshSemanticLabelSetANDROID que se usa para especificar el conjunto de etiquetas semánticas que se usarán para el mallado de la escena. Si se establece en XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , el tiempo de ejecución ignorará el campo de búfer vertexSemantics de XrSceneSubmeshDataANDROID.
  • enableNormals es un XrBool32 que se usa para especificar si se deben incluir las normales de los vértices de la malla en el búfer de malla de la escena cuando se obtienen los datos de la malla de la escena.

La estructura XrSceneMeshingTrackerCreateInfoANDROID describe la información para crear un identificador XrSceneMeshingTrackerANDROID.

Uso válido (implícito)

La función xrDestroySceneMeshingTrackerANDROID se define de la siguiente manera:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Descripciones de los parámetros

La función xrDestroySceneMeshingTrackerANDROID libera el tracker y los recursos subyacentes cuando se terminan las experiencias de mallado de la escena.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a tracker y a cualquier identificador secundario debe sincronizarse de forma externa.

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Crea un identificador de instantánea de malla de escena

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

El identificador XrSceneMeshSnapshotANDROID representa una instantánea de la malla de la escena. Esta instantánea se crea con xrCreateSceneMeshSnapshotANDROID, que toma una instantánea de los datos de la malla de la escena en el momento de la llamada a la función.

Este identificador se puede usar para recuperar información y datos de la submalla con xrGetAllSubmeshStatesANDROID y xrGetSubmeshDataANDROID .

La función xrCreateSceneMeshSnapshotANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

La aplicación puede usar la función xrCreateSceneMeshSnapshotANDROID para crear una instantánea de la malla de la escena a partir del objeto de seguimiento de la malla de la escena. Esta función devuelve un identificador de XrSceneMeshSnapshotANDROID junto con XrSceneMeshTrackingStateANDROID encapsulado en una estructura de XrSceneMeshSnapshotCreationResultANDROID. Técnicamente, el identificador es una instantánea de los datos de la malla de la escena en el momento de la creación. Este identificador se puede usar para consultar la información y los datos de la malla de la escena con xrGetAllSubmeshStatesANDROID y xrGetSubmeshDataANDROID, respectivamente.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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

La estructura XrSceneMeshSnapshotCreateInfoANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • baseSpace es un XrSpace dentro del cual se representa la información de la pose de la submalla de la escena.
  • time es el XrTime que describe el momento en que se procesará o mostrará la malla de la escena, por lo general, XrFrameState :: predictedDisplayTime .
  • boundingBox es un XrBoxf que describe el cuadro delimitador dentro del cual se debe adquirir la malla de la escena.

La estructura XrSceneMeshSnapshotCreateInfoANDROID describe la información para crear un identificador XrSceneMeshSnapshotANDROID.

Uso válido (implícito)

La estructura XrSceneMeshSnapshotCreationResultANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • snapshot es un identificador de XrSceneMeshSnapshotANDROID creado por el tiempo de ejecución.
  • trackingState es un XrSceneMeshTrackingStateANDROID que describe el estado del objeto de seguimiento de la malla de la escena en el momento de la creación de la instantánea.

La estructura XrSceneMeshSnapshotCreationResultANDROID almacena el resultado de la creación de una instantánea de malla de escena que se devolvió desde xrCreateSceneMeshSnapshotANDROID .

Uso válido (implícito)

La enumeración XrSceneMeshTrackingStateANDROID describe el estado de seguimiento de un objeto de seguimiento de malla de escena. Cada valor de esta enumeración representa un estado del objeto de seguimiento de la malla de la escena.

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;

Los valores de enumeración tienen los siguientes significados:

Descripción de la enumeración

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

El dispositivo de rastreo aún no está listo para proporcionar datos de malla.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

El dispositivo de rastreo está realizando el seguimiento de forma activa.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

El dispositivo de seguimiento está esperando mediciones válidas para integrar desde la última actualización de la malla.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

El rastreador no recibió mediciones válidas durante varios ciclos y se encuentra en estado de error.

Este estado solo sirve como información adicional para la aplicación. En ausencia de otras fuentes de errores, el tiempo de ejecución debe seguir permitiendo que la aplicación cree instantáneas y recupere datos de ellas, independientemente del XrSceneMeshTrackingStateANDROID actual del objeto de seguimiento. Si el estado no es XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID , es posible que las instantáneas no estén actualizadas o estén vacías.

Cómo adquirir datos de la malla de la escena a partir de la instantánea de la malla de la escena

La función xrGetAllSubmeshStatesANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

  • snapshot es un identificador de XrSceneMeshSnapshotANDROID creado anteriormente con xrCreateSceneMeshSnapshotANDROID .
  • submeshStateCapacityInput es la capacidad de submeshStates o 0 para recuperar la capacidad requerida.
  • submeshStateCountOutput es un puntero al recuento de submeshStates escritos o un puntero a la capacidad requerida en el caso de que submeshStateCapacityInput sea insuficiente.
  • submeshStates es un puntero a un array de estructuras XrSceneSubmeshStateANDROID en el que el tiempo de ejecución generará el estado de todas las submallas de la malla de la escena. Puede ser NULL si submeshStateCapacityInput es 0.
  • Consulta el capítulo Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño submeshStates requerido.

La aplicación puede usar la función xrGetAllSubmeshStatesANDROID para obtener el estado de todas las submallas en la malla de la escena. Contiene información básica para permitir que la aplicación seleccione las submallas para las que desea datos.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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

La estructura XrSceneSubmeshStateANDROID se define de la siguiente manera:

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

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • submeshId es un XrUuid que identifica la submalla.
  • lastUpdatedTime es un XrTime que representa la hora en la que se actualizó la malla secundaria por última vez.
  • submeshPoseInBaseSpace es un XrPosef que representa la pose de la submalla en el espacio base que se usa para crear la instantánea de la malla de la escena. La pose también es el centro del cuadro delimitador de la submalla.
  • bounds es un XrExtent3Df que describe las dimensiones del cuadro delimitador que encierra la submalla. Estos límites se definen en el espacio base que se usó para crear el identificador de la malla de la escena.

El tiempo de ejecución hace todo lo posible para correlacionar submeshId con la región del espacio físico que ocupa la submalla. Los tiempos de ejecución pueden perder esta asignación en cualquier momento y asignar un nuevo UUID a cualquier subconjunto de las submallas detectadas. En particular, no se requiere que los tiempos de ejecución reutilicen los mismos UUID para las mismas mallas en instancias de aplicaciones posteriores.

Uso válido (implícito)

La función xrGetSubmeshDataANDROID se define de la siguiente manera:

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

Descripciones de los parámetros

La aplicación puede usar la función xrGetSubmeshDataANDROID para obtener lotes de submallas o todas las submallas a la vez. Para ello, debe pasar una lista de XrSceneSubmeshDataANDROID con cada XrSceneSubmeshDataANDROID :: submeshId establecida en el ID respectivo de la submalla que se recuperará.

El XrSceneSubmeshDataANDROID :: submeshId debe ser único para cada elemento de inoutSubmeshData y recuperable por xrGetAllSubmeshStatesANDROID para el mismo snapshot . Si el ID de la submalla es no válido o más de un elemento en inoutSubmeshData tiene el mismo ID de submalla, el tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

submeshDataCount debe ser igual o menor que el valor que devuelve xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput; de lo contrario , el tiempo de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

Este can se puede usar en un modismo de 2 llamadas para consultar el recuento de vértices y de índices de todas las submallas seleccionadas.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

  • 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

La estructura XrSceneSubmeshDataANDROID se define de la siguiente manera:

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;

Descripciones de los miembros

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • submeshId es un XrUuid que identifica la submalla.
  • vertexCapacityInput es la capacidad de vertexPositions , vertexNormals y vertexSemantics , o 0 para recuperar la capacidad requerida.
  • vertexCountOutput es un puntero al recuento de vertexPositions, vertexNormals y vertexSemantics escritos, o bien un puntero a la capacidad requerida en el caso de que vertexCapacityInput sea insuficiente.
  • vertexPositions es un array de XrVector3f en el que el tiempo de ejecución generará las posiciones de los vértices de la malla secundaria.
  • vertexNormals es un array de XrVector3f en el que el tiempo de ejecución generará las normales de los vértices de la submalla. Este campo se puede dejar NULL si la aplicación creó un objeto de seguimiento con las normales inhabilitadas.
  • vertexSemantics es un array de uint8_t al que el tiempo de ejecución generará la semántica de los vértices de la submalla. Este campo se puede dejar NULL si la aplicación creó un objeto de seguimiento con la etiqueta semántica XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID establecida.
  • indexCapacityInput es la capacidad de indices o 0 para recuperar la capacidad requerida.
  • indexCountOutput es un puntero al recuento de indices escritos o un puntero a la capacidad requerida en el caso de que vertexCapacityInput sea insuficiente.
  • indices es un array de uint32_t en el que el tiempo de ejecución generará los índices de la submalla.
  • Consulta el capítulo Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño requerido de vertexPositions, vertexNormals, vertexSemantics y indices.

Uso válido (implícito)

  • La extensión XR_ANDROID_scene_meshing debe habilitarse antes de usar XrSceneSubmeshDataANDROID
  • type debe ser XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructuras
  • Si vertexCapacityInput no es 0 , vertexPositions debe ser un puntero a un array de estructuras XrVector3f de vertexCapacityInput.
  • Si vertexCapacityInput no es 0 , vertexNormals debe ser un puntero a un array de estructuras XrVector3f de vertexCapacityInput.
  • Si vertexCapacityInput no es 0 , vertexSemantics debe ser un puntero a un array de valores vertexCapacityInput uint8_t.
  • Si indexCapacityInput no es 0 , indices debe ser un puntero a un array de valores indexCapacityInput uint32_t.

La enumeración XrSceneMeshSemanticLabelANDROID es el conjunto predeterminado de etiquetas semánticas que se pueden usar para etiquetar los vértices de la malla y describir en qué superficie del entorno físico se encuentra el vértice de la malla. Este conjunto de enumeración se representa con el valor XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID en 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;

Los enums tienen los siguientes significados:

Descripción de la enumeración

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

Esta etiqueta semántica indica que el elemento de malla correspondiente representa un objeto desconocido.

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

Esta etiqueta semántica indica que el elemento de malla correspondiente representa un piso.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

Esta etiqueta semántica indica que el elemento de malla correspondiente representa un techo.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

Esta etiqueta semántica indica que el elemento de malla correspondiente representa una pared.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

Esta etiqueta semántica indica que el elemento de malla correspondiente representa una mesa.

Destruye una instantánea de malla de escena

La función xrDestroySceneMeshSnapshotANDROID se define de la siguiente manera:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Descripciones de los parámetros

La aplicación puede usar la función xrDestroySceneMeshSnapshotANDROID para destruir una instantánea de malla de escena. Una vez que se destruye el identificador, la aplicación ya no puede usarlo para obtener información o datos de la submalla. El identificador se destruye automáticamente cuando se destruye el objeto de seguimiento, ya que el identificador del objeto de seguimiento es el elemento superior del identificador de la instantánea de la malla de la escena.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a snapshot y a cualquier identificador secundario debe sincronizarse de forma externa.

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Ejemplo de código para la generación de mallas de escenas

En el siguiente ejemplo de código, se muestra cómo acceder a los datos de la malla de la escena para la renderización.

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

Nuevos tipos de objetos

Comandos nuevos

Nuevas estructuras

Enums nuevos

Nuevas constantes de enumeración

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • Extensión de XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • Extensión 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

Historial de versiones

  • Revisión 3, 2025-05-15 (Salar Khan)

    • Descripción inicial de la extensión