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