XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

719

Revision

3

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

OpenXR 1.0

Datum der letzten Änderung

2025-05-15

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

Mitwirkende

Spencer Quin, Google
Jared Finder, Google
Antonio Fontan, Google
Cairn Overturf, Google
Nihav Jain, Google
Salar Khan, Google
Sebastian Klose, Google
Jürgen Sturm, Google
Vinny DaSilva, Google
Ricardo Campbell, Google

Übersicht

Diese Erweiterung soll Meshes bereitstellen, die die physischen Objekte in der Umgebung des Nutzers ungefähr darstellen.

Anwendungen können diese Erweiterung verwenden, um die Szene zu visualisieren und virtuelle Objekte mit physischen Objekten interagieren zu lassen, z. B. bei Kollisionen.

Die Daten des Szenen-Mesh werden von der Laufzeit generiert und über XrSceneMeshingTrackerANDROID und XrSceneMeshSnapshotANDROID mit der Anwendung geteilt. Anwendungen können auf die Werte in den Informationen zu Szenen-Submeshes über XrSceneSubmeshStateANDROID zugreifen, die von xrGetAllSubmeshStatesANDROID zurückgegeben werden. Anwendungen können auf die Werte in den Submesh-Daten der Szene über XrSceneSubmeshDataANDROID zugreifen, die von xrGetSubmeshDataANDROID zurückgegeben werden.

Daten zur Szenenvernetzung sind sensible personenbezogene Daten und eng mit dem Datenschutz und der Integrität verbunden. Es wird dringend empfohlen, dass Anwendungen, die Daten zur Szenenvernetzung speichern oder übertragen, den Nutzer immer um eine aktive und spezifische Zustimmung bitten.

Berechtigungen

Android-Apps müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING_FINE“ in ihrem Manifest enthalten. Die Berechtigung „android.permission.SCENE_UNDERSTANDING_FINE“ gilt als vertrauliche Berechtigung, da sie es der Laufzeit ermöglicht, die Nutzerumgebung zu analysieren.

Die Anwendung muss die Berechtigung zur Laufzeit anfordern, um diese Funktionen zu verwenden:

(Schutzebene: gefährlich)

Systemkapazität prüfen

Die Struktur XrSystemSceneMeshingPropertiesANDROID ist so definiert:

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • supportsSceneMeshing ist ein XrBool32, der angibt, ob das System Szenen-Meshing unterstützt.

Eine Anwendung kann prüfen, ob das System in der Lage ist, ein Szenen-Mesh zu erstellen, indem sie beim Aufruf von xrGetSystemProperties eine XrSystemSceneMeshingPropertiesANDROID-Struktur mit den XrSystemProperties verknüpft.

Wenn eine Laufzeit XR_FALSE für supportsSceneMeshing zurückgibt, unterstützt das System kein Szenen-Meshing und muss daher XR_ERROR_FEATURE_UNSUPPORTED von xrCreateSceneMeshingTrackerANDROID zurückgeben. Die Anwendung sollte die Verwendung der Szenen-Meshing-Funktion vermeiden, wenn supportsSceneMeshing den Wert XR_FALSE hat.

Wenn eine Laufzeit XR_TRUE für supportsSceneMeshing zurückgibt, unterstützt das System die Szenenvernetzung.

Gültige Verwendung (implizit)

Die Aufzählung XrSceneMeshSemanticLabelSetANDROID beschreibt die semantischen Label-Sets für das Szenen-Meshing. Jeder Wert in diesem Enum stellt ein anderes Enum dar, das die semantischen Labels enthält. Der Wert XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID steht beispielsweise für die Gruppe XrSceneMeshSemanticLabelANDROID .

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID = 1000801000,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

Die Aufzählungswerte haben die folgenden Bedeutungen:

Enum-Beschreibung

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Dieser Satz semantischer Labels steht für das Fehlen semantischer Labels.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

Diese semantische Labelgruppe stellt XrSceneMeshSemanticLabelANDROID dar.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

Diese semantischen Labels entsprechen XrSceneMeshSemanticLabel2ANDROID. (Hinzugefügt durch die Erweiterung „XR_ANDROID_scene_meshing_semantic_label2“)

Die Funktion xrEnumerateSupportedSemanticLabelSetsANDROID ist so definiert:

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

Parameterbeschreibungen

  • instance ist eine von der Anwendung erstellte XrInstance.
  • systemId ist ein XrSystemId, der von xrGetSystem wiederholt wird.
  • supportedSemanticLabelSetsInputCapacity ist die Kapazität von supportedSemanticLabelSets oder 0, um die erforderliche Kapazität abzurufen.
  • supportedSemanticLabelSetsOutputCount ist ein Zeiger auf die Anzahl der geschriebenen supportedSemanticLabelSets oder ein Zeiger auf die erforderliche Kapazität, falls supportedSemanticLabelSetsInputCapacity nicht ausreicht.
  • supportedSemanticLabelSets ist ein Zeiger auf ein Array von XrSceneMeshSemanticLabelSetANDROID . Er kann NULL sein, wenn supportedSemanticLabelSetsInputCapacity 0 ist.
  • Eine ausführliche Beschreibung zum Abrufen der erforderlichen supportedSemanticLabelSets-Größe finden Sie im Kapitel Parameter für die Puffergröße.

Die Anwendung kann die vom System unterstützten semantischen Labelsets mit der Funktion xrEnumerateSupportedSemanticLabelSetsANDROID auflisten.

Jedes System muss mindestens XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID unterstützen, da dieser Enum-Wert für keinen semantischen Labelsatz steht und verwendet werden kann, wenn die Anwendung keine Vertex-Semantik benötigt.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_scene_meshing muss aktiviert werden, bevor xrEnumerateSupportedSemanticLabelSetsANDROID aufgerufen wird.
  • instance muss ein gültiges XrInstance-Handle sein
  • supportedSemanticLabelSetsOutputCount muss ein Zeiger auf einen uint32_t-Wert sein
  • Wenn supportedSemanticLabelSetsInputCapacity nicht 0 ist, muss supportedSemanticLabelSets ein Zeiger auf ein Array von supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID-Werten sein.

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Handle für Szenen-Meshing-Tracker erstellen

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

Das Handle XrSceneMeshingTrackerANDROID stellt einen Scene-Meshing-Tracker für das Scene-Meshing und die Verwaltung der zugehörigen Ressourcen dar.

Dieses Handle kann verwendet werden, um mit xrCreateSceneMeshSnapshotANDROID in dieser Erweiterung einen Snapshot des Szenen-Meshs zu erstellen.

Die Funktion xrCreateSceneMeshingTrackerANDROID ist so definiert:

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

Parameterbeschreibungen

Eine Anwendung kann mit der Funktion xrCreateSceneMeshingTrackerANDROID ein XrSceneMeshingTrackerANDROID-Handle erstellen.

Wenn das System kein Szenen-Meshing unterstützt, muss die Laufzeit XR_ERROR_FEATURE_UNSUPPORTED von xrCreateSceneMeshingTrackerANDROID zurückgeben. In diesem Fall muss die Laufzeit XR_FALSE für XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing zurückgeben, wenn die Funktion xrGetSystemProperties aufgerufen wird, damit die Anwendung keinen Tracker für die Szenenvernetzung erstellen muss.

Die Anwendung darf beim Erstellen eines Scene Meshing Trackers nur die semantischen Label-Sets verwenden, die vom System in XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet unterstützt werden. Wenn die Anwendung einen nicht unterstützten Satz semantischer Labels für Szenennetz-Scheitelpunkte verwendet, muss die Laufzeit XR_ERROR_FEATURE_UNSUPPORTED von xrCreateSceneMeshingTrackerANDROID zurückgeben.

Die Anwendung kann die Liste der unterstützten semantischen Label-Sets mit der Funktion xrEnumerateSupportedSemanticLabelSetsANDROID aufzählen.

Das Handle xrCreateSceneMeshingTrackerANDROID besitzt alle Ressourcen für die Szenenvernetzung. Nachdem die Scene Meshing-Anwendung beendet wurde, muss das Handle über die Funktion xrDestroySceneMeshingTrackerANDROID gelöscht werden.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrSceneMeshingTrackerCreateInfoANDROID ist so definiert:

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • semanticLabelSet ist ein XrSceneMeshSemanticLabelSetANDROID, mit dem der Satz semantischer Labels angegeben wird, der für das Szenen-Meshing verwendet werden soll. Wenn dieser Wert auf XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID gesetzt ist, ignoriert die Laufzeit das Pufferfeld XrSceneSubmeshDataANDROID :: vertexSemantics.
  • enableNormals ist ein XrBool32, mit dem angegeben wird, ob beim Abrufen der Szenennetzdaten die Vertexnormalen für die Netzvertices im Szenennetz-Zwischenspeicher enthalten sein sollen.

Die Struktur XrSceneMeshingTrackerCreateInfoANDROID beschreibt die Informationen zum Erstellen eines XrSceneMeshingTrackerANDROID-Handles.

Gültige Verwendung (implizit)

Die Funktion xrDestroySceneMeshingTrackerANDROID ist so definiert:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Parameterbeschreibungen

Die Funktion xrDestroySceneMeshingTrackerANDROID gibt den tracker und die zugrunde liegenden Ressourcen frei, wenn die Scene-Meshing-Erfahrung beendet ist.

Gültige Verwendung (implizit)

Threadsicherheit

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

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Snapshot-Handle für Szenen-Mesh erstellen

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

Das XrSceneMeshSnapshotANDROID-Handle stellt einen Szenen-Mesh-Snapshot dar. Dieser Snapshot wird mit xrCreateSceneMeshSnapshotANDROID erstellt. Dabei wird ein Snapshot der Szenen-Mesh-Daten zum Zeitpunkt des Funktionsaufrufs erstellt.

Dieses Handle kann verwendet werden, um mit xrGetAllSubmeshStatesANDROID und xrGetSubmeshDataANDROID Informationen und Daten zu Submeshes abzurufen.

Die Funktion xrCreateSceneMeshSnapshotANDROID ist so definiert:

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

Parameterbeschreibungen

Die Anwendung kann die Funktion xrCreateSceneMeshSnapshotANDROID verwenden, um einen Szenen-Mesh-Snapshot aus dem Szenen-Mesh-Tracker zu erstellen. Diese Funktion gibt ein XrSceneMeshSnapshotANDROID-Handle zusammen mit XrSceneMeshTrackingStateANDROID zurück, verpackt in einer XrSceneMeshSnapshotCreationResultANDROID-Struktur. Das Handle ist technisch gesehen ein Snapshot der Szenen-Mesh-Daten zum Zeitpunkt der Erstellung. Dieses Handle kann verwendet werden, um die Informationen und Daten des Szenen-Mesh mit xrGetAllSubmeshStatesANDROID bzw. xrGetSubmeshDataANDROID abzufragen.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID

Die Struktur XrSceneMeshSnapshotCreateInfoANDROID ist so definiert:

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • baseSpace ist ein XrSpace, in dem die Pose-Informationen des Szenen-Submeshs dargestellt werden.
  • time ist der XrTime, der die Zeit beschreibt, zu der das Szenennetz verarbeitet oder angezeigt wird, normalerweise XrFrameState :: predictedDisplayTime .
  • boundingBox ist eine XrBoxf, die den Begrenzungsrahmen beschreibt, in dem das Szenen-Mesh erfasst werden soll.

Die Struktur XrSceneMeshSnapshotCreateInfoANDROID beschreibt die Informationen zum Erstellen eines XrSceneMeshSnapshotANDROID-Handles.

Gültige Verwendung (implizit)

Die Struktur XrSceneMeshSnapshotCreationResultANDROID ist so definiert:

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • snapshot ist ein von der Laufzeit erstelltes XrSceneMeshSnapshotANDROID-Handle.
  • trackingState ist ein XrSceneMeshTrackingStateANDROID, der den Status des Scene-Meshing-Trackers zum Zeitpunkt der Snapshot-Erstellung beschreibt.

In der Struktur XrSceneMeshSnapshotCreationResultANDROID wird das Ergebnis der Erstellung eines Szenen-Mesh-Snapshots gespeichert, das von xrCreateSceneMeshSnapshotANDROID zurückgegeben wird.

Gültige Verwendung (implizit)

Die Aufzählung XrSceneMeshTrackingStateANDROID beschreibt den Tracking-Status für einen Tracker für Szenen-Meshing. Jeder Wert in diesem Enum stellt einen Status des Scene Meshing-Trackers dar.

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

Die Aufzählungswerte haben die folgenden Bedeutungen:

Enum-Beschreibung

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

Der Tracker ist noch nicht bereit, Mesh-Daten bereitzustellen.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

Der Tracker zeichnet aktiv auf.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

Der Tracker wartet auf gültige Messungen, die seit der letzten Mesh-Aktualisierung integriert werden können.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

Der Tracker hat über mehrere Zyklen hinweg keine gültigen Messwerte erhalten und befindet sich in einem Fehlerstatus.

Dieser Status dient nur als zusätzliche Information für die Anwendung. Wenn keine anderen Fehlerquellen vorliegen, muss die Laufzeit der Anwendung weiterhin erlauben, Snapshots zu erstellen und Daten daraus abzurufen, unabhängig vom aktuellen XrSceneMeshTrackingStateANDROID des Trackers. Wenn der Status nicht XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID ist, sind die Snapshots möglicherweise nicht auf dem neuesten Stand oder leer.

Szenen-Mesh-Daten aus dem Szenen-Mesh-Snapshot abrufen

Die Funktion xrGetAllSubmeshStatesANDROID ist so definiert:

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

Parameterbeschreibungen

  • snapshot ist ein XrSceneMeshSnapshotANDROID-Handle, das zuvor mit xrCreateSceneMeshSnapshotANDROID erstellt wurde.
  • submeshStateCapacityInput ist die Kapazität von submeshStates oder 0, um die erforderliche Kapazität abzurufen.
  • submeshStateCountOutput ist ein Zeiger auf die Anzahl der geschriebenen submeshStates oder ein Zeiger auf die erforderliche Kapazität, falls submeshStateCapacityInput nicht ausreicht.
  • submeshStates ist ein Zeiger auf ein Array von XrSceneSubmeshStateANDROID-Strukturen, in die die Laufzeit den Status aller Submeshes im Szenen-Mesh ausgibt. Er kann NULL sein, wenn submeshStateCapacityInput 0 ist.
  • Eine ausführliche Beschreibung zum Abrufen der erforderlichen submeshStates-Größe finden Sie im Kapitel Parameter für die Puffergröße.

Die Anwendung kann die Funktion xrGetAllSubmeshStatesANDROID verwenden, um den Status aller Submeshes im Szenen-Mesh abzurufen. Diese enthält grundlegende Informationen, damit die Anwendung Submeshes auswählen kann, für die sie Daten benötigt.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_scene_meshing muss aktiviert sein, bevor xrGetAllSubmeshStatesANDROID aufgerufen wird.
  • snapshot muss ein gültiges XrSceneMeshSnapshotANDROID-Handle sein
  • submeshStateCountOutput muss ein Zeiger auf einen uint32_t-Wert sein
  • Wenn submeshStateCapacityInput nicht 0 ist, muss submeshStates ein Zeiger auf ein Array von submeshStateCapacityInput XrSceneSubmeshStateANDROID-Strukturen sein.

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrSceneSubmeshStateANDROID ist so definiert:

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • submeshId ist eine XrUuid, die das Submesh identifiziert.
  • lastUpdatedTime ist ein XrTime, der den Zeitpunkt der letzten Aktualisierung des Submesh angibt.
  • submeshPoseInBaseSpace ist ein XrPosef, das die Pose des Submesh im Basisraum darstellt, der zum Erstellen des Szenen-Mesh-Snapshots verwendet wurde. Die Pose ist auch der Mittelpunkt des Begrenzungsrahmens des Submeshs.
  • bounds ist ein XrExtent3Df, der die Abmessungen des Begrenzungsrahmens beschreibt, der das Submesh umschließt. Diese Grenzen werden im Basisbereich definiert, der zum Erstellen des Szenennetz-Handles verwendet wurde.

Die Laufzeit versucht, submeshId der Region des physischen Bereichs zuzuordnen, der vom Submesh belegt wird. Die Laufzeiten können diese Zuordnung jederzeit verlieren und einer beliebigen Teilmenge der erkannten Submeshes eine neue UUID zuweisen. Insbesondere müssen Laufzeiten nicht dieselben UUIDs für dieselben Meshes in nachfolgenden Anwendungsinstanzen wiederverwenden.

Gültige Verwendung (implizit)

Die Funktion xrGetSubmeshDataANDROID ist so definiert:

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

Parameterbeschreibungen

Die Anwendung kann die Funktion xrGetSubmeshDataANDROID verwenden, um Batches von Submeshes oder alle Submeshes auf einmal abzurufen. Dazu wird eine Liste von XrSceneSubmeshDataANDROID übergeben, wobei jede XrSceneSubmeshDataANDROID :: submeshId auf die entsprechende ID des abzurufenden Submeshs festgelegt ist.

Die XrSceneSubmeshDataANDROID :: submeshId muss für jedes Element in inoutSubmeshData eindeutig sein und über xrGetAllSubmeshStatesANDROID für dieselbe snapshot abrufbar sein. Wenn die Submesh-ID ungültig ist oder mehrere Elemente in inoutSubmeshData dieselbe Submesh-ID haben, muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.

submeshDataCount muss kleiner oder gleich dem von xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput zurückgegebenen Wert sein. Andernfalls muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.

Diese kann in einem 2-Aufruf-Idiom verwendet werden, um die Anzahl der Eckpunkte und Indizes für alle ausgewählten Submeshes abzufragen.

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrSceneSubmeshDataANDROID ist so definiert:

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • submeshId ist eine XrUuid, die das Submesh identifiziert.
  • vertexCapacityInput ist die Kapazität von vertexPositions , vertexNormals und vertexSemantics oder 0, um die erforderliche Kapazität abzurufen.
  • vertexCountOutput ist ein Zeiger auf die Anzahl der geschriebenen vertexPositions, vertexNormals und vertexSemantics oder ein Zeiger auf die erforderliche Kapazität, falls vertexCapacityInput nicht ausreicht.
  • vertexPositions ist ein Array von XrVector3f, in das die Laufzeit die Vertexpositionen des Submesh ausgibt.
  • vertexNormals ist ein Array von XrVector3f, in das die Laufzeit die Vertexnormalen des Submesh ausgibt. Dieses Feld kann NULL bleiben, wenn die Anwendung einen Tracker mit deaktivierten Normalen erstellt hat.
  • vertexSemantics ist ein Array von uint8_t, in das die Laufzeit die Vertex-Semantik des Submeshs ausgibt. Dieses Feld kann NULL bleiben, wenn die Anwendung einen Tracker mit dem semantischen Label XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID erstellt hat.
  • indexCapacityInput ist die Kapazität von indices oder 0, um die erforderliche Kapazität abzurufen.
  • indexCountOutput ist ein Zeiger auf die Anzahl der geschriebenen indices oder ein Zeiger auf die erforderliche Kapazität, falls vertexCapacityInput nicht ausreicht.
  • indices ist ein Array von uint32_t, in das die Laufzeit die Indexe des Submesh ausgibt.
  • Eine detaillierte Beschreibung zum Abrufen der erforderlichen Größe für vertexPositions, vertexNormals, vertexSemantics und indices finden Sie im Kapitel Parameter für die Puffergröße.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_scene_meshing muss aktiviert sein, bevor XrSceneSubmeshDataANDROID verwendet werden kann.
  • type muss XR_TYPE_SCENE_SUBMESH_DATA_ANDROID sein
  • next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
  • Wenn vertexCapacityInput nicht 0 ist, muss vertexPositions ein Zeiger auf ein Array von vertexCapacityInput XrVector3f-Strukturen sein.
  • Wenn vertexCapacityInput nicht 0 ist, muss vertexNormals ein Zeiger auf ein Array von vertexCapacityInput XrVector3f-Strukturen sein.
  • Wenn vertexCapacityInput nicht 0 ist, muss vertexSemantics ein Zeiger auf ein Array von vertexCapacityInput-uint8_t-Werten sein.
  • Wenn indexCapacityInput nicht 0 ist, muss indices ein Zeiger auf ein Array von indexCapacityInput-uint32_t-Werten sein.

Die Aufzählung XrSceneMeshSemanticLabelANDROID ist der Standardsatz semantischer Labels, die verwendet werden können, um Mesh-Eckpunkte zu kennzeichnen und zu beschreiben, auf welcher physischen Oberfläche sich der Mesh-Eckpunkt befindet. Dieser Enum-Satz wird durch den Wert XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID in XrSceneMeshSemanticLabelSetANDROID dargestellt.

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

Die Enums haben die folgenden Bedeutungen:

Enum-Beschreibung

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

Dieses semantische Label gibt an, dass das entsprechende Mesh-Element ein unbekanntes Objekt darstellt.

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

Dieses semantische Label gibt an, dass das entsprechende Mesh-Element einen Boden darstellt.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

Dieses semantische Label gibt an, dass das entsprechende Mesh-Element eine Decke darstellt.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

Dieses semantische Label gibt an, dass das entsprechende Mesh-Element eine Wand darstellt.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

Dieses semantische Label gibt an, dass das entsprechende Mesh-Element eine Tabelle darstellt.

Snapshot eines Szenen-Meshs löschen

Die Funktion xrDestroySceneMeshSnapshotANDROID ist so definiert:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Parameterbeschreibungen

Die Anwendung kann die Funktion xrDestroySceneMeshSnapshotANDROID verwenden, um einen Szenen-Mesh-Snapshot zu löschen. Sobald das Handle gelöscht wurde, kann die Anwendung es nicht mehr verwenden, um die Informationen oder Daten des Submesh abzurufen. Das Handle wird automatisch gelöscht, wenn der Tracker gelöscht wird, da das Tracker-Handle das übergeordnete Element des Scene Mesh-Snapshot-Handles ist.

Gültige Verwendung (implizit)

Threadsicherheit

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

Rückgabecodes

Erfolg

  • XR_SUCCESS

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Beispielcode für Szenen-Meshing

Der folgende Beispielcode zeigt, wie Sie auf Szenen-Mesh-Daten für das Rendering zugreifen.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup
XrSpace appPlaySpace; // Created at app startup

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

Neue Objekttypen

Neue Befehle

Neue Gebäude

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • Erweiterung von XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • Erweiterung von XrStructureType :

    • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
    • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
    • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
    • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

Probleme

Versionsverlauf

  • Version 3, 15.05.2025 (Salar Khan)

    • Anfängliche Beschreibung der Erweiterung