XR_ANDROID_spatial_anchor_space

Name String

XR_ANDROID_spatial_anchor_space

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

796

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

XR_EXT_spatial_anchor

Data ostatniej modyfikacji

2025-09-15

Stan IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

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

Przegląd

Funkcja xrCreateSpatialAnchorEXT zdefiniowana w rozszerzeniu XR_EXT_spatial_anchor umożliwia aplikacjom tworzenie kotwic przestrzennych z uchwytem XrSpatialEntityEXT, który je reprezentuje. To rozszerzenie tworzy natomiast kotwicę przestrzenną, która jest reprezentowana przez uchwyt XrSpace. Jest to przydatne w przypadkach, gdy aplikacja ma:

  • Aby uzyskać lokalizację kotwicy, użyj xrLocateSpaces.
  • Zlokalizuj inne przestrzenie względem kotwicy.
  • Wyeksportuj kotwicę za pomocą XR_ANDROID_anchor_sharing_export .
  • Aplikacja umieściła kotwice i teraz interesuje ją tylko ich lokalizacja (aby dołączyć treści wirtualne). Nie interesuje jej żaden inny komponent żadnych innych elementów wykrytych za pomocą XrSpatialContextEXT użytego do utworzenia kotwicy, co pozwala aplikacji na zniszczenie kontekstu przestrzennego.

Kotwice utworzone za pomocą tego rozszerzenia nie mogą być utrwalane za pomocą rozszerzenia XR_ANDROID_device_anchor_persistence, a aplikacja musi zamiast tego używać XR_EXT_spatial_persistence_operations . Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE z xrPersistAnchorANDROID, jeśli XrPersistedAnchorSpaceInfoANDROID :: anchor jest tworzony za pomocą xrCreateSpatialAnchorSpaceANDROID lub xrCreateSpatialAnchorSpaceFromIdANDROID .

Tworzenie XrSpace dla kotwicy przestrzennej

Tworzenie kotwicy przestrzennej i przestrzeni

Funkcja xrCreateSpatialAnchorSpaceANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

Funkcja xrCreateSpatialAnchorSpaceANDROID tworzy kotwicę, która zwraca uchwyt XrSpatialEntityIdEXT i XrSpace. xrCreateSpatialAnchorSpaceANDROID ma takie same wymagania dotyczące weryfikacji jak xrCreateSpatialAnchorEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE, jeśli element XrSpatialContextEXT przekazany do xrCreateSpatialAnchorSpaceANDROID nie został skonfigurowany z XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

W odniesieniu do możliwości wykrywania kotwicy utworzonej przez xrCreateSpatialAnchorSpaceANDROID obowiązuje ostatni akapit specyfikacji xrCreateSpatialAnchorEXT.

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_ANDROID_spatial_anchor_space musi być włączone przed wywołaniem xrCreateSpatialAnchorSpaceANDROID.
  • session musi być prawidłowym uchwytem XrSession
  • spatialContext musi być prawidłowym uchwytem XrSpatialContextEXT
  • createInfo musi być wskaźnikiem do prawidłowej struktury XrSpatialAnchorCreateInfoEXT.
  • anchorEntityId musi być wskaźnikiem do wartości XrSpatialEntityIdEXT
  • anchorSpace musi być wskaźnikiem do uchwytu XrSpace
  • spatialContext musi zostać utworzony, przydzielony lub pobrany z: session

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Tworzenie XrSpace na podstawie istniejącej kotwicy przestrzennej

Funkcja xrCreateSpatialAnchorSpaceFromIdANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

W przypadkach, gdy encje kotwic przestrzennych już istnieją (np. ze względu na trwałość), aplikacje mogą utworzyć XrSpace z tych kotwic przestrzennych, podając ich identyfikatory encji przestrzennych.

Funkcja xrCreateSpatialAnchorSpaceFromIdANDROID tworzy uchwyt XrSpace, podając XrSpatialEntityIdEXT w polu XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId.

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE, jeśli element XrSpatialContextEXT przekazany do xrCreateSpatialAnchorSpaceFromIdANDROID nie został skonfigurowany z XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Struktura XrSpatialAnchorSpaceFromIdCreateInfoANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • anchorEntityId to XrSpatialEntityIdEXT istniejącej kotwicy przestrzennej, z której ma zostać utworzony obiekt XrSpace .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT, jeśli XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId nie jest prawidłowym identyfikatorem dla spatialContext .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID, jeśli XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId nie jest prawidłowym identyfikatorem encji kotwicy.

Prawidłowe użycie (pośrednie)

Cykl życia kotwicy

Uchwytem nadrzędnym uchwytu XrSpace jest XrSession . Oznacza to, że uchwyt XrSpace reprezentujący kotwicę pozostaje ważny nawet po zniszczeniu xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext lub xrCreateSpatialAnchorSpaceANDROID :: spatialContext. Utworzenie XrSpace do reprezentowania kotwicy elementu przestrzennego umożliwia aplikacji zniszczenie XrSpatialContextEXT, który został skonfigurowany za pomocą XR_SPATIAL_CAPABILITY_ANCHOR_EXT, przy jednoczesnym dalszym uzyskiwaniu najnowszej pozycji kotwicy za pomocą XrSpace z xrLocateSpaces, tzn. środowisko wykonawcze musi nadal śledzić kotwicę, dopóki wszystkie uchwyty XrSpace, które ją reprezentują, nie zostaną zniszczone.

Przykładowy kod

Tworzenie kotwicy przestrzennej jako XrSpace

Poniższy przykładowy kod pokazuje, jak utworzyć kotwicę przestrzenną i zwrócić ją jako XrSpace .

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

// ...

Utwórz XrSpace na podstawie identyfikatora elementu zakotwiczonego

Poniższy przykładowy kod pokazuje, jak utworzyć obiekt XrSpace na podstawie istniejącego identyfikatora encji kotwicy.

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

// ...

Nowe polecenia

Nowe domy

Nowe stałe typu wyliczeniowego

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • Rozszerzenie XrResult :

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • Rozszerzanie XrStructureType :

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

Problemy

Historia zmian

  • Wersja 1, 15 września 2025 r. (YuSheng Chang, Kyle Chen)

    • Początkowy opis rozszerzenia.