cogl-shader: Update the gtk-doc

This adds a description of the replacement Cogl names for the GLSL
builtins. It also updates some of the deprecation tags and corrects
some misinformation.

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

cogl/cogl-shader.h

@@ -37,10 +37,187 @@ G_BEGIN_DECLS
  * SECTION:cogl-shaders
  * @short_description: Fuctions for accessing the programmable GL pipeline
  *
- * COGL allows accessing the GL programmable pipeline in order to create
+ * Cogl allows accessing the GL programmable pipeline in order to create
  * vertex and fragment shaders.
  *
- * The only supported format is GLSL shaders.
+ * The shader source code can either be GLSL or ARBfp. If the source
+ * code is ARBfp, it must begin with the string “!!ARBfp1.0”. The
+ * application should check for the %COGL_FEATURE_SHADERS_GLSL or
+ * %COGL_FEATURE_SHADERS_ARBFP features before using shaders.
+ *
+ * When using GLSL Cogl provides replacement names for most of the
+ * builtin varyings and uniforms. It is recommended to use these names
+ * wherever possible to increase portability between OpenGL 2.0 and
+ * GLES 2.0. GLES 2.0 does not have most of the builtins under their
+ * original names so they will only work with the Cogl names.
+ *
+ * For use in all GLSL shaders, the Cogl builtins are as follows:
+ *
+ * <tip>
+ * <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>
+ * </tip>
+ *
+ * In a vertex shader, the following are also available:
+ *
+ * <tip>
+ * <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 the first texture unit. This is
+ *    equivalent to #gl_MultiTexCoord0.
+ *   </para></glossdef>
+ *  </glossentry>
+ *  <glossentry>
+ *   <glossterm>attribute vec4
+ *         <emphasis>cogl_tex_coord0_in</emphasis></glossterm>
+ *   <glossdef><para>
+ *    The texture coordinate for the first texture unit. This is
+ *    equivalent to #gl_MultiTexCoord0. There is also
+ *    #cogl_tex_coord1_in and so on.
+ *   </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_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_coord_out</emphasis>[]</glossterm>
+ *   <glossdef><para>
+ *    An array of calculated texture coordinates for a vertex. This is
+ *    equivalent to #gl_TexCoord.
+ *   </para></glossdef>
+ *  </glossentry>
+ * </glosslist>
+ * </tip>
+ *
+ * In a fragment shader, the following are also available:
+ *
+ * <tip>
+ * <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_coord_in</emphasis>[]</glossterm>
+ *   <glossdef><para>
+ *    An array of calculated texture coordinates for a vertex. This is
+ *    equivalent to #gl_TexCoord.
+ *   </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>
+ * </glosslist>
+ * </tip>
+ *
+ * It's worth nothing that this API isn't what Cogl would like to have
+ * and at some point it may become deprecated. In future Cogl would
+ * like to have an API where parts of the pipeline in a #CoglMaterial
+ * can be replaced with snippets of shader code. This API only allows
+ * the entire fragment or vertex pipeline to be replaced with shader
+ * code.
  */
 
 /**
@@ -61,8 +238,8 @@ typedef enum {
  * cogl_create_shader:
  * @shader_type: COGL_SHADER_TYPE_VERTEX or COGL_SHADER_TYPE_FRAGMENT.
  *
- * Create a new shader handle, use #cogl_shader_source to set the source code
+ * Create a new shader handle, use cogl_shader_source() to set the
- * to be used on it.
+ * source code to be used on it.
  *
  * Returns: a new shader handle.
  */
@@ -77,6 +254,8 @@ cogl_create_shader (CoglShaderType shader_type);
  *
  * Add an extra reference to a shader.
  *
+ * Deprecated: 1.0: Please use cogl_handle_ref() instead.
+ *
  * Returns: @handle
  */
 CoglHandle
@@ -88,6 +267,8 @@ cogl_shader_ref (CoglHandle handle) G_GNUC_DEPRECATED;
  *
  * Removes a reference to a shader. If it was the last reference the
  * shader object will be destroyed.
+ *
+ * Deprecated: 1.0: Please use cogl_handle_unref() instead.
  */
 void
 cogl_shader_unref (CoglHandle handle) G_GNUC_DEPRECATED;
@@ -103,15 +284,20 @@ cogl_shader_unref (CoglHandle handle) G_GNUC_DEPRECATED;
  * Returns: %TRUE if the handle references a shader,
  *   %FALSE otherwise
  */
-gboolean cogl_is_shader (CoglHandle handle);
+gboolean
+cogl_is_shader (CoglHandle handle);
 
 /**
  * cogl_shader_source:
  * @shader: #CoglHandle for a shader.
- * @source: GLSL shader source.
+ * @source: Shader source.
  *
- * Replaces the current GLSL source associated with a shader with a new
+ * Replaces the current source associated with a shader with a new
  * one.
+ *
+ * Please see <link
+ * linkend="cogl-Shaders-and-Programmable-Pipeline.description">above</link>
+ * for a description of the recommended format for the shader code.
  */
 void
 cogl_shader_source (CoglHandle  shader,
@@ -120,8 +306,10 @@ cogl_shader_source (CoglHandle  shader,
  * cogl_shader_compile:
  * @handle: #CoglHandle for a shader.
  *
- * Compiles the shader, no return value, but the shader is now ready for
+ * Compiles the shader, no return value, but the shader is now ready
- * linking into a program.
+ * for linking into a program. Note that calling this function is
+ * optional. If it is not called then the shader will be automatically
+ * compiled when it is linked.
  */
 void
 cogl_shader_compile (CoglHandle handle);
@@ -175,16 +363,20 @@ cogl_shader_is_compiled (CoglHandle handle);
 CoglHandle
 cogl_create_program (void);
 
+#ifndef COGL_DISABLE_DEPRECATED
+
 /**
  * cogl_program_ref:
  * @handle: A #CoglHandle to a program.
  *
  * Add an extra reference to a program.
  *
+ * Deprecated: 1.0: Please use cogl_handle_ref() instead.
+ *
  * Returns: @handle
  */
 CoglHandle
-cogl_program_ref (CoglHandle handle);
+cogl_program_ref (CoglHandle handle) G_GNUC_DEPRECATED;
 
 /**
  * cogl_program_unref:
@@ -192,9 +384,13 @@ cogl_program_ref (CoglHandle handle);
  *
  * Removes a reference to a program. If it was the last reference the
  * program object will be destroyed.
+ *
+ * Deprecated: 1.0: Please use cogl_handle_unref() instead.
  */
 void
-cogl_program_unref (CoglHandle handle);
+cogl_program_unref (CoglHandle handle) G_GNUC_DEPRECATED;
+
+#endif /* COGL_DISABLE_DEPRECATED */
 
 /**
  * cogl_is_program:
@@ -213,19 +409,22 @@ cogl_is_program (CoglHandle handle);
  * @program_handle: a #CoglHandle for a shdaer program.
  * @shader_handle: a #CoglHandle for a vertex of fragment shader.
  *
- * Attaches a shader to a program object, a program can have one vertex shader
+ * Attaches a shader to a program object. A program can have multiple
- * and one fragment shader attached.
+ * vertex or fragment shaders but only one of them may provide a
+ * main() function. It is allowed to use a program with only a vertex
+ * shader or only a fragment shader.
  */
 void
 cogl_program_attach_shader (CoglHandle program_handle,
                             CoglHandle shader_handle);
 
-
 /**
  * cogl_program_link:
  * @handle: a #CoglHandle for a shader program.
  *
- * Links a program making it ready for use.
+ * Links a program making it ready for use. Note that calling this
+ * function is optional. If it is not called the program will
+ * automatically be linked the first time it is used.
  */
 void
 cogl_program_link (CoglHandle handle);
@@ -237,6 +436,11 @@ cogl_program_link (CoglHandle handle);
  * Activate a specific shader program replacing that part of the GL
  * rendering pipeline, if passed in %COGL_INVALID_HANDLE the default
  * behavior of GL is reinstated.
+ *
+ * This function affects the global state of the current Cogl
+ * context. It is much more efficient to attach the shader to a
+ * specific material used for rendering instead by calling
+ * cogl_material_set_user_program().
  */
 void
 cogl_program_use (CoglHandle handle);