XR_ANDROID_spatial_anchor_space

رشته نام

XR_ANDROID_spatial_anchor_space

نوع افزونه

افزونه نمونه

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

796

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

XR_EXT_spatial_anchor

تاریخ آخرین تغییر

2025-09-15

وضعیت IP

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

همیاران

YuSheng Chang،‏ Google
Kyle Chen،‏ Google
Levana Chen،‏ Google
Nihav Jain،‏ Google
Spencer Quin،‏ Google

نمای کلی

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

• از xrLocateSpaces برای دریافت مکان لنگر استفاده کنید.
• مکان‌یابی فضاهای دیگر نسبت‌به لنگر.
• لنگر را بااستفاده از XR_ANDROID_anchor_sharing_export صادر کنید.
• برنامه لنگرهایی را قرار داده است و اکنون فقط به مکان لنگرها (برای پیوست کردن محتوای مجازی به آن‌ها) اهمیت می‌دهد و به هیچ مؤلفه دیگری از هیچ موجودیت دیگری که ازطریق 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 یک لنگر ایجاد می‌کند که یک 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 لنگر فضایی موجود که XrSpace از آن ایجاد می‌شود.

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

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

استفاده معتبر (ضمنی)

• افزونه XR_ANDROID_spatial_anchor_space باید قبل‌از استفاده از XrSpatialAnchorSpaceFromIdCreateInfoANDROID فعال شود
• 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

مشکلات

سابقه نسخه

• بازبینی ۱،‏ ۲۰۲۵/۰۹/۱۵ (YuSheng Chang،‏ Kyle Chen)

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