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

Имя Строка

XR_ANDROID_performance_metrics

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

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

Зарегистрированный добавочный номер

466

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

2024-09-06

Статус ИС

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

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

OpenXR 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 (миллисекунды, float) — время, затраченное клиентом на ожидание завершения работы GPU на кадр. Примечания:
    • Большое время ожидания может означать, что графический процессор был занят другими задачами, а не обязательно, что этот клиент выполняет слишком много работы с графическим процессором.
    • Время ожидания графического процессора может быть равно нулю, если рендеринг уже был завершен на момент проверки композитором.
  • /perfmetrics_android/app/cpu_utilization (процент, число с плавающей точкой) — общий уровень использования ЦП приложением, усредненный по времени.
    • На многоядерных процессорах этот показатель может превышать 100%.
  • /perfmetrics_android/app/gpu_utilization (в процентах) — общий уровень использования графического процессора приложения, усредненный по времени.
  • /perfmetrics_android/app/motion_to_photon_latency (миллисекунды, число с плавающей точкой) — время, прошедшее от момента инициированного пользователем события движения до соответствующего обновления физического изображения на дисплее.
  • /perfmetrics_android/compositor/cpu_frametime (миллисекунды, float) - время, затраченное компоновщиком на обработку кадра.
  • /perfmetrics_android/compositor/gpu_frametime (миллисекунды, число с плавающей точкой) — время, затрачиваемое композитором на ожидание завершения работы графического процессора для каждого кадра.
  • /perfmetrics_android/compositor/dropped_frame_count (integer) — общее количество пропущенных кадров из всех приложений.
  • /perfmetrics_android/compositor/frames_per_second (float) — количество кадров композитора, отрисовываемых на устройстве в секунду.
  • /perfmetrics_android/device/cpu_utilization_average (percentage, float) — усредненный по всем ядрам и усредненный по времени уровень использования ЦП устройства.
  • /perfmetrics_android/device/cpu_utilization_worst (процент, число с плавающей точкой) — усредненный по времени уровень загрузки процессора устройства для ядра с наихудшей производительностью.
  • /perfmetrics_android/device/cpu0_utilization — /perfmetrics_android/device/cpuX_utilization (процент, число с плавающей точкой, X — количество ядер ЦП минус один) — усредненный по времени уровень использования ЦП устройства на ядро ​​ЦП.
  • /perfmetrics_android/device/cpu_frequency (МГц, float) — частота процессора устройства, усредненная по всем ядрам и усредненная по времени.
  • /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 для запроса информации счетчика показателей производительности в реальном времени.

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

  • Расширение 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);

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

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

OpenXR™ и логотип OpenXR являются товарными знаками компании Khronos Group Inc. и зарегистрированы в качестве товарного знака в Китае, Европейском Союзе, Японии и Великобритании.