XR_ANDROID_depth_texture

Name String

XR_ANDROID_depth_texture

ประเภทส่วนขยาย

ส่วนขยายอินสแตนซ์

หมายเลขต่อที่ลงทะเบียนไว้

703

การแก้ไข

1

สถานะการให้สัตยาบัน

ไม่ได้รับการให้สัตยาบัน

ทรัพยากร Dependency ของส่วนขยายและเวอร์ชัน

OpenXR 1.0

วันที่แก้ไขล่าสุด

2024-09-11

สถานะ IP

ไม่มีการอ้างสิทธิ์ IP ที่ทราบ

ผู้เขียน

Sushant Kulkarni, Google
Cairn Overturf, Google
Spencer Quin, Google
Levana Chen, Google

ภาพรวม

ส่วนขยายนี้ช่วยให้แอปพลิเคชันขอแผนที่ความลึกของสภาพแวดล้อมจริงรอบชุดหูฟังและค้นหาความละเอียดของความลึกที่รองรับเมื่อสร้างได้

ส่วนขยายนี้มีไว้เพื่อแสดงความลึกแบบข้อมูลดิบและแบบราบรื่นสำหรับการบดบัง การทดสอบตัวชี้ และงานเฉพาะอื่นๆ ที่ใช้ประโยชน์จากเรขาคณิตของฉากที่แม่นยำ เช่น การตรวจจับใบหน้าปลอม

หมายเหตุ

แผนที่ความลึกจะสร้างขึ้นโดยรันไทม์และแชร์กับแอปพลิเคชันโดยใช้ XrDepthSwapchainANDROID รันไทม์ต้องไม่เปลี่ยนความละเอียดของรูปภาพความลึกที่แสดงผลผ่าน xrEnumerateDepthResolutionsANDROID ตลอดอายุการใช้งานของแอปพลิเคชัน

สิทธิ์

ส่วนขยายนี้จะแสดงพื้นผิวความลึกที่ลดอัตราสุ่มเพื่อลดข้อกังวลเกี่ยวกับข้อมูลส่วนบุคคลที่ระบุตัวบุคคลนั้นได้ (PII) แอปพลิเคชัน Android ต้องมีสิทธิ์ android.permission.SCENE_UNDERSTANDING_FINE แสดงอยู่ในไฟล์ Manifest เนื่องจากส่วนขยายนี้จะแสดงเรขาคณิตของสภาพแวดล้อม สิทธิ์ android.permission.SCENE_UNDERSTANDING_FINE ถือเป็นสิทธิ์ที่เป็นอันตราย แอปพลิเคชันต้องขอสิทธิ์ที่รันไทม์เพื่อใช้ฟังก์ชันต่อไปนี้

• xrCreateDepthSwapchainANDROID

(ระดับการป้องกัน: อันตราย)

ตรวจสอบความสามารถของระบบ

โครงสร้าง 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

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_depth_texture ก่อนใช้ XrSystemDepthTrackingPropertiesANDROID
• 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 คือตัวชี้ไปยังจำนวน 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

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

คำอธิบาย Enumerant

• XR_DEPTH_CAMERA_RESOLUTION_80x80_ANDROID — ความละเอียดของรูปภาพความลึกและความเชื่อมั่นคือ 80x80
• XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID — ความละเอียดของรูปภาพความลึกและความเชื่อมั่นคือ 160x160
• XR_DEPTH_CAMERA_RESOLUTION_320x320_ANDROID — ความละเอียดของรูปภาพความลึกและความเชื่อมั่นคือ 320x320

สร้าง Swapchain ความลึก

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 เพื่อสร้าง Swapchain ความลึกซึ่งจัดการทั้งรูปภาพความลึกและความเชื่อมั่น

• รันไทม์ต้องแสดงผล XR_ERROR_FEATURE_UNSUPPORTED หากระบบไม่รองรับการติดตามความลึก
• รันไทม์ต้องแสดงผล XR_ERROR_PERMISSION_INSUFFICIENT หากแอปการโทรไม่ได้รับสิทธิ์ที่จำเป็น
• รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE หากไม่รองรับความละเอียดของความลึกที่ระบุใน XrDepthSwapchainCreateInfoANDROID
• รันไทม์ควรสร้างรูปภาพความเชื่อมั่นของความลึกเมื่อมีการตั้งค่าบิตที่เกี่ยวข้องสำหรับ 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 อย่างน้อย 1 รายการ

โครงสร้าง XrDepthSwapchainCreateInfoANDROID มีตัวเลือกการสร้างสำหรับ XrDepthSwapchainANDROID เมื่อส่งไปยัง xrCreateDepthSwapchainANDROID

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_depth_texture ก่อนใช้ XrDepthSwapchainCreateInfoANDROID
• 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 และแฮนเดิลย่อยต้องซิงค์กับภายนอก

รหัสการคืนสินค้า

สำเร็จ

• 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

รันไทม์ต้องแสดงเนื้อหาบัฟเฟอร์ที่เหมือนกันจากการแจงนับนี้เสมอสำหรับอายุการใช้งานของ 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 แล้ว ระบบจะถือว่าพอยน์เตอร์เป็นแบบ Dangling

XrDepthSwapchainImageANDROID แสดงรูปภาพความลึกจาก XrDepthSwapchainANDROID ที่อ่านได้ ซึ่งจัดสรรตามที่อธิบายไว้ใน XrDepthSwapchainCreateInfoANDROID :: resolution และ XrDepthSwapchainCreateInfoANDROID :: createFlags ขณะเรียกใช้ xrCreateDepthSwapchainANDROID สำหรับรูปภาพที่มีข้อมูลความลึกแต่ละรูป ให้ทำดังนี้

• ค่ารูปภาพจะจัดวางในหน่วยความจำตามลำดับแถวหลัก โดยไม่มีระยะห่างจากขอบระหว่างแถว
• ค่าแรกคือด้านซ้ายบน และค่าสุดท้ายคือด้านขวาล่าง
• ขนาดของหน่วยความจำที่ชี้ไปจะกำหนดโดยค่าของ xrEnumerateDepthSwapchainImagesANDROID และตั้งค่าโดย XrDepthSwapchainCreateInfoANDROID :: resolution ขณะเรียกใช้ xrCreateDepthSwapchainANDROID ตัวอย่างเช่น หาก XrDepthSwapchainCreateInfoANDROID :: resolution คือ XR_DEPTH_CAMERA_RESOLUTION_160x160_ANDROID รูปภาพความลึกจะมีขนาด 2*160*160*sizeof(float)
• ค่าของ rawDepthImage ต้องเป็น NULL หาก XrDepthSwapchainCreateInfoANDROID :: createFlags ไม่รวม XR_DEPTH_SWAPCHAIN_CREATE_RAW_DEPTH_IMAGE_BIT_ANDROID
• ค่าของ rawDepthConfidenceImage ต้องเป็น NULL หาก XrDepthSwapchainCreateInfoANDROID :: createFlags ไม่มี XR_DEPTH_SWAPCHAIN_CREATE_RAW_CONFIDENCE_IMAGE_BIT_ANDROID
• ค่าของ smoothDepthImage ต้องเป็น 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

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_depth_texture ก่อนใช้ XrDepthSwapchainImageANDROID
• 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 ไม่เกิน 1 ครั้งระหว่างการเรียก xrBeginFrame และ xrEndFrame ที่สอดคล้องกันในเซสชัน

• รันไทม์อาจบล็อกหากรันไทม์ยังคงใช้รูปภาพ Swapchain ที่ได้มาก่อนหน้านี้
• รันไทม์ต้องแสดงผล XR_ERROR_CALL_ORDER_INVALID หากมีการเรียกใช้ xrAcquireDepthSwapchainImagesANDROID ก่อน xrBeginFrame หรือหลัง xrEndFrame
• รันไทม์ต้องแสดงผล XR_ERROR_LIMIT_REACHED หากมีการเรียกใช้ xrAcquireDepthSwapchainImagesANDROID มากกว่า 1 ครั้งต่อเฟรม กล่าวคือ ในเซสชันที่ทำงานอยู่ หลังจากเรียกใช้ xrBeginFrame ที่ไม่มี xrEndFrame ที่เชื่อมโยง
• รันไทม์อาจแสดงผล 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 แอปพลิเคชันควรส่งเวลาแสดงผลที่คาดการณ์ไว้สำหรับเฟรมปัจจุบัน

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_depth_texture ก่อนใช้ XrDepthAcquireInfoANDROID
• 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 2 รายการ โดยแต่ละรายการจะแสดงผลสำหรับตาแต่ละข้าง โดยดัชนี 0 คือตาซ้าย และดัชนี 1 คือตาขวา

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_depth_texture ก่อนใช้ XrDepthAcquireResultANDROID
• 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

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_depth_texture ก่อนใช้ XrDepthViewANDROID
• 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
    // ...
}

ประเภทออบเจ็กต์ใหม่

• XrDepthSwapchainANDROID

คำสั่งใหม่

• xrAcquireDepthSwapchainImagesANDROID
• xrCreateDepthSwapchainANDROID
• xrDestroyDepthSwapchainANDROID
• xrEnumerateDepthResolutionsANDROID
• xrEnumerateDepthSwapchainImagesANDROID

โครงสร้างใหม่

• XrDepthAcquireInfoANDROID
• XrDepthAcquireResultANDROID
• XrDepthSwapchainCreateInfoANDROID
• XrDepthSwapchainImageANDROID
• XrDepthViewANDROID

• การขยาย XrSystemProperties :

  • XrSystemDepthTrackingPropertiesANDROID

Enum ใหม่

• XrDepthCameraResolutionANDROID
• XrDepthSwapchainCreateFlagBitsANDROID

บิตมาสก์ใหม่

• XrDepthSwapchainCreateFlagsANDROID

ค่าคงที่ Enum ใหม่

• 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

ปัญหา

ประวัติเวอร์ชัน

• Revision 1, 2024-09-09 (Levana Chen)

  • คำอธิบายส่วนขยายเริ่มต้น