Merge changes I002177a6,Ibaff52fe

* changes:
  Add the EGL_ANDROID_recordable spec.
  Add the spec for EGL_ANDROID_blob_cache.

3 files changed, 333 insertions, 0 deletions

diff --git a/opengl/specs/EGL_ANDROID_blob_cache.txt b/opengl/specs/EGL_ANDROID_blob_cache.txt
new file mode 100644
index 0000000..55dc900
--- /dev/null
+++ b/opengl/specs/EGL_ANDROID_blob_cache.txt
@@ -0,0 +1,208 @@
+Name
+
+    ANDROID_blob_cache
+
+Name Strings
+
+    EGL_ANDROID_blob_cache
+
+Contributors
+
+    Jamie Gennis
+
+Contact
+
+    Jamie Gennis, Google Inc. (jgennis 'at' google.com)
+
+Status
+
+    Draft.
+
+Version
+
+    Version 1, April 22, 2011
+
+Number
+
+    EGL Extension #XXX
+
+Dependencies
+
+    Requires EGL 1.0
+
+    This extension is written against the wording of the EGL 1.4 Specification
+
+Overview
+
+    Shader compilation and optimization has been a troublesome aspect of OpenGL
+    programming for a long time.  It can consume seconds of CPU cycles during
+    application start-up.  Additionally, state-based re-compiles done
+    internally by the drivers add an unpredictable element to application
+    performance tuning, often leading to occasional pauses in otherwise smooth
+    animations.
+
+    This extension provides a mechanism through which client API
+    implementations may cache shader binaries after they are compiled.  It may
+    then retrieve those cached shaders during subsequent executions of the same
+    program.  The management of the cache is handled by the application (or
+    middleware), allowing it to be tuned to a particular platform or
+    environment.
+
+    While the focus of this extension is on providing a persistent cache for
+    shader binaries, it may also be useful for caching other data.  This is
+    perfectly acceptable, but the guarantees provided (or lack thereof) were
+    designed around the shader use case.
+
+    Note that although this extension is written as if the application
+    implements the caching functionality, on the Android OS it is implemented
+    as part of the Android EGL module.  This extension is not exposed to
+    applications on Android, but will be used automatically in every
+    application that uses EGL if it is supported by the underlying
+    device-specific EGL implementation.
+
+New Types
+
+    /*
+     * EGLsizei is a signed integer type for representing the size of a memory
+     * buffer.
+     */
+    #include <khrplatform.h>
+    typedef khronos_ssize_t EGLsizei;
+
+    /*
+     * EGLSetBlobFunc is a pointer to an application-provided function that a
+     * client API implementation may use to insert a key/value pair into the
+     * cache.
+     */
+    typedef void (*EGLSetBlobFunc) (const void* key, EGLsizei keySize,
+        const void* value, EGLsizei valueSize)
+
+    /*
+     * EGLGetBlobFunc is a pointer to an application-provided function that a
+     * client API implementation may use to retrieve a cached value from the
+     * cache.
+     */
+    typedef EGLsizei (*EGLGetBlobFunc) (const void* key, EGLsizei keySize,
+        void* value, EGLsizei valueSize)
+
+New Procedures and Functions
+
+    void eglSetBlobCacheFuncs(EGLDisplay dpy,
+                              EGLSetBlobFunc set,
+                              EGLGetBlobFunc get);
+
+New Tokens
+
+    None.
+
+Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
+
+    Add a new subsection after Section 3.8, page 50
+    (Synchronization Primitives)
+
+    "3.9 Persistent Caching
+
+    In order to facilitate persistent caching of internal client API state that
+    is slow to compute or collect, the application may specify callback
+    function pointers through which the client APIs can request data be cached
+    and retrieved.  The command
+
+        void eglSetBlobCacheFuncs(EGLDisplay dpy,
+            EGLSetBlobFunc set, EGLGetBlobFunc get);
+
+    sets the callback function pointers that client APIs associated with
+    display <dpy> can use to interact with caching functionality provided by
+    the application.  <set> points to a function that inserts a new value into
+    the cache and associates it with the given key.  <get> points to a function
+    that retrieves from the cache the value associated with a given key.  The
+    semantics of these callback functions are described in Section 3.9.1 (Cache
+    Operations).
+
+    Cache functions may only be specified once during the lifetime of an
+    EGLDisplay.  The <set> and <get> functions may be called at any time and
+    from any thread from the time at which eglSetBlobCacheFuncs is called until
+    the time that the last resource associated with <dpy> is deleted and <dpy>
+    itself is terminated.  Concurrent calls to these functions from different
+    threads is also allowed.
+
+    If eglSetBlobCacheFuncs generates an error then all client APIs must behave
+    as though eglSetBlobCacheFuncs was not called for the display <dpy>.  If
+    <set> or <get> is NULL then an EGL_BAD_PARAMETER error is generated.  If a
+    successful eglSetBlobCacheFuncs call was already made for <dpy> and the
+    display has not since been terminated then an EGL_BAD_PARAMETER error is
+    generated.
+
+    3.9.1 Cache Operations
+
+    To insert a new binary value into the cache and associate it with a given
+    key, a client API implementation can call the application-provided callback
+    function
+
+        void (*set) (const void* key, EGLsizei keySize, const void* value,
+            EGLsizei valueSize)
+
+    <key> and <value> are pointers to the beginning of the key and value,
+    respectively, that are to be inserted.  <keySize> and <valueSize> specify
+    the size in bytes of the data pointed to by <key> and <value>,
+    respectively.
+
+    No guarantees are made as to whether a given key/value pair is present in
+    the cache after the set call.  If a different value has been associated
+    with the given key in the past then it is undefined which value, if any, is
+    associated with the key after the set call.  Note that while there are no
+    guarantees, the cache implementation should attempt to cache the most
+    recently set value for a given key.
+
+    To retrieve the binary value associated with a given key from the cache, a
+    client API implementation can call the application-provided callback
+    function
+
+        EGLsizei (*get) (const void* key, EGLsizei keySize, void* value,
+            EGLsizei valueSize)
+
+    <key> is a pointer to the beginning of the key.  <keySize> specifies the
+    size in bytes of the binary key pointed to by <key>.  If the cache contains
+    a value associated with the given key then the size of that binary value in
+    bytes is returned.  Otherwise 0 is returned.
+
+    If the cache contains a value for the given key and its size in bytes is
+    less than or equal to <valueSize> then the value is written to the memory
+    pointed to by <value>.  Otherwise nothing is written to the memory pointed
+    to by <value>.
+
+Issues
+
+    1. How should errors be handled in the callback functions?
+
+    RESOLVED: No guarantees are made about the presence of values in the cache,
+    so there should not be a need to return error information to the client API
+    implementation.  The cache implementation can simply drop a value if it
+    encounters an error during the 'set' callback.  Similarly, it can simply
+    return 0 if it encouters an error in a 'get' callback.
+
+    2. When a client API driver gets updated, that may need to invalidate
+    previously cached entries.  How can the driver handle this situation?
+
+    RESPONSE: There are a number of ways the driver can handle this situation.
+    The recommended way is to include the driver version in all cache keys.
+    That way each driver version will use a set of cache keys that are unique
+    to that version, and conflicts should never occur.  Updating the driver
+    could then leave a number of values in the cache that will never be
+    requested again.  If needed, the cache implementation can handle those
+    values in some way, but the driver does not need to take any special
+    action.
+
+    3. How much data can be stored in the cache?
+
+    RESPONSE: This is entirely dependent upon the cache implementation.
+    Presumably it will be tuned to store enough data to be useful, but not
+    enough to become problematic. :)
+
+Revision History
+
+#2 (Jamie Gennis, April 25, 2011)
+    - Swapped the order of the size and pointer arguments to the get and set
+      functions.
+
+#1 (Jamie Gennis, April 22, 2011)
+    - Initial draft.
diff --git a/opengl/specs/EGL_ANDROID_recordable.txt b/opengl/specs/EGL_ANDROID_recordable.txt
new file mode 100644
index 0000000..cf44465
--- /dev/null
+++ b/opengl/specs/EGL_ANDROID_recordable.txt
@@ -0,0 +1,113 @@
+Name
+
+    ANDROID_recordable
+
+Name Strings
+
+    EGL_ANDROID_recordable
+
+Contributors
+
+    Jamie Gennis
+
+Contact
+
+    Jamie Gennis, Google Inc. (jgennis 'at' google.com)
+
+Status
+
+    Draft.
+
+Version
+
+    Version 1, July 8, 2011
+
+Number
+
+    EGL Extension #XXX
+
+Dependencies
+
+    Requires EGL 1.0
+
+    This extension is written against the wording of the EGL 1.4 Specification
+
+Overview
+
+    Android supports a number of different ANativeWindow implementations that
+    can be used to create an EGLSurface.  One implementation, which records the
+    rendered image as a video each time eglSwapBuffers gets called, may have
+    some device-specific restrictions.  Because of this, some EGLConfigs may be
+    incompatible with these ANativeWindows.  This extension introduces a new
+    boolean EGLConfig attribute that indicates whether the EGLConfig supports
+    rendering to an ANativeWindow that records images to a video.
+
+New Types
+
+    None.
+
+New Procedures and Functions
+
+    None.
+
+New Tokens
+
+    Accepted by the <attribute> parameter of eglGetConfigAttrib and
+    the <attrib_list> parameter of eglChooseConfig:
+
+        EGL_RECORDABLE_ANDROID                      0xXXXX
+
+Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
+
+    Section 3.4, Configuration Management, add a row to Table 3.1.
+    
+              Attribute             Type                 Notes
+        ----------------------     -------     --------------------------
+        EGL_RECORDABLE_ANDROID     boolean     whether video recording is
+                                               supported
+
+    Section 3.4, Configuration Management, add a row to Table 3.4.
+
+              Attribute            Default     Selection  Sort   Sort
+                                               Criteria   Order  Priority
+        ----------------------  -------------  ---------  -----  --------
+        EGL_RECORDABLE_ANDROID  EGL_DONT_CARE    Exact    None
+
+    Section 3.4, Configuration Management, add a paragraph at the end of the
+    subsection titled Other EGLConfig Attribute Descriptions.
+
+        EGL_RECORDABLE_ANDROID is a boolean indicating whether the config may
+        be used to create an EGLSurface from an ANativeWindow that is a video
+        recorder as indicated by the NATIVE_WINDOW_IS_VIDEO_RECORDER query on
+        the ANativeWindow.
+
+    Section 3.4.1, Querying Configurations, change the last paragraph as follow
+
+        EGLConfigs are not sorted with respect to the parameters
+        EGL_BIND_TO_TEXTURE_RGB, EGL_BIND_TO_TEXTURE_RGBA, EGL_CONFORMANT,
+        EGL_LEVEL, EGL_NATIVE_RENDERABLE, EGL_MAX_SWAP_INTERVAL,
+        EGL_MIN_SWAP_INTERVAL, EGL_RENDERABLE_TYPE, EGL_SURFACE_TYPE,
+        EGL_TRANSPARENT_TYPE, EGL_TRANSPARENT_RED_VALUE,
+        EGL_TRANSPARENT_GREEN_VALUE, EGL_TRANSPARENT_BLUE_VALUE, and
+        EGL_RECORDABLE_ANDROID.
+
+Issues
+
+    1. Should this functionality be exposed as a new attribute or as a bit in
+    the EGL_SURFACE_TYPE bitfield?
+
+    RESOLVED: It should be a new attribute.  It does not make sense to use up a
+    bit in the limit-size bitfield for a platform-specific extension.
+
+    2. How should the new attribute affect the sorting of EGLConfigs?
+
+    RESOLVED: It should not affect sorting.  Some implementations may not have
+    any drawback associated with using a recordable EGLConfig.  Such
+    implementations should not have to double-up some of their configs to  one sort earlier than .
+    Implementations that do have drawbacks can use the existing caveat
+    mechanism to report this drawback to the client.
+
+Revision History
+
+#1 (Jamie Gennis, July 8, 2011)
+    - Initial draft.
diff --git a/opengl/specs/README b/opengl/specs/README
new file mode 100644
index 0000000..2fa2587
--- /dev/null
+++ b/opengl/specs/README
@@ -0,0 +1,12 @@
+This directory contains OpenGL ES and EGL extension specifications that have
+been or are being defined for Android.  
+
+The table below tracks usage of EGL enumerant values that have been reserved
+for use by Android extensions.
+
+     Value                       Extension
+----------------     ----------------------------------
+0x3140               EGL_ANDROID_image_native_buffer
+0x3141               (unused)
+0x3142               EGL_ANDROID_recordable
+0x3143 - 0x314F      (unused)