From b85f5e0198c849b541aecc274c0da9ee478007e6 Mon Sep 17 00:00:00 2001 From: Neil Roberts Date: Thu, 20 Oct 2011 13:53:04 +0100 Subject: [PATCH] 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 --- cogl/cogl-shader.h | 234 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 219 insertions(+), 15 deletions(-) diff --git a/cogl/cogl-shader.h b/cogl/cogl-shader.h index 9d0d7ad24..bdef11c71 100644 --- a/cogl/cogl-shader.h +++ b/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: + * + * + * + * + * uniform mat4 + * cogl_modelview_matrix + * + * The current modelview matrix. This is equivalent to + * #gl_ModelViewMatrix. + * + * + * + * uniform mat4 + * cogl_projection_matrix + * + * The current projection matrix. This is equivalent to + * #gl_ProjectionMatrix. + * + * + * + * uniform mat4 + * cogl_modelview_projection_matrix + * + * 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. + * + * + * + * uniform mat4 + * cogl_texture_matrix[] + * + * An array of matrices for transforming the texture + * coordinates. This is equivalent to #gl_TextureMatrix. + * + * + * + * + * + * In a vertex shader, the following are also available: + * + * + * + * + * attribute vec4 + * cogl_position_in + * + * The incoming vertex position. This is equivalent to #gl_Vertex. + * + * + * + * attribute vec4 + * cogl_color_in + * + * The incoming vertex color. This is equivalent to #gl_Color. + * + * + * + * attribute vec4 + * cogl_tex_coord_in + * + * The texture coordinate for the first texture unit. This is + * equivalent to #gl_MultiTexCoord0. + * + * + * + * attribute vec4 + * cogl_tex_coord0_in + * + * The texture coordinate for the first texture unit. This is + * equivalent to #gl_MultiTexCoord0. There is also + * #cogl_tex_coord1_in and so on. + * + * + * + * attribute vec3 + * cogl_normal_in + * + * The normal of the vertex. This is equivalent to #gl_Normal. + * + * + * + * vec4 + * cogl_position_out + * + * The calculated position of the vertex. This must be written to + * in all vertex shaders. This is equivalent to #gl_Position. + * + * + * + * float + * cogl_point_size_out + * + * The calculated size of a point. This is equivalent to #gl_PointSize. + * + * + * + * varying vec4 + * cogl_color_out + * + * The calculated color of a vertex. This is equivalent to #gl_FrontColor. + * + * + * + * varying vec4 + * cogl_tex_coord_out[] + * + * An array of calculated texture coordinates for a vertex. This is + * equivalent to #gl_TexCoord. + * + * + * + * + * + * In a fragment shader, the following are also available: + * + * + * + * + * varying vec4 cogl_color_in + * + * The calculated color of a vertex. This is equivalent to #gl_FrontColor. + * + * + * + * varying vec4 + * cogl_tex_coord_in[] + * + * An array of calculated texture coordinates for a vertex. This is + * equivalent to #gl_TexCoord. + * + * + * + * vec4 cogl_color_out + * + * The final calculated color of the fragment. All fragment shaders + * must write to this variable. This is equivalent to + * #gl_FrontColor. + * + * + * + * float cogl_depth_out + * + * An optional output variable specifying the depth value to use + * for this fragment. This is equivalent to #gl_FragDepth. + * + * + * + * bool cogl_front_facing + * + * 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. + * + * + * + * + * + * 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 - * to be used on it. + * Create a new shader handle, use cogl_shader_source() to set the + * 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 above + * 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 - * linking into a program. + * Compiles the shader, no return value, but the shader is now ready + * 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 - * and one fragment shader attached. + * Attaches a shader to a program object. A program can have multiple + * 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);