Estensione OpenXR XR_ANDROID_composition_layer_passthrough_mesh

Stringa del nome

XR_ANDROID_composition_layer_passthrough_mesh

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

463

Revisione

1

Dipendenze di estensioni e versioni

OpenXR 1.0

Data ultima modifica

2024-09-18

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

Grant Yoshida, Google

Kevin Moule, Google

Vasiliy Baranov, Google

Peter Chen, Google

Levana Chen, Google

Panoramica

Per i dispositivi che supportano più modalità di sfumatura dell'ambiente, il sistema può fornire configurazioni passthrough per mostrare all'utente il suo ambiente fisico da una visualizzazione immersiva.

Questa estensione consente alle applicazioni di proiettare texture passthrough su geometrie arbitrarie tramite un livello di composizione aggiuntivo XrCompositionLayerPassthroughANDROID.

Le caratteristiche del livello passthrough sono specificate dai seguenti parametri, in cui la proiezione è rappresentata da XrPassthroughLayerANDROID.

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

Per il passthrough a schermo intero, le applicazioni possono utilizzare la modalità di miscela dell'ambiente.

Controlla la funzionalità del sistema

Un'applicazione può verificare se il sistema è in grado di comporre un mesh di passaggio dei livelli collegando una struttura XrSystemPassthroughLayerPropertiesANDROID a XrSystemProperties quando chiama xrGetSystemProperties.

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • supportsPassthroughLayer è un XrBool32 che indica se il sistema corrente supporta il mesh di passaggio del livello di composizione.
  • maxMeshIndexCount è un uint32_t che restituisce il numero massimo di indici che verranno accettati per una mesh passthrough.
  • maxMeshVertexCount è un uint32_t che restituisce il numero massimo di vertici che verranno accettati per una mesh passthrough.

Se supportsPassthroughLayer restituisce XR_FALSE, il sistema non supporta il mesh passthrough del livello di composizione e, di conseguenza, riceverà XR_ERROR_FEATURE_UNSUPPORTED da xrCreatePassthroughLayerANDROID. L'applicazione deve evitare di utilizzare la mesh di trasmissione del livello di composizione quando supportsPassthroughLayer è XR_FALSE.

Se supportsPassthroughLayer restituisce XR_TRUE, il sistema supporta il mesh di trasmissione del livello di composizione. In questo caso, maxMeshIndexCount e maxMeshVertexCount restituiranno un numero diverso da zero. Un'applicazione deve utilizzare maxMeshIndexCount e maxMeshVertexCount come valori massimi per impostare i mesh di transizione quando chiama xrCreatePassthroughLayerANDROID e xrSetPassthroughLayerMeshANDROID, altrimenti potrebbe essere restituito XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID per indicare che i dati del mesh superano il limite supportato.

Utilizzo valido (implicito)

Composizione livello passthrough

XrCompositionLayerPassthroughANDROID contiene le informazioni necessarie per eseguire il rendering di una texture passthrough su una mesh triangolare quando viene chiamata xrEndFrame. XrCompositionLayerPassthroughANDROID è un tipo di alias per la struttura di base XrCompositionLayerBaseHeader utilizzata in XrFrameEndInfo.

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Queste strutture non sono definite in OpenXR di base o in questa estensione.
  • layerFlags è una maschera di bit di XrCompositionLayerFlags che descrive i flag da applicare al livello.
  • space è lo spazio Xr in cui viene valutato il pose della mesh del livello nel tempo.
  • pose è un XrPosef che definisce la posizione e l'orientamento della maglia del livello nel sistema di riferimento del space.
  • scale è un XrVector3f che definisce la scala della mesh del livello.
  • opacity è un float che definisce l'opacità della texture di translucenza nell'intervallo [0, 1].
  • layer è l'XrPassthroughLayerANDROID creato in precedenza da xrCreatePassthroughLayerANDROID.

L'applicazione può creare una struttura XrCompositionLayerPassthroughANDROID con il layer creato e i mesh corrispondenti forniti da XrPassthroughLayerMeshANDROID.

Un puntatore a XrCompositionLayerPassthroughANDROID può essere inviato in xrEndFrame come puntatore alla struttura di base XrCompositionLayerBaseHeader, nell'ordine dei livelli scelto, per richiedere al runtime di comporre un livello passthrough nell'output del frame finale.

Utilizzo valido (implicito)

Creare un handle del livello passthrough

Il handle XrPassthroughLayerANDROID rappresenta un livello passthrough che definisce il comportamento di XrCompositionLayerPassthroughANDROID.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

Un'applicazione può creare un handle XrPassthroughLayerANDROID chiamando xrCreatePassthroughLayerANDROID. L'handle XrPassthroughLayerANDROID restituito può essere utilizzato successivamente nelle chiamate API. 

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

Descrizioni dei parametri

L'applicazione deve specificare il numero di indici del mesh passthrough in XrPassthroughLayerCreateInfoANDROID::vertexCapacity e XrPassthroughLayerCreateInfoANDROID::indexCapacity inferiore o uguale ai valori massimi restituiti da XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount e XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount quando viene chiamata xrGetSystemProperties. xrCreatePassthroughLayerANDROID restituirà un errore XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID se il conteggio degli indici del mesh definito dacreateInfo è maggiore dei valori massimi.

L'handle XrPassthroughLayerANDROID deve essere eventualmente liberato utilizzando la funzione xrDestroyPassthroughLayerANDROID.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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 struttura XrPassthroughLayerCreateInfoANDROID è definita come: 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. XrPassthroughLayerMeshANDROID può essere fornito nella catena successiva per specificare un mesh iniziale per il livello di trasparenza quando viene chiamata la funzione xrCreatePassthroughLayerANDROID.
  • vertexCapacity è un uint32_t che rappresenta la capacità massima del buffer di vertici per la mesh di questo livello oppure 0 se non specificato. Se specificato, XrPassthroughLayerMeshANDROID::vertexCount di qualsiasi mesh impostato per questo livello deve essere inferiore o uguale a vertexCapacity.
  • indexCapacity è un uint32_t che rappresenta la capacità massima del buffer di indice per la mesh di questo livello o 0 se non specificato. Se specificato, il valore XrPassthroughLayerMeshANDROID::indexCount di qualsiasi mesh impostato per questo livello deve essere inferiore o uguale a indexCapacity.

Utilizzo valido (implicito)

Un'applicazione può utilizzare la funzione xrDestroyPassthroughLayerANDROID per liberare il livello passthrough e le risorse sottostanti.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Descrizioni dei parametri

Utilizzo valido (implicito)

Coerenza di thread

  • L'accesso a layer e a eventuali handle secondari deve essere sincronizzato esternamente

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

Imposta il mesh del livello di passthrough

Un'applicazione può utilizzare la funzione xrSetPassthroughLayerMeshANDROID per impostare la mesh per un livello di trasmissione.

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

Descrizioni dei parametri

L'applicazione deve specificare il numero di indici del mesh passthrough in XrPassthroughLayerMeshANDROID::vertexCount e XrPassthroughLayerMeshANDROID::indexCount inferiore o uguale ai valori massimi restituiti da XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount e XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount quando viene chiamata xrGetSystemProperties. Se il numero di indici del mesh specificato da mesh in xrSetPassthroughLayerMeshANDROID è maggiore dei valori massimi, verrà restituito XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID.

Se la capacità del buffer del mesh è specificata da XrPassthroughLayerCreateInfoANDROID::vertexCapacity e XrPassthroughLayerCreateInfoANDROID::indexCapacity durante la creazione del layer utilizzando xrCreatePassthroughLayerANDROID, verrà restituito l'errore XR_ERROR_SIZE_INSUFFICIENT su xrSetPassthroughLayerMeshANDROID se il numero di indici del mesh definiti da mesh è maggiore della capacità.

Utilizzo valido (implicito)

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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 struttura XrPassthroughLayerMeshANDROID è definita come: 

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • windingOrder è l'attributo XrWindingOrderANDROID dei triangoli della mesh, che verrà utilizzato per il culling della faccia posteriore durante il rendering della mesh.
  • vertexCount è un uint32_t che rappresenta il numero di vertici nel mesh. Quando viene specificato XrPassthroughLayerCreateInfoANDROID::vertexCapacity, vertexCount deve essere inferiore o uguale a vertexCapacity.
    • vertices è un puntatore a un array di XrVector3f che contiene le posizioni dei vertici del mesh triangolare.
  • indexCount è un uint32_t che rappresenta il numero di indici nel triangulo mesh. Gli ultimi indexCount % 3 indici, se presenti, non verranno disegnati. Quando viene specificato XrPassthroughLayerCreateInfoANDROID::indexCapacity, indexCount deve essere inferiore o uguale a indexCapacity.
  • indices è un puntatore a un array di uint16_t che contiene gli indici della mesh triangolare.

Utilizzo valido (implicito)

L'enumerazione XrWindingOrderANDROID identifica l'ordine di orientamento dei triangoli di un mesh, utilizzato dal runtime per il culling della faccia posteriore durante il rendering del mesh del livello di passaggio. 

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

Descrizioni degli enumeranti

  • XR_WINDING_ORDER_UNKNOWN_ANDROID  — L'ordine di orientamento dei triangoli della maglia non è conosciuto.
  • XR_WINDING_ORDER_CW_ANDROID  — L'ordine di orientamento dei triangoli della mesh è in senso orario.
  • XR_WINDING_ORDER_CCW_ANDROID  — L'ordine di orientamento dei triangoli della maglia è antiorario.

Codice di esempio per la composizione del livello passthrough

Il seguente codice di esempio mostra come creare un livello passthrough e usarlo nel 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));

Nuovi tipi di oggetti

Nuove costanti enum

L'enumerazione XrObjectType è estesa con:

  • XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

L'enumerazione XrStructureType è stata estesa con:

  • 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'enumerazione XrResult è stata estesa con:

  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Nuovi enum

Nuove strutture

Nuove funzioni

Problemi

Cronologia delle versioni

  • Revisione 1, 11-09-2024 (Levana Chen)
    • Descrizione iniziale dell'estensione