**Name String**

`XR_ANDROID_performance_metrics`

**Extension Type**

Instance extension

**Registered Extension Number**

466

**Last Modified Date**

2024-09-06

**IP Status**

No known IP claims.

**Extension and Version Dependencies**

[OpenXR 1.0](https://registry.khronos.org/OpenXR/specs/1.0/man/html/openxr.html)

**Contributors**

Dmitry Kotov, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

## Overview

This extension provides APIs to enumerate and query various performance metrics counters of the current XR device, compositor and XR application. Developers**can** perform performance analysis and do targeted optimization to the XR application using the performance metrics counters being collected. The application**should**not change its behavior based on the counter reads.

The performance metrics counters are organized into predefined[`XrPath`](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrPath)values, under the root path*/perfmetrics_android*. An application**can** query the available counters through[xrEnumeratePerformanceMetricsCounterPathsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrEnumeratePerformanceMetricsCounterPathsANDROID). Here is a list of the performance metrics counter paths that**may**be provided on Android devices:

- */perfmetrics_android/app/cpu_frametime*(milliseconds, float) - wallclock time client spent to process a frame.
- */perfmetrics_android/app/gpu_frametime*(milliseconds, float) - wallclock time client spent waiting for GPU work to complete per frame. Notes:
  - A high wait time**can**mean that the GPU was busy with other tasks, not necessarily that this client is doing too much GPU work.
  - The GPU wait time**can**be zero if rendering was already complete when checked by the compositor.
- */perfmetrics_android/app/cpu_utilization*(percentage, float) - total app CPU utilization rate averaged over time.
  - It**can**be higher than 100% on multi-core processors.
- */perfmetrics_android/app/gpu_utilization*(percentage) - app total GPU utilization rate averaged over time.
- */perfmetrics_android/app/motion_to_photon_latency*(milliseconds, float) - time spent from user-initiated motion event to corresponding physical image update on the display.
- */perfmetrics_android/compositor/cpu_frametime*(milliseconds, float) - wallclock time compositor spent to process a frame.
- */perfmetrics_android/compositor/gpu_frametime*(milliseconds, float) - wallclock time compositor spent waiting for GPU work to complete per frame.
- */perfmetrics_android/compositor/dropped_frame_count*(integer) - total number of dropped frames from all apps.
- */perfmetrics_android/compositor/frames_per_second*(float) - number of compositor frames drawn on device per second.
- */perfmetrics_android/device/cpu_utilization_average*(percentage, float) - device CPU utilization rate averaged across all cores and averaged over time.
- */perfmetrics_android/device/cpu_utilization_worst*(percentage, float) - device CPU utilization rate of worst performing core averaged over time.
- */perfmetrics_android/device/cpu0_utilization*through*/perfmetrics_android/device/cpuX_utilization*(percentage, float, X is the number of CPU cores minus one) - device CPU utilization rate per CPU core averaged over time.
- */perfmetrics_android/device/cpu_frequency*(MHz, float) - device CPU frequency averaged across all cores and averaged over time.
- */perfmetrics_android/device/gpu_utilization*(percentage, float) - device GPU utilization rate averaged over time.

After a session is created, an application**can** use[xrSetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrSetPerformanceMetricsStateANDROID)to enable the performance metrics system for that session. An application**can** use[xrQueryPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrQueryPerformanceMetricsCounterANDROID)to query a performance metrics counter on a session that has the performance metrics system enabled, or use[xrGetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrGetPerformanceMetricsStateANDROID)to query if the performance metrics system is enabled.
| **Note:** the measurement intervals of individual performance metrics counters are defined by the OpenXR runtime. The application**should**not make assumptions or change its behavior at runtime by measuring them.

In order to enable the functionality of this extension, the application**should** pass the name of the extension into[xrCreateInstance](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrCreateInstance)using the[XrInstanceCreateInfo::enabledExtensionNames](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrInstanceCreateInfo)parameter as indicated in the[Extensions](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-extensions)section.

### New Flag Types

    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;

### New Enum Constants

[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)enumeration is extended with:

- `XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID`
- `XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID`

### New Enums

    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;

### New Structures

The[XrPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsStateANDROID)structure is defined as:  

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

#### Member Descriptions

- `type`is the[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)of this structure.
- `next`is`NULL`or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
- `enabled`is set to`XR_TRUE`to indicate the performance metrics system is enabled,`XR_FALSE`otherwise, when getting state. When setting state, set to`XR_TRUE`to enable the performance metrics system and`XR_FALSE`to disable it.

[XrPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsStateANDROID)is provided as input when calling[xrSetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrSetPerformanceMetricsStateANDROID)to enable or disable the performance metrics system.[XrPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsStateANDROID)is populated as an output parameter when calling[xrGetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrGetPerformanceMetricsStateANDROID)to query if the performance metrics system is enabled.

#### Valid Usage (Implicit)

- The`XR_ANDROID_performance_metrics`extension**must** be enabled prior to using[XrPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsStateANDROID)
- `type`**must** be`XR_TYPE_PERFORMANCE_METRICS_STATE_ANDROID`
- `next`**must** be`NULL`or a valid pointer to the next structure in a structure chain

The[XrPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsCounterANDROID)structure is defined as:  

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

#### Member Descriptions

- `type`is the[XrStructureType](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrStructureType)of this structure.
- `next`is`NULL`or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
- `counterFlags`is a bitmask of[XrPerformanceMetricsCounterFlagsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsCounterFlagsANDROID)describing the validity of value members.
- `counterUnit`is an enum of[XrPerformanceMetricsCounterUnitANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsCounterUnitANDROID)describing the measurement unit.
- `uintValue`is the counter value in`uint32_t`format. It is valid if`counterFlags`contains`XR_PERFORMANCE_METRICS_COUNTER_UINT_VALUE_VALID_BIT_ANDROID`.
- `floatValue`is the counter value in`float`format. It is valid if`counterFlags`contains`XR_PERFORMANCE_METRICS_COUNTER_FLOAT_VALUE_VALID_BIT_ANDROID`.

[XrPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsCounterANDROID)is populated by calling[xrQueryPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrQueryPerformanceMetricsCounterANDROID)to query real-time performance metrics counter information.

#### Valid Usage (Implicit)

- The`XR_ANDROID_performance_metrics`extension**must** be enabled prior to using[XrPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsCounterANDROID)
- `type`**must** be`XR_TYPE_PERFORMANCE_METRICS_COUNTER_ANDROID`
- `next`**must** be`NULL`or a valid pointer to the next structure in a structure chain
- `counterFlags`**must** be 0 or a valid combination of[XrPerformanceMetricsCounterFlagsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsCounterFlagsANDROID)values
- `counterUnit`**must** be a valid[XrPerformanceMetricsCounterUnitANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsCounterUnitANDROID)value

### New Functions

The[xrEnumeratePerformanceMetricsCounterPathsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrEnumeratePerformanceMetricsCounterPathsANDROID)function enumerates all performance metrics counter paths that are supported by the runtime, it is defined as:  

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

#### Parameter Descriptions

- `instance`is an[XrInstance](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrInstance)handle previously created with[xrCreateInstance](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrCreateInstance).
- `counterPathCapacityInput`is the capacity of the`counterPaths`array, or 0 to indicate a request to retrieve the required capacity.
- `counterPathCountOutput`is filled in by the runtime with the count of`counterPaths`written or the required capacity in the case that`counterPathCapacityInput`is insufficient.
- `counterPaths`is an array of[`XrPath`](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrPath)filled in by the runtime which contains all the available performance metrics counters, but**can** be`NULL`if`counterPathCapacityInput`is 0.
- See the[Buffer Size Parameters](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-buffer-size-parameters)section for a detailed description of retrieving the required`counterPaths`size.

#### Valid Usage (Implicit)

- The`XR_ANDROID_performance_metrics`extension**must** be enabled prior to calling[xrEnumeratePerformanceMetricsCounterPathsANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrEnumeratePerformanceMetricsCounterPathsANDROID)
- `instance`**must** be a valid[XrInstance](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrInstance)handle
- `counterPathCountOutput`**must** be a pointer to a`uint32_t`value
- If`counterPathCapacityInput`is not 0,`counterPaths`**must** be a pointer to an array of`counterPathCapacityInput`[`XrPath`](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrPath)values

#### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `XR_ERROR_FUNCTION_UNSUPPORTED`
- `XR_ERROR_VALIDATION_FAILURE`
- `XR_ERROR_RUNTIME_FAILURE`
- `XR_ERROR_HANDLE_INVALID`
- `XR_ERROR_INSTANCE_LOST`
- `XR_ERROR_SIZE_INSUFFICIENT`

The[xrSetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrSetPerformanceMetricsStateANDROID)function is defined as:  

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

#### Parameter Descriptions

- `session`is an[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)handle previously created with[xrCreateSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrCreateSession).
- `state`is a pointer to an[XrPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsStateANDROID)structure.

The[xrSetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrSetPerformanceMetricsStateANDROID)function enables or disables the performance metrics system.

#### Valid Usage (Implicit)

- The`XR_ANDROID_performance_metrics`extension**must** be enabled prior to calling[xrSetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrSetPerformanceMetricsStateANDROID)
- `session`**must** be a valid[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)handle
- `state`**must** be a pointer to a valid[XrPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsStateANDROID)structure

#### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`
- `XR_SESSION_LOSS_PENDING`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `XR_ERROR_FUNCTION_UNSUPPORTED`
- `XR_ERROR_VALIDATION_FAILURE`
- `XR_ERROR_RUNTIME_FAILURE`
- `XR_ERROR_HANDLE_INVALID`
- `XR_ERROR_INSTANCE_LOST`
- `XR_ERROR_SESSION_LOST`

The[xrGetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrGetPerformanceMetricsStateANDROID)function is defined as:  

    XrResult xrGetPerformanceMetricsStateANDROID(
        XrSession                                   session,
        XrPerformanceMetricsStateANDROID*           state);

#### Parameter Descriptions

- `session`is an[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)handle previously created with[xrCreateSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrCreateSession).
- `state`is a pointer to an[XrPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsStateANDROID)structure.

The[xrGetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrGetPerformanceMetricsStateANDROID)function gets the current state of the performance metrics system.

#### Valid Usage (Implicit)

- The`XR_ANDROID_performance_metrics`extension**must** be enabled prior to calling[xrGetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrGetPerformanceMetricsStateANDROID)
- `session`**must** be a valid[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)handle
- `state`**must** be a pointer to an[XrPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsStateANDROID)structure

#### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`
- `XR_SESSION_LOSS_PENDING`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `XR_ERROR_FUNCTION_UNSUPPORTED`
- `XR_ERROR_VALIDATION_FAILURE`
- `XR_ERROR_HANDLE_INVALID`
- `XR_ERROR_INSTANCE_LOST`
- `XR_ERROR_SESSION_LOST`

The[xrQueryPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrQueryPerformanceMetricsCounterANDROID)function is defined as:  

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

#### Parameter Descriptions

- `session`is an[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)handle previously created with[xrCreateSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrCreateSession).
- `counterPath`is a valid performance metrics counter path.
- `counter`is a pointer to an[XrPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsCounterANDROID)structure.

The[xrQueryPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrQueryPerformanceMetricsCounterANDROID)function queries a performance metrics counter.

The application**should** enable the performance metrics system by calling[xrSetPerformanceMetricsStateANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrSetPerformanceMetricsStateANDROID)before querying metrics using[xrQueryPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrQueryPerformanceMetricsCounterANDROID).

#### Valid Usage (Implicit)

- The`XR_ANDROID_performance_metrics`extension**must** be enabled prior to calling[xrQueryPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#xrQueryPerformanceMetricsCounterANDROID)
- `session`**must** be a valid[XrSession](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrSession)handle
- `counter`**must** be a pointer to an[XrPerformanceMetricsCounterANDROID](https://developer.android.com/develop/xr/openxr/extensions/XR_ANDROID_performance_metrics#XrPerformanceMetricsCounterANDROID)structure

#### Return Codes

[**Success**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-successcodes)

- `XR_SUCCESS`
- `XR_SESSION_LOSS_PENDING`

[**Failure**](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#fundamentals-errorcodes)

- `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™ and the OpenXR logo are trademarks owned by The Khronos Group Inc. and are registered as a trademark in China, the European Union, Japan and the United Kingdom.