cogl-pipeline: Add two hook points for adding shader snippets

This adds two new public experimental functions for attaching
CoglSnippets to two hook points on a CoglPipeline:

void cogl_pipeline_add_vertex_hook (CoglPipeline *, CoglSnippet *)
void cogl_pipeline_add_fragment_hook (CoglPipeline *, CoglSnippet *)

The hooks are intended to be around the entire vertex or fragment
processing. That means the pre string in the snippet will be inserted
at the very top of the main function and the post function will be
inserted at the very end. The declarations get inserted in the global
scope.

The snippets are stored in two separate linked lists with a structure
containing an enum representing the hook point and a pointer to the
snippet. The lists are meant to be for hooks that affect the vertex
shader and fragment shader respectively. Although there are currently
only two hooks and the names match these two lists, the intention is
*not* that each new hook will be in a separate list. The separation of
the lists is just to make it easier to determine which shader needs to
be regenerated when a new snippet is added.

When a pipeline becomes the authority for either the vertex or
fragment snipper state, it simply copies the entire list from the
previous authority (although of course the shader snippet objects are
referenced instead of copied so it doesn't duplicate the source
strings).

Each string is inserted into its own block in the shader. This means
that each string has its own scope so it doesn't need to worry about
name collisions with variables in other snippets. However it does mean
that the pre and post strings can't share variables. It could be
possible to wrap both parts in one block and then wrap the actual
inner hook code in another block, however this would mean that any
further snippets within the outer snippet would be able to see those
variables. Perhaps something to consider would be to put each snippet
into its own function which calls another function between the pre and
post strings to do further processing.

The pipeline cache for generated programs was previously shared with
the fragment shader cache because the state that affects vertex
shaders was a subset of the state that affects fragment shaders. This
is no longer the case because there is a separate state mask for
vertex snippets so the program cache now has its own hash table.

Reviewed-by: Robert Bragg <robert@linux.intel.com>

1 files changed, 58 insertions, 0 deletions

diff --git a/cogl/cogl-pipeline-state.h b/cogl/cogl-pipeline-state.h
index b69966cc..d2c0ada8 100644
--- a/cogl/cogl-pipeline-state.h
+++ b/cogl/cogl-pipeline-state.h
@@ -937,6 +937,64 @@ cogl_pipeline_set_uniform_matrix (CoglPipeline *pipeline,
                                   gboolean transpose,
                                   const float *value);
 
+/**
+ * cogl_pipeline_add_vertex_hook:
+ * @pipeline: A #CoglPipeline
+ * @snippet: The #CoglSnippet to add to the vertex processing hook
+ *
+ * Adds a shader snippet that will hook on to the vertex processing
+ * stage of @pipeline. This gives a chance for the application to
+ * modify the vertex attributes generated by the shader. Typically the
+ * snippet will modify cogl_color_out or cogl_position_out builtins.
+ *
+ * The ‘declarations’ string in @snippet will be inserted in the
+ * global scope of the shader. Use this to declare any uniforms,
+ * attributes or functions that the snippet requires.
+ *
+ * The ‘pre’ string in @snippet will be inserted at the top of the
+ * main() function before any vertex processing is done.
+ *
+ * The ‘post’ string in @snippet will be inserted after all of the
+ * standard vertex processing is done. This can be used to modify the
+ * outputs.
+ *
+ * Since: 1.10
+ * Stability: Unstable
+ */
+void
+cogl_pipeline_add_vertex_hook (CoglPipeline *pipeline,
+                               CoglSnippet *snippet);
+
+/**
+ * cogl_pipeline_add_fragment_hook:
+ * @pipeline: A #CoglPipeline
+ * @snippet: The #CoglSnippet to add to the fragment processing hook
+ *
+ * Adds a shader snippet that will hook on to the fragment processing
+ * stage of @pipeline. This gives a chance for the application to
+ * modify the fragment color generated by the shader. Typically the
+ * snippet will modify cogl_color_out.
+ *
+ * The ‘declarations’ string in @snippet will be inserted in the
+ * global scope of the shader. Use this to declare any uniforms,
+ * attributes or functions that the snippet requires.
+ *
+ * The ‘pre’ string in @snippet will be inserted at the top of the
+ * main() function before any fragment processing is done.
+ *
+ * The ‘post’ string in @snippet will be inserted after all of the
+ * standard fragment processing is done. At this point the generated
+ * value for the rest of the pipeline state will already be in
+ * cogl_color_out so the application can modify the result by altering
+ * this variable.
+ *
+ * Since: 1.10
+ * Stability: Unstable
+ */
+void
+cogl_pipeline_add_fragment_hook (CoglPipeline *pipeline,
+                                 CoglSnippet *snippet);
+
 #endif /* COGL_ENABLE_EXPERIMENTAL_API */
 
 G_END_DECLS