XR_ANDROID_spatial_anchor_space

Name String

XR_ANDROID_spatial_anchor_space

Uzantı Türü

Örnek uzantısı

Kayıtlı Dahili Numara

796

Düzeltme

1

Onay Durumu

Onaylanmadı

Uzantı ve Sürüm Bağımlılıkları

XR_EXT_spatial_anchor

Son Değiştirilme Tarihi

2025-09-15

IP Durumu

Bilinen bir fikri mülkiyet hak talebi yok.

Katkıda bulunanlar

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

Genel Bakış

XR_EXT_spatial_anchor uzantısında tanımlanan xrCreateSpatialAnchorEXT işlevi, uygulamaların bunu temsil edecek bir XrSpatialEntityEXT herkese açık anahtarı ile uzamsal yer işaretleri oluşturmasına olanak tanır. Bunun aksine, bu uzantı XrSpace herkese açık kullanıcı adı ile temsil edilen bir uzamsal sabitleyici oluşturur. Bu, uygulamanın aşağıdakileri yapmak istediği durumlarda kullanışlıdır:

  • Sabit noktanın konumunu almak için xrLocateSpaces'i kullanın.
  • Sabit noktaya göre diğer alanları bulun.
  • XR_ANDROID_anchor_sharing_export kullanarak sabiti dışa aktarın.
  • Uygulama, yerleştirilen sabitleyicilerin yalnızca konumunu (sanal içerik eklemek için) dikkate alır. Sabitleyiciyi oluşturmak için kullanılan XrSpatialContextEXT aracılığıyla keşfedilen diğer varlıkların başka bileşenlerini dikkate almaz. Bu sayede uygulama, uzamsal bağlamı yok edebilir.

Bu uzantıyla oluşturulan sabit noktalar XR_ANDROID_device_anchor_persistence uzantısı kullanılarak kalıcı hale getirilemez ve uygulamanın bunun yerine XR_EXT_spatial_persistence_operations kullanması gerekir. XrPersistedAnchorSpaceInfoANDROID :: anchor, xrCreateSpatialAnchorSpaceANDROID veya xrCreateSpatialAnchorSpaceFromIdANDROID kullanılarak oluşturulursa çalışma zamanı, xrPersistAnchorANDROID'den XR_ERROR_VALIDATION_FAILURE döndürmelidir.

Üç boyutlu yer işareti için XrSpace oluşturma

Uzamsal yer işareti ve alan oluşturma

xrCreateSpatialAnchorSpaceANDROID işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

xrCreateSpatialAnchorSpaceANDROID işlevi, XrSpatialEntityIdEXT ve XrSpace herkese açık kullanıcı adı döndüren bir sabitleyici oluşturur. xrCreateSpatialAnchorSpaceANDROID, xrCreateSpatialAnchorEXT ile aynı doğrulama koşullarına sahiptir.

xrCreateSpatialAnchorSpaceANDROID'e iletilen XrSpatialContextEXT, XR_SPATIAL_CAPABILITY_ANCHOR_EXT ile yapılandırılmamışsa çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.

xrCreateSpatialAnchorSpaceANDROID tarafından oluşturulan sabitleyicinin bulunabilirliğiyle ilgili olarak xrCreateSpatialAnchorEXT spesifikasyonunun son paragrafı geçerlidir.

Geçerli Kullanım (Dolaylı)

  • XR_ANDROID_spatial_anchor_space uzantısı, xrCreateSpatialAnchorSpaceANDROID çağrılmadan önce etkinleştirilmelidir.
  • session geçerli bir XrSession herkese açık kullanıcı adı olmalıdır
  • spatialContext, geçerli bir XrSpatialContextEXT herkese açık kullanıcı adı olmalıdır
  • createInfo, geçerli bir XrSpatialAnchorCreateInfoEXT yapısına işaret eden bir işaretçi olmalıdır.
  • anchorEntityId, bir XrSpatialEntityIdEXT değerine işaretçi olmalıdır
  • anchorSpace, bir XrSpace tutamacına işaretçi olmalıdır.
  • spatialContext, session üzerinden oluşturulmuş, tahsis edilmiş veya alınmış olmalıdır.

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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

Mevcut bir uzamsal sabitleyiciden XrSpace oluşturma

xrCreateSpatialAnchorSpaceFromIdANDROID işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

Uzamsal yer işareti varlıklarının önceden mevcut olduğu senaryolarda (ör. kalıcılık nedeniyle) uygulamalar, uzamsal varlık kimliklerini sağlayarak bu uzamsal yer işaretlerinden bir XrSpace oluşturabilir.

xrCreateSpatialAnchorSpaceFromIdANDROID işlevi, XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId alanında bir XrSpatialEntityIdEXT sağlayarak XrSpace herkese açık kullanıcı adı oluşturur.

xrCreateSpatialAnchorSpaceFromIdANDROID'e iletilen XrSpatialContextEXT, XR_SPATIAL_CAPABILITY_ANCHOR_EXT ile yapılandırılmamışsa çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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

XrSpatialAnchorSpaceFromIdCreateInfoANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir.
  • anchorEntityId, XrSpace'in oluşturulacağı mevcut uzamsal sabitleyicinin XrSpatialEntityIdEXT değeridir.

XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId, spatialContext için geçerli bir kimlik değilse çalışma zamanı XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT değerini döndürmelidir.

XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId, bir sabitleyici için geçerli bir varlık kimliği değilse çalışma zamanı XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID değerini döndürmelidir .

Geçerli Kullanım (Dolaylı)

Sabit Yaşam Döngüsü

XrSpace herkese açık adının üst öğesi XrSession'dır. Bu, sabitleyiciyi temsil eden bir XrSpace tutma yerinin, xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext veya xrCreateSpatialAnchorSpaceANDROID :: spatialContext yok edildikten sonra bile geçerli kaldığı anlamına gelir. Uzamsal varlık yer işaretini temsil eden bir XrSpace oluşturmak, uygulamanın XR_SPATIAL_CAPABILITY_ANCHOR_EXT ile yapılandırılmış XrSpatialContextEXT'yi yok etmesine olanak tanır.Bu sırada, xrLocateSpaces ile XrSpace'ini kullanarak yer işaretinin en son konumunu almaya devam eder. Yani çalışma zamanı, yer işaretini temsil eden tüm XrSpace tanıtıcıları yok edilene kadar yer işaretini izlemeye devam etmelidir.

Örnek kod

XrSpace olarak uzamsal yer işareti oluşturma

Aşağıdaki örnek kodda, uzamsal yer işaretinin nasıl oluşturulacağı ve XrSpace olarak nasıl döndürüleceği gösterilmektedir.

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

// ...

Bağlantı noktası varlık kimliğinden XrSpace oluşturma

Aşağıdaki örnek kodda, önceden var olan bir sabitleyici öğe kimliğinden nasıl XrSpace oluşturulacağı gösterilmektedir.

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

// ...

Yeni Komutlar

Yeni Yapılar

Yeni Enum Sabitleri

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • XrResult'ı genişletme:

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • XrStructureType'ı genişletme:

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

Sayılar

Sürüm Geçmişi

  • Düzeltme 1, 15.09.2025 (YuSheng Chang, Kyle Chen)

    • İlk uzantı açıklaması.