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