XR_ANDROID_depth_texture

Name String

XR_ANDROID_depth_texture

نوع الإضافة

إضافة مثيل

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

703

المراجعة

1

حالة التصديق

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

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

OpenXR 1.0

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

2024-09-11

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

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

المساهمون

سوشانت كولكارني، Google
كيرن أوفرتورف، Google
سبنسر كوين، Google
ليفانا تشن، Google

نظرة عامة

تتيح هذه الإضافة للتطبيق طلب خرائط العمق للبيئة الواقعية المحيطة بسماعة الرأس والاستعلام عن درجات دقة العمق المتوافقة عند الإنشاء.

تهدف هذه الإضافة إلى عرض العمق الأولي والسلس للحجب واختبارات مؤشر الماوس والمهام المحدّدة الأخرى التي تستفيد من هندسة المشهد الدقيقة، مثل التعرّف على الوجوه المزيّفة.

ملاحظة

يتم إنشاء خرائط العمق من خلال بيئة التشغيل ومشاركتها مع التطبيق باستخدام XrDepthSwapchainANDROID . يجب ألا يغيّر وقت التشغيل درجات دقة صور العمق التي يتم عرضها من خلال xrEnumerateDepthResolutionsANDROID طوال مدة تشغيل التطبيق.

الأذونات

تعرض هذه الإضافة مادة عمق منخفضة العيّنات للتخفيف من المخاوف المتعلّقة بمعلومات تكشف الهوية الشخصية (PII). يجب أن تتضمّن تطبيقات Android الإذن android.permission.SCENE_UNDERSTANDING_FINE في ملف البيان الخاص بها لأنّ هذه الإضافة تكشف عن الشكل الهندسي للبيئة. يُعدّ الإذن android.permission.SCENE_UNDERSTANDING_FINE من الأذونات الخطيرة. يجب أن يطلب التطبيق الإذن أثناء التشغيل لاستخدام هذه الوظائف:

(مستوى الحماية: خطير)

فحص إمكانات النظام

يتم تعريف بنية XrSystemDepthTrackingPropertiesANDROID على النحو التالي:

typedef struct XrSystemDepthTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsDepthTracking;
} XrSystemDepthTrackingPropertiesANDROID;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى. لا يتم تحديد مثل هذه البُنى في OpenXR الأساسية أو هذه الإضافة.
  • ‫supportsDepthTracking هي قيمة XrBool32 تشير إلى ما إذا كان النظام الحالي يتيح تتبُّع العمق.

يمكن للتطبيق فحص ما إذا كان النظام قادرًا على تتبُّع العمق من خلال توسيع XrSystemProperties باستخدام بنية XrSystemDepthTrackingPropertiesANDROID عند استدعاء xrGetSystemProperties .

إذا عرضت بيئة التشغيل XR_FALSE لـ supportsDepthTracking، يجب أن تعرض بيئة التشغيل XR_ERROR_FEATURE_UNSUPPORTED من xrCreateDepthSwapchainANDROID .

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

درجات دقة عمق طلب البحث

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

XrResult xrEnumerateDepthResolutionsANDROID(
    XrSession                                   session,
    uint32_t                                    resolutionCapacityInput,
    uint32_t*                                   resolutionCountOutput,
    XrDepthCameraResolutionANDROID*             resolutions);

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

  • ‫session هو XrSession الذي يحدّد درجات دقة العمق المتوافقة.
  • ‫resolutionCapacityInput هي سعة resolutions، أو 0 لاسترداد السعة المطلوبة.
  • ‫resolutionCountOutput هو مؤشر إلى عدد uint64_t resolutions المكتوبة، أو مؤشر إلى السعة المطلوبة في حال عدم كفاية resolutionCapacityInput.
  • ‫resolutions هو مؤشر إلى مصفوفة من XrDepthCameraResolutionANDROID، ولكن يمكن أن يكون NULL إذا كان resolutionCapacityInput هو 0 .
  • يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم resolutions المطلوب.

تُعدّد الدالة xrEnumerateDepthResolutionsANDROID درجات دقة العمق التي تتيحها الجلسة الحالية. يجب أن تكون درجات دقة العمق بالترتيب من الأعلى إلى الأقل تفضيلاً في وقت التشغيل. يجب أن يستخدم التطبيق أعلى تفضيل يتيحه لتحقيق الأداء والجودة الأمثل.

يجب أن تعرض بيئات التشغيل دائمًا محتوى مخزن مؤقت متطابقًا من هذا التعداد طوال مدة الجلسة.

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

  • يجب تفعيل الإضافة XR_ANDROID_depth_texture قبل طلب xrEnumerateDepthResolutionsANDROID
  • يجب أن يكون session اسم معرِّف XrSession صالحًا
  • يجب أن يكون resolutionCountOutput مؤشرًا إلى قيمة uint32_t
  • إذا لم تكن قيمة resolutionCapacityInput هي 0، resolutions يجب أن تكون مؤشرًا إلى مصفوفة من قيم resolutionCapacityInput XrDepthCameraResolutionANDROID

رموز الإرجاع

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذّر الإجراء

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

يصف التعداد XrDepthCameraResolutionANDROID درجات دقة العمق المتوافقة عند إنشاء XrDepthSwapchainANDROID .

typedef enum XrDepthCameraResolutionANDROID {
    XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID = 0,
    XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID = 1,
    XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID = 2,
    XR_DEPTH_CAMERA_RESOLUTION_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrDepthCameraResolutionANDROID;

أوصاف التعداد

  • XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID — تبلغ دقة صور العمق والثقة 80x80.
  • XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID — تبلغ دقة صور العمق والثقة 160×160.
  • XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID — تبلغ دقة صور العمق والثقة 320×320.

إنشاء سلسلة تبديل للعمق

XR_DEFINE_HANDLE(XrDepthSwapchainANDROID)

‫XrDepthSwapchainANDROID هو اسم معرِّف لسلسلة تبديل العمق.

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

XrResult xrCreateDepthSwapchainANDROID(
    XrSession                                   session,
    const XrDepthSwapchainCreateInfoANDROID*    createInfo,
    XrDepthSwapchainANDROID*                    swapchain);

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

  • ‫session هي XrSession التي تنشئ سلسلة تبديل العمق.
  • ‫createInfo هو مؤشر إلى بنية XrDepthSwapchainCreateInfoANDROID تحتوي على مَعلمات يتم استخدامها لإنشاء سلسلة التبديل.
  • ‫swapchain هو مؤشر إلى اسم معرِّف يتم فيه عرض XrDepthSwapchainANDROID الذي تم إنشاؤه.

يمكن للتطبيق استخدام دالة xrCreateDepthSwapchainANDROID لإنشاء سلسلة تبديل العمق التي تدير كلاً من صور العمق والثقة.

  • يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_FEATURE_UNSUPPORTED إذا كان النظام لا يتيح تتبُّع العمق.
  • يجب أن يعرض وقت التشغيل XR_ERROR_PERMISSION_INSUFFICIENT إذا لم يتم منح الأذونات المطلوبة لتطبيق الاتصال.
  • يجب أن يعرض وقت التشغيل القيمة XR_ERROR_VALIDATION_FAILURE إذا كانت درجة دقة العمق المحدّدة في XrDepthSwapchainCreateInfoANDROID غير متوافقة.
  • يجب أن ينشئ وقت التشغيل صورًا لمستوى الثقة في العمق فقط عند ضبط وحدات البت المقابلة لـ createInfo عند إنشاء سلسلة التبديل.

قد يتم استخدام مؤشر سلسلة التبديل للعمق الذي تم عرضه لاحقًا في طلبات البيانات من واجهة برمجة التطبيقات. يجب في النهاية إخلاء مؤشر XrDepthSwapchainANDROID من خلال دالة xrDestroyDepthSwapchainANDROID.

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

رموز الإرجاع

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذّر الإجراء

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST

يتم تحديد بنية XrDepthSwapchainCreateInfoANDROID على النحو التالي:

typedef struct XrDepthSwapchainCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrDepthCameraResolutionANDROID        resolution;
    XrDepthSwapchainCreateFlagsANDROID    createFlags;
} XrDepthSwapchainCreateInfoANDROID;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى. لا يتم تحديد مثل هذه البُنى في OpenXR الأساسية أو هذه الإضافة.
  • ‫resolution هي السمة XrDepthCameraResolutionANDROID التي يتم إنشاء زخارف العمق والثقة باستخدامها.
  • ‫createFlags هي قيمة واحدة أو أكثر من XrDepthSwapchainCreateFlagsANDROID .

توفّر بنية XrDepthSwapchainCreateInfoANDROID خيارات إنشاء لـ XrDepthSwapchainANDROID عند تمريرها إلى xrCreateDepthSwapchainANDROID .

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

يحدّد XrDepthSwapchainCreateFlagsANDROID خيارات إنشاء XrDepthSwapchainANDROID .

typedef XrFlags64 XrDepthSwapchainCreateFlagsANDROID;

يتم تحديد وحدات البت الصالحة لـ XrDepthSwapchainCreateFlagsANDROID من خلال XrDepthSwapchainCreateFlagBitsANDROID، والتي يتم تحديدها على النحو التالي:

// Flag bits for XrDepthSwapchainCreateFlagsANDROID
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID = 0x00000001;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID = 0x00000002;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID = 0x00000004;
static const XrDepthSwapchainCreateFlagsANDROID XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID = 0x00000008;

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

  • ‫XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID: تشير إلى أنّ سلسلة التبديل ستوفّر صورًا سلسة للعمق.
  • ‫XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID: يشير إلى أنّ سلسلة التبديل ستوفّر صورًا سلسة لمستوى الثقة في العمق.
  • ‫XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID: تشير إلى أنّ سلسلة التبديل ستوفّر صورًا أولية للعمق.
  • ‫XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID: يشير إلى أنّ سلسلة التبديل ستوفّر صورًا أولية لمستوى الثقة في العمق.

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

XrResult xrDestroyDepthSwapchainANDROID(
    XrDepthSwapchainANDROID                     swapchain);

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

تؤدي الدالة xrDestroyDepthSwapchainANDROID إلى تدمير سلسلة تبديل العمق. بعد هذا الاستدعاء، قد يحرّر وقت التشغيل جميع الذاكرة والموارد ذات الصلة.

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

أمان Thread

  • يجب مزامنة الوصول إلى swapchain وأي معرّفات فرعية خارجيًا

رموز الإرجاع

Success

  • XR_SUCCESS

تعذّر الإجراء

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

الوصول إلى زخارف العمق

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

XrResult xrEnumerateDepthSwapchainImagesANDROID(
    XrDepthSwapchainANDROID                     depthSwapchain,
    uint32_t                                    depthImageCapacityInput,
    uint32_t*                                   depthImageCountOutput,
    XrDepthSwapchainImageANDROID*               depthImages);

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

  • ‫depthSwapchain هي XrDepthSwapchainANDROID للحصول على الصور منها.
  • ‫depthImageCapacityInput هي سعة مصفوفة depthImages، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
  • ‫depthImageCountOutput هو مؤشر إلى عدد depthImages المكتوبة، أو مؤشر إلى السعة المطلوبة في حال عدم كفاية depthImageCapacityInput.
  • ‫depthImages هو مؤشر إلى مصفوفة من بُنى XrDepthSwapchainImageANDROID. يمكن أن تكون القيمة NULL إذا كانت قيمة depthImageCapacityInput هي 0.
  • يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم depthImages المطلوب.

تعبئ الدالة xrEnumerateDepthSwapchainImagesANDROID مصفوفة من هياكل XrDepthSwapchainImageANDROID. يجب أن تكون الموارد ثابتة وصالحة طوال مدة استخدام XrDepthSwapchainANDROID . تعمل هذه الدالة بشكل مشابه لـ xrEnumerateSwapchainImages .

يجب أن يعرض وقت التشغيل دائمًا محتوى مخزن مؤقت متطابقًا من هذا التعداد طوال مدة سلسلة التبديل.

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

  • يجب تفعيل الإضافة XR_ANDROID_depth_texture قبل استدعاء xrEnumerateDepthSwapchainImagesANDROID
  • يجب أن يكون depthSwapchain اسم معرِّف صالحًا لـ XrDepthSwapchainANDROID
  • يجب أن يكون depthImageCountOutput مؤشرًا إلى قيمة uint32_t
  • إذا لم تكن قيمة depthImageCapacityInput هي 0، يجب أن تكون قيمة depthImages مؤشرًا إلى مصفوفة من هياكل depthImageCapacityInput XrDepthSwapchainImageANDROID

رموز الإرجاع

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذّر الإجراء

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

يتم تعريف بنية XrDepthSwapchainImageANDROID على النحو التالي:

typedef struct XrDepthSwapchainImageANDROID {
    XrStructureType    type;
    void*              next;
    const float*       rawDepthImage;
    const uint8_t*     rawDepthConfidenceImage;
    const float*       smoothDepthImage;
    const uint8_t*     smoothDepthConfidenceImage;
} XrDepthSwapchainImageANDROID;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى. لا يتم تحديد مثل هذه البُنى في OpenXR الأساسية أو هذه الإضافة.
  • ‫rawDepthImage هو NULL أو المؤشر إلى صور العمق الأولية لكل من العرضَين الأيمن والأيسر اللذين يخصّصهما وقت التشغيل. وتكون القيم بوحدة المتر. القيم الخاصة: تشير القيمة 0.0 إلى بكسل عمق غير صالح أو فارغ في العمق الأوّلي، وتشير القيمة Inf إلى عمق معروف بعيد بشكل لا نهائي،
  • ‫rawDepthConfidenceImage هي NULL أو المؤشر إلى صور الثقة في العمق الأوّلي لكل من العرضَين الأيمن والأيسر اللذين تم تخصيصهما من خلال وقت التشغيل.
  • ‫smoothDepthImage هو NULL أو المؤشر إلى صور العمق السلسة لكل من العرضَين الأيمن والأيسر اللذين يخصّصهما وقت التشغيل. وتكون القيم بوحدة المتر. القيم الخاصة: تشير القيمة 0.0 إلى بكسل عمق غير صالح أو فارغ في العمق السلس، بينما تشير القيمة Inf إلى عمق معروف بعيد بشكل لا نهائي.
  • ‫smoothDepthConfidenceImage هو NULL أو المؤشر إلى صور الثقة في العمق السلس لكل من العرضَين الأيمن والأيسر اللذين يخصّصهما وقت التشغيل.

ستكون مؤشرات مخزن الصور المؤقت صالحة فقط خلال فترة عمل سلسلة التبديل. بعد تدمير سلسلة التبديل، سيتم اعتبار المؤشرات معلّقة.

يمثّل XrDepthSwapchainImageANDROID صور العمق من XrDepthSwapchainANDROID قابل للقراءة، ويتم تخصيصه كما هو موضّح في XrDepthSwapchainCreateInfoANDROID :: resolution وXrDepthSwapchainCreateInfoANDROID :: createFlags أثناء استدعاء xrCreateDepthSwapchainANDROID . لكل صورة عمق:

  • يتم وضع قيم الصور في الذاكرة بترتيب الصف الرئيسي، بدون مساحة متروكة بين الصفوف.
  • القيمة الأولى هي أعلى اليسار والقيمة الأخيرة هي أسفل اليمين.
  • يتم تحديد حجم الذاكرة التي تتم الإشارة إليها من خلال قيمة xrEnumerateDepthSwapchainImagesANDROID ويتم ضبطها من خلال XrDepthSwapchainCreateInfoANDROID :: resolution أثناء استدعاء xrCreateDepthSwapchainANDROID . على سبيل المثال، إذا كانت قيمة resolution في XrDepthSwapchainCreateInfoANDROID هي XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID، سيكون حجم صور العمق 2*160*160*sizeof(float) .
  • يجب أن تكون قيمة rawDepthImage هي NULL إذا لم يتضمّن XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID XrDepthSwapchainCreateInfoANDROID :: createFlags.
  • يجب أن تكون قيمة rawDepthConfidenceImage هي NULL إذا لم يتضمّن XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID XrDepthSwapchainCreateInfoANDROID :: createFlags.
  • يجب أن تكون قيمة smoothDepthImage هي NULL إذا لم يتضمّن XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID XrDepthSwapchainCreateInfoANDROID :: createFlags.
  • يجب أن تكون قيمة smoothDepthImage هي NULL إذا لم يتضمّن XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID XrDepthSwapchainCreateInfoANDROID :: createFlags.

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

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

XrResult xrAcquireDepthSwapchainImagesANDROID(
    XrDepthSwapchainANDROID                     depthSwapchain,
    const XrDepthAcquireInfoANDROID*            acquireInfo,
    XrDepthAcquireResultANDROID*                acquireResult);

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

  • ‫depthSwapchain هو مقبض XrDepthSwapchainANDROID لصورة العمق.
  • ‫acquireInfo هو XrDepthAcquireInfoANDROID يحتوي على معلومات حول كيفية الحصول على صورة العمق.
  • ‫acquireResult هي القيمة المعروضة XrDepthAcquireResultANDROID التي تحتوي على معلومات حول صورة العمق التي تم الحصول عليها.

يمكن للتطبيقات استخدام دالة xrAcquireDepthSwapchainImagesANDROID للحصول على أحدث فهرس متاح لصورة سلسلة التبديل، أي XrDepthAcquireResultANDROID :: acquiredIndex ، في مصفوفة XrDepthSwapchainImageANDROID التي تم تعدادها بواسطة xrEnumerateDepthSwapchainImagesANDROID . تحتوي النتيجة XrDepthAcquireResultANDROID التي تم عرضها أيضًا على معلومات أخرى، مثل مجال الرؤية والوضعية اللازمة لتفسير بيانات العمق. يمكن القراءة بأمان من الخانة المكتسَبة في مصفوفة الصور إلى أن يتم إجراء الطلب التالي إلى xrAcquireDepthSwapchainImagesANDROID .

يجب ألا يكون هناك أكثر من استدعاء واحد لـ xrAcquireDepthSwapchainImagesANDROID بين أي زوج من استدعاءات xrBeginFrame وxrEndFrame المقابلة في جلسة واحدة.

  • قد يحظر وقت التشغيل إذا كانت صور سلسلة التبديل التي تم الحصول عليها سابقًا لا تزال قيد الاستخدام من قِبل وقت التشغيل.
  • يجب أن يعرض وقت التشغيل XR_ERROR_CALL_ORDER_INVALID إذا تم استدعاء xrAcquireDepthSwapchainImagesANDROID قبل xrBeginFrame أو بعد xrEndFrame .
  • يجب أن تعرض بيئة التشغيل XR_ERROR_LIMIT_REACHED إذا تم استدعاء xrAcquireDepthSwapchainImagesANDROID أكثر من مرة لكل لقطة، أي في جلسة قيد التشغيل، بعد استدعاء xrBeginFrame الذي لم يتضمّن xrEndFrame مرتبطًا به.
  • قد يعرض وقت التشغيل القيمة XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID إذا لم تكن بيانات عمق البيئة متاحة بعد. في هذه الحالة، يجب أن يستدعي التطبيق xrAcquireDepthSwapchainImagesANDROID مرة أخرى في إطار لاحق.

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

رموز الإرجاع

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذّر الإجراء

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

يتم تحديد بنية XrDepthAcquireInfoANDROID على النحو التالي:

typedef struct XrDepthAcquireInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             displayTime;
} XrDepthAcquireInfoANDROID;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى. لا يتم تحديد مثل هذه البُنى في OpenXR الأساسية أو هذه الإضافة.
  • space هو XrSpace يحدّد الإطار المرجعي للوضعية المعروضة في XrDepthAcquireResultANDROID :: views .
  • ‫displayTime هو XrTime يحدّد الوقت المستخدَم لاحتساب الوضعية التي يتم عرضها في XrDepthAcquireResultANDROID :: views . يجب أن تمرّر التطبيقات وقت العرض المتوقّع للإطار الحالي.

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

يتم تحديد بنية XrDepthAcquireResultANDROID على النحو التالي:

typedef struct XrDepthAcquireResultANDROID {
    XrStructureType       type;
    const void*           next;
    uint32_t              acquiredIndex;
    XrTime                exposureTimestamp;
    XrDepthViewANDROID    views[2];
} XrDepthAcquireResultANDROID;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى. لا يتم تحديد مثل هذه البُنى في OpenXR الأساسية أو هذه الإضافة.
  • ‫acquiredIndex هو فهرس المادة التي تم الحصول عليها في مصفوفة XrDepthSwapchainImageANDROID التي تم تعدادها بواسطة xrEnumerateDepthSwapchainImagesANDROID .
  • ‫exposureTimestamp هي السمة XrTime التي تحدّد وقت التقاط خريطة العمق.
  • ‫views هي مصفوفة من عنصرَي XrDepthViewANDROID، واحد لكل عين، حيث يمثّل الفهرس 0 العين اليسرى والفهرس 1 العين اليمنى.

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

يتم تعريف بنية XrDepthViewANDROID على النحو التالي:

typedef struct XrDepthViewANDROID {
    XrStructureType    type;
    const void*        next;
    XrFovf             fov;
    XrPosef            pose;
} XrDepthViewANDROID;

أوصاف الأعضاء

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى. لا يتم تحديد مثل هذه البُنى في OpenXR الأساسية أو هذه الإضافة.
  • ‫fov هو XrFovf يحدّد مجال الرؤية المستخدَم لإنشاء هذا العرض. لا يتم قلب العرض أفقيًا أو عموديًا أبدًا.
  • pose هو XrPosef يحدّد الوضعية التي تم عرض خريطة العمق منها. يتم تحديد الإطار المرجعي في XrDepthAcquireInfoANDROID .

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

مثال على رمز لتتبُّع العمق

يوضّح الرمز البرمجي في المثال التالي كيفية الحصول على صور العمق واستخدام قيم العمق لربط إحداثيات صور العمق بمساحة المسرح.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session; // previously initialized
XrSpace stageSpace; // space created for XR_REFERENCE_SPACE_TYPE_STAGE.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateDepthSwapchainANDROID xrCreateDepthSwapchainANDROID; // previously initialized
PFN_xrDestroyDepthSwapchainANDROID xrDestroyDepthSwapchainANDROID; // previously initialized
PFN_xrEnumerateDepthSwapchainImagesANDROID xrEnumerateDepthSwapchainImagesANDROID; // previously initialized
PFN_xrEnumerateDepthResolutionsANDROID xrEnumerateDepthResolutionsANDROID; // previously initialized
PFN_xrAcquireDepthSwapchainImagesANDROID xrAcquireDepthSwapchainImagesANDROID; // previously initialized

float tanf(float);

// Inspect system capability
XrSystemProperties properties{XR_TYPE_SYSTEM_PROPERTIES};
XrSystemDepthTrackingPropertiesANDROID depthTrackingProperties{XR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID};
properties.next = &depthTrackingProperties;
CHK_XR(xrGetSystemProperties(instance, systemId, &properties));
if (!depthTrackingProperties.supportsDepthTracking) {
  // depth tracking is not supported.
  return;
}

// Query the supported depth resolution.
XrDepthCameraResolutionANDROID supportedDepthResolution;
uint32_t supportedResolutionCount = 0;
CHK_XR(xrEnumerateDepthResolutionsANDROID(
    session, 1, &supportedResolutionCount, &supportedDepthResolution));

// Define metadata to access the raw and smooth depth along with confidences.
XrDepthSwapchainCreateInfoANDROID swapchainCreateInfo = {
  .type = XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID,
  .next = nullptr,
  // Use the resolution supported by the runtime.
  .resolution = supportedDepthResolution,
  .createFlags =
    XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID |
    XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID,
};

XrDepthSwapchainANDROID depthSwapchain;
CHK_XR(xrCreateDepthSwapchainANDROID(
    session, &swapchainCreateInfo, &depthSwapchain));

// Enumerate depth images.
uint32_t imageCountOutput = 0;
CHK_XR(xrEnumerateDepthSwapchainImagesANDROID(
    depthSwapchain, 0, &imageCountOutput, nullptr));
std::vector<XrDepthSwapchainImageANDROID> depthImages(imageCountOutput);
for (int i = 0; i < imageCountOutput; i++) {
  depthImages[i].type = XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID;
}
CHK_XR(xrEnumerateDepthSwapchainImagesANDROID(
  depthSwapchain, imageCountOutput, &imageCountOutput, depthImages.data()));

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;

    XrDepthAcquireInfoANDROID acquireInfo = {
        .type = XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID,
        .space = stageSpace,
        .displayTime = time
    };
    XrDepthAcquireResultANDROID acquireResult = {
        .type = XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID,
    };
    CHK_XR(xrAcquireDepthSwapchainImagesANDROID(
        depthSwapchain, &acquireInfo, &acquireResult));

    // Each value in a depth image corresponds to a point in the real world.
    // The sample code below shows how to find the stageSpace position of
    // the point corresponding to a particular value in the depth image.

    // For this sample code, assume we are using a right handed coordinate system
    // with +X to the right, +Y up and -Z forward.

    XrDepthSwapchainImageANDROID *image =
        &depthImages[acquireResult.acquiredIndex];

    // Assume supported resolution is XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID.
    const int imageResolution = 160;
    int imageY = 80; // value in [0, imageResolution)
    int imageX = 80; // value in [0, imageResolution)

    // Get depth value from left eye.
    // A right depth value is obtained with the following expression:
    // depthR = image->rawDepthImage[imageResolution*imageResolution+i*imageResolution+j]
    float depthL = image->rawDepthImage[imageY*imageResolution + imageX];
    XrDepthViewANDROID viewL = acquireResult.views[0];

    float tanL = tanf(viewL.fov.angleLeft);
    float tanR = tanf(viewL.fov.angleRight);
    float tanU = tanf(viewL.fov.angleUp);
    float tanD = tanf(viewL.fov.angleDown);

    float s = (imageX + 0.5f) / (float)imageResolution;
    float t = (imageY + 0.5f) / (float)imageResolution;

    // Calculate the depth camera space position of the point
    // corresponding to this depth value.
    XrVector3f posInCameraSpace;
    posInCameraSpace.z = -depthL;
    posInCameraSpace.x = (tanL + (tanR - tanL)*s)*depthL;
    posInCameraSpace.y = (tanD + (tanU - tanD)*t)*depthL;

    XrPosef depthCameraPoseL = viewL.pose;
    // Transform posInCameraSpace by depthCameraPoseL

    // ...
    // Finish frame loop
    // ...
}

أنواع العناصر الجديدة

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

منشآت جديدة

عمليات تعداد جديدة

أقنعة بت جديدة

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

  • XR_ANDROID_DEPTH_TEXTURE_EXTENSION_NAME
  • XR_ANDROID_depth_texture_SPEC_VERSION

  • توسيع XrObjectType :

    • XR_OBJECT_TYPE_DEPTH_SWAPCHAIN_ANDROID

  • توسيع XrResult :

    • XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID

  • توسيع XrStructureType :

    • XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID
    • XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID
    • XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID
    • XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID
    • XR_TYPE_DEPTH_VIEW_ANDROID
    • XR_TYPE_SYSTEM_DEPTH_TRACKING_PROPERTIES_ANDROID

المشاكل

سجلّ الإصدارات

  • المراجعة 1، ‎09-09-2024 (ليفانا تشن)

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