XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

719

Revision

3

Ratification Status (Status der Ratifizierung)

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

OpenXR 1.0

Datum der letzten Änderung

2025-05-15

IP-Status

Es sind keine Ansprüche wegen geistigen Eigentums bekannt.

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. durch Kollisionen.

Die Daten für das Szenen-Mesh werden von der Laufzeit generiert und über XrSceneMeshingTrackerANDROID und XrSceneMeshSnapshotANDROID für die Anwendung freigegeben . Anwendungen können über XrSceneSubmeshStateANDROID, das von xrGetAllSubmeshStatesANDROID zurückgegeben wird, auf die Werte in den Informationen zu den Unterteilungen der Szene zugreifen . Anwendungen können über XrSceneSubmeshDataANDROID, das von xrGetSubmeshDataANDROID zurückgegeben wird, auf die Werte in den Untermesh-Daten der Szene zugreifen .

Daten zum Erstellen von 3D-Modellen von Szenen sind sensible personenbezogene Daten und eng mit der Privatsphäre und Integrität von Personen verknüpft. Es wird dringend empfohlen, dass Anwendungen, die Daten zum Erstellen von 3D-Modellen speichern oder übertragen, den Nutzer immer um eine aktive und spezifische Zustimmung bitten.

Berechtigungen

Android-Anwendungen müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING_FINE“ in ihrem Manifest aufführen. Die Berechtigung „android.permission.SCENE_UNDERSTANDING_FINE“ gilt als vertrauliche Berechtigung, da die Laufzeit damit die Nutzerumgebung analysieren kann.

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

(Schutzebene: gefährlich)

Systemfunktionen 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 in OpenXR oder dieser Erweiterung nicht definiert.
  • supportsSceneMeshing ist ein XrBool32, das angibt, ob das System das Zusammenfügen von Szenen unterstützt.

Eine Anwendung kann prüfen, ob das System in der Lage ist, Szenen zu erstellen, indem sie beim Aufrufen von xrGetSystemProperties eine XrSystemSceneMeshingPropertiesANDROID-Struktur an die XrSystemProperties anhängt .

Wenn eine Laufzeit XR_FALSE für supportsSceneMeshing zurückgibt, unterstützt das System kein Scene Meshing. Daher muss XR_ERROR_FEATURE_UNSUPPORTED von xrCreateSceneMeshingTrackerANDROID zurückgegeben werden. Die Anwendung sollte die Funktion für das Erstellen von Szenen-Meshes vermeiden, wenn supportsSceneMeshing XR_FALSE ist .

Wenn eine Laufzeit XR_TRUE für supportsSceneMeshing zurückgibt , unterstützt das System das Erstellen von Szenen-Meshes.

Gültige Nutzung (implizit)

Die Enumeration XrSceneMeshSemanticLabelSetANDROID beschreibt die semantischen Labelsätze für das Erstellen von Szenen-Meshes. 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 Menge 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_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

Die Aufzählungswerte haben die folgenden Bedeutungen:

Enum-Beschreibung

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Dieser Satz von semantischen Labels steht für das Fehlen von semantischen Labels.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

Diese semantische Labelgruppe steht für XrSceneMeshSemanticLabelANDROID.

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, das 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 . Kann NULL sein, wenn supportedSemanticLabelSetsInputCapacity = 0.
  • Eine ausführliche Beschreibung zum Abrufen der erforderlichen supportedSemanticLabelSets-Größe finden Sie im Kapitel Puffergrößenparameter.

Die Anwendung kann semantische Labelsätze, die vom System unterstützt werden, mit der Funktion xrEnumerateSupportedSemanticLabelSetsANDROID auflisten.

Jedes System muss mindestens XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID unterstützen, da dieser Enum-Wert kein semantisches Labelset darstellt und verwendet werden kann, wenn die Anwendung keine Vertex-Semantik benötigt.

Gültige Nutzung (implizit)

  •  Die XR_ANDROID_scene_meshing-Erweiterung muss aktiviert werden, bevor xrEnumerateSupportedSemanticLabelSetsANDROID aufgerufen wird.
  • instance muss ein gültiger XrInstance-Handle sein.
  • supportedSemanticLabelSetsOutputCount muss ein Zeiger auf einen uint32_t-Wert sein.
  • : Wenn supportedSemanticLabelSetsInputCapacity nicht 0 ist , supportedSemanticLabelSets muss 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

Tracker-Handle für das Verschmelzen von Szenen erstellen

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

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

Mit diesem Handle kann ein Snapshot des Szenen-Mesh mit xrCreateSceneMeshSnapshotANDROID in dieser Erweiterung erstellt werden.

Die Funktion xrCreateSceneMeshingTrackerANDROID ist so definiert:

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

Parameterbeschreibungen

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

Wenn das System kein Scene 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 vermeiden kann, einen Tracker für das Erstellen von Szenen-Meshes zu erstellen.

Die Anwendung muss beim Erstellen eines Scene Meshing-Trackers nur die semantischen Labelsätze verwenden, die vom System in XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet unterstützt werden. Wenn die Anwendung eine nicht unterstützte semantische Labelgruppe für Szenen-Mesh-Vertices verwendet, muss die Laufzeit XR_ERROR_FEATURE_UNSUPPORTED von xrCreateSceneMeshingTrackerANDROID zurückgeben .

Die Anwendung kann die Liste der unterstützten semantischen Labelsätze mit der Funktion xrEnumerateSupportedSemanticLabelSetsANDROID aufzählen.

Das Handle xrCreateSceneMeshingTrackerANDROID enthält alle Ressourcen für das Scene Meshing. Wenn Sie mit dem Erstellen von Szenen-Meshes fertig sind, muss die Anwendung das Handle über die Funktion xrDestroySceneMeshingTrackerANDROID zerstören.

Gültige Nutzung (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 in OpenXR oder dieser Erweiterung nicht definiert.
  • semanticLabelSet ist ein XrSceneMeshSemanticLabelSetANDROID, mit dem das semantische Labelset für die Szenenvernetzung angegeben wird. Wenn dies 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 Szenen-Mesh-Daten Scheitelpunktnormalen für die Mesh-Scheitelpunkte im Szenen-Mesh-Puffer enthalten sein sollen.

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

Gültige Nutzung (implizit)

Die Funktion xrDestroySceneMeshingTrackerANDROID ist so definiert:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Parameterbeschreibungen

Die Funktion xrDestroySceneMeshingTrackerANDROID gibt tracker und die zugrunde liegenden Ressourcen frei, wenn die Szenenvernetzung abgeschlossen ist.

Gültige Nutzung (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 Handle XrSceneMeshSnapshotANDROID stellt einen Snapshot des Szenen-Mesh dar. Dieser Snapshot wird mit xrCreateSceneMeshSnapshotANDROID erstellt, das zum Zeitpunkt des Funktionsaufrufs einen Snapshot der Daten des Szenen-Meshs erstellt.

Mit diesem Handle können Submesh-Informationen und ‑Daten mit xrGetAllSubmeshStatesANDROID und xrGetSubmeshDataANDROID abgerufen werden .

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 Snapshot des Szenen-Mesh aus dem Tracker für das Szenen-Meshing zu erstellen. Diese Funktion gibt ein XrSceneMeshSnapshotANDROID-Handle zusammen mit XrSceneMeshTrackingStateANDROID zurück, das in einer XrSceneMeshSnapshotCreationResultANDROID-Struktur umschlossen ist. Der Handle ist technisch gesehen ein Snapshot der Mesh-Daten der Szene zum Zeitpunkt der Erstellung. Mit diesem Handle kann die Mesh-Informationen und -Daten der Szene mit xrGetAllSubmeshStatesANDROID bzw. xrGetSubmeshDataANDROID abgefragt werden.

Gültige Nutzung (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 in OpenXR oder dieser Erweiterung nicht definiert.
  • baseSpace ist ein XrSpace, in dem die Informationen zur Pose des Szenen-Submesh dargestellt werden.
  • time ist der XrTime, der die Zeit beschreibt, zu der das Szenen-Mesh verarbeitet oder angezeigt wird, in der Regel XrFrameState :: predictedDisplayTime .
  • boundingBox ist ein XrBoxf, der den Begrenzungsrahmen beschreibt, in dem das Szenen-Mesh erfasst werden soll.

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

Gültige Nutzung (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 in OpenXR oder dieser Erweiterung nicht definiert.
  • snapshot ist ein XrSceneMeshSnapshotANDROID-Handle, das von der Laufzeit erstellt wird.
  • trackingState ist ein XrSceneMeshTrackingStateANDROID, das den Status des Scene Meshing-Trackers zum Zeitpunkt der Snapshot-Erstellung beschreibt.

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

Gültige Nutzung (implizit)

Die Enumeration XrSceneMeshTrackingStateANDROID beschreibt den Tracking-Status für einen Tracker für die Erstellung von Szenen-Meshes. Jeder Wert in diesem Enum stellt einen Status des Scene Meshing Tracker 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 zu liefern.

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 dem letzten Mesh-Update integriert werden sollen.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

Der Tracker hat über mehrere Zyklen hinweg keine gültigen Messungen empfangen 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 weiterhin zulassen, dass die Anwendung Snapshots erstellt und Daten daraus abruft, 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 aktuell oder leer.

Mesh-Daten der Szene aus dem Mesh-Snapshot der Szene 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. Kann NULL sein, wenn submeshStateCapacityInput = 0.
  • Eine ausführliche Beschreibung zum Abrufen der erforderlichen submeshStates-Größe finden Sie im Kapitel Puffergrößenparameter.

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

Gültige Nutzung (implizit)

  •  Die Erweiterung XR_ANDROID_scene_meshing muss aktiviert sein, bevor xrGetAllSubmeshStatesANDROID aufgerufen wird.
  • snapshot muss ein gültiger XrSceneMeshSnapshotANDROID-Handle sein
  • submeshStateCountOutput muss ein Zeiger auf einen uint32_t-Wert sein.
  • Wenn submeshStateCapacityInput nicht 0 ist , submeshStates muss 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 in OpenXR oder dieser Erweiterung nicht definiert.
  • submeshId ist eine XrUuid, die das Submesh identifiziert.
  • lastUpdatedTime ist ein XrTime, das den Zeitpunkt der letzten Aktualisierung des Submesh darstellt.
  • submeshPoseInBaseSpace ist ein XrPosef, das die Position des Submesh im Basisraum darstellt, der zum Erstellen des Szenenmesh-Snapshots verwendet wurde. Die Pose ist auch der Mittelpunkt des Begrenzungsrahmens des Unternetzes.
  • bounds ist ein XrExtent3Df, das die Abmessungen des Begrenzungsrahmens beschreibt, der das Submesh umschließt. Diese Grenzen werden im Basisbereich definiert, der zum Erstellen des Szenen-Mesh-Handles verwendet wurde.

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

Gültige Nutzung (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 Unternetzen oder alle Unternetze gleichzeitig abzurufen. Dazu muss eine Liste von XrSceneSubmeshDataANDROID übergeben werden, wobei XrSceneSubmeshDataANDROID :: submeshId auf die jeweilige ID des abzurufenden Unternetzes festgelegt ist.

Die XrSceneSubmeshDataANDROID :: submeshId muss für jedes Element in inoutSubmeshData eindeutig sein und kann mit xrGetAllSubmeshStatesANDROID für dieselbe snapshot abgerufen werden . 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.

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

Gültige Nutzung (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 in OpenXR oder dieser Erweiterung nicht 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 Eckpunktpositionen des Submesh ausgibt.
  • vertexNormals ist ein Array von XrVector3f, in das die Laufzeit die Vertex-Normalen des Submesh ausgibt. Dieses Feld kann NULL bleiben, wenn in der Anwendung ein Tracker ohne aktivierte Normen erstellt wurde.
  • vertexSemantics ist ein Array von uint8_t, in das die Laufzeit die Vertex-Semantik des Submesh 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 von vertexPositions, vertexNormals, vertexSemantics und indices finden Sie im Kapitel Parameter für die Puffergröße.

Gültige Nutzung (implizit)

  •  Die Erweiterung XR_ANDROID_scene_meshing muss aktiviert werden, bevor XrSceneSubmeshDataANDROID verwendet wird.
  • 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 , vertexPositions muss ein Zeiger auf ein Array von vertexCapacityInput XrVector3f-Strukturen sein.
  • : Wenn vertexCapacityInput nicht 0 ist , vertexNormals muss ein Zeiger auf ein Array von vertexCapacityInput XrVector3f-Strukturen sein.
  • Wenn vertexCapacityInput nicht 0 ist , vertexSemantics muss ein Zeiger auf ein Array von vertexCapacityInput uint8_t-Werten sein.
  • Wenn indexCapacityInput nicht 0 ist , indices muss ein Zeiger auf ein Array von indexCapacityInput uint32_t-Werten sein.

Die Enumeration XrSceneMeshSemanticLabelANDROID ist die Standardgruppe semantischer Labels, die verwendet werden kann, um Mesh-Vertices zu kennzeichnen und zu beschreiben, auf welcher physischen Umgebungsoberfläche sich der Mesh-Vertex befindet. Diese Enum-Gruppe 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-Mesh löschen

Die Funktion xrDestroySceneMeshSnapshotANDROID ist so definiert:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Parameterbeschreibungen

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

Gültige Nutzung (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 die Szenenvernetzung

Im folgenden Beispielcode wird gezeigt, wie Sie auf Szenen-Mesh-Daten für das Rendern 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 Strukturen

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • XrObjectType erweitern :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • XrStructureType erweitern :

    • 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

  • Revision 3, 15.05.2025 (Salar Khan)

    • Erste Beschreibung der Erweiterung