xref: /aosp_15_r20/external/angle/extensions/EGL_ANGLE_power_preference.txt (revision 8975f5c5ed3d1c378011245431ada316dfb6f244) 
1Name
2
3    ANGLE_power_preference
4
5Name Strings
6
7    EGL_ANGLE_power_preference
8
9Contributors
10
11    Kenneth Russell
12    Kimmo Kinnunen
13
14Contacts
15
16    Kenneth Russell, Google Inc. (kbr 'at' google.com)
17
18Status
19
20    Draft
21
22Version
23
24    Version 3, March 10, 2022
25
26Number
27
28    EGL Extension #??
29
30Dependencies
31
32    This extension is written against the wording of the EGL 1.4
33    Specification.
34
35Overview
36
37    This extension allows selection of the high- or low-power GPU on
38    dual-GPU systems, specifically on macOS.
39
40New Types
41
42    None
43
44New Procedures and Functions
45
46    void eglReleaseHighPowerGPUANGLE(
47        EGLDisplay dpy,
48        EGLContext context);
49    void eglReacquireHighPowerGPUANGLE(
50        EGLDisplay dpy,
51        EGLContext context);
52    void eglHandleGPUSwitchANGLE(EGLDisplay dpy);
53    void eglForceGPUSwitchANGLE(EGLDisplay dpy, EGLint gpuIDHigh,
54        EGLint gpuIDLow);
55
56New Tokens
57
58    Accepted as an attribute name in the <*attrib_list> argument to
59    eglCreateContext:
60
61        EGL_POWER_PREFERENCE_ANGLE  0x3482
62
63    Accepted as an attribute value in the <*attrib_list> argument to
64    eglCreateContext:
65
66        EGL_LOW_POWER_ANGLE         0x0001
67        EGL_HIGH_POWER_ANGLE        0x0002
68
69Additions to the EGL 1.4 Specification
70
71    Add the following to section 3.7.1 "Creating Rendering Contexts":
72
73    EGL_POWER_PREFERENCE_ANGLE indicates whether the context should be
74    created on the integrated (low-power) or discrete (high-power) GPU
75    on dual-GPU systems. EGL_POWER_PREFERENCE_ANGLE is only a legal
76    context creation attribute when the EGL_ANGLE_power_preference
77    extension is advertised. The valid values for this attribute are
78    EGL_LOW_POWER_ANGLE and EGL_HIGH_POWER_ANGLE. If this extension is
79    advertised and this context creation attribute is not specified,
80    the default value is EGL_LOW_POWER_ANGLE.
81
82    The containing application must set the
83    NSSupportsAutomaticGraphicsSwitching attribute to true in its
84    Info.plist in order for this extension to operate as advertised.
85
86    eglReleaseHighPowerGPUANGLE, when passed an EGLContext allocated
87    with the EGL_POWER_PREFERENCE_ANGLE context creation attribute set
88    to EGL_HIGH_POWER_ANGLE, will cause that context to release its
89    hold on the high-power GPU.
90
91    eglReacquireHighPowerGPUANGLE, when passed an EGLContext allocated
92    with the EGL_POWER_PREFERENCE_ANGLE context creation attribute set
93    to EGL_HIGH_POWER_ANGLE and which was previously released via
94    eglReleaseHighPowerGPUANGLE, will cause that context to reacquire
95    its hold on the high-power GPU.
96
97    eglReleaseHighPowerGPUANGLE and eglReacquireHighPowerGPUANGLE have
98    no effect on contexts that were allocated with the
99    EGL_LOW_POWER_ANGLE preference, or contexts not allocated with
100    either preference.
101
102    For either eglReleaseHighPowerGPUANGLE or
103    eglReacquireHighPowerGPUANGLE:
104
105    If |dpy| is not a valid display, an EGL_BAD_DISPLAY error is
106    generated.
107
108    if |dpy| is an uninitialized display, an EGL_NOT_INITIALIZED error
109    is generated.
110
111    If |context| is not a valid context, an EGL_BAD_CONTEXT error is
112    generated.
113
114    eglHandleGPUSwitchANGLE should be called in response to a display
115    reconfiguration callback (registered via
116    CGDisplayRegisterReconfigurationCallback) in order to complete
117    transitions between the low-power and high-power GPUs. For calls
118    to this function:
119
120    If |dpy| is not a valid display, an EGL_BAD_DISPLAY error is
121    generated.
122
123    if |dpy| is an uninitialized display, an EGL_NOT_INITIALIZED error
124    is generated.
125
126    eglForceGPUSwitchANGLE should be called with an explicit gpuID to transition
127    between the low-power and high-power GPUs. This should be called if
128    the environment is altered in such a way that eglHandleGPUSwitchANGLE
129    will not work.
130    On the macOS platform, the sandbox policy might prevent eglHandleGPUSwitchANGLE
131    from obtaining the current main active GPU. In these cases, the gpuID can
132    be obtained another way (e.g in other process) and communicated via
133    eglForceGPUSwitchANGLE to the OpenGL display.
134    If gpuID does not match any available GPUs in the system,
135    nothing happens.
136
137    For calls to this function:
138
139    If |dpy| is not a valid display, an EGL_BAD_DISPLAY error is
140    generated.
141
142    if |dpy| is an uninitialized display, an EGL_NOT_INITIALIZED error
143    is generated.
144
145    |gpuIDHigh| the high 32 bits of the IOKit registry ID of the GPU to
146    use for all contexts in the display.
147
148    |gpuIDLow| the low 32 bits of the IOKit registry ID of the GPU to
149    use for all contexts in the display.
150
151Issues
152
153    None yet.
154
155Revision History
156
157    Rev.    Date         Author     Changes
158    ----  -------------  ---------  ----------------------------------------
159      1   Apr 16, 2019   kbr        Initial version
160      2   June 5, 2020   kbr        Add eglReleaseHighPowerGPUANGLE,
161                                      eglReacquireHighPowerGPUANGLE, and
162                                      eglHandleGPUSwitchANGLE
163      3   March 10, 2022 kkinnunen  Add eglForceGPUSwitchANGLE
164