OpenXR-Erweiterung „XR_ANDROID_composition_layer_passthrough_mesh“

Namensstring

XR_ANDROID_composition_layer_passthrough_mesh

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

463

Revision

1

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Datum der letzten Änderung

2024-09-18

IP-Status

Es sind keine Ansprüche aufgrund von Urheberrechten bekannt.

Mitwirkende

Grant Yoshida, Google

Kevin Moule, Google

Vasiliy Baranov, Google

Peter Chen, Google

Levana Chen, Google

Übersicht

Bei Geräten, die mehrere Umgebungsmischungsmodi unterstützen, kann das System Passthrough-Konfigurationen bereitstellen, um Nutzern ihre physische Umgebung in einer immersiven Ansicht zu zeigen.

Mit dieser Erweiterung können Anwendungen Passthrough-Texturen über eine zusätzliche Kompositionierungsebene XrCompositionLayerPassthroughANDROID auf beliebige Geometrie projizieren.

Die Eigenschaften der Passthrough-Ebene werden durch die folgenden Parameter angegeben, in denen die Projektion durch XrPassthroughLayerANDROID dargestellt wird.

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

Für die Vollbildweiterleitung können Anwendungen den Umgebungsblendmodus verwenden.

Systemkapazität prüfen

Eine Anwendung kann prüfen, ob das System ein Passthrough-Mesh für die Kompositionebene unterstützt, indem sie beim Aufruf von xrGetSystemProperties eine XrSystemPassthroughLayerPropertiesANDROID-Struktur an die XrSystemProperties-Struktur anhängt.

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

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • supportsPassthroughLayer ist ein XrBool32, das angibt, ob das aktuelle System das Passthrough-Mesh der Kompositionslagen unterstützt.
  • maxMeshIndexCount ist ein uint32_t gibt die maximale Anzahl von Indizes zurück, die für ein Passthrough-Mesh akzeptiert werden.
  • maxMeshVertexCount ist ein uint32_t gibt die maximale Anzahl von Spitzen zurück, die für ein Passthrough-Mesh akzeptiert werden.

Wenn supportsPassthroughLayer XR_FALSE zurückgibt, unterstützt das System kein Passthrough-Mesh für die Kompositionebene und erhält daher XR_ERROR_FEATURE_UNSUPPORTED von xrCreatePassthroughLayerANDROID. In der Anwendung sollte kein Passthrough-Mesh für die Kompositionslagen verwendet werden, wenn supportsPassthroughLayer = XR_FALSE ist.

Wenn supportsPassthroughLayer XR_TRUE zurückgibt, unterstützt das System das Passthrough-Mesh der Kompositionebene. In diesem Fall geben maxMeshIndexCount und maxMeshVertexCount eine positive Zahl zurück. Eine Anwendung sollte maxMeshIndexCount und maxMeshVertexCount als maximale Werte verwenden, um Passthrough-Meshes beim Aufrufen von xrCreatePassthroughLayerANDROID und xrSetPassthroughLayerMeshANDROID festzulegen. Andernfalls wird möglicherweise XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID zurückgegeben, um anzugeben, dass die Mesh-Daten das unterstützte Limit überschreiten.

Gültige Verwendung (implizit)

Zusammensetzung der Passthrough-Ebene

XrCompositionLayerPassthroughANDROID enthält die Informationen, die zum Rendern einer Passthrough-Textur auf einem Dreiecksnetz beim Aufrufen von xrEndFrame erforderlich sind. XrCompositionLayerPassthroughANDROID ist ein Aliastyp für die Basisstruktur XrCompositionLayerBaseHeader, die in XrFrameEndInfo verwendet wird.

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

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR oder dieser Erweiterung nicht definiert.
  • layerFlags ist eine Bitmaske von XrCompositionLayerFlags, die Flags beschreibt, die auf die Ebene angewendet werden sollen.
  • space ist der XrSpace, in dem die pose des Ebenen-Meshes im Zeitverlauf ausgewertet wird.
  • pose ist ein XrPosef, das die Position und Ausrichtung des Ebenen-Mesh im Referenzrahmen der space definiert.
  • scale ist eine XrVector3f, die den Maßstab des Ebenen-Meshes definiert.
  • opacity ist eine float, die die Deckkraft der Transparenttextur im Bereich [0, 1] definiert.
  • layer ist die XrPassthroughLayerANDROID, die zuvor mit xrCreatePassthroughLayerANDROID erstellt wurde.

Die Anwendung kann eine XrCompositionLayerPassthroughANDROID-Struktur mit der erstellten layer und den entsprechenden Meshes von XrPassthroughLayerMeshANDROID erstellen.

Ein Verweis auf XrCompositionLayerPassthroughANDROID kann in xrEndFrame als Verweis auf die Basisstruktur XrCompositionLayerBaseHeader in der ausgewählten Ebenenreihenfolge gesendet werden, um die Runtime aufzufordern, eine Passthrough-Ebene in die endgültige Frame-Ausgabe einzufügen.

Gültige Verwendung (implizit)

Passthrough-Ebenen-Handle erstellen

Der Handle XrPassthroughLayerANDROID stellt eine Passthrough-Ebene dar, die das Verhalten von XrCompositionLayerPassthroughANDROID definiert.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

Eine Anwendung kann einen XrPassthroughLayerANDROID-Handle erstellen, indem sie xrCreatePassthroughLayerANDROID aufruft. Der zurückgegebene XrPassthroughLayerANDROID-Handle kann anschließend in API-Aufrufen verwendet werden. 

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

Parameterbeschreibungen

Die Anwendung muss die Anzahl der Passthrough-Mesh-Indexe in den XrPassthroughLayerCreateInfoANDROID::vertexCapacity und XrPassthroughLayerCreateInfoANDROID::indexCapacity kleiner oder gleich den Maximalwerten angeben, die von XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount und XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount beim Aufruf von xrGetSystemProperties zurückgegeben werden. xrCreatePassthroughLayerANDROID gibt einen XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID-Fehler zurück, wenn die Anzahl der von createInfo definierten Mesh-Indexe größer als die Maximalwerte ist.

Der Handle XrPassthroughLayerANDROID muss schließlich mit der Funktion xrDestroyPassthroughLayerANDROID freigegeben werden.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur XrPassthroughLayerCreateInfoANDROID ist so definiert: 

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

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. XrPassthroughLayerMeshANDROID kann in der nächsten Kette angegeben werden, um beim Aufruf von xrCreatePassthroughLayerANDROID ein Anfangs-Mesh für die Passthrough-Ebene anzugeben.
  • vertexCapacity ist ein uint32_t, das die maximale Kapazität des Vertex-Buffers für das Mesh dieser Ebene darstellt. Wenn nichts angegeben ist, ist es 0. Falls angegeben, muss XrPassthroughLayerMeshANDROID::vertexCount jedes Mesh, das für diese Ebene festgelegt ist, kleiner oder gleich vertexCapacity sein.
  • indexCapacity ist ein uint32_t, das die maximale Kapazität des Indexpuffers für das Mesh dieser Ebene darstellt, oder 0, wenn nicht angegeben. Falls angegeben, muss XrPassthroughLayerMeshANDROID::indexCount eines für diese Ebene festgelegten Mesh kleiner oder gleich indexCapacity sein.

Gültige Verwendung (implizit)

Eine Anwendung kann die Funktion xrDestroyPassthroughLayerANDROID verwenden, um die Durchlaufebene und die zugrunde liegenden Ressourcen freizugeben.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Parameterbeschreibungen

Gültige Verwendung (implizit)

Threadsicherheit

  • Der Zugriff auf layer und alle untergeordneten Handles muss extern synchronisiert werden.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

Mesh für die Passthrough-Ebene festlegen

Eine Anwendung kann die Funktion xrSetPassthroughLayerMeshANDROID verwenden, um das Mesh für eine standortunabhängige Ebene festzulegen.

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

Parameterbeschreibungen

Die Anwendung muss die Anzahl der Passthrough-Mesh-Indexe in den Variablen XrPassthroughLayerMeshANDROID::vertexCount und XrPassthroughLayerMeshANDROID::indexCount so angeben, dass sie kleiner oder gleich den Maximalwerten ist, die von XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount und XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount beim Aufruf von xrGetSystemProperties zurückgegeben werden. Wenn die Anzahl der Mesh-Indexe, die durch mesh von xrSetPassthroughLayerMeshANDROID angegeben wird, größer als die maximalen Werte ist, wird XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID zurückgegeben.

Wenn die Mesh-Bufferkapazität durch XrPassthroughLayerCreateInfoANDROID::vertexCapacity und XrPassthroughLayerCreateInfoANDROID::indexCapacity beim Erstellen der layer mit xrCreatePassthroughLayerANDROID angegeben wird, wird bei xrSetPassthroughLayerMeshANDROID der Fehler XR_ERROR_SIZE_INSUFFICIENT zurückgegeben, wenn die Anzahl der von mesh definierten Mesh-Indexe größer als die Kapazität ist.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur XrPassthroughLayerMeshANDROID ist so definiert: 

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

Beschreibungen von Mitgliedern

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • windingOrder ist die XrWindingOrderANDROID der Mesh-Dreiecke, die beim Rendern des Mesh für das Culling von Rückseiten verwendet wird.
  • vertexCount ist eine uint32_t, die die Anzahl der Eckpunkte im Mesh angibt. Wenn XrPassthroughLayerCreateInfoANDROID::vertexCapacity angegeben ist, muss vertexCount kleiner oder gleich vertexCapacity sein.
    • vertices ist ein Verweis auf ein Array von XrVector3f, das die Knotenpositionen des Dreiecksnetzes enthält.
  • indexCount ist eine uint32_t, die die Anzahl der Indizes im Dreiecksnetz angibt. Die letzten indexCount % 3 Indexe (falls vorhanden) werden nicht dargestellt. Wenn XrPassthroughLayerCreateInfoANDROID::indexCapacity angegeben ist, muss indexCount kleiner oder gleich indexCapacity sein.
  • indices ist ein Verweis auf ein Array von uint16_t, das die Indizes des Dreiecksnetzes enthält.

Gültige Verwendung (implizit)

Die Aufzählung XrWindingOrderANDROID gibt die Windungsreihenfolge der Dreiecke eines Mesh an, die von der Laufzeit für das Backface-Culling beim Rendern des Mesh der Durchlassebene verwendet wird. 

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

Beschreibungen der Aufzählungen

  • XR_WINDING_ORDER_UNKNOWN_ANDROID – Die Windungsreihenfolge der Dreiecke des Netzes ist nicht bekannt.
  • XR_WINDING_ORDER_CW_ANDROID – Die Windungsreihenfolge der Dreiecke des Netzes verläuft im Uhrzeigersinn.
  • XR_WINDING_ORDER_CCW_ANDROID – Die Windungsreihenfolge der Dreiecke des Netzes verläuft gegen den Uhrzeigersinn.

Beispielcode für die Zusammensetzung von Durchlassebenen

Im folgenden Beispielcode wird gezeigt, wie du eine Durchlaufebene erstellst und sie beim Compositing verwendest.

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

Neue Objekttypen

Neue Enum-Konstanten

Die Aufzählung XrObjectType wurde um Folgendes erweitert:

  • XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

Die Aufzählung XrStructureType wurde um folgende Elemente erweitert:

  • 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

Die Aufzählung XrResult wurde um Folgendes erweitert:

  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Neue Enums

Neue Strukturen

Neue Funktionen

Probleme

Versionsverlauf

  • Revision 1, 2024-09-11 (Levana Chen)
    • Erste Beschreibung der Erweiterung

OpenXR™ und das OpenXR-Logo sind Marken der Khronos Group Inc. und sind als Marke in China, der Europäischen Union, Japan und dem Vereinigten Königreich eingetragen.