include::{generated}/meta/XR_EXT_performance_settings.adoc[]

*Last Modified Date*::
    2021-04-14
*IP Status*::
    No known IP claims.
*Contributors*::
    Armelle Laine, Qualcomm Technologies Inc, on behalf of Qualcomm
    Innovation Center, Inc +
    Rylie Pavlik, Collabora +

// REUSE-IgnoreStart

// "This submission is provided subject to and covered by the Khronos Group Intellectual
// Property ("IP") Rights Policy. No other rights are granted by this submission, and
// Khronos may elect to exercise its Copyright  license to incorporate this submission into
// other works it controls as it desires."


==== Overview

This extension defines an API for the application to give performance hints
to the runtime and for the runtime to send performance related notifications
back to the application.
This allows both sides to dial in a suitable compromise between needed CPU
and GPU performance, thermal sustainability and a consistent good user
experience throughout the session.

The goal is to render frames consistently, in time, under varying system
load without consuming more energy than necessary.


In summary, the APIs allow:

* setting performance level hints

* receiving performance related notifications

==== Setting Performance Levels Hints

[[ext_performance_settings-level-definition]]
===== Performance level hint definition

The XR performance level hints for a given hardware system are expressed as
a level elink:XrPerfSettingsLevelEXT for each of the XR-critical processing
domains elink:XrPerfSettingsDomainEXT (currently defined is a CPU and a GPU
domain):

[open,refpage='XrPerfSettingsDomainEXT',type='enums',desc='XrPerfSettingsDomainEXT']
--
include::{generated}/api/enums/XrPerfSettingsDomainEXT.adoc[]
--

[open,refpage='XrPerfSettingsLevelEXT',type='enums',desc='XrPerfSettingsLevelEXT']
--
include::{generated}/api/enums/XrPerfSettingsLevelEXT.adoc[]
--

This extension defines platform-independent level hints:

* ename:XR_PERF_SETTINGS_LEVEL_POWER_SAVINGS_EXT is used by the application
  to indicate that it enters a non-XR section (head-locked / static screen),
  during which power savings are to be prioritized.
  Consistent XR compositing, consistent frame rendering, and low latency are
  not needed.
* ename:XR_PERF_SETTINGS_LEVEL_SUSTAINED_LOW_EXT is used by the application
  to indicate that it enters a low and stable complexity section, during
  which reducing power is more important than occasional late rendering
  frames.
  With such a hint, the XR Runtime still strives for consistent XR
  compositing (no tearing) within a thermally sustainable range(*), but is
  allowed to take measures to reduce power, such as increasing latencies or
  reducing headroom.
* ename:XR_PERF_SETTINGS_LEVEL_SUSTAINED_HIGH_EXT is used by the application
  to indicate that it enters a high or dynamic complexity section, during
  which the XR Runtime strives for consistent XR compositing and frame
  rendering within a thermally sustainable range(*).
* ename:XR_PERF_SETTINGS_LEVEL_BOOST_EXT is used to indicate that the
  application enters a section with very high complexity, during which the
  XR Runtime is allowed to step up beyond the thermally sustainable range.
  As not thermally sustainable, this level is meant to be used for
  short-term durations (< 30 seconds).

(*) If the application chooses one of the two sustainable levels
(ename:XR_PERF_SETTINGS_LEVEL_SUSTAINED_LOW_EXT or
ename:XR_PERF_SETTINGS_LEVEL_SUSTAINED_HIGH_EXT), the device may still run
into thermal limits under non-nominal circumstances (high room temperature,
additional background loads, extended device operation) and therefore the
application should also in the sustainable modes be prepared to react to
performance notifications (in particular
ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT and
ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT in the thermal sub-domain,
see <<ext_performance_settings-notification-levels>>). +

The XR Runtime shall select ename:XR_PERF_SETTINGS_LEVEL_SUSTAINED_HIGH_EXT
as the default hint if the application does not provide any.
The function to call for setting performance level hints is
flink:xrPerfSettingsSetPerformanceLevelEXT.

include::{generated}/api/protos/xrPerfSettingsSetPerformanceLevelEXT.no-xref.adoc[]]

===== Example of using the short-term boost level hint

For a limited amount of time, both the Mobile and PC systems can provide a
higher level of performance than is thermally sustainable.
It is desirable to make this extra computational power available for short
complex scenes, then go back to a sustainable lower level.
This section describes means for the application developer to apply settings
directing the runtime to boost performance for a short-term duration.

The application developer must pay attention to keep these boost periods
very short and carefully monitor the side effects, which may vary a lot
between different hardware systems.

.[.underline]#Sample code for temporarily boosting the performance#
[source,C,%autofit]
----
extern XrInstance instance; // <1>
extern XrSession session;

// Get function pointer for xrPerfSettingsSetPerformanceLevelEXT
PFN_xrPerfSettingsSetPerformanceLevelEXT pfnPerfSettingsSetPerformanceLevelEXT;
CHK_XR(xrGetInstanceProcAddr(instance, "xrPerfSettingsSetPerformanceLevelEXT",
                             (PFN_xrVoidFunction*)(
                             &pfnPerfSettingsSetPerformanceLevelEXT)));

// before entering the high complexity section
pfnPerfSettingsSetPerformanceLevelEXT(session, XR_PERF_SETTINGS_DOMAIN_CPU_EXT, XR_PERF_SETTINGS_LEVEL_BOOST_EXT); // <2>
pfnPerfSettingsSetPerformanceLevelEXT(session, XR_PERF_SETTINGS_DOMAIN_GPU_EXT, XR_PERF_SETTINGS_LEVEL_BOOST_EXT);

// entering the high complexity section
// ... running
// end of the high complexity section

pfnPerfSettingsSetPerformanceLevelEXT(session, XR_PERF_SETTINGS_DOMAIN_CPU_EXT, XR_PERF_SETTINGS_LEVEL_SUSTAINED_HIGH_EXT); // <3>
pfnPerfSettingsSetPerformanceLevelEXT(session, XR_PERF_SETTINGS_DOMAIN_GPU_EXT, XR_PERF_SETTINGS_LEVEL_SUSTAINED_HIGH_EXT);

----
<1> we assume that `instance` and `session` are initialized and their
    handles are available
<2> setting performance level to ename:XR_PERF_SETTINGS_LEVEL_BOOST_EXT on
    both CPU and GPU domains
<3> going back to the sustainable
    ename:XR_PERF_SETTINGS_LEVEL_SUSTAINED_HIGH_EXT

===== Example of using the sustained low level hint for the CPU domain

.[.underline]#power reduction sample code#
[source,C,%autofit]
----
extern XrInstance instance; // <1>
extern XrSession session;

// Get function pointer for xrPerfSettingsSetPerformanceLevelEXT
PFN_xrPerfSettingsSetPerformanceLevelEXT pfnPerfSettingsSetPerformanceLevelEXT;
CHK_XR(xrGetInstanceProcAddr(instance, "xrPerfSettingsSetPerformanceLevelEXT",
                             (PFN_xrVoidFunction*)(
                             &pfnPerfSettingsSetPerformanceLevelEXT)));

// before entering a low CPU complexity section
pfnPerfSettingsSetPerformanceLevelEXT(session, XR_PERF_SETTINGS_DOMAIN_CPU_EXT, XR_PERF_SETTINGS_LEVEL_SUSTAINED_LOW_EXT);
pfnPerfSettingsSetPerformanceLevelEXT(session, XR_PERF_SETTINGS_DOMAIN_GPU_EXT, XR_PERF_SETTINGS_LEVEL_SUSTAINED_HIGH_EXT); // <2>

// entering the low complexity section
// ... running
// end of the low complexity section

pfnPerfSettingsSetPerformanceLevelEXT(session, XR_PERF_SETTINGS_DOMAIN_CPU_EXT, XR_PERF_SETTINGS_LEVEL_SUSTAINED_HIGH_EXT); // <3>
----
<1> we assume that `instance` and `session` are initialized and their
    handles are available
<2> the developer may choose to only reduce CPU domain and keep the GPU
    domain at ename:XR_PERF_SETTINGS_LEVEL_SUSTAINED_HIGH_EXT
<3> going back to the sustainable
    ename:XR_PERF_SETTINGS_LEVEL_SUSTAINED_HIGH_EXT for CPU


==== Receiving Performance Related Notifications
The XR runtime shall provide performance related notifications to the
application in the following situations:

* the compositing performance within the runtime has reached a new level,
  either improved or degraded from the previous one (pname:subDomain is set
  to ename:XR_PERF_SETTINGS_SUB_DOMAIN_COMPOSITING_EXT)
* the application rendering performance has reached a new level, either
  improved or degraded from the previous one (pname:subDomain is set to
  ename:XR_PERF_SETTINGS_SUB_DOMAIN_RENDERING_EXT)
* the temperature of the device has reached a new level, either improved or
  degraded from the previous one (pname:subDomain is set to
  ename:XR_PERF_SETTINGS_SUB_DOMAIN_THERMAL_EXT).

When degradation is observed, the application should: take measures reducing
its workload, helping the compositing or rendering pname:subDomain to meet
their deadlines, or the thermal pname:subDomain to avoid or stop throttling.
When improvement is observed, the application can potentially rollback some
of its mitigations.

include::{generated}/api/structs/XrEventDataPerfSettingsEXT.no-xref.adoc[]

include::{generated}/api/enums/XrPerfSettingsSubDomainEXT.no-xref.adoc[]

===== Compositing Sub-Domain
One of the major functions the runtime shall provide is the timely
compositing of the submitted layers in the background.
The runtime has to share the CPU and GPU system resources for this operation
with the application.
Since this is extremely time sensitive - the head room is only a few
milliseconds - the runtime may have to ask the application via notifications
to cooperate and relinquish some usage of the indicated resource (CPU or GPU
domain).
Performance issues in this area that the runtime notices are notified to the
application with the pname:subDomain set to
ename:XR_PERF_SETTINGS_SUB_DOMAIN_COMPOSITING_EXT.

===== Rendering Sub-Domain
The application submits rendered layers to the runtime for compositing.
Performance issues in this area that the runtime notices (i.e. missing
submission deadlines) are notified to the application with the
pname:subDomain set to ename:XR_PERF_SETTINGS_SUB_DOMAIN_RENDERING_EXT. +

===== Thermal Sub-Domain
XR applications run at a high-performance level during long periods of time,
across a game or an entire movie session.
As form factors shrink, especially on mobile solutions, the risk of reaching
die thermal runaway or reaching the limits on skin and battery temperatures
increases.
When thermal limits are reached, the device mitigates the heat generation
leading to severe performance reductions, which greatly affects user
experience (dropped frames, high latency).

Better than dropping frames when it is too late, pro-active measures from
the application should be encouraged.

The performance notification with the pname:subDomain set to
ename:XR_PERF_SETTINGS_SUB_DOMAIN_THERMAL_EXT provides an early warning
allowing the application to take mitigation actions.

[[ext_performance_settings-notification-levels]]
===== Notification level definition

The levels are defined as follows:

include::{generated}/api/enums/XrPerfSettingsNotificationLevelEXT.no-xref.adoc[]
* ename:XR_PERF_SETTINGS_NOTIF_LEVEL_NORMAL_EXT notifies that the sub-domain
  has reached a level where no further actions other than currently applied
  are necessary.
* ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT notifies that the
  sub-domain has reached an early warning level where the application should
  start proactive mitigation actions with the goal to return to the
  ename:XR_PERF_SETTINGS_NOTIF_LEVEL_NORMAL_EXT level.
* ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT notifies that the
  sub-domain has reached a critical level with significant performance
  degradation.
  The application should take drastic mitigation action.

The above definitions summarize the broad interpretation of the notification
levels, however sub-domain specific definitions of each level and their
transitions are specified below:

* ename:XR_PERF_SETTINGS_NOTIF_LEVEL_NORMAL_EXT
** For the compositing sub-domain,
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_NORMAL_EXT indicates that the
   composition headroom is consistently being met with sufficient margin. +
   Getting into ename:XR_PERF_SETTINGS_NOTIF_LEVEL_NORMAL_EXT from
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT indicates that the
   composition headroom was consistently *met with sufficient margin during
   a sufficient time period*.
** For the rendering sub-domain,
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_NORMAL_EXT indicates that frames are
   being submitted in time to be used by the compositor. +
   Getting into ename:XR_PERF_SETTINGS_NOTIF_LEVEL_NORMAL_EXT from
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT indicates that *during a
   sufficient time period*, *none* of the due layers was *too late* to be
   picked up by the compositor.
** For the thermal sub-domain, ename:XR_PERF_SETTINGS_NOTIF_LEVEL_NORMAL_EXT
   indicates that the current load should be sustainable in the near future. +
   Getting into ename:XR_PERF_SETTINGS_NOTIF_LEVEL_NORMAL_EXT from
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT indicates that the runtime
   does not presuppose any further temperature mitigation action on the
   application side, other than the current ones.

* ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT
** For the compositing sub-domain,
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT indicates that the
   compositing headroom of the current frame was met but the margin is
   considered insufficient by the runtime, and the application should:
   reduce its workload in the notified domain to solve this problem. +
   Getting into ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT from
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT indicates that the
   compositing deadline was *not missed during a sufficient time period*.
** For the rendering sub-domain,
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT indicates that at least
   one layer is regularly late to be picked up by the compositor, resulting
   in a degraded user experience, and that the application should take
   action to consistently provide frames in a more timely manner. +
   Getting into ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT from
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT indicates that *the
   runtime has stopped any of its own independent actions* which are tied to
   the ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT level.
** For the thermal sub-domain, the
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT indicates that the runtime
   expects the device to overheat under the current load, and that the
   application should take mitigating action in order to prevent thermal
   throttling. +
   Getting into ename:XR_PERF_SETTINGS_NOTIF_LEVEL_WARNING_EXT from
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT indicates that *the
   underlying system thermal throttling has stopped*.

* ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT
** For the compositing sub-domain,
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT indicates that
   composition can no longer be maintained under the current workload.
   The runtime may take independent action that will interfere with the
   application (e.g. limiting the framerate, ignoring submitted layers, or
   shutting down the application) in order to correct this problem.
** For the rendering sub-domain,
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT indicates that at least
   one layer is *too often* late to be picked up by the compositor, and
   consequently the runtime may take independent action that will interfere
   with the application (e.g. informing the user that the application is not
   responding, displaying a tracking environment in order to maintain user
   orientation). +
** For the thermal sub-domain,
   ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT indicates that the
   *underlying* *system is taking measures, such as thermal throttling* to
   reduce the temperature, impacting the XR experience.​

Leaving ename:XR_PERF_SETTINGS_NOTIF_LEVEL_IMPAIRED_EXT indicates that any
mitigating actions by the runtime (e.g. down-clocking the device to stay
within thermal limits) have ended.​

[performance-settings-api]
==== Performance Settings API Reference

'''
===== [big]#xrPerfSettingsSetPerformanceLevelEXT#

[open,refpage='xrPerfSettingsSetPerformanceLevelEXT',type='protos',desc='xrPerfSettingsSetPerformanceLevelEXT',xrefs='']
--
include::{generated}/api/protos/xrPerfSettingsSetPerformanceLevelEXT.adoc[]

.Parameter Descriptions
****
* pname:session is a valid slink:XrSession handle.
* pname:domain: the processing domain for which the level hint is applied
* pname:level: the level hint to be applied
****

include::{generated}/validity/protos/xrPerfSettingsSetPerformanceLevelEXT.adoc[]
--

Refer to <<ext_performance_settings-level-definition>> for the definition of
the level enumerations.

'''
===== [big]#XrEventDataPerformanceSettingsEXT#

[open,refpage='XrEventDataPerfSettingsEXT',type='structs',desc='XrEventDataPerfSettingsEXT',xrefs='']
--
include::{generated}/api/structs/XrEventDataPerfSettingsEXT.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:domain : processing domain in which a threshold has been crossed
* pname:subDomain : system area in which a threshold has been crossed
* pname:fromLevel : enumerated notification level which has been exited
* pname:toLevel : enumerated notification level which has been entered
****

include::{generated}/validity/structs/XrEventDataPerfSettingsEXT.adoc[]
--

include::{generated}/api/enums/XrPerfSettingsDomainEXT.no-xref.adoc[]

[open,refpage='XrPerfSettingsSubDomainEXT',type='enums',desc='XrPerfSettingsSubDomainEXT',xrefs='']
--
include::{generated}/api/enums/XrPerfSettingsSubDomainEXT.adoc[]
--

[open,refpage='XrPerfSettingsNotificationLevelEXT',type='enums',desc='XrPerfSettingsNotificationLevelEXT',xrefs='']
--
include::{generated}/api/enums/XrPerfSettingsNotificationLevelEXT.adoc[]
--

*Version History*

* Revision 1, 2017-11-30 (Armelle Laine)
* Revision 2, 2021-04-13 (Rylie Pavlik)
** Correctly show function pointer retrieval in sample code
** Fix sample code callouts
* Revision 3, 2021-04-14 (Rylie Pavlik)
** Fix missing error code
* Revision 4, 2022-10-26 (Rylie Pavlik)
** Update XML markup to correct the generated valid usage

