بافت_عمق_XR_ANDROID

رشته نام

XR_ANDROID_depth_texture

نوع افزونه

افزونه نمونه

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

۷۰۳

بازنگری

۱

وضعیت تصویب

تصویب نشده

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

اوپن‌ایکس‌آر ۱.۰

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

۲۰۲۴-۰۹-۱۱

وضعیت آی‌پی

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

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

سوشانت کولکارنی، گوگل
کایرن اوورترف، گوگل
اسپنسر کوئین، گوگل
لوانا چن، گوگل

نمای کلی

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

این افزونه برای نمایش عمق خام و روان برای انسداد، تست‌های ضربه و سایر وظایف خاص که از هندسه دقیق صحنه بهره می‌برند، مانند تشخیص چهره جعلی، در نظر گرفته شده است.

توجه داشته باشید

نقشه‌های عمق توسط زمان اجرا تولید شده و با استفاده از XrDepthSwapchainANDROID با برنامه به اشتراک گذاشته می‌شوند. زمان اجرا نباید وضوح تصویر عمقی که از طریق xrEnumerateDepthResolutionsANDROID برگردانده می‌شود را در طول عمر برنامه تغییر دهد.

مجوزها

این افزونه، بافتی با عمق نمونه‌برداری کاهش‌یافته را نمایش می‌دهد تا نگرانی‌های مربوط به اطلاعات شخصی قابل شناسایی (PII) را کاهش دهد. برنامه‌های اندروید باید مجوز android.permission.SCENE_UNDERSTANDING_FINE را در مانیفست خود داشته باشند، زیرا این افزونه هندسه محیط را نمایش می‌دهد. مجوز android.permission.SCENE_UNDERSTANDING_FINE یک مجوز خطرناک محسوب می‌شود. برنامه باید در زمان اجرا برای استفاده از این توابع درخواست مجوز کند:

• xrCreateDepthSwapchain اندروید

(سطح حفاظت: خطرناک)

بررسی قابلیت سیستم

ساختار 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 برگرداند.

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

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

وضوح عمق پرس و جو

تابع xrEnumerateDepthResolutionsANDROID به صورت زیر تعریف شده است:

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

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

• session همان XrSession است که وضوح عمق پشتیبانی شده را فهرست می‌کند.
• resolutionCapacityInput ظرفیت resolutions یا 0 برای بازیابی ظرفیت مورد نیاز است.
• resolutionCountOutput اشاره‌گری به تعداد resolutions نوشته شده از uint64_t است، یا در صورتی که resolutionCapacityInput کافی نباشد، اشاره‌گری به ظرفیت مورد نیاز است.
• resolutions یک اشاره‌گر به آرایه‌ای از XrDepthCameraResolutionANDROID است، اما اگر resolutionCapacityInput برابر با 0 باشد، می‌تواند NULL باشد.
• برای توضیحات مفصل در مورد بازیابی اندازه 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 وضوح عمق پشتیبانی‌شده هنگام ایجاد یک 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 — وضوح تصاویر عمق و اطمینان ۸۰x۸۰ است.
• XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID — وضوح تصاویر عمق و اطمینان ۱۶۰x۱۶۰ است.
• XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID — وضوح تصاویر عمق و اطمینان ۳۲۰x۳۲۰ است.

ایجاد یک زنجیره مبادله عمقی

XR_DEFINE_HANDLE(XrDepthSwapchainANDROID)

XrDepthSwapchainANDROID یک دسته swapchain عمق است.

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

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

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

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

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

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

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

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

• افزونه‌ی XR_ANDROID_depth_texture باید قبل از فراخوانی xrCreateDepthSwapchainANDROID فعال شود.
• session باید یک دسته XrSession معتبر باشد
• createInfo باید یک اشاره‌گر به ساختار معتبر XrDepthSwapchainCreateInfoANDROID باشد.
• swapchain باید یک اشاره‌گر به یک هندل XrDepthSwapchainANDROID باشد.

کدهای بازگشت

موفقیت

• 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 فراهم می‌کند.

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

• قبل از استفاده از XrDepthSwapchainCreateInfoANDROID، افزونه‌ی XR_ANDROID_depth_texture باید فعال باشد.
• type باید XR_TYPE_DEPTH_SWAPCHAIN_CREATE_INFO_ANDROID باشد.
• next باید NULL یا یک اشاره‌گر معتبر به ساختار بعدی در یک زنجیره ساختار باشد.
• resolution باید یک مقدار معتبر XrDepthCameraResolutionANDROID باشد.
• createFlags باید ترکیبی معتبر از مقادیر XrDepthSwapchainCreateFlagBitsANDROID باشد.
• createFlags نباید 0 باشد.

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

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

• swapchain یک شناسه XrDepthSwapchainANDROID است که قبلاً توسط xrCreateDepthSwapchainANDROID ایجاد شده است.

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

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

• افزونه‌ی XR_ANDROID_depth_texture باید قبل از فراخوانی xrDestroyDepthSwapchainANDROID فعال شود.
• swapchain باید یک شناسه معتبر XrDepthSwapchainANDROID باشد.

ایمنی رزوه

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

کدهای بازگشت

موفقیت

• XR_SUCCESS

شکست

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

دسترسی به بافت‌های عمقی

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

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

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

• depthSwapchain همان XrDepthSwapchainANDROID است که می‌توان از آن تصاویر را دریافت کرد.
• depthImageCapacityInput ظرفیت آرایه depthImages است، یا 0 برای نشان دادن درخواست بازیابی ظرفیت مورد نیاز.
• 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 یا اشاره‌گری به تصاویر با اطمینان عمق هموار برای هر دو نمای چپ و راست اختصاص داده شده توسط زمان اجرا است.

اشاره‌گرهای بافر تصویر فقط در طول عمر swapchain معتبر خواهند بود. پس از نابودی swapchain، اشاره‌گرها به صورت معلق در نظر گرفته می‌شوند.

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 باشد.

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

• قبل از استفاده از XrDepthSwapchainImageANDROID، افزونه‌ی XR_ANDROID_depth_texture باید فعال باشد.
• type باید XR_TYPE_DEPTH_SWAPCHAIN_IMAGE_ANDROID باشد.
• next باید 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 در یک جلسه وجود داشته باشد.

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

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

• افزونه‌ی XR_ANDROID_depth_texture باید قبل از فراخوانی xrAcquireDepthSwapchainImagesANDROID فعال شود.
• depthSwapchain باید یک شناسه معتبر XrDepthSwapchainANDROID باشد.
• acquireInfo باید یک اشاره‌گر به یک ساختار معتبر XrDepthAcquireInfoANDROID باشد.
• acquireResult باید یک اشاره‌گر به ساختار XrDepthAcquireResultANDROID باشد.

کدهای بازگشت

موفقیت

• 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 مشخص می‌کند. برنامه‌ها باید زمان نمایش پیش‌بینی‌شده‌ی خود را برای فریم فعلی ارسال کنند.

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

• قبل از استفاده از XrDepthAcquireInfoANDROID، افزونه‌ی XR_ANDROID_depth_texture باید فعال باشد.
• type باید XR_TYPE_DEPTH_ACQUIRE_INFO_ANDROID باشد.
• next باید NULL یا یک اشاره‌گر معتبر به ساختار بعدی در یک زنجیره ساختار باشد.
• space باید یک شناسه معتبر XrSpace باشد.

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

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

• قبل از استفاده از XrDepthAcquireResultANDROID، افزونه‌ی XR_ANDROID_depth_texture باید فعال باشد.
• type باید XR_TYPE_DEPTH_ACQUIRE_RESULT_ANDROID باشد.
• next باید NULL یا یک اشاره‌گر معتبر به ساختار بعدی در یک زنجیره ساختار باشد.
• هر عنصر داده شده از 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 مشخص شده است.

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

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

کد نمونه برای ردیابی عمق

کد مثال زیر نحوه‌ی به دست آوردن تصاویر عمق و استفاده از مقادیر عمق برای نگاشت مختصات تصویر عمق به فضای صحنه را نشان می‌دهد.

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
    // ...
}

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

• زنجیره تعویض XrDepth اندروید

دستورات جدید

• xrAcquireDepthSwapchainImagesANDROID
• xrCreateDepthSwapchain اندروید
• xrDestroyDepthSwapchain اندروید
• xrEnumerateDepthResolutions اندروید
• xrEnumerateDepthSwapchainImagesANDROID

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

• XrDepthAcquireInfoاندروید
• XrDepthAcquireResultاندروید
• XrDepthSwapchainCreateInfoANDROID
• XrDepthSwapchainImageANDROID
• نمای عمق Xr اندروید

• بسط XrSystemProperties :

  • ویژگی‌های ردیابی عمق XrSystemDepth در اندروید

Enum های جدید

• XrDepth Camera ResolutionANDROID
• XrDepthSwapchainCreateFlagBitsANDROID

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

• XrDepthSwapchainCreateFlagsANDROID

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

• 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 (لوانا چن)

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