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

Diese Seite wurde von der Cloud Translation API übersetzt.

OpenXR-Erweiterung „XR_ANDROID_composition_layer_passthrough_mesh“

Namensstring

XR_ANDROID_composition_layer_passthrough_mesh

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

463

Revision

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, wobei 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 beim Aufruf von xrGetSystemProperties eine XrSystemPassthroughLayerPropertiesANDROID-Struktur an die XrSystemProperties angehängt wird.

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 Komposition. 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)

Die Erweiterung XR_ANDROID_composition_layer_passthrough_mesh muss aktiviert sein, bevor XrSystemPassthroughLayerPropertiesANDROID verwendet werden kann.
type muss XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID sein.
next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.

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 Transparenz-Textur 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)

Die Erweiterung XR_ANDROID_composition_layer_passthrough_mesh muss aktiviert sein, bevor XrCompositionLayerPassthroughANDROID verwendet werden kann.
type muss XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID sein.
next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
layerFlags muss 0 oder eine gültige Kombination von XrCompositionLayerFlagBits-Werten sein
space muss ein gültiger XrSpace-Handle sein
layer muss ein gültiger XrPassthroughLayerANDROID-Handle sein
Sowohl layer als auch space müssen in derselben XrSession erstellt, zugewiesen oder abgerufen worden sein.

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

session ist eine XrSession, für die die Passthrough-Ebene erstellt wird.
createInfo ist ein Verweis auf eine XrPassthroughLayerCreateInfoANDROID-Struktur, die die anfänglichen Parameter der Passthrough-Ebene angibt. Dieses Feld kann auch an eine XrPassthroughLayerMeshANDROID-Struktur angehängt werden, um das Mesh gleichzeitig festzulegen.
layer ist ein Verweis auf einen Handle, über den die erstellte XrPassthroughLayerANDROID zurückgegeben wird.

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)

Die Erweiterung XR_ANDROID_composition_layer_passthrough_mesh muss aktiviert sein, bevor xrCreatePassthroughLayerANDROID aufgerufen wird.
session muss ein gültiger XrSession-Alias sein.
createInfo muss ein Verweis auf eine gültige XrPassthroughLayerCreateInfoANDROID-Struktur sein.
layer muss ein Verweis auf einen XrPassthroughLayerANDROID-Handle sein.

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)

Die XR_ANDROID_composition_layer_passthrough_mesh-Erweiterung muss aktiviert sein, bevor XrPassthroughLayerCreateInfoANDROID verwendet werden kann.
type muss XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID sein.
next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. Weitere Informationen finden Sie unter XrPassthroughLayerMeshANDROID.

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

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Parameterbeschreibungen

layer ist die zu löschende XrPassthroughLayerANDROID.

Gültige Verwendung (implizit)

Die Erweiterung XR_ANDROID_composition_layer_passthrough_mesh muss aktiviert sein, bevor xrDestroyPassthroughLayerANDROID aufgerufen wird.
layer muss ein gültiger XrPassthroughLayerANDROID-Handle sein.

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

layer ist ein XrPassthroughLayerANDROID-Handle, der mit der angegebenen mesh aktualisiert werden soll.
- mesh ist ein Verweis auf eine XrPassthroughLayerMeshANDROID-Struktur, die die Informationen zum Mesh angibt.

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)

Die XR_ANDROID_composition_layer_passthrough_mesh-Erweiterung muss aktiviert sein, bevor xrSetPassthroughLayerMeshANDROID aufgerufen wird.
layer muss ein gültiger XrPassthroughLayerANDROID-Handle sein
mesh muss ein Verweis auf eine gültige XrPassthroughLayerMeshANDROID-Struktur sein.

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 Erweiterung XR_ANDROID_composition_layer_passthrough_mesh muss aktiviert sein, bevor XrPassthroughLayerMeshANDROID verwendet werden kann.
type muss XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID sein.
next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
windingOrder muss ein gültiger Wert für XrWindingOrderANDROID sein
Wenn vertexCount nicht 0, vertices ist, muss es sich um einen Verweis auf ein Array von vertexCount XrVector3f-Strukturen handeln.
Wenn indexCount nicht 0, indices ist, muss es ein Verweis auf ein Array von indexCount uint16_t-Werten sein.

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 Durchlaufebene 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 Komposition einer Durchlassebene

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