XR_EXT_spatial_anchor

Name String

XR_EXT_spatial_anchor

Uzantı Türü

Örnek uzantısı

Kayıtlı Dahili Numara

763

Düzeltme

1

Onay Durumu

Onaylandı

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

XR_EXT_spatial_entity

Katkıda bulunanlar

Nihav Jain, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Genel Bakış

Bu uzantı, XR_EXT_spatial_entity üzerine kuruludur ve uygulamaların uzamsal yer işaretleri oluşturmasına olanak tanır. Bu yer işaretleri, kullanıcının fiziksel ortamındaki rastgele noktalardır ve daha sonra çalışma zamanı tarafından izlenir. Çalışma zamanı, gerçek dünyadaki orijinal eşlemesini korumasını sağlamak için diğer tüm alanlardan ve sabitleyicilerden bağımsız olarak sabitleyicinin başlangıç noktasının konumunu ve yönünü zaman içinde gerektiği gibi ayarlamalıdır (should).

XrSpatialContextEXT içinde belirli bir konumu ve yönü izleyen bir sabitleyici, XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT bileşenine sahip (veya "sahip olan") uzamsal bir varlık olarak temsil edilir.

Sabitleri kullanmanın avantajı

Çalışma zamanının, kullanıcının fiziksel ortamıyla ilgili bilgileri XrSpatialContextEXT'in kullanım ömrü boyunca güncellenir. Bu süreçte sanal nesneler, uygulama tarafından yerleştirildikleri yerden uzaklaşıyor gibi görünebilir. Bu durum, uygulamanın gerçekçiliğini ve kullanıcı deneyiminin kalitesini etkiler. Uygulama, sanal bir nesnenin yerleştirildiği yerin yakınına bir sabitleyici oluşturup bu sanal nesneyi her zaman sabitleyicisine göre oluşturarak her sanal nesnenin fiziksel ortamda aynı konumda ve yönde kalmasını sağlayabilir. Ayrıca, belirli referans alanlarının aksine, sabit noktalar sistem düzeyinde yeniden ortalamadan etkilenmez.

Çalışma zamanı desteği

Çalışma zamanı, uzamsal sabitleyicileri destekliyorsa bunu xrEnumerateSpatialCapabilitiesEXT içinde XR_SPATIAL_CAPABILITY_ANCHOR_EXT değerini numaralandırarak belirtmesi gerekir.

Yapılandırma

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

typedef struct XrSpatialCapabilityConfigurationAnchorEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationAnchorEXT;

Ü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.
  • capability, bir XrSpatialCapabilityEXT'tir.
  • enabledComponentCount, enabledComponents dizisindeki öğe sayısını açıklayan bir uint32_t değeridir.
  • enabledComponents, XrSpatialComponentTypeEXT dizisine işaret eden bir göstergedir.

Uygulamalar, XrSpatialContextCreateInfoEXT :: capabilityConfigs içinde bir XrSpatialCapabilityConfigurationAnchorEXT yapısına işaretçi ekleyerek XR_SPATIAL_CAPABILITY_ANCHOR_EXT uzamsal özelliğini etkinleştirebilir.

capability, XR_SPATIAL_CAPABILITY_ANCHOR_EXT değilse çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.

Geçerli Kullanım (Dolaylı)

Garantili Bileşenler

XR_SPATIAL_CAPABILITY_ANCHOR_EXT özelliğini destekleyen bir çalışma zamanı, bu özellik tarafından oluşturulan veya keşfedilen tüm varlıkların garantili bileşenleri olarak aşağıdaki uzamsal bileşenleri sağlamalı ve bunları xrEnumerateSpatialCapabilityComponentTypesEXT içinde listelemelidir:

  • XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Sabit Bileşen

Bileşen Verileri

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT, verileri için sabitleyicinin konumunu ve yönünü sağlayan XrPosef'i kullanır.

Verileri Sorgulamak İçin Bileşen Listesi Yapısı

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

typedef struct XrSpatialComponentAnchorListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           locationCount;
    XrPosef*           locations;
} XrSpatialComponentAnchorListEXT;

Ü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.
  • locationCount, locations dizisindeki öğe sayısını açıklayan bir uint32_t değeridir.
  • locations, XrPosef dizisidir.

XrSpatialComponentDataQueryResultEXT :: next zincirinde XrSpatialComponentAnchorListEXT varsa ancak XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT, XrSpatialComponentDataQueryConditionEXT :: componentTypes içinde yer almıyorsa çalışma zamanı, xrQuerySpatialComponentDataEXT'ten XR_ERROR_VALIDATION_FAILURE döndürmelidir.

locationCount, XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput değerinden küçükse çalışma zamanı, xrQuerySpatialComponentDataEXT'ten XR_ERROR_SIZE_INSUFFICIENT değerini döndürmelidir.

Geçerli Kullanım (Dolaylı)

  • XrSpatialComponentAnchorListEXT kullanılmadan önce XR_EXT_spatial_anchor uzantısı etkinleştirilmelidir.
  • type XR_TYPE_SPATIAL_COMPONENT_ANCHOR_LIST_EXT olmalıdır
  • next, NULL veya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır.
  • locations, locationCount XrPosef yapılarından oluşan bir diziye işaretçi olmalıdır
  • locationCount parametresi 0 değerinden büyük olmalıdır.
Yapılandırma

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT, bir özellik için XrSpatialCapabilityComponentTypesEXT :: componentTypes içinde listeleniyorsa uygulama, bu bileşeni destekleyen özelliğin XrSpatialCapabilityConfigurationBaseHeaderEXT türetilmiş yapısının XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents listesine numaralandırıcıyı ekleyerek bu özelliği etkinleştirebilir.

Bu bileşenin XrSpatialCapabilityConfigurationBaseHeaderEXT :: next zincirine dahil edilmesi için özel bir yapılandırma gerekmez.

Uzamsal yer işareti oluşturma

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

XrResult xrCreateSpatialAnchorEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpatialEntityEXT*                         anchorEntity);

Parametre Açıklamaları

Uygulama, xrCreateSpatialAnchorEXT kullanarak uzamsal yer işareti oluşturabilir.

Bir sabitleme noktası için güncellenmiş bileşen verilerini almak istiyorsanız anlık görüntü oluştururken anchorEntity içinde doldurulan değeri XrSpatialUpdateSnapshotCreateInfoEXT :: entities içine iletin. Uygulama, xrQuerySpatialComponentDataEXT kullanırken XrSpatialComponentDataQueryResultEXT :: entityIds dizisinde bu sabitleyiciyi benzersiz şekilde tanımlamak için anchorEntityId değerini kullanabilir .

XR_SPATIAL_CAPABILITY_ANCHOR_EXT, spatialContext için yapılandırılmadıysa çalışma zamanı, xrCreateSpatialAnchorEXT'ten XR_ERROR_VALIDATION_FAILURE döndürmelidir. XR_SPATIAL_CAPABILITY_ANCHOR_EXT özelliği için XrSpatialContextEXT'yi nasıl yapılandıracağınızı öğrenmek üzere Yapılandırma bölümüne bakın.

anchorEntity ile temsil edilen sabitleyici, yalnızca spatialContext kullanım ömrü boyunca veya uygulama, sabitleyici üzerinde xrDestroySpatialEntityEXT işlevini çağırana kadar (hangisi önce gerçekleşirse) geçerlidir. Diğer uzantılar, yeni oluşturulan bu sabitleyiciyi birden fazla XrSession'da kalıcı hale getirmek veya işlem sınırları genelinde diğer uygulamalarla paylaşmak için işlevler sunabilir.

Yeni oluşturulan bir sabitleyici, yok edilene kadar üst uzamsal bağlamında bulunabilir olmalıdır. Bu, çalışma zamanının, yer işareti XrSpatialDiscoverySnapshotCreateInfoEXT içinde ayarlanan keşif ölçütleriyle eşleşiyorsa spatialContext için xrCreateSpatialDiscoverySnapshotAsyncEXT kullanılarak oluşturulan anlık görüntüye anchorEntityId öğesini eklemesi gerektiği anlamına gelir. Yeni oluşturulan sabitleyici, XR_SPATIAL_CAPABILITY_ANCHOR_EXT ile yapılandırılmış diğer uzamsal bağlamlarda da keşfedilebilir olabilir. Ancak belirli bir XrSpatialEntityIdEXT, XrSpatialContextEXT'e özgü olduğundan farklı bir XrSpatialEntityIdEXT ile keşfedilebilir.

Geçerli Kullanım (Dolaylı)

  • XR_EXT_spatial_anchor uzantısı, xrCreateSpatialAnchorEXT çağrılmadan önce etkinleştirilmelidir
  • 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
  • anchorEntity, bir XrSpatialEntityEXT tutamacına işaretçi 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_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID (XR_ANDROID_spatial_entity_bound_anchor etkinse)
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT (XR_ANDROID_spatial_entity_bound_anchor etkinse)

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

typedef struct XrSpatialAnchorCreateInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrPosef            pose;
} XrSpatialAnchorCreateInfoEXT;

Ü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.
  • baseSpace, pose öğesinin uygulandığı XrSpace'tir.
  • time, baseSpace'nin bulunduğu (ve pose'nin uygulandığı) XrTime değeridir.
  • pose, sabitleme varlığının konumudur.

Geçerli Kullanım (Dolaylı)

Sorgu Sabit Noktası Pozu

Sabit nokta oluşturulduktan sonra çalışma zamanı, sabit noktanın orijinal gerçek dünya konumuna mümkün olan en iyi şekilde hizalanmasını sağlamak için zaman içinde diğer alanlara göre konumunu ve yönünü ayarlamalıdır (should). Bu işlem, sabit noktanın başlatmak için kullanılan orijinal XrSpatialAnchorCreateInfoEXT :: baseSpace ile ilişkisini değiştirse bile geçerlidir.

Uygulama, yeni bir XrSpatialSnapshotEXT oluşturmak için sabitleyicinin XrSpatialEntityEXT ile xrCreateSpatialUpdateSnapshotEXT'yi kullanabilir ve ardından xrQuerySpatialComponentDataEXT kullanarak bu anlık görüntüden XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT bileşenini sorgulayabilir. Uygulama, bağlantı noktalarının en son konum verilerini almak için XrSpatialComponentDataQueryResultEXT :: next öğesine XrSpatialComponentAnchorListEXT ekleyebilir.

Çalışma zamanı, yeni oluşturulan bir sabitin izleme durumunu XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT olarak ayarlayabilir. Uygulama, yalnızca XrSpatialComponentDataQueryResultEXT :: entityStates içinde sağlanan sabitleme öğesinin durumunu ve izleme durumu XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT ise öğenin sabitleme bileşeni verilerini okumalıdır (must).

Sabit reklamları kullanmayla ilgili yönergeler

  • Her bir sabitleyicinin pozu, diğer sabitleyicilerden veya alanlardan bağımsız olarak ayarlanır. Ayrı ayrı sabitlenmiş sanal nesneler birbirlerine göre kayabilir veya dönebilir. Bu durum, sanal nesnelerin birbirlerine göre yerinde kalması beklenen durumlarda uzamsal hiyerarşiyi bozabilir. Bu gibi durumlarda uygulama, birbirine göre hareket etmeyen tüm sanal nesneler için aynı sabitleyiciyi yeniden kullanmalıdır.
  • Uygulama, artık kullanılmayan sabitleyiciler için tüm XrSpatialEntityEXT tutamaçlarını yok etmelidir. Böylece çalışma zamanının bu sabitleyicileri izlemek için kullanabileceği kaynaklar serbest bırakılır.

Örnek Kod

Sabit Reklam Özelliğini Yapılandırma

Aşağıdaki örnekte, uzamsal bağlam oluştururken sabitleme özelliğinin nasıl yapılandırılacağı gösterilmektedir.

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{

  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = completion.spatialContext;
}

// ...
// Create spatial anchors and get their latest pose in the frame loop.
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Uzamsal yer işareti oluşturma ve konumunu alma

Aşağıdaki örnekte, uzamsal yer işaretinin nasıl oluşturulacağı ve her karede pozunun nasıl alınacağı gösterilmektedir.

XrSpatialAnchorCreateInfoEXT createInfo{XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT};
createInfo.baseSpace = localSpace;
createInfo.time = predictedDisplayTime;
createInfo.pose = {{0, 0, 0, 1}, {1, 1, 1}};

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpatialEntityEXT spatialAnchorEntity;
CHK_XR(xrCreateSpatialAnchorEXT(spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorEntity));

auto updateAnchorLocation = [&](XrTime time) {
  // We want to get updated data for all components of the entities, so skip specifying componentTypes.
  XrSpatialUpdateSnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.entityCount = 1;
  snapshotCreateInfo.entities = &spatialAnchorEntity;
  snapshotCreateInfo.baseSpace = localSpace;
  snapshotCreateInfo.time = time;

  XrSpatialSnapshotEXT snapshot;
  CHK_XR(xrCreateSpatialUpdateSnapshotEXT(spatialContext, &snapshotCreateInfo, &snapshot));

  // Query for the entities that have the anchor component on them.
  std::array<XrSpatialComponentTypeEXT, 1> componentsToQuery {XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT};
  XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
  queryCond.componentTypeCount = componentsToQuery.size();
  queryCond.componentTypes = componentsToQuery.data();

  XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
  CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

  std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
  std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
  queryResult.entityIdCapacityInput = entityIds.size();
  queryResult.entityIds = entityIds.data();
  queryResult.entityStateCapacityInput = entityStates.size();
  queryResult.entityStates = entityStates.data();

  // query for the pose data
  std::vector<XrPosef> locations(queryResult.entityIdCountOutput);
  XrSpatialComponentAnchorListEXT locationList{XR_TYPE_SPATIAL_COMPONENT_ANCHOR_LIST_EXT};
  locationList.locationCount = locations.size();
  locationList.locations = locations.data();
  queryResult.next = &locationList;

  CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

  for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
    if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
      // Pose for entity entityIds[i] is locations[i].
    }
  }

  CHK_XR(xrDestroySpatialSnapshotEXT(snapshot));
};


while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  updateAnchorLocation(time);

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

CHK_XR(xrDestroySpatialEntityEXT(spatialAnchorEntity));

Yeni Komutlar

Yeni Yapılar

Yeni Enum Sabitleri

  • XR_EXT_SPATIAL_ANCHOR_EXTENSION_NAME
  • XR_EXT_spatial_anchor_SPEC_VERSION

  • XrSpatialCapabilityEXT'yi genişletme:

    • XR_SPATIAL_CAPABILITY_ANCHOR_EXT

  • XrSpatialComponentTypeEXT'yi genişletme:

    • XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

  • XrStructureType'ı genişletme:

    • XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT
    • XR_TYPE_SPATIAL_COMPONENT_ANCHOR_LIST_EXT

Sayılar

  • xrCreateSpatialAnchorEXT neden bir varlık kimliğinin yanı sıra bir varlık herkese açık kullanıcı adı da döndürür?

    • Çözüldü
    • Cevap: xrCreateSpatialAnchorEXT işlevi, çıkış olarak yalnızca varlık kimliğini sağlayabilir ve uygulamalar, xrCreateSpatialEntityFromIdEXT işlevini kullanarak bu kimlik için bir varlık tutma yeri oluşturabilir. Ancak uygulamaların her karede sabitleyici pozunu sorguladığı tipik bir sabitleyici kullanımı göz önüne alındığında, giriş olarak varlık tutamaçları gerektiren bir "güncelleme anlık görüntüsünde" kullanılmak için iyi bir aday haline gelir. Bu tipik kullanım alanını öngören xrCreateSpatialAnchorEXT, uygulama adına xrCreateSpatialEntityFromIdEXT işlemini gerçekleştirir ve xrCreateSpatialUpdateSnapshotEXT ile kullanılacak varlık tutma yerini sağlar.

Sürüm Geçmişi

  • 1. düzeltme, 10.07.2024 (Nihav Jain, Google)

    • İlk uzantı açıklaması