XR_ANDROID_spatial_anchor_space

Name String

XR_ANDROID_spatial_anchor_space

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

796

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

XR_EXT_spatial_anchor

Datum der letzten Änderung

2025-09-15

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

Mitwirkende

YuSheng Chang, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Übersicht

Mit der in der Erweiterung XR_EXT_spatial_anchor definierten Funktion xrCreateSpatialAnchorEXT können Anwendungen räumliche Anker mit einem XrSpatialEntityEXT-Handle erstellen, um sie darzustellen. Im Gegensatz dazu wird mit dieser Erweiterung ein räumlicher Anker erstellt, der durch ein XrSpace-Handle dargestellt wird. Dies ist in folgenden Fällen nützlich:

  • Verwenden Sie xrLocateSpaces, um die Position des Ankers abzurufen.
  • Andere Bereiche relativ zum Anker finden.
  • Exportieren Sie den Anker mit XR_ANDROID_anchor_sharing_export .
  • Die Anwendung hat Anker platziert und benötigt jetzt nur noch die Position der Anker (um virtuelle Inhalte daran anzuhängen). Andere Komponenten anderer Entitäten, die über den XrSpatialContextEXT gefunden wurden, der zum Erstellen des Ankers verwendet wurde, sind nicht mehr relevant. Dadurch kann die Anwendung den räumlichen Kontext löschen.

Mit dieser Erweiterung erstellte Anker können nicht mit der Erweiterung XR_ANDROID_device_anchor_persistence beibehalten werden. Die Anwendung muss stattdessen XR_EXT_spatial_persistence_operations verwenden. Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrPersistAnchorANDROID zurückgeben, wenn XrPersistedAnchorSpaceInfoANDROID :: anchor mit xrCreateSpatialAnchorSpaceANDROID oder xrCreateSpatialAnchorSpaceFromIdANDROID erstellt wird.

XrSpace für einen räumlichen Anker erstellen

Räumlichen Anker und Raum erstellen

Die Funktion xrCreateSpatialAnchorSpaceANDROID ist so definiert:

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

Parameterbeschreibungen

Die Funktion xrCreateSpatialAnchorSpaceANDROID erstellt einen Anker, der ein XrSpatialEntityIdEXT- und ein XrSpace-Handle ausgibt. Für xrCreateSpatialAnchorSpaceANDROID gelten dieselben Validierungsanforderungen wie für xrCreateSpatialAnchorEXT .

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE zurückgeben, wenn der an xrCreateSpatialAnchorSpaceANDROID übergebene XrSpatialContextEXT nicht mit XR_SPATIAL_CAPABILITY_ANCHOR_EXT konfiguriert wurde.

In Bezug auf die Auffindbarkeit des erstellten Ankers durch xrCreateSpatialAnchorSpaceANDROID gilt der letzte Absatz der xrCreateSpatialAnchorEXT-Spezifikation.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_spatial_anchor_space muss aktiviert sein, bevor xrCreateSpatialAnchorSpaceANDROID aufgerufen wird.
  • session muss ein gültiges XrSession-Handle sein
  • spatialContext muss ein gültiges XrSpatialContextEXT-Handle sein
  • createInfo muss ein Zeiger auf eine gültige XrSpatialAnchorCreateInfoEXT-Struktur sein.
  • anchorEntityId muss ein Zeiger auf einen XrSpatialEntityIdEXT-Wert sein
  • anchorSpace muss ein Zeiger auf ein XrSpace-Handle sein
  • spatialContext muss erstellt, zugewiesen oder von session abgerufen worden 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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrSpace aus einem vorhandenen räumlichen Anker erstellen

Die Funktion xrCreateSpatialAnchorSpaceFromIdANDROID ist so definiert:

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

Parameterbeschreibungen

In Szenarien, in denen räumliche Ankerentitäten bereits vorhanden sind (z.B. aufgrund von Persistenz), können Anwendungen einen XrSpace aus diesen räumlichen Ankern erstellen, indem sie ihre räumlichen Entitäts-IDs angeben.

Die Funktion xrCreateSpatialAnchorSpaceFromIdANDROID erstellt ein XrSpace-Handle, indem im Feld XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId eine XrSpatialEntityIdEXT angegeben wird.

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE zurückgeben, wenn der an xrCreateSpatialAnchorSpaceFromIdANDROID übergebene XrSpatialContextEXT nicht mit XR_SPATIAL_CAPABILITY_ANCHOR_EXT konfiguriert wurde.

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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrSpatialAnchorSpaceFromIdCreateInfoANDROID ist so definiert:

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • anchorEntityId ist die XrSpatialEntityIdEXT des vorhandenen räumlichen Ankers, aus dem der XrSpace erstellt werden soll.

Die Laufzeit muss XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT zurückgeben, wenn XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId keine gültige ID für spatialContext ist.

Die Laufzeit muss XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID zurückgeben, wenn XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId keine gültige Entitäts-ID für einen Anker ist.

Gültige Verwendung (implizit)

Lebenszyklus des Ankers

Das übergeordnete Element eines XrSpace-Handles ist eine XrSession . Das bedeutet, dass ein XrSpace-Handle, das den Anker darstellt, auch nach dem Löschen von xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext oder xrCreateSpatialAnchorSpaceANDROID :: spatialContext gültig bleibt. Wenn ein XrSpace erstellt wird, um einen räumlichen Entitätsanker darzustellen, kann die Anwendung den mit XR_SPATIAL_CAPABILITY_ANCHOR_EXT konfigurierten XrSpatialContextEXT zerstören, während sie weiterhin die neueste Position des Ankers über seinen XrSpace mit xrLocateSpaces abruft. Das bedeutet, dass die Laufzeit den Anker weiterhin verfolgen muss, bis alle XrSpace-Handles, die ihn darstellen, zerstört wurden.

Beispielcode

Raumanker als XrSpace erstellen

Der folgende Beispielcode zeigt, wie Sie einen räumlichen Anker erstellen und als XrSpace zurückgeben.

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

XrSpace aus Ankerentitäts-ID erstellen

Im folgenden Beispielcode wird gezeigt, wie Sie einen XrSpace aus einer vorhandenen Ankerentitäts-ID erstellen.

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

Neue Befehle

Neue Gebäude

Neue Enum-Konstanten

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • Erweiterung von XrResult :

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • Erweiterung von XrStructureType :

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

Probleme

Versionsverlauf

  • Version 1, 15.09.2025 (YuSheng Chang, Kyle Chen)

    • Erste Beschreibung der Erweiterung.