The Android XR SDK is now available in Developer Preview. We want your feedback! Visit our support page to reach out.

XR_ANDROID_performance_metrics OpenXR extension

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

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 values, under the root path /perfmetrics_android. An application can query the available counters through 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 to enable the performance metrics system for that session. An application can use xrQueryPerformanceMetricsCounterANDROID to query a performance metrics counter on a session that has the performance metrics system enabled, or use xrGetPerformanceMetricsStateANDROID to query if the performance metrics system is enabled.

In order to enable the functionality of this extension, the application should pass the name of the extension into xrCreateInstance using the XrInstanceCreateInfo::enabledExtensionNames parameter as indicated in the 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 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 structure is defined as:

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

Member Descriptions

type is the 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 is provided as input when calling xrSetPerformanceMetricsStateANDROID to enable or disable the performance metrics system. XrPerformanceMetricsStateANDROID is populated as an output parameter when calling 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
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 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 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 describing the validity of value members.
counterUnit is an enum of 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 is populated by calling 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
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 values
counterUnit must be a valid XrPerformanceMetricsCounterUnitANDROID value

New Functions

The 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 handle previously created with 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 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 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
instance must be a valid 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 values

Return Codes

Success

XR_SUCCESS

Failure

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 function is defined as:

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

Parameter Descriptions

session is an XrSession handle previously created with xrCreateSession.
state is a pointer to an XrPerformanceMetricsStateANDROID structure.

The 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
session must be a valid XrSession handle
state must be a pointer to a valid XrPerformanceMetricsStateANDROID structure

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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 function is defined as:

XrResult xrGetPerformanceMetricsStateANDROID(
    XrSession                                   session,
    XrPerformanceMetricsStateANDROID*           state);

Parameter Descriptions

session is an XrSession handle previously created with xrCreateSession.
state is a pointer to an XrPerformanceMetricsStateANDROID structure.

The 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
session must be a valid XrSession handle
state must be a pointer to an XrPerformanceMetricsStateANDROID structure

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_VALIDATION_FAILURE
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_SESSION_LOST

The xrQueryPerformanceMetricsCounterANDROID function is defined as:

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

Parameter Descriptions

session is an XrSession handle previously created with xrCreateSession.
counterPath is a valid performance metrics counter path.
counter is a pointer to an XrPerformanceMetricsCounterANDROID structure.

The xrQueryPerformanceMetricsCounterANDROID function queries a performance metrics counter.

The application should enable the performance metrics system by calling xrSetPerformanceMetricsStateANDROID before querying metrics using xrQueryPerformanceMetricsCounterANDROID.

Valid Usage (Implicit)

The XR_ANDROID_performance_metrics extension must be enabled prior to calling xrQueryPerformanceMetricsCounterANDROID
session must be a valid XrSession handle
counter must be a pointer to an XrPerformanceMetricsCounterANDROID structure

Return Codes

Success

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Failure

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