XR_ANDROID_spatial_anchor_space

رشته نام

XR_ANDROID_spatial_anchor_space

نوع افزونه

افزونه نمونه

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

۷۹۶ عدد

بازنگری

۱

وضعیت تصویب

تصویب نشده

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

XR_EXT_spatial_anchor

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

۲۰۲۵-۰۹-۱۵

وضعیت آی‌پی

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

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

یوشنگ چانگ، گوگل
کایل چن، گوگل
لوانا چن، گوگل
نیهاو جین، گوگل
اسپنسر کوئین، گوگل

نمای کلی

تابع xrCreateSpatialAnchorEXT که در افزونه‌ی XR_EXT_spatial_anchor تعریف شده است، به برنامه‌ها اجازه می‌دهد تا لنگرهای مکانی را با استفاده از یک دستگیره‌ی XrSpatialEntityEXT برای نمایش آن ایجاد کنند. در مقابل، این افزونه یک لنگر مکانی ایجاد می‌کند که به جای آن توسط یک دستگیره‌ی XrSpace نمایش داده می‌شود. این برای مواردی مفید است که برنامه می‌خواهد:

• برای بدست آوردن موقعیت لنگر از xrLocateSpaces استفاده کنید.
• فضاهای دیگر را نسبت به لنگر پیدا کنید.
• با استفاده از XR_ANDROID_anchor_sharing_export انکر را اکسپورت کنید.
• برنامه لنگرهایی (anchors) قرار داده است و اکنون فقط به مکان لنگرها (برای اتصال محتوای مجازی) اهمیت می‌دهد و به هیچ مؤلفه دیگری از موجودیت‌های دیگر که از طریق XrSpatialContextEXT مورد استفاده برای ایجاد لنگر کشف شده است، اهمیتی نمی‌دهد و در نتیجه به برنامه اجازه می‌دهد تا زمینه مکانی را از بین ببرد.

انکرهای ایجاد شده با این افزونه را نمی‌توان با استفاده از افزونه XR_ANDROID_device_anchor_persistence ذخیره کرد و برنامه باید در عوض از XR_EXT_spatial_persistence_operations استفاده کند. اگر XrPersistedAnchorSpaceInfoANDROID :: anchor با استفاده از xrCreateSpatialAnchorSpaceANDROID یا xrCreateSpatialAnchorSpaceFromIdANDROID ایجاد شده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE از xrPersistAnchorANDROID برگرداند.

ایجاد XrSpace برای یک لنگر مکانی

یک لنگر و فضای مکانی ایجاد کنید

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

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

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

• session یک هندل برای XrSession است که قبلاً با xrCreateSession ایجاد شده است.
• spatialContext یک XrSpatialContextEXT است که قبلاً با استفاده از xrCreateSpatialContextAsyncEXT ایجاد شده است.
• createInfo یک اشاره‌گر به XrSpatialAnchorCreateInfoEXT است.
• anchorEntityId یک اشاره‌گر به XrSpatialEntityIdEXT است.
• anchorSpace یک اشاره‌گر به XrSpace است.

تابع xrCreateSpatialAnchorSpaceANDROID یک anchor ایجاد می‌کند که یک XrSpatialEntityIdEXT و یک هندل XrSpace را خروجی می‌دهد. xrCreateSpatialAnchorSpaceANDROID همان الزامات اعتبارسنجی xrCreateSpatialAnchorEXT را دارد.

اگر XrSpatialContextEXT ارسال شده به xrCreateSpatialAnchorSpaceANDROID با XR_SPATIAL_CAPABILITY_ANCHOR_EXT پیکربندی نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

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

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

• افزونه‌ی XR_ANDROID_spatial_anchor_space باید قبل از فراخوانی xrCreateSpatialAnchorSpaceANDROID فعال شود.
• session باید یک دسته XrSession معتبر باشد
• spatialContext باید یک هندل معتبر XrSpatialContextEXT باشد.
• createInfo باید یک اشاره‌گر به ساختار معتبر XrSpatialAnchorCreateInfoEXT باشد.
• anchorEntityId باید یک اشاره‌گر به مقدار XrSpatialEntityIdEXT باشد.
• anchorSpace باید یک اشاره‌گر به یک هندل XrSpace باشد.
• spatialContext باید از session ایجاد، تخصیص یا بازیابی شده باشد

کدهای بازگشت

موفقیت

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

شکست

• 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_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
• XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

ایجاد XrSpace از یک لنگر مکانی موجود

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

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

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

• session یک هندل برای XrSession است که قبلاً با xrCreateSession ایجاد شده است.
• spatialContext یک XrSpatialContextEXT است که قبلاً با استفاده از xrCreateSpatialContextAsyncEXT ایجاد شده است.
• createInfo یک اشاره‌گر به XrSpatialAnchorSpaceFromIdCreateInfoANDROID است.
• anchorSpace یک اشاره‌گر به XrSpace است.

در سناریوهایی که موجودیت‌های لنگر مکانی از قبل وجود دارند (مثلاً به دلیل پایداری)، برنامه‌ها می‌توانند با ارائه شناسه‌های موجودیت مکانی خود، یک XrSpace از این لنگرهای مکانی ایجاد کنند.

تابع xrCreateSpatialAnchorSpaceFromIdANDROID با ارائه XrSpatialEntityIdEXT در فیلد XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId، یک دستگیره XrSpace ایجاد می‌کند.

اگر XrSpatialContextEXT ارسال شده به xrCreateSpatialAnchorSpaceFromIdANDROID با XR_SPATIAL_CAPABILITY_ANCHOR_EXT پیکربندی نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

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

• افزونه‌ی XR_ANDROID_spatial_anchor_space باید قبل از فراخوانی xrCreateSpatialAnchorSpaceFromIdANDROID فعال شود.
• session باید یک دسته XrSession معتبر باشد
• spatialContext باید یک هندل معتبر XrSpatialContextEXT باشد.
• createInfo باید یک اشاره‌گر به ساختار معتبر XrSpatialAnchorSpaceFromIdCreateInfoANDROID باشد.
• anchorSpace باید یک اشاره‌گر به یک هندل XrSpace باشد.
• spatialContext باید از session ایجاد، تخصیص یا بازیابی شده باشد

کدهای بازگشت

موفقیت

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

شکست

• XR_ERROR_FUNCTION_UNSUPPORTED
• 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_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID
• XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
• XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

توضیحات اعضا

• type نوع XrStructureType این ساختار است.
• next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
• anchorEntityId ، XrSpatialEntityIdEXT مربوط به anchor فضایی موجود است که XrSpace از روی آن ایجاد می‌شود.

اگر XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId یک شناسه معتبر برای spatialContext نباشد، زمان اجرا باید XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT را برگرداند.

اگر XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId یک شناسه موجودیت معتبر برای یک anchor نباشد، زمان اجرا باید XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID را برگرداند.

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

• قبل از استفاده از XrSpatialAnchorSpaceFromIdCreateInfoANDROID، افزونه‌ی XR_ANDROID_spatial_anchor_space باید فعال باشد.
• type باید XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID باشد.
• next باید NULL یا یک اشاره‌گر معتبر به ساختار بعدی در یک زنجیره ساختار باشد.

چرخه حیات انکر

والد یک دستگیره XrSpace، یک XrSession است. این بدان معناست که یک دستگیره XrSpace که نمایانگر لنگر است، حتی پس از از بین رفتن xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext یا xrCreateSpatialAnchorSpaceANDROID :: spatialContext معتبر باقی می‌ماند. ایجاد یک XrSpace برای نشان دادن یک لنگر موجودیت مکانی، به برنامه اجازه می‌دهد تا XrSpatialContextEXT را که با XR_SPATIAL_CAPABILITY_ANCHOR_EXT پیکربندی شده است، از بین ببرد و در عین حال همچنان به دریافت آخرین حالت لنگر با استفاده از XrSpace آن با xrLocateSpaces ادامه دهد، یعنی زمان اجرا باید به ردیابی لنگر ادامه دهد تا زمانی که تمام دستگیره‌های XrSpace که نمایانگر آن هستند، از بین بروند.

کد مثال

ایجاد لنگر مکانی به عنوان XrSpace

کد مثال زیر نحوه ایجاد یک لنگر مکانی و بازگرداندن آن به عنوان XrSpace را نشان می‌دهد.

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

ایجاد XrSpace از شناسه موجودیت لنگر

کد مثال زیر نحوه ایجاد XrSpace را از یک شناسه موجودیت لنگر از پیش موجود نشان می‌دهد.

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

دستورات جدید

• xrCreateSpatialAnchorSpaceANDROID
• xrCreateSpatialAnchorSpaceFromIdANDROID

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

• XrSpatialAnchorSpaceFromIdCreateInfoANDROID

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

• XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
• XR_ANDROID_spatial_anchor_space_SPEC_VERSION

• بسط XrResult :

  • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

• گسترش XrStructureType :

  • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

مسائل

تاریخچه نسخه

• بازبینی 1، 15/09/2025 (یوشنگ چانگ، کایل چن)

  • توضیحات اولیه افزونه