Add program binary cache EGL and GL extensions.

extensions/ANGLE_program_cache_control.txt

+Name
+
+    ANGLE_program_cache_control
+
+Name Strings
+
+    GL_ANGLE_program_cache_control
+
+Contributors
+
+    Jamie Madill, Google
+
+Contacts
+
+    Jamie Madill (jmadill 'at' google.com)
+
+Status
+
+    Draft
+
+Version
+
+    Version 1, June 29, 2017
+
+Number
+
+    OpenGL ES Extension #??
+
+Dependencies
+
+    OpenGL ES 3.0 is required.
+
+    This extension is written against the wording of the OpenGL ES
+    3.0 specification.
+
+Overview
+
+    With the program cache enabled, created OpenGL ES contexts will use an
+    internal program binary cache to save linking time. The extension allows the
+    application to determine if a particular Context has this feature enabled.
+
+New Types
+
+    None
+
+New Procedures and Functions
+
+    None
+
+New Tokens
+
+    Accepted by the <cap> parameter to IsEnabled and the <pname> parameter to
+    GetBooleanv, GetIntegerv, GetFloatv, and GetInteger64v:
+
+    PROGRAM_CACHE_ENABLED_ANGLE
+
+Additions to the OpenGL ES Specification:
+
+    Add to section 2.12.3 (Program Objects), p. 52, after paragraph 4:
+
+    Contexts with PROGRAM_CACHE_ENABLED_ANGLE set to TRUE will query the
+    internal program cache on any LinkProgram call, and re-use program binaries
+    if matching values are found. LinkProgram will succeed in this case. If the
+    binary load fails for any reason, LinkProgram will fall back to linking
+    normally.
+
+Issues
+
+    None
+
+Revision History
+
+    Rev.    Date         Author     Changes
+    ----  -------------  ---------  -------------------------------------------
+      1   June 29, 2017  jmadill    Initial version

extensions/EGL_ANGLE_program_cache_control.txt

+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
+
+    void eglGetProgramCacheAttribANGLE(
+        EGLDisplay dpy,
+        EGLenum attrib,
+        EGLint *value);
+
+    void eglQueryProgramCacheANGLE(
+        EGLDisplay dpy,
+        EGLint index,
+        void *key,
+        EGLint *keysize,
+        void *binary,
+        EGLint *size);
+
+    void eglPopulateProgramCacheANGLE(
+        EGLDisplay dpy,
+        void *key,
+        EGLint keysize,
+        void *binary,
+        EGLint binarysize);
+
+    EGLint eglTrimProgramCacheANGLE(
+        EGLDisplay dpy,
+        EGLint limit);
+
+New Tokens
+
+    Accepted as a value for 'attrib' in eglGetProgramCacheAttribANGLE:
+
+        EGL_PROGRAM_CACHE_SIZE_ANGLE       0xXXXX
+        EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE 0xXXXX
+
+    Accepted as an attribute name in the <*attrib_list> argument to
+    eglGetPlatformDisplay:
+
+        EGL_DISPLAY_PROGRAM_BINARY_CACHE_MAX_SIZE_ANGLE 0xXXXX
+
+    Accepted as an attribute name in the <*attrib_list> argument to
+    eglCreateContext:
+
+        EGL_CONTEXT_PROGRAM_BINARY_CACHE_ENABLED_ANGLE 0xXXXX
+
+Additions to the EGL 1.5 Specification
+
+    Add a new section entitled "OpenGL ES Program Cache Initialization"
+    to section 3.2:
+
+    If the attribute EGL_DISPLAY_PROGRAM_BINARY_CACHE_MAX_SIZE_ANGLE is set to a
+    positive number, a Display supporting a program binary cache will be
+    returned. OpenGL ES contexts created on this display must support the
+    ANGLE_program_cache_control extension, or equivalent core API functionality.
+    The maximum size, in bytes, of the cache will be set to the value of
+    EGL_DISPLAY_PROGRAM_BINARY_CACHE_MAX_SIZE_ANGLE. If
+    EGL_DISPLAY_PROGRAM_BINARY_CACHE_MAX_SIZE_ANGLE is zero, program caching is
+    disabled. The default value of
+    EGL_DISPLAY_PROGRAM_BINARY_CACHE_MAX_SIZE_ANGLE is implementation-dependent.
+
+    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
+
+        void eglGetProgramCacheAttribANGLE(EGLDisplay dpy, EGLenum attrib,
+            EGLint *value);
+
+    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 in 'value'. A
+    query of EGL_PROGRAM_CACHE_KEY_LENGTH_ANGLE will return the required length
+    (in bytes) of the 'key' parameter to eglQueryProgramCacheANGLE 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.
+
+    Cache contents may be queried by using
+
+        void eglQueryProgramCacheANGLE(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 'size', 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 eglPopulateProgramCacheANGLE(EGLDisplay dpy, void *key,
+            EGLint keysize, void *binary, EGLint binarysize);
+
+    If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If
+    'binarysize' is negative or greater than an internally defined maximum size,
+    EGL_BAD_PARAMETER is generated. If 'keysize' does not match the cache key
+    size of the implementation, 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 may be temporarily released by using
+
+        EGLint eglTrimProgramCacheANGLE(EGLDisplay dpy, EGLint limit);
+
+    If 'dpy' is not a valid display an EGL_BAD_DISPLAY error is generated. If
+    limit is negative then EGL_BAD_PARAMETER is generated. In any error case,
+    zero is returned, otherwise, the command will free cache resources until the
+    total cache size, in bytes, is less than or equal to limit, and return the
+    number of bytes of memory released.
+
+ 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.
+
+      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.
+
+      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.
+
+      RESOLVED: yes, we should expose cache size controls.
+
+Revision History
+
+    Rev.    Date         Author     Changes
+    ----  -------------  ---------  ----------------------------------------
+      1   June 29, 2017  jmadill    Initial version