1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
Name
KHR_display_reference
Name Strings
EGL_KHR_display_reference
Contributors
James Jones
Daniel Kartch
Contacts
James Jones, NVIDIA (jajones 'at' nvidia.com)
Status
Complete
Ratified by the Khronos Board of Promoters on March 31, 2017.
Version
Version 4 - March 15, 2018
Number
EGL Extension #126
Extension Type
EGL client extension
Dependencies
Written based on the wording of the EGL 1.5 specification.
Requires EGL_EXT_platform_base or EGL 1.5
Interacts with EGL platform extensions.
Interacts with the EGL_EXT_device_query extension.
Overview
The existing semantics of EGLDisplay object lifetimes work well for
applications in which one module manages all EGL usage, and in which
EGL displays are expected to remain available until application
termination once they are instantiated. However, EGL does not
provide reasonable semantics in the case where applications rely on
toolkit libraries which use EGL independently from the application
itself.
This issue can be solved by adding a per-EGLDisplay reference
counter which is incremented by eglInitialize calls. Resource
destruction can then be deferred until a corresponding number of
eglTerminate calls is made. However, switching to this behavior
universally could cause backwards incompatibility problems with
existing applications that assume a single eglTerminate will
immediately free resources regardless of how many times the display
has been initialized.
We therefore must support both behaviors. A new attribute specified
when the EGLDisplay is obtained will indicate whether or not
reference counting is enabled. If an application requests the
EGLDisplay multiple times with different values for this attribute,
two separate displays will be returned. The one potential drawaback
is that these displays will have independent resource spaces, so
objects allocated from one cannot be used by the other. However, the
goal here is to support modules that access EGL independently. In
such a use case, they are not likely to need to share resources with
another module, particularly one that uses a different method for
accessing the display.
New Types
None
New Functions
EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy,
EGLint name,
EGLAttrib *value);
New Tokens
Accepted as an attribute in the <attrib_list> parameter of
eglGetPlatformDisplay and the <name> parameter of
eglQueryDisplayAttribKHR:
EGL_TRACK_REFERENCES_KHR 0x3352
In section "3.2 Initialization":
Remove the sentence in the description of eglGetPlatformDisplay
indicating no valid attribute names are defined, and add the following:
The EGL_TRACK_REFERENCES_KHR attribute may be set to EGL_TRUE or
EGL_FALSE to indicate whether or not an EGLDisplay that tracks
reference counts for eglInitialize and eglTerminate calls (as
described below) is desired. If not specified, the default is
platform dependent. Implementations are not required to support both
EGL_TRUE and EGL_FALSE for this attribute. If separate successful
calls are made to eglGetPlatformDisplay requesting default and non-
default behavior for reference counting, two independent EGLDisplays
will be returned.
Also add to the Errors section:
An EGL_BAD_ATTRIBUTE error is generated if the requested value for
EGL_TRACK_REFERENCES_KHR is not supported.
Replace the first sentence of the second paragraph of the description of
eglInitialize with:
When a previously uninitialized display is initialized, its
reference count will be set to one. Initializing an already-
initialized display is allowed, and will return EGL_TRUE and update
the EGL version numbers, but has no other effect except to increment
the display's reference count if its EGL_TRACK_REFERENCES_KHR
attribute is EGL_TRUE.
Insert after the declaration of eglTerminate:
If the specified display's EGL_TRACK_REFERENCES_KHR attribute is
EGL_FALSE, eglTerminate will immediately set its reference count
to zero. Otherwise, its reference count will be decremented if it
is above zero. When an initialized display's reference count reaches
zero, termination will occur.
Replace the second sentence of the last paragraph with:
All displays start out uninitialized with a reference count of zero.
Add to the end of section "3.3 EGL Queries".
To query non-string attributes of an initialized display, use:
EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy,
EGLint name,
EGLAttrib *value);
On success, EGL_TRUE is returned, and the value of the attribute
specified by <name> is returned in the space pointed to by <value>.
On failure, EGL_FALSE is returned. An EGL_NOT_INITIALIZED error
is generated if EGL is not initialized for <dpy>. An
EGL_BAD_ATTRIBUTE error is generated if <name> is not a valid
value. Currently, the only valid attribute name is
EGL_TRACK_REFERENCES_KHR.
Interactions with EGL_KHR_platform_android:
If eglGetPlatformDisplay() is called with <platform> set to
EGL_PLATFORM_ANDROID_KHR, the default value of
EGL_TRACK_REFERENCES_KHR is EGL_TRUE.
Interactions with EGL_EXT_platform_device, EGL_KHR_platform_gbm,
EGL_KHR_platform_x11, and EGL_KHR_platform_wayland:
If eglGetPlatformDisplay() is called with <platform> set to
EGL_PLATFORM_DEVICE_EXT, EGL_PLATFORM_GBM_KHR, EGL_PLATFORM_X11_KHR,
or EGL_PLATFORM_WAYLAND_KHR, the default value of
EGL_TRACK_REFERENCES_KHR is EGL_FALSE.
Interactions with EGL_EXT_device_query:
The eglQueryDisplayAttribKHR function defined here is equivalent to
eglQueryDisplayAttribEXT defined by EGL_EXT_device_query, and the
attribute names supported are a superset of those provided by both
extensions and any others which rely on them.
Issues
1. What is the default value for EGL_TRACK_REFERENCES_KHR?
RESOLUTION: For backwards compatibility reasons, the default
value is platform-specific. The Android platform has
historically implemented the behavior of
EGL_TRACK_REFERENCES_KHR = EGL_TRUE, while other platforms
defaulted to the opposite behavior. Application components
capable of supporting either behavior will be able to query
the value to determine how to proceed.
2. Should the value of EGL_TRACK_REFERENCES_KHR affect whether
eglGetPlatformDisplay returns a new display handle or an
existing one given otherwise identical parameters?
RESOLUTION: Yes. For any given combination of platform display
handle and other attributes, calling eglGetPlatformDisplay
with different values for EGL_TRACK_REFERENCES_KHR will result
in two different EGLDisplay handles being returned.
Resources created with respect to one of these EGLDisplays will
not be accessible to the other. This restriction is unlikely to
cause issues, because the reference counting is added primarily
to support independent toolkits. Application components which
independently initialize and terminate the display are not
likely to share resources, particularly if they use different
methods for that initialization.
3. Should the new display attribute be queryable?
RESOLUTION: Yes. Not all implemenations will support both TRUE
and FALSE for this attribute. Application components capable of
supporting either value will allow the default to be chosen, and
then query the value to determine how to handle termination.
4. Should implementations which support this extension be required
to support both TRUE and FALSE for the attribute?
RESOLUTION: No. Lack of refcounting in the core specification is
considered by many to be a flaw, and some implementations/platforms
will choose to always provide refcounting behavior. This technically
makes them non-compliant. The addition of this extension should allow
that deviation.
Revision History
#4 (March 15, 2018) Jon Leech
- Change extension number from 118 to 126 to avoid an accidental
collision.
#3 (January 12, 2017) Daniel Kartch
- Change to KHR.
- Allocate enum value.
#2 (November 15, 2016) Daniel Kartch
- Full termination portion split off into separate extension
EGL_XXX_full_termination.
- Update reference counting to have separate EGLDisplays for
the same native display, one with reference counting and
one without.
- Add query function to determine attribute value.
#1 (October 28, 2014) James Jones
- Initial draft as EGL_XXX_display_reference
|
