XR_ANDROID_depth_texture

رشته نام

XR_ANDROID_depth_texture

نوع افزونه

افزونه نمونه

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

703

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

OpenXR 1.0

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

2024-09-11

وضعیت IP

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

همیاران

Sushant Kulkarni،‏ Google
Cairn Overturf،‏ Google
Spencer Quin،‏ Google
Levana Chen،‏ 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 است، یا ۰ برای بازیابی ظرفیت موردنیاز.
  • ‫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 باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • 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 enum وضوح‌های عمق پشتیبانی‌شده را هنگام ایجاد 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 — وضوح تصاویر عمق و اطمینان ۸۰×۸۰ است.
  • XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID — وضوح تصاویر عمق و اطمینان ۱۶۰x۱۶۰ است.
  • XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID — وضوح تصاویر عمق و اطمینان ۳۲۰×۳۲۰ است.

ایجاد زنجیره تعویض عمق

XR_DEFINE_HANDLE(XrDepthSwapchainANDROID)

XrDepthSwapchainANDROID یک دسته زنجیره تعویض عمق است.

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

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

شرح پارامترها

  • ‫session همان XrSession است که زنجیره تعویض عمق را ایجاد می‌کند.
  • ‫createInfo اشاره‌گری به ساختار XrDepthSwapchainCreateInfoANDROID است که حاوی پارامترهایی است که برای ایجاد swapchain استفاده می‌شود.
  • ‫swapchain اشاره‌گری به دسته‌ای است که در آن XrDepthSwapchainANDROID ایجادشده برگردانده می‌شود.

برنامه می‌تواند از تابع xrCreateDepthSwapchainANDROID برای ایجاد زنجیره تبادل عمق استفاده کند که هم تصاویر عمق و هم تصاویر اطمینان را مدیریت می‌کند.

  • اگر سیستم از ردیابی عمق پشتیبانی نمی‌کند، زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED را برگرداند.
  • اگر اجازه‌های لازم به برنامه تماس‌گیرنده اعطا نشده باشد، زمان اجرا باید XR_ERROR_PERMISSION_INSUFFICIENT را برگرداند.
  • اگر وضوح عمق مشخص‌شده در XrDepthSwapchainCreateInfoANDROID پشتیبانی نشود، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE را برگرداند.
  • زمان اجرا باید فقط زمانی تصاویر اطمینان عمق را ایجاد کند که بیت‌های مربوطه برای createInfo در زمان ایجاد زنجیره تعویض تنظیم شده باشند.

دسته زنجیره تعویض عمق برگردانده‌شده ممکن است متعاقباً در فراخوانی‌های میانای برنامه‌سازی کاربردی استفاده شود. دستگیره XrDepthSwapchainANDROID باید درنهایت ازطریق تابع xrDestroyDepthSwapchainANDROID آزاد شود.

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

کدهای برگشتی

موفقیت‌آمیز بود

  • 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 — نشان می‌دهد که swapchain تصاویر عمق همواری ارائه خواهد داد.
  • XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID — نشان می‌دهد که swapchain تصاویر اطمینان عمق همواری ارائه خواهد داد.
  • XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID — نشان می‌دهد که swapchain تصاویر عمق خام ارائه خواهد کرد.
  • XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID — نشان می‌دهد که swapchain تصاویر اطمینان عمق خام را ارائه خواهد داد.

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

XrResult xrDestroyDepthSwapchainANDROID(
    XrDepthSwapchainANDROID                     swapchain);

شرح پارامترها

تابع xrDestroyDepthSwapchainANDROID زنجیره تعویض عمق را ازبین می‌برد. پس‌از این فراخوانی، زمان اجرا ممکن است همه حافظه و منابع مرتبط را آزاد کند.

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

ایمنی رشته‌ای

  • دسترسی به swapchain و هرگونه دسته فرزند باید به‌صورت خارجی همگام‌سازی شود

کدهای برگشتی

موفقیت‌آمیز بود

  • 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 است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
  • ‫depthImageCountOutput اشاره‌گری به تعداد depthImages نوشته‌شده است، یا اشاره‌گری به ظرفیت موردنیاز درصورتی‌که depthImageCapacityInput کافی نباشد.
  • ‫depthImages اشاره‌گری به آرایه‌ای از ساختارهای XrDepthSwapchainImageANDROID است. اگر depthImageCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصل بازیابی اندازه depthImages موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

xrEnumerateDepthSwapchainImagesANDROID آرایه‌ای از ساختارهای XrDepthSwapchainImageANDROID را پر می‌کند. منابع باید ثابت و برای طول عمر XrDepthSwapchainANDROID معتبر باشند. این تابع مشابه xrEnumerateSwapchainImages عمل می‌کند.

زمان اجرا باید همیشه محتوای میان‌گیر یکسانی را از این شمارش برای طول عمر swapchain برگرداند.

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

  • افزونه XR_ANDROID_depth_texture باید پیش‌از فراخوانی xrEnumerateDepthSwapchainImagesANDROID فعال شود
  • depthSwapchain باید یک دسته XrDepthSwapchainANDROID معتبر باشد
  • depthImageCountOutput باید اشاره‌گری به مقدار uint32_t باشد
  • اگر depthImageCapacityInput 0 نباشد، depthImages باید اشاره‌گری به آرایه‌ای از ساختارهای depthImageCapacityInput XrDepthSwapchainImageANDROID باشد

کدهای برگشتی

موفقیت‌آمیز بود

  • 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 تنظیم می‌شود. برای مثال، اگر XrDepthSwapchainCreateInfoANDROID :: resolution برابر با XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID باشد، اندازه تصاویر عمق 2*160*160*sizeof(float) خواهد بود.
  • اگر XrDepthSwapchainCreateInfoANDROID :: createFlags شامل XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID نباشد، مقدار rawDepthImage باید NULL باشد.
  • اگر XrDepthSwapchainCreateInfoANDROID :: createFlags شامل XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID نباشد، مقدار rawDepthConfidenceImage باید NULL باشد.
  • اگر XrDepthSwapchainCreateInfoANDROID :: createFlags شامل XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_DEPTH_IMAGE_BIT_ANDROID نباشد، مقدار smoothDepthImage باید NULL باشد.
  • اگر XrDepthSwapchainCreateInfoANDROID :: createFlags شامل XR_DEPTH_SWAPCHAIN_CREATE_SMOOTH_CONFIDENCE_IMAGE_BIT_ANDROID نباشد، مقدار smoothDepthImage باید NULL باشد.

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

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

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

شرح پارامترها

  • ‫depthSwapchain یک دسته XrDepthSwapchainANDROID برای تصویر عمق است.
  • ‫acquireInfo یک XrDepthAcquireInfoANDROID است که حاوی اطلاعاتی درباره نحوه دریافت تصویر عمق است.
  • ‫acquireResult مقدار XrDepthAcquireResultANDROID برگردانده‌شده است که حاوی اطلاعاتی درباره تصویر عمق به‌دست‌آمده است.

برنامه‌ها می‌توانند از تابع xrAcquireDepthSwapchainImagesANDROID برای دریافت جدیدترین نمایه تصویر swapchain دردسترس، یعنی XrDepthAcquireResultANDROID :: acquiredIndex ، در آرایه XrDepthSwapchainImageANDROID که توسط xrEnumerateDepthSwapchainImagesANDROID شمارش شده است استفاده کنند. XrDepthAcquireResultANDROID برگردانده‌شده همچنین حاوی اطلاعات دیگری مانند میدان دید و ژست است که برای تفسیر داده‌های عمق ضروری هستند. خواندن از جایگاه به‌دست‌آمده در آرایه تصویر تا فراخوانی بعدی به xrAcquireDepthSwapchainImagesANDROID ایمن است.

نباید بیش‌از یک تماس با xrAcquireDepthSwapchainImagesANDROID بین هر جفت تماس متناظر xrBeginFrame و xrEndFrame در یک جلسه وجود داشته باشد.

  • اگر تصاویر زنجیره تعویض که قبلاً به‌دست آمده‌اند همچنان توسط زمان اجرا استفاده شوند، زمان اجرا ممکن است مسدود شود.
  • اگر xrAcquireDepthSwapchainImagesANDROID قبل‌از xrBeginFrame یا بعداز xrEndFrame فراخوانی شود، زمان اجرا باید XR_ERROR_CALL_ORDER_INVALID را برگرداند.
  • اگر xrAcquireDepthSwapchainImagesANDROID بیش‌از یک‌بار در هر فریم فراخوانی شود، زمان اجرا باید XR_ERROR_LIMIT_REACHED را برگرداند - یعنی در یک جلسه درحال اجرا، پس‌از فراخوانی xrBeginFrame که xrEndFrame مرتبط نداشته است.
  • اگر داده‌های عمق محیط هنوز دردسترس نباشد، زمان اجرا ممکن است XR_ERROR_DEPTH_NOT_AVAILABLE_ANDROID را برگرداند. اگر این اتفاق بیفتد، برنامه باید xrAcquireDepthSwapchainImagesANDROID را دوباره در فریم بعدی فراخوانی کند.

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

کدهای برگشتی

موفقیت‌آمیز بود

  • 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 است، یکی برای هر چشم، که در آن شاخص ۰ چشم چپ و شاخص ۱ چشم راست است.

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

ساختار 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
    // ...
}

انواع شیء جدید

فرمان‌های جدید

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

Enums جدید

ماسک‌های بیتی جدید

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

  • 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

مشکلات

سابقه نسخه

  • بازبینی ۱، ۲۰۲۴/۰۹/۰۹ (Levana Chen)

    • شرح اولیه افزونه