XR_EXT_spatial_anchor

Name String

XR_EXT_spatial_anchor

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı Numarası

763

Düzeltme

1

Onay durumu

Onaylanma tarihi

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, kullanıcının fiziksel ortamındaki rastgele noktalar olan ve çalışma zamanı tarafından izlenen uzamsal bağlantılar oluşturmasına olanak tanır. Çalışma zamanı, gerçek dünyayla orijinal eşlemesini korumak için diğer tüm alanlardan ve sabit noktalardan bağımsız olarak zaman içinde sabit noktanın başlangıç noktasının konumunu ve yönünü gerektiği gibi ayarlamalıdır.

Bir XrSpatialContextEXT içindeki belirli bir konumu ve yönü izleyen bir sabit öğe, XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT bileşenine sahip bir uzamsal öğe olarak temsil edilir.

Bağlantı kullanmanın avantajı

Çalışma zamanının, XrSpatialContextEXT'nin yaşam döngüsü boyunca kullanıcının fiziksel ortamıyla ilgili anlayışı güncellendikçe sanal nesneler, uygulama tarafından yerleştirildikleri yerden uzaklaşıyormuş gibi görünebilir. Bu durum, uygulamanın gerçekçiliğini ve kullanıcının deneyiminin kalitesini etkiler. Bir sanal nesnenin yerleştirildiği yere yakın bir sabitleme noktası oluşturup bu sanal nesneyi her zaman sabitleme noktasına göre oluşturarak bir uygulama, 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 bağlantıları destekliyorsa xrEnumerateSpatialCapabilitiesEXT içinde XR_SPATIAL_CAPABILITY_ANCHOR_EXT numaralandırarak bunu belirtmelidir .

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'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • capability, XrSpatialCapabilityEXT'dir .
  • enabledComponentCount, enabledComponents dizisindeki öğelerin sayısını açıklayan bir uint32_t'dir.
  • enabledComponents, XrSpatialComponentTypeEXT dizisine yönelik bir işaretçidir .

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

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

Geçerli Kullanım (Dolaylı)

Garantili Bileşenler

XR_SPATIAL_CAPABILITY_ANCHOR_EXT 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 numaralandırmalıdır:

  • XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Sabit Bileşen

Bileşen Verileri

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT, verileri için XrPosef kullanır. Bu, sabitleme noktasının konumunu ve yönünü sağlar.

Verileri sorgulamak iç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'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • locationCount, locations dizisindeki öğelerin sayısını açıklayan bir uint32_t'dir.
  • locations, XrPosef dizisidir .

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

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

Geçerli Kullanım (Dolaylı)

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

Bazı özellikler için XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT, XrSpatialCapabilityComponentTypesEXT :: componentTypes içinde numaralandırılıyorsa bir uygulama, bu bileşeni destekleyen özelliğin XrSpatialCapabilityConfigurationBaseHeaderEXT türetilmiş yapısının XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents listesine numaralandırılmış değeri ekleyerek bu özelliği etkinleştirebilir.

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

Mekansal bağlantı 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 tutturma noktası oluşturabilir .

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

Çalışma zamanı, XR_SPATIAL_CAPABILITY_ANCHOR_EXT spatialContext için yapılandırılmamışsa xrCreateSpatialAnchorEXT işlevinden XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir . XR_SPATIAL_CAPABILITY_ANCHOR_EXT özelliği için XrSpatialContextEXT'yi nasıl yapılandıracağınızı öğrenmek için Yapılandırma bölümüne bakın.

anchorEntity ile gösterilen sabitleme yalnızca spatialContext ömrü boyunca veya uygulama üzerinde xrDestroySpatialEntityEXT çağrısı yapana kadar (hangisi önce gerçekleşirse) geçerlidir. Diğer uzantılar, yeni oluşturulan bu bağlantıyı birden fazla XrSession'da kalıcı hale getirme veya süreç sınırları içinde diğer uygulamalarla paylaşma işlevleri sunabilir.

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

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_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'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • baseSpace, pose öğesinin uygulandığı XrSpace'tir.
  • time, baseSpace konumunun bulunduğu (ve pose uygulandığı) XrTime'dir.
  • pose, ana tüzel kişinin bulunduğu yerdir.

Geçerli Kullanım (Dolaylı)

Sorgu Sabitleme Pozu

Sabitleme noktası oluşturulduktan sonra, çalışma zamanı, orijinal gerçek dünya konumuna mümkün olan en iyi hizalamayı korumak için zaman içinde konumunu ve yönünü diğer alanlara göre ayarlamalıdır. Bu durum, sabitleme noktasını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 sabitleme noktasının XrSpatialEntityEXT ile xrCreateSpatialUpdateSnapshotEXT işlevini kullanabilir ve ardından xrQuerySpatialComponentDataEXT işlevini kullanarak bu anlık görüntüden XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT bileşenini sorgulayabilir . Uygulama, sabitleme noktalarının en son konum verilerini almak için XrSpatialComponentDataQueryResultEXT :: next öğesine XrSpatialComponentAnchorListEXT öğesini ekleyebilir.

Çalışma zamanı, yeni oluşturulan bir sabitleyicinin izleme durumunu ayarlayabilir.XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT Uygulama, izleme durumu XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT ise XrSpatialComponentDataQueryResultEXT :: entityStates içinde sağlanan bağlantı öğesinin durumunu ve öğenin bağlantı öğesi verilerini okumalıdır .

Bağlantı Kullanma Kuralları

  • Her tutturucunun pozu, diğer tutturuculardan 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ı beklendiği durumlarda uzamsal hiyerarşinin bozulmasına neden olabilir. Bu gibi durumlarda uygulama, birbirine göre hareket etmeyen tüm sanal nesneler için aynı sabitleme noktasını yeniden kullanmalıdır.
  • Uygulama, çalışma zamanının bu tutturucuları izlemek için kullanabileceği kaynakları boşaltmak amacıyla artık kullanılmayan tutturucular için tüm XrSpatialEntityEXT tanıtıcılarını kaldırmalıdır.

Örnek Kod

Sabitleme özelliğini yapılandırma

Aşağıdaki örnekte, mekansal 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 Çapa Oluşturma ve Konumunu Alma

Aşağıdaki örnekte, uzamsal bağlantının 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 uzatılıyor :

    • XR_SPATIAL_CAPABILITY_ANCHOR_EXT

  • XrSpatialComponentTypeEXT'yi genişletme :

    • XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

  • XrStructureType uzatma :

    • XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT
    • XR_TYPE_SPATIAL_COMPONENT_ANCHOR_LIST_EXT

Sayılar

  • Neden xrCreateSpatialAnchorEXT, varlık kimliğinin yanı sıra varlık tutucusu da çıkış olarak veriyor?

    • Çözüldü
    • Yanıt: xrCreateSpatialAnchorEXT işlevi, çıkış olarak yalnızca varlık kimliğini sağlamış olabilir ve uygulamalar, xrCreateSpatialEntityFromIdEXT işlevini kullanarak bu kimlik için bir varlık tutacağı oluşturabilir . Ancak, uygulamaların her karede sabit duruş sorguladığı tipik bir sabit kullanımı göz önüne alındığında, "anlık görüntüyü güncelle" işleminde kullanılmak için iyi bir aday haline gelir. Bu işlem, giriş olarak öğe tutma yerlerini gerektirir. Bu tipik kullanım alanını öngören xrCreateSpatialAnchorEXT, uygulama adına xrCreateSpatialEntityFromIdEXT işlevini gerçekleştirir ve xrCreateSpatialUpdateSnapshotEXT ile kullanılacak öğe tutamacını sağlar .

Sürüm Geçmişi

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

    • İlk uzantı açıklaması