Tiện ích OpenXR XR_ANDROID_performance_metrics

Chuỗi tên

XR_ANDROID_performance_metrics

Loại phần mở rộng

Tiện ích thực thể

Số điện thoại mở rộng đã đăng ký

466

Ngày sửa đổi gần đây nhất

2024-09-06

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu đối với tài sản trí tuệ nào.

Phần mở rộng và phần phụ thuộc phiên bản

OpenXR 1.0

Cộng tác viên

Dmitry Kotov, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Tổng quan

Tiện ích này cung cấp các API để liệt kê và truy vấn nhiều bộ đếm chỉ số hiệu suất của thiết bị XR, trình kết hợp và ứng dụng XR hiện tại. Nhà phát triển có thể thực hiện phân tích hiệu suất và tối ưu hoá mục tiêu cho ứng dụng XR bằng cách sử dụng bộ đếm chỉ số hiệu suất đang được thu thập. Ứng dụng không được thay đổi hành vi dựa trên số lần đọc bộ đếm.

Bộ đếm chỉ số hiệu suất được sắp xếp thành các giá trị XrPath được xác định trước, trong đường dẫn gốc /perfmetrics_android. Một ứng dụng có thể truy vấn các bộ đếm có sẵn thông qua xrEnumeratePerformanceMetricsCounterPathsANDROID. Dưới đây là danh sách các đường dẫn bộ đếm chỉ số hiệu suất có thể được cung cấp trên thiết bị Android:

  • /perfmetrics_android/app/cpu_frametime (mili giây, float) – thời gian đồng hồ thực mà ứng dụng đã dùng để xử lý một khung hình.
  • /perfmetrics_android/app/gpu_frametime (mili giây, float) – thời gian đồng hồ thực mà ứng dụng dành để chờ GPU hoàn tất công việc trên mỗi khung hình. Lưu ý:
    • Thời gian chờ cao có thể có nghĩa là GPU đang bận với các tác vụ khác, không nhất thiết là ứng dụng này đang làm quá nhiều việc trên GPU.
    • Thời gian chờ GPU có thể bằng 0 nếu quá trình kết xuất đã hoàn tất khi trình kết hợp kiểm tra.
  • /perfmetrics_android/app/cpu_utilization (phần trăm, số thực) – tổng tỷ lệ sử dụng CPU của ứng dụng được tính trung bình theo thời gian.
    • Chỉ số này có thể cao hơn 100% trên bộ xử lý đa nhân.
  • /perfmetrics_android/app/gpu_utilization (phần trăm) – tỷ lệ sử dụng GPU tổng thể của ứng dụng được tính trung bình theo thời gian.
  • /perfmetrics_android/app/motion_to_photon_latency (mili giây, float) – thời gian từ khi người dùng bắt đầu sự kiện chuyển động cho đến khi cập nhật hình ảnh thực tế tương ứng trên màn hình.
  • /perfmetrics_android/compositor/cpu_frametime (mili giây, float) – thời gian đồng hồ thực mà trình kết hợp đã dùng để xử lý một khung hình.
  • /perfmetrics_android/compositor/gpu_frametime (mili giây, float) – thời gian đồng hồ thực mà trình kết hợp dành để chờ GPU hoàn tất công việc trên mỗi khung hình.
  • /perfmetrics_android/compositor/dropped_frame_count (số nguyên) – tổng số khung hình bị bỏ qua từ tất cả ứng dụng.
  • /perfmetrics_android/compositor/frames_per_second (float) – số khung hình của trình kết hợp được vẽ trên thiết bị mỗi giây.
  • /perfmetrics_android/device/cpu_utilization_average (phần trăm, số thực) – tỷ lệ sử dụng CPU của thiết bị được tính trung bình trên tất cả các lõi và được tính trung bình theo thời gian.
  • /perfmetrics_android/device/cpu_utilization_worst (phần trăm, số thực) – tỷ lệ sử dụng CPU của thiết bị của lõi hoạt động kém nhất được tính trung bình theo thời gian.
  • /perfmetrics_android/device/cpu0_utilization thông qua /perfmetrics_android/device/cpuX_utilization (phần trăm, số thực, X là số lõi CPU trừ đi 1) – tốc độ sử dụng CPU của thiết bị trên mỗi lõi CPU trung bình theo thời gian.
  • /perfmetrics_android/device/cpu_frequency (MHz, float) – tần suất CPU của thiết bị được tính trung bình trên tất cả các lõi và trung bình theo thời gian.
  • /perfmetrics_android/device/gpu_utilization (phần trăm, số thực) – tỷ lệ sử dụng GPU của thiết bị tính trung bình theo thời gian.

Sau khi tạo một phiên, ứng dụng có thể sử dụng xrSetPerformanceMetricsStateANDROID để bật hệ thống chỉ số hiệu suất cho phiên đó. Ứng dụng có thể sử dụng xrQueryPerformanceMetricsCounterANDROID để truy vấn bộ đếm chỉ số hiệu suất trên một phiên đã bật hệ thống chỉ số hiệu suất hoặc sử dụng xrGetPerformanceMetricsStateANDROID để truy vấn xem hệ thống chỉ số hiệu suất có được bật hay không.

Để bật chức năng của tiện ích này, ứng dụng phải truyền tên của tiện ích vào xrCreateInstance bằng cách sử dụng tham số XrInstanceCreateInfo::enabledExtensionNames như được chỉ định trong phần Extensions (Tiện ích).

Các loại cờ mới

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;

Hằng số enum mới

Bổ sung enum XrStructureType:

  • XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Enum mới

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;

Cấu trúc mới

Cấu trúc XrPerformanceMetricsStateANDROID được xác định như sau: 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • enabled được đặt thành XR_TRUE để cho biết hệ thống chỉ số hiệu suất đang bật, XR_FALSE nếu không, khi nhận trạng thái. Khi đặt trạng thái, hãy đặt thành XR_TRUE để bật hệ thống chỉ số hiệu suất và XR_FALSE để tắt hệ thống đó.

XrPerformanceMetricsStateANDROID được cung cấp dưới dạng dữ liệu đầu vào khi gọi xrSetPerformanceMetricsStateANDROID để bật hoặc tắt hệ thống chỉ số hiệu suất. XrPerformanceMetricsStateANDROID được điền sẵn dưới dạng tham số đầu ra khi gọi xrGetPerformanceMetricsStateANDROID để truy vấn xem hệ thống chỉ số hiệu suất có được bật hay không.

Cách sử dụng hợp lệ (ngầm ẩn)

  • Bạn phải bật tiện ích XR_ANDROID_performance_metrics trước khi sử dụng XrPerformanceMetricsStateANDROID
  • type phải là XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • next phải là NULL hoặc con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc

Cấu trúc XrPerformanceMetricsCounterANDROID được xác định như sau: 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • counterFlags là một mặt nạ bit của XrPerformanceMetricsCounterFlagsANDROID mô tả tính hợp lệ của các thành phần giá trị.
  • counterUnit là một enum của XrPerformanceMetricsCounterUnitANDROID mô tả đơn vị đo lường.
  • uintValue là giá trị bộ đếm ở định dạng uint32_t. Giá trị này hợp lệ nếu counterFlags chứa XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID.
  • floatValue là giá trị bộ đếm ở định dạng float. Giá trị này hợp lệ nếu counterFlags chứa XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID.

XrPerformanceMetricsCounterANDROID được điền bằng cách gọi xrQueryPerformanceMetricsCounterANDROID để truy vấn thông tin về bộ đếm chỉ số hiệu suất theo thời gian thực.

Cách sử dụng hợp lệ (ngầm ẩn)

Hàm mới

Hàm xrEnumeratePerformanceMetricsCounterPathsANDROID liệt kê tất cả các đường dẫn bộ đếm chỉ số hiệu suất mà thời gian chạy hỗ trợ, được xác định là: 

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

Nội dung mô tả thông số

  • instance là một tay cầm XrInstance được tạo trước đó bằng xrCreateInstance.
  • counterPathCapacityInput là dung lượng của mảng counterPaths hoặc 0 để cho biết yêu cầu truy xuất dung lượng cần thiết.
  • counterPathCountOutput được thời gian chạy điền sẵn số lượng counterPaths đã ghi hoặc dung lượng cần thiết trong trường hợp counterPathCapacityInput không đủ.
  • counterPaths là một mảng XrPath do thời gian chạy điền vào, chứa tất cả bộ đếm chỉ số hiệu suất hiện có, nhưng có thể là NULL nếu counterPathCapacityInput là 0.
  • Hãy xem phần Tham số kích thước bộ đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước counterPaths bắt buộc.

Cách sử dụng hợp lệ (ngầm ẩn)

  • Bạn phải bật tiện ích XR_ANDROID_performance_metrics trước khi gọi xrEnumeratePerformanceMetricsCounterPathsANDROID
  • instance phải là một tay cầm XrInstance hợp lệ
  • counterPathCountOutput phải là con trỏ đến giá trị uint32_t
  • Nếu counterPathCapacityInput không phải là 0, thì counterPaths phải là con trỏ đến một mảng các giá trị counterPathCapacityInput XrPath

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

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

Hàm xrSetPerformanceMetricsStateANDROID được xác định như sau: 

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

Nội dung mô tả thông số

Hàm xrSetPerformanceMetricsStateANDROID bật hoặc tắt hệ thống chỉ số hiệu suất.

Cách sử dụng hợp lệ (ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

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

Hàm xrGetPerformanceMetricsStateANDROID được xác định như sau: 

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

Nội dung mô tả thông số

Hàm xrGetPerformanceMetricsStateANDROID nhận trạng thái hiện tại của hệ thống chỉ số hiệu suất.

Cách sử dụng hợp lệ (ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST

Hàm xrQueryPerformanceMetricsCounterANDROID được định nghĩa là: 

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

Nội dung mô tả thông số

Hàm xrQueryPerformanceMetricsCounterANDROID truy vấn một bộ đếm chỉ số hiệu suất.

Ứng dụng phải bật hệ thống chỉ số hiệu suất bằng cách gọi xrSetPerformanceMetricsStateANDROID trước khi truy vấn chỉ số bằng xrQueryPerformanceMetricsCounterANDROID.

Cách sử dụng hợp lệ (ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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