Extension OpenXR XR_ANDROID_composition_layer_passthrough_mesh

Chaîne de nom

XR_ANDROID_composition_layer_passthrough_mesh

Type d'extension

Extension d'instance

Numéro d'extension enregistré

463

Révision

1

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2024-09-18

État de l'adresse IP

Aucune revendication d'adresse IP connue.

Contributeurs

Grant Yoshida, Google

Kevin Moule, Google

Vasiliy Baranov, Google

Peter Chen, Google

Levana Chen, Google

Présentation

Pour les appareils compatibles avec plusieurs modes de mélange d'environnement, le système peut fournir des configurations de passthrough pour montrer à l'utilisateur son environnement physique à partir d'une vue immersive.

Cette extension permet aux applications de projeter des textures de passthrough sur une géométrie arbitraire via une couche de composition supplémentaire XrCompositionLayerPassthroughANDROID.

Les caractéristiques de la couche de passthrough sont spécifiées par les paramètres suivants, dans lesquels la projection est représentée par XrPassthroughLayerANDROID.

  XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;

Pour le passthrough en plein écran, les applications peuvent utiliser le mode de mélange d'environnement.

Inspecter les fonctionnalités du système

Une application peut vérifier si le système est capable de créer un maillage de passthrough de couche de composition en enchainant une structure XrSystemPassthroughLayerPropertiesANDROID à la XrSystemProperties lors de l'appel de xrGetSystemProperties.

typedef struct XrSystemPassthroughLayerPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsPassthroughLayer;
    uint32_t           maxMeshIndexCount;
    uint32_t           maxMeshVertexCount;
} XrSystemPassthroughLayerPropertiesANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • supportsPassthroughLayer est un XrBool32, qui indique si le système actuel est compatible avec le maillage de passthrough de la couche de composition.
  • maxMeshIndexCount est un uint32_t qui renvoie le nombre maximal d'indices acceptés pour un maillage de passthrough.
  • maxMeshVertexCount est un uint32_t qui renvoie le nombre maximal de sommets acceptés pour un maillage de passthrough.

Si supportsPassthroughLayer renvoie XR_FALSE, le système n'est pas compatible avec le maillage de passthrough de la couche de composition et reçoit donc XR_ERROR_FEATURE_UNSUPPORTED à partir de xrCreatePassthroughLayerANDROID. L'application doit éviter d'utiliser le maillage de passthrough de la couche de composition lorsque supportsPassthroughLayer est XR_FALSE.

Si supportsPassthroughLayer renvoie XR_TRUE, le système prend en charge la mise en réseau de passthrough de la couche de composition. Dans ce cas, maxMeshIndexCount et maxMeshVertexCount renvoient un nombre non nul. Une application doit utiliser maxMeshIndexCount et maxMeshVertexCount comme valeurs maximales pour définir des maillages de passthrough lors de l'appel de xrCreatePassthroughLayerANDROID et de xrSetPassthroughLayerMeshANDROID. Sinon, XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID peut être renvoyé pour indiquer que les données de maillage dépassent la limite prise en charge.

Utilisation valide (implicite)

Composition de la couche de passthrough

XrCompositionLayerPassthroughANDROID contient les informations nécessaires pour afficher une texture de passthrough sur un maillage triangulaire lors de l'appel de xrEndFrame. XrCompositionLayerPassthroughANDROID est un type d'alias pour la struct de base XrCompositionLayerBaseHeader utilisée dans XrFrameEndInfo.

typedef struct XrCompositionLayerPassthroughANDROID {
    XrStructureType              type;
    const void*                  next;
    XrCompositionLayerFlags      layerFlags;
    XrSpace                      space;
    XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;
} XrCompositionLayerPassthroughANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures. Aucune de ces structures n'est définie dans OpenXR de base ni dans cette extension.
  • layerFlags est un masque de bits de XrCompositionLayerFlags décrivant les options à appliquer à la couche.
  • space est l'espace Xr dans lequel le pose du maillage de la couche est évalué au fil du temps.
  • pose est un XrPosef qui définit la position et l'orientation du maillage de la couche dans le repère de référence de space.
  • scale est un XrVector3f qui définit l'échelle du maillage de la couche.
  • opacity est un float qui définit l'opacité de la texture de transmission dans la plage [0, 1].
  • layer est la XrPassthroughLayerANDROID créée précédemment par xrCreatePassthroughLayerANDROID.

L'application peut créer une structure XrCompositionLayerPassthroughANDROID avec le layer créé et les maillages correspondants fournis par XrPassthroughLayerMeshANDROID.

Un pointeur vers XrCompositionLayerPassthroughANDROID peut être envoyé dans xrEndFrame en tant que pointeur vers la structure de base XrCompositionLayerBaseHeader, dans l'ordre de calque choisi, pour demander à l'environnement d'exécution de composer une couche de passthrough dans la sortie de frame finale.

Utilisation valide (implicite)

Créer un gestionnaire de couche de passthrough

La poignée XrPassthroughLayerANDROID représente une couche de passthrough qui définit le comportement de XrCompositionLayerPassthroughANDROID.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

Une application peut créer un gestionnaire XrPassthroughLayerANDROID en appelant xrCreatePassthroughLayerANDROID. Le handle XrPassthroughLayerANDROID renvoyé peut ensuite être utilisé dans les appels d'API. 

XrResult xrCreatePassthroughLayerANDROID(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoANDROID*  createInfo,
    XrPassthroughLayerANDROID*                  layer);

Descriptions des paramètres

L'application doit spécifier le nombre d'indices de maillage de passthrough dans XrPassthroughLayerCreateInfoANDROID::vertexCapacity et XrPassthroughLayerCreateInfoANDROID::indexCapacity inférieur ou égal aux valeurs maximales renvoyées par XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount et XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount lors de l'appel de xrGetSystemProperties. xrCreatePassthroughLayerANDROID renvoie une erreur XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID si le nombre d'indices de maillage défini par createInfo est supérieur aux valeurs maximales.

Le contrôleur XrPassthroughLayerANDROID doit être libéré à terme à l'aide de la fonction xrDestroyPassthroughLayerANDROID.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

La structure XrPassthroughLayerCreateInfoANDROID est définie comme suit: 

typedef struct XrPassthroughLayerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    uint32_t           vertexCapacity;
    uint32_t           indexCapacity;
} XrPassthroughLayerCreateInfoANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. XrPassthroughLayerMeshANDROID peut être fourni dans la chaîne suivante pour spécifier un maillage initial pour la couche de passthrough lors de l'appel de xrCreatePassthroughLayerANDROID.
  • vertexCapacity est un uint32_t représentant la capacité maximale du tampon de sommets pour le maillage de cette couche, ou 0 si non spécifié. Si vous spécifiez une valeur, le XrPassthroughLayerMeshANDROID::vertexCount de tout maillage défini pour cette couche doit être inférieur ou égal à vertexCapacity.
  • indexCapacity est un uint32_t représentant la capacité maximale du tampon d'index pour le maillage de cette couche, ou 0 si elle n'est pas spécifiée. Si vous spécifiez une valeur, l'XrPassthroughLayerMeshANDROID::indexCount de tout maillage défini pour cette couche doit être inférieur ou égal à indexCapacity.

Utilisation valide (implicite)

Une application peut utiliser la fonction xrDestroyPassthroughLayerANDROID pour libérer la couche de passthrough et les ressources sous-jacentes.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Descriptions des paramètres

Utilisation valide (implicite)

Sécurité des threads

  • L'accès à layer et à tous les gestionnaires enfants doit être synchronisé en externe.

Codes de retour

Réussite

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

Définir le maillage de la couche de passthrough

Une application peut utiliser la fonction xrSetPassthroughLayerMeshANDROID pour définir le maillage d'une couche de passthrough.

XrResult xrSetPassthroughLayerMeshANDROID(
    XrPassthroughLayerANDROID                   layer,
    const XrPassthroughLayerMeshANDROID*        mesh);

Descriptions des paramètres

L'application doit spécifier le nombre d'indices de maillage de passthrough dans les XrPassthroughLayerMeshANDROID::vertexCount et XrPassthroughLayerMeshANDROID::indexCount inférieur ou égal aux valeurs maximales renvoyées par XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount et XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount lors de l'appel de xrGetSystemProperties. Si le nombre d'indices de maillage donné par mesh à partir de xrSetPassthroughLayerMeshANDROID est supérieur aux valeurs maximales, XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID est renvoyé.

Si la capacité du tampon de maillage est spécifiée par XrPassthroughLayerCreateInfoANDROID::vertexCapacity et XrPassthroughLayerCreateInfoANDROID::indexCapacity lors de la création de layer à l'aide de xrCreatePassthroughLayerANDROID, l'erreur XR_ERROR_SIZE_INSUFFICIENT est renvoyée sur xrSetPassthroughLayerMeshANDROID si le nombre d'indices de maillage définis par mesh est supérieur à la capacité.

Utilisation valide (implicite)

Codes de retour

Réussite

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

La structure XrPassthroughLayerMeshANDROID est définie comme suit: 

typedef struct XrPassthroughLayerMeshANDROID {
    XrStructureType          type;
    const void*              next;
    XrWindingOrderANDROID    windingOrder;
    uint32_t                 vertexCount;
    const XrVector3f*        vertices;
    uint32_t                 indexCount;
    const uint16_t*          indices;
} XrPassthroughLayerMeshANDROID;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante d'une chaîne de structures.
  • windingOrder est le XrWindingOrderANDROID des triangles du maillage, qui sera utilisé pour le masquage des faces arrière lors du rendu du maillage.
  • vertexCount est un uint32_t représentant le nombre de sommets dans la maille. Lorsque XrPassthroughLayerCreateInfoANDROID::vertexCapacity est spécifié, vertexCount doit être inférieur ou égal à vertexCapacity.
    • vertices est un pointeur vers un tableau de XrVector3f qui contient les positions des sommets du maillage triangulaire.
  • indexCount est un uint32_t représentant le nombre d'indices dans le maillage triangulaire. Les derniers indices indexCount % 3, le cas échéant, ne seront pas dessinés. Lorsque XrPassthroughLayerCreateInfoANDROID::indexCapacity est spécifié, indexCount doit être inférieur ou égal à indexCapacity.
  • indices est un pointeur vers un tableau de uint16_t qui contient les indices du maillage triangulaire.

Utilisation valide (implicite)

L'énumération XrWindingOrderANDROID identifie l'ordre de balayage des triangles d'un maillage, utilisé par l'environnement d'exécution pour le masquage des faces arrière lors du rendu du maillage de la couche de passthrough. 

typedef enum XrWindingOrderANDROID {
    XR_WINDING_ORDER_UNKNOWN_ANDROID = 0,
    XR_WINDING_ORDER_CW_ANDROID = 1,
    XR_WINDING_ORDER_CCW_ANDROID = 2
} XrWindingOrderANDROID;

Descriptions des énumérateurs

  • XR_WINDING_ORDER_UNKNOWN_ANDROID : l'ordre de balayage des triangles du maillage n'est pas connu.
  • XR_WINDING_ORDER_CW_ANDROID : l'ordre de déroulement des triangles du maillage est dans le sens des aiguilles d'une montre.
  • XR_WINDING_ORDER_CCW_ANDROID : l'ordre de déroulement des triangles du maillage est dans le sens inverse des aiguilles d'une montre.

Exemple de code pour la composition de calques de passthrough

L'exemple de code suivant montre comment créer une couche de passthrough et l'utiliser dans le compositing.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace space; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreatePassthroughLayerANDROID xrCreatePassthroughLayerANDROID; // previously initialized
PFN_xrDestroyPassthroughLayerANDROID xrDestroyPassthroughLayerANDROID; // previously initialized
PFN_xrSetPassthroughLayerMeshANDROID xrSetPassthroughLayerMeshANDROID; // previously initialized

// Inspect passthrough mesh system properties
XrSystemPassthroughLayerPropertiesANDROID passthroughLayerSystemProperties{
  XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{
  XR_TYPE_SYSTEM_PROPERTIES, &passthroughLayerSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!passthroughLayerSystemProperties.supportsPassthroughLayer) {
    // the system does not support composite layer passthrough mesh.
    return;
}

// The initial mesh for the layer.
XrPassthroughLayerMeshANDROID mesh = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID,
  .windingOrder = XR_WINDING_ORDER_CW_ANDROID,
  .vertexCount = 4,
  .vertices = {
    { 0, 0, 0 }, { 0, 1, 0 }, { 1, 1, 0 }, { 1, 0, 0 }
  },
  .indexCount = 6,
  .indices = {
    0, 1, 2,
    0, 2, 3
  },
};

// Create the layer. Layers are expected to persist across frames.
XrPassthroughLayerCreateInfoANDROID create_info = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID,
  .next = &mesh,
  .vertexCapacity = 0,
  .indexCapacity = 0,
};
XrPassthroughLayerANDROID layer;
CHK_XR(xrCreatePassthroughLayerANDROID(session, &create_info, &layer));

// Create a composition layer. Composition layers are submitted per frame.
XrCompositionLayerPassthroughANDROID passthrough_layer = {
  .type = XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID,
  .next = nullptr,
  .layerFlags = 0,
  .space = space,
  .pose = {
    .orientation = { 0.0f, 0.0f, 0.0f, 1.0f }
    .position = { 0.0f, 0.0f, 0.0f }
  },
  .scale = { 1.0f, 1.0f, 1.0f },
  .opacity = 1.0f,
  .layer = layer
};

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    // Submit composition layer in xrEndFrame.
    std::vector<XrCompositionLayerBaseHeader*> layers = {
        ...,
        &passthrough_layer,
        ...,
    };
    XrFrameEndInfo end_frame_info = { XR_TYPE_FRAME_END_INFO, nullptr };
    end_frame_info.layerCount = (uint32_t)layers.size();
    end_frame_info.layers = layers.data();
    CHK_XR(xrEndFrame(session, &end_frame_info));

    // Update the layer. Results can be seen the next time a passthrough composition
    // layer is submitted.
    mesh.indexCount = 9;
    const uint16_t new_index_buffer[] = {
        0, 1, 2,
        0, 2, 3,
        0, 1, 2
    };
    mesh.indexBuffer = &new_index_buffer[0];
    CHK_XR(xrSetPassthroughLayerMeshANDROID(&layer, &mesh));

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

// Clean up.
CHK_XR(xrDestroyPassthroughLayerANDROID(layer));

Nouveaux types d'objets

Nouvelles constantes d'énumération

L'énumération XrObjectType est étendue avec:

  • XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

L'énumération XrStructureType est étendue avec:

  • XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
  • XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
  • XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
  • XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID

L'énumération XrResult est étendue avec:

  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Nouvelles énumérations

Nouvelles structures

Nouvelles fonctions

Problèmes

Historique des versions

  • Révision 1, 11/09/2024 (Levana Chen)
    • Description initiale de l'extension

OpenXR™ et le logo OpenXR sont des marques appartenant à The Khronos Group Inc. et sont enregistrés en tant que marques en Chine, dans l'Union européenne, au Japon et au Royaume-Uni.