XR_ANDROID_spatial_anchor_space

Name String

XR_ANDROID_spatial_anchor_space

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

796

المراجعة

1

حالة التصديق

لم تتم المصادقة عليها

الاعتماد على الإضافات والإصدارات

XR_EXT_spatial_anchor

تاريخ آخر تعديل

2025-09-15

حالة الملكية الفكرية

ما مِن مطالبات معروفة بشأن الملكية الفكرية.

المساهمون

يو شينغ تشانغ، Google
كايل تشن، Google
ليفانا تشن، Google
نيهاف جاين، Google
سبنسر كوين، 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 بدلاً من ذلك. يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE من xrPersistAnchorANDROID إذا تم إنشاء XrPersistedAnchorSpaceInfoANDROID :: anchor باستخدام xrCreateSpatialAnchorSpaceANDROID أو xrCreateSpatialAnchorSpaceFromIdANDROID .

إنشاء XrSpace لمرساة مكانية

إنشاء نقطة تثبيت مكانية ومساحة

يتم تعريف الدالة xrCreateSpatialAnchorSpaceANDROID على النحو التالي:

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

أوصاف المَعلمات

تنشئ الدالة xrCreateSpatialAnchorSpaceANDROID نقطة ارتساء تُخرج XrSpatialEntityIdEXT ومؤشر XrSpace. تتطلّب الدالة xrCreateSpatialAnchorSpaceANDROID متطلبات التحقّق نفسها التي تتطلّبها الدالة xrCreateSpatialAnchorEXT .

يجب أن تعرض بيئة التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم يتم ضبط XrSpatialContextEXT الذي تم تمريره إلى xrCreateSpatialAnchorSpaceANDROID باستخدام XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

في ما يتعلق بإمكانية العثور على نقطة الارتكاز التي تم إنشاؤها بواسطة xrCreateSpatialAnchorSpaceANDROID، تنطبق الفقرة الأخيرة من مواصفات xrCreateSpatialAnchorEXT.

الاستخدام الصالح (ضمني)

  • يجب تفعيل إضافة XR_ANDROID_spatial_anchor_space قبل استدعاء xrCreateSpatialAnchorSpaceANDROID
  • يجب أن يكون session اسم معرِّف XrSession صالحًا
  • يجب أن يكون spatialContext مؤشرًا صالحًا لـ XrSpatialContextEXT
  • createInfo يجب أن يكون مؤشرًا إلى بنية XrSpatialAnchorCreateInfoEXT صالحة
  • يجب أن يكون anchorEntityId مؤشرًا إلى قيمة XrSpatialEntityIdEXT
  • anchorSpace يجب أن يكون مؤشرًا إلى مقبض XrSpace
  • يجب أن يكون قد تم إنشاء spatialContext أو تخصيصه أو استرداده من session

رموز الإرجاع

Success

  • 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);

أوصاف المَعلمات

في السيناريوهات التي تكون فيها كيانات نقاط الارتكاز المكانية موجودة مسبقًا (على سبيل المثال، بسبب الثبات)، يمكن للتطبيقات إنشاء XrSpace من نقاط الارتكاز المكانية هذه من خلال تقديم معرّفات الكيانات المكانية الخاصة بها.

تنشئ الدالة xrCreateSpatialAnchorSpaceFromIdANDROID مؤشر XrSpace من خلال توفير XrSpatialEntityIdEXT في الحقل XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId.

يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم يتم ضبط XrSpatialContextEXT الذي تم تمريره إلى xrCreateSpatialAnchorSpaceFromIdANDROID باستخدام XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

الاستخدام الصالح (ضمني)

رموز الإرجاع

Success

  • 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 منها.

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT إذا لم يكن XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId معرّفًا صالحًا لـ spatialContext .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID إذا لم يكن XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId رقم تعريف كيان صالحًا لنقطة ارتساء.

الاستخدام الصالح (ضمني)

مراحل نشاط علامات الارتساء

إنّ العنصر الرئيسي لمؤشر 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));

// ...

الأوامر الجديدة

منشآت جديدة

ثوابت تعداد جديدة

  • 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 (يو شينغ تشانغ، كايل تشن)

    • وصف الإضافة الأوّلي