mutter/cogl/cogl-snippet.h

/*
 * Cogl
 *
 * A Low Level GPU Graphics and Utilities API
 *
 * Copyright (C) 2011, 2013 Intel Corporation.
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use, copy,
 * modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 *
 *
 * Authors:
 *   Neil Roberts <neil@linux.intel.com>
 */

#if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION)
#error "Only <cogl/cogl.h> can be included directly."
#endif

#ifndef __COGL_SNIPPET_H__
#define __COGL_SNIPPET_H__

COGL_BEGIN_DECLS

/**
 * SECTION:cogl-snippet
 * @short_description: Functions for creating and manipulating shader snippets
 *
 * #CoglSnippet<!-- -->s are used to modify or replace parts of a
 * #CoglPipeline using GLSL. GLSL is a programming language supported
 * by OpenGL on programmable hardware to provide a more flexible
 * description of what should be rendered. A description of GLSL
 * itself is outside the scope of this documentation but any good
 * OpenGL book should help to describe it.
 *
 * Unlike in OpenGL, when using GLSL with Cogl it is possible to write
 * short snippets to replace small sections of the pipeline instead of
 * having to replace the whole of either the vertex or fragment
 * pipelines. Of course it is also possible to replace the whole of
 * the pipeline if needed.
 *
 * Each snippet is a standalone chunk of code which would attach to
 * the pipeline at a particular point. The code is split into four
 * separate strings (all of which are optional):
 *
 * <glosslist>
 *  <glossentry>
 *   <glossterm>declarations</glossterm>
 *   <glossdef><para>
 * The code in this string will be inserted outside of any function in
 * the global scope of the shader. This can be used to declare
 * uniforms, attributes, varyings and functions to be used by the
 * snippet.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>pre</glossterm>
 *   <glossdef><para>
 * The code in this string will be inserted before the hook point.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>post</glossterm>
 *   <glossdef><para>
 * The code in this string will be inserted after the hook point. This
 * can be used to modify the results of the builtin generated code for
 * that hook point.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>replace</glossterm>
 *   <glossdef><para>
 * If present the code in this string will replace the generated code
 * for the hook point.
 *   </para></glossdef>
 *  </glossentry>
 * </glosslist>
 *
 * All of the strings apart from the declarations string of a pipeline
 * are generated in a single function so they can share variables
 * declared from one string in another. The scope of the code is
 * limited to each snippet so local variables declared in the snippet
 * will not collide with variables declared in another
 * snippet. However, code in the 'declarations' string is global to
 * the shader so it is the application's responsibility to ensure that
 * variables declared here will not collide with those from other
 * snippets.
 *
 * The snippets can be added to a pipeline with
 * cogl_pipeline_add_snippet() or
 * cogl_pipeline_add_layer_snippet(). Which function to use depends on
 * which hook the snippet is targetting. The snippets are all
 * generated in the order they are added to the pipeline. That is, the
 * post strings are executed in the order they are added to the
 * pipeline and the pre strings are executed in reverse order. If any
 * replace strings are given for a snippet then any other snippets
 * with the same hook added before that snippet will be ignored. The
 * different hooks are documented under #CoglSnippetHook.
 *
 * For portability with GLES2, it is recommended not to use the GLSL
 * builtin names such as gl_FragColor. Instead there are replacement
 * names under the cogl_* namespace which can be used instead. These
 * are:
 *
 * <glosslist>
 *  <glossentry>
 *   <glossterm>uniform mat4
 *         <emphasis>cogl_modelview_matrix</emphasis></glossterm>
 *   <glossdef><para>
 *    The current modelview matrix. This is equivalent to
 *    #gl_ModelViewMatrix.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>uniform mat4
 *         <emphasis>cogl_projection_matrix</emphasis></glossterm>
 *   <glossdef><para>
 *    The current projection matrix. This is equivalent to
 *    #gl_ProjectionMatrix.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>uniform mat4
 *         <emphasis>cogl_modelview_projection_matrix</emphasis></glossterm>
 *   <glossdef><para>
 *    The combined modelview and projection matrix. A vertex shader
 *    would typically use this to transform the incoming vertex
 *    position. The separate modelview and projection matrices are
 *    usually only needed for lighting calculations. This is
 *    equivalent to #gl_ModelViewProjectionMatrix.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>uniform mat4
 *         <emphasis>cogl_texture_matrix</emphasis>[]</glossterm>
 *   <glossdef><para>
 *    An array of matrices for transforming the texture
 *    coordinates. This is equivalent to #gl_TextureMatrix.
 *   </para></glossdef>
 *  </glossentry>
 * </glosslist>
 *
 * In a vertex shader, the following are also available:
 *
 * <glosslist>
 *  <glossentry>
 *   <glossterm>attribute vec4
 *         <emphasis>cogl_position_in</emphasis></glossterm>
 *   <glossdef><para>
 *    The incoming vertex position. This is equivalent to #gl_Vertex.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>attribute vec4
 *         <emphasis>cogl_color_in</emphasis></glossterm>
 *   <glossdef><para>
 *    The incoming vertex color. This is equivalent to #gl_Color.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>attribute vec4
 *         <emphasis>cogl_tex_coord_in</emphasis></glossterm>
 *   <glossdef><para>
 *    The texture coordinate for layer 0. This is an alternative name
 *    for #cogl_tex_coord0_in.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>attribute vec4
 *         <emphasis>cogl_tex_coord0_in</emphasis></glossterm>
 *   <glossdef><para>
 *    The texture coordinate for the layer 0. This is equivalent to
 *    #gl_MultiTexCoord0. There will also be #cogl_tex_coord1_in and
 *    so on if more layers are added to the pipeline.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>attribute vec3
 *         <emphasis>cogl_normal_in</emphasis></glossterm>
 *   <glossdef><para>
 *    The normal of the vertex. This is equivalent to #gl_Normal.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>vec4
 *         <emphasis>cogl_position_out</emphasis></glossterm>
 *   <glossdef><para>
 *    The calculated position of the vertex. This must be written to
 *    in all vertex shaders. This is equivalent to #gl_Position.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>float
 *         <emphasis>cogl_point_size_in</emphasis></glossterm>
 *   <glossdef><para>
 *    The incoming point size from the cogl_point_size_in attribute.
 *    This is only available if
 *    cogl_pipeline_set_per_vertex_point_size() is set on the
 *    pipeline.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>float
 *         <emphasis>cogl_point_size_out</emphasis></glossterm>
 *   <glossdef><para>
 *    The calculated size of a point. This is equivalent to #gl_PointSize.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>varying vec4
 *         <emphasis>cogl_color_out</emphasis></glossterm>
 *   <glossdef><para>
 *    The calculated color of a vertex. This is equivalent to #gl_FrontColor.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>varying vec4
 *         <emphasis>cogl_tex_coord0_out</emphasis></glossterm>
 *   <glossdef><para>
 *    The calculated texture coordinate for layer 0 of the pipeline.
 *    This is equivalent to #gl_TexCoord[0]. There will also be
 *    #cogl_tex_coord1_out and so on if more layers are added to the
 *    pipeline. In the fragment shader, this varying is called
 *    #cogl_tex_coord0_in.
 *   </para></glossdef>
 *  </glossentry>
 * </glosslist>
 *
 * In a fragment shader, the following are also available:
 *
 * <glosslist>
 *  <glossentry>
 *   <glossterm>varying vec4 <emphasis>cogl_color_in</emphasis></glossterm>
 *   <glossdef><para>
 *    The calculated color of a vertex. This is equivalent to #gl_FrontColor.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>varying vec4
 *              <emphasis>cogl_tex_coord0_in</emphasis></glossterm>
 *   <glossdef><para>
 *    The texture coordinate for layer 0. This is equivalent to
 *    #gl_TexCoord[0]. There will also be #cogl_tex_coord1_in and so
 *    on if more layers are added to the pipeline.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>vec4 <emphasis>cogl_color_out</emphasis></glossterm>
 *   <glossdef><para>
 *    The final calculated color of the fragment. All fragment shaders
 *    must write to this variable. This is equivalent to
 *    #gl_FrontColor.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>float <emphasis>cogl_depth_out</emphasis></glossterm>
 *   <glossdef><para>
 *    An optional output variable specifying the depth value to use
 *    for this fragment. This is equivalent to #gl_FragDepth.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>bool <emphasis>cogl_front_facing</emphasis></glossterm>
 *   <glossdef><para>
 *    A readonly variable that will be true if the current primitive
 *    is front facing. This can be used to implement two-sided
 *    coloring algorithms. This is equivalent to #gl_FrontFacing.
 *   </para></glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>vec2 <emphasis>cogl_point_coord</emphasis></glossterm>
 *   <glossdef><para>
 *    When rendering points, this will contain a vec2 which represents
 *    the position within the point of the current fragment.
 *    vec2(0.0,0.0) will be the topleft of the point and vec2(1.0,1.0)
 *    will be the bottom right. Note that there is currently a bug in
 *    Cogl where when rendering to an offscreen buffer these
 *    coordinates will be upside-down. The value is undefined when not
 *    rendering points. This builtin can only be used if the
 *    %COGL_FEATURE_ID_POINT_SPRITE feature is available.
 *   </para></glossdef>
 *  </glossentry>
 * </glosslist>
 *
 * Here is an example of using a snippet to add a desaturate effect to the
 * generated color on a pipeline.
 *
 * <programlisting>
 *   CoglPipeline *pipeline = cogl_pipeline_new ();
 *
 *   /<!-- -->* Set up the pipeline here, ie by adding a texture or other
 *      layers *<!-- -->/
 *
 *   /<!-- -->* Create the snippet. The first string is the declarations which
 *      we will use to add a uniform. The second is the 'post' string which
 *      will contain the code to perform the desaturation. *<!-- -->/
 *   CoglSnippet *snippet =
 *     cogl_snippet_new (COGL_SNIPPET_HOOK_FRAGMENT,
 *                       "uniform float factor;",
 *                       "float gray = dot (vec3 (0.299, 0.587, 0.114), "
 *                       "                  cogl_color_out.rgb);"
 *                       "cogl_color_out.rgb = mix (vec3 (gray),"
 *                       "                          cogl_color_out.rgb,"
 *                       "                          factor);");
 *
 *   /<!-- -->* Add it to the pipeline *<!-- -->/
 *   cogl_pipeline_add_snippet (pipeline, snippet);
 *   /<!-- -->* The pipeline keeps a reference to the snippet
 *      so we don't need to *<!-- -->/
 *   cogl_object_unref (snippet);
 *
 *   /<!-- -->* Update the custom uniform on the pipeline *<!-- -->/
 *   int location = cogl_pipeline_get_uniform_location (pipeline, "factor");
 *   cogl_pipeline_set_uniform_1f (pipeline, location, 0.5f);
 *
 *   /<!-- -->* Now we can render with the snippet as usual *<!-- -->/
 *   cogl_push_source (pipeline);
 *   cogl_rectangle (0, 0, 10, 10);
 *   cogl_pop_source ();
 * </programlisting>
 */
typedef struct _CoglSnippet CoglSnippet;

#define COGL_SNIPPET(OBJECT) ((CoglSnippet *)OBJECT)

/* Enumeration of all the hook points that a snippet can be attached
   to within a pipeline. */
/**
 * CoglSnippetHook:
 * @COGL_SNIPPET_HOOK_VERTEX_GLOBALS: A hook for declaring global data
 *   that can be shared with all other snippets that are on a vertex
 *   hook.
 * @COGL_SNIPPET_HOOK_FRAGMENT_GLOBALS: A hook for declaring global
 *   data wthat can be shared with all other snippets that are on a
 *   fragment hook.
 * @COGL_SNIPPET_HOOK_VERTEX: A hook for the entire vertex processing
 *   stage of the pipeline.
 * @COGL_SNIPPET_HOOK_VERTEX_TRANSFORM: A hook for the vertex transformation.
 * @COGL_SNIPPET_HOOK_POINT_SIZE: A hook for manipulating the point
 *   size of a vertex. This is only used if
 *   cogl_pipeline_set_per_vertex_point_size() is enabled on the
 *   pipeline.
 * @COGL_SNIPPET_HOOK_FRAGMENT: A hook for the entire fragment
 *   processing stage of the pipeline.
 * @COGL_SNIPPET_HOOK_TEXTURE_COORD_TRANSFORM: A hook for applying the
 *   layer matrix to a texture coordinate for a layer.
 * @COGL_SNIPPET_HOOK_LAYER_FRAGMENT: A hook for the fragment
 *   processing of a particular layer.
 * @COGL_SNIPPET_HOOK_TEXTURE_LOOKUP: A hook for the texture lookup
 *   stage of a given layer in a pipeline.
 *
 * #CoglSnippetHook is used to specify a location within a
 * #CoglPipeline where the code of the snippet should be used when it
 * is attached to a pipeline.
 *
 * <glosslist>
 *  <glossentry>
 *   <glossterm>%COGL_SNIPPET_HOOK_VERTEX_GLOBALS</glossterm>
 *   <glossdef>
 * <para>
 * Adds a shader snippet at the beginning of the global section of the
 * shader for the vertex processing. Any declarations here can be
 * shared with all other snippets that are attached to a vertex hook.
 * Only the ‘declarations’ string is used and the other strings are
 * ignored.
 * </para>
 *   </glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>%COGL_SNIPPET_HOOK_FRAGMENT_GLOBALS</glossterm>
 *   <glossdef>
 * <para>
 * Adds a shader snippet at the beginning of the global section of the
 * shader for the fragment processing. Any declarations here can be
 * shared with all other snippets that are attached to a fragment
 * hook. Only the ‘declarations’ string is used and the other strings
 * are ignored.
 * </para>
 *   </glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>%COGL_SNIPPET_HOOK_VERTEX</glossterm>
 *   <glossdef>
 * <para>
 * Adds a shader snippet that will hook on to the vertex processing
 * stage of the 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.
 * </para>
 * <para>
 * 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.
 * </para>
 * <para>
 * The ‘pre’ string in @snippet will be inserted at the top of the
 * main() function before any vertex processing is done.
 * </para>
 * <para>
 * The ‘replace’ string in @snippet will be used instead of the
 * generated vertex processing if it is present. This can be used if
 * the application wants to provide a complete vertex shader and
 * doesn't need the generated output from Cogl.
 * </para>
 * <para>
 * 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.
 * </para>
 *   </glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>%COGL_SNIPPET_HOOK_VERTEX_TRANSFORM</glossterm>
 *   <glossdef>
 * <para>
 * Adds a shader snippet that will hook on to the vertex transform stage.
 * Typically the snippet will use the cogl_modelview_matrix,
 * cogl_projection_matrix and cogl_modelview_projection_matrix matrices and the
 * cogl_position_in attribute. The hook must write to cogl_position_out.
 * The default processing for this hook will multiply cogl_position_in by
 * the combined modelview-projection matrix and store it on cogl_position_out.
 * </para>
 * <para>
 * 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.
 * </para>
 * <para>
 * The ‘pre’ string in @snippet will be inserted at the top of the
 * main() function before the vertex transform is done.
 * </para>
 * <para>
 * The ‘replace’ string in @snippet will be used instead of the
 * generated vertex transform if it is present.
 * </para>
 * <para>
 * The ‘post’ string in @snippet will be inserted after all of the
 * standard vertex transformation is done. This can be used to modify the
 * cogl_position_out in addition to the default processing.
 * </para>
 *   </glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>%COGL_SNIPPET_HOOK_POINT_SIZE</glossterm>
 *   <glossdef>
 * <para>
 * Adds a shader snippet that will hook on to the point size
 * calculation step within the vertex shader stage. The snippet should
 * write to the builtin cogl_point_size_out with the new point size.
 * The snippet can either read cogl_point_size_in directly and write a
 * new value or first read an existing value in cogl_point_size_out
 * that would be set by a previous snippet. Note that this hook is
 * only used if cogl_pipeline_set_per_vertex_point_size() is enabled
 * on the pipeline.
 * </para>
 * <para>
 * 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.
 * </para>
 * <para>
 * The ‘pre’ string in @snippet will be inserted just before
 * calculating the point size.
 * </para>
 * <para>
 * The ‘replace’ string in @snippet will be used instead of the
 * generated point size calculation if it is present.
 * </para>
 * <para>
 * The ‘post’ string in @snippet will be inserted after the
 * standard point size calculation is done. This can be used to modify
 * cogl_point_size_out in addition to the default processing.
 * </para>
 *   </glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>%COGL_SNIPPET_HOOK_FRAGMENT</glossterm>
 *   <glossdef>
 * <para>
 * Adds a shader snippet that will hook on to the fragment processing
 * stage of the 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.
 * </para>
 * <para>
 * 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.
 * </para>
 * <para>
 * The ‘pre’ string in @snippet will be inserted at the top of the
 * main() function before any fragment processing is done.
 * </para>
 * <para>
 * The ‘replace’ string in @snippet will be used instead of the
 * generated fragment processing if it is present. This can be used if
 * the application wants to provide a complete fragment shader and
 * doesn't need the generated output from Cogl.
 * </para>
 * <para>
 * 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.
 * </para>
 *   </glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>%COGL_SNIPPET_HOOK_TEXTURE_COORD_TRANSFORM</glossterm>
 *    <glossdef>
 * <para>
 * Adds a shader snippet that will hook on to the texture coordinate
 * transformation of a particular layer. This can be used to replace
 * the processing for a layer or to modify the results.
 * </para>
 * <para>
 * Within the snippet code for this hook there are two extra
 * variables. The first is a mat4 called cogl_matrix which represents
 * the user matrix for this layer. The second is called cogl_tex_coord
 * and represents the incoming and outgoing texture coordinate. On
 * entry to the hook, cogl_tex_coord contains the value of the
 * corresponding texture coordinate attribute for this layer. The hook
 * is expected to modify this variable. The output will be passed as a
 * varying to the fragment processing stage. The default code will
 * just multiply cogl_matrix by cogl_tex_coord and store the result in
 * cogl_tex_coord.
 * </para>
 * <para>
 * 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.
 * </para>
 * <para>
 * The ‘pre’ string in @snippet will be inserted just before the
 * fragment processing for this layer. At this point cogl_tex_coord
 * still contains the value of the texture coordinate attribute.
 * </para>
 * <para>
 * If a ‘replace’ string is given then this will be used instead of
 * the default fragment processing for this layer. The snippet can
 * modify cogl_tex_coord or leave it as is to apply no transformation.
 * </para>
 * <para>
 * The ‘post’ string in @snippet will be inserted just after the
 * transformation. At this point cogl_tex_coord will contain the
 * results of the transformation but it can be further modified by the
 * snippet.
 * </para>
 *   </glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>%COGL_SNIPPET_HOOK_LAYER_FRAGMENT</glossterm>
 *    <glossdef>
 * <para>
 * Adds a shader snippet that will hook on to the fragment processing
 * of a particular layer. This can be used to replace the processing
 * for a layer or to modify the results.
 * </para>
 * <para>
 * Within the snippet code for this hook there is an extra vec4
 * variable called ‘cogl_layer’. This contains the resulting color
 * that will be used for the layer. This can be modified in the ‘post’
 * section or it the default processing can be replaced entirely using
 * the ‘replace’ section.
 * </para>
 * <para>
 * 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.
 * </para>
 * <para>
 * The ‘pre’ string in @snippet will be inserted just before the
 * fragment processing for this layer.
 * </para>
 * <para>
 * If a ‘replace’ string is given then this will be used instead of
 * the default fragment processing for this layer. The snippet must write to
 * the ‘cogl_layer’ variable in that case.
 * </para>
 * <para>
 * The ‘post’ string in @snippet will be inserted just after the
 * fragment processing for the layer. The results can be modified by changing
 * the value of the ‘cogl_layer’ variable.
 * </para>
 *   </glossdef>
 *  </glossentry>
 *  <glossentry>
 *   <glossterm>%COGL_SNIPPET_HOOK_TEXTURE_LOOKUP</glossterm>
 *   <glossdef>
 * <para>
 * Adds a shader snippet that will hook on to the texture lookup part
 * of a given layer. This gives a chance for the application to modify
 * the coordinates that will be used for the texture lookup or to
 * alter the returned texel.
 * </para>
 * <para>
 * Within the snippet code for this hook there are three extra
 * variables available. ‘cogl_sampler’ is a sampler object
 * representing the sampler for the layer where the snippet is
 * attached. ‘cogl_tex_coord’ is a vec4 which contains the texture
 * coordinates that will be used for the texture lookup. This can be
 * modified. ‘cogl_texel’ will contain the result of the texture
 * lookup. This can also be modified.
 * </para>
 * <para>
 * 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.
 * </para>
 * <para>
 * The ‘pre’ string in @snippet will be inserted at the top of the
 * main() function before any fragment processing is done. This is a
 * good place to modify the cogl_tex_coord variable.
 * </para>
 * <para>
 * If a ‘replace’ string is given then this will be used instead of a
 * the default texture lookup. The snippet would typically use its own
 * sampler in this case.
 * </para>
 * <para>
 * The ‘post’ string in @snippet will be inserted after texture lookup
 * has been preformed. Here the snippet can modify the cogl_texel
 * variable to alter the returned texel.
 * </para>
 *   </glossdef>
 *  </glossentry>
 * </glosslist>
 *
 * Since: 1.10
 * Stability: Unstable
 */
typedef enum {
  /* Per pipeline vertex hooks */
  COGL_SNIPPET_HOOK_VERTEX = 0,
  COGL_SNIPPET_HOOK_VERTEX_TRANSFORM,
  COGL_SNIPPET_HOOK_VERTEX_GLOBALS,
  COGL_SNIPPET_HOOK_POINT_SIZE,

  /* Per pipeline fragment hooks */
  COGL_SNIPPET_HOOK_FRAGMENT = 2048,
  COGL_SNIPPET_HOOK_FRAGMENT_GLOBALS,

  /* Per layer vertex hooks */
  COGL_SNIPPET_HOOK_TEXTURE_COORD_TRANSFORM = 4096,

  /* Per layer fragment hooks */
  COGL_SNIPPET_HOOK_LAYER_FRAGMENT = 6144,
  COGL_SNIPPET_HOOK_TEXTURE_LOOKUP
} CoglSnippetHook;

/**
 * cogl_snippet_new:
 * @hook: The point in the pipeline that this snippet will wrap around
 *   or replace.
 * @declarations: The source code for the declarations for this
 *   snippet or %NULL. See cogl_snippet_set_declarations().
 * @post: The source code to run after the hook point where this
 *   shader snippet is attached or %NULL. See cogl_snippet_set_post().
 *
 * Allocates and initializes a new snippet with the given source strings.
 *
 * Return value: a pointer to a new #CoglSnippet
 *
 * Since: 1.10
 * Stability: Unstable
 */
CoglSnippet *
cogl_snippet_new (CoglSnippetHook hook,
                  const char *declarations,
                  const char *post);

/**
 * cogl_snippet_get_hook:
 * @snippet: A #CoglSnippet
 *
 * Return value: the hook that was set when cogl_snippet_new() was
 *   called.
 * Since: 1.10
 * Stability: Unstable
 */
CoglSnippetHook
cogl_snippet_get_hook (CoglSnippet *snippet);

/**
 * cogl_is_snippet:
 * @object: A #CoglObject pointer
 *
 * Gets whether the given @object references an existing snippet object.
 *
 * Return value: %TRUE if the @object references a #CoglSnippet,
 *   %FALSE otherwise
 *
 * Since: 1.10
 * Stability: Unstable
 */
CoglBool
cogl_is_snippet (void *object);

/**
 * cogl_snippet_set_declarations:
 * @snippet: A #CoglSnippet
 * @declarations: The new source string for the declarations section
 *   of this snippet.
 *
 * Sets a source string that will be inserted in the global scope of
 * the generated shader when this snippet is used on a pipeline. This
 * string is typically used to declare uniforms, attributes or
 * functions that will be used by the other parts of the snippets.
 *
 * This function should only be called before the snippet is attached
 * to its first pipeline. After that the snippet should be considered
 * immutable.
 *
 * Since: 1.10
 * Stability: Unstable
 */
void
cogl_snippet_set_declarations (CoglSnippet *snippet,
                               const char *declarations);

/**
 * cogl_snippet_get_declarations:
 * @snippet: A #CoglSnippet
 *
 * Return value: the source string that was set with
 *   cogl_snippet_set_declarations() or %NULL if none was set.
 *
 * Since: 1.10
 * Stability: Unstable
 */
const char *
cogl_snippet_get_declarations (CoglSnippet *snippet);

/**
 * cogl_snippet_set_pre:
 * @snippet: A #CoglSnippet
 * @pre: The new source string for the pre section of this snippet.
 *
 * Sets a source string that will be inserted before the hook point in
 * the generated shader for the pipeline that this snippet is attached
 * to. Please see the documentation of each hook point in
 * #CoglPipeline for a description of how this string should be used.
 *
 * This function should only be called before the snippet is attached
 * to its first pipeline. After that the snippet should be considered
 * immutable.
 *
 * Since: 1.10
 * Stability: Unstable
 */
void
cogl_snippet_set_pre (CoglSnippet *snippet,
                      const char *pre);

/**
 * cogl_snippet_get_pre:
 * @snippet: A #CoglSnippet
 *
 * Return value: the source string that was set with
 *   cogl_snippet_set_pre() or %NULL if none was set.
 *
 * Since: 1.10
 * Stability: Unstable
 */
const char *
cogl_snippet_get_pre (CoglSnippet *snippet);

/**
 * cogl_snippet_set_replace:
 * @snippet: A #CoglSnippet
 * @replace: The new source string for the replace section of this snippet.
 *
 * Sets a source string that will be used instead of any generated
 * source code or any previous snippets for this hook point. Please
 * see the documentation of each hook point in #CoglPipeline for a
 * description of how this string should be used.
 *
 * This function should only be called before the snippet is attached
 * to its first pipeline. After that the snippet should be considered
 * immutable.
 *
 * Since: 1.10
 * Stability: Unstable
 */
void
cogl_snippet_set_replace (CoglSnippet *snippet,
                          const char *replace);

/**
 * cogl_snippet_get_replace:
 * @snippet: A #CoglSnippet
 *
 * Return value: the source string that was set with
 *   cogl_snippet_set_replace() or %NULL if none was set.
 *
 * Since: 1.10
 * Stability: Unstable
 */
const char *
cogl_snippet_get_replace (CoglSnippet *snippet);

/**
 * cogl_snippet_set_post:
 * @snippet: A #CoglSnippet
 * @post: The new source string for the post section of this snippet.
 *
 * Sets a source string that will be inserted after the hook point in
 * the generated shader for the pipeline that this snippet is attached
 * to. Please see the documentation of each hook point in
 * #CoglPipeline for a description of how this string should be used.
 *
 * This function should only be called before the snippet is attached
 * to its first pipeline. After that the snippet should be considered
 * immutable.
 *
 * Since: 1.10
 * Stability: Unstable
 */
void
cogl_snippet_set_post (CoglSnippet *snippet,
                       const char *post);

/**
 * cogl_snippet_get_post:
 * @snippet: A #CoglSnippet
 *
 * Return value: the source string that was set with
 *   cogl_snippet_set_post() or %NULL if none was set.
 *
 * Since: 1.10
 * Stability: Unstable
 */
const char *
cogl_snippet_get_post (CoglSnippet *snippet);

COGL_END_DECLS

#endif /* __COGL_SNIPPET_H__ */