XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

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

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

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

719

การแก้ไข

3

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

ยังไม่ได้รับการรับรอง

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

OpenXR 1.0

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

2025-05-15

สถานะ IP

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

ผู้เขียน

Spencer Quin, Google
Jared Finder, Google
Antonio Fontan, Google
Cairn Overturf, Google
Nihav Jain, Google
Salar Khan, Google
Sebastian Klose, Google
Jürgen Sturm, Google
Vinny DaSilva, Google
Ricardo Campbell, Google

ภาพรวม

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

แอปพลิเคชันสามารถใช้ส่วนขยายนี้เพื่อแสดงภาพฉากและอนุญาตให้วัตถุเสมือนจริงโต้ตอบกับวัตถุจริง เช่น การชนกัน

ข้อมูลตาข่ายฉากสร้างขึ้นโดยรันไทม์และแชร์กับแอปพลิเคชันโดยใช้ XrSceneMeshingTrackerANDROID และ XrSceneMeshSnapshotANDROID แอปพลิเคชันเข้าถึงค่าในข้อมูล Submesh ของฉากได้ผ่าน XrSceneSubmeshStateANDROID ที่แสดงผลจาก xrGetAllSubmeshStatesANDROID แอปพลิเคชันสามารถเข้าถึงค่าในข้อมูลตาข่ายย่อยของฉากผ่าน XrSceneSubmeshDataANDROID ที่แสดงผลจาก xrGetSubmeshDataANDROID ได้

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

สิทธิ์

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

แอปพลิเคชันต้องขอสิทธิ์ขณะรันไทม์เพื่อใช้ฟังก์ชันต่อไปนี้

• xrCreateSceneMeshingTrackerANDROID
• xrDestroySceneMeshingTrackerANDROID
• xrCreateSceneMeshSnapshotANDROID
• xrDestroySceneMeshSnapshotANDROID
• xrGetAllSubmeshStatesANDROID
• xrGetSubmeshDataANDROID

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

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

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

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
• supportsSceneMeshing คือ XrBool32 ที่ระบุว่าระบบรองรับการเชื่อมต่อฉากหรือไม่

แอปพลิเคชันสามารถตรวจสอบว่าระบบสามารถทำ Scene Meshing ได้หรือไม่โดยการเชื่อมต่อโครงสร้าง XrSystemSceneMeshingPropertiesANDROID กับ XrSystemProperties เมื่อเรียกใช้ xrGetSystemProperties

หากรันไทม์แสดงผล XR_FALSE สำหรับ supportsSceneMeshing ระบบจะไม่รองรับการเชื่อมโยงฉาก และต้องแสดงผล XR_ERROR_FEATURE_UNSUPPORTED จาก xrCreateSceneMeshingTrackerANDROID แอปพลิเคชันควรหลีกเลี่ยงการใช้ฟังก์ชันการเชื่อมโยงฉากเมื่อ supportsSceneMeshing เป็น XR_FALSE

หากรันไทม์แสดง XR_TRUE สำหรับ supportsSceneMeshing แสดงว่าระบบรองรับการเชื่อมโยงฉาก

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

• คุณต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนจึงจะใช้ XrSystemSceneMeshingPropertiesANDROID ได้
• type ต้องเป็น XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID
• next ต้องเป็น NULL หรือ Pointer ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง

การแจงนับ XrSceneMeshSemanticLabelSetANDROID จะอธิบายชุดป้ายกำกับความหมายสำหรับการสร้างตาข่ายฉาก แต่ละค่าใน Enum นี้แสดงถึง Enum อื่นที่มีป้ายกำกับเชิงความหมาย เช่น XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID ค่าแสดงถึงชุด XrSceneMeshSemanticLabelANDROID

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

ค่าการแจงนับมีความหมายดังนี้

คำอธิบาย Enum

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

ชุดป้ายกำกับความหมายนี้แสดงถึงการไม่มีป้ายกำกับความหมาย

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

ชุดป้ายกำกับความหมายนี้แสดง XrSceneMeshSemanticLabelANDROID

ฟังก์ชัน xrEnumerateSupportedSemanticLabelSetsANDROID มีคำจำกัดความดังนี้

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

คำอธิบายพารามิเตอร์

• instance คือ XrInstance ที่แอปพลิเคชันสร้างขึ้น
• systemId คือ XrSystemId ที่ลองใหม่จาก xrGetSystem
• supportedSemanticLabelSetsInputCapacity คือความจุของ supportedSemanticLabelSets หรือ 0 เพื่อดึงข้อมูลความจุที่ต้องการ
• supportedSemanticLabelSetsOutputCount คือตัวชี้ไปยังจำนวน supportedSemanticLabelSets ที่เขียน หรือตัวชี้ไปยังความจุที่จำเป็นในกรณีที่ supportedSemanticLabelSetsInputCapacity ไม่เพียงพอ
• supportedSemanticLabelSets เป็นตัวชี้ไปยังอาร์เรย์ของ XrSceneMeshSemanticLabelSetANDROID ทำได้หาก supportedSemanticLabelSetsInputCapacity เป็น 0NULL
• ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด supportedSemanticLabelSets ที่ต้องการได้ในบทพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถแจงนับชุดป้ายกำกับเชิงความหมายที่ระบบรองรับได้โดยใช้ฟังก์ชัน xrEnumerateSupportedSemanticLabelSetsANDROID

ทุกระบบต้องรองรับ XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID เป็นอย่างน้อย เนื่องจากค่า Enum นี้แสดงถึงชุดป้ายกำกับเชิงความหมายที่ไม่มี และใช้ได้ในกรณีที่แอปพลิเคชันไม่จำเป็นต้องใช้ความหมายของจุดยอด

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนเรียกใช้ xrEnumerateSupportedSemanticLabelSetsANDROID
• instance ต้องเป็นแฮนเดิล XrInstance ที่ถูกต้อง
• supportedSemanticLabelSetsOutputCount ต้องเป็นพอยน์เตอร์ไปยังค่า uint32_t
• หาก supportedSemanticLabelSetsInputCapacity ไม่ใช่ 0 supportedSemanticLabelSets ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID

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

สำเร็จ

• XR_SUCCESS

ความล้มเหลว

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SYSTEM_INVALID
• XR_ERROR_VALIDATION_FAILURE

สร้างแฮนเดิลเครื่องมือติดตามการเชื่อมโยงฉาก

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

แฮนเดิล XrSceneMeshingTrackerANDROID แสดงถึงเครื่องมือติดตามการสร้างโมเดลฉากสำหรับการสร้างโมเดลฉากและการจัดการทรัพยากรที่เกี่ยวข้อง

แฮนเดิลนี้ใช้เพื่อสร้างสแนปชอตของตาข่ายฉากได้โดยใช้ xrCreateSceneMeshSnapshotANDROID ในส่วนขยายนี้

ฟังก์ชัน xrCreateSceneMeshingTrackerANDROID มีคำจำกัดความดังนี้

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

คำอธิบายพารามิเตอร์

• session คือ XrSession ที่จะเปิดใช้งานเครื่องมือติดตามการสร้างตาข่ายฉาก
• createInfo คือตัวชี้ไปยังโครงสร้าง XrSceneMeshingTrackerCreateInfoANDROID ที่ใช้เพื่ออธิบายเครื่องมือติดตามการสร้างตาข่ายฉากที่จะสร้างขึ้น
• tracker คือแฮนเดิล XrSceneMeshingTrackerANDROID ที่แสดงผล

แอปพลิเคชันสามารถสร้างแฮนเดิล XrSceneMeshingTrackerANDROID ได้โดยใช้ฟังก์ชัน xrCreateSceneMeshingTrackerANDROID

หากระบบไม่รองรับการเชื่อมโยงฉาก รันไทม์ต้องส่งคืน XR_ERROR_FEATURE_UNSUPPORTED จาก xrCreateSceneMeshingTrackerANDROID ในกรณีนี้ รันไทม์ต้องแสดงผล XR_FALSE สำหรับ XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing เมื่อมีการเรียกใช้ฟังก์ชัน xrGetSystemProperties เพื่อให้แอปพลิเคชันหลีกเลี่ยงการสร้างเครื่องมือติดตามการสร้างตาข่ายฉากได้

แอปพลิเคชันต้องใช้ชุดป้ายกำกับเชิงความหมายที่ระบบรองรับใน XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet เท่านั้นเมื่อสร้างเครื่องมือติดตามการสร้างตาข่ายฉาก หากแอปพลิเคชันใช้ชุดป้ายกำกับเชิงความหมายของจุดยอดใน Scene Mesh ที่ไม่รองรับ รันไทม์ต้องส่งคืน XR_ERROR_FEATURE_UNSUPPORTED จาก xrCreateSceneMeshingTrackerANDROID

แอปพลิเคชันสามารถแสดงรายการชุดป้ายกำกับเชิงความหมายที่รองรับด้วยฟังก์ชัน xrEnumerateSupportedSemanticLabelSetsANDROID

แฮนเดิล xrCreateSceneMeshingTrackerANDROID เป็นเจ้าของทรัพยากรทั้งหมดสำหรับการสร้างตาข่ายฉาก เมื่อใช้ประสบการณ์การสร้างโมเดลฉากเสร็จแล้ว แอปพลิเคชันต้องทำลายแฮนเดิลผ่านฟังก์ชัน xrDestroySceneMeshingTrackerANDROID

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนที่จะเรียกใช้ xrCreateSceneMeshingTrackerANDROID
• session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
• createInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSceneMeshingTrackerCreateInfoANDROID ที่ถูกต้อง
• tracker ต้องเป็นตัวชี้ไปยังแฮนเดิล XrSceneMeshingTrackerANDROID

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

สำเร็จ

• 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_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
• semanticLabelSet คือ XrSceneMeshSemanticLabelSetANDROID ที่ใช้เพื่อระบุชุดป้ายกำกับเชิงความหมายที่จะใช้สำหรับการสร้างตาข่ายฉาก หากตั้งค่าเป็น XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID รันไทม์จะไม่สนใจฟิลด์บัฟเฟอร์ XrSceneSubmeshDataANDROID :: vertexSemantics
• enableNormals คือ XrBool32 ที่ใช้เพื่อระบุว่าจะรวมเวกเตอร์ปกติของจุดยอดสำหรับจุดยอดของเมชในบัฟเฟอร์เมชของฉากเมื่อรับข้อมูลเมชของฉากหรือไม่

โครงสร้าง XrSceneMeshingTrackerCreateInfoANDROID อธิบายข้อมูลเพื่อสร้างแฮนเดิล XrSceneMeshingTrackerANDROID

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

• คุณต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนจึงจะใช้ XrSceneMeshingTrackerCreateInfoANDROID ได้
• type ต้องเป็น XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
• next ต้องเป็น NULL หรือ Pointer ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
• semanticLabelSet ต้องเป็นค่า XrSceneMeshSemanticLabelSetANDROID ที่ถูกต้อง

ฟังก์ชัน xrDestroySceneMeshingTrackerANDROID มีคำจำกัดความดังนี้

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

คำอธิบายพารามิเตอร์

• tracker คือ XrSceneMeshingTrackerANDROID ที่สร้างไว้ก่อนหน้านี้โดย xrCreateSceneMeshingTrackerANDROID

ฟังก์ชัน xrDestroySceneMeshingTrackerANDROID จะปล่อย tracker และทรัพยากรพื้นฐานเมื่อเสร็จสิ้นประสบการณ์การสร้างโมเดลฉาก

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนที่จะเรียกใช้ xrDestroySceneMeshingTrackerANDROID
• tracker ต้องเป็นแฮนเดิล XrSceneMeshingTrackerANDROID ที่ถูกต้อง

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

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

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

สำเร็จ

• XR_SUCCESS

ความล้มเหลว

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

สร้างแฮนเดิลสแนปชอตของตาข่ายฉาก

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

แฮนเดิล XrSceneMeshSnapshotANDROID แสดงถึงภาพรวมของ Scene Mesh สแนปชอตนี้สร้างขึ้นโดยใช้ xrCreateSceneMeshSnapshotANDROID ซึ่งจะถ่ายสแนปชอตของข้อมูลตาข่ายฉาก ณ เวลาที่เรียกใช้ฟังก์ชัน

แฮนเดิลนี้ใช้เพื่อดึงข้อมูลและข้อมูลของซับเมชได้โดยใช้ xrGetAllSubmeshStatesANDROID และ xrGetSubmeshDataANDROID

ฟังก์ชัน xrCreateSceneMeshSnapshotANDROID มีคำจำกัดความดังนี้

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

คำอธิบายพารามิเตอร์

• tracker คือแฮนเดิล XrSceneMeshingTrackerANDROID ที่สร้างไว้ก่อนหน้านี้ด้วย xrCreateSceneMeshingTrackerANDROID
• createInfo คือตัวชี้ไปยังโครงสร้าง XrSceneMeshSnapshotCreateInfoANDROID ซึ่งมีข้อมูลที่จำเป็นในการสร้างภาพรวมของ Scene Mesh
• outSnapshotCreationResult เป็นตัวชี้ไปยังออบเจ็กต์ XrSceneMeshSnapshotCreationResultANDROID ซึ่งรันไทม์จะป้อนข้อมูลผลการสร้างสแนปชอต

แอปพลิเคชันสามารถใช้ฟังก์ชัน xrCreateSceneMeshSnapshotANDROID เพื่อสร้างสแนปชอตของ Scene Mesh จากเครื่องมือติดตาม Scene Meshing ฟังก์ชันนี้จะแสดงผลแฮนเดิล XrSceneMeshSnapshotANDROID พร้อมกับ XrSceneMeshTrackingStateANDROID ที่ห่อหุ้มไว้ในโครงสร้าง XrSceneMeshSnapshotCreationResultANDROID ในทางเทคนิคแล้ว แฮนเดิลคือสแนปชอตของข้อมูลตาข่ายฉาก ณ เวลาที่สร้าง แฮนเดิลนี้ใช้เพื่อค้นหาข้อมูลและข้อมูลตาข่ายฉากได้โดยใช้ xrGetAllSubmeshStatesANDROID และ xrGetSubmeshDataANDROID ตามลำดับ

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนที่จะเรียกใช้ xrCreateSceneMeshSnapshotANDROID
• tracker ต้องเป็นแฮนเดิล XrSceneMeshingTrackerANDROID ที่ถูกต้อง
• createInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSceneMeshSnapshotCreateInfoANDROID ที่ถูกต้อง
• outSnapshotCreationResult ต้องเป็นตัวชี้ไปยังโครงสร้าง XrSceneMeshSnapshotCreationResultANDROID

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

สำเร็จ

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ความล้มเหลว

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_POSE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID

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

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
• baseSpace คือ XrSpace ที่ใช้แสดงข้อมูลท่าทางของ Submesh ของฉาก
• time คือ XrTime ที่อธิบายเวลาที่จะประมวลผลหรือแสดง Scene Mesh ซึ่งโดยปกติคือ XrFrameState :: predictedDisplayTime
• boundingBox คือ XrBoxf ที่อธิบายกรอบพื้นที่ซึ่งจะใช้รับตาข่ายฉาก

โครงสร้าง XrSceneMeshSnapshotCreateInfoANDROID อธิบายข้อมูลในการสร้างแฮนเดิล XrSceneMeshSnapshotANDROID

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนจึงจะใช้ XrSceneMeshSnapshotCreateInfoANDROID ได้
• type ต้องเป็น XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
• baseSpace ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง

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

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
• snapshot คือแฮนเดิล XrSceneMeshSnapshotANDROID ที่รันไทม์สร้างขึ้น
• trackingState คือ XrSceneMeshTrackingStateANDROID ที่อธิบายสถานะของเครื่องมือติดตามการสร้างตาข่ายฉาก ณ เวลาที่สร้างสแนปชอต

โครงสร้าง XrSceneMeshSnapshotCreationResultANDROID จะจัดเก็บผลลัพธ์ของการสร้างสแนปชอตของ Scene Mesh ที่ส่งคืนจาก xrCreateSceneMeshSnapshotANDROID

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

• คุณต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนจึงจะใช้ XrSceneMeshSnapshotCreationResultANDROID ได้
• type ต้องเป็น XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
• snapshot ต้องเป็นแฮนเดิล XrSceneMeshSnapshotANDROID ที่ถูกต้อง
• trackingState ต้องเป็นค่า XrSceneMeshTrackingStateANDROID ที่ถูกต้อง

การแจงนับ XrSceneMeshTrackingStateANDROID อธิบายสถานะการติดตามสำหรับเครื่องมือติดตามการสร้างตาข่ายฉาก ค่าแต่ละค่าใน Enum นี้แสดงถึงสถานะของเครื่องมือติดตามการสร้างโมเดลฉาก

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

ค่าการแจงนับมีความหมายดังนี้

คำอธิบาย Enum

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

เครื่องมือติดตามยังไม่พร้อมที่จะให้ข้อมูล Mesh

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

อุปกรณ์ติดตามกำลังติดตามอยู่

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

เครื่องมือติดตามกำลังรอการวัดที่ถูกต้องเพื่อผสานรวมตั้งแต่การอัปเดต Mesh ครั้งล่าสุด

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

เครื่องติดตามไม่ได้รับการวัดที่ถูกต้องเป็นเวลาหลายรอบและอยู่ในสถานะข้อผิดพลาด

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

การรับข้อมูลตาข่ายฉากจากสแนปชอตตาข่ายฉาก

ฟังก์ชัน xrGetAllSubmeshStatesANDROID มีคำจำกัดความดังนี้

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

คำอธิบายพารามิเตอร์

• snapshot คือแฮนเดิล XrSceneMeshSnapshotANDROID ที่สร้างไว้ก่อนหน้านี้ด้วย xrCreateSceneMeshSnapshotANDROID
• submeshStateCapacityInput คือความจุของ submeshStates หรือ 0 เพื่อดึงข้อมูลความจุที่ต้องการ
• submeshStateCountOutput คือตัวชี้ไปยังจำนวน submeshStates ที่เขียน หรือตัวชี้ไปยังความจุที่จำเป็นในกรณีที่ submeshStateCapacityInput ไม่เพียงพอ
• submeshStates เป็นตัวชี้ไปยังอาร์เรย์ของโครงสร้าง XrSceneSubmeshStateANDROID ซึ่งรันไทม์จะเอาต์พุตสถานะของซับเมชทั้งหมดในเมชฉาก ทำได้หาก submeshStateCapacityInput เป็น 0NULL
• ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด submeshStates ที่ต้องการได้ในบทพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถใช้ฟังก์ชัน xrGetAllSubmeshStatesANDROID เพื่อรับสถานะของ Submesh ทั้งหมดใน Scene Mesh ซึ่งมีข้อมูลพื้นฐานเพื่อให้แอปพลิเคชันเลือกซับเมชที่แอปพลิเคชันต้องการข้อมูล

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

• ต้องเปิดใช้XR_ANDROID_scene_meshingส่วนขยายก่อนเรียกใช้ xrGetAllSubmeshStatesANDROID
• snapshot ต้องเป็นแฮนเดิล XrSceneMeshSnapshotANDROID ที่ถูกต้อง
• submeshStateCountOutput ต้องเป็น Pointer ไปยังค่า uint32_t
• หาก submeshStateCapacityInput ไม่ใช่ 0 submeshStates ต้องเป็น Pointer ไปยัง อาร์เรย์ ของโครงสร้าง submeshStateCapacityInput XrSceneSubmeshStateANDROID

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

สำเร็จ

• 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

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

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
• submeshId คือ XrUuid ที่ระบุซับเมช
• lastUpdatedTime คือ XrTime ที่แสดงเวลาที่อัปเดตซับเมชครั้งล่าสุด
• submeshPoseInBaseSpace คือ XrPosef ที่แสดงท่าทางของซับเมชในพื้นที่ฐานที่ใช้สร้างสแนปชอตของเมชฉาก ท่าทางยังเป็นจุดศูนย์กลางของกรอบล้อมรอบของตาข่ายย่อยด้วย
• bounds คือ XrExtent3Df ที่อธิบายขนาดของกรอบล้อมรอบที่ล้อมรอบตาข่ายย่อย ขอบเขตนี้กำหนดไว้ในพื้นที่ฐานที่ใช้สร้างแฮนเดิลของตาข่ายฉาก

รันไทม์จะพยายามอย่างเต็มที่เพื่อแมป submeshId กับภูมิภาคของพื้นที่จริงที่ซับเมชครอบครอง รันไทม์อาจสูญเสียการเชื่อมโยงนี้ได้ทุกเมื่อ และกำหนด UUID ใหม่ให้กับชุดย่อยของ Submesh ที่ตรวจพบ โดยเฉพาะอย่างยิ่ง รันไทม์ไม่จำเป็นต้องใช้ UUID เดียวกันซ้ำสำหรับ Mesh เดียวกันในอินสแตนซ์แอปพลิเคชันที่ตามมา

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

• คุณต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนจึงจะใช้ XrSceneSubmeshStateANDROID ได้
• type ต้องเป็น XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
• next ต้องเป็น NULL หรือ Pointer ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง

ฟังก์ชัน xrGetSubmeshDataANDROID มีคำจำกัดความดังนี้

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

คำอธิบายพารามิเตอร์

• snapshot คือแฮนเดิล XrSceneMeshSnapshotANDROID ที่สร้างไว้ก่อนหน้านี้ด้วย xrCreateSceneMeshSnapshotANDROID
• submeshDataCount คือความยาวของ inoutSubmeshData
• inoutSubmeshData คืออาร์เรย์ที่จัดสรรแอปพลิเคชันของ XrSceneSubmeshDataANDROID ซึ่งรันไทม์จะสร้างแต่ละองค์ประกอบด้วยข้อมูลเมชที่เชื่อมโยงกับรหัสซับเมชที่ส่งใน XrSceneSubmeshDataANDROID :: submeshId

แอปพลิเคชันสามารถใช้ฟังก์ชัน xrGetSubmeshDataANDROID เพื่อรับกลุ่มของ Submesh หรือ Submesh ทั้งหมดพร้อมกันได้โดยการส่งรายการ XrSceneSubmeshDataANDROID ที่มี XrSceneSubmeshDataANDROID :: submeshId แต่ละรายการตั้งค่าเป็นรหัสของ Submesh ที่เกี่ยวข้องเพื่อดึงข้อมูล

XrSceneSubmeshDataANDROID :: submeshId ต้องไม่ซ้ำกันสำหรับทุกองค์ประกอบใน inoutSubmeshData และเรียกข้อมูลได้โดยใช้ xrGetAllSubmeshStatesANDROID สำหรับ snapshot เดียวกัน หากรหัส Submesh ไม่ถูกต้องหรือมีองค์ประกอบมากกว่า 1 รายการใน inoutSubmeshData ที่มีรหัส Submesh เดียวกัน รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE

submeshDataCount ต้องมีค่าเท่ากับหรือน้อยกว่าค่าที่ xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput ส่งคืน ไม่เช่นนั้นรันไทม์ต้องส่งคืน XR_ERROR_VALIDATION_FAILURE

สามารถใช้ในสำนวน 2 การเรียกเพื่อค้นหาจำนวนจุดยอดและดัชนีสำหรับตาข่ายย่อยที่เลือกทั้งหมด

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนเรียกใช้ xrGetSubmeshDataANDROID
• snapshot ต้องเป็นแฮนเดิล XrSceneMeshSnapshotANDROID ที่ถูกต้อง
• inoutSubmeshData ต้องเป็นตัวชี้ไปยังอาร์เรย์ของโครงสร้าง submeshDataCount XrSceneSubmeshDataANDROID
• พารามิเตอร์ submeshDataCount ต้องมากกว่า 0

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

สำเร็จ

• 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

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

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
• submeshId คือ XrUuid ที่ระบุซับเมช
• vertexCapacityInput คือความจุของ vertexPositions , vertexNormals และ vertexSemantics หรือ 0 เพื่อดึงข้อมูลความจุที่ต้องการ
• vertexCountOutput เป็นตัวชี้ไปยังจำนวนของ vertexPositions , vertexNormals และ vertexSemantics ที่เขียน หรือตัวชี้ไปยังความจุที่จำเป็นในกรณีที่ vertexCapacityInput ไม่เพียงพอ
• vertexPositions คืออาร์เรย์ของ XrVector3f ที่รันไทม์จะส่งออกตำแหน่งจุดยอดของซับเมช
• vertexNormals คืออาร์เรย์ของ XrVector3f ที่รันไทม์จะแสดงผลเวกเตอร์ปกติของจุดยอดของตาข่ายย่อย คุณเว้นช่องนี้ไว้ได้NULL หากแอปพลิเคชันสร้างเครื่องมือติดตามโดยปิดใช้ค่าปกติ
• vertexSemantics คืออาร์เรย์ของ uint8_t ซึ่งรันไทม์จะส่งออกความหมายของจุดยอดของตาข่ายย่อย คุณปล่อยช่องนี้ว่างไว้ได้NULL หากแอปพลิเคชันสร้างเครื่องมือติดตามที่มีชุดป้ายกำกับเชิงความหมาย XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID
• indexCapacityInput คือความจุของ indices หรือ 0 เพื่อดึงข้อมูลความจุที่ต้องการ
• indexCountOutput คือตัวชี้ไปยังจำนวน indices ที่เขียน หรือตัวชี้ไปยังความจุที่จำเป็นในกรณีที่ vertexCapacityInput ไม่เพียงพอ
• indices คืออาร์เรย์ของ uint32_t ซึ่งรันไทม์จะส่งออกดัชนีของซับเมช
• ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด vertexPositions, vertexNormals, vertexSemantics และ indices ที่จำเป็นได้ในบทพารามิเตอร์ขนาดบัฟเฟอร์

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_scene_meshing ก่อนจึงจะใช้ XrSceneSubmeshDataANDROID ได้
• type ต้องเป็น XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
• next ต้องเป็น NULL หรือ Pointer ที่ถูกต้องไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง
• หาก vertexCapacityInput ไม่ใช่ 0 vertexPositions ต้องเป็น Pointer ไปยัง อาร์เรย์ ของโครงสร้าง XrVector3f จำนวน vertexCapacityInput
• หาก vertexCapacityInput ไม่ใช่ 0 vertexNormals ต้องเป็น Pointer ไปยัง อาร์เรย์ ของโครงสร้าง XrVector3f จำนวน vertexCapacityInput
• หาก vertexCapacityInput ไม่ใช่ 0 vertexSemantics ต้องเป็น Pointer ไปยัง อาร์เรย์ ของค่า vertexCapacityInput uint8_t
• หาก indexCapacityInput ไม่ใช่ 0 indices ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า indexCapacityInput uint32_t

การแจงนับ XrSceneMeshSemanticLabelANDROID คือชุดป้ายกำกับเชิงความหมายเริ่มต้นที่ใช้ติดป้ายกำกับจุดยอดของตาข่ายเพื่ออธิบายว่าจุดยอดของตาข่ายอยู่บนพื้นผิวสภาพแวดล้อมจริงใด ชุดการแจงนับนี้แสดงด้วยค่า XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID ใน XrSceneMeshSemanticLabelSetANDROID

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

โดย Enum มีความหมายดังนี้

คำอธิบาย Enum

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

ป้ายกำกับเชิงความหมายนี้บ่งชี้ว่าองค์ประกอบของ Mesh ที่เกี่ยวข้องแสดงถึงออบเจ็กต์ที่ไม่รู้จัก

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

ป้ายกำกับเชิงความหมายนี้บ่งบอกว่าองค์ประกอบของ Mesh ที่เกี่ยวข้องแสดงถึงพื้น

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

ป้ายกำกับเชิงความหมายนี้บ่งบอกว่าองค์ประกอบของ Mesh ที่เกี่ยวข้องแสดงถึงเพดาน

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

ป้ายกำกับเชิงความหมายนี้บ่งบอกว่าองค์ประกอบของ Mesh ที่เกี่ยวข้องแสดงถึงผนัง

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

ป้ายกำกับเชิงความหมายนี้บ่งบอกว่าองค์ประกอบ Mesh ที่เกี่ยวข้องแสดงถึงตาราง

ทำลายสแนปชอตของตาข่ายฉาก

ฟังก์ชัน xrDestroySceneMeshSnapshotANDROID มีคำจำกัดความดังนี้

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

คำอธิบายพารามิเตอร์

• snapshot คือแฮนเดิล XrSceneMeshSnapshotANDROID ที่สร้างไว้ก่อนหน้านี้ด้วย xrCreateSceneMeshSnapshotANDROID ซึ่งฟังก์ชันนี้จะทำลาย

แอปพลิเคชันสามารถใช้ฟังก์ชัน xrDestroySceneMeshSnapshotANDROID เพื่อทำลายภาพรวมของตาข่ายฉากได้ เมื่อทำลายแฮนเดิลแล้ว แอปพลิเคชันจะใช้แฮนเดิลนั้นเพื่อรับข้อมูลหรือข้อมูลย่อยไม่ได้อีกต่อไป ระบบจะทำลายแฮนเดิลโดยอัตโนมัติเมื่อทำลายเครื่องมือติดตาม เนื่องจากแฮนเดิลของเครื่องมือติดตามเป็นแฮนเดิลระดับบนสุดของแฮนเดิลสแนปชอตของตาข่ายฉาก

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

• ต้องเปิดใช้XR_ANDROID_scene_meshingส่วนขยายก่อนเรียกใช้ xrDestroySceneMeshSnapshotANDROID
• snapshot ต้องเป็นแฮนเดิล XrSceneMeshSnapshotANDROID ที่ถูกต้อง

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

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

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

สำเร็จ

• XR_SUCCESS

ความล้มเหลว

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

ตัวอย่างโค้ดสำหรับการสร้างโมเดลฉาก

โค้ดตัวอย่างต่อไปนี้แสดงวิธีเข้าถึงข้อมูลตาข่ายฉากเพื่อการแสดงผล

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup
XrSpace appPlaySpace; // Created at app startup

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

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

• XrSceneMeshSnapshotANDROID
• XrSceneMeshingTrackerANDROID

คำสั่งใหม่

• xrCreateSceneMeshSnapshotANDROID
• xrCreateSceneMeshingTrackerANDROID
• xrDestroySceneMeshSnapshotANDROID
• xrDestroySceneMeshingTrackerANDROID
• xrEnumerateSupportedSemanticLabelSetsANDROID
• xrGetAllSubmeshStatesANDROID
• xrGetSubmeshDataANDROID

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

• XrSceneMeshSnapshotCreateInfoANDROID
• XrSceneMeshSnapshotCreationResultANDROID
• XrSceneMeshingTrackerCreateInfoANDROID
• XrSceneSubmeshDataANDROID
• XrSceneSubmeshStateANDROID

• การขยาย XrSystemProperties :

  • XrSystemSceneMeshingPropertiesANDROID

Enum ใหม่

• XrSceneMeshSemanticLabelANDROID
• XrSceneMeshSemanticLabelSetANDROID
• XrSceneMeshTrackingStateANDROID

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

• XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
• XR_ANDROID_scene_meshing_SPEC_VERSION

• การขยาย XrObjectType :

  • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
  • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

• การขยาย XrStructureType :

  • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
  • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
  • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
  • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

ปัญหา

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

• การแก้ไข 3, 2025-05-15 (Salar Khan)

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