XR_ANDROID_depth_texture

Name String

XR_ANDROID_depth_texture

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

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

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

703

การแก้ไข

1

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

ยังไม่ให้สัตยาบัน

การขึ้นต่อกันของส่วนขยายและเวอร์ชัน

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 ถือเป็นสิทธิ์ที่เป็นอันตราย แอปพลิเคชันต้องขอสิทธิ์ขณะรันไทม์เพื่อใช้ฟังก์ชันต่อไปนี้

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

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

โครงสร้าง XrSystemDepthTrackingPropertiesANDROID มีคำจำกัดความดังนี้

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

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน 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 ต้องเป็น Pointer ไปยังค่า uint32_t
  • หาก resolutionCapacityInput ไม่ใช่ 0 resolutions ต้องเป็น Pointer ไปยังอาร์เรย์ของค่า 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 — ความละเอียดของรูปภาพความลึกและความเชื่อมั่นคือ 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 คือ Pointer ไปยังโครงสร้าง XrDepthSwapchainCreateInfoANDROID ที่มีพารามิเตอร์ที่จะใช้สร้าง Swapchain
  • swapchain เป็นตัวชี้ไปยังแฮนเดิลที่ส่งคืน XrDepthSwapchainANDROID ที่สร้างขึ้น

แอปพลิเคชันสามารถใช้ฟังก์ชัน xrCreateDepthSwapchainANDROID เพื่อสร้าง Depth 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 ต้องเป็น Pointer ไปยังโครงสร้าง 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 หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • resolution คือ XrDepthCameraResolutionANDROID ที่ใช้สร้างพื้นผิวความลึกและความน่าเชื่อถือ
  • createFlags คือ XrDepthSwapchainCreateFlagsANDROID อย่างน้อย 1 รายการ

โครงสร้าง 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 จะทำลายสวอปเชนความลึก หลังจากการเรียกนี้ รันไทม์อาจปล่อยหน่วยความจำและทรัพยากรที่เกี่ยวข้องทั้งหมด

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_depth_texture ก่อนที่จะเรียกใช้ xrDestroyDepthSwapchainANDROID
  • swapchain ต้องเป็นแฮนเดิล XrDepthSwapchainANDROID ที่ถูกต้อง

ความปลอดภัยของเธรด

  • การเข้าถึง swapchain และแฮนเดิลย่อยทั้งหมดต้องซิงค์ภายนอก

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

สำเร็จ

  • 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 คือ Pointer ไปยังจำนวน depthImages ที่เขียน หรือ Pointer ไปยังความจุที่จำเป็นในกรณีที่ depthImageCapacityInput ไม่เพียงพอ
  • depthImages เป็นตัวชี้ไปยังอาร์เรย์ของโครงสร้าง XrDepthSwapchainImageANDROID อาจเป็น NULL หาก depthImageCapacityInput เป็น 0
  • ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด depthImages ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

xrEnumerateDepthSwapchainImagesANDROID จะเติมข้อมูลอาร์เรย์ของโครงสร้าง XrDepthSwapchainImageANDROID โดยทรัพยากรต้องคงที่และใช้ได้ตลอดอายุการใช้งานของ XrDepthSwapchainANDROID ฟังก์ชันนี้ทำงานในลักษณะเดียวกับ xrEnumerateSwapchainImages

รันไทม์ต้องคืนค่าเนื้อหาบัฟเฟอร์ที่เหมือนกันเสมอจากการแจงนับนี้ตลอดอายุการใช้งานของ Swapchain

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

  • ต้องเปิดใช้XR_ANDROID_depth_textureส่วนขยายก่อนเรียกใช้ xrEnumerateDepthSwapchainImagesANDROID
  • depthSwapchain ต้องเป็นแฮนเดิล XrDepthSwapchainANDROID ที่ถูกต้อง
  • depthImageCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
  • หาก depthImageCapacityInput ไม่ใช่ 0 , depthImages ต้องเป็น Pointer ไปยังอาร์เรย์ของโครงสร้าง 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 หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน 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)
  • ค่าของ 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

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

ฟังก์ชัน 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_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 หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน 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 หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • acquiredIndex คือดัชนีของพื้นผิวที่ได้มาในอาร์เรย์ XrDepthSwapchainImageANDROID ที่แจงนับโดย xrEnumerateDepthSwapchainImagesANDROID
  • exposureTimestamp คือ XrTime ที่ระบุเวลาที่บันทึกแผนที่ความลึก
  • views คืออาร์เรย์ของ XrDepthViewANDROID 2 รายการ รายการหนึ่งสำหรับแต่ละตา โดยดัชนี 0 คือตาซ้าย และดัชนี 1 คือตาขวา

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

โครงสร้าง XrDepthViewANDROID มีคำจำกัดความดังนี้

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

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน 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
    // ...
}

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

คำสั่งใหม่

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

Enum ใหม่

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

ค่าคงที่ 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

ปัญหา

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

  • การแก้ไขครั้งที่ 1, 2024-09-09 (Levana Chen)

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