XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

Uzantı Türü

Örnek uzantısı

Kayıtlı Dahili Numara

798

Düzeltme

1

Onay Durumu

Onaylanmadı

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

XR_ANDROID_geospatial
ve
XR_EXT_future
ve
XR_EXT_spatial_entity
ve
XR_EXT_spatial_anchor

Son Değiştirilme Tarihi

2025-10-30

IP Durumu

Bilinen bir fikri mülkiyet hak talebi yok.

Katkıda bulunanlar

John Ullman, Google
Ben King, Google
Nihav Jain, Google
Jared Finder, Google

Genel Bakış

Bu uzantı, temel Geospatial uzantısını temel alan Geospatial Anchors ve Surface Anchors sağlar. Coğrafi sabitleyiciler, belirli bir enlem, boylam ve rakımda Dünya'ya göre uzayda konumlandırılan sabitleyicilerdir. Yüzey sabitleri, Görsel Konumlandırma Hizmeti tarafından bilinen bir yüzeye göre belirli bir enlem, boylam ve rakıma yerleştirilen, Dünya'ya göre sabitlerdir. Çalışma zamanının Dünya'ya göre konumunun doğruluğu arttıkça sabitleyicinin pozu da buna göre ayarlanır.

Coğrafi Yer İşaretleri İçin Sistem Özelliği

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

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

Ü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. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • maxSurfaceAnchorCount, oluşturulabilecek maksimum yüzey sabitleyici sayısını gösteren bir uint32_t değeridir.

Uygulamalar, xrGetSystemProperties işlevini çağırırken XrSystemProperties yapısına bir XrSystemGeospatialAnchorPropertiesANDROID yapısı ekleyerek sistemin coğrafi konum sabitleyici özelliklerini inceleyebilir.

XrSystemGeospatialPropertiesANDROID :: supportsGeospatial, XR_TRUE ise maxSurfaceAnchorCount, çalışma zamanının desteklediği maksimum yüzey sabitleyici sayısını gösterir. Bu durumda sınır 0'dan büyük olmalıdır.

XrSystemGeospatialPropertiesANDROID :: supportsGeospatial, XR_TRUE değilse maxSurfaceAnchorCount 0 olmalıdır.

Geçerli Kullanım (Dolaylı)

Sabitler için düzlem izleme

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

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

Ü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.
  • shouldTrackPlanes, coğrafi konum izleyicinin yüzeye kilitli sabitleyicilerin konumunu iyileştirmek için düzlemleri izleyip izlemeyeceğini belirten bir XrBool32 değeridir.

Yüzeye kilitli sabit noktaların konumunu iyileştirmek için düzlem izleme etkinleştirilebilir.

Uygulama, yüzey sabitleyici pozlarını iyileştirmek için düzlem izlemeyi etkinleştirmek istiyorsa xrCreateGeospatialTrackerANDROID'i çağırırken XrGeospatialTrackerAnchorTrackingInfoANDROID yapısını XrGeospatialTrackerCreateInfoANDROID'e zincirleyebilir.

Geçerli Kullanım (Dolaylı)

Geospatial Anchors

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

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

Parametre Açıklamaları

  • spatialContext, sabitleyicinin oluşturulacağı XrSpatialContextEXT'tir. Bağlam XR_SPATIAL_CAPABILITY_ANCHOR_EXT için yapılandırılmış olmalıdır. Aksi takdirde çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.
  • createInfo, sabitleme noktası oluşturma parametrelerini içeren XrGeospatialAnchorCreateInfoANDROID'e işaret eden bir göstergedir.
  • anchorEntityId, sabitleme varlığı kimliğinin döndürüldüğü XrSpatialEntityIdEXT için bir işaretçidir.

XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker içinde belirtilen XrGeospatialTrackerANDROID, XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID durumunda değilse çalışma zamanı XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID 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_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • 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_VALIDATION_FAILURE

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

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

Ü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.
  • geospatialTracker, sabitleyiciyi oluşturmak için kullanılacak XrGeospatialTrackerANDROID'dir.
  • geospatialPose, sabitleyicinin konumunu ve yönünü tanımlayan XrGeospatialPoseANDROID'e işaret eden bir göstergedir.

Geçerli Kullanım (Dolaylı)

Yüzey Bağlantıları

Yüzey sabitleyiciler, arazi veya çatı gibi bir yüzeye göre yerleştirilen sabitleyicilerdir.

XrSurfaceAnchorTypeANDROID numaralandırması şu şekilde tanımlanır:

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

XrSurfaceAnchorTypeANDROID sıralaması, bir sabitin ilişkili olduğu yüzey türünü belirtir.

Numaralandırıcılar aşağıdaki değerlere sahiptir:

Enum Açıklaması

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Zemine göre yerleştirilen bir sabitin türü.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Çatıya veya bina olmayan yerlerde zemine göre yerleştirilen bir sabitin türü.

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

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

Parametre Açıklamaları

  • spatialContext, sabitleyicinin oluşturulacağı XrSpatialContextEXT'tir.
  • createInfo, sabitleyici oluşturma parametrelerini içeren XrSurfaceAnchorCreateInfoANDROID'e işaret eden bir işaretçidir.
  • future, eşzamansız işlemin sonucunu tutacak olan XrFutureEXT için bir işaretçidir.

xrCreateSurfaceAnchorAsyncANDROID işlevi, yüzey sabitleyici oluşturmak için eşzamansız bir işlem başlatır. Standart coğrafi sabitleyicilerin aksine, çalışma zamanı doğru rakımı belirlemek için arazi verilerini getirebilir. Uygulama, tek seferde XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount yüzey bağlantı noktasından fazlasını oluşturmaya çalışırsa çalışma zamanı XR_ERROR_LIMIT_REACHED değerini döndürmelidir (must). XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker içinde belirtilen XrGeospatialTrackerANDROID, XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID durumunda değilse çalışma zamanı XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID değerini döndürmelidir (must). Belirtilen konum için yüzey verisi yoksa işlem, XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID sonucuyla eşzamansız olarak başarısız olabilir. spatialContext için XR_SPATIAL_CAPABILITY_ANCHOR_EXT yapılandırılmadıysa ç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_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • 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_VALIDATION_FAILURE

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

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

Ü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.
  • geospatialTracker, kullanılacak XrGeospatialTrackerANDROID'dir.
  • surfaceAnchorType, sabitleyicinin XrSurfaceAnchorTypeANDROID değeridir.
  • eastUpSouthOrientation, +X=Doğu, +Y=Yukarı ve +Z=Güney olan bir koordinat sistemine göre yönü belirtir.
  • latitude, -89,9 ile +89,9 arasında derece cinsinden enlemdir.
  • longitude, -180 ile +180 arasında derece cinsinden boylamdır.
  • altitudeRelativeToSurface, surfaceAnchorType ile belirtilen yüzeye göre metre cinsinden yüksekliktir.

Geçerli Kullanım (Dolaylı)

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

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     completion);

Parametre Açıklamaları

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • 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_VALIDATION_FAILURE

XrSurfaceAnchorCreateCompletionANDROID yapısı, eşzamansız bir yüzey sabitleyici oluşturma işleminin sonucunu içerir.

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

Ü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.
  • futureResult, oluşturma işleminin XrResult değeridir. futureResult, XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID ise next zincirindeki bir yapı, hatayla ilgili daha fazla bilgi sağlayabilir.
  • anchorEntityId, oluşturulan sabitleyicinin XrSpatialEntityIdEXT değeridir veya futureResult, XR_SUCCESS değilse XR_NULL_SPATIAL_ENTITY_ID_EXT değeridir.

Gelecekteki İade Kodları

futureResult değer:

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Geçerli Kullanım (Dolaylı)

Örnek

Arazi Çapası Oluşturma

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a 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));

  // ... wait until future is ready ...

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

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

XrFuturePollInfoEXT anchorPollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT anchorPollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
anchorPollInfo.future = anchorFuture;
anchorPollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (anchorPollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &anchorPollInfo, &anchorPollResult));
}

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

Yeni Komutlar

Yeni Yapılar

Yeni Enum Veri Türleri

Yeni Enum Sabitleri

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION

  • XrResult'ı genişletme:

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

  • XrStructureType'ı genişletme:

    • XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

Sorunlar

Sürüm Geçmişi

  • Düzeltme 1, 30.10.2025 (Ben King)

    • İlk taslak.