[Mesa-dev] [PATCH v2 01/17] docs/specs: Add GL_MESA_program_binary_formats extension spec

[Jordan Justen]

Similar idea to Tim's "spec: MESA_program_binary", but simplified and
written to support both ARB_get_program_binary and
OES_get_program_binary.

This spec was merged into the OpenGL Registry in version
667c5a253781834b40a6ae9eb19d05af4542cfe1.

Ref: https://github.com/KhronosGroup/OpenGL-Registry/pull/127
Signed-off-by: Jordan Justen <jordan.l.justen at intel.com>
Cc: Ian Romanick <idr at freedesktop.org>
Cc: Timothy Arceri <tarceri at itsqueeze.com>
Reviewed-by: Ian Romanick <ian.d.romanick at intel.com>
Reviewed-by: Nicolai Hähnle <nicolai.haehnle at amd.com>
---
 docs/specs/MESA_program_binary_formats.txt | 88 ++++++++++++++++++++++++++++++
 docs/specs/enums.txt                       |  3 +
 src/mapi/glapi/registry/gl.xml             |  7 ++-
 3 files changed, 97 insertions(+), 1 deletion(-)
 create mode 100644 docs/specs/MESA_program_binary_formats.txt

diff --git a/docs/specs/MESA_program_binary_formats.txt b/docs/specs/MESA_program_binary_formats.txt
new file mode 100644
index 00000000000..937e8ef4bf3
--- /dev/null
+++ b/docs/specs/MESA_program_binary_formats.txt
@@ -0,0 +1,88 @@
+Name
+
+    MESA_program_binary_formats
+
+Name Strings
+
+    GL_MESA_program_binary_formats
+
+Contributors
+
+    Ian Romanick
+    Jordan Justen
+    Timothy Arceri
+
+Contact
+
+    Jordan Justen (jordan.l.justen 'at' intel.com)
+
+Status
+
+    Complete.
+
+Version
+
+    Last Modified Date: November 10, 2017
+    Revision: #2
+
+Number
+
+    OpenGL Extension #516
+    OpenGL ES Extension #294
+
+Dependencies
+
+    For use with the OpenGL ARB_get_program_binary extension, or the
+    OpenGL ES OES_get_program_binary extension.
+
+Overview
+
+    The get_program_binary exensions require a GLenum binaryFormat.
+    This extension documents that format for use with Mesa.
+
+New Procedures and Functions
+
+    None.
+
+New Tokens
+
+        GL_PROGRAM_BINARY_FORMAT_MESA           0x875F
+
+    For ARB_get_program_binary, GL_PROGRAM_BINARY_FORMAT_MESA may be
+    returned from GetProgramBinary calls in the <binaryFormat>
+    parameter and when retrieving the value of PROGRAM_BINARY_FORMATS.
+
+    For OES_get_program_binary, GL_PROGRAM_BINARY_FORMAT_MESA may be
+    returned from GetProgramBinaryOES calls in the <binaryFormat>
+    parameter and when retrieving the value of
+    PROGRAM_BINARY_FORMATS_OES.
+
+New State
+
+    None.
+
+Issues
+
+    (1) Should we have a different format for each driver?
+
+      RESOLVED. Since Mesa supports multiple hardware drivers, having
+      a single format may cause separate drivers to have to reject a
+      binary for another type of hardware on the same machine. This
+      could lead to an application having to invalidate and get a new
+      binary more often.
+
+      This extension, at least initially, does not to attempt to
+      define a new token for each driver since systems that run
+      multiple drivers are not the common case.
+
+      Additionally, drivers in Mesa are now gaining the ability to
+      transparently cache shader programs. Therefore, although they
+      may need to provide the application with a new binary more
+      often, they likely can retrieve the program from the cache
+      rather than performing an expensive recompile.
+
+Revision History
+
+    #02    11/10/2017    Jordan Justen       Add Issues (1) suggested by Ian
+
+    #01    10/28/2017    Jordan Justen       First draft.
diff --git a/docs/specs/enums.txt b/docs/specs/enums.txt
index eb4aa396c56..bf3ca9c1762 100644
--- a/docs/specs/enums.txt
+++ b/docs/specs/enums.txt
@@ -63,6 +63,9 @@ GL_MESAX_texture_stack:
 	GL_TEXTURE_1D_STACK_BINDING_MESAX    0x875D
 	GL_TEXTURE_2D_STACK_BINDING_MESAX    0x875E
 
+GL_MESA_program_binary_formats:
+        GL_PROGRAM_BINARY_FORMAT_MESA           0x875F
+
 GL_MESA_tile_raster_order
 	GL_TILE_RASTER_ORDER_FIXED_MESA		0x8BB8
 	GL_TILE_RASTER_ORDER_INCREASING_X_MESA	0x8BB9
diff --git a/src/mapi/glapi/registry/gl.xml b/src/mapi/glapi/registry/gl.xml
index cbabe11b398..833478aa515 100644
--- a/src/mapi/glapi/registry/gl.xml
+++ b/src/mapi/glapi/registry/gl.xml
@@ -5505,7 +5505,7 @@ typedef unsigned int GLhandleARB;
         <enum value="0x875C" name="GL_PROXY_TEXTURE_2D_STACK_MESAX"/>
         <enum value="0x875D" name="GL_TEXTURE_1D_STACK_BINDING_MESAX"/>
         <enum value="0x875E" name="GL_TEXTURE_2D_STACK_BINDING_MESAX"/>
-            <unused start="0x875F" vendor="MESA"/>
+        <enum value="0x875F" name="GL_PROGRAM_BINARY_FORMAT_MESA"/>
     </enums>
 
     <enums namespace="GL" start="0x8760" end="0x883F" vendor="AMD">
@@ -44361,6 +44361,11 @@ typedef unsigned int GLhandleARB;
                 <enum name="GL_PACK_INVERT_MESA"/>
             </require>
         </extension>
+        <extension name="GL_MESA_program_binary_formats" supported="gl|gles2">
+            <require>
+                <enum name="GL_PROGRAM_BINARY_FORMAT_MESA"/>
+            </require>
+        </extension>
         <extension name="GL_MESA_resize_buffers" supported="gl">
             <require>
                 <command name="glResizeBuffersMESA"/>
-- 
2.14.1