| 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 |
