The Android XR SDK is now available in Developer Preview. We want your feedback! Visit our support page to reach out.

Cette page a été traduite par l'API Cloud Translation.

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

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)

L'extension XR_ANDROID_composition_layer_passthrough_mesh doit être activée avant d'utiliser XrSystemPassthroughLayerPropertiesANDROID.
type doit être XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID.
next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.

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)

L'extension XR_ANDROID_composition_layer_passthrough_mesh doit être activée avant d'utiliser XrCompositionLayerPassthroughANDROID.
type doit être XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID.
next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
layerFlags doit être 0 ou une combinaison valide de valeurs XrCompositionLayerFlagBits.
space doit être un gestionnaire XrSpace valide.
layer doit être un gestionnaire XrPassthroughLayerANDROID valide.
layer et space doivent avoir été créés, alloués ou récupérés à partir de la même XrSession.

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

session est une XrSession pour laquelle la couche de passthrough sera créée.
createInfo est un pointeur vers une structure XrPassthroughLayerCreateInfoANDROID spécifiant les paramètres initiaux de la couche de passthrough. Ce champ peut également être enchaîné à une structure XrPassthroughLayerMeshANDROID pour définir le maillage en même temps.
layer est un pointeur vers un handle dans lequel la XrPassthroughLayerANDROID créée est renvoyée.

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)

L'extension XR_ANDROID_composition_layer_passthrough_mesh doit être activée avant d'appeler xrCreatePassthroughLayerANDROID.
session doit être un identifiant XrSession valide.
createInfo doit être un pointeur vers une structure XrPassthroughLayerCreateInfoANDROID valide.
layer doit être un pointeur vers un gestionnaire XrPassthroughLayerANDROID.

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 elle n'est pas spécifiée. 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)

L'extension XR_ANDROID_composition_layer_passthrough_mesh doit être activée avant d'utiliser XrPassthroughLayerCreateInfoANDROID.
type doit être XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID.
next doit être NULL ou un pointeur valide vers la structure suivante d'une chaîne de structures. Voir également: XrPassthroughLayerMeshANDROID

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

layer est l'XrPassthroughLayerANDROID à détruire.

Utilisation valide (implicite)

L'extension XR_ANDROID_composition_layer_passthrough_mesh doit être activée avant d'appeler xrDestroyPassthroughLayerANDROID.
layer doit être un gestionnaire XrPassthroughLayerANDROID valide.

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

layer est un gestionnaire XrPassthroughLayerANDROID dans lequel effectuer la mise à jour avec l'mesh donné.
- mesh est un pointeur vers une structure XrPassthroughLayerMeshANDROID spécifiant les informations du maillage.

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)

L'extension XR_ANDROID_composition_layer_passthrough_mesh doit être activée avant d'appeler xrSetPassthroughLayerMeshANDROID.
layer doit être un gestionnaire XrPassthroughLayerANDROID valide.
mesh doit être un pointeur vers une structure XrPassthroughLayerMeshANDROID valide.

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 affiché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'extension XR_ANDROID_composition_layer_passthrough_mesh doit être activée avant d'utiliser XrPassthroughLayerMeshANDROID.
type doit être XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID.
next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
windingOrder doit être une valeur XrWindingOrderANDROID valide
Si vertexCount n'est pas 0, vertices, doit être un pointeur vers un tableau de structures vertexCount XrVector3f
Si indexCount n'est pas 0, indices, doit être un pointeur vers un tableau de valeurs indexCount uint16_t

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