ส่วนขยาย XR_ANDROID_performance_metrics OpenXR

สตริงชื่อ

XR_ANDROID_performance_metrics

ประเภทชิ้นงาน

การขยายเวลาอินสแตนซ์

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

466

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

2024-09-06

สถานะ IP

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

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

OpenXR 1.0

ผู้เขียน

Dmitry Kotov จาก Google

Levana Chen จาก Google

Jared Finder จาก Google

Spencer Quin จาก Google

ภาพรวม

ส่วนขยายนี้ให้ API เพื่อแจกแจงและค้นหาเมตริกประสิทธิภาพต่างๆ ของตัวนับของอุปกรณ์ XR, คอมโพสิเตอร์ และแอปพลิเคชัน XR ปัจจุบัน นักพัฒนาแอปสามารถทำการวิเคราะห์ประสิทธิภาพและเพิ่มประสิทธิภาพที่มุ่งเน้นไปยังแอปพลิเคชัน XR โดยใช้ตัวนับเมตริกประสิทธิภาพที่รวบรวม ไม่ควรเปลี่ยนลักษณะการทํางานตามการอ่านเคาน์เตอร์

ตัวนับเมตริกประสิทธิภาพจะจัดระเบียบเป็นค่า XrPath ที่กําหนดไว้ล่วงหน้าในส่วนเส้นทางรูท /perfmetrics_android แอปพลิเคชันสามารถค้นหาเคาน์เตอร์ที่ใช้ได้ผ่าน xrEnumeratePerformanceMetricsCounterPathsANDROID ต่อไปนี้คือรายการเส้นทางตัวนับเมตริกประสิทธิภาพที่อาจระบุในอุปกรณ์ Android

• /perfmetrics_android/app/cpu_frametime (มิลลิวินาที, ตัวเลขทศนิยม) - เวลาตามนาฬิกาที่ไคลเอ็นต์ใช้ในการประมวลผลเฟรม
• /perfmetrics_android/app/gpu_frametime (มิลลิวินาที, ตัวเลขทศนิยม) - เวลาตามนาฬิกาที่ลูกค้าใช้ในการรอให้ GPU ทำงานเสร็จสมบูรณ์ต่อเฟรม หมายเหตุ:
  • เวลารอที่สูง อาจหมายความว่า GPU ไม่ว่างเนื่องจากมีงานอื่นๆ อยู่ ไม่ได้หมายความว่าไคลเอ็นต์นี้ใช้ GPU มากเกินไป
  • เวลารอ GPU อาจเป็น 0 ได้หากคอมโพสิตตรวจสอบแล้วพบว่าการแสดงผลเสร็จสมบูรณ์แล้ว
• /perfmetrics_android/app/cpu_utilization (เปอร์เซ็นต์, ตัวเลขทศนิยม) - อัตราการใช้งาน CPU ทั้งหมดของแอปโดยเฉลี่ยในช่วงเวลาหนึ่ง
  • สามารถมีค่ามากกว่า 100% ในโปรเซสเซอร์แบบหลายแกน
• /perfmetrics_android/app/gpu_utilization (เปอร์เซ็นต์) - อัตราการใช้งาน GPU ทั้งหมดของแอปโดยเฉลี่ยในช่วงเวลาหนึ่ง
• /perfmetrics_android/app/motion_to_photon_latency (มิลลิวินาที, ตัวเลขทศนิยม) - เวลาที่ใช้ในการประมวลผลเหตุการณ์การเคลื่อนไหวที่ผู้ใช้เริ่มจนถึงการอัปเดตรูปภาพจริงที่เกี่ยวข้องบนจอแสดงผล
• /perfmetrics_android/compositor/cpu_frametime (มิลลิวินาที, ตัวเลขทศนิยม) - เวลาตามนาฬิกาจริงที่คอมโพสิตเตอร์ใช้ในการประมวลผลเฟรม
• /perfmetrics_android/compositor/gpu_frametime (มิลลิวินาที, ตัวเลขทศนิยม) - เวลาตามนาฬิกาจริงที่คอมโพสิตอร์ใช้ในการรอให้ GPU ทำงานเสร็จสมบูรณ์ต่อเฟรม
• /perfmetrics_android/compositor/dropped_frame_count (จำนวนเต็ม) - จํานวนเฟรมทั้งหมดที่ทิ้งจากแอปทั้งหมด
• /perfmetrics_android/compositor/frames_per_second (float) - จํานวนเฟรมคอมโพสิตที่วาดในอุปกรณ์ต่อวินาที
• /perfmetrics_android/device/cpu_utilization_average (เปอร์เซ็นต์, ตัวเลขทศนิยม) - อัตราการใช้งาน CPU ของอุปกรณ์โดยเฉลี่ยจากทุกแกน และค่าเฉลี่ยตามช่วงเวลา
• /perfmetrics_android/device/cpu_utilization_worst (เปอร์เซ็นต์, ตัวเลขทศนิยม) - อัตราการใช้งาน CPU ของอุปกรณ์สำหรับแกนประมวลผลที่มีประสิทธิภาพต่ำที่สุดโดยเฉลี่ยในช่วงเวลาหนึ่ง
• /perfmetrics_android/device/cpu0_utilization ผ่าน /perfmetrics_android/device/cpuX_utilization (เปอร์เซ็นต์, ตัวเลขทศนิยม, X คือจํานวนแกน CPU ลบ 1) - อัตราการใช้งาน CPU ของอุปกรณ์ต่อแกน CPU โดยเฉลี่ยเมื่อเวลาผ่านไป
• /perfmetrics_android/device/cpu_frequency (MHz, ตัวเลขทศนิยม) - ความถี่ของ CPU ของอุปกรณ์โดยเฉลี่ยจากทุกแกนและค่าเฉลี่ยเมื่อเวลาผ่านไป
• /perfmetrics_android/device/gpu_utilization (เปอร์เซ็นต์, ตัวเลขทศนิยม) - อัตราการใช้งาน GPU ของอุปกรณ์โดยเฉลี่ยในช่วงเวลาหนึ่ง

หลังจากสร้างเซสชันแล้ว แอปพลิเคชันสามารถใช้ xrSetPerformanceMetricsStateANDROID เพื่อเปิดใช้ระบบเมตริกประสิทธิภาพสําหรับเซสชันนั้น แอปพลิเคชันสามารถใช้ xrQueryPerformanceMetricsCounterANDROID เพื่อค้นหาตัวนับเมตริกประสิทธิภาพในเซสชันที่เปิดใช้ระบบเมตริกประสิทธิภาพ หรือใช้ xrGetPerformanceMetricsStateANDROID เพื่อค้นหาว่าระบบเมตริกประสิทธิภาพเปิดใช้อยู่หรือไม่

หากต้องการเปิดใช้ฟังก์ชันการทำงานของส่วนขยายนี้ แอปพลิเคชันควรส่งชื่อส่วนขยายไปยัง xrCreateInstance โดยใช้พารามิเตอร์ XrInstanceCreateInfo::enabledExtensionNames ตามที่ระบุไว้ในส่วนส่วนขยาย

ประเภทธงใหม่

typedef XrFlags64 XrPerformanceMetricsCounterFlagsANDROID;

// Flag bits for XrPerformanceMetricsCounterFlagsANDROID
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_ANY_VALUE_VALID_BIT_ANDROID = 0x00000001;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID = 0x00000002;
static const XrPerformanceMetricsCounterFlagsANDROID XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID = 0x00000004;

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

เพิ่มรายการต่อไปนี้ในคําจํากัดความของ XrStructureType

• XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
• XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Enumeration ใหม่

typedef enum XrPerformanceMetricsCounterUnitANDROID {
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_GENERIC_ANDROID = 0,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_PERCENTAGE_ANDROID = 1,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_MILLISECONDS_ANDROID = 2,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_BYTES_ANDROID = 3,
    XR_PERFORMANCE_METRICS_COUNTER_UNIT_HERTZ_ANDROID = 4
} XrPerformanceMetricsCounterUnitANDROID;

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

โครงสร้าง XrPerformanceMetricsStateANDROID ได้รับการกําหนดดังนี้

typedef struct XrPerformanceMetricsStateANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           enabled;
} XrPerformanceMetricsStateANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• enabled มีการตั้งค่าเป็น XR_TRUE เพื่อระบุว่าระบบเมตริกประสิทธิภาพเปิดใช้อยู่ หรือ XR_FALSE หากไม่ได้เปิดใช้เมื่อรับสถานะ เมื่อตั้งค่าสถานะ ให้ตั้งค่าเป็น XR_TRUE เพื่อเปิดใช้ระบบเมตริกประสิทธิภาพ และ XR_FALSE เพื่อปิดใช้

XrPerformanceMetricsStateANDROID ใช้เป็นอินพุตเมื่อเรียกใช้ xrSetPerformanceMetricsStateANDROID เพื่อเปิดหรือปิดใช้ระบบเมตริกประสิทธิภาพ ระบบจะป้อนข้อมูล XrPerformanceMetricsStateANDROID เป็นพารามิเตอร์เอาต์พุตเมื่อเรียกใช้ xrGetPerformanceMetricsStateANDROID เพื่อสอบถามว่าเปิดใช้ระบบเมตริกประสิทธิภาพหรือไม่

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_performance_metrics ก่อนใช้ XrPerformanceMetricsStateANDROID
• type ต้องเป็น XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง

โครงสร้าง XrPerformanceMetricsCounterANDROID ได้รับการกําหนดดังนี้

typedef struct XrPerformanceMetricsCounterANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrPerformanceMetricsCounterFlagsANDROID    counterFlags;
    XrPerformanceMetricsCounterUnitANDROID     counterUnit;
    uint32_t                                   uintValue;
    float                                      floatValue;
} XrPerformanceMetricsCounterANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• counterFlags คือบิตมาสก์ของ XrPerformanceMetricsCounterFlagsANDROID ที่อธิบายความถูกต้องของสมาชิกค่า
• counterUnit คือ enum ของ XrPerformanceMetricsCounterUnitANDROID ที่อธิบายหน่วยวัด
• uintValue คือค่าตัวนับในรูปแบบ uint32_t ใช้ได้หาก counterFlags มี XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID
• floatValue คือค่าตัวนับในรูปแบบ float ใช้ได้หาก counterFlags มี XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID

XrPerformanceMetricsCounterANDROID จะสร้างขึ้นโดยการเรียกใช้ xrQueryPerformanceMetricsCounterANDROID เพื่อค้นหาข้อมูลเคาน์เตอร์เมตริกประสิทธิภาพแบบเรียลไทม์

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_performance_metrics ก่อนใช้ XrPerformanceMetricsCounterANDROID
• type ต้องเป็น XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• counterFlags ต้องเป็น 0 หรือชุดค่าผสมที่ถูกต้องของค่า XrPerformanceMetricsCounterFlagsANDROID
• counterUnit ต้องเป็นค่า XrPerformanceMetricsCounterUnitANDROID ที่ถูกต้อง

ฟังก์ชันใหม่

ฟังก์ชัน xrEnumeratePerformanceMetricsCounterPathsANDROID จะแสดงรายการเส้นทางตัวนับเมตริกประสิทธิภาพทั้งหมดที่รันไทม์รองรับ โดยคําจํากัดความมีดังนี้

XrResult xrEnumeratePerformanceMetricsCounterPathsANDROID(
    XrInstance                                  instance,
    uint32_t                                    counterPathCapacityInput,
    uint32_t*                                   counterPathCountOutput,
    XrPath*                                     counterPaths);

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

• instance คือแฮนเดิล XrInstance ที่สร้างขึ้นก่อนหน้านี้ด้วย xrCreateInstance
• counterPathCapacityInput คือความจุของอาร์เรย์ counterPaths หรือ 0 เพื่อระบุคําขอดึงข้อมูลความจุที่จําเป็น
• รันไทม์จะกรอก counterPathCountOutput ด้วยจํานวน counterPaths ที่เขียนหรือความจุที่จําเป็นในกรณีที่ counterPathCapacityInput ไม่เพียงพอ
• counterPaths คืออาร์เรย์ของ XrPath ที่รันไทม์กรอกข้อมูลไว้ ซึ่งมีตัวนับเมตริกประสิทธิภาพทั้งหมดที่ใช้ได้ แต่สามารถเป็น NULL ได้หาก counterPathCapacityInput เป็น 0
• ดูรายละเอียดเกี่ยวกับการดึงข้อมูลcounterPathsขนาดที่ต้องการได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_performance_metrics ก่อนเรียกใช้ xrEnumeratePerformanceMetricsCounterPathsANDROID
• instance ต้องเป็นตัวแฮนเดิล XrInstance ที่ถูกต้อง
• counterPathCountOutput ต้องเป็นพอยน์เตอร์ไปยังค่า uint32_t
• หาก counterPathCapacityInput ไม่ใช่ 0 counterPaths ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า counterPathCapacityInput XrPath

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

สำเร็จ

• XR_SUCCESS

ไม่สำเร็จ

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

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

XrResult xrSetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    const XrPerformanceMetricsStateANDROID*     state);

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

• session คือแฮนเดิล XrSession ที่สร้างขึ้นก่อนหน้านี้ด้วย xrCreateSession
• state เป็นพอยน์เตอร์ไปยังโครงสร้าง XrPerformanceMetricsStateANDROID

ฟังก์ชัน xrSetPerformanceMetricsStateANDROID จะเปิดหรือปิดใช้ระบบเมตริกประสิทธิภาพ

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_performance_metrics ก่อนเรียกใช้ xrSetPerformanceMetricsStateANDROID
• session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
• state ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrPerformanceMetricsStateANDROID ที่ถูกต้อง

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

สำเร็จ

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ไม่สำเร็จ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST

ฟังก์ชัน xrGetPerformanceMetricsStateANDROID ได้รับการกําหนดดังนี้

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

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

• session คือแฮนเดิล XrSession ที่สร้างขึ้นก่อนหน้านี้ด้วย xrCreateSession
• state เป็นพอยน์เตอร์ไปยังโครงสร้าง XrPerformanceMetricsStateANDROID

ฟังก์ชัน xrGetPerformanceMetricsStateANDROID จะรับสถานะปัจจุบันของระบบเมตริกประสิทธิภาพ

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_performance_metrics ก่อนเรียกใช้ xrGetPerformanceMetricsStateANDROID
• session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
• state ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrPerformanceMetricsStateANDROID

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

สำเร็จ

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ไม่สำเร็จ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST

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

XrResult xrQueryPerformanceMetricsCounterANDROID(
    XrSession                                   session,
    XrPath                                      counterPath,
    XrPerformanceMetricsCounterANDROID*         counter);

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

• session คือแฮนเดิล XrSession ที่สร้างขึ้นก่อนหน้านี้ด้วย xrCreateSession
• counterPath เป็นเส้นทางตัวนับเมตริกประสิทธิภาพที่ถูกต้อง
• counter เป็นพอยน์เตอร์ไปยังโครงสร้าง XrPerformanceMetricsCounterANDROID

ฟังก์ชัน xrQueryPerformanceMetricsCounterANDROID จะค้นหาตัวนับเมตริกประสิทธิภาพ

แอปพลิเคชันควรเปิดใช้ระบบเมตริกประสิทธิภาพโดยการเรียกใช้ xrSetPerformanceMetricsStateANDROID ก่อนการค้นหาเมตริกโดยใช้ xrQueryPerformanceMetricsCounterANDROID

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_performance_metrics ก่อนเรียกใช้ xrQueryPerformanceMetricsCounterANDROID
• session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
• counter ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrPerformanceMetricsCounterANDROID

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

สำเร็จ

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ไม่สำเร็จ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_PATH_UNSUPPORTED
• XR_ERROR_PATH_INVALID