XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

Tipo de extensión

Extensión de instancia

Número de extensión registrado

719

Revisión

3

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de la última modificación

2025-05-15

Estado de la IP

No hay reclamos de IP conocidos.

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 de forma aproximada 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 mediante 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 de xrGetAllSubmeshStatesANDROID . Las aplicaciones pueden acceder a los valores de los datos de la submesh de la escena a través de XrSceneSubmeshDataANDROID que se devuelve de xrGetSubmeshDataANDROID .

Los datos de malla de escenas son información personal sensible y están estrechamente vinculados a la privacidad y la integridad de las personas. Se recomienda que las aplicaciones que almacenan o transfieren datos de mallas de escenas siempre soliciten al usuario una aceptación activa y específica para 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 entorno 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 creación de mallas de escenas.

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

Si un entorno de ejecución devuelve XR_FALSE para supportsSceneMeshing, el sistema no admite la creación de mallas de escenas y, por lo tanto, debe devolver XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateSceneMeshingTrackerANDROID . La aplicación debería evitar usar la funcionalidad de generación de mallas de escenas cuando supportsSceneMeshing sea XR_FALSE .

Si un entorno de ejecución devuelve XR_TRUE para supportsSceneMeshing , el sistema admite la creación de mallas de escenas.

Uso válido (implícito)

La enumeración XrSceneMeshSemanticLabelSetANDROID describe los conjuntos de etiquetas semánticas para la malla 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_DEFAULT2_ANDROID = 1000801000,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

Los valores de enumeración tienen los siguientes significados:

Descripción de enum

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.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

Este conjunto de etiquetas semánticas representa XrSceneMeshSemanticLabel2ANDROID. (Agregado por la extensión XR_ANDROID_scene_meshing_semantic_label2)

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 una XrInstance que crea la aplicación.
  • systemId es un XrSystemId que se reintentó 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 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 de supportedSemanticLabelSets requerido.

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

Cada sistema debe, al menos, admitir XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID, ya que este valor de enumeración no representa un conjunto de etiquetas semánticas y se puede usar en 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 estar habilitada antes de llamar a xrEnumerateSupportedSemanticLabelSetsANDROID.
  • instance debe ser un controlador 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 supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID.

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 controlador de seguimiento de mallas de escenas

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

El controlador XrSceneMeshingTrackerANDROID representa un rastreador de mallas de escenas para crear mallas de escenas y administrar los recursos relacionados.

Este controlador se puede usar para crear una instantánea de malla de 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 malla de escenas, el entorno de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateSceneMeshingTrackerANDROID . En este caso, el entorno 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 crear un rastreador de mallas de escena.

La aplicación debe usar solo los conjuntos de etiquetas semánticas que admite el sistema en XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet cuando se crea un rastreador de mallas de escenas. Si la aplicación usa un conjunto de etiquetas semánticas de vértices de malla de escena no compatible, el entorno de ejecución debe devolver XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateSceneMeshingTrackerANDROID .

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

El controlador xrCreateSceneMeshingTrackerANDROID posee todos los recursos para la creación de mallas de escenas. Una vez que finalice la experiencia de creación de mallas de escenas, la aplicación debe destruir el controlador 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á para la malla de la escena. Si se establece en XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , el entorno de ejecución ignorará el campo de búfer XrSceneSubmeshDataANDROID :: vertexSemantics.
  • enableNormals es un XrBool32 que se usa para especificar si se deben incluir normales de vértices para 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 controlador 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 finalizan las experiencias de generación de mallas de escenas.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a tracker y a cualquier controlador 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 controlador de instantáneas de malla de escena

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

El controlador 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 función.

Este controlador se puede usar para recuperar información y datos de submallas 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 malla de escena a partir del rastreador de mallas de escena. Esta función devuelve un controlador XrSceneMeshSnapshotANDROID junto con XrSceneMeshTrackingStateANDROID unidos en una estructura XrSceneMeshSnapshotCreationResultANDROID. Técnicamente, el controlador es una instantánea de los datos de la malla de la escena en el momento de la creación. Este controlador 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 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 en el que se adquirirá la malla de la escena.

La estructura XrSceneMeshSnapshotCreateInfoANDROID describe la información para crear un controlador 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 controlador XrSceneMeshSnapshotANDROID que crea el entorno de ejecución.
  • trackingState es un XrSceneMeshTrackingStateANDROID que describe el estado del seguimiento de mallas de escenas en el momento en que se creó la instantánea.

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

Uso válido (implícito)

La enumeración XrSceneMeshTrackingStateANDROID describe el estado de seguimiento de un rastreador de mallas de escenas. Cada valor de este enum representa un estado del seguimiento de mallas 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 enum

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

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

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

El monitor está realizando un seguimiento activo.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

El rastreador está esperando que se integren mediciones válidas desde la última actualización de la malla.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

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

Este estado solo sirve como información adicional para la aplicación. En ausencia de otras fuentes de errores, el entorno de ejecución debe seguir permitiendo que la aplicación cree instantáneas y recupere datos de ellas, independientemente del XrSceneMeshTrackingStateANDROID actual del rastreador. 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.

Adquiere 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 controlador 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 caso de que submeshStateCapacityInput sea insuficiente.
  • submeshStates es un puntero a un array de estructuras XrSceneSubmeshStateANDROID en las que el entorno de ejecución generará el estado de todas las sub mallas 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 de submeshStates requerido.

La aplicación puede usar la función xrGetAllSubmeshStatesANDROID para obtener el estado de todas las sub mallas en la malla de la escena. Contiene información básica que permite que la aplicación seleccione las mallas secundarias para las que desea obtener 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 submalla por última vez.
  • submeshPoseInBaseSpace es un XrPosef que representa la pose de la submalla en el espacio base que se usó 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. Este límite se define en el espacio base que se usó para crear el controlador de malla de la escena.

El entorno de ejecución hace todo lo posible para asignar submeshId con la región del espacio físico que ocupa la submalla. Los entornos de ejecución pueden perder esta asignación en cualquier momento y asignar un UUID nuevo a cualquier subconjunto de las submallas detectadas. En particular, no se requiere que los entornos de ejecución reutilicen los mismos UUID para las mismas mallas en instancias de aplicación 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 configurado con el ID correspondiente de la submalla que se recuperará.

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

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

Esto se puede usar en un lenguaje 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 un puntero a la capacidad requerida en caso de que vertexCapacityInput sea insuficiente.
  • vertexPositions es un array de XrVector3f en el que el entorno de ejecución generará las posiciones de los vértices de la submesh.
  • vertexNormals es un array de XrVector3f en el que el entorno de ejecución generará las normales de vértices de la submesh. Este campo puede dejarse NULL si la aplicación creó un rastreador con las normales inhabilitadas.
  • vertexSemantics es un array de uint8_t en el que el entorno de ejecución generará la semántica de vértices de la submalla. Este campo puede dejarse NULL si la aplicación creó un rastreador 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 caso de que vertexCapacityInput sea insuficiente.
  • indices es un array de uint32_t en el que el entorno de ejecución generará los índices de la submesh.
  • 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 estar habilitada 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 vertexCapacityInput XrVector3f.
  • Si vertexCapacityInput no es 0 , vertexNormals debe ser un puntero a un array de estructuras vertexCapacityInput XrVector3f.
  • 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 vértices de malla y describir en qué superficie del entorno físico se encuentra el vértice de malla. Este conjunto de enumeraciones 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;

Las enumeraciones tienen los siguientes significados:

Descripción de enum

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

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 controlador, la aplicación ya no puede usarlo para obtener la información o los datos de la submalla. El controlador se destruye automáticamente cuando se destruye el rastreador, ya que el controlador del rastreador es el elemento superior del controlador 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 controlador 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

Código de ejemplo para la creació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 renderizarla.

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

Estructuras nuevas

Enums nuevas

Nuevas constantes de enum

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • Extiende XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • Extiende 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, 15 de mayo de 2025 (Salar Khan)

    • Descripción inicial de la extensión