OpenXR-Erweiterung XR_ANDROID_scene_meshing

Name String XR_ANDROID_scene_meshing

Erweiterungstyp Instanzerweiterung

Registrierte Erweiterungsnummer 464

Revision 3

Abhängigkeiten von Erweiterungen und Versionen OpenXR 1.0

Datum der letzten Änderung 2025-05-15

IP-Status Es sind keine bekannten Ansprüche in Bezug auf geistiges Eigentum vorhanden.

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 Mesh-Daten für die Meshes bereitstellen, die die physischen Objekte in Ihrer Umgebung ungefähr darstellen. Sie kann verwendet werden, um Ihre Szene in einer immersiven Anwendung zu visualisieren und virtuellen Objekten die Interaktion mit physischen Objekten zu ermöglichen, z. B. durch Kollisionen.

Daten zum Erstellen von 3D-Modellen von Szenen können vertrauliche personenbezogene Daten sein und sind eng mit dem Schutz der Privatsphäre und der Integrität von Personen verbunden. Es wird dringend empfohlen, dass Anwendungen, die Daten zum Erstellen von 3D-Modellen von Szenen 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 sensible Berechtigung, da die Laufzeit damit die Nutzerumgebung untersuchen kann.

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

(Schutzebene: gefährlich)

Systemfunktionen prüfen

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

XrSystemSceneMeshingPropertiesANDROID

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 das Erstellen von Szenen-Meshes unterstützt.

Wenn supportsSceneMeshing den Wert XR_FALSE hat, wird das Zusammenfügen von Szenen vom System nicht unterstützt. Die Anwendung sollte die Funktion zum Erstellen von Szenen-Meshes vermeiden, wenn supportsSceneMeshing XR_FALSE ist, da Aufrufe von xrCreateSceneMeshingTrackerANDROID fehlschlagen.

Wenn supportsSceneMeshing gleich XR_TRUE ist, unterstützt das System das Erstellen von Szenen-Meshes.

Gültige Nutzung (implizit)

XrSceneMeshSemanticLabelSetANDROID

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;

xrEnumerateSupportedSemanticLabelSetsANDROID

Die Anwendung kann mit der Funktion xrEnumerateSupportedSemanticLabelSetsANDROID vom System unterstützte semantische Labelsätze abrufen.

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 eine XrSystemId, die von xrGetSystem abgerufen wurde.
  • supportedSemanticLabelSetsInputCapacity ist die Länge von supportedSemanticLabelSets.
  • supportedSemanticLabelSetsOutputCount ist die Anzahl der Elemente in supportedSemanticLabelSets, die von der Laufzeit ab dem Beginn des Arrays geändert wurden.
  • supportedSemanticLabelSets ist ein Array von XrSceneMeshSemanticLabelSetANDROID, in das die unterstützten semantischen Labelsätze von der Laufzeit geschrieben werden.

Es wird erwartet, dass jedes System mindestens XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID unterstützt, da dieser Enum-Wert kein semantisches Labelset darstellt und verwendet werden kann, wenn die Anwendung keine Vertex-Semantik benötigt.

Tracker-Handle für das Zusammenfügen von Szenen erstellen

XrSceneMeshingTrackerANDROID

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

Das Handle XrSceneMeshingTrackerANDROID stellt einen Tracker für das Erstellen von 3D-Modellen von Szenen und die Verwaltung der zugehörigen Ressourcen dar.

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

xrCreateSceneMeshingTrackerANDROID

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

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

Parameterbeschreibungen

Wenn das System kein Scene Meshing unterstützt, gibt xrCreateSceneMeshingTrackerANDROID den Wert XR_ERROR_FEATURE_UNSUPPORTED zurück. Die Anwendung kann die Systemunterstützung prüfen, indem sie xrGetSystemProperties mit der Struktur XrSystemSceneMeshingPropertiesANDROID aufruft.

Beim Erstellen eines Scene-Meshing-Trackers können in XrSceneMeshingTrackerCreateInfoANDROID::semanticLabelSet nur semantische Labelsets verwendet werden, die vom System unterstützt werden. Mit der Funktion xrEnumerateSupportedSemanticLabelSetsANDROID kann die Liste der unterstützten semantischen Labelsätze abgerufen werden.

Wenn die Anwendung eine nicht unterstützte semanticLabelSet anfordert, gibt xrCreateSceneMeshingTrackerANDROID XR_ERROR_FEATURE_UNSUPPORTED zurück.

Das Handle xrCreateSceneMeshingTrackerANDROID ist Inhaber aller 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.

XrSceneMeshingTrackerCreateInfoANDROID

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

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, das verwendet wird, um die semantische Labelgruppe für die Szenenvernetzung anzugeben. Wenn dieser Wert auf XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID gesetzt ist, wird das Pufferfeld XrSceneSubmeshDataANDROID::vertexSemantics von der Laufzeit ignoriert.
  • 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.

xrDestroySceneMeshingTrackerANDROID

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

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID          tracker);

Parameterbeschreibungen

Snapshot-Handle für Szenen-Mesh erstellen

XrSceneMeshSnapshotANDROID

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

Das Handle XrSceneMeshSnapshotANDROID stellt einen Snapshot des Szenen-Mesh dar. Es wird mit xrCreateSceneMeshSnapshotANDROID erstellt, das im Wesentlichen einen Snapshot der Daten des Szenen-Mesh zum Zeitpunkt des Funktionsaufrufs erstellt.

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

XrSceneMeshSnapshotCreateInfoANDROID

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

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, mit dem der Referenzraum beschrieben wird, in dem die Pose-Informationen der Szenen-Submeshes dargestellt werden sollen.
  • time ist die XrTime, die den Zeitpunkt beschreibt, zu dem das Szenen-Mesh verarbeitet oder angezeigt wird.
  • boundingBox ist ein XrBoxf, der den Begrenzungsrahmen beschreibt, in dem das Szenen-Mesh erfasst werden soll.

XrSceneMeshTrackingStateANDROID

Die Enumeration XrSceneMeshTrackingStateANDROID beschreibt den Tracking-Status für den Tracker für das Erstellen von Szenen-Meshes. Jeder Wert in diesem Enum stellt einen Status des Scene Meshing Tracker dar. Diese Enumeration ist in der Struktur XrSceneMeshSnapshotCreationResultANDROID enthalten, die von xrCreateSceneMeshSnapshotANDROID zurückgegeben wird.

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;

XrSceneMeshSnapshotCreationResultANDROID

Die Struktur XrSceneMeshSnapshotCreationResultANDROID speichert das Ergebnis der Erstellung eines Szenen-Mesh-Snapshots, das von xrCreateSceneMeshSnapshotANDROID zurückgegeben wird. Das Ergebnis enthält das Snapshot-Handle und den Tracking-Status des Scene Meshing Tracker zum Zeitpunkt der Snapshot-Erstellung.

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                  type;
    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 XrSceneMeshSnapshotANDROID-Handle, das von der Laufzeit erstellt wird.
  • trackingState ist ein XrSceneMeshTrackingStateANDROID, der den Status des Scene Meshing-Trackers zum Zeitpunkt der Snapshot-Erstellung beschreibt.

xrCreateSceneMeshSnapshotANDROID

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 Szenen-Mesh-Daten zum Zeitpunkt der Erstellung. Mit diesem Handle kann die Mesh-Informationen und -Daten der Szene mit xrGetAllSubmeshStatesANDROID bzw. xrGetSubmeshDataANDROID abgefragt werden.

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

Parameterbeschreibungen

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

XrSceneSubmeshStateANDROID

XrSceneSubmeshStateANDROID beschreibt ein Submesh. Er enthält die grundlegenden Informationen zum Submesh (ID, Pose, Grenzen, Zeitpunkt der letzten Aktualisierung).

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 darstellt.
  • submeshPoseInBaseSpace ist ein XrPosef, das die Position des Submesh im Basisraum darstellt, der zum Erstellen des Szenenmesh-Snapshots verwendet wurde. Dies ist auch die Pose des Mittelpunkts des Begrenzungsrahmens des Submesh.
  • bounds ist ein XrExtent3Df, das die Abmessungen des umschließenden Rechtecks beschreibt, das das Submesh umschließt. Diese Grenzen befinden sich im Basisbereich, der zum Erstellen des Handles für das Szenen-Mesh verwendet wurde.

xrGetAllSubmeshStatesANDROID

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. Diese Funktion kann in einem Idiom mit zwei Aufrufen verwendet werden.

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 Länge von submeshStates.
  • submeshStateCountOutput ist die Anzahl der Elemente in submeshStates, die von der Laufzeit ab dem Beginn des Arrays geändert werden.
  • submeshStates ist ein Array von XrSceneSubmeshStateANDROID-Strukturen, in die die Laufzeit den Status aller Submeshes im Szenen-Mesh ausgibt.

XrSceneSubmeshDataANDROID

XrSceneSubmeshDataANDROID enthält die Dreiecksdaten für ein Submesh sowie die Submesh-ID. Diese Struktur wird in xrGetSubmeshDataANDROID verwendet, um die Daten des Submesh abzurufen. Die Anwendung muss die Submesh-ID dieser Struktur und die Pufferzeiger auf zugewiesene Puffer festlegen, damit die zurückgegebenen Daten für das Submesh in die zugewiesenen Puffer eingefügt werden können. Die Anwendung kann xrGetSubmeshDataANDROID als 2-Aufruf-Idiom verwenden. Beim ersten Aufruf muss die Anwendung die Submesh-ID festlegen und die Größen der für die Submesh-Daten erforderlichen Puffer abrufen. Anschließend kann die Anwendung die Puffer zuweisen und die Daten beim zweiten Aufruf abrufen.

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 Länge von vertexPositions, vertexNormals und vertexSemantics.
  • vertexCountOutput ist die Anzahl der Elemente in vertexPositions, vertexNormals und vertexSemantics, die von der Laufzeit ab dem Anfang des Arrays geändert wurden.
  • 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 werden, wenn in der Anwendung ein Tracker ohne aktivierte Normals erstellt wurde.
  • vertexSemantics ist ein Array von uint8_t, in das die Laufzeit die Vertex-Semantik des Submesh ausgibt. Dieses Feld kann leer gelassen werden (NULL), wenn die Anwendung einen Tracker mit dem semantischen Label XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID erstellt hat.
  • indexCapacityInput ist die Länge von indices.
  • indexCountOutput ist die Anzahl der Elemente in indices, die von der Laufzeit ab dem Beginn des Arrays geändert wurden.
  • indices ist ein Array von uint32_t, in das die Laufzeit die Indexe des Submesh ausgibt.

xrGetSubmeshDataANDROID

Die Anwendung kann die Funktion xrGetSubmeshDataANDROID verwenden, um die Daten für eine ausgewählte Liste von Submeshes abzurufen. Diese Funktion kann in einem Idiom mit zwei Aufrufen verwendet werden. Beim ersten Aufruf muss die Anwendung eine gültige Submesh-ID festlegen (d. h. abrufbar von xrGetAllSubmeshStatesANDROID mit demselben Szenen-Mesh-Snapshot) und eine Kapazität von null für jedes Element in der ausgewählten Liste von Submeshes festlegen, um die Größen der für die Submesh-Daten erforderlichen Puffer zu erhalten. Beim zweiten Aufruf muss die Anwendung die Pufferzeiger für jedes Element in der ausgewählten Liste der Unternetze auf einen zugewiesenen Puffer festlegen, zusammen mit der Kapazität der Puffer, um die Daten der Unternetze abzurufen.

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

Parameterbeschreibungen

XrSceneMeshSemanticLabelANDROID

Die Enumeration XrSceneMeshSemanticLabelANDROID ist der Standardsatz semantischer Labels, die verwendet werden können, 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;

Snapshot eines Szenen-Mesh löschen

xrDestroySceneMeshSnapshotANDROID

Die Anwendung kann die Funktion xrDestroySceneMeshSnapshotANDROID verwenden, um einen Snapshot des Szenen-Mesh zu löschen. Sobald das Handle zerstört wurde, kann die Anwendung es nicht mehr verwenden, um die Informationen oder Daten des 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.

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID            snapshot);

Parameterbeschreibungen

Beispielcode für die Szenenvernetzung

Das folgende Beispiel zeigt, 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
  std::vector<XrSceneSubmeshStateANDROID> states;
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  states.resize(submeshCount);
  for (XrSceneSubmeshStateANDROID& state : states) {
    state = {.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.vertexCountOutput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCountOutput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCountOutput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCountOutput];
  }
  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 =
      reinterpret_cast<XrSceneMeshSemanticLabelANDROID*>(data.vertexSemantics);
    XrPosef pose = submeshesPoses[i];

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

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

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

Neue Objekttypen

Neue Enum-Konstanten

Die Enumeration XrObjectType wird um Folgendes erweitert:

  • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
  • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

Die Enumeration XrStructureType wurde um Folgendes erweitert:

  • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID
  • 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_STATE_ANDROID
  • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID

Neue Enums

Neue Strukturen

Neue Funktionen

Probleme

Versionsverlauf

  • Version 3, 15.05.2025 (Salar Khan) ** Erste Beschreibung der Erweiterung

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