brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

cogl-shader: Update the gtk-doc

Browse Source 
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>
This commit is contained in:
Neil Roberts 2011-10-20 13:53:04 +01:00
parent 81eab3dbcf
commit b85f5e0198
1 changed files with 219 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
cogl/cogl-shader.h
View File

@ -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
* 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 <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
* 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);