Android XR SDK พร้อมใช้งานในเวอร์ชันตัวอย่างสำหรับนักพัฒนาแอปแล้ว เราอยากฟังความคิดเห็นจากคุณ โปรดไปที่หน้าการสนับสนุนเพื่อติดต่อเรา

หน้านี้ได้รับการแปลโดย Cloud Translation API

ส่วนขยาย OpenXR ของ XR_ANDROID_scene_meshing

สตริงชื่อ XR_ANDROID_scene_meshing

ประเภทส่วนขยาย ส่วนขยายอินสแตนซ์

หมายเลขต่อที่จดทะเบียน 464

การแก้ไข 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

ภาพรวม

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

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

สิทธิ์

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

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

xrCreateSceneMeshingTrackerANDROID
xrDestroySceneMeshingTrackerANDROID
xrCreateSceneMeshSnapshotANDROID
xrDestroySceneMeshSnapshotANDROID
xrGetAllSubmeshStatesANDROID
xrGetSubmeshDataANDROID

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

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

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

XrSystemSceneMeshingPropertiesANDROID

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

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

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

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

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

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

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

XrSceneMeshSemanticLabelSetANDROID

การแจงนับ 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;

xrEnumerateSupportedSemanticLabelSetsANDROID

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

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

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

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

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

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

XrSceneMeshingTrackerANDROID

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

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

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

xrCreateSceneMeshingTrackerANDROID

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

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

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

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

หากระบบไม่รองรับการเชื่อมโยงฉาก xrCreateSceneMeshingTrackerANDROID จะแสดงผล XR_ERROR_FEATURE_UNSUPPORTED แอปพลิเคชันสามารถตรวจสอบการรองรับระบบได้โดยการเรียกใช้ xrGetSystemProperties ด้วยโครงสร้าง XrSystemSceneMeshingPropertiesANDROID

ใช้ได้เฉพาะชุดป้ายกำกับเชิงความหมายที่ระบบรองรับเท่านั้นใน XrSceneMeshingTrackerCreateInfoANDROID::semanticLabelSet เมื่อ สร้างเครื่องมือติดตามการสร้างตาข่ายฉาก ฟังก์ชัน xrEnumerateSupportedSemanticLabelSetsANDROID สามารถใช้เพื่อรับรายการชุดป้ายกำกับเชิงความหมายที่รองรับได้

หากแอปพลิเคชันขอ semanticLabelSet ที่ไม่รองรับ xrCreateSceneMeshingTrackerANDROID จะแสดงผล XR_ERROR_FEATURE_UNSUPPORTED

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

XrSceneMeshingTrackerCreateInfoANDROID

โครงสร้าง XrSceneMeshingTrackerCreateInfoANDROID อธิบายข้อมูลสำหรับสร้างแฮนเดิล XrSceneMeshingTrackerANDROID

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

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

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

xrDestroySceneMeshingTrackerANDROID

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

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID          tracker);

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

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

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

XrSceneMeshSnapshotANDROID

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

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

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

XrSceneMeshSnapshotCreateInfoANDROID

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

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

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

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

XrSceneMeshTrackingStateANDROID

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

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;

XrSceneMeshSnapshotCreationResultANDROID

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

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

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

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

xrCreateSceneMeshSnapshotANDROID

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

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

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

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

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

XrSceneSubmeshStateANDROID

XrSceneSubmeshStateANDROID อธิบายซับเมช มีข้อมูลพื้นฐานเกี่ยวกับ Submesh (รหัส ท่าทาง ขอบเขต เวลาที่อัปเดตล่าสุด)

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 ที่อธิบายขนาดของ กรอบล้อมรอบที่ล้อมรอบตาข่ายย่อย ขอบเขตนี้อยู่ในพื้นที่ฐานที่ใช้สร้างแฮนเดิลของตาข่ายฉาก

xrGetAllSubmeshStatesANDROID

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

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

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

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

XrSceneSubmeshDataANDROID

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

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
vertexCountOutput คือจำนวนองค์ประกอบใน vertexPositions, vertexNormals และ vertexSemantics ที่รันไทม์แก้ไขตั้งแต่ต้นอาร์เรย์
vertexPositions คืออาร์เรย์ของ XrVector3f ที่รันไทม์ จะส่งออกตำแหน่งจุดยอดของซับเมช
vertexNormals คืออาร์เรย์ของ XrVector3f ที่รันไทม์ จะส่งออกเวกเตอร์ปกติของจุดยอดของซับเมช คุณเว้นช่องนี้ไว้ได้NULLหากแอปพลิเคชันสร้างเครื่องมือติดตาม โดยปิดใช้เวกเตอร์ปกติ
vertexSemantics คืออาร์เรย์ของ uint8_t ที่รันไทม์ จะส่งออกซีแมนติกของจุดยอดของซับเมช คุณเว้นช่องนี้ว่างได้NULLหากแอปพลิเคชันสร้างเครื่องมือติดตาม โดยตั้งค่าXR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROIDป้ายกำกับเชิงความหมาย
indexCapacityInput คือความยาวของ indices
indexCountOutput คือจำนวนองค์ประกอบใน indices ที่ รันไทม์แก้ไขโดยเริ่มจากจุดเริ่มต้นของ อาร์เรย์
indices คืออาร์เรย์ของ uint32_t ซึ่งรันไทม์จะส่งออกดัชนีของซับเมช

xrGetSubmeshDataANDROID

แอปพลิเคชันสามารถใช้ฟังก์ชัน xrGetSubmeshDataANDROID เพื่อรับข้อมูลสำหรับรายการซับเมชที่เลือก ฟังก์ชันนี้ใช้ในสำนวน 2 การเรียกได้ ในการเรียกครั้งแรก แอปพลิเคชันต้องตั้งค่ารหัสตาข่ายย่อยที่ถูกต้อง (เช่น เรียกข้อมูลจาก xrGetAllSubmeshStatesANDROID ด้วยสแนปชอตของตาข่ายฉากเดียวกัน ) และความจุเป็น 0 สำหรับแต่ละองค์ประกอบในรายการตาข่ายย่อยที่เลือก เพื่อรับขนาดของบัฟเฟอร์ที่จำเป็นสำหรับข้อมูลตาข่ายย่อย ในการเรียกครั้งที่ 2 แอปพลิเคชันต้องตั้งค่าพอยน์เตอร์บัฟเฟอร์เป็นบัฟเฟอร์ที่จัดสรรแล้วสำหรับแต่ละองค์ประกอบในรายการของซับเมชที่เลือกพร้อมกับความจุของบัฟเฟอร์เพื่อรับข้อมูลของซับเมช

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

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

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

XrSceneMeshSemanticLabelANDROID

การแจงนับ 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;

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

xrDestroySceneMeshSnapshotANDROID

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

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID            snapshot);

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

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

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

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

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
  std::vector<XrSceneSubmeshStateANDROID> states;
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  states.resize(submeshCount);
  for (XrSceneSubmeshStateANDROID& state : states) {
    state = {.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.vertexCountOutput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCountOutput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCountOutput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCountOutput];
  }
  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 =
      reinterpret_cast<XrSceneMeshSemanticLabelANDROID*>(data.vertexSemantics);
    XrPosef pose = submeshesPoses[i];

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

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

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));