cogl/cogl-material-compat.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2007,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_MATERIAL_H__
  29 #define __COGL_MATERIAL_H__
  30
  31 #include <cogl/cogl-types.h>
  32 #include <cogl/cogl-matrix.h>
  33 #include <cogl/cogl-depth-state.h>
  34
  35 G_BEGIN_DECLS
  36
  37 /**
  38  * SECTION:cogl-material
  39  * @short_description: Fuctions for creating and manipulating materials
  40  *
  41  * COGL allows creating and manipulating materials used to fill in
  42  * geometry. Materials may simply be lighting attributes (such as an
  43  * ambient and diffuse colour) or might represent one or more textures
  44  * blended together.
  45  */
  46
  47 typedef struct _CoglMaterial          CoglMaterial;
  48 typedef struct _CoglMaterialLayer     CoglMaterialLayer;
  49
  50 #define COGL_MATERIAL(OBJECT) ((CoglMaterial *)OBJECT)
  51
  52 /**
  53  * CoglMaterialFilter:
  54  * @COGL_MATERIAL_FILTER_NEAREST: Measuring in manhatten distance from the,
  55  *   current pixel center, use the nearest texture texel
  56  * @COGL_MATERIAL_FILTER_LINEAR: Use the weighted average of the 4 texels
  57  *   nearest the current pixel center
  58  * @COGL_MATERIAL_FILTER_NEAREST_MIPMAP_NEAREST: Select the mimap level whose
  59  *   texel size most closely matches the current pixel, and use the
  60  *   %COGL_MATERIAL_FILTER_NEAREST criterion
  61  * @COGL_MATERIAL_FILTER_LINEAR_MIPMAP_NEAREST: Select the mimap level whose
  62  *   texel size most closely matches the current pixel, and use the
  63  *   %COGL_MATERIAL_FILTER_LINEAR criterion
  64  * @COGL_MATERIAL_FILTER_NEAREST_MIPMAP_LINEAR: Select the two mimap levels
  65  *   whose texel size most closely matches the current pixel, use
  66  *   the %COGL_MATERIAL_FILTER_NEAREST criterion on each one and take
  67  *   their weighted average
  68  * @COGL_MATERIAL_FILTER_LINEAR_MIPMAP_LINEAR: Select the two mimap levels
  69  *   whose texel size most closely matches the current pixel, use
  70  *   the %COGL_MATERIAL_FILTER_LINEAR criterion on each one and take
  71  *   their weighted average
  72  *
  73  * Texture filtering is used whenever the current pixel maps either to more
  74  * than one texture element (texel) or less than one. These filter enums
  75  * correspond to different strategies used to come up with a pixel color, by
  76  * possibly referring to multiple neighbouring texels and taking a weighted
  77  * average or simply using the nearest texel.
  78  */
  79 typedef enum {
  80   COGL_MATERIAL_FILTER_NEAREST = 0x2600,
  81   COGL_MATERIAL_FILTER_LINEAR = 0x2601,
  82   COGL_MATERIAL_FILTER_NEAREST_MIPMAP_NEAREST = 0x2700,
  83   COGL_MATERIAL_FILTER_LINEAR_MIPMAP_NEAREST = 0x2701,
  84   COGL_MATERIAL_FILTER_NEAREST_MIPMAP_LINEAR = 0x2702,
  85   COGL_MATERIAL_FILTER_LINEAR_MIPMAP_LINEAR = 0x2703
  86 } CoglMaterialFilter;
  87 /* NB: these values come from the equivalents in gl.h */
  88
  89 /**
  90  * CoglMaterialWrapMode:
  91  * @COGL_MATERIAL_WRAP_MODE_REPEAT: The texture will be repeated. This
  92  *   is useful for example to draw a tiled background.
  93  * @COGL_MATERIAL_WRAP_MODE_CLAMP_TO_EDGE: The coordinates outside the
  94  *   range 0→1 will sample copies of the edge pixels of the
  95  *   texture. This is useful to avoid artifacts if only one copy of
  96  *   the texture is being rendered.
  97  * @COGL_MATERIAL_WRAP_MODE_AUTOMATIC: Cogl will try to automatically
  98  *   decide which of the above two to use. For cogl_rectangle(), it
  99  *   will use repeat mode if any of the texture coordinates are
 100  *   outside the range 0→1, otherwise it will use clamp to edge. For
 101  *   cogl_polygon() it will always use repeat mode. For
 102  *   cogl_vertex_buffer_draw() it will use repeat mode except for
 103  *   layers that have point sprite coordinate generation enabled. This
 104  *   is the default value.
 105  *
 106  * The wrap mode specifies what happens when texture coordinates
 107  * outside the range 0→1 are used. Note that if the filter mode is
 108  * anything but %COGL_MATERIAL_FILTER_NEAREST then texels outside the
 109  * range 0→1 might be used even when the coordinate is exactly 0 or 1
 110  * because OpenGL will try to sample neighbouring pixels. For example
 111  * if you are trying to render the full texture then you may get
 112  * artifacts around the edges when the pixels from the other side are
 113  * merged in if the wrap mode is set to repeat.
 114  *
 115  * Since: 1.4
 116  */
 117 /* GL_ALWAYS is just used here as a value that is known not to clash
 118  * with any valid GL wrap modes
 119  *
 120  * XXX: keep the values in sync with the CoglMaterialWrapModeInternal
 121  * enum so no conversion is actually needed.
 122  */
 123 typedef enum {
 124   COGL_MATERIAL_WRAP_MODE_REPEAT = 0x2901,
 125   COGL_MATERIAL_WRAP_MODE_CLAMP_TO_EDGE = 0x812F,
 126   COGL_MATERIAL_WRAP_MODE_AUTOMATIC = 0x0207
 127 } CoglMaterialWrapMode;
 128 /* NB: these values come from the equivalents in gl.h */
 129
 130 /**
 131  * cogl_material_new:
 132  *
 133  * Allocates and initializes a blank white material
 134  *
 135  * Return value: a pointer to a new #CoglMaterial
 136  */
 137 CoglMaterial *
 138 cogl_material_new (void);
 139
 140 /**
 141  * cogl_material_copy:
 142  * @source: a #CoglMaterial object to copy
 143  *
 144  * Creates a new material with the configuration copied from the
 145  * source material.
 146  *
 147  * We would strongly advise developers to always aim to use
 148  * cogl_material_copy() instead of cogl_material_new() whenever there will
 149  * be any similarity between two materials. Copying a material helps Cogl
 150  * keep track of a materials ancestry which we may use to help minimize GPU
 151  * state changes.
 152  *
 153  * Returns: a pointer to the newly allocated #CoglMaterial
 154  *
 155  * Since: 1.2
 156  */
 157 CoglMaterial *
 158 cogl_material_copy (CoglMaterial *source);
 159
 160 #ifndef COGL_DISABLE_DEPRECATED
 161
 162 /**
 163  * cogl_material_ref:
 164  * @material: a #CoglMaterial object.
 165  *
 166  * Increment the reference count for a #CoglMaterial.
 167  *
 168  * Return value: the @material.
 169  *
 170  * Since: 1.0
 171  *
 172  * Deprecated: 1.2: Use cogl_object_ref() instead
 173  */
 174 CoglHandle
 175 cogl_material_ref (CoglHandle material) G_GNUC_DEPRECATED;
 176
 177 /**
 178  * cogl_material_unref:
 179  * @material: a #CoglMaterial object.
 180  *
 181  * Decrement the reference count for a #CoglMaterial.
 182  *
 183  * Since: 1.0
 184  *
 185  * Deprecated: 1.2: Use cogl_object_unref() instead
 186  */
 187 void
 188 cogl_material_unref (CoglHandle material) G_GNUC_DEPRECATED;
 189
 190 #endif /* COGL_DISABLE_DEPRECATED */
 191
 192 /**
 193  * cogl_is_material:
 194  * @handle: A CoglHandle
 195  *
 196  * Gets whether the given handle references an existing material object.
 197  *
 198  * Return value: %TRUE if the handle references a #CoglMaterial,
 199  *   %FALSE otherwise
 200  */
 201 gboolean
 202 cogl_is_material (CoglHandle handle);
 203
 204 /**
 205  * cogl_material_set_color:
 206  * @material: A #CoglMaterial object
 207  * @color: The components of the color
 208  *
 209  * Sets the basic color of the material, used when no lighting is enabled.
 210  *
 211  * Note that if you don't add any layers to the material then the color
 212  * will be blended unmodified with the destination; the default blend
 213  * expects premultiplied colors: for example, use (0.5, 0.0, 0.0, 0.5) for
 214  * semi-transparent red. See cogl_color_premultiply().
 215  *
 216  * The default value is (1.0, 1.0, 1.0, 1.0)
 217  *
 218  * Since: 1.0
 219  */
 220 void
 221 cogl_material_set_color (CoglMaterial    *material,
 222                          const CoglColor *color);
 223
 224 /**
 225  * cogl_material_set_color4ub:
 226  * @material: A #CoglMaterial object
 227  * @red: The red component
 228  * @green: The green component
 229  * @blue: The blue component
 230  * @alpha: The alpha component
 231  *
 232  * Sets the basic color of the material, used when no lighting is enabled.
 233  *
 234  * The default value is (0xff, 0xff, 0xff, 0xff)
 235  *
 236  * Since: 1.0
 237  */
 238 void
 239 cogl_material_set_color4ub (CoglMaterial *material,
 240                             guint8        red,
 241                             guint8        green,
 242                             guint8        blue,
 243                             guint8        alpha);
 244
 245 /**
 246  * cogl_material_set_color4f:
 247  * @material: A #CoglMaterial object
 248  * @red: The red component
 249  * @green: The green component
 250  * @blue: The blue component
 251  * @alpha: The alpha component
 252  *
 253  * Sets the basic color of the material, used when no lighting is enabled.
 254  *
 255  * The default value is (1.0, 1.0, 1.0, 1.0)
 256  *
 257  * Since: 1.0
 258  */
 259 void
 260 cogl_material_set_color4f (CoglMaterial *material,
 261                            float         red,
 262                            float         green,
 263                            float         blue,
 264                            float         alpha);
 265
 266 /**
 267  * cogl_material_get_color:
 268  * @material: A #CoglMaterial object
 269  * @color: (out): The location to store the color
 270  *
 271  * Retrieves the current material color.
 272  *
 273  * Since: 1.0
 274  */
 275 void
 276 cogl_material_get_color (CoglMaterial *material,
 277                          CoglColor    *color);
 278
 279 /**
 280  * cogl_material_set_ambient:
 281  * @material: A #CoglMaterial object
 282  * @ambient: The components of the desired ambient color
 283  *
 284  * Sets the material's ambient color, in the standard OpenGL lighting
 285  * model. The ambient color affects the overall color of the object.
 286  *
 287  * Since the diffuse color will be intense when the light hits the surface
 288  * directly, the ambient will be most apparent where the light hits at a
 289  * slant.
 290  *
 291  * The default value is (0.2, 0.2, 0.2, 1.0)
 292  *
 293  * Since: 1.0
 294  */
 295 void
 296 cogl_material_set_ambient (CoglMaterial    *material,
 297                            const CoglColor *ambient);
 298
 299 /**
 300  * cogl_material_get_ambient:
 301  * @material: A #CoglMaterial object
 302  * @ambient: The location to store the ambient color
 303  *
 304  * Retrieves the current ambient color for @material
 305  *
 306  * Since: 1.0
 307  */
 308 void
 309 cogl_material_get_ambient (CoglMaterial *material,
 310                            CoglColor    *ambient);
 311
 312 /**
 313  * cogl_material_set_diffuse:
 314  * @material: A #CoglMaterial object
 315  * @diffuse: The components of the desired diffuse color
 316  *
 317  * Sets the material's diffuse color, in the standard OpenGL lighting
 318  * model. The diffuse color is most intense where the light hits the
 319  * surface directly - perpendicular to the surface.
 320  *
 321  * The default value is (0.8, 0.8, 0.8, 1.0)
 322  *
 323  * Since: 1.0
 324  */
 325 void
 326 cogl_material_set_diffuse (CoglMaterial    *material,
 327                            const CoglColor *diffuse);
 328
 329 /**
 330  * cogl_material_get_diffuse:
 331  * @material: A #CoglMaterial object
 332  * @diffuse: The location to store the diffuse color
 333  *
 334  * Retrieves the current diffuse color for @material
 335  *
 336  * Since: 1.0
 337  */
 338 void
 339 cogl_material_get_diffuse (CoglMaterial *material,
 340                            CoglColor    *diffuse);
 341
 342 /**
 343  * cogl_material_set_ambient_and_diffuse:
 344  * @material: A #CoglMaterial object
 345  * @color: The components of the desired ambient and diffuse colors
 346  *
 347  * Conveniently sets the diffuse and ambient color of @material at the same
 348  * time. See cogl_material_set_ambient() and cogl_material_set_diffuse().
 349  *
 350  * The default ambient color is (0.2, 0.2, 0.2, 1.0)
 351  *
 352  * The default diffuse color is (0.8, 0.8, 0.8, 1.0)
 353  *
 354  * Since: 1.0
 355  */
 356 void
 357 cogl_material_set_ambient_and_diffuse (CoglMaterial    *material,
 358                                        const CoglColor *color);
 359
 360 /**
 361  * cogl_material_set_specular:
 362  * @material: A #CoglMaterial object
 363  * @specular: The components of the desired specular color
 364  *
 365  * Sets the material's specular color, in the standard OpenGL lighting
 366  * model. The intensity of the specular color depends on the viewport
 367  * position, and is brightest along the lines of reflection.
 368  *
 369  * The default value is (0.0, 0.0, 0.0, 1.0)
 370  *
 371  * Since: 1.0
 372  */
 373 void
 374 cogl_material_set_specular (CoglMaterial    *material,
 375                             const CoglColor *specular);
 376
 377 /**
 378  * cogl_material_get_specular:
 379  * @material: A #CoglMaterial object
 380  * @specular: The location to store the specular color
 381  *
 382  * Retrieves the materials current specular color.
 383  *
 384  * Since: 1.0
 385  */
 386 void
 387 cogl_material_get_specular (CoglMaterial *material,
 388                             CoglColor    *specular);
 389
 390 /**
 391  * cogl_material_set_shininess:
 392  * @material: A #CoglMaterial object
 393  * @shininess: The desired shininess; must be >= 0.0
 394  *
 395  * Sets the shininess of the material, in the standard OpenGL lighting
 396  * model, which determines the size of the specular highlights. A
 397  * higher @shininess will produce smaller highlights which makes the
 398  * object appear more shiny.
 399  *
 400  * The default value is 0.0
 401  *
 402  * Since: 1.0
 403  */
 404 void
 405 cogl_material_set_shininess (CoglMaterial *material,
 406                              float         shininess);
 407
 408 /**
 409  * cogl_material_get_shininess:
 410  * @material: A #CoglMaterial object
 411  *
 412  * Retrieves the materials current emission color.
 413  *
 414  * Return value: The materials current shininess value
 415  *
 416  * Since: 1.0
 417  */
 418 float
 419 cogl_material_get_shininess (CoglMaterial *material);
 420
 421 /**
 422  * cogl_material_set_emission:
 423  * @material: A #CoglMaterial object
 424  * @emission: The components of the desired emissive color
 425  *
 426  * Sets the material's emissive color, in the standard OpenGL lighting
 427  * model. It will look like the surface is a light source emitting this
 428  * color.
 429  *
 430  * The default value is (0.0, 0.0, 0.0, 1.0)
 431  *
 432  * Since: 1.0
 433  */
 434 void
 435 cogl_material_set_emission (CoglMaterial    *material,
 436                             const CoglColor *emission);
 437
 438 /**
 439  * cogl_material_get_emission:
 440  * @material: A #CoglMaterial object
 441  * @emission: The location to store the emission color
 442  *
 443  * Retrieves the materials current emission color.
 444  *
 445  * Since: 1.0
 446  */
 447 void
 448 cogl_material_get_emission (CoglMaterial *material,
 449                             CoglColor    *emission);
 450
 451 /**
 452  * CoglMaterialAlphaFunc:
 453  * @COGL_MATERIAL_ALPHA_FUNC_NEVER: Never let the fragment through.
 454  * @COGL_MATERIAL_ALPHA_FUNC_LESS: Let the fragment through if the incoming
 455  *   alpha value is less than the reference alpha value
 456  * @COGL_MATERIAL_ALPHA_FUNC_EQUAL: Let the fragment through if the incoming
 457  *   alpha value equals the reference alpha value
 458  * @COGL_MATERIAL_ALPHA_FUNC_LEQUAL: Let the fragment through if the incoming
 459  *   alpha value is less than or equal to the reference alpha value
 460  * @COGL_MATERIAL_ALPHA_FUNC_GREATER: Let the fragment through if the incoming
 461  *   alpha value is greater than the reference alpha value
 462  * @COGL_MATERIAL_ALPHA_FUNC_NOTEQUAL: Let the fragment through if the incoming
 463  *   alpha value does not equal the reference alpha value
 464  * @COGL_MATERIAL_ALPHA_FUNC_GEQUAL: Let the fragment through if the incoming
 465  *   alpha value is greater than or equal to the reference alpha value.
 466  * @COGL_MATERIAL_ALPHA_FUNC_ALWAYS: Always let the fragment through.
 467  *
 468  * Alpha testing happens before blending primitives with the framebuffer and
 469  * gives an opportunity to discard fragments based on a comparison with the
 470  * incoming alpha value and a reference alpha value. The #CoglMaterialAlphaFunc
 471  * determines how the comparison is done.
 472  */
 473 typedef enum {
 474   COGL_MATERIAL_ALPHA_FUNC_NEVER    = 0x0200,
 475   COGL_MATERIAL_ALPHA_FUNC_LESS     = 0x0201,
 476   COGL_MATERIAL_ALPHA_FUNC_EQUAL    = 0x0202,
 477   COGL_MATERIAL_ALPHA_FUNC_LEQUAL   = 0x0203,
 478   COGL_MATERIAL_ALPHA_FUNC_GREATER  = 0x0204,
 479   COGL_MATERIAL_ALPHA_FUNC_NOTEQUAL = 0x0205,
 480   COGL_MATERIAL_ALPHA_FUNC_GEQUAL   = 0x0206,
 481   COGL_MATERIAL_ALPHA_FUNC_ALWAYS   = 0x0207
 482 } CoglMaterialAlphaFunc;
 483
 484 /**
 485  * cogl_material_set_alpha_test_function:
 486  * @material: A #CoglMaterial object
 487  * @alpha_func: A @CoglMaterialAlphaFunc constant
 488  * @alpha_reference: A reference point that the chosen alpha function uses
 489  *   to compare incoming fragments to.
 490  *
 491  * Before a primitive is blended with the framebuffer, it goes through an
 492  * alpha test stage which lets you discard fragments based on the current
 493  * alpha value. This function lets you change the function used to evaluate
 494  * the alpha channel, and thus determine which fragments are discarded
 495  * and which continue on to the blending stage.
 496  *
 497  * The default is %COGL_MATERIAL_ALPHA_FUNC_ALWAYS
 498  *
 499  * Since: 1.0
 500  */
 501 void
 502 cogl_material_set_alpha_test_function (CoglMaterial         *material,
 503                                        CoglMaterialAlphaFunc alpha_func,
 504                                        float                 alpha_reference);
 505
 506 /**
 507  * cogl_material_set_blend:
 508  * @material: A #CoglMaterial object
 509  * @blend_string: A <link linkend="cogl-Blend-Strings">Cogl blend string</link>
 510  *   describing the desired blend function.
 511  * @error: return location for a #GError that may report lack of driver
 512  *   support if you give separate blend string statements for the alpha
 513  *   channel and RGB channels since some drivers, or backends such as
 514  *   GLES 1.1, don't support this feature. May be %NULL, in which case a
 515  *   warning will be printed out using GLib's logging facilities if an
 516  *   error is encountered.
 517  *
 518  * If not already familiar; please refer <link linkend="cogl-Blend-Strings">here</link>
 519  * for an overview of what blend strings are, and their syntax.
 520  *
 521  * Blending occurs after the alpha test function, and combines fragments with
 522  * the framebuffer.
 523
 524  * Currently the only blend function Cogl exposes is ADD(). So any valid
 525  * blend statements will be of the form:
 526  *
 527  * |[
 528  *   &lt;channel-mask&gt;=ADD(SRC_COLOR*(&lt;factor&gt;), DST_COLOR*(&lt;factor&gt;))
 529  * ]|
 530  *
 531  * <warning>The brackets around blend factors are currently not
 532  * optional!</warning>
 533  *
 534  * This is the list of source-names usable as blend factors:
 535  * <itemizedlist>
 536  *   <listitem><para>SRC_COLOR: The color of the in comming fragment</para></listitem>
 537  *   <listitem><para>DST_COLOR: The color of the framebuffer</para></listitem>
 538  *   <listitem><para>CONSTANT: The constant set via cogl_material_set_blend_constant()</para></listitem>
 539  * </itemizedlist>
 540  *
 541  * The source names can be used according to the
 542  * <link linkend="cogl-Blend-String-syntax">color-source and factor syntax</link>,
 543  * so for example "(1-SRC_COLOR[A])" would be a valid factor, as would
 544  * "(CONSTANT[RGB])"
 545  *
 546  * These can also be used as factors:
 547  * <itemizedlist>
 548  *   <listitem>0: (0, 0, 0, 0)</listitem>
 549  *   <listitem>1: (1, 1, 1, 1)</listitem>
 550  *   <listitem>SRC_ALPHA_SATURATE_FACTOR: (f,f,f,1) where f = MIN(SRC_COLOR[A],1-DST_COLOR[A])</listitem>
 551  * </itemizedlist>
 552  *
 553  * <note>Remember; all color components are normalized to the range [0, 1]
 554  * before computing the result of blending.</note>
 555  *
 556  * <example id="cogl-Blend-Strings-blend-unpremul">
 557  *   <title>Blend Strings/1</title>
 558  *   <para>Blend a non-premultiplied source over a destination with
 559  *   premultiplied alpha:</para>
 560  *   <programlisting>
 561  * "RGB = ADD(SRC_COLOR*(SRC_COLOR[A]), DST_COLOR*(1-SRC_COLOR[A]))"
 562  * "A   = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
 563  *   </programlisting>
 564  * </example>
 565  *
 566  * <example id="cogl-Blend-Strings-blend-premul">
 567  *   <title>Blend Strings/2</title>
 568  *   <para>Blend a premultiplied source over a destination with
 569  *   premultiplied alpha</para>
 570  *   <programlisting>
 571  * "RGBA = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
 572  *   </programlisting>
 573  * </example>
 574  *
 575  * The default blend string is:
 576  * |[
 577  *    RGBA = ADD (SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))
 578  * ]|
 579  *
 580  * That gives normal alpha-blending when the calculated color for the material
 581  * is in premultiplied form.
 582  *
 583  * Return value: %TRUE if the blend string was successfully parsed, and the
 584  *   described blending is supported by the underlying driver/hardware. If
 585  *   there was an error, %FALSE is returned and @error is set accordingly (if
 586  *   present).
 587  *
 588  * Since: 1.0
 589  */
 590 gboolean
 591 cogl_material_set_blend (CoglMaterial *material,
 592                          const char   *blend_string,
 593                          GError      **error);
 594
 595 /**
 596  * cogl_material_set_blend_constant:
 597  * @material: A #CoglMaterial object
 598  * @constant_color: The constant color you want
 599  *
 600  * When blending is setup to reference a CONSTANT blend factor then
 601  * blending will depend on the constant set with this function.
 602  *
 603  * Since: 1.0
 604  */
 605 void
 606 cogl_material_set_blend_constant (CoglMaterial *material,
 607                                   const CoglColor *constant_color);
 608
 609 /**
 610  * cogl_material_set_point_size:
 611  * @material: a material.
 612  * @point_size: the new point size.
 613  *
 614  * Changes the size of points drawn when %COGL_VERTICES_MODE_POINTS is
 615  * used with the vertex buffer API. Note that typically the GPU will
 616  * only support a limited minimum and maximum range of point sizes. If
 617  * the chosen point size is outside that range then the nearest value
 618  * within that range will be used instead. The size of a point is in
 619  * screen space so it will be the same regardless of any
 620  * transformations. The default point size is 1.0.
 621  *
 622  * Since: 1.4
 623  */
 624 void
 625 cogl_material_set_point_size (CoglMaterial *material,
 626                               float         point_size);
 627
 628 /**
 629  * cogl_material_get_point_size:
 630  * @material: a #CoglHandle to a material.
 631  *
 632  * Get the size of points drawn when %COGL_VERTICES_MODE_POINTS is
 633  * used with the vertex buffer API.
 634  *
 635  * Return value: the point size of the material.
 636  *
 637  * Since: 1.4
 638  */
 639 float
 640 cogl_material_get_point_size (CoglMaterial *material);
 641
 642 /**
 643  * cogl_material_get_user_program:
 644  * @material: a #CoglMaterial object.
 645  *
 646  * Queries what user program has been associated with the given
 647  * @material using cogl_material_set_user_program().
 648  *
 649  * Return value: (transfer none): The current user program
 650  *   or %COGL_INVALID_HANDLE.
 651  *
 652  * Since: 1.4
 653  */
 654 CoglHandle
 655 cogl_material_get_user_program (CoglMaterial *material);
 656
 657 /**
 658  * cogl_material_set_user_program:
 659  * @material: a #CoglMaterial object.
 660  * @program: A #CoglHandle to a linked CoglProgram
 661  *
 662  * Associates a linked CoglProgram with the given material so that the
 663  * program can take full control of vertex and/or fragment processing.
 664  *
 665  * This is an example of how it can be used to associate an ARBfp
 666  * program with a #CoglMaterial:
 667  * |[
 668  * CoglHandle shader;
 669  * CoglHandle program;
 670  * CoglMaterial *material;
 671  *
 672  * shader = cogl_create_shader (COGL_SHADER_TYPE_FRAGMENT);
 673  * cogl_shader_source (shader,
 674  *                     "!!ARBfp1.0\n"
 675  *                     "MOV result.color,fragment.color;\n"
 676  *                     "END\n");
 677  * cogl_shader_compile (shader);
 678  *
 679  * program = cogl_create_program ();
 680  * cogl_program_attach_shader (program, shader);
 681  * cogl_program_link (program);
 682  *
 683  * material = cogl_material_new ();
 684  * cogl_material_set_user_program (material, program);
 685  *
 686  * cogl_set_source_color4ub (0xff, 0x00, 0x00, 0xff);
 687  * cogl_rectangle (0, 0, 100, 100);
 688  * ]|
 689  *
 690  * It is possibly worth keeping in mind that this API is not part of
 691  * the long term design for how we want to expose shaders to Cogl
 692  * developers (We are planning on deprecating the cogl_program and
 693  * cogl_shader APIs in favour of a "snippet" framework) but in the
 694  * meantime we hope this will handle most practical GLSL and ARBfp
 695  * requirements.
 696  *
 697  * Also remember you need to check for either the
 698  * %COGL_FEATURE_SHADERS_GLSL or %COGL_FEATURE_SHADERS_ARBFP before
 699  * using the cogl_program or cogl_shader API.
 700  *
 701  * Since: 1.4
 702  */
 703 void
 704 cogl_material_set_user_program (CoglMaterial *material,
 705                                 CoglHandle program);
 706
 707 /**
 708  * cogl_material_set_layer:
 709  * @material: A #CoglMaterial object
 710  * @layer_index: the index of the layer
 711  * @texture: a #CoglHandle for the layer object
 712  *
 713  * In addition to the standard OpenGL lighting model a Cogl material may have
 714  * one or more layers comprised of textures that can be blended together in
 715  * order, with a number of different texture combine modes. This function
 716  * defines a new texture layer.
 717  *
 718  * The index values of multiple layers do not have to be consecutive; it is
 719  * only their relative order that is important.
 720  *
 721  * <note>In the future, we may define other types of material layers, such
 722  * as purely GLSL based layers.</note>
 723  *
 724  * Since: 1.0
 725  */
 726 void
 727 cogl_material_set_layer (CoglMaterial *material,
 728                          int           layer_index,
 729                          CoglHandle    texture);
 730
 731 /**
 732  * cogl_material_remove_layer:
 733  * @material: A #CoglMaterial object
 734  * @layer_index: Specifies the layer you want to remove
 735  *
 736  * This function removes a layer from your material
 737  */
 738 void
 739 cogl_material_remove_layer (CoglMaterial *material,
 740                             int           layer_index);
 741
 742
 743 /**
 744  * cogl_material_set_layer_combine:
 745  * @material: A #CoglMaterial object
 746  * @layer_index: Specifies the layer you want define a combine function for
 747  * @blend_string: A <link linkend="cogl-Blend-Strings">Cogl blend string</link>
 748  *    describing the desired texture combine function.
 749  * @error: A #GError that may report parse errors or lack of GPU/driver
 750  *   support. May be %NULL, in which case a warning will be printed out if an
 751  *   error is encountered.
 752  *
 753  * If not already familiar; you can refer
 754  * <link linkend="cogl-Blend-Strings">here</link> for an overview of what blend
 755  * strings are and there syntax.
 756  *
 757  * These are all the functions available for texture combining:
 758  * <itemizedlist>
 759  *   <listitem>REPLACE(arg0) = arg0</listitem>
 760  *   <listitem>MODULATE(arg0, arg1) = arg0 x arg1</listitem>
 761  *   <listitem>ADD(arg0, arg1) = arg0 + arg1</listitem>
 762  *   <listitem>ADD_SIGNED(arg0, arg1) = arg0 + arg1 - 0.5</listitem>
 763  *   <listitem>INTERPOLATE(arg0, arg1, arg2) = arg0 x arg2 + arg1 x (1 - arg2)</listitem>
 764  *   <listitem>SUBTRACT(arg0, arg1) = arg0 - arg1</listitem>
 765  *   <listitem>
 766  *     <programlisting>
 767  *  DOT3_RGB(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
 768  *                              (arg0[G] - 0.5)) * (arg1[G] - 0.5) +
 769  *                              (arg0[B] - 0.5)) * (arg1[B] - 0.5))
 770  *     </programlisting>
 771  *   </listitem>
 772  *   <listitem>
 773  *     <programlisting>
 774  *  DOT3_RGBA(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
 775  *                               (arg0[G] - 0.5)) * (arg1[G] - 0.5) +
 776  *                               (arg0[B] - 0.5)) * (arg1[B] - 0.5))
 777  *     </programlisting>
 778  *   </listitem>
 779  * </itemizedlist>
 780  *
 781  * Refer to the
 782  * <link linkend="cogl-Blend-String-syntax">color-source syntax</link> for
 783  * describing the arguments. The valid source names for texture combining
 784  * are:
 785  * <variablelist>
 786  *   <varlistentry>
 787  *     <term>TEXTURE</term>
 788  *     <listitem>Use the color from the current texture layer</listitem>
 789  *   </varlistentry>
 790  *   <varlistentry>
 791  *     <term>TEXTURE_0, TEXTURE_1, etc</term>
 792  *     <listitem>Use the color from the specified texture layer</listitem>
 793  *   </varlistentry>
 794  *   <varlistentry>
 795  *     <term>CONSTANT</term>
 796  *     <listitem>Use the color from the constant given with
 797  *     cogl_material_set_layer_constant()</listitem>
 798  *   </varlistentry>
 799  *   <varlistentry>
 800  *     <term>PRIMARY</term>
 801  *     <listitem>Use the color of the material as set with
 802  *     cogl_material_set_color()</listitem>
 803  *   </varlistentry>
 804  *   <varlistentry>
 805  *     <term>PREVIOUS</term>
 806  *     <listitem>Either use the texture color from the previous layer, or
 807  *     if this is layer 0, use the color of the material as set with
 808  *     cogl_material_set_color()</listitem>
 809  *   </varlistentry>
 810  * </variablelist>
 811  *
 812  * <refsect2 id="cogl-Layer-Combine-Examples">
 813  *   <title>Layer Combine Examples</title>
 814  *   <para>This is effectively what the default blending is:</para>
 815  *   <informalexample><programlisting>
 816  *   RGBA = MODULATE (PREVIOUS, TEXTURE)
 817  *   </programlisting></informalexample>
 818  *   <para>This could be used to cross-fade between two images, using
 819  *   the alpha component of a constant as the interpolator. The constant
 820  *   color is given by calling cogl_material_set_layer_constant.</para>
 821  *   <informalexample><programlisting>
 822  *   RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
 823  *   </programlisting></informalexample>
 824  * </refsect2>
 825  *
 826  * <note>You can't give a multiplication factor for arguments as you can
 827  * with blending.</note>
 828  *
 829  * Return value: %TRUE if the blend string was successfully parsed, and the
 830  *   described texture combining is supported by the underlying driver and
 831  *   or hardware. On failure, %FALSE is returned and @error is set
 832  *
 833  * Since: 1.0
 834  */
 835 gboolean
 836 cogl_material_set_layer_combine (CoglMaterial *material,
 837                                  int           layer_index,
 838                                  const char   *blend_string,
 839                                  GError      **error);
 840
 841 /**
 842  * cogl_material_set_layer_combine_constant:
 843  * @material: A #CoglMaterial object
 844  * @layer_index: Specifies the layer you want to specify a constant used
 845  *               for texture combining
 846  * @constant: The constant color you want
 847  *
 848  * When you are using the 'CONSTANT' color source in a layer combine
 849  * description then you can use this function to define its value.
 850  *
 851  * Since: 1.0
 852  */
 853 void
 854 cogl_material_set_layer_combine_constant (CoglMaterial    *material,
 855                                           int              layer_index,
 856                                           const CoglColor *constant);
 857
 858 /**
 859  * cogl_material_set_layer_matrix:
 860  * @material: A #CoglMaterial object
 861  * @layer_index: the index for the layer inside @material
 862  * @matrix: the transformation matrix for the layer
 863  *
 864  * This function lets you set a matrix that can be used to e.g. translate
 865  * and rotate a single layer of a material used to fill your geometry.
 866  */
 867 void
 868 cogl_material_set_layer_matrix (CoglMaterial     *material,
 869                                 int               layer_index,
 870                                 const CoglMatrix *matrix);
 871
 872 /**
 873  * cogl_material_get_layers:
 874  * @material: A #CoglMaterial object
 875  *
 876  * This function lets you access a material's internal list of layers
 877  * for iteration.
 878  *
 879  * <note>You should avoid using this API if possible since it was only
 880  * made public by mistake and will be deprecated when we have
 881  * suitable alternative.</note>
 882  *
 883  * <note>It's important to understand that the list returned may not
 884  * remain valid if you modify the material or any of the layers in any
 885  * way and so you would have to re-get the list in that
 886  * situation.</note>
 887  *
 888  * Return value: (element-type CoglMaterialLayer) (transfer none): A
 889  *    list of #CoglMaterialLayer<!-- -->'s that can be passed to the
 890  *    cogl_material_layer_* functions. The list is owned by Cogl and it
 891  *    should not be modified or freed
 892  */
 893 const GList *
 894 cogl_material_get_layers (CoglMaterial *material);
 895
 896 /**
 897  * cogl_material_get_n_layers:
 898  * @material: A #CoglMaterial object
 899  *
 900  * Retrieves the number of layers defined for the given @material
 901  *
 902  * Return value: the number of layers
 903  *
 904  * Since: 1.0
 905  */
 906 int
 907 cogl_material_get_n_layers (CoglMaterial *material);
 908
 909 /**
 910  * CoglMaterialLayerType:
 911  * @COGL_MATERIAL_LAYER_TYPE_TEXTURE: The layer represents a
 912  *   <link linkend="cogl-Textures">texture</link>
 913  *
 914  * Available types of layers for a #CoglMaterial. This enumeration
 915  * might be expanded in later versions.
 916  *
 917  * Since: 1.0
 918  */
 919 typedef enum {
 920   COGL_MATERIAL_LAYER_TYPE_TEXTURE
 921 } CoglMaterialLayerType;
 922
 923
 924 /**
 925  * cogl_material_layer_get_type:
 926  * @layer: A #CoglMaterialLayer object
 927  *
 928  * Retrieves the type of the layer
 929  *
 930  * Currently there is only one type of layer defined:
 931  * %COGL_MATERIAL_LAYER_TYPE_TEXTURE, but considering we may add purely GLSL
 932  * based layers in the future, you should write code that checks the type
 933  * first.
 934  *
 935  * Return value: the type of the layer
 936  */
 937 CoglMaterialLayerType
 938 cogl_material_layer_get_type (CoglMaterialLayer *layer);
 939
 940 /**
 941  * cogl_material_layer_get_texture:
 942  * @layer: A #CoglMaterialLayer object
 943  *
 944  * Extracts a texture handle for a specific layer.
 945  *
 946  * <note>In the future Cogl may support purely GLSL based layers; for those
 947  * layers this function which will likely return %COGL_INVALID_HANDLE if you
 948  * try to get the texture handle from them. Considering this scenario, you
 949  * should call cogl_material_layer_get_type() first in order check it is of
 950  * type %COGL_MATERIAL_LAYER_TYPE_TEXTURE before calling this function.</note>
 951  *
 952  * Return value: (transfer none): a #CoglHandle for the texture inside the layer
 953  */
 954 CoglHandle
 955 cogl_material_layer_get_texture (CoglMaterialLayer *layer);
 956
 957 /**
 958  * cogl_material_layer_get_min_filter:
 959  * @layer: a #CoglHandle for a material layer
 960  *
 961  * Queries the currently set downscaling filter for a material layer
 962  *
 963  * Return value: the current downscaling filter
 964  */
 965 CoglMaterialFilter
 966 cogl_material_layer_get_min_filter (CoglMaterialLayer *layer);
 967
 968 /**
 969  * cogl_material_layer_get_mag_filter:
 970  * @layer: A #CoglMaterialLayer object
 971  *
 972  * Queries the currently set downscaling filter for a material later
 973  *
 974  * Return value: the current downscaling filter
 975  */
 976 CoglMaterialFilter
 977 cogl_material_layer_get_mag_filter (CoglMaterialLayer *layer);
 978
 979 /**
 980  * cogl_material_set_layer_filters:
 981  * @material: A #CoglMaterial object
 982  * @layer_index: the layer number to change.
 983  * @min_filter: the filter used when scaling a texture down.
 984  * @mag_filter: the filter used when magnifying a texture.
 985  *
 986  * Changes the decimation and interpolation filters used when a texture is
 987  * drawn at other scales than 100%.
 988  */
 989 void
 990 cogl_material_set_layer_filters (CoglMaterial      *material,
 991                                  int                layer_index,
 992                                  CoglMaterialFilter min_filter,
 993                                  CoglMaterialFilter mag_filter);
 994
 995 /**
 996  * cogl_material_set_layer_point_sprite_coords_enabled:
 997  * @material: a #CoglHandle to a material.
 998  * @layer_index: the layer number to change.
 999  * @enable: whether to enable point sprite coord generation.
1000  * @error: A return location for a GError, or NULL to ignore errors.
1001  *
1002  * When rendering points, if @enable is %TRUE then the texture
1003  * coordinates for this layer will be replaced with coordinates that
1004  * vary from 0.0 to 1.0 across the primitive. The top left of the
1005  * point will have the coordinates 0.0,0.0 and the bottom right will
1006  * have 1.0,1.0. If @enable is %FALSE then the coordinates will be
1007  * fixed for the entire point.
1008  *
1009  * This function will only work if %COGL_FEATURE_POINT_SPRITE is
1010  * available. If the feature is not available then the function will
1011  * return %FALSE and set @error.
1012  *
1013  * Return value: %TRUE if the function succeeds, %FALSE otherwise.
1014  * Since: 1.4
1015  */
1016 gboolean
1017 cogl_material_set_layer_point_sprite_coords_enabled (CoglMaterial *material,
1018                                                      int           layer_index,
1019                                                      gboolean      enable,
1020                                                      GError      **error);
1021
1022 /**
1023  * cogl_material_get_layer_point_sprite_coords_enabled:
1024  * @material: a #CoglHandle to a material.
1025  * @layer_index: the layer number to check.
1026  *
1027  * Gets whether point sprite coordinate generation is enabled for this
1028  * texture layer.
1029  *
1030  * Return value: whether the texture coordinates will be replaced with
1031  * point sprite coordinates.
1032  *
1033  * Since: 1.4
1034  */
1035 gboolean
1036 cogl_material_get_layer_point_sprite_coords_enabled (CoglMaterial *material,
1037                                                      int           layer_index);
1038
1039 /**
1040  * cogl_material_get_layer_wrap_mode_s:
1041  * @material: A #CoglMaterial object
1042  * @layer_index: the layer number to change.
1043  *
1044  * Returns the wrap mode for the 's' coordinate of texture lookups on this
1045  * layer.
1046  *
1047  * Return value: the wrap mode for the 's' coordinate of texture lookups on
1048  * this layer.
1049  *
1050  * Since: 1.6
1051  */
1052 CoglMaterialWrapMode
1053 cogl_material_get_layer_wrap_mode_s (CoglMaterial *material,
1054                                      int           layer_index);
1055
1056 /**
1057  * cogl_material_set_layer_wrap_mode_s:
1058  * @material: A #CoglMaterial object
1059  * @layer_index: the layer number to change.
1060  * @mode: the new wrap mode
1061  *
1062  * Sets the wrap mode for the 's' coordinate of texture lookups on this layer.
1063  *
1064  * Since: 1.4
1065  */
1066 void
1067 cogl_material_set_layer_wrap_mode_s (CoglMaterial        *material,
1068                                      int                  layer_index,
1069                                      CoglMaterialWrapMode mode);
1070
1071 /**
1072  * cogl_material_get_layer_wrap_mode_t:
1073  * @material: A #CoglMaterial object
1074  * @layer_index: the layer number to change.
1075  *
1076  * Returns the wrap mode for the 't' coordinate of texture lookups on this
1077  * layer.
1078  *
1079  * Return value: the wrap mode for the 't' coordinate of texture lookups on
1080  * this layer.
1081  *
1082  * Since: 1.6
1083  */
1084 CoglMaterialWrapMode
1085 cogl_material_get_layer_wrap_mode_t (CoglMaterial *material,
1086                                      int           layer_index);
1087
1088
1089 /**
1090  * cogl_material_set_layer_wrap_mode_t:
1091  * @material: A #CoglMaterial object
1092  * @layer_index: the layer number to change.
1093  * @mode: the new wrap mode
1094  *
1095  * Sets the wrap mode for the 't' coordinate of texture lookups on this layer.
1096  *
1097  * Since: 1.4
1098  */
1099 void
1100 cogl_material_set_layer_wrap_mode_t (CoglMaterial        *material,
1101                                      int                  layer_index,
1102                                      CoglMaterialWrapMode mode);
1103
1104 /**
1105  * cogl_material_get_layer_wrap_mode_p:
1106  * @material: A #CoglMaterial object
1107  * @layer_index: the layer number to change.
1108  *
1109  * Returns the wrap mode for the 'p' coordinate of texture lookups on this
1110  * layer.
1111  *
1112  * Return value: the wrap mode for the 'p' coordinate of texture lookups on
1113  * this layer.
1114  *
1115  * Since: 1.6
1116  */
1117 CoglMaterialWrapMode
1118 cogl_material_get_layer_wrap_mode_p (CoglMaterial *material,
1119                                      int           layer_index);
1120
1121 /**
1122  * cogl_material_set_layer_wrap_mode_p:
1123  * @material: A #CoglMaterial object
1124  * @layer_index: the layer number to change.
1125  * @mode: the new wrap mode
1126  *
1127  * Sets the wrap mode for the 'p' coordinate of texture lookups on
1128  * this layer. 'p' is the third coordinate.
1129  *
1130  * Since: 1.4
1131  */
1132 void
1133 cogl_material_set_layer_wrap_mode_p (CoglMaterial        *material,
1134                                      int                  layer_index,
1135                                      CoglMaterialWrapMode mode);
1136
1137 /**
1138  * cogl_material_set_layer_wrap_mode:
1139  * @material: A #CoglMaterial object
1140  * @layer_index: the layer number to change.
1141  * @mode: the new wrap mode
1142  *
1143  * Sets the wrap mode for all three coordinates of texture lookups on
1144  * this layer. This is equivalent to calling
1145  * cogl_material_set_layer_wrap_mode_s(),
1146  * cogl_material_set_layer_wrap_mode_t() and
1147  * cogl_material_set_layer_wrap_mode_p() separately.
1148  *
1149  * Since: 1.4
1150  */
1151 void
1152 cogl_material_set_layer_wrap_mode (CoglMaterial        *material,
1153                                    int                  layer_index,
1154                                    CoglMaterialWrapMode mode);
1155
1156 /**
1157  * cogl_material_layer_get_wrap_mode_s:
1158  * @layer: A #CoglMaterialLayer object
1159  *
1160  * Gets the wrap mode for the 's' coordinate of texture lookups on this layer.
1161  *
1162  * Return value: the wrap mode value for the s coordinate.
1163  *
1164  * Since: 1.4
1165  */
1166 CoglMaterialWrapMode
1167 cogl_material_layer_get_wrap_mode_s (CoglMaterialLayer *layer);
1168
1169 /**
1170  * cogl_material_layer_get_wrap_mode_t:
1171  * @layer: A #CoglMaterialLayer object
1172  *
1173  * Gets the wrap mode for the 't' coordinate of texture lookups on this layer.
1174  *
1175  * Return value: the wrap mode value for the t coordinate.
1176  *
1177  * Since: 1.4
1178  */
1179 CoglMaterialWrapMode
1180 cogl_material_layer_get_wrap_mode_t (CoglMaterialLayer *layer);
1181
1182 /**
1183  * cogl_material_layer_get_wrap_mode_p:
1184  * @layer: A #CoglMaterialLayer object
1185  *
1186  * Gets the wrap mode for the 'p' coordinate of texture lookups on
1187  * this layer. 'p' is the third coordinate.
1188  *
1189  * Return value: the wrap mode value for the p coordinate.
1190  *
1191  * Since: 1.4
1192  */
1193 CoglMaterialWrapMode
1194 cogl_material_layer_get_wrap_mode_p (CoglMaterialLayer *layer);
1195
1196 #ifdef COGL_ENABLE_EXPERIMENTAL_API
1197
1198 /**
1199  * cogl_material_set_depth_state:
1200  * @material: A #CoglMaterial object
1201  * @state: A #CoglDepthState struct
1202  * @error: A #GError to report failures to setup the given @state.
1203  *
1204  * This commits all the depth state configured in @state struct to the
1205  * given @material. The configuration values are copied into the
1206  * material so there is no requirement to keep the #CoglDepthState
1207  * struct around if you don't need it any more.
1208  *
1209  * Note: Since some platforms do not support the depth range feature
1210  * it is possible for this function to fail and report an @error.
1211  *
1212  * Returns: TRUE if the GPU supports all the given @state else %FALSE
1213  *          and returns an @error.
1214  *
1215  * Since: 1.8
1216  * Stability: Unstable
1217  */
1218 gboolean
1219 cogl_material_set_depth_state (CoglMaterial *material,
1220                                const CoglDepthState *state,
1221                                GError **error);
1222
1223 /**
1224  * cogl_material_get_depth_state:
1225  * @material: A #CoglMaterial object
1226  * @state_out: A destination #CoglDepthState struct
1227  *
1228  * Retrieves the current depth state configuration for the given
1229  * @pipeline as previously set using cogl_pipeline_set_depth_state().
1230  *
1231  * Since: 2.0
1232  * Stability: Unstable
1233  */
1234 void
1235 cogl_material_get_depth_state (CoglMaterial *material,
1236                                CoglDepthState *state_out);
1237
1238 /**
1239  * CoglMaterialLayerCallback:
1240  * @material: The #CoglMaterial whos layers are being iterated
1241  * @layer_index: The current layer index
1242  * @user_data: The private data passed to cogl_material_foreach_layer()
1243  *
1244  * The callback prototype used with cogl_material_foreach_layer() for
1245  * iterating all the layers of a @material.
1246  *
1247  * Since: 1.4
1248  * Stability: Unstable
1249  */
1250 typedef gboolean (*CoglMaterialLayerCallback) (CoglMaterial *material,
1251                                                int layer_index,
1252                                                void *user_data);
1253
1254 /**
1255  * cogl_material_foreach_layer:
1256  * @material: A #CoglMaterial object
1257  * @callback: A #CoglMaterialLayerCallback to be called for each layer
1258  *            index
1259  * @user_data: Private data that will be passed to the callback
1260  *
1261  * Iterates all the layer indices of the given @material.
1262  *
1263  * Since: 1.4
1264  * Stability: Unstable
1265  */
1266 void
1267 cogl_material_foreach_layer (CoglMaterial *material,
1268                              CoglMaterialLayerCallback callback,
1269                              void *user_data);
1270
1271 #endif /* COGL_ENABLE_EXPERIMENTAL_API */
1272
1273 G_END_DECLS
1274
1275 #endif /* __COGL_MATERIAL_H__ */