2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
<!ENTITY version "1.0.8">
6
<refentry id="cogl-Materials">
8
<refentrytitle role="top_of_page" id="cogl-Materials.top_of_page">Materials</refentrytitle>
9
<manvolnum>3</manvolnum>
10
<refmiscinfo>COGL Library</refmiscinfo>
14
<refname>Materials</refname>
15
<refpurpose>Fuctions for creating and manipulating materials</refpurpose>
18
<refsynopsisdiv id="cogl-Materials.synopsis" role="synopsis">
19
<title role="synopsis.title">Synopsis</title>
22
<link linkend="CoglHandle">CoglHandle</link> <link linkend="cogl-material-new">cogl_material_new</link> (void);
23
<link linkend="CoglHandle">CoglHandle</link> <link linkend="cogl-material-ref">cogl_material_ref</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
24
<link linkend="void">void</link> <link linkend="cogl-material-unref">cogl_material_unref</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
25
<link linkend="gboolean">gboolean</link> <link linkend="cogl-is-material">cogl_is_material</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
26
<link linkend="void">void</link> <link linkend="cogl-material-set-color">cogl_material_set_color</link> (<link linkend="CoglHandle">CoglHandle</link> material,
27
const <link linkend="CoglColor">CoglColor</link> *color);
28
<link linkend="void">void</link> <link linkend="cogl-material-set-color4ub">cogl_material_set_color4ub</link> (<link linkend="CoglHandle">CoglHandle</link> material,
29
<link linkend="guint8">guint8</link> red,
30
<link linkend="guint8">guint8</link> green,
31
<link linkend="guint8">guint8</link> blue,
32
<link linkend="guint8">guint8</link> alpha);
33
<link linkend="void">void</link> <link linkend="cogl-material-set-color4f">cogl_material_set_color4f</link> (<link linkend="CoglHandle">CoglHandle</link> material,
34
<link linkend="float">float</link> red,
35
<link linkend="float">float</link> green,
36
<link linkend="float">float</link> blue,
37
<link linkend="float">float</link> alpha);
38
<link linkend="void">void</link> <link linkend="cogl-material-get-color">cogl_material_get_color</link> (<link linkend="CoglHandle">CoglHandle</link> material,
39
<link linkend="CoglColor">CoglColor</link> *color);
40
<link linkend="void">void</link> <link linkend="cogl-material-set-ambient">cogl_material_set_ambient</link> (<link linkend="CoglHandle">CoglHandle</link> material,
41
const <link linkend="CoglColor">CoglColor</link> *ambient);
42
<link linkend="void">void</link> <link linkend="cogl-material-get-ambient">cogl_material_get_ambient</link> (<link linkend="CoglHandle">CoglHandle</link> material,
43
<link linkend="CoglColor">CoglColor</link> *ambient);
44
<link linkend="void">void</link> <link linkend="cogl-material-set-diffuse">cogl_material_set_diffuse</link> (<link linkend="CoglHandle">CoglHandle</link> material,
45
const <link linkend="CoglColor">CoglColor</link> *diffuse);
46
<link linkend="void">void</link> <link linkend="cogl-material-get-diffuse">cogl_material_get_diffuse</link> (<link linkend="CoglHandle">CoglHandle</link> material,
47
<link linkend="CoglColor">CoglColor</link> *diffuse);
48
<link linkend="void">void</link> <link linkend="cogl-material-set-ambient-and-diffuse">cogl_material_set_ambient_and_diffuse</link>
49
(<link linkend="CoglHandle">CoglHandle</link> material,
50
const <link linkend="CoglColor">CoglColor</link> *color);
51
<link linkend="void">void</link> <link linkend="cogl-material-set-emission">cogl_material_set_emission</link> (<link linkend="CoglHandle">CoglHandle</link> material,
52
const <link linkend="CoglColor">CoglColor</link> *emission);
53
<link linkend="void">void</link> <link linkend="cogl-material-get-emission">cogl_material_get_emission</link> (<link linkend="CoglHandle">CoglHandle</link> material,
54
<link linkend="CoglColor">CoglColor</link> *emission);
55
<link linkend="void">void</link> <link linkend="cogl-material-set-specular">cogl_material_set_specular</link> (<link linkend="CoglHandle">CoglHandle</link> material,
56
const <link linkend="CoglColor">CoglColor</link> *specular);
57
<link linkend="void">void</link> <link linkend="cogl-material-get-specular">cogl_material_get_specular</link> (<link linkend="CoglHandle">CoglHandle</link> material,
58
<link linkend="CoglColor">CoglColor</link> *specular);
59
<link linkend="void">void</link> <link linkend="cogl-material-set-shininess">cogl_material_set_shininess</link> (<link linkend="CoglHandle">CoglHandle</link> material,
60
<link linkend="float">float</link> shininess);
61
<link linkend="float">float</link> <link linkend="cogl-material-get-shininess">cogl_material_get_shininess</link> (<link linkend="CoglHandle">CoglHandle</link> material);
62
enum <link linkend="CoglMaterialAlphaFunc">CoglMaterialAlphaFunc</link>;
63
<link linkend="void">void</link> <link linkend="cogl-material-set-alpha-test-function">cogl_material_set_alpha_test_function</link>
64
(<link linkend="CoglHandle">CoglHandle</link> material,
65
<link linkend="CoglMaterialAlphaFunc">CoglMaterialAlphaFunc</link> alpha_func,
66
<link linkend="float">float</link> alpha_reference);
67
enum <link linkend="CoglBlendStringError">CoglBlendStringError</link>;
68
#define <link linkend="COGL-BLEND-STRING-ERROR--CAPS">COGL_BLEND_STRING_ERROR</link>
69
<link linkend="gboolean">gboolean</link> <link linkend="cogl-material-set-blend">cogl_material_set_blend</link> (<link linkend="CoglHandle">CoglHandle</link> material,
70
const <link linkend="char">char</link> *blend_string,
71
<link linkend="GError">GError</link> **error);
72
<link linkend="void">void</link> <link linkend="cogl-material-set-blend-constant">cogl_material_set_blend_constant</link> (<link linkend="CoglHandle">CoglHandle</link> material,
73
<link linkend="CoglColor">CoglColor</link> *constant_color);
74
<link linkend="void">void</link> <link linkend="cogl-material-set-layer">cogl_material_set_layer</link> (<link linkend="CoglHandle">CoglHandle</link> material,
75
<link linkend="int">int</link> layer_index,
76
<link linkend="CoglHandle">CoglHandle</link> texture);
77
<link linkend="void">void</link> <link linkend="cogl-material-remove-layer">cogl_material_remove_layer</link> (<link linkend="CoglHandle">CoglHandle</link> material,
78
<link linkend="gint">gint</link> layer_index);
79
<link linkend="gboolean">gboolean</link> <link linkend="cogl-material-set-layer-combine">cogl_material_set_layer_combine</link> (<link linkend="CoglHandle">CoglHandle</link> material,
80
<link linkend="gint">gint</link> layer_index,
81
const <link linkend="char">char</link> *blend_string,
82
<link linkend="GError">GError</link> **error);
83
<link linkend="void">void</link> <link linkend="cogl-material-set-layer-combine-constant">cogl_material_set_layer_combine_constant</link>
84
(<link linkend="CoglHandle">CoglHandle</link> material,
85
<link linkend="int">int</link> layer_index,
86
<link linkend="CoglColor">CoglColor</link> *constant);
87
<link linkend="void">void</link> <link linkend="cogl-material-set-layer-matrix">cogl_material_set_layer_matrix</link> (<link linkend="CoglHandle">CoglHandle</link> material,
88
<link linkend="int">int</link> layer_index,
89
<link linkend="CoglMatrix">CoglMatrix</link> *matrix);
90
const <link linkend="GList">GList</link> * <link linkend="cogl-material-get-layers">cogl_material_get_layers</link> (<link linkend="CoglHandle">CoglHandle</link> material);
91
<link linkend="int">int</link> <link linkend="cogl-material-get-n-layers">cogl_material_get_n_layers</link> (<link linkend="CoglHandle">CoglHandle</link> material);
92
enum <link linkend="CoglMaterialFilter">CoglMaterialFilter</link>;
93
<link linkend="void">void</link> <link linkend="cogl-material-set-layer-filters">cogl_material_set_layer_filters</link> (<link linkend="CoglHandle">CoglHandle</link> handle,
94
<link linkend="gint">gint</link> layer_index,
95
<link linkend="CoglMaterialFilter">CoglMaterialFilter</link> min_filter,
96
<link linkend="CoglMaterialFilter">CoglMaterialFilter</link> mag_filter);
97
<link linkend="CoglMaterialLayerType">CoglMaterialLayerType</link> <link linkend="cogl-material-layer-get-type">cogl_material_layer_get_type</link> (<link linkend="CoglHandle">CoglHandle</link> layer_handle);
98
<link linkend="CoglHandle">CoglHandle</link> <link linkend="cogl-material-layer-get-texture">cogl_material_layer_get_texture</link> (<link linkend="CoglHandle">CoglHandle</link> layer_handle);
99
<link linkend="CoglMaterialFilter">CoglMaterialFilter</link> <link linkend="cogl-material-layer-get-min-filter">cogl_material_layer_get_min_filter</link> (<link linkend="CoglHandle">CoglHandle</link> layer_handle);
100
<link linkend="CoglMaterialFilter">CoglMaterialFilter</link> <link linkend="cogl-material-layer-get-mag-filter">cogl_material_layer_get_mag_filter</link> (<link linkend="CoglHandle">CoglHandle</link> layer_handle);
112
<refsect1 id="cogl-Materials.description" role="desc">
113
<title role="desc.title">Description</title>
115
COGL allows creating and manipulating materials used to fill in
116
geometry. Materials may simply be lighting attributes (such as an
117
ambient and diffuse colour) or might represent one or more textures
118
blended together.</para>
123
<refsect1 id="cogl-Materials.details" role="details">
124
<title role="details.title">Details</title>
125
<refsect2 id="cogl-material-new" role="function">
126
<title>cogl_material_new ()</title>
127
<indexterm zone="cogl-material-new"><primary sortas="material_new">cogl_material_new</primary></indexterm><programlisting><link linkend="CoglHandle">CoglHandle</link> cogl_material_new (void);</programlisting>
129
Allocates and initializes a blank white material</para>
131
</para><variablelist role="params">
132
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a handle to the new material
133
</simpara></listitem></varlistentry>
134
</variablelist></refsect2>
135
<refsect2 id="cogl-material-ref" role="function">
136
<title>cogl_material_ref ()</title>
137
<indexterm zone="cogl-material-ref"><primary sortas="material_ref">cogl_material_ref</primary></indexterm><programlisting><link linkend="CoglHandle">CoglHandle</link> cogl_material_ref (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
139
Increment the reference count for a cogl material.</para>
141
</para><variablelist role="params">
142
<varlistentry><term><parameter>handle</parameter> :</term>
143
<listitem><simpara> a <parameter>CoglHandle</parameter>.
144
</simpara></listitem></varlistentry>
145
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <parameter>handle</parameter>.
148
</simpara></listitem></varlistentry>
149
</variablelist></refsect2>
150
<refsect2 id="cogl-material-unref" role="function">
151
<title>cogl_material_unref ()</title>
152
<indexterm zone="cogl-material-unref"><primary sortas="material_unref">cogl_material_unref</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_unref (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
154
Decrement the reference count for a cogl material.
159
</para><variablelist role="params">
160
<varlistentry><term><parameter>handle</parameter> :</term>
161
<listitem><simpara> a <parameter>CoglHandle</parameter>.
162
</simpara></listitem></varlistentry>
163
</variablelist></refsect2>
164
<refsect2 id="cogl-is-material" role="function">
165
<title>cogl_is_material ()</title>
166
<indexterm zone="cogl-is-material"><primary sortas="is_material">cogl_is_material</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_is_material (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
168
Gets whether the given handle references an existing material object.</para>
170
</para><variablelist role="params">
171
<varlistentry><term><parameter>handle</parameter> :</term>
172
<listitem><simpara> A CoglHandle
173
</simpara></listitem></varlistentry>
174
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the handle references a <link linkend="CoglMaterial"><type>CoglMaterial</type></link>,
175
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise
176
</simpara></listitem></varlistentry>
177
</variablelist></refsect2>
178
<refsect2 id="cogl-material-set-color" role="function">
179
<title>cogl_material_set_color ()</title>
180
<indexterm zone="cogl-material-set-color"><primary sortas="material_set_color">cogl_material_set_color</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_color (<link linkend="CoglHandle">CoglHandle</link> material,
181
const <link linkend="CoglColor">CoglColor</link> *color);</programlisting>
183
This is the basic color of the material, used when no lighting is enabled.
186
Note that if you don't add any layers to the material then the color
187
will be blended unmodified with the destination; the default blend
188
expects premultiplied colors: for example, use (0.5, 0.0, 0.0, 0.5) for
189
semi-transparent red. See <link linkend="cogl-color-premultiply"><function>cogl_color_premultiply()</function></link>.
192
The default value is (1.0, 1.0, 1.0, 1.0)
197
</para><variablelist role="params">
198
<varlistentry><term><parameter>material</parameter> :</term>
199
<listitem><simpara> A CoglMaterial object
200
</simpara></listitem></varlistentry>
201
<varlistentry><term><parameter>color</parameter> :</term>
202
<listitem><simpara> The components of the color
203
</simpara></listitem></varlistentry>
204
</variablelist></refsect2>
205
<refsect2 id="cogl-material-set-color4ub" role="function">
206
<title>cogl_material_set_color4ub ()</title>
207
<indexterm zone="cogl-material-set-color4ub"><primary sortas="material_set_color4ub">cogl_material_set_color4ub</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_color4ub (<link linkend="CoglHandle">CoglHandle</link> material,
208
<link linkend="guint8">guint8</link> red,
209
<link linkend="guint8">guint8</link> green,
210
<link linkend="guint8">guint8</link> blue,
211
<link linkend="guint8">guint8</link> alpha);</programlisting>
213
This is the basic color of the material, used when no lighting is enabled.
216
The default value is (0xff, 0xff, 0xff, 0xff)
221
</para><variablelist role="params">
222
<varlistentry><term><parameter>material</parameter> :</term>
223
<listitem><simpara> A CoglMaterial object
224
</simpara></listitem></varlistentry>
225
<varlistentry><term><parameter>red</parameter> :</term>
226
<listitem><simpara> The red component
227
</simpara></listitem></varlistentry>
228
<varlistentry><term><parameter>green</parameter> :</term>
229
<listitem><simpara> The green component
230
</simpara></listitem></varlistentry>
231
<varlistentry><term><parameter>blue</parameter> :</term>
232
<listitem><simpara> The blue component
233
</simpara></listitem></varlistentry>
234
<varlistentry><term><parameter>alpha</parameter> :</term>
235
<listitem><simpara> The alpha component
236
</simpara></listitem></varlistentry>
237
</variablelist></refsect2>
238
<refsect2 id="cogl-material-set-color4f" role="function">
239
<title>cogl_material_set_color4f ()</title>
240
<indexterm zone="cogl-material-set-color4f"><primary sortas="material_set_color4f">cogl_material_set_color4f</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_color4f (<link linkend="CoglHandle">CoglHandle</link> material,
241
<link linkend="float">float</link> red,
242
<link linkend="float">float</link> green,
243
<link linkend="float">float</link> blue,
244
<link linkend="float">float</link> alpha);</programlisting>
246
This is the basic color of the material, used when no lighting is enabled.
249
The default value is (1.0, 1.0, 1.0, 1.0)
254
</para><variablelist role="params">
255
<varlistentry><term><parameter>material</parameter> :</term>
256
<listitem><simpara> A CoglMaterial object
257
</simpara></listitem></varlistentry>
258
<varlistentry><term><parameter>red</parameter> :</term>
259
<listitem><simpara> The red component
260
</simpara></listitem></varlistentry>
261
<varlistentry><term><parameter>green</parameter> :</term>
262
<listitem><simpara> The green component
263
</simpara></listitem></varlistentry>
264
<varlistentry><term><parameter>blue</parameter> :</term>
265
<listitem><simpara> The blue component
266
</simpara></listitem></varlistentry>
267
<varlistentry><term><parameter>alpha</parameter> :</term>
268
<listitem><simpara> The alpha component
269
</simpara></listitem></varlistentry>
270
</variablelist></refsect2>
271
<refsect2 id="cogl-material-get-color" role="function">
272
<title>cogl_material_get_color ()</title>
273
<indexterm zone="cogl-material-get-color"><primary sortas="material_get_color">cogl_material_get_color</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_get_color (<link linkend="CoglHandle">CoglHandle</link> material,
274
<link linkend="CoglColor">CoglColor</link> *color);</programlisting>
276
This retrieves the current material color.
281
</para><variablelist role="params">
282
<varlistentry><term><parameter>material</parameter> :</term>
283
<listitem><simpara> A CoglMaterial object
284
</simpara></listitem></varlistentry>
285
<varlistentry><term><parameter>color</parameter> :</term>
286
<listitem><simpara> The location to store the color
287
</simpara></listitem></varlistentry>
288
</variablelist></refsect2>
289
<refsect2 id="cogl-material-set-ambient" role="function">
290
<title>cogl_material_set_ambient ()</title>
291
<indexterm zone="cogl-material-set-ambient"><primary sortas="material_set_ambient">cogl_material_set_ambient</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_ambient (<link linkend="CoglHandle">CoglHandle</link> material,
292
const <link linkend="CoglColor">CoglColor</link> *ambient);</programlisting>
294
Exposing the standard OpenGL lighting model; this function sets
295
the material's ambient color. The ambient color affects the overall
296
color of the object. Since the diffuse color will be intense when
297
the light hits the surface directly, the ambient will most aparent
298
where the light hits at a slant.
301
The default value is (0.2, 0.2, 0.2, 1.0)
306
</para><variablelist role="params">
307
<varlistentry><term><parameter>material</parameter> :</term>
308
<listitem><simpara> A CoglMaterial object
309
</simpara></listitem></varlistentry>
310
<varlistentry><term><parameter>ambient</parameter> :</term>
311
<listitem><simpara> The components of the desired ambient color
312
</simpara></listitem></varlistentry>
313
</variablelist></refsect2>
314
<refsect2 id="cogl-material-get-ambient" role="function">
315
<title>cogl_material_get_ambient ()</title>
316
<indexterm zone="cogl-material-get-ambient"><primary sortas="material_get_ambient">cogl_material_get_ambient</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_get_ambient (<link linkend="CoglHandle">CoglHandle</link> material,
317
<link linkend="CoglColor">CoglColor</link> *ambient);</programlisting>
319
This retrieves the materials current ambient color.
324
</para><variablelist role="params">
325
<varlistentry><term><parameter>material</parameter> :</term>
326
<listitem><simpara> A CoglMaterial object
327
</simpara></listitem></varlistentry>
328
<varlistentry><term><parameter>ambient</parameter> :</term>
329
<listitem><simpara> The location to store the ambient color
330
</simpara></listitem></varlistentry>
331
</variablelist></refsect2>
332
<refsect2 id="cogl-material-set-diffuse" role="function">
333
<title>cogl_material_set_diffuse ()</title>
334
<indexterm zone="cogl-material-set-diffuse"><primary sortas="material_set_diffuse">cogl_material_set_diffuse</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_diffuse (<link linkend="CoglHandle">CoglHandle</link> material,
335
const <link linkend="CoglColor">CoglColor</link> *diffuse);</programlisting>
337
Exposing the standard OpenGL lighting model; this function sets
338
the material's diffuse color. The diffuse color is most intense
339
where the light hits the surface directly; perpendicular to the
343
The default value is (0.8, 0.8, 0.8, 1.0)
348
</para><variablelist role="params">
349
<varlistentry><term><parameter>material</parameter> :</term>
350
<listitem><simpara> A CoglMaterial object
351
</simpara></listitem></varlistentry>
352
<varlistentry><term><parameter>diffuse</parameter> :</term>
353
<listitem><simpara> The components of the desired diffuse color
354
</simpara></listitem></varlistentry>
355
</variablelist></refsect2>
356
<refsect2 id="cogl-material-get-diffuse" role="function">
357
<title>cogl_material_get_diffuse ()</title>
358
<indexterm zone="cogl-material-get-diffuse"><primary sortas="material_get_diffuse">cogl_material_get_diffuse</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_get_diffuse (<link linkend="CoglHandle">CoglHandle</link> material,
359
<link linkend="CoglColor">CoglColor</link> *diffuse);</programlisting>
361
This retrieves the materials current diffuse color.
366
</para><variablelist role="params">
367
<varlistentry><term><parameter>material</parameter> :</term>
368
<listitem><simpara> A CoglMaterial object
369
</simpara></listitem></varlistentry>
370
<varlistentry><term><parameter>diffuse</parameter> :</term>
371
<listitem><simpara> The location to store the diffuse color
372
</simpara></listitem></varlistentry>
373
</variablelist></refsect2>
374
<refsect2 id="cogl-material-set-ambient-and-diffuse" role="function">
375
<title>cogl_material_set_ambient_and_diffuse ()</title>
376
<indexterm zone="cogl-material-set-ambient-and-diffuse"><primary sortas="material_set_ambient_and_diffuse">cogl_material_set_ambient_and_diffuse</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_ambient_and_diffuse
377
(<link linkend="CoglHandle">CoglHandle</link> material,
378
const <link linkend="CoglColor">CoglColor</link> *color);</programlisting>
380
This is a convenience for setting the diffuse and ambient color
381
of the material at the same time.
384
The default ambient color is (0.2, 0.2, 0.2, 1.0)
385
The default diffuse color is (0.8, 0.8, 0.8, 1.0)
390
</para><variablelist role="params">
391
<varlistentry><term><parameter>material</parameter> :</term>
392
<listitem><simpara> A CoglMaterial object
393
</simpara></listitem></varlistentry>
394
<varlistentry><term><parameter>color</parameter> :</term>
395
<listitem><simpara> The components of the desired ambient and diffuse colors
396
</simpara></listitem></varlistentry>
397
</variablelist></refsect2>
398
<refsect2 id="cogl-material-set-emission" role="function">
399
<title>cogl_material_set_emission ()</title>
400
<indexterm zone="cogl-material-set-emission"><primary sortas="material_set_emission">cogl_material_set_emission</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_emission (<link linkend="CoglHandle">CoglHandle</link> material,
401
const <link linkend="CoglColor">CoglColor</link> *emission);</programlisting>
403
Exposing the standard OpenGL lighting model; this function sets
404
the material's emissive color. It will look like the surface is
405
a light source emitting this color.
408
The default value is (0.0, 0.0, 0.0, 1.0)
413
</para><variablelist role="params">
414
<varlistentry><term><parameter>material</parameter> :</term>
415
<listitem><simpara> A CoglMaterial object
416
</simpara></listitem></varlistentry>
417
<varlistentry><term><parameter>emission</parameter> :</term>
418
<listitem><simpara> The components of the desired emissive color
419
</simpara></listitem></varlistentry>
420
</variablelist></refsect2>
421
<refsect2 id="cogl-material-get-emission" role="function">
422
<title>cogl_material_get_emission ()</title>
423
<indexterm zone="cogl-material-get-emission"><primary sortas="material_get_emission">cogl_material_get_emission</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_get_emission (<link linkend="CoglHandle">CoglHandle</link> material,
424
<link linkend="CoglColor">CoglColor</link> *emission);</programlisting>
426
This retrieves the materials current emission color.
431
</para><variablelist role="params">
432
<varlistentry><term><parameter>material</parameter> :</term>
433
<listitem><simpara> A CoglMaterial object
434
</simpara></listitem></varlistentry>
435
<varlistentry><term><parameter>emission</parameter> :</term>
436
<listitem><simpara> The location to store the emission color
437
</simpara></listitem></varlistentry>
438
</variablelist></refsect2>
439
<refsect2 id="cogl-material-set-specular" role="function">
440
<title>cogl_material_set_specular ()</title>
441
<indexterm zone="cogl-material-set-specular"><primary sortas="material_set_specular">cogl_material_set_specular</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_specular (<link linkend="CoglHandle">CoglHandle</link> material,
442
const <link linkend="CoglColor">CoglColor</link> *specular);</programlisting>
444
Exposing the standard OpenGL lighting model; this function sets
445
the material's specular color. The intensity of the specular color
446
depends on the viewport position, and is brightest along the lines
450
The default value is (0.0, 0.0, 0.0, 1.0)
455
</para><variablelist role="params">
456
<varlistentry><term><parameter>material</parameter> :</term>
457
<listitem><simpara> A CoglMaterial object
458
</simpara></listitem></varlistentry>
459
<varlistentry><term><parameter>specular</parameter> :</term>
460
<listitem><simpara> The components of the desired specular color
461
</simpara></listitem></varlistentry>
462
</variablelist></refsect2>
463
<refsect2 id="cogl-material-get-specular" role="function">
464
<title>cogl_material_get_specular ()</title>
465
<indexterm zone="cogl-material-get-specular"><primary sortas="material_get_specular">cogl_material_get_specular</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_get_specular (<link linkend="CoglHandle">CoglHandle</link> material,
466
<link linkend="CoglColor">CoglColor</link> *specular);</programlisting>
468
This retrieves the materials current specular color.
473
</para><variablelist role="params">
474
<varlistentry><term><parameter>material</parameter> :</term>
475
<listitem><simpara> A CoglMaterial object
476
</simpara></listitem></varlistentry>
477
<varlistentry><term><parameter>specular</parameter> :</term>
478
<listitem><simpara> The location to store the specular color
479
</simpara></listitem></varlistentry>
480
</variablelist></refsect2>
481
<refsect2 id="cogl-material-set-shininess" role="function">
482
<title>cogl_material_set_shininess ()</title>
483
<indexterm zone="cogl-material-set-shininess"><primary sortas="material_set_shininess">cogl_material_set_shininess</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_shininess (<link linkend="CoglHandle">CoglHandle</link> material,
484
<link linkend="float">float</link> shininess);</programlisting>
486
This function sets the materials shininess which determines how
487
specular highlights are calculated. A higher shininess will produce
488
smaller brigher highlights.
491
The default value is 0.0
496
</para><variablelist role="params">
497
<varlistentry><term><parameter>material</parameter> :</term>
498
<listitem><simpara> A CoglMaterial object
499
</simpara></listitem></varlistentry>
500
<varlistentry><term><parameter>shininess</parameter> :</term>
501
<listitem><simpara> The desired shininess; range: [0.0, 1.0]
502
</simpara></listitem></varlistentry>
503
</variablelist></refsect2>
504
<refsect2 id="cogl-material-get-shininess" role="function">
505
<title>cogl_material_get_shininess ()</title>
506
<indexterm zone="cogl-material-get-shininess"><primary sortas="material_get_shininess">cogl_material_get_shininess</primary></indexterm><programlisting><link linkend="float">float</link> cogl_material_get_shininess (<link linkend="CoglHandle">CoglHandle</link> material);</programlisting>
508
This retrieves the materials current emission color.</para>
510
</para><variablelist role="params">
511
<varlistentry><term><parameter>material</parameter> :</term>
512
<listitem><simpara> A CoglMaterial object
513
</simpara></listitem></varlistentry>
514
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The materials current shininess value
517
</simpara></listitem></varlistentry>
518
</variablelist></refsect2>
519
<refsect2 id="CoglMaterialAlphaFunc" role="enum">
520
<title>enum CoglMaterialAlphaFunc</title>
521
<indexterm zone="CoglMaterialAlphaFunc"><primary sortas="MaterialAlphaFunc">CoglMaterialAlphaFunc</primary></indexterm><programlisting>typedef enum _CoglMaterialAlphaFunc
523
COGL_MATERIAL_ALPHA_FUNC_NEVER = GL_NEVER,
524
COGL_MATERIAL_ALPHA_FUNC_LESS = GL_LESS,
525
COGL_MATERIAL_ALPHA_FUNC_EQUAL = GL_EQUAL,
526
COGL_MATERIAL_ALPHA_FUNC_LEQUAL = GL_LEQUAL,
527
COGL_MATERIAL_ALPHA_FUNC_GREATER = GL_GREATER,
528
COGL_MATERIAL_ALPHA_FUNC_NOTEQUAL = GL_NOTEQUAL,
529
COGL_MATERIAL_ALPHA_FUNC_GEQUAL = GL_GEQUAL,
530
COGL_MATERIAL_ALPHA_FUNC_ALWAYS = GL_ALWAYS
531
} CoglMaterialAlphaFunc;
534
Alpha testing happens before blending primitives with the framebuffer and
535
gives an opportunity to discard fragments based on a comparison with the
536
incoming alpha value and a reference alpha value. The <link linkend="CoglMaterialAlphaFunc"><type>CoglMaterialAlphaFunc</type></link>
537
determines how the comparison is done.</para>
539
</para><variablelist role="enum">
540
<varlistentry id="COGL-MATERIAL-ALPHA-FUNC-NEVER--CAPS" role="constant">
541
<term><literal>COGL_MATERIAL_ALPHA_FUNC_NEVER</literal></term>
542
<listitem><simpara> Never let the fragment through.
543
</simpara></listitem>
545
<varlistentry id="COGL-MATERIAL-ALPHA-FUNC-LESS--CAPS" role="constant">
546
<term><literal>COGL_MATERIAL_ALPHA_FUNC_LESS</literal></term>
547
<listitem><simpara> Let the fragment through if the incoming
548
alpha value is less than the reference alpha
550
</simpara></listitem>
552
<varlistentry id="COGL-MATERIAL-ALPHA-FUNC-EQUAL--CAPS" role="constant">
553
<term><literal>COGL_MATERIAL_ALPHA_FUNC_EQUAL</literal></term>
554
<listitem><simpara> Let the fragment through if the incoming
555
alpha value equals the reference alpha
557
</simpara></listitem>
559
<varlistentry id="COGL-MATERIAL-ALPHA-FUNC-LEQUAL--CAPS" role="constant">
560
<term><literal>COGL_MATERIAL_ALPHA_FUNC_LEQUAL</literal></term>
561
<listitem><simpara> Let the fragment through if the incoming
562
alpha value is less than or equal to the
563
reference alpha value.
564
</simpara></listitem>
566
<varlistentry id="COGL-MATERIAL-ALPHA-FUNC-GREATER--CAPS" role="constant">
567
<term><literal>COGL_MATERIAL_ALPHA_FUNC_GREATER</literal></term>
568
<listitem><simpara> Let the fragment through if the incoming
569
alpha value is greater than the reference
571
</simpara></listitem>
573
<varlistentry id="COGL-MATERIAL-ALPHA-FUNC-NOTEQUAL--CAPS" role="constant">
574
<term><literal>COGL_MATERIAL_ALPHA_FUNC_NOTEQUAL</literal></term>
575
<listitem><simpara> Let the fragment through if the incoming
576
alpha value does not equal the reference
578
</simpara></listitem>
580
<varlistentry id="COGL-MATERIAL-ALPHA-FUNC-GEQUAL--CAPS" role="constant">
581
<term><literal>COGL_MATERIAL_ALPHA_FUNC_GEQUAL</literal></term>
582
<listitem><simpara> Let the fragment through if the incoming
583
alpha value is greater than or equal to the
584
reference alpha value.
585
</simpara></listitem>
587
<varlistentry id="COGL-MATERIAL-ALPHA-FUNC-ALWAYS--CAPS" role="constant">
588
<term><literal>COGL_MATERIAL_ALPHA_FUNC_ALWAYS</literal></term>
589
<listitem><simpara> Always let the fragment through.
590
</simpara></listitem>
592
</variablelist></refsect2>
593
<refsect2 id="cogl-material-set-alpha-test-function" role="function">
594
<title>cogl_material_set_alpha_test_function ()</title>
595
<indexterm zone="cogl-material-set-alpha-test-function"><primary sortas="material_set_alpha_test_function">cogl_material_set_alpha_test_function</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_alpha_test_function
596
(<link linkend="CoglHandle">CoglHandle</link> material,
597
<link linkend="CoglMaterialAlphaFunc">CoglMaterialAlphaFunc</link> alpha_func,
598
<link linkend="float">float</link> alpha_reference);</programlisting>
600
Before a primitive is blended with the framebuffer, it goes through an
601
alpha test stage which lets you discard fragments based on the current
602
alpha value. This function lets you change the function used to evaluate
603
the alpha channel, and thus determine which fragments are discarded
604
and which continue on to the blending stage.
607
The default is COGL_MATERIAL_ALPHA_FUNC_ALWAYS
612
</para><variablelist role="params">
613
<varlistentry><term><parameter>material</parameter> :</term>
614
<listitem><simpara> A CoglMaterial object
615
</simpara></listitem></varlistentry>
616
<varlistentry><term><parameter>alpha_func</parameter> :</term>
617
<listitem><simpara> A <parameter>CoglMaterialAlphaFunc</parameter> constant
618
</simpara></listitem></varlistentry>
619
<varlistentry><term><parameter>alpha_reference</parameter> :</term>
620
<listitem><simpara> A reference point that the chosen alpha function uses
621
to compare incoming fragments to.
622
</simpara></listitem></varlistentry>
623
</variablelist></refsect2>
624
<refsect2 id="CoglBlendStringError" role="enum">
625
<title>enum CoglBlendStringError</title>
626
<indexterm zone="CoglBlendStringError"><primary sortas="BlendStringError">CoglBlendStringError</primary></indexterm><programlisting>typedef enum { /*< prefix=COGL_BLEND_STRING_ERROR >*/
627
COGL_BLEND_STRING_ERROR_PARSE_ERROR,
628
COGL_BLEND_STRING_ERROR_ARGUMENT_PARSE_ERROR,
629
COGL_BLEND_STRING_ERROR_INVALID_ERROR,
630
COGL_BLEND_STRING_ERROR_GPU_UNSUPPORTED_ERROR
631
} CoglBlendStringError;
635
<refsect2 id="COGL-BLEND-STRING-ERROR--CAPS" role="macro">
636
<title>COGL_BLEND_STRING_ERROR</title>
637
<indexterm zone="COGL-BLEND-STRING-ERROR--CAPS"><primary sortas="BLEND_STRING_ERROR">COGL_BLEND_STRING_ERROR</primary></indexterm><programlisting>#define COGL_BLEND_STRING_ERROR (cogl_blend_string_error_quark ())
641
<refsect2 id="cogl-material-set-blend" role="function" condition="since:1.0">
642
<title>cogl_material_set_blend ()</title>
643
<indexterm zone="cogl-material-set-blend" role="1.0"><primary sortas="material_set_blend">cogl_material_set_blend</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_material_set_blend (<link linkend="CoglHandle">CoglHandle</link> material,
644
const <link linkend="char">char</link> *blend_string,
645
<link linkend="GError">GError</link> **error);</programlisting>
647
If not already familiar; please refer
648
<link linkend="cogl-Blend-Strings">here</link> for an overview of what blend
649
strings are and there syntax.
652
Blending occurs after the alpha test function, and combines fragments with
656
Currently the only blend function Cogl exposes is <link linkend="ADD--CAPS"><function>ADD()</function></link>. So any valid
657
blend statements will be of the form:
661
<channel-mask>=ADD(SRC_COLOR*(<factor>), DST_COLOR*(<factor>))
665
<warning>The brackets around blend factors are currently not optional!</warning>
668
This is the list of source-names usable as blend factors:
670
<listitem>SRC_COLOR: The color of the in comming fragment</listitem>
671
<listitem>DST_COLOR: The color of the framebuffer</listitem>
673
CONSTANT: The constant set via <link linkend="cogl-material-set-blend-constant"><function>cogl_material_set_blend_constant()</function></link></listitem>
675
The source names can be used according to the
676
<link linkend="cogl-Blend-String-syntax">color-source and factor syntax</link>,
677
so for example "(1-SRC_COLOR[A])" would be a valid factor, as would
681
These can also be used as factors:
683
<listitem>0: (0, 0, 0, 0)</listitem>
684
<listitem>1: (1, 1, 1, 1)</listitem>
685
<listitem>SRC_ALPHA_SATURATE_FACTOR: (f,f,f,1)
686
where f=MIN(SRC_COLOR[A],1-DST_COLOR[A])</listitem>
689
Remember; all color components are normalized to the range [0, 1] before
690
computing the result of blending.
693
<title>Examples</title>
694
Blend a non-premultiplied source over a destination with
697
"RGB = ADD(SRC_COLOR*(SRC_COLOR[A]), DST_COLOR*(1-SRC_COLOR[A]))"
698
"A = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
700
Blend a premultiplied source over a destination with premultiplied alpha:
702
"RGBA = ADD(SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
707
The default blend string is:
708
"RGBA = ADD (SRC_COLOR, DST_COLOR*(1-SRC_COLOR[A]))"
709
That gives normal alpha-blending when the calculated color for the material
710
is in premultiplied form.</para>
712
</para><variablelist role="params">
713
<varlistentry><term><parameter>material</parameter> :</term>
714
<listitem><simpara> A CoglMaterial object
715
</simpara></listitem></varlistentry>
716
<varlistentry><term><parameter>blend_string</parameter> :</term>
717
<listitem><simpara> A <link linkend="cogl-Blend-Strings">Cogl blend string</link>
718
describing the desired blend function.
719
</simpara></listitem></varlistentry>
720
<varlistentry><term><parameter>error</parameter> :</term>
721
<listitem><simpara> A GError that may report lack of driver support if you give
722
separate blend string statements for the alpha channel and RGB
723
channels since some drivers or backends such as GLES 1.1 dont
724
support this. May be <link linkend="NULL--CAPS"><literal>NULL</literal></link>, in which case a warning will be
725
printed out if an error is encountered.
726
</simpara></listitem></varlistentry>
727
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if the blend string was successfully parsed, and the described
728
blending is supported by the underlying driver/hardware. If there
729
was an error, it returns FALSE.
731
</simpara></listitem></varlistentry>
732
</variablelist><para role="since">Since 1.0</para></refsect2>
733
<refsect2 id="cogl-material-set-blend-constant" role="function" condition="since:1.0">
734
<title>cogl_material_set_blend_constant ()</title>
735
<indexterm zone="cogl-material-set-blend-constant" role="1.0"><primary sortas="material_set_blend_constant">cogl_material_set_blend_constant</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_blend_constant (<link linkend="CoglHandle">CoglHandle</link> material,
736
<link linkend="CoglColor">CoglColor</link> *constant_color);</programlisting>
738
When blending is setup to reference a CONSTANT blend factor then
739
blending will depend on the constant set with this function.</para>
741
</para><variablelist role="params">
742
<varlistentry><term><parameter>material</parameter> :</term>
743
<listitem><simpara> A CoglMaterial object
744
</simpara></listitem></varlistentry>
745
<varlistentry><term><parameter>constant_color</parameter> :</term>
746
<listitem><simpara> The constant color you want
747
</simpara></listitem></varlistentry>
748
</variablelist><para role="since">Since 1.0</para></refsect2>
749
<refsect2 id="cogl-material-set-layer" role="function">
750
<title>cogl_material_set_layer ()</title>
751
<indexterm zone="cogl-material-set-layer"><primary sortas="material_set_layer">cogl_material_set_layer</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_layer (<link linkend="CoglHandle">CoglHandle</link> material,
752
<link linkend="int">int</link> layer_index,
753
<link linkend="CoglHandle">CoglHandle</link> texture);</programlisting>
755
In addition to the standard OpenGL lighting model a Cogl material may have
756
one or more layers comprised of textures that can be blended together in
757
order, with a number of different texture combine modes. This function
758
defines a new texture layer.
761
The index values of multiple layers do not have to be consecutive; it is
762
only their relative order that is important.
765
<note>In the future, we may define other types of material layers, such
766
as purely GLSL based layers.</note>
771
</para><variablelist role="params">
772
<varlistentry><term><parameter>material</parameter> :</term>
773
<listitem><simpara> A <link linkend="CoglHandle"><type>CoglHandle</type></link> for a material object
774
</simpara></listitem></varlistentry>
775
<varlistentry><term><parameter>layer_index</parameter> :</term>
776
<listitem><simpara> the index of the layer
777
</simpara></listitem></varlistentry>
778
<varlistentry><term><parameter>texture</parameter> :</term>
779
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for the layer object
780
</simpara></listitem></varlistentry>
781
</variablelist></refsect2>
782
<refsect2 id="cogl-material-remove-layer" role="function">
783
<title>cogl_material_remove_layer ()</title>
784
<indexterm zone="cogl-material-remove-layer"><primary sortas="material_remove_layer">cogl_material_remove_layer</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_remove_layer (<link linkend="CoglHandle">CoglHandle</link> material,
785
<link linkend="gint">gint</link> layer_index);</programlisting>
787
</para><variablelist role="params">
788
<varlistentry><term><parameter>material</parameter> :</term>
790
</simpara></listitem></varlistentry>
791
<varlistentry><term><parameter>layer_index</parameter> :</term>
793
</simpara></listitem></varlistentry>
794
</variablelist></refsect2>
795
<refsect2 id="cogl-material-set-layer-combine" role="function" condition="since:1.0">
796
<title>cogl_material_set_layer_combine ()</title>
797
<indexterm zone="cogl-material-set-layer-combine" role="1.0"><primary sortas="material_set_layer_combine">cogl_material_set_layer_combine</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_material_set_layer_combine (<link linkend="CoglHandle">CoglHandle</link> material,
798
<link linkend="gint">gint</link> layer_index,
799
const <link linkend="char">char</link> *blend_string,
800
<link linkend="GError">GError</link> **error);</programlisting>
802
If not already familiar; you can refer
803
<link linkend="cogl-Blend-Strings">here</link> for an overview of what blend
804
strings are and there syntax.
807
These are all the functions available for texture combining:
809
<listitem>REPLACE(arg0) = arg0</listitem>
810
<listitem>MODULATE(arg0, arg1) = arg0 x arg1</listitem>
811
<listitem>ADD(arg0, arg1) = arg0 + arg1</listitem>
812
<listitem>ADD_SIGNED(arg0, arg1) = arg0 + arg1 - 0.5</listitem>
813
<listitem>INTERPOLATE(arg0, arg1, arg2) =
814
arg0 x arg2 + arg1 x (1 - arg2)</listitem>
815
<listitem>SUBTRACT(arg0, arg1) = arg0 - arg1</listitem>
817
DOT3_RGB(arg0, arg1) =
819
4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
820
(arg0[G] - 0.5)) * (arg1[G] - 0.5) +
821
(arg0[B] - 0.5)) * (arg1[B] - 0.5))
824
<listitem>DOT3_RGBA(arg0, arg1) =
826
4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
827
(arg0[G] - 0.5)) * (arg1[G] - 0.5) +
828
(arg0[B] - 0.5)) * (arg1[B] - 0.5))
835
<link linkend="cogl-Blend-String-syntax">color-source syntax</link> for
836
describing the arguments. The valid source names for texture combining
840
TEXTURE: Use the color from the current texture layer
843
TEXTURE_0, TEXTURE_1, etc: Use the color from the specified texture layer
846
CONSTANT: Use the color from the constant given with
847
<link linkend="cogl-material-set-layer-constant"><function>cogl_material_set_layer_constant()</function></link>
850
PRIMARY: Use the color of the material as set with <link linkend="cogl-material-set-color"><function>cogl_material_set_color()</function></link>
853
PREVIOUS: Either use the texture color from the previous layer, or if this
854
is layer 0, use the color of the material as set with
855
<link linkend="cogl-material-set-color"><function>cogl_material_set_color()</function></link>
859
<title>Example</title>
860
This is effectively what the default blending is:
861
<informalexample><programlisting>
862
RGBA = MODULATE (PREVIOUS, TEXTURE)
863
</programlisting></informalexample>
864
This could be used to cross-fade between two images, using the alpha
865
component of a constant as the interpolator. The constant color
866
is given by calling cogl_material_set_layer_constant.
867
<informalexample><programlisting>
868
RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
869
</programlisting></informalexample>
873
<note>You can't give a multiplication factor for arguments as you can
874
with blending.</note></para>
876
</para><variablelist role="params">
877
<varlistentry><term><parameter>material</parameter> :</term>
878
<listitem><simpara> A CoglMaterial object
879
</simpara></listitem></varlistentry>
880
<varlistentry><term><parameter>layer_index</parameter> :</term>
881
<listitem><simpara> Specifies the layer you want define a combine function for
882
</simpara></listitem></varlistentry>
883
<varlistentry><term><parameter>blend_string</parameter> :</term>
884
<listitem><simpara> A <link linkend="cogl-Blend-Strings">Cogl blend string</link>
885
describing the desired texture combine function.
886
</simpara></listitem></varlistentry>
887
<varlistentry><term><parameter>error</parameter> :</term>
888
<listitem><simpara> A <link linkend="GError"><type>GError</type></link> that may report parse errors or lack of GPU/driver support.
889
May be <link linkend="NULL--CAPS"><literal>NULL</literal></link>, in which case a warning will be printed out if an
890
error is encountered.
891
</simpara></listitem></varlistentry>
892
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the blend string was successfully parsed, and the
893
described texture combining is supported by the underlying driver and
894
or hardware. If there was an error, it returns FALSE.
896
</simpara></listitem></varlistentry>
897
</variablelist><para role="since">Since 1.0</para></refsect2>
898
<refsect2 id="cogl-material-set-layer-combine-constant" role="function">
899
<title>cogl_material_set_layer_combine_constant ()</title>
900
<indexterm zone="cogl-material-set-layer-combine-constant"><primary sortas="material_set_layer_combine_constant">cogl_material_set_layer_combine_constant</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_layer_combine_constant
901
(<link linkend="CoglHandle">CoglHandle</link> material,
902
<link linkend="int">int</link> layer_index,
903
<link linkend="CoglColor">CoglColor</link> *constant);</programlisting>
905
When you are using the 'CONSTANT' color source in a layer combine
906
description then you can use this function to define its value.
911
</para><variablelist role="params">
912
<varlistentry><term><parameter>material</parameter> :</term>
913
<listitem><simpara> A CoglMaterial object
914
</simpara></listitem></varlistentry>
915
<varlistentry><term><parameter>layer_index</parameter> :</term>
916
<listitem><simpara> Specifies the layer you want to specify a constant used
917
for texture combining
918
</simpara></listitem></varlistentry>
919
<varlistentry><term><parameter>constant</parameter> :</term>
920
<listitem><simpara> The constant color you want
921
</simpara></listitem></varlistentry>
922
</variablelist></refsect2>
923
<refsect2 id="cogl-material-set-layer-matrix" role="function">
924
<title>cogl_material_set_layer_matrix ()</title>
925
<indexterm zone="cogl-material-set-layer-matrix"><primary sortas="material_set_layer_matrix">cogl_material_set_layer_matrix</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_layer_matrix (<link linkend="CoglHandle">CoglHandle</link> material,
926
<link linkend="int">int</link> layer_index,
927
<link linkend="CoglMatrix">CoglMatrix</link> *matrix);</programlisting>
929
This function lets you set a matrix that can be used to e.g. translate
930
and rotate a single layer of a material used to fill your geometry.</para>
932
</para><variablelist role="params">
933
<varlistentry><term><parameter>material</parameter> :</term>
934
<listitem><simpara> A CoglMaterial object
935
</simpara></listitem></varlistentry>
936
<varlistentry><term><parameter>layer_index</parameter> :</term>
937
<listitem><simpara> the index for the layer inside <parameter>material</parameter>
938
</simpara></listitem></varlistentry>
939
<varlistentry><term><parameter>matrix</parameter> :</term>
940
<listitem><simpara> the transformation matrix for the layer
941
</simpara></listitem></varlistentry>
942
</variablelist></refsect2>
943
<refsect2 id="cogl-material-get-layers" role="function">
944
<title>cogl_material_get_layers ()</title>
945
<indexterm zone="cogl-material-get-layers"><primary sortas="material_get_layers">cogl_material_get_layers</primary></indexterm><programlisting>const <link linkend="GList">GList</link> * cogl_material_get_layers (<link linkend="CoglHandle">CoglHandle</link> material);</programlisting>
947
This function lets you access a materials internal list of layers
948
for iteration.</para>
950
</para><variablelist role="params">
951
<varlistentry><term><parameter>material</parameter> :</term>
952
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a material
953
</simpara></listitem></varlistentry>
954
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>element-type Handle) (transfer none. <acronym>element-type</acronym> Handle. <acronym>transfer</acronym> none. </simpara></listitem></varlistentry>
955
</variablelist></refsect2>
956
<refsect2 id="cogl-material-get-n-layers" role="function" condition="since:1.0">
957
<title>cogl_material_get_n_layers ()</title>
958
<indexterm zone="cogl-material-get-n-layers" role="1.0"><primary sortas="material_get_n_layers">cogl_material_get_n_layers</primary></indexterm><programlisting><link linkend="int">int</link> cogl_material_get_n_layers (<link linkend="CoglHandle">CoglHandle</link> material);</programlisting>
960
Retrieves the number of layers defined for the given <parameter>material</parameter></para>
962
</para><variablelist role="params">
963
<varlistentry><term><parameter>material</parameter> :</term>
964
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a material
965
</simpara></listitem></varlistentry>
966
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of layers
968
</simpara></listitem></varlistentry>
969
</variablelist><para role="since">Since 1.0</para></refsect2>
970
<refsect2 id="CoglMaterialFilter" role="enum">
971
<title>enum CoglMaterialFilter</title>
972
<indexterm zone="CoglMaterialFilter"><primary sortas="MaterialFilter">CoglMaterialFilter</primary></indexterm><programlisting>typedef enum _CoglMaterialFilter
974
COGL_MATERIAL_FILTER_NEAREST = GL_NEAREST,
975
COGL_MATERIAL_FILTER_LINEAR = GL_LINEAR,
976
COGL_MATERIAL_FILTER_NEAREST_MIPMAP_NEAREST = GL_NEAREST_MIPMAP_NEAREST,
977
COGL_MATERIAL_FILTER_LINEAR_MIPMAP_NEAREST = GL_LINEAR_MIPMAP_NEAREST,
978
COGL_MATERIAL_FILTER_NEAREST_MIPMAP_LINEAR = GL_NEAREST_MIPMAP_LINEAR,
979
COGL_MATERIAL_FILTER_LINEAR_MIPMAP_LINEAR = GL_LINEAR_MIPMAP_LINEAR
980
} CoglMaterialFilter;
983
Texture filtering is used whenever the current pixel maps either to more
984
than one texture element (texel) or less than one. These filter enums
985
correspond to different strategies used to come up with a pixel color, by
986
possibly referring to multiple neighbouring texels and taking a weighted
987
average or simply using the nearest texel.</para>
989
</para><variablelist role="enum">
990
<varlistentry id="COGL-MATERIAL-FILTER-NEAREST--CAPS" role="constant">
991
<term><literal>COGL_MATERIAL_FILTER_NEAREST</literal></term>
992
<listitem><simpara> Measuring in manhatten distance from the,
993
current pixel center, use the nearest texture
995
</simpara></listitem>
997
<varlistentry id="COGL-MATERIAL-FILTER-LINEAR--CAPS" role="constant">
998
<term><literal>COGL_MATERIAL_FILTER_LINEAR</literal></term>
999
<listitem><simpara> Use the weighted average of the 4 texels
1000
nearest the current pixel center.
1001
</simpara></listitem>
1003
<varlistentry id="COGL-MATERIAL-FILTER-NEAREST-MIPMAP-NEAREST--CAPS" role="constant">
1004
<term><literal>COGL_MATERIAL_FILTER_NEAREST_MIPMAP_NEAREST</literal></term>
1005
<listitem><simpara> Select the mimap level whose
1006
texel size most closely matches
1007
the current pixel, and use the
1008
COGL_MATERIAL_FILTER_NEAREST
1010
</simpara></listitem>
1012
<varlistentry id="COGL-MATERIAL-FILTER-LINEAR-MIPMAP-NEAREST--CAPS" role="constant">
1013
<term><literal>COGL_MATERIAL_FILTER_LINEAR_MIPMAP_NEAREST</literal></term>
1014
<listitem><simpara> Select the mimap level whose
1015
texel size most closely matches
1016
the current pixel, and use the
1017
COGL_MATERIAL_FILTER_LINEAR
1019
</simpara></listitem>
1021
<varlistentry id="COGL-MATERIAL-FILTER-NEAREST-MIPMAP-LINEAR--CAPS" role="constant">
1022
<term><literal>COGL_MATERIAL_FILTER_NEAREST_MIPMAP_LINEAR</literal></term>
1023
<listitem><simpara> Select the two mimap levels
1024
whose texel size most closely
1025
matches the current pixel, use
1026
the COGL_MATERIAL_FILTER_NEAREST
1027
criterion on each one and take
1028
their weighted average.
1029
</simpara></listitem>
1031
<varlistentry id="COGL-MATERIAL-FILTER-LINEAR-MIPMAP-LINEAR--CAPS" role="constant">
1032
<term><literal>COGL_MATERIAL_FILTER_LINEAR_MIPMAP_LINEAR</literal></term>
1033
<listitem><simpara> Select the two mimap levels
1034
whose texel size most closely
1035
matches the current pixel, use
1036
the COGL_MATERIAL_FILTER_LINEAR
1037
criterion on each one and take
1038
their weighted average.
1039
</simpara></listitem>
1041
</variablelist></refsect2>
1042
<refsect2 id="cogl-material-set-layer-filters" role="function">
1043
<title>cogl_material_set_layer_filters ()</title>
1044
<indexterm zone="cogl-material-set-layer-filters"><primary sortas="material_set_layer_filters">cogl_material_set_layer_filters</primary></indexterm><programlisting><link linkend="void">void</link> cogl_material_set_layer_filters (<link linkend="CoglHandle">CoglHandle</link> handle,
1045
<link linkend="gint">gint</link> layer_index,
1046
<link linkend="CoglMaterialFilter">CoglMaterialFilter</link> min_filter,
1047
<link linkend="CoglMaterialFilter">CoglMaterialFilter</link> mag_filter);</programlisting>
1049
Changes the decimation and interpolation filters used when a texture is
1050
drawn at other scales than 100%.</para>
1052
</para><variablelist role="params">
1053
<varlistentry><term><parameter>handle</parameter> :</term>
1054
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> to a material.
1055
</simpara></listitem></varlistentry>
1056
<varlistentry><term><parameter>layer_index</parameter> :</term>
1057
<listitem><simpara> the layer number to change.
1058
</simpara></listitem></varlistentry>
1059
<varlistentry><term><parameter>min_filter</parameter> :</term>
1060
<listitem><simpara> the filter used when scaling a texture down.
1061
</simpara></listitem></varlistentry>
1062
<varlistentry><term><parameter>mag_filter</parameter> :</term>
1063
<listitem><simpara> the filter used when magnifying a texture.
1064
</simpara></listitem></varlistentry>
1065
</variablelist></refsect2>
1066
<refsect2 id="cogl-material-layer-get-type" role="function">
1067
<title>cogl_material_layer_get_type ()</title>
1068
<indexterm zone="cogl-material-layer-get-type"><primary sortas="material_layer_get_type">cogl_material_layer_get_type</primary></indexterm><programlisting><link linkend="CoglMaterialLayerType">CoglMaterialLayerType</link> cogl_material_layer_get_type (<link linkend="CoglHandle">CoglHandle</link> layer_handle);</programlisting>
1070
Retrieves the type of the layer
1073
Currently there is only one type of layer defined:
1074
<link linkend="COGL-MATERIAL-LAYER-TYPE-TEXTURE--CAPS"><literal>COGL_MATERIAL_LAYER_TYPE_TEXTURE</literal></link>, but considering we may add purely GLSL
1075
based layers in the future, you should write code that checks the type
1078
</para><variablelist role="params">
1079
<varlistentry><term><parameter>layer_handle</parameter> :</term>
1080
<listitem><simpara> A <link linkend="CoglHandle"><type>CoglHandle</type></link> for a material layer
1081
</simpara></listitem></varlistentry>
1082
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the type of the layer
1083
</simpara></listitem></varlistentry>
1084
</variablelist></refsect2>
1085
<refsect2 id="cogl-material-layer-get-texture" role="function">
1086
<title>cogl_material_layer_get_texture ()</title>
1087
<indexterm zone="cogl-material-layer-get-texture"><primary sortas="material_layer_get_texture">cogl_material_layer_get_texture</primary></indexterm><programlisting><link linkend="CoglHandle">CoglHandle</link> cogl_material_layer_get_texture (<link linkend="CoglHandle">CoglHandle</link> layer_handle);</programlisting>
1089
This lets you extract a CoglTexture handle for a specific layer.
1092
<note>In the future, we may support purely GLSL based layers which will
1093
likely return <link linkend="COGL-INVALID-HANDLE--CAPS"><literal>COGL_INVALID_HANDLE</literal></link> if you try to get the texture.
1094
Considering this, you can call cogl_material_layer_get_type first,
1095
to check it is of type <link linkend="COGL-MATERIAL-LAYER-TYPE-TEXTURE--CAPS"><literal>COGL_MATERIAL_LAYER_TYPE_TEXTURE</literal></link>.</note></para>
1097
</para><variablelist role="params">
1098
<varlistentry><term><parameter>layer_handle</parameter> :</term>
1099
<listitem><simpara> A <link linkend="CoglHandle"><type>CoglHandle</type></link> for a material layer
1100
</simpara></listitem></varlistentry>
1101
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for the texture inside <parameter>layer_handle</parameter>
1102
</simpara></listitem></varlistentry>
1103
</variablelist></refsect2>
1104
<refsect2 id="cogl-material-layer-get-min-filter" role="function">
1105
<title>cogl_material_layer_get_min_filter ()</title>
1106
<indexterm zone="cogl-material-layer-get-min-filter"><primary sortas="material_layer_get_min_filter">cogl_material_layer_get_min_filter</primary></indexterm><programlisting><link linkend="CoglMaterialFilter">CoglMaterialFilter</link> cogl_material_layer_get_min_filter (<link linkend="CoglHandle">CoglHandle</link> layer_handle);</programlisting>
1108
Query the currently set downscaling filter for a cogl material layer.</para>
1110
</para><variablelist role="params">
1111
<varlistentry><term><parameter>layer_handle</parameter> :</term>
1112
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a material layer
1113
</simpara></listitem></varlistentry>
1114
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current downscaling filter for a cogl material layer.
1115
</simpara></listitem></varlistentry>
1116
</variablelist></refsect2>
1117
<refsect2 id="cogl-material-layer-get-mag-filter" role="function">
1118
<title>cogl_material_layer_get_mag_filter ()</title>
1119
<indexterm zone="cogl-material-layer-get-mag-filter"><primary sortas="material_layer_get_mag_filter">cogl_material_layer_get_mag_filter</primary></indexterm><programlisting><link linkend="CoglMaterialFilter">CoglMaterialFilter</link> cogl_material_layer_get_mag_filter (<link linkend="CoglHandle">CoglHandle</link> layer_handle);</programlisting>
1121
Query the currently set downscaling filter for a cogl material layer.</para>
1123
</para><variablelist role="params">
1124
<varlistentry><term><parameter>layer_handle</parameter> :</term>
1125
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link> for a material layer
1126
</simpara></listitem></varlistentry>
1127
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current downscaling filter for a cogl material layer.
1128
</simpara></listitem></varlistentry>
1129
</variablelist></refsect2>
added
removed
doc/reference/cogl/xml/cogl-material.xml
