cogl/cogl-pipeline-state.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2007,2008,2009,2011 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_PIPELINE_STATE_H__
  29 #define __COGL_PIPELINE_STATE_H__
  30
  31 #include <cogl/cogl-pipeline.h>
  32 #include <cogl/cogl-color.h>
  33 #include <cogl/cogl-depth-state.h>
  34 #include <glib.h>
  35
  36 G_BEGIN_DECLS
  37
  38 #ifdef COGL_ENABLE_EXPERIMENTAL_API
  39
  40 /**
  41  * cogl_pipeline_set_color:
  42  * @pipeline: A #CoglPipeline object
  43  * @color: The components of the color
  44  *
  45  * Sets the basic color of the pipeline, used when no lighting is enabled.
  46  *
  47  * Note that if you don't add any layers to the pipeline then the color
  48  * will be blended unmodified with the destination; the default blend
  49  * expects premultiplied colors: for example, use (0.5, 0.0, 0.0, 0.5) for
  50  * semi-transparent red. See cogl_color_premultiply().
  51  *
  52  * The default value is (1.0, 1.0, 1.0, 1.0)
  53  *
  54  * Since: 2.0
  55  * Stability: Unstable
  56  */
  57 void
  58 cogl_pipeline_set_color (CoglPipeline    *pipeline,
  59                          const CoglColor *color);
  60
  61 /**
  62  * cogl_pipeline_set_color4ub:
  63  * @pipeline: A #CoglPipeline object
  64  * @red: The red component
  65  * @green: The green component
  66  * @blue: The blue component
  67  * @alpha: The alpha component
  68  *
  69  * Sets the basic color of the pipeline, used when no lighting is enabled.
  70  *
  71  * The default value is (0xff, 0xff, 0xff, 0xff)
  72  *
  73  * Since: 2.0
  74  * Stability: Unstable
  75  */
  76 void
  77 cogl_pipeline_set_color4ub (CoglPipeline *pipeline,
  78                             guint8        red,
  79                             guint8        green,
  80                             guint8        blue,
  81                             guint8        alpha);
  82
  83 /**
  84  * cogl_pipeline_set_color4f:
  85  * @pipeline: A #CoglPipeline object
  86  * @red: The red component
  87  * @green: The green component
  88  * @blue: The blue component
  89  * @alpha: The alpha component
  90  *
  91  * Sets the basic color of the pipeline, used when no lighting is enabled.
  92  *
  93  * The default value is (1.0, 1.0, 1.0, 1.0)
  94  *
  95  * Since: 2.0
  96  * Stability: Unstable
  97  */
  98 void
  99 cogl_pipeline_set_color4f (CoglPipeline *pipeline,
 100                            float         red,
 101                            float         green,
 102                            float         blue,
 103                            float         alpha);
 104
 105 /**
 106  * cogl_pipeline_get_color:
 107  * @pipeline: A #CoglPipeline object
 108  * @color: (out): The location to store the color
 109  *
 110  * Retrieves the current pipeline color.
 111  *
 112  * Since: 2.0
 113  * Stability: Unstable
 114  */
 115 void
 116 cogl_pipeline_get_color (CoglPipeline *pipeline,
 117                          CoglColor    *color);
 118
 119 /**
 120  * cogl_pipeline_set_ambient:
 121  * @pipeline: A #CoglPipeline object
 122  * @ambient: The components of the desired ambient color
 123  *
 124  * Sets the pipeline's ambient color, in the standard OpenGL lighting
 125  * model. The ambient color affects the overall color of the object.
 126  *
 127  * Since the diffuse color will be intense when the light hits the surface
 128  * directly, the ambient will be most apparent where the light hits at a
 129  * slant.
 130  *
 131  * The default value is (0.2, 0.2, 0.2, 1.0)
 132  *
 133  * Since: 2.0
 134  * Stability: Unstable
 135  */
 136 void
 137 cogl_pipeline_set_ambient (CoglPipeline    *pipeline,
 138                            const CoglColor *ambient);
 139
 140 /**
 141  * cogl_pipeline_get_ambient:
 142  * @pipeline: A #CoglPipeline object
 143  * @ambient: The location to store the ambient color
 144  *
 145  * Retrieves the current ambient color for @pipeline
 146  *
 147  * Since: 2.0
 148  * Stability: Unstable
 149  */
 150 void
 151 cogl_pipeline_get_ambient (CoglPipeline *pipeline,
 152                            CoglColor    *ambient);
 153
 154 /**
 155  * cogl_pipeline_set_diffuse:
 156  * @pipeline: A #CoglPipeline object
 157  * @diffuse: The components of the desired diffuse color
 158  *
 159  * Sets the pipeline's diffuse color, in the standard OpenGL lighting
 160  * model. The diffuse color is most intense where the light hits the
 161  * surface directly - perpendicular to the surface.
 162  *
 163  * The default value is (0.8, 0.8, 0.8, 1.0)
 164  *
 165  * Since: 2.0
 166  * Stability: Unstable
 167  */
 168 void
 169 cogl_pipeline_set_diffuse (CoglPipeline    *pipeline,
 170                            const CoglColor *diffuse);
 171
 172 /**
 173  * cogl_pipeline_get_diffuse:
 174  * @pipeline: A #CoglPipeline object
 175  * @diffuse: The location to store the diffuse color
 176  *
 177  * Retrieves the current diffuse color for @pipeline
 178  *
 179  * Since: 2.0
 180  * Stability: Unstable
 181  */
 182 void
 183 cogl_pipeline_get_diffuse (CoglPipeline *pipeline,
 184                            CoglColor    *diffuse);
 185
 186 /**
 187  * cogl_pipeline_set_ambient_and_diffuse:
 188  * @pipeline: A #CoglPipeline object
 189  * @color: The components of the desired ambient and diffuse colors
 190  *
 191  * Conveniently sets the diffuse and ambient color of @pipeline at the same
 192  * time. See cogl_pipeline_set_ambient() and cogl_pipeline_set_diffuse().
 193  *
 194  * The default ambient color is (0.2, 0.2, 0.2, 1.0)
 195  *
 196  * The default diffuse color is (0.8, 0.8, 0.8, 1.0)
 197  *
 198  * Since: 2.0
 199  * Stability: Unstable
 200  */
 201 void
 202 cogl_pipeline_set_ambient_and_diffuse (CoglPipeline    *pipeline,
 203                                        const CoglColor *color);
 204
 205 /**
 206  * cogl_pipeline_set_specular:
 207  * @pipeline: A #CoglPipeline object
 208  * @specular: The components of the desired specular color
 209  *
 210  * Sets the pipeline's specular color, in the standard OpenGL lighting
 211  * model. The intensity of the specular color depends on the viewport
 212  * position, and is brightest along the lines of reflection.
 213  *
 214  * The default value is (0.0, 0.0, 0.0, 1.0)
 215  *
 216  * Since: 2.0
 217  * Stability: Unstable
 218  */
 219 void
 220 cogl_pipeline_set_specular (CoglPipeline    *pipeline,
 221                             const CoglColor *specular);
 222
 223 /**
 224  * cogl_pipeline_get_specular:
 225  * @pipeline: A #CoglPipeline object
 226  * @specular: The location to store the specular color
 227  *
 228  * Retrieves the pipelines current specular color.
 229  *
 230  * Since: 2.0
 231  * Stability: Unstable
 232  */
 233 void
 234 cogl_pipeline_get_specular (CoglPipeline *pipeline,
 235                             CoglColor    *specular);
 236
 237 /**
 238  * cogl_pipeline_set_shininess:
 239  * @pipeline: A #CoglPipeline object
 240  * @shininess: The desired shininess; must be >= 0.0
 241  *
 242  * Sets the shininess of the pipeline, in the standard OpenGL lighting
 243  * model, which determines the size of the specular highlights. A
 244  * higher @shininess will produce smaller highlights which makes the
 245  * object appear more shiny.
 246  *
 247  * The default value is 0.0
 248  *
 249  * Since: 2.0
 250  * Stability: Unstable
 251  */
 252 void
 253 cogl_pipeline_set_shininess (CoglPipeline *pipeline,
 254                              float         shininess);
 255
 256 /**
 257  * cogl_pipeline_get_shininess:
 258  * @pipeline: A #CoglPipeline object
 259  *
 260  * Retrieves the pipelines current emission color.
 261  *
 262  * Return value: The pipelines current shininess value
 263  *
 264  * Since: 2.0
 265  * Stability: Unstable
 266  */
 267 float
 268 cogl_pipeline_get_shininess (CoglPipeline *pipeline);
 269
 270 /**
 271  * cogl_pipeline_set_emission:
 272  * @pipeline: A #CoglPipeline object
 273  * @emission: The components of the desired emissive color
 274  *
 275  * Sets the pipeline's emissive color, in the standard OpenGL lighting
 276  * model. It will look like the surface is a light source emitting this
 277  * color.
 278  *
 279  * The default value is (0.0, 0.0, 0.0, 1.0)
 280  *
 281  * Since: 2.0
 282  * Stability: Unstable
 283  */
 284 void
 285 cogl_pipeline_set_emission (CoglPipeline    *pipeline,
 286                             const CoglColor *emission);
 287
 288 /**
 289  * cogl_pipeline_get_emission:
 290  * @pipeline: A #CoglPipeline object
 291  * @emission: The location to store the emission color
 292  *
 293  * Retrieves the pipelines current emission color.
 294  *
 295  * Since: 2.0
 296  * Stability: Unstable
 297  */
 298 void
 299 cogl_pipeline_get_emission (CoglPipeline *pipeline,
 300                             CoglColor    *emission);
 301
 302 /**
 303  * CoglPipelineAlphaFunc:
 304  * @COGL_PIPELINE_ALPHA_FUNC_NEVER: Never let the fragment through.
 305  * @COGL_PIPELINE_ALPHA_FUNC_LESS: Let the fragment through if the incoming
 306  *   alpha value is less than the reference alpha value
 307  * @COGL_PIPELINE_ALPHA_FUNC_EQUAL: Let the fragment through if the incoming
 308  *   alpha value equals the reference alpha value
 309  * @COGL_PIPELINE_ALPHA_FUNC_LEQUAL: Let the fragment through if the incoming
 310  *   alpha value is less than or equal to the reference alpha value
 311  * @COGL_PIPELINE_ALPHA_FUNC_GREATER: Let the fragment through if the incoming
 312  *   alpha value is greater than the reference alpha value
 313  * @COGL_PIPELINE_ALPHA_FUNC_NOTEQUAL: Let the fragment through if the incoming
 314  *   alpha value does not equal the reference alpha value
 315  * @COGL_PIPELINE_ALPHA_FUNC_GEQUAL: Let the fragment through if the incoming
 316  *   alpha value is greater than or equal to the reference alpha value.
 317  * @COGL_PIPELINE_ALPHA_FUNC_ALWAYS: Always let the fragment through.
 318  *
 319  * Alpha testing happens before blending primitives with the framebuffer and
 320  * gives an opportunity to discard fragments based on a comparison with the
 321  * incoming alpha value and a reference alpha value. The #CoglPipelineAlphaFunc
 322  * determines how the comparison is done.
 323  */
 324 typedef enum {
 325   COGL_PIPELINE_ALPHA_FUNC_NEVER    = 0x0200,
 326   COGL_PIPELINE_ALPHA_FUNC_LESS     = 0x0201,
 327   COGL_PIPELINE_ALPHA_FUNC_EQUAL    = 0x0202,
 328   COGL_PIPELINE_ALPHA_FUNC_LEQUAL   = 0x0203,
 329   COGL_PIPELINE_ALPHA_FUNC_GREATER  = 0x0204,
 330   COGL_PIPELINE_ALPHA_FUNC_NOTEQUAL = 0x0205,
 331   COGL_PIPELINE_ALPHA_FUNC_GEQUAL   = 0x0206,
 332   COGL_PIPELINE_ALPHA_FUNC_ALWAYS   = 0x0207
 333 } CoglPipelineAlphaFunc;
 334 /* NB: these values come from the equivalents in gl.h */
 335
 336 /**
 337  * cogl_pipeline_set_alpha_test_function:
 338  * @pipeline: A #CoglPipeline object
 339  * @alpha_func: A @CoglPipelineAlphaFunc constant
 340  * @alpha_reference: A reference point that the chosen alpha function uses
 341  *   to compare incoming fragments to.
 342  *
 343  * Before a primitive is blended with the framebuffer, it goes through an
 344  * alpha test stage which lets you discard fragments based on the current
 345  * alpha value. This function lets you change the function used to evaluate
 346  * the alpha channel, and thus determine which fragments are discarded
 347  * and which continue on to the blending stage.
 348  *
 349  * The default is %COGL_PIPELINE_ALPHA_FUNC_ALWAYS
 350  *
 351  * Since: 2.0
 352  * Stability: Unstable
 353  */
 354 void
 355 cogl_pipeline_set_alpha_test_function (CoglPipeline         *pipeline,
 356                                        CoglPipelineAlphaFunc alpha_func,
 357                                        float                 alpha_reference);
 358
 359 /**
 360  * cogl_pipeline_get_alpha_test_function:
 361  * @pipeline: A #CoglPipeline object
 362  *
 363  * Return value: The alpha test function of @pipeline.
 364  *
 365  * Since: 2.0
 366  * Stability: Unstable
 367  */
 368 CoglPipelineAlphaFunc
 369 cogl_pipeline_get_alpha_test_function (CoglPipeline *pipeline);
 370
 371 /**
 372  * cogl_pipeline_get_alpha_test_reference:
 373  * @pipeline: A #CoglPipeline object
 374  *
 375  * Return value: The alpha test reference value of @pipeline.
 376  *
 377  * Since: 2.0
 378  * Stability: Unstable
 379  */
 380 float
 381 cogl_pipeline_get_alpha_test_reference (CoglPipeline *pipeline);
 382
 383 /**
 384  * cogl_pipeline_set_blend:
 385  * @pipeline: A #CoglPipeline object
 386  * @blend_string: A <link linkend="cogl-Blend-Strings">Cogl blend string</link>
 387  *   describing the desired blend function.
 388  * @error: return location for a #GError that may report lack of driver
 389  *   support if you give separate blend string statements for the alpha
 390  *   channel and RGB channels since some drivers, or backends such as
 391  *   GLES 1.1, don't support this feature. May be %NULL, in which case a
 392  *   warning will be printed out using GLib's logging facilities if an
 393  *   error is encountered.
 394  *
 395  * If not already familiar; please refer <link linkend="cogl-Blend-Strings">here</link>
 396  * for an overview of what blend strings are, and their syntax.
 397  *
 398  * Blending occurs after the alpha test function, and combines fragments with
 399  * the framebuffer.
 400
 401  * Currently the only blend function Cogl exposes is ADD(). So any valid
 402  * blend statements will be of the form:
 403  *
 404  * |[
 405  *   &lt;channel-mask&gt;=ADD(SRC_COLOR*(&lt;factor&gt;), DST_COLOR*(&lt;factor&gt;))
 406  * ]|
 407  *
 408  * This is the list of source-names usable as blend factors:
 409  * <itemizedlist>
 410  *   <listitem><para>SRC_COLOR: The color of the in comming fragment</para></listitem>
 411  *   <listitem><para>DST_COLOR: The color of the framebuffer</para></listitem>
 412  *   <listitem><para>CONSTANT: The constant set via cogl_pipeline_set_blend_constant()</para></listitem>
 413  * </itemizedlist>
 414  *
 415  * The source names can be used according to the
 416  * <link linkend="cogl-Blend-String-syntax">color-source and factor syntax</link>,
 417  * so for example "(1-SRC_COLOR[A])" would be a valid factor, as would
 418  * "(CONSTANT[RGB])"
 419  *
 420  * These can also be used as factors:
 421  * <itemizedlist>
 422  *   <listitem>0: (0, 0, 0, 0)</listitem>
 423  *   <listitem>1: (1, 1, 1, 1)</listitem>
 424  *   <listitem>SRC_ALPHA_SATURATE_FACTOR: (f,f,f,1) where f = MIN(SRC_COLOR[A],1-DST_COLOR[A])</listitem>
 425  * </itemizedlist>
 426  *
 427  * <note>Remember; all color components are normalized to the range [0, 1]
 428  * before computing the result of blending.</note>
 429  *
 430  * <example id="cogl-Blend-Strings-blend-unpremul">
 431  *   <title>Blend Strings/1</title>
 432  *   <para>Blend a non-premultiplied source over a destination with
 433  *   premultiplied alpha:</para>
 434  *   <programlisting>
 435  * "RGB = ADD(SRC_COLOR*(SRC_COLOR[A]), DST_COLOR*(1-SRC_COLOR[A]))"
 436  * "A   = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
 437  *   </programlisting>
 438  * </example>
 439  *
 440  * <example id="cogl-Blend-Strings-blend-premul">
 441  *   <title>Blend Strings/2</title>
 442  *   <para>Blend a premultiplied source over a destination with
 443  *   premultiplied alpha</para>
 444  *   <programlisting>
 445  * "RGBA = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
 446  *   </programlisting>
 447  * </example>
 448  *
 449  * The default blend string is:
 450  * |[
 451  *    RGBA = ADD (SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))
 452  * ]|
 453  *
 454  * That gives normal alpha-blending when the calculated color for the pipeline
 455  * is in premultiplied form.
 456  *
 457  * Return value: %TRUE if the blend string was successfully parsed, and the
 458  *   described blending is supported by the underlying driver/hardware. If
 459  *   there was an error, %FALSE is returned and @error is set accordingly (if
 460  *   present).
 461  *
 462  * Since: 2.0
 463  * Stability: Unstable
 464  */
 465 gboolean
 466 cogl_pipeline_set_blend (CoglPipeline *pipeline,
 467                          const char   *blend_string,
 468                          GError      **error);
 469
 470 /**
 471  * cogl_pipeline_set_blend_constant:
 472  * @pipeline: A #CoglPipeline object
 473  * @constant_color: The constant color you want
 474  *
 475  * When blending is setup to reference a CONSTANT blend factor then
 476  * blending will depend on the constant set with this function.
 477  *
 478  * Since: 2.0
 479  * Stability: Unstable
 480  */
 481 void
 482 cogl_pipeline_set_blend_constant (CoglPipeline *pipeline,
 483                                   const CoglColor *constant_color);
 484
 485 /**
 486  * cogl_pipeline_set_point_size:
 487  * @pipeline: a #CoglPipeline pointer
 488  * @point_size: the new point size.
 489  *
 490  * Changes the size of points drawn when %COGL_VERTICES_MODE_POINTS is
 491  * used with the vertex buffer API. Note that typically the GPU will
 492  * only support a limited minimum and maximum range of point sizes. If
 493  * the chosen point size is outside that range then the nearest value
 494  * within that range will be used instead. The size of a point is in
 495  * screen space so it will be the same regardless of any
 496  * transformations. The default point size is 1.0.
 497  *
 498  * Since: 2.0
 499  * Stability: Unstable
 500  */
 501 void
 502 cogl_pipeline_set_point_size (CoglPipeline *pipeline,
 503                               float point_size);
 504
 505 /**
 506  * cogl_pipeline_get_point_size:
 507  * @pipeline: a #CoglPipeline pointer
 508  *
 509  * Get the size of points drawn when %COGL_VERTICES_MODE_POINTS is
 510  * used with the vertex buffer API.
 511  *
 512  * Return value: the point size of the @pipeline.
 513  *
 514  * Since: 2.0
 515  * Stability: Unstable
 516  */
 517 float
 518 cogl_pipeline_get_point_size (CoglPipeline *pipeline);
 519
 520 /**
 521  * cogl_pipeline_get_color_mask:
 522  * @pipeline: a #CoglPipeline object.
 523  *
 524  * Gets the current #CoglColorMask of which channels would be written to the
 525  * current framebuffer. Each bit set in the mask means that the
 526  * corresponding color would be written.
 527  *
 528  * Returns: A #CoglColorMask
 529  * Since: 1.8
 530  * Stability: unstable
 531  */
 532 CoglColorMask
 533 cogl_pipeline_get_color_mask (CoglPipeline *pipeline);
 534
 535 /**
 536  * cogl_pipeline_set_color_mask:
 537  * @pipeline: a #CoglPipeline object.
 538  * @color_mask: A #CoglColorMask of which color channels to write to
 539  *              the current framebuffer.
 540  *
 541  * Defines a bit mask of which color channels should be written to the
 542  * current framebuffer. If a bit is set in @color_mask that means that
 543  * color will be written.
 544  *
 545  * Since: 1.8
 546  * Stability: unstable
 547  */
 548 void
 549 cogl_pipeline_set_color_mask (CoglPipeline *pipeline,
 550                               CoglColorMask color_mask);
 551
 552 /**
 553  * cogl_pipeline_get_user_program:
 554  * @pipeline: a #CoglPipeline object.
 555  *
 556  * Queries what user program has been associated with the given
 557  * @pipeline using cogl_pipeline_set_user_program().
 558  *
 559  * Return value: The current user program or %COGL_INVALID_HANDLE.
 560  *
 561  * Since: 2.0
 562  * Stability: Unstable
 563  */
 564 CoglHandle
 565 cogl_pipeline_get_user_program (CoglPipeline *pipeline);
 566
 567 /**
 568  * cogl_pipeline_set_user_program:
 569  * @pipeline: a #CoglPipeline object.
 570  * @program: A #CoglHandle to a linked CoglProgram
 571  *
 572  * Associates a linked CoglProgram with the given pipeline so that the
 573  * program can take full control of vertex and/or fragment processing.
 574  *
 575  * This is an example of how it can be used to associate an ARBfp
 576  * program with a #CoglPipeline:
 577  * |[
 578  * CoglHandle shader;
 579  * CoglHandle program;
 580  * CoglPipeline *pipeline;
 581  *
 582  * shader = cogl_create_shader (COGL_SHADER_TYPE_FRAGMENT);
 583  * cogl_shader_source (shader,
 584  *                     "!!ARBfp1.0\n"
 585  *                     "MOV result.color,fragment.color;\n"
 586  *                     "END\n");
 587  * cogl_shader_compile (shader);
 588  *
 589  * program = cogl_create_program ();
 590  * cogl_program_attach_shader (program, shader);
 591  * cogl_program_link (program);
 592  *
 593  * pipeline = cogl_pipeline_new ();
 594  * cogl_pipeline_set_user_program (pipeline, program);
 595  *
 596  * cogl_set_source_color4ub (0xff, 0x00, 0x00, 0xff);
 597  * cogl_rectangle (0, 0, 100, 100);
 598  * ]|
 599  *
 600  * It is possibly worth keeping in mind that this API is not part of
 601  * the long term design for how we want to expose shaders to Cogl
 602  * developers (We are planning on deprecating the cogl_program and
 603  * cogl_shader APIs in favour of a "snippet" framework) but in the
 604  * meantime we hope this will handle most practical GLSL and ARBfp
 605  * requirements.
 606  *
 607  * Also remember you need to check for either the
 608  * %COGL_FEATURE_SHADERS_GLSL or %COGL_FEATURE_SHADERS_ARBFP before
 609  * using the cogl_program or cogl_shader API.
 610  *
 611  * Since: 2.0
 612  * Stability: Unstable
 613  */
 614 void
 615 cogl_pipeline_set_user_program (CoglPipeline *pipeline,
 616                                 CoglHandle program);
 617
 618 /**
 619  * cogl_pipeline_set_depth_state:
 620  * @pipeline: A #CoglPipeline object
 621  * @state: A #CoglDepthState struct
 622  * @error: A #GError to report failures to setup the given @state.
 623  *
 624  * This commits all the depth state configured in @state struct to the
 625  * given @pipeline. The configuration values are copied into the
 626  * pipeline so there is no requirement to keep the #CoglDepthState
 627  * struct around if you don't need it any more.
 628  *
 629  * Note: Since some platforms do not support the depth range feature
 630  * it is possible for this function to fail and report an @error.
 631  *
 632  * Returns: TRUE if the GPU supports all the given @state else %FALSE
 633  *          and returns an @error.
 634  *
 635  * Since: 2.0
 636  * Stability: Unstable
 637  */
 638 gboolean
 639 cogl_pipeline_set_depth_state (CoglPipeline *pipeline,
 640                                const CoglDepthState *state,
 641                                GError **error);
 642
 643 /**
 644  * cogl_pipeline_get_depth_state
 645  * @pipeline: A #CoglPipeline object
 646  * @state: A destination #CoglDepthState struct
 647  *
 648  * Retrieves the current depth state configuration for the given
 649  * @pipeline as previously set using cogl_pipeline_set_depth_state().
 650  *
 651  * Since: 2.0
 652  * Stability: Unstable
 653  */
 654 void
 655 cogl_pipeline_get_depth_state (CoglPipeline *pipeline,
 656                                CoglDepthState *state_out);
 657
 658 /**
 659  * CoglPipelineCullFaceMode:
 660  * @COGL_PIPELINE_CULL_FACE_MODE_NONE: Neither face will be
 661  *  culled. This is the default.
 662  * @COGL_PIPELINE_CULL_FACE_MODE_FRONT: Front faces will be culled.
 663  * @COGL_PIPELINE_CULL_FACE_MODE_BACK: Back faces will be culled.
 664  * @COGL_PIPELINE_CULL_FACE_MODE_BOTH: All faces will be culled.
 665  *
 666  * Specifies which faces should be culled. This can be set on a
 667  * pipeline using cogl_pipeline_set_cull_face_mode().
 668  */
 669 typedef enum
 670 {
 671   COGL_PIPELINE_CULL_FACE_MODE_NONE,
 672   COGL_PIPELINE_CULL_FACE_MODE_FRONT,
 673   COGL_PIPELINE_CULL_FACE_MODE_BACK,
 674   COGL_PIPELINE_CULL_FACE_MODE_BOTH
 675 } CoglPipelineCullFaceMode;
 676
 677 /**
 678  * cogl_pipeline_set_cull_face_mode:
 679  * @pipeline: A #CoglPipeline
 680  * @cull_face_mode: The new mode to set
 681  *
 682  * Sets which faces will be culled when drawing. Face culling can be
 683  * used to increase efficiency by avoiding drawing faces that would
 684  * get overridden. For example, if a model has gaps so that it is
 685  * impossible to see the inside then faces which are facing away from
 686  * the screen will never be seen so there is no point in drawing
 687  * them. This can be acheived by setting the cull face mode to
 688  * %COGL_PIPELINE_CULL_FACE_MODE_BACK.
 689  *
 690  * Face culling relies on the primitives being drawn with a specific
 691  * order to represent which faces are facing inside and outside the
 692  * model. This order can be specified by calling
 693  * cogl_pipeline_set_front_face_winding().
 694  *
 695  * Status: Unstable
 696  * Since: 2.0
 697  */
 698 void
 699 cogl_pipeline_set_cull_face_mode (CoglPipeline *pipeline,
 700                                   CoglPipelineCullFaceMode cull_face_mode);
 701
 702 /**
 703  * cogl_pipeline_get_cull_face_mode:
 704  *
 705  * Return value: the cull face mode that was previously set with
 706  * cogl_pipeline_set_cull_face_mode().
 707  *
 708  * Status: Unstable
 709  * Since: 2.0
 710  */
 711 CoglPipelineCullFaceMode
 712 cogl_pipeline_get_cull_face_mode (CoglPipeline *pipeline);
 713
 714 /**
 715  * cogl_pipeline_set_front_face_winding:
 716  *
 717  * The order of the vertices within a primitive specifies whether it
 718  * is considered to be front or back facing. This function specifies
 719  * which order is considered to be the front
 720  * faces. %COGL_WINDING_COUNTER_CLOCKWISE sets the front faces to
 721  * primitives with vertices in a counter-clockwise order and
 722  * %COGL_WINDING_CLOCKWISE sets them to be clockwise. The default is
 723  * %COGL_WINDING_COUNTER_CLOCKWISE.
 724  *
 725  * Status: Unstable
 726  * Since: 2.0
 727  */
 728 void
 729 cogl_pipeline_set_front_face_winding (CoglPipeline *pipeline,
 730                                       CoglWinding front_winding);
 731
 732 /**
 733  * cogl_pipeline_set_front_face_winding:
 734  *
 735  * The order of the vertices within a primitive specifies whether it
 736  * is considered to be front or back facing. This function specifies
 737  * which order is considered to be the front
 738  * faces. %COGL_WINDING_COUNTER_CLOCKWISE sets the front faces to
 739  * primitives with vertices in a counter-clockwise order and
 740  * %COGL_WINDING_CLOCKWISE sets them to be clockwise. The default is
 741  * %COGL_WINDING_COUNTER_CLOCKWISE.
 742  *
 743  * Status: Unstable
 744  * Since: 2.0
 745  */
 746 CoglWinding
 747 cogl_pipeline_get_front_face_winding (CoglPipeline *pipeline);
 748
 749 /**
 750  * cogl_pipeline_set_uniform_1f:
 751  * @pipeline: A #CoglPipeline object
 752  * @uniform_location: The uniform's location identifier
 753  * @value: The new value for the uniform
 754  *
 755  * Sets a new value for the uniform at @uniform_location. If this
 756  * pipeline has a user program attached and is later used as a source
 757  * for drawing, the given value will be assigned to the uniform which
 758  * can be accessed from the shader's source. The value for
 759  * @uniform_location should be retrieved from the string name of the
 760  * uniform by calling cogl_pipeline_get_uniform_location().
 761  *
 762  * This function should be used to set uniforms that are of type
 763  * float. It can also be used to set a single member of a float array
 764  * uniform.
 765  *
 766  * Since: 2.0
 767  * Stability: Unstable
 768  */
 769 void
 770 cogl_pipeline_set_uniform_1f (CoglPipeline *pipeline,
 771                               int uniform_location,
 772                               float value);
 773
 774 /**
 775  * cogl_pipeline_set_uniform_1i:
 776  * @pipeline: A #CoglPipeline object
 777  * @uniform_location: The uniform's location identifier
 778  * @value: The new value for the uniform
 779  *
 780  * Sets a new value for the uniform at @uniform_location. If this
 781  * pipeline has a user program attached and is later used as a source
 782  * for drawing, the given value will be assigned to the uniform which
 783  * can be accessed from the shader's source. The value for
 784  * @uniform_location should be retrieved from the string name of the
 785  * uniform by calling cogl_pipeline_get_uniform_location().
 786  *
 787  * This function should be used to set uniforms that are of type
 788  * int. It can also be used to set a single member of a int array
 789  * uniform or a sampler uniform.
 790  *
 791  * Since: 2.0
 792  * Stability: Unstable
 793  */
 794 void
 795 cogl_pipeline_set_uniform_1i (CoglPipeline *pipeline,
 796                               int uniform_location,
 797                               int value);
 798
 799 /**
 800  * cogl_pipeline_set_uniform_float:
 801  * @pipeline: A #CoglPipeline object
 802  * @uniform_location: The uniform's location identifier
 803  * @n_components: The number of components in the corresponding uniform's type
 804  * @count: The number of values to set
 805  * @value: Pointer to the new values to set
 806  *
 807  * Sets new values for the uniform at @uniform_location. If this
 808  * pipeline has a user program attached and is later used as a source
 809  * for drawing, the given values will be assigned to the uniform which
 810  * can be accessed from the shader's source. The value for
 811  * @uniform_location should be retrieved from the string name of the
 812  * uniform by calling cogl_pipeline_get_uniform_location().
 813  *
 814  * This function can be used to set any floating point type uniform,
 815  * including float arrays and float vectors. For example, to set a
 816  * single vec4 uniform you would use 4 for @n_components and 1 for
 817  * @count. To set an array of 8 float values, you could use 1 for
 818  * @n_components and 8 for @count.
 819  *
 820  * Since: 2.0
 821  * Stability: Unstable
 822  */
 823 void
 824 cogl_pipeline_set_uniform_float (CoglPipeline *pipeline,
 825                                  int uniform_location,
 826                                  int n_components,
 827                                  int count,
 828                                  const float *value);
 829
 830 /**
 831  * cogl_pipeline_set_uniform_int:
 832  * @pipeline: A #CoglPipeline object
 833  * @uniform_location: The uniform's location identifier
 834  * @n_components: The number of components in the corresponding uniform's type
 835  * @count: The number of values to set
 836  * @value: Pointer to the new values to set
 837  *
 838  * Sets new values for the uniform at @uniform_location. If this
 839  * pipeline has a user program attached and is later used as a source
 840  * for drawing, the given values will be assigned to the uniform which
 841  * can be accessed from the shader's source. The value for
 842  * @uniform_location should be retrieved from the string name of the
 843  * uniform by calling cogl_pipeline_get_uniform_location().
 844  *
 845  * This function can be used to set any integer type uniform,
 846  * including int arrays and int vectors. For example, to set a single
 847  * ivec4 uniform you would use 4 for @n_components and 1 for
 848  * @count. To set an array of 8 int values, you could use 1 for
 849  * @n_components and 8 for @count.
 850  *
 851  * Since: 2.0
 852  * Stability: Unstable
 853  */
 854 void
 855 cogl_pipeline_set_uniform_int (CoglPipeline *pipeline,
 856                                int uniform_location,
 857                                int n_components,
 858                                int count,
 859                                const int *value);
 860
 861 /**
 862  * cogl_pipeline_set_uniform_matrix:
 863  * @pipeline: A #CoglPipeline object
 864  * @uniform_location: The uniform's location identifier
 865  * @dimensions: The size of the matrix
 866  * @count: The number of values to set
 867  * @transpose: Whether to transpose the matrix
 868  * @value: Pointer to the new values to set
 869  *
 870  * Sets new values for the uniform at @uniform_location. If this
 871  * pipeline has a user program attached and is later used as a source
 872  * for drawing, the given values will be assigned to the uniform which
 873  * can be accessed from the shader's source. The value for
 874  * @uniform_location should be retrieved from the string name of the
 875  * uniform by calling cogl_pipeline_get_uniform_location().
 876  *
 877  * This function can be used to set any matrix type uniform, including
 878  * matrix arrays. For example, to set a single mat4 uniform you would
 879  * use 4 for @dimensions and 1 for @count. To set an array of 8
 880  * mat3 values, you could use 3 for @dimensions and 8 for @count.
 881  *
 882  * If @transpose is %FALSE then the matrix is expected to be in
 883  * column-major order or if it is %TRUE then the matrix is in
 884  * row-major order. You can pass a #CoglMatrix by calling by passing
 885  * the result of cogl_matrix_get_array() in @value and setting
 886  * @transpose to %FALSE.
 887  *
 888  * Since: 2.0
 889  * Stability: Unstable
 890  */
 891 void
 892 cogl_pipeline_set_uniform_matrix (CoglPipeline *pipeline,
 893                                   int uniform_location,
 894                                   int dimensions,
 895                                   int count,
 896                                   gboolean transpose,
 897                                   const float *value);
 898
 899 /**
 900  * cogl_pipeline_add_snippet:
 901  * @pipeline: A #CoglPipeline
 902  * @snippet: The #CoglSnippet to add to the vertex processing hook
 903  *
 904  * Adds a shader snippet to @pipeline. The snippet will wrap around or
 905  * replace some part of the pipeline as defined by the hook point in
 906  * @snippet. Note that some hook points are specific to a layer and
 907  * must be added with cogl_pipeline_add_layer_snippet() instead.
 908  *
 909  * Since: 1.10
 910  * Stability: Unstable
 911  */
 912 void
 913 cogl_pipeline_add_snippet (CoglPipeline *pipeline,
 914                            CoglSnippet *snippet);
 915
 916 #endif /* COGL_ENABLE_EXPERIMENTAL_API */
 917
 918 G_END_DECLS
 919
 920 #endif /* __COGL_PIPELINE_STATE_H__ */