XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı Numarası

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 IP hak talebi yok.

Katkıda bulunanlar

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

Genel Bakış

Bu uzantı, temel Coğrafi uzantı üzerine kurulu Coğrafi Sabitleyiciler ve Yüzey Sabitleyiciler 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 yükseklikte 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 Anchor'ın duruşu da buna göre ayarlanır.

Coğrafi sabitleme iç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'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • maxSurfaceAnchorCount, oluşturulabilecek maksimum yüzey tutturucu sayısını gösteren bir uint32_t değeridir.

Bir uygulama, xrGetSystemProperties çağrılırken XrSystemGeospatialAnchorPropertiesANDROID yapısını XrSystemProperties'e zincirleyerek sistemin coğrafi uzamsal sabitleme özelliklerini inceleyebilir .

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

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

Geçerli Kullanım (Dolaylı)

Sabitleme için düzlem takibi

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'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • shouldTrackPlanes, XrBool32 olup uzamsal izleyicinin, yüzeye kilitlenmiş bağlantı noktalarının konumunu iyileştirmek için düzlemleri izleyip izlemeyeceğini gösterir.

Yüzeye kilitlenmiş tutturucuların konumlandırılmasını iyileştirmek için düzlem takibi etkinleştirilebilir.

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

Geçerli Kullanım (Dolaylı)

Coğrafi Sabitleyiciler

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

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

Parametre Açıklamaları

  • spatialContext, sabitleme noktasının oluşturulacağı XrSpatialContextEXT'dir. 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 oluşturma parametrelerini içeren XrGeospatialAnchorCreateInfoANDROID işaretçisidir.
  • anchorEntityId, sabitleme varlık kimliğinin döndürüldüğü XrSpatialEntityIdEXT öğesine yönelik bir işaretçidir.

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

Başarısız

  • 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_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'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • geospatialTracker, sabitleme noktası oluşturmak için kullanılacak XrGeospatialTrackerANDROID'dir.
  • geospatialPose, sabitleme noktasının konumunu ve yönünü tanımlayan XrGeospatialPoseANDROID işaretçisidir.

Geçerli Kullanım (Dolaylı)

Yüzey Ankrajları

Yüzey bağlantıları, arazi veya çatılar gibi bir yüzeye göre yerleştirilen bağlantılardır.

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 numaralandırması, bir sabitleme noktasının göreli olduğu yüzeyin türünü belirtir.

Numaralandırılmış değerler aşağıdaki değerlere sahiptir:

Enum Açıklaması

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Zemine göre yerleştirilmiş bir sabitleme noktasının türü.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

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

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

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

Parametre Açıklamaları

  • spatialContext, sabitleme noktasının oluşturulacağı XrSpatialContextEXT'dir.
  • createInfo, sabitleme oluşturma parametrelerini içeren XrSurfaceAnchorCreateInfoANDROID işaretçisidir.
  • future, eşzamansız işlemin sonucunu tutacak olan XrFutureEXT işaretçisidir.

xrCreateSurfaceAnchorAsyncANDROID işlevi, yüzey tutturucu oluşturmak için eşzamansız bir işlem başlatır. Standart coğrafi uzamsal bağlantı noktalarının aksine, çalışma zamanı doğru yüksekliği belirlemek için arazi verilerini getirebilir. Çalışma zamanı, uygulama aynı anda XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount yüzey tutturucudan fazla oluşturmaya çalışırsa XR_ERROR_LIMIT_REACHED değerini döndürmelidir. 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 . 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. Çalışma zamanı, spatialContext için XR_SPATIAL_CAPABILITY_ANCHOR_EXT yapılandırılmamışsa 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

Başarısız

  • 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_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'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • geospatialTracker, kullanılacak XrGeospatialTrackerANDROID'dir.
  • surfaceAnchorType, sabitleme için XrSurfaceAnchorTypeANDROID'dir.
  • eastUpSouthOrientation, +X=Doğu, +Y=Yukarı ve +Z=Güney olan bir koordinat sistemine göre yönlendirmedir.
  • 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

Başarısız

  • 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 yüzey tutturucu oluşturma işleminin sonucunu tutar.

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • futureResult, oluşturma işleminin XrResult'ıdır. futureResult XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID ise next zincirindeki bir yapı , hata hakkında daha fazla bilgi sağlayabilir.
  • anchorEntityId, oluşturulan bağlantının XrSpatialEntityIdEXT değeridir veya futureResult, XR_SUCCESS değilse XR_NULL_SPATIAL_ENTITY_ID_EXT değeridir .

Gelecekteki İade Kodları

futureResult değerleri:

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Başarısız

  • 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 Anchor'u 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 Sıralamalar

Yeni Numaralandırılmış Değer 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

  • 1. düzeltme, 30.10.2025 (Ben King)

    • İlk taslak.