Ekstensi OpenXR XR_ANDROID_performance_metrics

String Nama

XR_ANDROID_performance_metrics

Jenis Ekstensi

Ekstensi instance

Registered Extension Number

466

Tanggal Terakhir Diubah

2024-09-06

Status IP

Tidak ada klaim IP yang diketahui.

Dependensi Ekstensi dan Versi

OpenXR 1.0

Kontributor

Dmitry Kotov, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Ringkasan

Ekstensi ini menyediakan API untuk menghitung dan membuat kueri berbagai penghitung metrik performa perangkat XR, komposer, dan aplikasi XR saat ini. Developer dapat melakukan analisis performa dan melakukan pengoptimalan yang ditargetkan ke aplikasi XR menggunakan penghitung metrik performa yang dikumpulkan. Aplikasi tidak boleh mengubah perilakunya berdasarkan pembacaan penghitung.

Penghitung metrik performa diatur ke dalam nilai XrPath yang telah ditentukan sebelumnya, di jalur root /perfmetrics_android. Aplikasi dapat mengkueri penghitung yang tersedia melalui xrEnumeratePerformanceMetricsCounterPathsANDROID. Berikut adalah daftar jalur penghitung metrik performa yang mungkin disediakan di perangkat Android:

  • /perfmetrics_android/app/cpu_frametime (milidetik, float) - waktu wallclock yang dihabiskan klien untuk memproses frame.
  • /perfmetrics_android/app/gpu_frametime (milidetik, float) - waktu wallclock yang dihabiskan klien untuk menunggu tugas GPU selesai per frame. Catatan:
    • Waktu tunggu yang tinggi dapat berarti GPU sedang sibuk dengan tugas lain, bukan selalu berarti klien ini melakukan terlalu banyak pekerjaan GPU.
    • Waktu tunggu GPU dapat nol jika rendering sudah selesai saat diperiksa oleh kompositor.
  • /perfmetrics_android/app/cpu_utilization (persentase, float) - total rasio penggunaan CPU aplikasi yang dirata-ratakan dari waktu ke waktu.
    • Nilai ini dapat lebih tinggi dari 100% pada prosesor multi-core.
  • /perfmetrics_android/app/gpu_utilization (persentase) - rasio penggunaan GPU total aplikasi yang dirata-ratakan dari waktu ke waktu.
  • /perfmetrics_android/app/motion_to_photon_latency (milidetik, float) - waktu yang dihabiskan dari peristiwa gerakan yang dimulai pengguna hingga pembaruan gambar fisik yang sesuai di layar.
  • /perfmetrics_android/compositor/cpu_frametime (milidetik, float) - waktu wallclock yang dihabiskan komposer untuk memproses frame.
  • /perfmetrics_android/compositor/gpu_frametime (milidetik, float) - waktu wallclock yang dihabiskan komposer untuk menunggu tugas GPU selesai per frame.
  • /perfmetrics_android/compositor/dropped_frame_count (bilangan bulat) - jumlah total frame yang dihapus dari semua aplikasi.
  • /perfmetrics_android/compositor/frames_per_second (float) - jumlah frame kompositor yang digambar di perangkat per detik.
  • /perfmetrics_android/device/cpu_utilization_average (persentase, float) - tingkat penggunaan CPU perangkat yang dirata-ratakan di semua core dan dirata-ratakan dari waktu ke waktu.
  • /perfmetrics_android/device/cpu_utilization_worst (persentase, float) - rasio penggunaan CPU perangkat dari inti berperforma terburuk yang dirata-ratakan dari waktu ke waktu.
  • /perfmetrics_android/device/cpu0_utilization hingga /perfmetrics_android/device/cpuX_utilization (persentase, float, X adalah jumlah core CPU dikurangi satu) - tingkat penggunaan CPU perangkat per core CPU yang dirata-ratakan dari waktu ke waktu.
  • /perfmetrics_android/device/cpu_frequency (MHz, float) - frekuensi CPU perangkat yang dirata-ratakan di semua core dan dirata-ratakan dari waktu ke waktu.
  • /perfmetrics_android/device/gpu_utilization (persentase, float) - rasio penggunaan GPU perangkat yang dirata-ratakan dari waktu ke waktu.

Setelah sesi dibuat, aplikasi dapat menggunakan xrSetPerformanceMetricsStateANDROID untuk mengaktifkan sistem metrik performa untuk sesi tersebut. Aplikasi dapat menggunakan xrQueryPerformanceMetricsCounterANDROID untuk mengkueri penghitung metrik performa pada sesi yang mengaktifkan sistem metrik performa, atau menggunakan xrGetPerformanceMetricsStateANDROID untuk mengkueri apakah sistem metrik performa diaktifkan.

Untuk mengaktifkan fungsi ekstensi ini, aplikasi harus meneruskan nama ekstensi ke xrCreateInstance menggunakan parameter XrInstanceCreateInfo::enabledExtensionNames seperti yang ditunjukkan di bagian Extensions.

Jenis Flag Baru

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;

Konstanta Enum Baru

Enumerasi XrStructureType diperluas dengan:

  • XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Enum Baru

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;

Struktur Baru

Struktur XrPerformanceMetricsStateANDROID ditentukan sebagai: 

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.
  • enabled ditetapkan ke XR_TRUE untuk menunjukkan bahwa sistem metrik performa diaktifkan, XR_FALSE jika tidak, saat mendapatkan status. Saat menetapkan status, tetapkan ke XR_TRUE untuk mengaktifkan sistem metrik performa dan XR_FALSE untuk menonaktifkannya.

XrPerformanceMetricsStateANDROID disediakan sebagai input saat memanggil xrSetPerformanceMetricsStateANDROID untuk mengaktifkan atau menonaktifkan sistem metrik performa. XrPerformanceMetricsStateANDROID diisi sebagai parameter output saat memanggil xrGetPerformanceMetricsStateANDROID untuk membuat kueri apakah sistem metrik performa diaktifkan.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_performance_metrics harus diaktifkan sebelum menggunakan XrPerformanceMetricsStateANDROID
  • type harus berupa XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Struktur XrPerformanceMetricsCounterANDROID ditentukan sebagai: 

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.
  • counterFlags adalah bitmask dari XrPerformanceMetricsCounterFlagsANDROID yang menjelaskan validitas anggota nilai.
  • counterUnit adalah enum dari XrPerformanceMetricsCounterUnitANDROID yang menjelaskan satuan pengukuran.
  • uintValue adalah nilai penghitung dalam format uint32_t. Valid jika counterFlags berisi XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID.
  • floatValue adalah nilai penghitung dalam format float. Valid jika counterFlags berisi XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID.

XrPerformanceMetricsCounterANDROID diisi dengan memanggil xrQueryPerformanceMetricsCounterANDROID untuk membuat kueri informasi penghitung metrik performa real-time.

Penggunaan yang Valid (Implisit)

Fungsi Baru

Fungsi xrEnumeratePerformanceMetricsCounterPathsANDROID mencantumkan semua jalur penghitung metrik performa yang didukung oleh runtime, yang ditentukan sebagai: 

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

Deskripsi Parameter

  • instance adalah handle XrInstance yang sebelumnya dibuat dengan xrCreateInstance.
  • counterPathCapacityInput adalah kapasitas array counterPaths, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
  • counterPathCountOutput diisi oleh runtime dengan jumlah counterPaths yang ditulis atau kapasitas yang diperlukan jika counterPathCapacityInput tidak memadai.
  • counterPaths adalah array XrPath yang diisi oleh runtime yang berisi semua penghitung metrik performa yang tersedia, tetapi dapat berupa NULL jika counterPathCapacityInput adalah 0.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui penjelasan mendetail tentang pengambilan ukuran counterPaths yang diperlukan.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_performance_metrics harus diaktifkan sebelum memanggil xrEnumeratePerformanceMetricsCounterPathsANDROID
  • instance harus berupa nama sebutan channel XrInstance yang valid
  • counterPathCountOutput harus berupa pointer ke nilai uint32_t
  • Jika counterPathCapacityInput bukan 0, counterPaths harus berupa pointer ke array nilai XrPath counterPathCapacityInput

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

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

Fungsi xrSetPerformanceMetricsStateANDROID ditentukan sebagai: 

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

Deskripsi Parameter

Fungsi xrSetPerformanceMetricsStateANDROID mengaktifkan atau menonaktifkan sistem metrik performa.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

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

Fungsi xrGetPerformanceMetricsStateANDROID ditentukan sebagai: 

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

Deskripsi Parameter

Fungsi xrGetPerformanceMetricsStateANDROID mendapatkan status sistem metrik performa saat ini.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST

Fungsi xrQueryPerformanceMetricsCounterANDROID ditentukan sebagai: 

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

Deskripsi Parameter

Fungsi xrQueryPerformanceMetricsCounterANDROID membuat kueri penghitung metrik performa.

Aplikasi harus mengaktifkan sistem metrik performa dengan memanggil xrSetPerformanceMetricsStateANDROID sebelum mengkueri metrik menggunakan xrQueryPerformanceMetricsCounterANDROID.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • 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