Class Material

You should avoid using this API if possible since it was only made public by mistake and will be deprecated when we have suitable alternative.

It's important to understand that the list returned may not remain valid if you modify the material or any of the layers in any way and so you would have to re-get the list in that situation.

The default is %COGL_MATERIAL_ALPHA_FUNC_ALWAYS

Since the diffuse color will be intense when the light hits the surface directly, the ambient will be most apparent where the light hits at a slant.

The default value is (0.2, 0.2, 0.2, 1.0)

The default ambient color is (0.2, 0.2, 0.2, 1.0)

The default diffuse color is (0.8, 0.8, 0.8, 1.0)

Blending occurs after the alpha test function, and combines fragments with the framebuffer.

Currently the only blend function Cogl exposes is ADD(). So any valid blend statements will be of the form:

|[ <channel-mask>=ADD(SRC_COLOR*(<factor>), DST_COLOR*(<factor>))

<warning>The brackets around blend factors are currently not
optional!</warning>

This is the list of source-names usable as blend factors:
<itemizedlist>
  <listitem><para>SRC_COLOR: The color of the in comming fragment</para></listitem>
  <listitem><para>DST_COLOR: The color of the framebuffer</para></listitem>
  <listitem><para>CONSTANT: The constant set via cogl_material_set_blend_constant()</para></listitem>
</itemizedlist>

The source names can be used according to the
<link linkend="cogl-Blend-String-syntax">color-source and factor syntax</link>,
so for example "(1-SRC_COLOR[A])" would be a valid factor, as would
"(CONSTANT[RGB])"

These can also be used as factors:
<itemizedlist>
  <listitem>0: (0, 0, 0, 0)</listitem>
  <listitem>1: (1, 1, 1, 1)</listitem>
  <listitem>SRC_ALPHA_SATURATE_FACTOR: (f,f,f,1) where f = MIN(SRC_COLOR[A],1-DST_COLOR[A])</listitem>
</itemizedlist>

<note>Remember; all color components are normalized to the range [0, 1]
before computing the result of blending.</note>

<example id="cogl-Blend-Strings-blend-unpremul">
  <title>Blend Strings/1</title>
  <para>Blend a non-premultiplied source over a destination with
  premultiplied alpha:</para>
  <programlisting>
"RGB = ADD(SRC_COLOR*(SRC_COLOR[A]), DST_COLOR*(1-SRC_COLOR[A]))"
"A   = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
  </programlisting>
</example>

<example id="cogl-Blend-Strings-blend-premul">
  <title>Blend Strings/2</title>
  <para>Blend a premultiplied source over a destination with
  premultiplied alpha</para>
  <programlisting>
"RGBA = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
  </programlisting>
</example>

The default blend string is:
|[
   RGBA = ADD (SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))

That gives normal alpha-blending when the calculated color for the material is in premultiplied form.

Note that if you don't add any layers to the material then the color will be blended unmodified with the destination; the default blend expects premultiplied colors: for example, use (0.5, 0.0, 0.0, 0.5) for semi-transparent red. See cogl_color_premultiply().

The default value is (1.0, 1.0, 1.0, 1.0)

The default value is (1.0, 1.0, 1.0, 1.0)

The default value is (0xff, 0xff, 0xff, 0xff)

The default value is (0.8, 0.8, 0.8, 1.0)

The default value is (0.0, 0.0, 0.0, 1.0)

The index values of multiple layers do not have to be consecutive; it is only their relative order that is important.

In the future, we may define other types of material layers, such as purely GLSL based layers.

These are all the functions available for texture combining: REPLACE(arg0) = arg0 MODULATE(arg0, arg1) = arg0 x arg1 ADD(arg0, arg1) = arg0 + arg1 ADD_SIGNED(arg0, arg1) = arg0 + arg1 - 0.5 INTERPOLATE(arg0, arg1, arg2) = arg0 x arg2 + arg1 x (1 - arg2) SUBTRACT(arg0, arg1) = arg0 - arg1 DOT3_RGB(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) + (arg0[G] - 0.5)) * (arg1[G] - 0.5) + (arg0[B] - 0.5)) * (arg1[B] - 0.5)) DOT3_RGBA(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) + (arg0[G] - 0.5)) * (arg1[G] - 0.5) + (arg0[B] - 0.5)) * (arg1[B] - 0.5))

Refer to the

color-source syntax for describing the arguments. The valid source names for texture combining are: TEXTURE Use the color from the current texture layer TEXTURE_0, TEXTURE_1, etc Use the color from the specified texture layer CONSTANT Use the color from the constant given with cogl_material_set_layer_constant() PRIMARY Use the color of the material as set with cogl_material_set_color() PREVIOUS Either use the texture color from the previous layer, or if this is layer 0, use the color of the material as set with cogl_material_set_color() This is effectively what the default blending is: RGBA = MODULATE (PREVIOUS, TEXTURE) This could be used to cross-fade between two images, using the alpha component of a constant as the interpolator. The constant color is given by calling cogl_material_set_layer_constant. RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])

You can't give a multiplication factor for arguments as you can with blending.

This function will only work if %COGL_FEATURE_POINT_SPRITE is available. If the feature is not available then the function will return %FALSE and set error.

The default value is 0.0

The default value is (0.0, 0.0, 0.0, 1.0)

This is an example of how it can be used to associate an ARBfp program with a #CoglMaterial: |[ CoglHandle shader; CoglHandle program; CoglMaterial *material;

shader = cogl_create_shader (COGL_SHADER_TYPE_FRAGMENT); cogl_shader_source (shader, "!!ARBfp1.0\n" "MOV result.color,fragment.color;\n" "END\n"); cogl_shader_compile (shader);

program = cogl_create_program (); cogl_program_attach_shader (program, shader); cogl_program_link (program);

material = cogl_material_new (); cogl_material_set_user_program (material, program);

cogl_set_source_color4ub (0xff, 0x00, 0x00, 0xff); cogl_rectangle (0, 0, 100, 100);

It is possibly worth keeping in mind that this API is not part of
the long term design for how we want to expose shaders to Cogl
developers (We are planning on deprecating the cogl_program and
cogl_shader APIs in favour of a "snippet" framework) but in the
meantime we hope this will handle most practical GLSL and ARBfp
requirements.

Also remember you need to check for either the
%COGL_FEATURE_SHADERS_GLSL or %COGL_FEATURE_SHADERS_ARBFP before
using the cogl_program or cogl_shader API.
@param program A #CoglHandle to a linked CoglProgram