XR_ANDROID_ Performance_metrics Расширение OpenXR

Строка имени

XR_ANDROID_performance_metrics

Тип расширения

Расширение экземпляра

Зарегистрированный внутренний номер

466

Дата последнего изменения

2024-09-06

IP-статус

Нет известных претензий на интеллектуальную собственность.

Зависимости расширений и версий

ОпенXR 1.0

Авторы

Дмитрий Котов, Google

Левана Чен, Google

Джаред Файндер, Google

Спенсер Куин, Google

Обзор

Это расширение предоставляет API-интерфейсы для перечисления и запроса различных счетчиков показателей производительности текущего устройства XR, композитора и приложения XR. Разработчики могут выполнять анализ производительности и целевую оптимизацию приложения XR, используя собираемые счетчики показателей производительности. Приложение не должно менять свое поведение в зависимости от показаний счетчика.

Счетчики показателей производительности организованы в заранее определенные значения XrPath по корневому пути /perfmetrics_android . Приложение может запросить доступные счетчики через xrEnumeratePerformanceMetricsCounterPathsANDROID . Ниже приведен список путей счетчиков показателей производительности, которые могут быть предоставлены на устройствах Android:

  • /perfmetrics_android/app/cpu_frametime (миллисекунды, с плавающей запятой) — время, потраченное клиентом на обработку кадра.
  • /perfmetrics_android/app/gpu_frametime (миллисекунды, с плавающей запятой) — время, которое клиент тратит на ожидание завершения работы графического процессора для каждого кадра. Примечания:
    • Большое время ожидания может означать, что графический процессор занят другими задачами, но не обязательно, что этот клиент выполняет слишком много работы с графическим процессором.
    • Время ожидания графического процессора может быть равно нулю, если рендеринг уже был завершен на момент проверки компоновщиком.
  • /perfmetrics_android/app/cpu_utilization (процент, число с плавающей запятой) — общий коэффициент использования ЦП приложения, усредненный с течением времени.
    • На многоядерных процессорах оно может быть выше 100%.
  • /perfmetrics_android/app/gpu_utilization (процент) — общий коэффициент использования графического процессора приложения, усредненный с течением времени.
  • /perfmetrics_android/app/motion_to_photon_latency (миллисекунды, с плавающей запятой) — время, затраченное от инициированного пользователем события движения до соответствующего физического обновления изображения на дисплее.
  • /perfmetrics_android/compositor/cpu_frametime (миллисекунды, с плавающей запятой) — время, затраченное композитором на обработку кадра.
  • /perfmetrics_android/compositor/gpu_frametime (миллисекунды, с плавающей запятой) — время, которое композитор тратит на ожидание завершения работы графического процессора для каждого кадра.
  • /perfmetrics_android/compositor/dropped_frame_count (целое число) — общее количество пропущенных кадров из всех приложений.
  • /perfmetrics_android/compositor/frames_per_sec (float) — количество кадров компоновщика, отрисовываемых на устройстве в секунду.
  • /perfmetrics_android/device/cpu_utilization_average (процент, число с плавающей запятой) — коэффициент использования ЦП устройства, усредненный по всем ядрам и усредненный по времени.
  • /perfmetrics_android/device/cpu_utilization_worst (процент, число с плавающей запятой) — коэффициент использования ЦП устройства с наихудшей производительностью ядра, усредненный с течением времени.
  • /perfmetrics_android/device/cpu0_utilization через /perfmetrics_android/device/cpuX_utilization (процент, число с плавающей запятой, X — количество ядер ЦП минус одно) — коэффициент использования ЦП устройства на одно ядро ​​ЦП, усредненный с течением времени.
  • /perfmetrics_android/device/cpu_ Frequency (МГц, с плавающей запятой) — частота ЦП устройства, усредненная по всем ядрам и усредненная по времени.
  • /perfmetrics_android/device/gpu_utilization (процент, число с плавающей запятой) — усредненный по времени коэффициент использования графического процессора устройства.

После создания сеанса приложение может использовать 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;

Новые константы перечисления

Перечисление XrStructureType расширено:

  • XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID
  • XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID

Новые перечисления 

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 — это перечисление 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 для запроса информации счетчика показателей производительности в реальном времени.

Допустимое использование (неявное)

Новые функции

Функция 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);

Описание параметров

Функция xrSetPerformanceMetricsStateANDROID включает или отключает систему показателей производительности.

Допустимое использование (неявное)

Коды возврата

Успех

  • 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);

Описание параметров

Функция xrGetPerformanceMetricsStateANDROID получает текущее состояние системы показателей производительности.

Допустимое использование (неявное)

Коды возврата

Успех

  • 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_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