لنگر مکانی-جغرافیایی XR_ANDROID

رشته نام

XR_ANDROID_geospatial_anchor

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

798

بازنگری

۱

وضعیت تصویب

تصویب نشده

وابستگی‌های افزونه و نسخه

XR_ANDROID_geospatial
و
XR_EXT_future
و
XR_EXT_spatial_entity
و
XR_EXT_spatial_anchor

آخرین تاریخ اصلاح

۲۰۲۵-۱۰-۳۰

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

جان اولمن، گوگل
بن کینگ، گوگل
نیهاو جین، گوگل
جارد فایندر، گوگل

نمای کلی

این افزونه، لنگرهای مکانی و لنگرهای سطحی را ارائه می‌دهد که بر اساس افزونه مکانی پایه ساخته می‌شوند. لنگرهای مکانی لنگرهایی هستند که در فضا نسبت به زمین در عرض جغرافیایی، طول جغرافیایی و ارتفاع مشخص قرار می‌گیرند. لنگرهای سطحی، لنگرهای نسبی به زمین هستند که در عرض جغرافیایی، طول جغرافیایی و ارتفاع مشخص نسبت به سطحی که توسط سرویس موقعیت‌یابی بصری شناخته می‌شود، قرار می‌گیرند. با بهبود دقت زمان اجرا در موقعیت آن نسبت به زمین، موقعیت لنگر نیز متناسب با آن تنظیم می‌شود.

قابلیت سیستم برای لنگرهای مکانی

ساختار XrSystemGeospatialAnchorPropertiesANDROID به صورت زیر تعریف می‌شود: 

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • maxSurfaceAnchorCount یک uint32_t است که حداکثر تعداد لنگرهای سطحی قابل ایجاد را نشان می‌دهد.

یک برنامه می‌تواند با اتصال ساختار XrSystemGeospatialAnchorPropertiesANDROID به XrSystemProperties هنگام فراخوانی xrGetSystemProperties ، قابلیت‌های لنگر مکانی سیستم را بررسی کند.

اگر XrSystemGeospatialPropertiesANDROID :: supportsGeospatial برابر با XR_TRUE باشد، آنگاه maxSurfaceAnchorCount حداکثر تعداد لنگرهای سطحی پشتیبانی شده توسط زمان اجرا را نشان می‌دهد. در این حالت، حد مجاز باید بزرگتر از 0 باشد.

اگر XrSystemGeospatialPropertiesANDROID :: supportsGeospatial برابر XR_TRUE نباشد، آنگاه maxSurfaceAnchorCount باید 0 باشد.

کاربرد معتبر (ضمنی)

ردیابی هواپیما برای لنگرها

ساختار XrGeospatialTrackerAnchorTrackingInfoANDROID به صورت زیر تعریف شده است: 

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
  • shouldTrackPlanes یک XrBool32 است که نشان می‌دهد آیا ردیاب مکانی، صفحات را ردیابی می‌کند تا موقعیت‌یابی لنگرهای قفل‌شده روی سطح را بهبود بخشد یا خیر.

ردیابی صفحه‌ای را می‌توان برای بهبود موقعیت‌یابی لنگرهای قفل‌شده روی سطح فعال کرد.

اگر برنامه بخواهد ردیابی صفحه‌ای را برای بهبود حالت‌های لنگر سطحی فعال کند، می‌تواند هنگام فراخوانی xrCreateGeospatialTrackerANDROID ، یک ساختار XrGeospatialTrackerAnchorTrackingInfoANDROID را به XrGeospatialTrackerCreateInfoANDROID زنجیر کند.

کاربرد معتبر (ضمنی)

لنگرهای جغرافیایی

تابع xrCreateGeospatialAnchorANDROID به صورت زیر تعریف می‌شود: 

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

توضیحات پارامتر

  • spatialContext همان XrSpatialContextEXT است که قرار است anchor را در آن ایجاد کند. context باید برای XR_SPATIAL_CAPABILITY_ANCHOR_EXT پیکربندی شود، در غیر این صورت زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.
  • createInfo یک اشاره‌گر به XrGeospatialAnchorCreateInfoANDROID است که حاوی پارامترهای ایجاد anchor می‌باشد.
  • anchorEntityId یک اشاره‌گر به XrSpatialEntityIdEXT است که در آن شناسه موجودیت لنگر بازگردانده می‌شود.

اگر XrGeospatialTrackerANDROID مشخص شده در XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker در حالت XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID نباشد، زمان اجرا باید XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID برگرداند.

کاربرد معتبر (ضمنی)

  • افزونه‌ی XR_ANDROID_geospatial_anchor باید قبل از فراخوانی xrCreateGeospatialAnchorANDROID فعال شود.
  • spatialContext باید یک هندل معتبر XrSpatialContextEXT باشد.
  • createInfo باید یک اشاره‌گر به ساختار معتبر XrGeospatialAnchorCreateInfoANDROID باشد.
  • anchorEntityId باید یک اشاره‌گر به مقدار XrSpatialEntityIdEXT باشد.

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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 به صورت زیر تعریف می‌شود: 

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
  • geospatialTracker همان XrGeospatialTrackerANDROID است که برای ایجاد لنگر استفاده می‌شود.
  • geospatialPose یک اشاره‌گر به XrGeospatialPoseANDROID است که مکان و جهت لنگر را تعریف می‌کند.

کاربرد معتبر (ضمنی)

لنگرهای سطحی

لنگرهای سطحی، لنگرهایی هستند که نسبت به یک سطح، مانند زمین یا پشت بام‌ها، قرار می‌گیرند.

نوع شمارشی XrSurfaceAnchorTypeANDROID به صورت زیر تعریف می‌شود: 

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 نوع سطحی را که یک anchor به آن نسبت دارد، مشخص می‌کند.

شمارشگرها مقادیر زیر را دارند:

توضیحات شمارشی

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

نوع لنگری که نسبت به زمین قرار می‌گیرد.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

نوعی لنگر که نسبت به پشت بام یا زمینی که ساختمانی در آن نیست، قرار می‌گیرد.

تابع xrCreateSurfaceAnchorAsyncANDROID به صورت زیر تعریف می‌شود: 

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

توضیحات پارامتر

  • spatialContext همان XrSpatialContextEXT است که برای ایجاد anchor در آن استفاده می‌شود.
  • createInfo یک اشاره‌گر به XrSurfaceAnchorCreateInfoANDROID است که حاوی پارامترهای ایجاد anchor می‌باشد.
  • future یک اشاره‌گر به XrFutureEXT است که نتیجه عملیات ناهمزمان را در خود نگه می‌دارد.

تابع xrCreateSurfaceAnchorAsyncANDROID یک عملیات ناهمزمان را برای ایجاد یک لنگر سطحی آغاز می‌کند. برخلاف لنگرهای زمینی استاندارد، زمان اجرا ممکن است داده‌های زمین را برای تعیین ارتفاع صحیح دریافت کند. اگر برنامه سعی کند بیش از XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount لنگرهای سطحی را در یک زمان ایجاد کند، زمان اجرا باید XR_ERROR_LIMIT_REACHED برگرداند. اگر XrGeospatialTrackerANDROID مشخص شده در XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker در حالت XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID نباشد، زمان اجرا باید XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID برگرداند. اگر هیچ داده سطحی برای مکان داده شده وجود نداشته باشد، ممکن است عملیات به صورت غیرهمزمان با نتیجه XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID با شکست مواجه شود. اگر XR_SPATIAL_CAPABILITY_ANCHOR_EXT برای spatialContext پیکربندی نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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 به صورت زیر تعریف شده است: 

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
  • geospatialTracker همان XrGeospatialTrackerANDROID است که باید از آن استفاده کنید.
  • surfaceAnchorType همان XrSurfaceAnchorTypeANDROID برای لنگر است.
  • eastUpSouthOrientation جهت‌گیری نسبت به یک سیستم مختصات است که در آن +X=شرق، +Y=بالا و +Z=جنوب.
  • latitude ، عرض جغرافیایی بر حسب درجه است که بین ۸۹.۹- و ۸۹.۹+ قرار دارد.
  • longitude ، طول جغرافیایی بر حسب درجه است که بین ۱۸۰- و ۱۸۰+ قرار دارد.
  • altitudeRelativeToSurface ارتفاع بر حسب متر نسبت به سطح مشخص شده توسط surfaceAnchorType است.

کاربرد معتبر (ضمنی)

  • قبل از استفاده از XrSurfaceAnchorCreateInfoANDROID، افزونه‌ی XR_ANDROID_geospatial_anchor باید فعال باشد.
  • type باید XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID باشد.
  • next باید NULL یا یک اشاره‌گر معتبر به ساختار بعدی در یک زنجیره ساختار باشد.
  • geospatialTracker باید یک شناسه معتبر XrGeospatialTrackerANDROID باشد
  • surfaceAnchorType باید یک مقدار معتبر XrSurfaceAnchorTypeANDROID باشد.
  • latitude باید یک مقدار double معتبر باشد
  • longitude باید یک مقدار double معتبر باشد.
  • altitudeRelativeToSurface باید یک مقدار double معتبر باشد.

تابع xrCreateSurfaceAnchorCompleteANDROID به صورت زیر تعریف می‌شود: 

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

توضیحات پارامتر

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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 نتیجه‌ی ایجاد یک anchor سطحی ناهمزمان را در خود نگه می‌دارد. 

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
  • futureResult ، XrResult عملیات ایجاد است. اگر futureResult برابر با XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID باشد، ساختاری در زنجیره next ممکن است اطلاعات بیشتری در مورد خرابی ارائه دهد.
  • anchorEntityId برابر با XrSpatialEntityIdEXT مربوط به anchor ایجاد شده است، یا اگر futureResult XR_SUCCESS نباشد، برابر با XR_NULL_SPATIAL_ENTITY_ID_EXT خواهد بود.

کدهای بازگشت آینده

مقادیر futureResult :

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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

کاربرد معتبر (ضمنی)

مثال

ایجاد لنگر زمینی 

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.
}

دستورات جدید

سازه‌های جدید

Enum های جدید

ثابت‌های شمارشی جدید

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION

  • بسط XrResult :

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

  • گسترش XrStructureType :

    • 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

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۵-۱۰-۳۰ (بن کینگ)

    • پیش‌نویس اولیه.