1Name 2 3 EGL_ANGLE_program_cache_control 4 5Name Strings 6 7 EGL_ANGLE_program_cache_control 8 9Contributors 10 11 Jamie Madill, Google 12 13Contacts 14 15 Jamie Madill (jmadill 'at' google.com) 16 17Status 18 19 Draft 20 21Version 22 23 Version 1, June 29, 2017 24 25Number 26 27 EGL Extension #?? 28 29Dependencies 30 31 Requires EGL 1.5. 32 33 Written against the EGL 1.5 specification. 34 35Overview 36 37 This extension allows the for creation of an OpenGL or OpenGL ES contexts 38 that have access to an internal binary program cache. It also allows for 39 querying and populating the contents of the binary cache. 40 41 An OpenGL ES implementation supporting GL_ANGLE_program_cache_control or 42 equivalent functionality is required. 43 44New Types 45 46 None 47 48New Procedures and Functions 49 50 EGLint eglProgramCacheGetAttribANGLE( 51 EGLDisplay dpy, 52 EGLenum attrib); 53 54 void eglProgramCacheQueryANGLE( 55 EGLDisplay dpy, 56 EGLint index, 57 void *key, 58 EGLint *keysize, 59 void *binary, 60 EGLint *binarysize); 61 62 void eglProgramCachePopulateANGLE( 63 EGLDisplay dpy, 64 const void *key, 65 EGLint keysize, 66 const void *binary, 67 EGLint binarysize); 68 69 EGLint eglProgramCacheResizeANGLE( 70 EGLDisplay dpy, 71 EGLint limit, 72 EGLenum mode); 73 74New Tokens 75 76 Accepted as a value for 'attrib' in eglProgramCacheGetAttribANGLE: 77 78 EGL_PROGRAM_CACHE_SIZE_ANGLE 0x3455 79 EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE 0x3456 80 81 Accepted as a value for 'mode' in eglProgramCacheResizeANGLE: 82 83 EGL_PROGRAM_CACHE_RESIZE_ANGLE 0x3457 84 EGL_PROGRAM_CACHE_TRIM_ANGLE 0x3458 85 86 Accepted as an attribute name in the <*attrib_list> argument to 87 eglCreateContext: 88 89 EGL_CONTEXT_PROGRAM_BINARY_CACHE_ENABLED_ANGLE 0x3459 90 91Additions to the EGL 1.5 Specification 92 93 Add the following to section 3.7.1 "Creating Rendering Contexts": 94 95 EGL_CONTEXT_PROGRAM_BINARY_CACHE_ENABLED_ANGLE indicates whether the context 96 should be created with the GL_PROGRAM_BINARY_CACHE_ENABLE_ANGLE state 97 initialized to GL_TRUE or GL_FALSE. The default value of 98 EGL_CONTEXT_PROGRAM_BINARY_CACHE_ENABLED_ANGLE is EGL_TRUE. See section 3.13 99 for details on the program binary cache. 100 101 Add a section 3.13 to the end of section 3 "EGL Program Binary Cache": 102 103 Each display has an associated program binary cache. This cache stores 104 compiled programs for re-use on subsequent calls to glLinkProgram. The 105 application can control the behaviour of the cache by enabling or disabling 106 its use per-context (see section 3.7.1) and specifying a cache size. It 107 can also query the current cache values and populate the cache during start- 108 up. 109 110 Program binary cache properties may be queried using 111 112 EGLint eglProgramCacheGetAttribANGLE(EGLDisplay dpy, EGLenum attrib); 113 114 The only accepted values for 'attrib' are EGL_PROGRAM_CACHE_SIZE_ANGLE and 115 EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE. A query for EGL_PROGRAM_CACHE_SIZE_ANGLE 116 will return the number of cache entries in the program cache. A 117 query of EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE will return the required length 118 (in bytes) of the 'key' parameter to eglProgramCacheQueryANGLE and 119 eglPopulateProgramCacheANGLE. Any other value for 'attrib' will produce an 120 error of EGL_BAD_ATTRIBUTE, and an invalid display for 'dpy' will produce an 121 error of EGL_BAD_DISPLAY. All error cases will return zero. 122 123 Cache contents may be queried by using 124 125 void eglProgramCacheQueryANGLE(EGLDisplay dpy, EGLint index, 126 void *key, EGLint *keysize, void *binary, EGLint *binarysize); 127 128 If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If 129 'index' is not equal to or greater than zero and less than 130 EGL_PROGRAM_CACHE_SIZE_ANGLE, an EGL_BAD_PARAMETER error is generated. If 131 'dpy' is not a valid display EGL_BAD_DISPLAY is generated. If 'binarysize' 132 and 'keysize' are non-null, and 'binary' and 'key' are null, the size of the 133 binary at 'index' is written to 'binarysize', and the key size to 'keysize'. 134 If 'binary' is not null, 'binarysize' specifies the maximum size of the 135 'binary' out parameter, and if 'keysize' is not null, the size of the 'key' 136 out parameter. Any attempt to write more than 'binarysize' or 'keysize' 137 bytes will produce an EGL_BAD_ACCESS error in this case. If 'keysize' or 138 'binarysize' is null, an EGL_BAD_PARAMETER error is generated. If 'key' is 139 not null, 'binary' must also be non-null, and vice versa, or an 140 EGL_BAD_PARAMETER error is generated. If the cache contents change such that 141 a cache entry at 'index' is not retrievable, either EGL_BAD_ACCESS is 142 generated or a null key and binary are returned. Valid entries returned are 143 not guaranteed to be in the cache. Otherwise, the binary is written to 144 'binary' and the program key is written to 'key'. 145 146 The cache may be warmed up on startup with 147 148 void eglProgramCachePopulateANGLE(EGLDisplay dpy, const void *key, 149 EGLint keysize, const void *binary, EGLint binarysize); 150 151 If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If 152 'binarysize' is not positive or is greater than an internally defined 153 maximum size, EGL_BAD_PARAMETER is generated. If 'keysize' does not equal 154 EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE, EGL_BAD_PARAMETER is generated. If the 155 program binary is invalid for any reason, behaviour is undefined. Otherwise 156 the program will be loaded into the internal binary cache with the key 157 'key'. If 'binary' or 'key' are null, an EGL_BAD_PARAMETER error is 158 generated. 159 160 The cache contents size may be changed using 161 162 EGLint eglProgramCacheResizeANGLE(EGLDisplay dpy, EGLint limit, 163 EGLenum mode); 164 165 If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If 166 limit is negative then EGL_BAD_PARAMETER is generated. If 'mode' is 167 EGL_PROGRAM_CACHE_RESIZE, cache contents are discarded and a new maximum 168 cache size is set to 'limit'. If 'limit' is larget than an implementation- 169 defined internal constant, EGL_BAD_PARAMETER is generated. Otherwise the 170 initial cache size is returned. If 'mode' is EGL_PROGRAM_CACHE_TRIM, cache 171 resources are released until the total cache size, in bytes, is less than or 172 equal to 'limit', and the number of bytes of memory released is returned. 173 In any error case, zero is returned. 174 175 Errors 176 177 None 178 179New State 180 181 None 182 183Conformance Tests 184 185 TBD 186 187Issues 188 189 1. Should the cache control be a property of the display or the contexts? 190 191 The cache itself will internally be a property of the display, since we 192 want to share caches between contexts. It is possible to design an 193 implementation with other kinds of cache sharing, such as between share 194 groups. 195 196 We can choose to prefer simplicity of design in this case. 197 198 RESOLVED: the cache should be a property of the display. 199 200 2. What should happen if the cache is modified as the user is querying its 201 contents? 202 203 It is more difficult to design a query API such that it can be returned 204 atomically. Hence the cache can change in some cases while it is being 205 queried. This can be controlled in the application layer. It can also be 206 locked using OS-level synchronization. 207 208 Introducing undefined behaviour can be very problematic. 209 210 RESOLVED: we should use a mutex or similar lock to allow for multithreaded 211 access, and not expose undefined behaviour. 212 213 3. Should we expose the key/value semantics or just have a binary value? 214 215 Having just the binary would eliminate one query enum, and make the APIs 216 simpler. Having both key and value represents the implementation exactly. 217 218 RESOLVED: we should expose the key to mirror the implementation. 219 220 4. Should the extension allow for setting cache size limits? 221 222 If caches are a property of the display, they could be set in 223 eglGetPlatformDisplay as an attribute. 224 225 Cache controls can be a necessary feature for memory management. 226 227 RESOLVED: yes, we should expose cache size controls. 228 229Revision History 230 231 Rev. Date Author Changes 232 ---- ------------- --------- ---------------------------------------- 233 1 June 29, 2017 jmadill Initial version 234