cogl/cogl-shader.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2008,2009 Intel Corporation.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  20  *
  21  *
  22  */
  23
  24 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  25 #error "Only <cogl/cogl.h> can be included directly."
  26 #endif
  27
  28 #ifndef __COGL_SHADER_H__
  29 #define __COGL_SHADER_H__
  30
  31 #include <cogl/cogl-types.h>
  32 #include <cogl/cogl-defines.h>
  33
  34 G_BEGIN_DECLS
  35
  36 /**
  37  * SECTION:cogl-shaders
  38  * @short_description: Fuctions for accessing the programmable GL pipeline
  39  *
  40  * Cogl allows accessing the GL programmable pipeline in order to create
  41  * vertex and fragment shaders.
  42  *
  43  * The shader source code can either be GLSL or ARBfp. If the source
  44  * code is ARBfp, it must begin with the string “!!ARBfp1.0”. The
  45  * application should check for the %COGL_FEATURE_SHADERS_GLSL or
  46  * %COGL_FEATURE_SHADERS_ARBFP features before using shaders.
  47  *
  48  * When using GLSL Cogl provides replacement names for most of the
  49  * builtin varyings and uniforms. It is recommended to use these names
  50  * wherever possible to increase portability between OpenGL 2.0 and
  51  * GLES 2.0. GLES 2.0 does not have most of the builtins under their
  52  * original names so they will only work with the Cogl names.
  53  *
  54  * For use in all GLSL shaders, the Cogl builtins are as follows:
  55  *
  56  * <tip>
  57  * <glosslist>
  58  *  <glossentry>
  59  *   <glossterm>uniform mat4
  60  *         <emphasis>cogl_modelview_matrix</emphasis></glossterm>
  61  *   <glossdef><para>
  62  *    The current modelview matrix. This is equivalent to
  63  *    #gl_ModelViewMatrix.
  64  *   </para></glossdef>
  65  *  </glossentry>
  66  *  <glossentry>
  67  *   <glossterm>uniform mat4
  68  *         <emphasis>cogl_projection_matrix</emphasis></glossterm>
  69  *   <glossdef><para>
  70  *    The current projection matrix. This is equivalent to
  71  *    #gl_ProjectionMatrix.
  72  *   </para></glossdef>
  73  *  </glossentry>
  74  *  <glossentry>
  75  *   <glossterm>uniform mat4
  76  *         <emphasis>cogl_modelview_projection_matrix</emphasis></glossterm>
  77  *   <glossdef><para>
  78  *    The combined modelview and projection matrix. A vertex shader
  79  *    would typically use this to transform the incoming vertex
  80  *    position. The separate modelview and projection matrices are
  81  *    usually only needed for lighting calculations. This is
  82  *    equivalent to #gl_ModelViewProjectionMatrix.
  83  *   </para></glossdef>
  84  *  </glossentry>
  85  *  <glossentry>
  86  *   <glossterm>uniform mat4
  87  *         <emphasis>cogl_texture_matrix</emphasis>[]</glossterm>
  88  *   <glossdef><para>
  89  *    An array of matrices for transforming the texture
  90  *    coordinates. This is equivalent to #gl_TextureMatrix.
  91  *   </para></glossdef>
  92  *  </glossentry>
  93  * </glosslist>
  94  * </tip>
  95  *
  96  * In a vertex shader, the following are also available:
  97  *
  98  * <tip>
  99  * <glosslist>
 100  *  <glossentry>
 101  *   <glossterm>attribute vec4
 102  *         <emphasis>cogl_position_in</emphasis></glossterm>
 103  *   <glossdef><para>
 104  *    The incoming vertex position. This is equivalent to #gl_Vertex.
 105  *   </para></glossdef>
 106  *  </glossentry>
 107  *  <glossentry>
 108  *   <glossterm>attribute vec4
 109  *         <emphasis>cogl_color_in</emphasis></glossterm>
 110  *   <glossdef><para>
 111  *    The incoming vertex color. This is equivalent to #gl_Color.
 112  *   </para></glossdef>
 113  *  </glossentry>
 114  *  <glossentry>
 115  *   <glossterm>attribute vec4
 116  *         <emphasis>cogl_tex_coord_in</emphasis></glossterm>
 117  *   <glossdef><para>
 118  *    The texture coordinate for the first texture unit. This is
 119  *    equivalent to #gl_MultiTexCoord0.
 120  *   </para></glossdef>
 121  *  </glossentry>
 122  *  <glossentry>
 123  *   <glossterm>attribute vec4
 124  *         <emphasis>cogl_tex_coord0_in</emphasis></glossterm>
 125  *   <glossdef><para>
 126  *    The texture coordinate for the first texture unit. This is
 127  *    equivalent to #gl_MultiTexCoord0. There is also
 128  *    #cogl_tex_coord1_in and so on.
 129  *   </para></glossdef>
 130  *  </glossentry>
 131  *  <glossentry>
 132  *   <glossterm>attribute vec3
 133  *         <emphasis>cogl_normal_in</emphasis></glossterm>
 134  *   <glossdef><para>
 135  *    The normal of the vertex. This is equivalent to #gl_Normal.
 136  *   </para></glossdef>
 137  *  </glossentry>
 138  *  <glossentry>
 139  *   <glossterm>vec4
 140  *         <emphasis>cogl_position_out</emphasis></glossterm>
 141  *   <glossdef><para>
 142  *    The calculated position of the vertex. This must be written to
 143  *    in all vertex shaders. This is equivalent to #gl_Position.
 144  *   </para></glossdef>
 145  *  </glossentry>
 146  *  <glossentry>
 147  *   <glossterm>float
 148  *         <emphasis>cogl_point_size_out</emphasis></glossterm>
 149  *   <glossdef><para>
 150  *    The calculated size of a point. This is equivalent to #gl_PointSize.
 151  *   </para></glossdef>
 152  *  </glossentry>
 153  *  <glossentry>
 154  *   <glossterm>varying vec4
 155  *         <emphasis>cogl_color_out</emphasis></glossterm>
 156  *   <glossdef><para>
 157  *    The calculated color of a vertex. This is equivalent to #gl_FrontColor.
 158  *   </para></glossdef>
 159  *  </glossentry>
 160  *  <glossentry>
 161  *   <glossterm>varying vec4
 162  *         <emphasis>cogl_tex_coord_out</emphasis>[]</glossterm>
 163  *   <glossdef><para>
 164  *    An array of calculated texture coordinates for a vertex. This is
 165  *    equivalent to #gl_TexCoord.
 166  *   </para></glossdef>
 167  *  </glossentry>
 168  * </glosslist>
 169  * </tip>
 170  *
 171  * In a fragment shader, the following are also available:
 172  *
 173  * <tip>
 174  * <glosslist>
 175  *  <glossentry>
 176  *   <glossterm>varying vec4 <emphasis>cogl_color_in</emphasis></glossterm>
 177  *   <glossdef><para>
 178  *    The calculated color of a vertex. This is equivalent to #gl_FrontColor.
 179  *   </para></glossdef>
 180  *  </glossentry>
 181  *  <glossentry>
 182  *   <glossterm>varying vec4
 183  *              <emphasis>cogl_tex_coord_in</emphasis>[]</glossterm>
 184  *   <glossdef><para>
 185  *    An array of calculated texture coordinates for a vertex. This is
 186  *    equivalent to #gl_TexCoord.
 187  *   </para></glossdef>
 188  *  </glossentry>
 189  *  <glossentry>
 190  *   <glossterm>vec4 <emphasis>cogl_color_out</emphasis></glossterm>
 191  *   <glossdef><para>
 192  *    The final calculated color of the fragment. All fragment shaders
 193  *    must write to this variable. This is equivalent to
 194  *    #gl_FrontColor.
 195  *   </para></glossdef>
 196  *  </glossentry>
 197  *  <glossentry>
 198  *   <glossterm>float <emphasis>cogl_depth_out</emphasis></glossterm>
 199  *   <glossdef><para>
 200  *    An optional output variable specifying the depth value to use
 201  *    for this fragment. This is equivalent to #gl_FragDepth.
 202  *   </para></glossdef>
 203  *  </glossentry>
 204  *  <glossentry>
 205  *   <glossterm>bool <emphasis>cogl_front_facing</emphasis></glossterm>
 206  *   <glossdef><para>
 207  *    A readonly variable that will be true if the current primitive
 208  *    is front facing. This can be used to implement two-sided
 209  *    coloring algorithms. This is equivalent to #gl_FrontFacing.
 210  *   </para></glossdef>
 211  *  </glossentry>
 212  * </glosslist>
 213  * </tip>
 214  *
 215  * It's worth nothing that this API isn't what Cogl would like to have
 216  * in the long term and it may be removed in Cogl 2.0. The
 217  * experimental #CoglShader API is the proposed replacement.
 218  */
 219
 220 /**
 221  * CoglShaderType:
 222  * @COGL_SHADER_TYPE_VERTEX: A program for proccessing vertices
 223  * @COGL_SHADER_TYPE_FRAGMENT: A program for processing fragments
 224  *
 225  * Types of shaders
 226  *
 227  * Since: 1.0
 228  */
 229 typedef enum {
 230   COGL_SHADER_TYPE_VERTEX,
 231   COGL_SHADER_TYPE_FRAGMENT
 232 } CoglShaderType;
 233
 234 /**
 235  * cogl_create_shader:
 236  * @shader_type: COGL_SHADER_TYPE_VERTEX or COGL_SHADER_TYPE_FRAGMENT.
 237  *
 238  * Create a new shader handle, use cogl_shader_source() to set the
 239  * source code to be used on it.
 240  *
 241  * Returns: a new shader handle.
 242  */
 243 CoglHandle
 244 cogl_create_shader (CoglShaderType shader_type);
 245
 246 #ifndef COGL_DISABLE_DEPRECATED
 247
 248 /**
 249  * cogl_shader_ref:
 250  * @handle: A #CoglHandle to a shader.
 251  *
 252  * Add an extra reference to a shader.
 253  *
 254  * Deprecated: 1.0: Please use cogl_handle_ref() instead.
 255  *
 256  * Returns: @handle
 257  */
 258 CoglHandle
 259 cogl_shader_ref (CoglHandle handle) G_GNUC_DEPRECATED;
 260
 261 /**
 262  * cogl_shader_unref:
 263  * @handle: A #CoglHandle to a shader.
 264  *
 265  * Removes a reference to a shader. If it was the last reference the
 266  * shader object will be destroyed.
 267  *
 268  * Deprecated: 1.0: Please use cogl_handle_unref() instead.
 269  */
 270 void
 271 cogl_shader_unref (CoglHandle handle) G_GNUC_DEPRECATED;
 272
 273 #endif /* COGL_DISABLE_DEPRECATED */
 274
 275 /**
 276  * cogl_is_shader:
 277  * @handle: A CoglHandle
 278  *
 279  * Gets whether the given handle references an existing shader object.
 280  *
 281  * Returns: %TRUE if the handle references a shader,
 282  *   %FALSE otherwise
 283  */
 284 gboolean
 285 cogl_is_shader (CoglHandle handle);
 286
 287 /**
 288  * cogl_shader_source:
 289  * @shader: #CoglHandle for a shader.
 290  * @source: Shader source.
 291  *
 292  * Replaces the current source associated with a shader with a new
 293  * one.
 294  *
 295  * Please see <link
 296  * linkend="cogl-Shaders-and-Programmable-Pipeline.description">above</link>
 297  * for a description of the recommended format for the shader code.
 298  */
 299 void
 300 cogl_shader_source (CoglHandle  shader,
 301                     const char *source);
 302 /**
 303  * cogl_shader_compile:
 304  * @handle: #CoglHandle for a shader.
 305  *
 306  * Compiles the shader, no return value, but the shader is now ready
 307  * for linking into a program. Note that calling this function is
 308  * optional. If it is not called then the shader will be automatically
 309  * compiled when it is linked.
 310  */
 311 void
 312 cogl_shader_compile (CoglHandle handle);
 313
 314 /**
 315  * cogl_shader_get_info_log:
 316  * @handle: #CoglHandle for a shader.
 317  *
 318  * Retrieves the information log for a coglobject, can be used in conjunction
 319  * with cogl_shader_get_parameteriv() to retrieve the compiler warnings/error
 320  * messages that caused a shader to not compile correctly, mainly useful for
 321  * debugging purposes.
 322  *
 323  * Return value: a newly allocated string containing the info log. Use
 324  *   g_free() to free it
 325  */
 326 char *
 327 cogl_shader_get_info_log (CoglHandle handle);
 328
 329 /**
 330  * cogl_shader_get_type:
 331  * @handle: #CoglHandle for a shader.
 332  *
 333  * Retrieves the type of a shader #CoglHandle
 334  *
 335  * Return value: %COGL_SHADER_TYPE_VERTEX if the shader is a vertex processor
 336  *          or %COGL_SHADER_TYPE_FRAGMENT if the shader is a frament processor
 337  */
 338 CoglShaderType
 339 cogl_shader_get_type (CoglHandle handle);
 340
 341 /**
 342  * cogl_shader_is_compiled:
 343  * @handle: #CoglHandle for a shader.
 344  *
 345  * Retrieves whether a shader #CoglHandle has been compiled
 346  *
 347  * Return value: %TRUE if the shader object has sucessfully be compiled
 348  */
 349 gboolean
 350 cogl_shader_is_compiled (CoglHandle handle);
 351
 352 /**
 353  * cogl_create_program:
 354  *
 355  * Create a new cogl program object that can be used to replace parts of the GL
 356  * rendering pipeline with custom code.
 357  *
 358  * Returns: a new cogl program.
 359  */
 360 CoglHandle
 361 cogl_create_program (void);
 362
 363 #ifndef COGL_DISABLE_DEPRECATED
 364
 365 /**
 366  * cogl_program_ref:
 367  * @handle: A #CoglHandle to a program.
 368  *
 369  * Add an extra reference to a program.
 370  *
 371  * Deprecated: 1.0: Please use cogl_handle_ref() instead.
 372  *
 373  * Returns: @handle
 374  */
 375 CoglHandle
 376 cogl_program_ref (CoglHandle handle) G_GNUC_DEPRECATED;
 377
 378 /**
 379  * cogl_program_unref:
 380  * @handle: A #CoglHandle to a program.
 381  *
 382  * Removes a reference to a program. If it was the last reference the
 383  * program object will be destroyed.
 384  *
 385  * Deprecated: 1.0: Please use cogl_handle_unref() instead.
 386  */
 387 void
 388 cogl_program_unref (CoglHandle handle) G_GNUC_DEPRECATED;
 389
 390 #endif /* COGL_DISABLE_DEPRECATED */
 391
 392 /**
 393  * cogl_is_program:
 394  * @handle: A CoglHandle
 395  *
 396  * Gets whether the given handle references an existing program object.
 397  *
 398  * Returns: %TRUE if the handle references a program,
 399  *   %FALSE otherwise
 400  */
 401 gboolean
 402 cogl_is_program (CoglHandle handle);
 403
 404 /**
 405  * cogl_program_attach_shader:
 406  * @program_handle: a #CoglHandle for a shdaer program.
 407  * @shader_handle: a #CoglHandle for a vertex of fragment shader.
 408  *
 409  * Attaches a shader to a program object. A program can have multiple
 410  * vertex or fragment shaders but only one of them may provide a
 411  * main() function. It is allowed to use a program with only a vertex
 412  * shader or only a fragment shader.
 413  */
 414 void
 415 cogl_program_attach_shader (CoglHandle program_handle,
 416                             CoglHandle shader_handle);
 417
 418 /**
 419  * cogl_program_link:
 420  * @handle: a #CoglHandle for a shader program.
 421  *
 422  * Links a program making it ready for use. Note that calling this
 423  * function is optional. If it is not called the program will
 424  * automatically be linked the first time it is used.
 425  */
 426 void
 427 cogl_program_link (CoglHandle handle);
 428
 429 /**
 430  * cogl_program_use:
 431  * @handle: a #CoglHandle for a shader program or %COGL_INVALID_HANDLE.
 432  *
 433  * Activate a specific shader program replacing that part of the GL
 434  * rendering pipeline, if passed in %COGL_INVALID_HANDLE the default
 435  * behavior of GL is reinstated.
 436  *
 437  * This function affects the global state of the current Cogl
 438  * context. It is much more efficient to attach the shader to a
 439  * specific material used for rendering instead by calling
 440  * cogl_material_set_user_program().
 441  */
 442 void
 443 cogl_program_use (CoglHandle handle);
 444
 445 /**
 446  * cogl_program_get_uniform_location:
 447  * @handle: a #CoglHandle for a shader program.
 448  * @uniform_name: the name of a uniform.
 449  *
 450  * Retrieve the location (offset) of a uniform variable in a shader program,
 451  * a uniform is a variable that is constant for all vertices/fragments for a
 452  * shader object and is possible to modify as an external parameter.
 453  *
 454  * Return value: the offset of a uniform in a specified program.
 455  *   This uniform can be set using cogl_program_uniform_1f() when the
 456  *   program is in use.
 457  */
 458 int
 459 cogl_program_get_uniform_location (CoglHandle  handle,
 460                                    const char *uniform_name);
 461
 462 /**
 463  * cogl_program_set_uniform_1f:
 464  * @program: A #CoglHandle for a linked program
 465  * @uniform_location: the uniform location retrieved from
 466  *    cogl_program_get_uniform_location().
 467  * @value: the new value of the uniform.
 468  *
 469  * Changes the value of a floating point uniform for the given linked
 470  * @program.
 471  *
 472  * Since: 1.4
 473  */
 474 void
 475 cogl_program_set_uniform_1f (CoglHandle program,
 476                              int uniform_location,
 477                              float value);
 478
 479 /**
 480  * cogl_program_set_uniform_1i:
 481  * @program: A #CoglHandle for a linked program
 482  * @uniform_location: the uniform location retrieved from
 483  *    cogl_program_get_uniform_location().
 484  * @value: the new value of the uniform.
 485  *
 486  * Changes the value of an integer uniform for the given linked
 487  * @program.
 488  *
 489  * Since: 1.4
 490  */
 491 void
 492 cogl_program_set_uniform_1i (CoglHandle program,
 493                              int uniform_location,
 494                              int value);
 495
 496 /**
 497  * cogl_program_set_uniform_float:
 498  * @program: A #CoglHandle for a linked program
 499  * @uniform_location: the uniform location retrieved from
 500  *    cogl_program_get_uniform_location().
 501  * @n_components: The number of components for the uniform. For
 502  * example with glsl you'd use 3 for a vec3 or 4 for a vec4.
 503  * @count: For uniform arrays this is the array length otherwise just
 504  * pass 1
 505  * @value: (array length=count): the new value of the uniform[s].
 506  *
 507  * Changes the value of a float vector uniform, or uniform array for
 508  * the given linked @program.
 509  *
 510  * Since: 1.4
 511  */
 512 void
 513 cogl_program_set_uniform_float (CoglHandle program,
 514                                 int uniform_location,
 515                                 int n_components,
 516                                 int count,
 517                                 const float *value);
 518
 519 /**
 520  * cogl_program_set_uniform_int:
 521  * @program: A #CoglHandle for a linked program
 522  * @uniform_location: the uniform location retrieved from
 523  *    cogl_program_get_uniform_location().
 524  * @n_components: The number of components for the uniform. For
 525  * example with glsl you'd use 3 for a vec3 or 4 for a vec4.
 526  * @count: For uniform arrays this is the array length otherwise just
 527  * pass 1
 528  * @value: (array length=count): the new value of the uniform[s].
 529  *
 530  * Changes the value of a int vector uniform, or uniform array for
 531  * the given linked @program.
 532  *
 533  * Since: 1.4
 534  */
 535 void
 536 cogl_program_set_uniform_int (CoglHandle program,
 537                               int uniform_location,
 538                               int n_components,
 539                               int count,
 540                               const int *value);
 541
 542 /**
 543  * cogl_program_set_uniform_matrix:
 544  * @program: A #CoglHandle for a linked program
 545  * @uniform_location: the uniform location retrieved from
 546  *    cogl_program_get_uniform_location().
 547  * @dimensions: The dimensions of the matrix. So for for example pass
 548  *    2 for a 2x2 matrix or 3 for 3x3.
 549  * @count: For uniform arrays this is the array length otherwise just
 550  * pass 1
 551  * @transpose: Whether to transpose the matrix when setting the uniform.
 552  * @value: (array length=count): the new value of the uniform.
 553  *
 554  * Changes the value of a matrix uniform, or uniform array in the
 555  * given linked @program.
 556  *
 557  * Since: 1.4
 558  */
 559 void
 560 cogl_program_set_uniform_matrix (CoglHandle program,
 561                                  int uniform_location,
 562                                  int dimensions,
 563                                  int count,
 564                                  gboolean transpose,
 565                                  const float *value);
 566
 567 #ifndef COGL_DISABLE_DEPRECATED
 568
 569 /**
 570  * cogl_program_uniform_1f:
 571  * @uniform_no: the uniform to set.
 572  * @value: the new value of the uniform.
 573  *
 574  * Changes the value of a floating point uniform in the currently
 575  * used (see cogl_program_use()) shader program.
 576  *
 577  * Deprecated: 1.4: Use cogl_program_set_uniform_1f() instead.
 578  */
 579 void
 580 cogl_program_uniform_1f (int   uniform_no,
 581                          float value) G_GNUC_DEPRECATED;
 582
 583 /**
 584  * cogl_program_uniform_1i:
 585  * @uniform_no: the uniform to set.
 586  * @value: the new value of the uniform.
 587  *
 588  * Changes the value of an integer uniform in the currently
 589  * used (see cogl_program_use()) shader program.
 590  *
 591  * Deprecated: 1.4: Use cogl_program_set_uniform_1i() instead.
 592  */
 593 void
 594 cogl_program_uniform_1i (int uniform_no,
 595                          int value) G_GNUC_DEPRECATED;
 596
 597 /**
 598  * cogl_program_uniform_float:
 599  * @uniform_no: the uniform to set.
 600  * @size: Size of float vector.
 601  * @count: Size of array of uniforms.
 602  * @value: (array length=count): the new value of the uniform.
 603  *
 604  * Changes the value of a float vector uniform, or uniform array in the
 605  * currently used (see cogl_program_use()) shader program.
 606  *
 607  * Deprecated: 1.4: Use cogl_program_set_uniform_float() instead.
 608  */
 609 void
 610 cogl_program_uniform_float (int            uniform_no,
 611                             int            size,
 612                             int            count,
 613                             const float   *value) G_GNUC_DEPRECATED;
 614
 615 /**
 616  * cogl_program_uniform_int:
 617  * @uniform_no: the uniform to set.
 618  * @size: Size of int vector.
 619  * @count: Size of array of uniforms.
 620  * @value: (array length=count): the new value of the uniform.
 621  *
 622  * Changes the value of a int vector uniform, or uniform array in the
 623  * currently used (see cogl_program_use()) shader program.
 624  */
 625 void
 626 cogl_program_uniform_int (int        uniform_no,
 627                           int        size,
 628                           int        count,
 629                           const int *value) G_GNUC_DEPRECATED;
 630
 631 /**
 632  * cogl_program_uniform_matrix:
 633  * @uniform_no: the uniform to set.
 634  * @size: Size of matrix.
 635  * @count: Size of array of uniforms.
 636  * @transpose: Whether to transpose the matrix when setting the uniform.
 637  * @value: (array length=count): the new value of the uniform.
 638  *
 639  * Changes the value of a matrix uniform, or uniform array in the
 640  * currently used (see cogl_program_use()) shader program. The @size
 641  * parameter is used to determine the square size of the matrix.
 642  */
 643 void
 644 cogl_program_uniform_matrix (int          uniform_no,
 645                              int          size,
 646                              int          count,
 647                              gboolean     transpose,
 648                              const float *value) G_GNUC_DEPRECATED;
 649
 650 #endif /* COGL_DISABLE_DEPRECATED */
 651
 652 G_END_DECLS
 653
 654 #endif /* __COGL_SHADER_H__ */