-
Notifications
You must be signed in to change notification settings - Fork 1
/
EGL_ANGLE_program_cache_control.txt
233 lines (159 loc) · 8.29 KB
/
EGL_ANGLE_program_cache_control.txt
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
Name
EGL_ANGLE_program_cache_control
Name Strings
EGL_ANGLE_program_cache_control
Contributors
Jamie Madill, Google
Contacts
Jamie Madill (jmadill 'at' google.com)
Status
Draft
Version
Version 1, June 29, 2017
Number
EGL Extension #??
Dependencies
Requires EGL 1.5.
Written against the EGL 1.5 specification.
Overview
This extension allows the for creation of an OpenGL or OpenGL ES contexts
that have access to an internal binary program cache. It also allows for
querying and populating the contents of the binary cache.
An OpenGL ES implementation supporting GL_ANGLE_program_cache_control or
equivalent functionality is required.
New Types
None
New Procedures and Functions
EGLint eglProgramCacheGetAttribANGLE(
EGLDisplay dpy,
EGLenum attrib);
void eglProgramCacheQueryANGLE(
EGLDisplay dpy,
EGLint index,
void *key,
EGLint *keysize,
void *binary,
EGLint *binarysize);
void eglProgramCachePopulateANGLE(
EGLDisplay dpy,
const void *key,
EGLint keysize,
const void *binary,
EGLint binarysize);
EGLint eglProgramCacheResizeANGLE(
EGLDisplay dpy,
EGLint limit,
EGLenum mode);
New Tokens
Accepted as a value for 'attrib' in eglProgramCacheGetAttribANGLE:
EGL_PROGRAM_CACHE_SIZE_ANGLE 0x3455
EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE 0x3456
Accepted as a value for 'mode' in eglProgramCacheResizeANGLE:
EGL_PROGRAM_CACHE_RESIZE_ANGLE 0x3457
EGL_PROGRAM_CACHE_TRIM_ANGLE 0x3458
Accepted as an attribute name in the <*attrib_list> argument to
eglCreateContext:
EGL_CONTEXT_PROGRAM_BINARY_CACHE_ENABLED_ANGLE 0x3459
Additions to the EGL 1.5 Specification
Add the following to section 3.7.1 "Creating Rendering Contexts":
EGL_CONTEXT_PROGRAM_BINARY_CACHE_ENABLED_ANGLE indicates whether the context
should be created with the GL_PROGRAM_BINARY_CACHE_ENABLE_ANGLE state
initialized to GL_TRUE or GL_FALSE. The default value of
EGL_CONTEXT_PROGRAM_BINARY_CACHE_ENABLED_ANGLE is EGL_TRUE. See section 3.13
for details on the program binary cache.
Add a section 3.13 to the end of section 3 "EGL Program Binary Cache":
Each display has an associated program binary cache. This cache stores
compiled programs for re-use on subsequent calls to glLinkProgram. The
application can control the behaviour of the cache by enabling or disabling
its use per-context (see section 3.7.1) and specifying a cache size. It
can also query the current cache values and populate the cache during start-
up.
Program binary cache properties may be queried using
EGLint eglProgramCacheGetAttribANGLE(EGLDisplay dpy, EGLenum attrib);
The only accepted values for 'attrib' are EGL_PROGRAM_CACHE_SIZE_ANGLE and
EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE. A query for EGL_PROGRAM_CACHE_SIZE_ANGLE
will return the number of cache entries in the program cache. A
query of EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE will return the required length
(in bytes) of the 'key' parameter to eglProgramCacheQueryANGLE and
eglPopulateProgramCacheANGLE. Any other value for 'attrib' will produce an
error of EGL_BAD_ATTRIBUTE, and an invalid display for 'dpy' will produce an
error of EGL_BAD_DISPLAY. All error cases will return zero.
Cache contents may be queried by using
void eglProgramCacheQueryANGLE(EGLDisplay dpy, EGLint index,
void *key, EGLint *keysize, void *binary, EGLint *binarysize);
If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If
'index' is not equal to or greater than zero and less than
EGL_PROGRAM_CACHE_SIZE_ANGLE, an EGL_BAD_PARAMETER error is generated. If
'dpy' is not a valid display EGL_BAD_DISPLAY is generated. If 'binarysize'
and 'keysize' are non-null, and 'binary' and 'key' are null, the size of the
binary at 'index' is written to 'binarysize', and the key size to 'keysize'.
If 'binary' is not null, 'binarysize' specifies the maximum size of the
'binary' out parameter, and if 'keysize' is not null, the size of the 'key'
out parameter. Any attempt to write more than 'binarysize' or 'keysize'
bytes will produce an EGL_BAD_ACCESS error in this case. If 'keysize' or
'binarysize' is null, an EGL_BAD_PARAMETER error is generated. If 'key' is
not null, 'binary' must also be non-null, and vice versa, or an
EGL_BAD_PARAMETER error is generated. If the cache contents change such that
a cache entry at 'index' is not retrievable, either EGL_BAD_ACCESS is
generated or a null key and binary are returned. Valid entries returned are
not guaranteed to be in the cache. Otherwise, the binary is written to
'binary' and the program key is written to 'key'.
The cache may be warmed up on startup with
void eglProgramCachePopulateANGLE(EGLDisplay dpy, const void *key,
EGLint keysize, const void *binary, EGLint binarysize);
If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If
'binarysize' is not positive or is greater than an internally defined
maximum size, EGL_BAD_PARAMETER is generated. If 'keysize' does not equal
EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE, EGL_BAD_PARAMETER is generated. If the
program binary is invalid for any reason, behaviour is undefined. Otherwise
the program will be loaded into the internal binary cache with the key
'key'. If 'binary' or 'key' are null, an EGL_BAD_PARAMETER error is
generated.
The cache contents size may be changed using
EGLint eglProgramCacheResizeANGLE(EGLDisplay dpy, EGLint limit,
EGLenum mode);
If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If
limit is negative then EGL_BAD_PARAMETER is generated. If 'mode' is
EGL_PROGRAM_CACHE_RESIZE, cache contents are discarded and a new maximum
cache size is set to 'limit'. If 'limit' is larget than an implementation-
defined internal constant, EGL_BAD_PARAMETER is generated. Otherwise the
initial cache size is returned. If 'mode' is EGL_PROGRAM_CACHE_TRIM, cache
resources are released until the total cache size, in bytes, is less than or
equal to 'limit', and the number of bytes of memory released is returned.
In any error case, zero is returned.
Errors
None
New State
None
Conformance Tests
TBD
Issues
1. Should the cache control be a property of the display or the contexts?
The cache itself will internally be a property of the display, since we
want to share caches between contexts. It is possible to design an
implementation with other kinds of cache sharing, such as between share
groups.
We can choose to prefer simplicity of design in this case.
RESOLVED: the cache should be a property of the display.
2. What should happen if the cache is modified as the user is querying its
contents?
It is more difficult to design a query API such that it can be returned
atomically. Hence the cache can change in some cases while it is being
queried. This can be controlled in the application layer. It can also be
locked using OS-level synchronization.
Introducing undefined behaviour can be very problematic.
RESOLVED: we should use a mutex or similar lock to allow for multithreaded
access, and not expose undefined behaviour.
3. Should we expose the key/value semantics or just have a binary value?
Having just the binary would eliminate one query enum, and make the APIs
simpler. Having both key and value represents the implementation exactly.
RESOLVED: we should expose the key to mirror the implementation.
4. Should the extension allow for setting cache size limits?
If caches are a property of the display, they could be set in
eglGetPlatformDisplay as an attribute.
Cache controls can be a necessary feature for memory management.
RESOLVED: yes, we should expose cache size controls.
Revision History
Rev. Date Author Changes
---- ------------- --------- ----------------------------------------
1 June 29, 2017 jmadill Initial version