Clutter::Cogl::Material(3) A material used to fill a geometry

DESCRIPTION

COGL allows creating and manipulating materials used to fill in geometry. Materials may simply be lighting attributes (such as an ambient and diffuse colour) or might represent one or more textures blended together.

METHODS

handle = Clutter::Cogl::Material->new

Creates a new white Clutter::Cogl::Material.

$material->set_alpha_test_function ($function, $reference)

  • $function (Clutter::Cogl::MaterialAlphaFunc)
  • $reference (double)

Before a primitive is blended with the framebuffer, it goes through an alpha test stage which lets you discard fragments based on the current alpha value. This function lets you change the function used to evaluate the alpha channel, and thus determine which fragments are discarded and which continue on to the blending stage.

The default is 'always'.

(red, green, blue, alpha) = $material->get_ambient

$material->set_ambient ($color)

  • $color (array of R, G, B, A values)

Exposing the standard OpenGL lighting model; this function sets the material's ambient color. The ambient color affects the overall color of the object. Since the diffuse color will be intense when the light hits the surface directly, the ambient will most aparent where the light hits at a slant.

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

$material->set_blend_constant ($color)

  • $color (array of R, G, B, A values)

When blending is setup to reference a CONSTANT blend factor then blending will depend on the constant set with this function.

boolean = $material->set_blend ($blend_string)

  • $blend_string (string)

If not already familiar; please refer to the ``BLEND STRINGS'' section for an overview of what blend strings are and their syntax.

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!

This is the list of source-names usable as blend factors:

SRC_COLOR
The color of the in comming fragment
DST_COLOR
The color of the framebuffer
CONSTANT
The constant set via Clutter::Cogl::Material::set_blend_constant()

The source names can be used according to the color-source and factor syntax, so for example ``(1-SRC_COLOR[A])'' would be a valid factor, as would ``(CONSTANT[RGB])''.

These can also be used as factors:

0: (0, 0, 0, 0)
1: (1, 1, 1, 1)
SRC_ALPHA_SATURATE_FACTOR: (f, f, f, 1)
Where f = MIN(SRC_COLOR[A], 1 - DST_COLOR[A])

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

Examples

Blend a non-premultiplied source over a destination with premultiplied alpha:
    "RGB = ADD(SRC_COLOR*(SRC_COLOR[A]), DST_COLOR*(1-SRC_COLOR[A]))"
    "A   = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
Blend a premultiplied source over a destination with premultiplied alpha:
    "RGBA = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"

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.

May croak with a Glib::Error in $@ on failure.

(red, green, blue, alpha) = $material->get_color

$material->set_color ($color)

  • $color (array of R, G, B, A values)

Sets the basic color of the material, used when no lighting is enabled.

(red, green, blue, alpha) = $material->get_diffuse

$material->set_diffuse ($color)

  • $color (array of R, G, B, A values)

Exposing the standard OpenGL lighting model; this function sets the material's diffuse color. The diffuse color is most intense where the light hits the surface directly; perpendicular to the surface.

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

(red, green, blue, alpha) = $material->get_emission

$material->set_emission ($color)

  • $color (array of R, G, B, A values)

Exposing the standard OpenGL lighting model; this function sets the material's emissive color. It will look like the surface is a light source emitting this color.

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

$material->set_layer_combine_constant ($layer_index, $color)

  • $layer_index (integer)
  • $color (array of R, G, B, A values)

When you are using the 'CONSTANT' color source in a layer combine description then you can use this function to define its value.

boolean = $material->set_layer_combine ($layer_index, $blend_string)

  • $layer_index (integer)
  • $blend_string (string)

If not already familiar; please refer to the ``BLEND STRINGS'' section for an overview of what blend strings are and their syntax.

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) +
         (arg0[A] - 0.5) * (arg1[A] - 0.5))

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 Clutter::Cogl::Material::set_layer_constant()
PRIMARY
Use the color of the material as set with Clutter::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 Clutter::Cogl::Material::set_color()

Examples:

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 Clutter::Cogl::Material::set_layer_constant(). 

   RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])

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

May croak with a Glib::Error in $@ on failure.

$material->set_layer_filters ($layer_index, $min_filter, $mag_filter)

  • $layer_index (integer)
  • $min_filter (Clutter::Cogl::MaterialFilter)
  • $mag_filter (Clutter::Cogl::MaterialFilter)

Changes the decimation and interpolation filters used when a texture is drawn at other scales than 100%

$material->set_layer_matrix ($layer_index, $matrix)

  • $layer_index (integer)
  • $matrix (matrix)

This function lets you set a matrix that can be used to e.g. translate and rotate a single layer of a material used to fill your geometry.

$material->set_layer ($layer_index, $layer)

  • $layer_index (integer)
  • $layer (handle)

In addition to the standard OpenGL lighting model a Cogl material may have one or more layers comprised of textures that can be blended together in order, with a number of different texture combine modes. This function defines a new texture layer.

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

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

(layers) = $material->get_layers

This function lets you access a materials internal list of layers for iteration. The returned list of materials is owned by Cogl and should not be modified or freed.

integer = $material->get_n_layers

$material->remove_layer ($layer_index)

  • $layer_index (integer)

double = $material->get_shininess

$material->set_shininess ($shininess)

  • $shininess (double)

This function sets the materials shininess which determines how specular highlights are calculated. A higher shininess will produce smaller brigher highlights. The shininess parameter must be a value between 0.0 and 1.0.

The default value is 0.0.

(red, green, blue, alpha) = $material->get_specular

$material->set_specular ($color)

  • $color (array of R, G, B, A values)

Exposing the standard OpenGL lighting model; this function sets the material's specular color. The intensity of the specular color depends on the viewport position, and is brightest along the lines of reflection.

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

ENUMS AND FLAGS

enum Clutter::Cogl::MaterialAlphaFunc

  • 'never' / 'COGL_MATERIAL_ALPHA_FUNC_NEVER'
  • 'less' / 'COGL_MATERIAL_ALPHA_FUNC_LESS'
  • 'equal' / 'COGL_MATERIAL_ALPHA_FUNC_EQUAL'
  • 'lequal' / 'COGL_MATERIAL_ALPHA_FUNC_LEQUAL'
  • 'greater' / 'COGL_MATERIAL_ALPHA_FUNC_GREATER'
  • 'notequal' / 'COGL_MATERIAL_ALPHA_FUNC_NOTEQUAL'
  • 'gequal' / 'COGL_MATERIAL_ALPHA_FUNC_GEQUAL'
  • 'always' / 'COGL_MATERIAL_ALPHA_FUNC_ALWAYS'

enum Clutter::Cogl::MaterialFilter

  • 'nearest' / 'COGL_MATERIAL_FILTER_NEAREST'
  • 'linear' / 'COGL_MATERIAL_FILTER_LINEAR'
  • 'nearest-mipmap-nearest' / 'COGL_MATERIAL_FILTER_NEAREST_MIPMAP_NEAREST'
  • 'linear-mipmap-nearest' / 'COGL_MATERIAL_FILTER_LINEAR_MIPMAP_NEAREST'
  • 'nearest-mipmap-linear' / 'COGL_MATERIAL_FILTER_NEAREST_MIPMAP_LINEAR'
  • 'linear-mipmap-linear' / 'COGL_MATERIAL_FILTER_LINEAR_MIPMAP_LINEAR'

enum Clutter::Cogl::MaterialLayerType

  • 'texture' / 'COGL_MATERIAL_LAYER_TYPE_TEXTURE'

BLEND STRINGS

Describing GPU blending and texture combining states is rather awkward to do in a concise but also readable fashion. Cogl helps by supporting string based descriptions using a simple syntax.

Some Examples

The following string replaces glBlendFunc[Separate] and glBlendEquation[Separate]: 

    RGBA = ADD (SRC_COLOR * (SRC_COLOR[A]), DST_COLOR * (1-SRC_COLOR[A]))"

In this case the blend string is actually slightly more verbose than the GL counterpart: 

    glBlendFunc (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);

Though, unless you are familiar with OpenGL or refer to its API documentation you wouldn't know that the default function used by OpenGL is GL_FUNC_ADD nor would you know that the above arguments determine what the source color and destination color will be multiplied by before being adding.

The following string can be used for texture combining: 

    RGB = REPLACE (PREVIOUS)
    A = MODULATE (PREVIOUS, TEXTURE)

In OpenGL terms, it replaces glTexEnv, and the above example is equivalent to this OpenGL code: 

    glTexEnvi (GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_COMBINE);
    glTexEnvi (GL_TEXTURE_ENV, GL_COMBINE_RGB, GL_REPLACE);
    glTexEnvi (GL_TEXTURE_ENV, GL_COMBINE_ALPHA, GL_REPLACE);
    glTexEnvi (GL_TEXTURE_ENV, GL_SRC0_RGB, GL_PREVIOUS);
    glTexEnvi (GL_TEXTURE_ENV, GL_OPERAND0_RGB, GL_SRC_COLOR);
    glTexEnvi (GL_TEXTURE_ENV, GL_COMBINE_ALPHA, GL_MODULATE);
    glTexEnvi (GL_TEXTURE_ENV, GL_SRC0_RGB, GL_PREVIOUS);
    glTexEnvi (GL_TEXTURE_ENV, GL_OPERAND0_RGB, GL_SRC_COLOR);
    glTexEnvi (GL_TEXTURE_ENV, GL_SRC1_RGB, GL_TEXTURE);
    glTexEnvi (GL_TEXTURE_ENV, GL_OPERAND1_RGB, GL_SRC_COLOR);

Blend Strings Syntax

<statement>
  <channel-mask> = <function-name>(<arg-list>)

You can either use a single statement with an RGBA channel-mask or you can use two statements; one with an A channel-mask and the other with an RGB channel-mask.

<channel-mask>
  A or RGB or RGBA
<function-name>
  [A-Za-z_]*
<arg-list>
  <arg>,<arg>
  or <arg>
  or ""

I.e. functions may take 0 or more arguments

<arg>
  <color-source>
  1 - <color-source>            : Only intended for texture combining
  <color-source> * ( <factor> ) : Only intended for blending
  0                             : Only intended for blending

See the blending or texture combining sections for further notes and examples.

<color-source>
  <source-name>[<channel-mask>]
  <source-name>

See the blending or texture combining sections for the list of source-names valid in each context.

If a channel mask is not given then the channel mask of the statement is assumed instead.

<factor>
  0
  1
  <color-source>
  1 - <color-source>
  SRC_ALPHA_SATURATE

COPYRIGHT

Copyright (C) 2006, 2007, 2008 OpenedHand Ltd

Copyright (C) 2009 Intel Corporation

This module is free software; you can redistribute it and/or modify it under the terms of either:

  • the GNU Lesser General Public Library version 2.1; or
  • the Artistic License, version 2.0.

See Clutter for the full copyright notice.

LAST SEARCHED