Clutter::Cogl::Material(3pm)

NAME

Clutter::Cogl::Material - 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): o $function (Clutter::Cogl::MaterialAlphaFunc); o $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): o $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): o $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): o $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): o $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): o $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): o $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): o $layer_index (integer); o $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): o $layer_index (integer); o $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): o $layer_index (integer); o $min_filter (Clutter::Cogl::MaterialFilter); o $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): o $layer_index (integer); o $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): o $layer_index (integer); o $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): o $layer_index (integer)
double = $material->get_shininess $material->set_shininess ($shininess): o $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): o $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: o 'never' / 'COGL_MATERIAL_ALPHA_FUNC_NEVER'; o 'less' / 'COGL_MATERIAL_ALPHA_FUNC_LESS'; o 'equal' / 'COGL_MATERIAL_ALPHA_FUNC_EQUAL'; o 'lequal' / 'COGL_MATERIAL_ALPHA_FUNC_LEQUAL'; o 'greater' / 'COGL_MATERIAL_ALPHA_FUNC_GREATER'; o 'notequal' / 'COGL_MATERIAL_ALPHA_FUNC_NOTEQUAL'; o 'gequal' / 'COGL_MATERIAL_ALPHA_FUNC_GEQUAL'; o 'always' / 'COGL_MATERIAL_ALPHA_FUNC_ALWAYS'
enum Clutter::Cogl::MaterialFilter: o 'nearest' / 'COGL_MATERIAL_FILTER_NEAREST'; o 'linear' / 'COGL_MATERIAL_FILTER_LINEAR'; o 'nearest-mipmap-nearest' /
'COGL_MATERIAL_FILTER_NEAREST_MIPMAP_NEAREST'; o 'linear-mipmap-nearest' /
'COGL_MATERIAL_FILTER_LINEAR_MIPMAP_NEAREST'; o 'nearest-mipmap-linear' /
'COGL_MATERIAL_FILTER_NEAREST_MIPMAP_LINEAR'; o 'linear-mipmap-linear' /
'COGL_MATERIAL_FILTER_LINEAR_MIPMAP_LINEAR'
enum Clutter::Cogl::MaterialLayerType: o '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>: 1
<color-source>
1 - <color-source>
SRC_ALPHA_SATURATE

COPYRIGHT

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

o the GNU Lesser General Public Library version 2.1; or

o the Artistic License, version 2.0.

docs.sk

komplexný repozitár dokumentácie

Najnavštevovanejšie