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-General-API">
8
<refentrytitle role="top_of_page" id="cogl-General-API.top_of_page">General API</refentrytitle>
9
<manvolnum>3</manvolnum>
10
<refmiscinfo>COGL Library</refmiscinfo>
14
<refname>General API</refname>
15
<refpurpose>General purpose API</refpurpose>
18
<refsynopsisdiv id="cogl-General-API.synopsis" role="synopsis">
19
<title role="synopsis.title">Synopsis</title>
22
#define <link linkend="COGL-INVALID-HANDLE--CAPS">COGL_INVALID_HANDLE</link>
23
typedef <link linkend="CoglHandle">CoglHandle</link>;
24
<link linkend="CoglHandle">CoglHandle</link> <link linkend="cogl-handle-ref">cogl_handle_ref</link> (<link linkend="CoglHandle">CoglHandle</link> handle);
25
<link linkend="void">void</link> <link linkend="cogl-handle-unref">cogl_handle_unref</link> (<link linkend="CoglHandle">CoglHandle</link> Handle);
27
<link linkend="void">void</link> (<link linkend="CoglFuncPtr">*CoglFuncPtr</link>) (void);
28
#define <link linkend="COGL-PIXEL-FORMAT-24--CAPS">COGL_PIXEL_FORMAT_24</link>
29
#define <link linkend="COGL-PIXEL-FORMAT-32--CAPS">COGL_PIXEL_FORMAT_32</link>
30
#define <link linkend="COGL-A-BIT--CAPS">COGL_A_BIT</link>
31
#define <link linkend="COGL-BGR-BIT--CAPS">COGL_BGR_BIT</link>
32
#define <link linkend="COGL-AFIRST-BIT--CAPS">COGL_AFIRST_BIT</link>
33
#define <link linkend="COGL-PREMULT-BIT--CAPS">COGL_PREMULT_BIT</link>
34
#define <link linkend="COGL-UNORDERED-MASK--CAPS">COGL_UNORDERED_MASK</link>
35
#define <link linkend="COGL-UNPREMULT-MASK--CAPS">COGL_UNPREMULT_MASK</link>
36
enum <link linkend="CoglPixelFormat">CoglPixelFormat</link>;
37
enum <link linkend="CoglBufferTarget">CoglBufferTarget</link>;
38
enum <link linkend="CoglBufferBit">CoglBufferBit</link>;
39
enum <link linkend="CoglAttributeType">CoglAttributeType</link>;
41
enum <link linkend="CoglFeatureFlags">CoglFeatureFlags</link>;
42
<link linkend="CoglFeatureFlags">CoglFeatureFlags</link> <link linkend="cogl-get-features">cogl_get_features</link> (void);
43
<link linkend="gboolean">gboolean</link> <link linkend="cogl-features-available">cogl_features_available</link> (<link linkend="CoglFeatureFlags">CoglFeatureFlags</link> features);
44
<link linkend="gboolean">gboolean</link> <link linkend="cogl-check-extension">cogl_check_extension</link> (const <link linkend="gchar">gchar</link> *name,
45
const <link linkend="gchar">gchar</link> *ext);
46
<link linkend="CoglFuncPtr">CoglFuncPtr</link> <link linkend="cogl-get-proc-address">cogl_get_proc_address</link> (const <link linkend="gchar">gchar</link> *name);
47
<link linkend="GOptionGroup">GOptionGroup</link> * <link linkend="cogl-get-option-group">cogl_get_option_group</link> (void);
49
<link linkend="void">void</link> <link linkend="cogl-push-matrix">cogl_push_matrix</link> (void);
50
<link linkend="void">void</link> <link linkend="cogl-pop-matrix">cogl_pop_matrix</link> (void);
51
<link linkend="void">void</link> <link linkend="cogl-scale">cogl_scale</link> (<link linkend="float">float</link> x,
52
<link linkend="float">float</link> y,
53
<link linkend="float">float</link> z);
54
<link linkend="void">void</link> <link linkend="cogl-translate">cogl_translate</link> (<link linkend="float">float</link> x,
55
<link linkend="float">float</link> y,
56
<link linkend="float">float</link> z);
57
<link linkend="void">void</link> <link linkend="cogl-rotate">cogl_rotate</link> (<link linkend="float">float</link> angle,
58
<link linkend="float">float</link> x,
59
<link linkend="float">float</link> y,
60
<link linkend="float">float</link> z);
61
<link linkend="void">void</link> <link linkend="cogl-frustum">cogl_frustum</link> (<link linkend="float">float</link> left,
62
<link linkend="float">float</link> right,
63
<link linkend="float">float</link> bottom,
64
<link linkend="float">float</link> top,
65
<link linkend="float">float</link> z_near,
66
<link linkend="float">float</link> z_far);
67
<link linkend="void">void</link> <link linkend="cogl-perspective">cogl_perspective</link> (<link linkend="float">float</link> fovy,
68
<link linkend="float">float</link> aspect,
69
<link linkend="float">float</link> z_near,
70
<link linkend="float">float</link> z_far);
71
<link linkend="void">void</link> <link linkend="cogl-ortho">cogl_ortho</link> (<link linkend="float">float</link> left,
72
<link linkend="float">float</link> right,
73
<link linkend="float">float</link> bottom,
74
<link linkend="float">float</link> top,
75
<link linkend="float">float</link> near,
76
<link linkend="float">float</link> far);
78
<link linkend="void">void</link> <link linkend="cogl-get-modelview-matrix">cogl_get_modelview_matrix</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix);
79
<link linkend="void">void</link> <link linkend="cogl-set-modelview-matrix">cogl_set_modelview_matrix</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix);
80
<link linkend="void">void</link> <link linkend="cogl-get-projection-matrix">cogl_get_projection_matrix</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix);
81
<link linkend="void">void</link> <link linkend="cogl-set-projection-matrix">cogl_set_projection_matrix</link> (<link linkend="CoglMatrix">CoglMatrix</link> *matrix);
82
<link linkend="void">void</link> <link linkend="cogl-viewport">cogl_viewport</link> (<link linkend="guint">guint</link> width,
83
<link linkend="guint">guint</link> height);
84
<link linkend="void">void</link> <link linkend="cogl-get-viewport">cogl_get_viewport</link> (<link linkend="float">float</link> v[4]);
86
<link linkend="void">void</link> <link linkend="cogl-clear">cogl_clear</link> (const <link linkend="CoglColor">CoglColor</link> *color,
87
<link linkend="gulong">gulong</link> buffers);
88
<link linkend="void">void</link> <link linkend="cogl-get-bitmasks">cogl_get_bitmasks</link> (<link linkend="gint">gint</link> *red,
89
<link linkend="gint">gint</link> *green,
90
<link linkend="gint">gint</link> *blue,
91
<link linkend="gint">gint</link> *alpha);
92
<link linkend="void">void</link> <link linkend="cogl-set-depth-test-enabled">cogl_set_depth_test_enabled</link> (<link linkend="gboolean">gboolean</link> setting);
93
<link linkend="gboolean">gboolean</link> <link linkend="cogl-get-depth-test-enabled">cogl_get_depth_test_enabled</link> (void);
94
<link linkend="void">void</link> <link linkend="cogl-set-backface-culling-enabled">cogl_set_backface_culling_enabled</link> (<link linkend="gboolean">gboolean</link> setting);
95
<link linkend="gboolean">gboolean</link> <link linkend="cogl-get-backface-culling-enabled">cogl_get_backface_culling_enabled</link> (void);
97
enum <link linkend="CoglFogMode">CoglFogMode</link>;
98
<link linkend="void">void</link> <link linkend="cogl-set-fog">cogl_set_fog</link> (const <link linkend="CoglColor">CoglColor</link> *fog_color,
99
<link linkend="CoglFogMode">CoglFogMode</link> mode,
100
<link linkend="float">float</link> density,
101
<link linkend="float">float</link> z_near,
102
<link linkend="float">float</link> z_far);
103
<link linkend="void">void</link> <link linkend="cogl-disable-fog">cogl_disable_fog</link> (void);
105
<link linkend="void">void</link> <link linkend="cogl-set-source">cogl_set_source</link> (<link linkend="CoglHandle">CoglHandle</link> material);
106
<link linkend="void">void</link> <link linkend="cogl-set-source-color">cogl_set_source_color</link> (const <link linkend="CoglColor">CoglColor</link> *color);
107
<link linkend="void">void</link> <link linkend="cogl-set-source-color4ub">cogl_set_source_color4ub</link> (<link linkend="guint8">guint8</link> red,
108
<link linkend="guint8">guint8</link> green,
109
<link linkend="guint8">guint8</link> blue,
110
<link linkend="guint8">guint8</link> alpha);
111
<link linkend="void">void</link> <link linkend="cogl-set-source-color4f">cogl_set_source_color4f</link> (<link linkend="float">float</link> red,
112
<link linkend="float">float</link> green,
113
<link linkend="float">float</link> blue,
114
<link linkend="float">float</link> alpha);
115
<link linkend="void">void</link> <link linkend="cogl-set-source-texture">cogl_set_source_texture</link> (<link linkend="CoglHandle">CoglHandle</link> texture_handle);
117
enum <link linkend="CoglReadPixelsFlags">CoglReadPixelsFlags</link>;
118
<link linkend="void">void</link> <link linkend="cogl-read-pixels">cogl_read_pixels</link> (<link linkend="int">int</link> x,
119
<link linkend="int">int</link> y,
120
<link linkend="int">int</link> width,
121
<link linkend="int">int</link> height,
122
<link linkend="CoglReadPixelsFlags">CoglReadPixelsFlags</link> source,
123
<link linkend="CoglPixelFormat">CoglPixelFormat</link> format,
124
<link linkend="guint8">guint8</link> *pixels);
126
<link linkend="void">void</link> <link linkend="cogl-flush">cogl_flush</link> (void);
127
<link linkend="void">void</link> <link linkend="cogl-begin-gl">cogl_begin_gl</link> (void);
128
<link linkend="void">void</link> <link linkend="cogl-end-gl">cogl_end_gl</link> (void);
140
<refsect1 id="cogl-General-API.description" role="desc">
141
<title role="desc.title">Description</title>
143
General utility functions for COGL.</para>
148
<refsect1 id="cogl-General-API.details" role="details">
149
<title role="details.title">Details</title>
150
<refsect2 id="COGL-INVALID-HANDLE--CAPS" role="macro">
151
<title>COGL_INVALID_HANDLE</title>
152
<indexterm zone="COGL-INVALID-HANDLE--CAPS"><primary sortas="INVALID_HANDLE">COGL_INVALID_HANDLE</primary></indexterm><programlisting>#define COGL_INVALID_HANDLE NULL
155
A COGL handle that is not valid, used for unitialized handles as well as
156
error conditions.</para>
159
<refsect2 id="CoglHandle" role="typedef">
160
<title>CoglHandle</title>
161
<indexterm zone="CoglHandle"><primary sortas="Handle">CoglHandle</primary></indexterm><programlisting>typedef gpointer CoglHandle;
164
Type used for storing references to cogl objects, the CoglHandle is
165
a fully opaque type without any public data members.</para>
168
<refsect2 id="cogl-handle-ref" role="function">
169
<title>cogl_handle_ref ()</title>
170
<indexterm zone="cogl-handle-ref"><primary sortas="handle_ref">cogl_handle_ref</primary></indexterm><programlisting><link linkend="CoglHandle">CoglHandle</link> cogl_handle_ref (<link linkend="CoglHandle">CoglHandle</link> handle);</programlisting>
172
Increases the reference count of <parameter>handle</parameter> by 1</para>
174
</para><variablelist role="params">
175
<varlistentry><term><parameter>handle</parameter> :</term>
176
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link>
177
</simpara></listitem></varlistentry>
178
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the handle, with its reference count increased
179
</simpara></listitem></varlistentry>
180
</variablelist></refsect2>
181
<refsect2 id="cogl-handle-unref" role="function">
182
<title>cogl_handle_unref ()</title>
183
<indexterm zone="cogl-handle-unref"><primary sortas="handle_unref">cogl_handle_unref</primary></indexterm><programlisting><link linkend="void">void</link> cogl_handle_unref (<link linkend="CoglHandle">CoglHandle</link> Handle);</programlisting>
185
Drecreases the reference count of <parameter>handle</parameter> by 1; if the reference
186
count reaches 0, the resources allocated by <parameter>handle</parameter> will be freed</para>
188
</para><variablelist role="params">
189
<varlistentry><term><parameter>Handle</parameter> :</term>
190
<listitem><simpara> a <link linkend="CoglHandle"><type>CoglHandle</type></link>
191
</simpara></listitem></varlistentry>
192
</variablelist></refsect2>
193
<refsect2 id="CoglFuncPtr" role="function">
194
<title>CoglFuncPtr ()</title>
195
<indexterm zone="CoglFuncPtr"><primary sortas="FuncPtr">CoglFuncPtr</primary></indexterm><programlisting><link linkend="void">void</link> (*CoglFuncPtr) (void);</programlisting>
197
The type used by cogl for function pointers, note that this type
198
is used as a generic catch-all cast for function pointers and the
199
actual arguments and return type may be different.</para>
202
<refsect2 id="COGL-PIXEL-FORMAT-24--CAPS" role="macro">
203
<title>COGL_PIXEL_FORMAT_24</title>
204
<indexterm zone="COGL-PIXEL-FORMAT-24--CAPS"><primary sortas="PIXEL_FORMAT_24">COGL_PIXEL_FORMAT_24</primary></indexterm><programlisting>#define COGL_PIXEL_FORMAT_24 2
208
<refsect2 id="COGL-PIXEL-FORMAT-32--CAPS" role="macro">
209
<title>COGL_PIXEL_FORMAT_32</title>
210
<indexterm zone="COGL-PIXEL-FORMAT-32--CAPS"><primary sortas="PIXEL_FORMAT_32">COGL_PIXEL_FORMAT_32</primary></indexterm><programlisting>#define COGL_PIXEL_FORMAT_32 3
214
<refsect2 id="COGL-A-BIT--CAPS" role="macro">
215
<title>COGL_A_BIT</title>
216
<indexterm zone="COGL-A-BIT--CAPS"><primary sortas="A_BIT">COGL_A_BIT</primary></indexterm><programlisting>#define COGL_A_BIT (1 << 4)
220
<refsect2 id="COGL-BGR-BIT--CAPS" role="macro">
221
<title>COGL_BGR_BIT</title>
222
<indexterm zone="COGL-BGR-BIT--CAPS"><primary sortas="BGR_BIT">COGL_BGR_BIT</primary></indexterm><programlisting>#define COGL_BGR_BIT (1 << 5)
226
<refsect2 id="COGL-AFIRST-BIT--CAPS" role="macro">
227
<title>COGL_AFIRST_BIT</title>
228
<indexterm zone="COGL-AFIRST-BIT--CAPS"><primary sortas="AFIRST_BIT">COGL_AFIRST_BIT</primary></indexterm><programlisting>#define COGL_AFIRST_BIT (1 << 6)
232
<refsect2 id="COGL-PREMULT-BIT--CAPS" role="macro">
233
<title>COGL_PREMULT_BIT</title>
234
<indexterm zone="COGL-PREMULT-BIT--CAPS"><primary sortas="PREMULT_BIT">COGL_PREMULT_BIT</primary></indexterm><programlisting>#define COGL_PREMULT_BIT (1 << 7)
238
<refsect2 id="COGL-UNORDERED-MASK--CAPS" role="macro">
239
<title>COGL_UNORDERED_MASK</title>
240
<indexterm zone="COGL-UNORDERED-MASK--CAPS"><primary sortas="UNORDERED_MASK">COGL_UNORDERED_MASK</primary></indexterm><programlisting>#define COGL_UNORDERED_MASK 0x0F
244
<refsect2 id="COGL-UNPREMULT-MASK--CAPS" role="macro">
245
<title>COGL_UNPREMULT_MASK</title>
246
<indexterm zone="COGL-UNPREMULT-MASK--CAPS"><primary sortas="UNPREMULT_MASK">COGL_UNPREMULT_MASK</primary></indexterm><programlisting>#define COGL_UNPREMULT_MASK 0x7F
250
<refsect2 id="CoglPixelFormat" role="enum" condition="since:0.8">
251
<title>enum CoglPixelFormat</title>
252
<indexterm zone="CoglPixelFormat" role="0.8"><primary sortas="PixelFormat">CoglPixelFormat</primary></indexterm><programlisting>typedef enum { /*< prefix=COGL_PIXEL_FORMAT >*/
253
COGL_PIXEL_FORMAT_ANY = 0,
254
COGL_PIXEL_FORMAT_A_8 = 1 | COGL_A_BIT,
256
COGL_PIXEL_FORMAT_RGB_565 = 4,
257
COGL_PIXEL_FORMAT_RGBA_4444 = 5 | COGL_A_BIT,
258
COGL_PIXEL_FORMAT_RGBA_5551 = 6 | COGL_A_BIT,
259
COGL_PIXEL_FORMAT_YUV = 7,
260
COGL_PIXEL_FORMAT_G_8 = 8,
262
COGL_PIXEL_FORMAT_RGB_888 = COGL_PIXEL_FORMAT_24,
263
COGL_PIXEL_FORMAT_BGR_888 = (COGL_PIXEL_FORMAT_24 | COGL_BGR_BIT),
265
COGL_PIXEL_FORMAT_RGBA_8888 = (COGL_PIXEL_FORMAT_32 | COGL_A_BIT),
266
COGL_PIXEL_FORMAT_BGRA_8888 = (COGL_PIXEL_FORMAT_32 | COGL_A_BIT | COGL_BGR_BIT),
267
COGL_PIXEL_FORMAT_ARGB_8888 = (COGL_PIXEL_FORMAT_32 | COGL_A_BIT | COGL_AFIRST_BIT),
268
COGL_PIXEL_FORMAT_ABGR_8888 = (COGL_PIXEL_FORMAT_32 | COGL_A_BIT | COGL_BGR_BIT | COGL_AFIRST_BIT),
270
COGL_PIXEL_FORMAT_RGBA_8888_PRE = (COGL_PIXEL_FORMAT_32 | COGL_A_BIT | COGL_PREMULT_BIT),
271
COGL_PIXEL_FORMAT_BGRA_8888_PRE = (COGL_PIXEL_FORMAT_32 | COGL_A_BIT | COGL_PREMULT_BIT | COGL_BGR_BIT),
272
COGL_PIXEL_FORMAT_ARGB_8888_PRE = (COGL_PIXEL_FORMAT_32 | COGL_A_BIT | COGL_PREMULT_BIT | COGL_AFIRST_BIT),
273
COGL_PIXEL_FORMAT_ABGR_8888_PRE = (COGL_PIXEL_FORMAT_32 | COGL_A_BIT | COGL_PREMULT_BIT | COGL_BGR_BIT | COGL_AFIRST_BIT),
274
COGL_PIXEL_FORMAT_RGBA_4444_PRE = (COGL_PIXEL_FORMAT_RGBA_4444 | COGL_A_BIT | COGL_PREMULT_BIT),
275
COGL_PIXEL_FORMAT_RGBA_5551_PRE = (COGL_PIXEL_FORMAT_RGBA_5551 | COGL_A_BIT | COGL_PREMULT_BIT),
279
Pixel formats used by COGL.</para>
281
</para><variablelist role="enum">
282
<varlistentry id="COGL-PIXEL-FORMAT-ANY--CAPS" role="constant">
283
<term><literal>COGL_PIXEL_FORMAT_ANY</literal></term>
284
<listitem><simpara> Any format
285
</simpara></listitem>
287
<varlistentry id="COGL-PIXEL-FORMAT-A-8--CAPS" role="constant">
288
<term><literal>COGL_PIXEL_FORMAT_A_8</literal></term>
289
<listitem><simpara> 8 bits alpha mask
290
</simpara></listitem>
292
<varlistentry id="COGL-PIXEL-FORMAT-RGB-565--CAPS" role="constant">
293
<term><literal>COGL_PIXEL_FORMAT_RGB_565</literal></term>
294
<listitem><simpara> RGB, 16 bits
295
</simpara></listitem>
297
<varlistentry id="COGL-PIXEL-FORMAT-RGBA-4444--CAPS" role="constant">
298
<term><literal>COGL_PIXEL_FORMAT_RGBA_4444</literal></term>
299
<listitem><simpara> RGBA, 16 bits
300
</simpara></listitem>
302
<varlistentry id="COGL-PIXEL-FORMAT-RGBA-5551--CAPS" role="constant">
303
<term><literal>COGL_PIXEL_FORMAT_RGBA_5551</literal></term>
304
<listitem><simpara> RGBA, 16 bits
305
</simpara></listitem>
307
<varlistentry id="COGL-PIXEL-FORMAT-YUV--CAPS" role="constant">
308
<term><literal>COGL_PIXEL_FORMAT_YUV</literal></term>
309
<listitem><simpara> FIXME
310
</simpara></listitem>
312
<varlistentry id="COGL-PIXEL-FORMAT-G-8--CAPS" role="constant">
313
<term><literal>COGL_PIXEL_FORMAT_G_8</literal></term>
314
<listitem><simpara> FIXME
315
</simpara></listitem>
317
<varlistentry id="COGL-PIXEL-FORMAT-RGB-888--CAPS" role="constant">
318
<term><literal>COGL_PIXEL_FORMAT_RGB_888</literal></term>
319
<listitem><simpara> RGB, 24 bits
320
</simpara></listitem>
322
<varlistentry id="COGL-PIXEL-FORMAT-BGR-888--CAPS" role="constant">
323
<term><literal>COGL_PIXEL_FORMAT_BGR_888</literal></term>
324
<listitem><simpara> BGR, 24 bits
325
</simpara></listitem>
327
<varlistentry id="COGL-PIXEL-FORMAT-RGBA-8888--CAPS" role="constant">
328
<term><literal>COGL_PIXEL_FORMAT_RGBA_8888</literal></term>
329
<listitem><simpara> RGBA, 32 bits
330
</simpara></listitem>
332
<varlistentry id="COGL-PIXEL-FORMAT-BGRA-8888--CAPS" role="constant">
333
<term><literal>COGL_PIXEL_FORMAT_BGRA_8888</literal></term>
334
<listitem><simpara> BGRA, 32 bits
335
</simpara></listitem>
337
<varlistentry id="COGL-PIXEL-FORMAT-ARGB-8888--CAPS" role="constant">
338
<term><literal>COGL_PIXEL_FORMAT_ARGB_8888</literal></term>
339
<listitem><simpara> ARGB, 32 bits
340
</simpara></listitem>
342
<varlistentry id="COGL-PIXEL-FORMAT-ABGR-8888--CAPS" role="constant">
343
<term><literal>COGL_PIXEL_FORMAT_ABGR_8888</literal></term>
344
<listitem><simpara> ABGR, 32 bits
345
</simpara></listitem>
347
<varlistentry id="COGL-PIXEL-FORMAT-RGBA-8888-PRE--CAPS" role="constant">
348
<term><literal>COGL_PIXEL_FORMAT_RGBA_8888_PRE</literal></term>
349
<listitem><simpara> Premultiplied RGBA, 32 bits
350
</simpara></listitem>
352
<varlistentry id="COGL-PIXEL-FORMAT-BGRA-8888-PRE--CAPS" role="constant">
353
<term><literal>COGL_PIXEL_FORMAT_BGRA_8888_PRE</literal></term>
354
<listitem><simpara> Premultiplied BGRA, 32 bits
355
</simpara></listitem>
357
<varlistentry id="COGL-PIXEL-FORMAT-ARGB-8888-PRE--CAPS" role="constant">
358
<term><literal>COGL_PIXEL_FORMAT_ARGB_8888_PRE</literal></term>
359
<listitem><simpara> Premultiplied ARGB, 32 bits
360
</simpara></listitem>
362
<varlistentry id="COGL-PIXEL-FORMAT-ABGR-8888-PRE--CAPS" role="constant">
363
<term><literal>COGL_PIXEL_FORMAT_ABGR_8888_PRE</literal></term>
364
<listitem><simpara> Premultiplied ABGR, 32 bits
365
</simpara></listitem>
367
<varlistentry id="COGL-PIXEL-FORMAT-RGBA-4444-PRE--CAPS" role="constant">
368
<term><literal>COGL_PIXEL_FORMAT_RGBA_4444_PRE</literal></term>
369
<listitem><simpara> Premultiplied RGBA, 16 bits
370
</simpara></listitem>
372
<varlistentry id="COGL-PIXEL-FORMAT-RGBA-5551-PRE--CAPS" role="constant">
373
<term><literal>COGL_PIXEL_FORMAT_RGBA_5551_PRE</literal></term>
374
<listitem><simpara> Premultiplied RGBA, 16 bits
375
</simpara></listitem>
377
</variablelist><para role="since">Since 0.8</para></refsect2>
378
<refsect2 id="CoglBufferTarget" role="enum" condition="since:0.8">
379
<title>enum CoglBufferTarget</title>
380
<indexterm zone="CoglBufferTarget" role="0.8"><primary sortas="BufferTarget">CoglBufferTarget</primary></indexterm><programlisting>typedef enum
382
COGL_WINDOW_BUFFER = (1 << 1),
383
COGL_OFFSCREEN_BUFFER = (1 << 2)
387
Target flags for FBOs.</para>
389
</para><variablelist role="enum">
390
<varlistentry id="COGL-WINDOW-BUFFER--CAPS" role="constant">
391
<term><literal>COGL_WINDOW_BUFFER</literal></term>
392
<listitem><simpara> FIXME
393
</simpara></listitem>
395
<varlistentry id="COGL-OFFSCREEN-BUFFER--CAPS" role="constant">
396
<term><literal>COGL_OFFSCREEN_BUFFER</literal></term>
397
<listitem><simpara> FIXME
398
</simpara></listitem>
400
</variablelist><para role="since">Since 0.8</para></refsect2>
401
<refsect2 id="CoglBufferBit" role="enum" condition="since:1.0">
402
<title>enum CoglBufferBit</title>
403
<indexterm zone="CoglBufferBit" role="1.0"><primary sortas="BufferBit">CoglBufferBit</primary></indexterm><programlisting>typedef enum {
404
COGL_BUFFER_BIT_COLOR = 1L<<0,
405
COGL_BUFFER_BIT_DEPTH = 1L<<1,
406
COGL_BUFFER_BIT_STENCIL = 1L<<2
410
Types of auxiliary buffers</para>
412
</para><variablelist role="enum">
413
<varlistentry id="COGL-BUFFER-BIT-COLOR--CAPS" role="constant">
414
<term><literal>COGL_BUFFER_BIT_COLOR</literal></term>
415
<listitem><simpara> Selects the primary color buffer
416
</simpara></listitem>
418
<varlistentry id="COGL-BUFFER-BIT-DEPTH--CAPS" role="constant">
419
<term><literal>COGL_BUFFER_BIT_DEPTH</literal></term>
420
<listitem><simpara> Selects the depth buffer
421
</simpara></listitem>
423
<varlistentry id="COGL-BUFFER-BIT-STENCIL--CAPS" role="constant">
424
<term><literal>COGL_BUFFER_BIT_STENCIL</literal></term>
425
<listitem><simpara> Selects the stencil buffer
426
</simpara></listitem>
428
</variablelist><para role="since">Since 1.0</para></refsect2>
429
<refsect2 id="CoglAttributeType" role="enum" condition="since:1.0">
430
<title>enum CoglAttributeType</title>
431
<indexterm zone="CoglAttributeType" role="1.0"><primary sortas="AttributeType">CoglAttributeType</primary></indexterm><programlisting>typedef enum _CoglAttributeType
433
COGL_ATTRIBUTE_TYPE_BYTE = GL_BYTE,
434
COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE = GL_UNSIGNED_BYTE,
435
COGL_ATTRIBUTE_TYPE_SHORT = GL_SHORT,
436
COGL_ATTRIBUTE_TYPE_UNSIGNED_SHORT = GL_UNSIGNED_SHORT,
437
COGL_ATTRIBUTE_TYPE_FLOAT = GL_FLOAT
441
Data types for the components of <link linkend="cogl-vertex-buffer-add"><function>cogl_vertex_buffer_add()</function></link></para>
443
</para><variablelist role="enum">
444
<varlistentry id="COGL-ATTRIBUTE-TYPE-BYTE--CAPS" role="constant">
445
<term><literal>COGL_ATTRIBUTE_TYPE_BYTE</literal></term>
446
<listitem><simpara> Data is the same size of a byte
447
</simpara></listitem>
449
<varlistentry id="COGL-ATTRIBUTE-TYPE-UNSIGNED-BYTE--CAPS" role="constant">
450
<term><literal>COGL_ATTRIBUTE_TYPE_UNSIGNED_BYTE</literal></term>
451
<listitem><simpara> Data is the same size of an
453
</simpara></listitem>
455
<varlistentry id="COGL-ATTRIBUTE-TYPE-SHORT--CAPS" role="constant">
456
<term><literal>COGL_ATTRIBUTE_TYPE_SHORT</literal></term>
457
<listitem><simpara> Data is the same size of a short integer
458
</simpara></listitem>
460
<varlistentry id="COGL-ATTRIBUTE-TYPE-UNSIGNED-SHORT--CAPS" role="constant">
461
<term><literal>COGL_ATTRIBUTE_TYPE_UNSIGNED_SHORT</literal></term>
462
<listitem><simpara> Data is the same size of
463
an unsigned short integer
464
</simpara></listitem>
466
<varlistentry id="COGL-ATTRIBUTE-TYPE-FLOAT--CAPS" role="constant">
467
<term><literal>COGL_ATTRIBUTE_TYPE_FLOAT</literal></term>
468
<listitem><simpara> Data is the same size of a float
469
</simpara></listitem>
471
</variablelist><para role="since">Since 1.0</para></refsect2>
472
<refsect2 id="CoglFeatureFlags" role="enum" condition="since:0.8">
473
<title>enum CoglFeatureFlags</title>
474
<indexterm zone="CoglFeatureFlags" role="0.8"><primary sortas="FeatureFlags">CoglFeatureFlags</primary></indexterm><programlisting>typedef enum
476
COGL_FEATURE_TEXTURE_RECTANGLE = (1 << 1),
477
COGL_FEATURE_TEXTURE_NPOT = (1 << 2),
478
COGL_FEATURE_TEXTURE_YUV = (1 << 3),
479
COGL_FEATURE_TEXTURE_READ_PIXELS = (1 << 4),
480
COGL_FEATURE_SHADERS_GLSL = (1 << 5),
481
COGL_FEATURE_OFFSCREEN = (1 << 6),
482
COGL_FEATURE_OFFSCREEN_MULTISAMPLE = (1 << 7),
483
COGL_FEATURE_OFFSCREEN_BLIT = (1 << 8),
484
COGL_FEATURE_FOUR_CLIP_PLANES = (1 << 9),
485
COGL_FEATURE_STENCIL_BUFFER = (1 << 10),
486
COGL_FEATURE_VBOS = (1 << 11)
490
Flags for the supported features.</para>
492
</para><variablelist role="enum">
493
<varlistentry id="COGL-FEATURE-TEXTURE-RECTANGLE--CAPS" role="constant">
494
<term><literal>COGL_FEATURE_TEXTURE_RECTANGLE</literal></term>
495
<listitem><simpara> ARB_texture_rectangle support
496
</simpara></listitem>
498
<varlistentry id="COGL-FEATURE-TEXTURE-NPOT--CAPS" role="constant">
499
<term><literal>COGL_FEATURE_TEXTURE_NPOT</literal></term>
500
<listitem><simpara> ARB_texture_non_power_of_two support
501
</simpara></listitem>
503
<varlistentry id="COGL-FEATURE-TEXTURE-YUV--CAPS" role="constant">
504
<term><literal>COGL_FEATURE_TEXTURE_YUV</literal></term>
505
<listitem><simpara> ycbcr conversion support
506
</simpara></listitem>
508
<varlistentry id="COGL-FEATURE-TEXTURE-READ-PIXELS--CAPS" role="constant">
509
<term><literal>COGL_FEATURE_TEXTURE_READ_PIXELS</literal></term>
510
<listitem><simpara> <link linkend="glReadPixels"><function>glReadPixels()</function></link> support
511
</simpara></listitem>
513
<varlistentry id="COGL-FEATURE-SHADERS-GLSL--CAPS" role="constant">
514
<term><literal>COGL_FEATURE_SHADERS_GLSL</literal></term>
515
<listitem><simpara> GLSL support
516
</simpara></listitem>
518
<varlistentry id="COGL-FEATURE-OFFSCREEN--CAPS" role="constant">
519
<term><literal>COGL_FEATURE_OFFSCREEN</literal></term>
520
<listitem><simpara> FBO support
521
</simpara></listitem>
523
<varlistentry id="COGL-FEATURE-OFFSCREEN-MULTISAMPLE--CAPS" role="constant">
524
<term><literal>COGL_FEATURE_OFFSCREEN_MULTISAMPLE</literal></term>
525
<listitem><simpara> Multisample support on FBOs
526
</simpara></listitem>
528
<varlistentry id="COGL-FEATURE-OFFSCREEN-BLIT--CAPS" role="constant">
529
<term><literal>COGL_FEATURE_OFFSCREEN_BLIT</literal></term>
530
<listitem><simpara> Blit support on FBOs
531
</simpara></listitem>
533
<varlistentry id="COGL-FEATURE-FOUR-CLIP-PLANES--CAPS" role="constant">
534
<term><literal>COGL_FEATURE_FOUR_CLIP_PLANES</literal></term>
535
<listitem><simpara> At least 4 clip planes available
536
</simpara></listitem>
538
<varlistentry id="COGL-FEATURE-STENCIL-BUFFER--CAPS" role="constant">
539
<term><literal>COGL_FEATURE_STENCIL_BUFFER</literal></term>
540
<listitem><simpara> Stencil buffer support
541
</simpara></listitem>
543
<varlistentry id="COGL-FEATURE-VBOS--CAPS" role="constant">
544
<term><literal>COGL_FEATURE_VBOS</literal></term>
545
<listitem><simpara> VBO support
546
</simpara></listitem>
548
</variablelist><para role="since">Since 0.8</para></refsect2>
549
<refsect2 id="cogl-get-features" role="function" condition="since:0.8">
550
<title>cogl_get_features ()</title>
551
<indexterm zone="cogl-get-features" role="0.8"><primary sortas="get_features">cogl_get_features</primary></indexterm><programlisting><link linkend="CoglFeatureFlags">CoglFeatureFlags</link> cogl_get_features (void);</programlisting>
553
Returns all of the features supported by COGL.</para>
555
</para><variablelist role="params">
556
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A logical OR of all the supported COGL features.
558
</simpara></listitem></varlistentry>
559
</variablelist><para role="since">Since 0.8</para></refsect2>
560
<refsect2 id="cogl-features-available" role="function">
561
<title>cogl_features_available ()</title>
562
<indexterm zone="cogl-features-available"><primary sortas="features_available">cogl_features_available</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_features_available (<link linkend="CoglFeatureFlags">CoglFeatureFlags</link> features);</programlisting>
564
Checks whether the given COGL features are available. Multiple
565
features can be checked for by or-ing them together with the '|'
566
operator. <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> is only returned if all of the requested features
567
are available.</para>
569
</para><variablelist role="params">
570
<varlistentry><term><parameter>features</parameter> :</term>
571
<listitem><simpara> A bitmask of features to check for
572
</simpara></listitem></varlistentry>
573
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the features are available, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
574
</simpara></listitem></varlistentry>
575
</variablelist></refsect2>
576
<refsect2 id="cogl-check-extension" role="function">
577
<title>cogl_check_extension ()</title>
578
<indexterm zone="cogl-check-extension"><primary sortas="check_extension">cogl_check_extension</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_check_extension (const <link linkend="gchar">gchar</link> *name,
579
const <link linkend="gchar">gchar</link> *ext);</programlisting>
581
Check whether <parameter>name</parameter> occurs in list of extensions in <parameter>ext</parameter>.</para>
583
</para><variablelist role="params">
584
<varlistentry><term><parameter>name</parameter> :</term>
585
<listitem><simpara> extension to check for
586
</simpara></listitem></varlistentry>
587
<varlistentry><term><parameter>ext</parameter> :</term>
588
<listitem><simpara> list of extensions
589
</simpara></listitem></varlistentry>
590
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the extension occurs in the list, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwize.
591
</simpara></listitem></varlistentry>
592
</variablelist></refsect2>
593
<refsect2 id="cogl-get-proc-address" role="function">
594
<title>cogl_get_proc_address ()</title>
595
<indexterm zone="cogl-get-proc-address"><primary sortas="get_proc_address">cogl_get_proc_address</primary></indexterm><programlisting><link linkend="CoglFuncPtr">CoglFuncPtr</link> cogl_get_proc_address (const <link linkend="gchar">gchar</link> *name);</programlisting>
597
Gets a pointer to a given GL or GL ES extension function. This acts
598
as a wrapper around <link linkend="glXGetProcAddress"><function>glXGetProcAddress()</function></link> or whatever is the
599
appropriate function for the current backend.</para>
601
</para><variablelist role="params">
602
<varlistentry><term><parameter>name</parameter> :</term>
603
<listitem><simpara> the name of the function.
604
</simpara></listitem></varlistentry>
605
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a pointer to the requested function or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the
606
function is not available.
607
</simpara></listitem></varlistentry>
608
</variablelist></refsect2>
609
<refsect2 id="cogl-get-option-group" role="function" condition="since:1.0">
610
<title>cogl_get_option_group ()</title>
611
<indexterm zone="cogl-get-option-group" role="1.0"><primary sortas="get_option_group">cogl_get_option_group</primary></indexterm><programlisting><link linkend="GOptionGroup">GOptionGroup</link> * cogl_get_option_group (void);</programlisting>
613
Retrieves the <link linkend="GOptionGroup"><type>GOptionGroup</type></link> used by COGL to parse the command
614
line options. Clutter uses this to handle the COGL command line
615
options during its initialization process.</para>
617
</para><variablelist role="params">
618
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
620
</simpara></listitem></varlistentry>
621
</variablelist><para role="since">Since 1.0</para></refsect2>
622
<refsect2 id="cogl-push-matrix" role="function">
623
<title>cogl_push_matrix ()</title>
624
<indexterm zone="cogl-push-matrix"><primary sortas="push_matrix">cogl_push_matrix</primary></indexterm><programlisting><link linkend="void">void</link> cogl_push_matrix (void);</programlisting>
626
Store the current model-view matrix on the matrix stack. The matrix
627
can later be restored with <link linkend="cogl-pop-matrix"><function>cogl_pop_matrix()</function></link>.</para>
630
<refsect2 id="cogl-pop-matrix" role="function">
631
<title>cogl_pop_matrix ()</title>
632
<indexterm zone="cogl-pop-matrix"><primary sortas="pop_matrix">cogl_pop_matrix</primary></indexterm><programlisting><link linkend="void">void</link> cogl_pop_matrix (void);</programlisting>
634
Restore the current model-view matrix from the matrix stack.</para>
637
<refsect2 id="cogl-scale" role="function">
638
<title>cogl_scale ()</title>
639
<indexterm zone="cogl-scale"><primary sortas="scale">cogl_scale</primary></indexterm><programlisting><link linkend="void">void</link> cogl_scale (<link linkend="float">float</link> x,
640
<link linkend="float">float</link> y,
641
<link linkend="float">float</link> z);</programlisting>
643
Multiplies the current model-view matrix by one that scales the x,
644
y and z axes by the given values.</para>
646
</para><variablelist role="params">
647
<varlistentry><term><parameter>x</parameter> :</term>
648
<listitem><simpara> Amount to scale along the x-axis
649
</simpara></listitem></varlistentry>
650
<varlistentry><term><parameter>y</parameter> :</term>
651
<listitem><simpara> Amount to scale along the y-axis
652
</simpara></listitem></varlistentry>
653
<varlistentry><term><parameter>z</parameter> :</term>
654
<listitem><simpara> Amount to scale along the z-axis
655
</simpara></listitem></varlistentry>
656
</variablelist></refsect2>
657
<refsect2 id="cogl-translate" role="function">
658
<title>cogl_translate ()</title>
659
<indexterm zone="cogl-translate"><primary sortas="translate">cogl_translate</primary></indexterm><programlisting><link linkend="void">void</link> cogl_translate (<link linkend="float">float</link> x,
660
<link linkend="float">float</link> y,
661
<link linkend="float">float</link> z);</programlisting>
663
Multiplies the current model-view matrix by one that translates the
664
model along all three axes according to the given values.</para>
666
</para><variablelist role="params">
667
<varlistentry><term><parameter>x</parameter> :</term>
668
<listitem><simpara> Distance to translate along the x-axis
669
</simpara></listitem></varlistentry>
670
<varlistentry><term><parameter>y</parameter> :</term>
671
<listitem><simpara> Distance to translate along the y-axis
672
</simpara></listitem></varlistentry>
673
<varlistentry><term><parameter>z</parameter> :</term>
674
<listitem><simpara> Distance to translate along the z-axis
675
</simpara></listitem></varlistentry>
676
</variablelist></refsect2>
677
<refsect2 id="cogl-rotate" role="function">
678
<title>cogl_rotate ()</title>
679
<indexterm zone="cogl-rotate"><primary sortas="rotate">cogl_rotate</primary></indexterm><programlisting><link linkend="void">void</link> cogl_rotate (<link linkend="float">float</link> angle,
680
<link linkend="float">float</link> x,
681
<link linkend="float">float</link> y,
682
<link linkend="float">float</link> z);</programlisting>
684
Multiplies the current model-view matrix by one that rotates the
685
model around the vertex specified by <parameter>x</parameter>, <parameter>y</parameter> and <parameter>z</parameter>. The rotation
686
follows the right-hand thumb rule so for example rotating by 10
687
degrees about the vertex (0, 0, 1) causes a small counter-clockwise
690
</para><variablelist role="params">
691
<varlistentry><term><parameter>angle</parameter> :</term>
692
<listitem><simpara> Angle in degrees to rotate.
693
</simpara></listitem></varlistentry>
694
<varlistentry><term><parameter>x</parameter> :</term>
695
<listitem><simpara> X-component of vertex to rotate around.
696
</simpara></listitem></varlistentry>
697
<varlistentry><term><parameter>y</parameter> :</term>
698
<listitem><simpara> Y-component of vertex to rotate around.
699
</simpara></listitem></varlistentry>
700
<varlistentry><term><parameter>z</parameter> :</term>
701
<listitem><simpara> Z-component of vertex to rotate around.
702
</simpara></listitem></varlistentry>
703
</variablelist></refsect2>
704
<refsect2 id="cogl-frustum" role="function" condition="since:0.8.2">
705
<title>cogl_frustum ()</title>
706
<indexterm zone="cogl-frustum" role="0.8.2"><primary sortas="frustum">cogl_frustum</primary></indexterm><programlisting><link linkend="void">void</link> cogl_frustum (<link linkend="float">float</link> left,
707
<link linkend="float">float</link> right,
708
<link linkend="float">float</link> bottom,
709
<link linkend="float">float</link> top,
710
<link linkend="float">float</link> z_near,
711
<link linkend="float">float</link> z_far);</programlisting>
713
Replaces the current projection matrix with a perspective matrix
714
for the given viewing frustum.</para>
716
</para><variablelist role="params">
717
<varlistentry><term><parameter>left</parameter> :</term>
718
<listitem><simpara> Left clipping plane
719
</simpara></listitem></varlistentry>
720
<varlistentry><term><parameter>right</parameter> :</term>
721
<listitem><simpara> Right clipping plane
722
</simpara></listitem></varlistentry>
723
<varlistentry><term><parameter>bottom</parameter> :</term>
724
<listitem><simpara> Bottom clipping plane
725
</simpara></listitem></varlistentry>
726
<varlistentry><term><parameter>top</parameter> :</term>
727
<listitem><simpara> Top clipping plane
728
</simpara></listitem></varlistentry>
729
<varlistentry><term><parameter>z_near</parameter> :</term>
730
<listitem><simpara> Nearest visible point
731
</simpara></listitem></varlistentry>
732
<varlistentry><term><parameter>z_far</parameter> :</term>
733
<listitem><simpara> Furthest visible point along the z-axis
734
</simpara></listitem></varlistentry>
735
</variablelist><para role="since">Since 0.8.2</para></refsect2>
736
<refsect2 id="cogl-perspective" role="function">
737
<title>cogl_perspective ()</title>
738
<indexterm zone="cogl-perspective"><primary sortas="perspective">cogl_perspective</primary></indexterm><programlisting><link linkend="void">void</link> cogl_perspective (<link linkend="float">float</link> fovy,
739
<link linkend="float">float</link> aspect,
740
<link linkend="float">float</link> z_near,
741
<link linkend="float">float</link> z_far);</programlisting>
743
Replaces the current projection matrix with a perspective matrix
744
based on the provided values.</para>
746
</para><variablelist role="params">
747
<varlistentry><term><parameter>fovy</parameter> :</term>
748
<listitem><simpara> Vertical of view angle in degrees.
749
</simpara></listitem></varlistentry>
750
<varlistentry><term><parameter>aspect</parameter> :</term>
751
<listitem><simpara> Aspect ratio of diesplay
752
</simpara></listitem></varlistentry>
753
<varlistentry><term><parameter>z_near</parameter> :</term>
754
<listitem><simpara> Nearest visible point
755
</simpara></listitem></varlistentry>
756
<varlistentry><term><parameter>z_far</parameter> :</term>
757
<listitem><simpara> Furthest visible point along the z-axis
758
</simpara></listitem></varlistentry>
759
</variablelist></refsect2>
760
<refsect2 id="cogl-ortho" role="function" condition="since:1.0">
761
<title>cogl_ortho ()</title>
762
<indexterm zone="cogl-ortho" role="1.0"><primary sortas="ortho">cogl_ortho</primary></indexterm><programlisting><link linkend="void">void</link> cogl_ortho (<link linkend="float">float</link> left,
763
<link linkend="float">float</link> right,
764
<link linkend="float">float</link> bottom,
765
<link linkend="float">float</link> top,
766
<link linkend="float">float</link> near,
767
<link linkend="float">float</link> far);</programlisting>
769
Replaces the current projection matrix with a parallel projection
772
</para><variablelist role="params">
773
<varlistentry><term><parameter>left</parameter> :</term>
774
<listitem><simpara> The coordinate for the left clipping plane
775
</simpara></listitem></varlistentry>
776
<varlistentry><term><parameter>right</parameter> :</term>
777
<listitem><simpara> The coordinate for the right clipping plane
778
</simpara></listitem></varlistentry>
779
<varlistentry><term><parameter>bottom</parameter> :</term>
780
<listitem><simpara> The coordinate for the bottom clipping plane
781
</simpara></listitem></varlistentry>
782
<varlistentry><term><parameter>top</parameter> :</term>
783
<listitem><simpara> The coordinate for the top clipping plane
784
</simpara></listitem></varlistentry>
785
<varlistentry><term><parameter>near</parameter> :</term>
786
<listitem><simpara> The coordinate for the near clipping plane (may be negative if
787
the plane is behind the viewer)
788
</simpara></listitem></varlistentry>
789
<varlistentry><term><parameter>far</parameter> :</term>
790
<listitem><simpara> The coordinate for the far clipping plane (may be negative if
791
the plane is behind the viewer)
792
</simpara></listitem></varlistentry>
793
</variablelist><para role="since">Since 1.0</para></refsect2>
794
<refsect2 id="cogl-get-modelview-matrix" role="function">
795
<title>cogl_get_modelview_matrix ()</title>
796
<indexterm zone="cogl-get-modelview-matrix"><primary sortas="get_modelview_matrix">cogl_get_modelview_matrix</primary></indexterm><programlisting><link linkend="void">void</link> cogl_get_modelview_matrix (<link linkend="CoglMatrix">CoglMatrix</link> *matrix);</programlisting>
798
Stores the current model-view matrix in <parameter>matrix</parameter>.</para>
800
</para><variablelist role="params">
801
<varlistentry><term><parameter>matrix</parameter> :</term>
802
<listitem><simpara> pointer to a CoglMatrix to recieve the matrix
803
</simpara></listitem></varlistentry>
804
</variablelist></refsect2>
805
<refsect2 id="cogl-set-modelview-matrix" role="function">
806
<title>cogl_set_modelview_matrix ()</title>
807
<indexterm zone="cogl-set-modelview-matrix"><primary sortas="set_modelview_matrix">cogl_set_modelview_matrix</primary></indexterm><programlisting><link linkend="void">void</link> cogl_set_modelview_matrix (<link linkend="CoglMatrix">CoglMatrix</link> *matrix);</programlisting>
809
Loads matrix as the new model-view matrix.</para>
811
</para><variablelist role="params">
812
<varlistentry><term><parameter>matrix</parameter> :</term>
813
<listitem><simpara> pointer to a CoglMatrix to set as the new model-view matrix
814
</simpara></listitem></varlistentry>
815
</variablelist></refsect2>
816
<refsect2 id="cogl-get-projection-matrix" role="function">
817
<title>cogl_get_projection_matrix ()</title>
818
<indexterm zone="cogl-get-projection-matrix"><primary sortas="get_projection_matrix">cogl_get_projection_matrix</primary></indexterm><programlisting><link linkend="void">void</link> cogl_get_projection_matrix (<link linkend="CoglMatrix">CoglMatrix</link> *matrix);</programlisting>
820
Stores the current projection matrix in <parameter>matrix</parameter>.</para>
822
</para><variablelist role="params">
823
<varlistentry><term><parameter>matrix</parameter> :</term>
824
<listitem><simpara> pointer to a CoglMatrix to recieve the matrix
825
</simpara></listitem></varlistentry>
826
</variablelist></refsect2>
827
<refsect2 id="cogl-set-projection-matrix" role="function">
828
<title>cogl_set_projection_matrix ()</title>
829
<indexterm zone="cogl-set-projection-matrix"><primary sortas="set_projection_matrix">cogl_set_projection_matrix</primary></indexterm><programlisting><link linkend="void">void</link> cogl_set_projection_matrix (<link linkend="CoglMatrix">CoglMatrix</link> *matrix);</programlisting>
831
Loads matrix as the new projection matrix.</para>
833
</para><variablelist role="params">
834
<varlistentry><term><parameter>matrix</parameter> :</term>
835
<listitem><simpara> pointer to a CoglMatrix to set as the new projection matrix
836
</simpara></listitem></varlistentry>
837
</variablelist></refsect2>
838
<refsect2 id="cogl-viewport" role="function" condition="since:0.8.2">
839
<title>cogl_viewport ()</title>
840
<indexterm zone="cogl-viewport" role="0.8.2"><primary sortas="viewport">cogl_viewport</primary></indexterm><programlisting><link linkend="void">void</link> cogl_viewport (<link linkend="guint">guint</link> width,
841
<link linkend="guint">guint</link> height);</programlisting>
843
Replace the current viewport with the given values.</para>
845
</para><variablelist role="params">
846
<varlistentry><term><parameter>width</parameter> :</term>
847
<listitem><simpara> Width of the viewport
848
</simpara></listitem></varlistentry>
849
<varlistentry><term><parameter>height</parameter> :</term>
850
<listitem><simpara> Height of the viewport
851
</simpara></listitem></varlistentry>
852
</variablelist><para role="since">Since 0.8.2</para></refsect2>
853
<refsect2 id="cogl-get-viewport" role="function">
854
<title>cogl_get_viewport ()</title>
855
<indexterm zone="cogl-get-viewport"><primary sortas="get_viewport">cogl_get_viewport</primary></indexterm><programlisting><link linkend="void">void</link> cogl_get_viewport (<link linkend="float">float</link> v[4]);</programlisting>
857
Stores the current viewport in <parameter>v</parameter>. <parameter>v</parameter>[0] and <parameter>v</parameter>[1] get the x and y
858
position of the viewport and <parameter>v</parameter>[2] and <parameter>v</parameter>[3] get the width and
861
</para><variablelist role="params">
862
<varlistentry><term><parameter>v</parameter> :</term>
863
<listitem><simpara> pointer to a 4 element array of <link linkend="float"><type>float</type></link><!-- -->s to
864
receive the viewport dimensions.
865
</simpara></listitem></varlistentry>
866
</variablelist></refsect2>
867
<refsect2 id="cogl-clear" role="function">
868
<title>cogl_clear ()</title>
869
<indexterm zone="cogl-clear"><primary sortas="clear">cogl_clear</primary></indexterm><programlisting><link linkend="void">void</link> cogl_clear (const <link linkend="CoglColor">CoglColor</link> *color,
870
<link linkend="gulong">gulong</link> buffers);</programlisting>
872
Clears all the auxiliary buffers identified in the <parameter>buffers</parameter> mask, and if
873
that includes the color buffer then the specified <parameter>color</parameter> is used.</para>
875
</para><variablelist role="params">
876
<varlistentry><term><parameter>color</parameter> :</term>
877
<listitem><simpara> Background color to clear to
878
</simpara></listitem></varlistentry>
879
<varlistentry><term><parameter>buffers</parameter> :</term>
880
<listitem><simpara> A mask of <link linkend="CoglBufferBit"><type>CoglBufferBit</type></link><!-- -->'s identifying which auxiliary
882
</simpara></listitem></varlistentry>
883
</variablelist></refsect2>
884
<refsect2 id="cogl-get-bitmasks" role="function">
885
<title>cogl_get_bitmasks ()</title>
886
<indexterm zone="cogl-get-bitmasks"><primary sortas="get_bitmasks">cogl_get_bitmasks</primary></indexterm><programlisting><link linkend="void">void</link> cogl_get_bitmasks (<link linkend="gint">gint</link> *red,
887
<link linkend="gint">gint</link> *green,
888
<link linkend="gint">gint</link> *blue,
889
<link linkend="gint">gint</link> *alpha);</programlisting>
891
Gets the number of bitplanes used for each of the color components
892
in the color buffer. Pass <link linkend="NULL--CAPS"><literal>NULL</literal></link> for any of the arguments if the
893
value is not required.</para>
895
</para><variablelist role="params">
896
<varlistentry><term><parameter>red</parameter> :</term>
897
<listitem><simpara> Return location for the number of red bits or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
898
</simpara></listitem></varlistentry>
899
<varlistentry><term><parameter>green</parameter> :</term>
900
<listitem><simpara> Return location for the number of green bits or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
901
</simpara></listitem></varlistentry>
902
<varlistentry><term><parameter>blue</parameter> :</term>
903
<listitem><simpara> Return location for the number of blue bits or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
904
</simpara></listitem></varlistentry>
905
<varlistentry><term><parameter>alpha</parameter> :</term>
906
<listitem><simpara> Return location for the number of alpha bits or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
907
</simpara></listitem></varlistentry>
908
</variablelist></refsect2>
909
<refsect2 id="cogl-set-depth-test-enabled" role="function">
910
<title>cogl_set_depth_test_enabled ()</title>
911
<indexterm zone="cogl-set-depth-test-enabled"><primary sortas="set_depth_test_enabled">cogl_set_depth_test_enabled</primary></indexterm><programlisting><link linkend="void">void</link> cogl_set_depth_test_enabled (<link linkend="gboolean">gboolean</link> setting);</programlisting>
913
Sets whether depth testing is enabled. If it is disabled then the
914
order that actors are layered on the screen depends solely on the
915
order specified using <link linkend="clutter-actor-raise"><function>clutter_actor_raise()</function></link> and
916
<link linkend="clutter-actor-lower"><function>clutter_actor_lower()</function></link>, otherwise it will also take into account the
917
actor's depth. Depth testing is disabled by default.</para>
919
</para><variablelist role="params">
920
<varlistentry><term><parameter>setting</parameter> :</term>
921
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to enable depth testing or <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> to disable.
922
</simpara></listitem></varlistentry>
923
</variablelist></refsect2>
924
<refsect2 id="cogl-get-depth-test-enabled" role="function">
925
<title>cogl_get_depth_test_enabled ()</title>
926
<indexterm zone="cogl-get-depth-test-enabled"><primary sortas="get_depth_test_enabled">cogl_get_depth_test_enabled</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_get_depth_test_enabled (void);</programlisting>
928
Queries if depth testing has been enabled via <link linkend="cogl-set-depth-test-enable"><function>cogl_set_depth_test_enable()</function></link></para>
930
</para><variablelist role="params">
931
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if depth testing is enabled, and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise
932
</simpara></listitem></varlistentry>
933
</variablelist></refsect2>
934
<refsect2 id="cogl-set-backface-culling-enabled" role="function">
935
<title>cogl_set_backface_culling_enabled ()</title>
936
<indexterm zone="cogl-set-backface-culling-enabled"><primary sortas="set_backface_culling_enabled">cogl_set_backface_culling_enabled</primary></indexterm><programlisting><link linkend="void">void</link> cogl_set_backface_culling_enabled (<link linkend="gboolean">gboolean</link> setting);</programlisting>
938
Sets whether textures positioned so that their backface is showing
939
should be hidden. This can be used to efficiently draw two-sided
940
textures or fully closed cubes without enabling depth testing. This
941
only affects calls to the cogl_rectangle* family of functions and
942
cogl_vertex_buffer_draw*. Backface culling is disabled by default.</para>
944
</para><variablelist role="params">
945
<varlistentry><term><parameter>setting</parameter> :</term>
946
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to enable backface culling or <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> to disable.
947
</simpara></listitem></varlistentry>
948
</variablelist></refsect2>
949
<refsect2 id="cogl-get-backface-culling-enabled" role="function">
950
<title>cogl_get_backface_culling_enabled ()</title>
951
<indexterm zone="cogl-get-backface-culling-enabled"><primary sortas="get_backface_culling_enabled">cogl_get_backface_culling_enabled</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> cogl_get_backface_culling_enabled (void);</programlisting>
953
Queries if backface culling has been enabled via
954
<link linkend="cogl-set-backface-culling-enabled"><function>cogl_set_backface_culling_enabled()</function></link></para>
956
</para><variablelist role="params">
957
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if backface culling is enabled, and <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise
958
</simpara></listitem></varlistentry>
959
</variablelist></refsect2>
960
<refsect2 id="CoglFogMode" role="enum" condition="since:1.0">
961
<title>enum CoglFogMode</title>
962
<indexterm zone="CoglFogMode" role="1.0"><primary sortas="FogMode">CoglFogMode</primary></indexterm><programlisting>typedef enum {
963
COGL_FOG_MODE_LINEAR,
964
COGL_FOG_MODE_EXPONENTIAL,
965
COGL_FOG_MODE_EXPONENTIAL_SQUARED
969
The fog mode determines the equation used to calculate the fogging blend
970
factor while fogging is enabled. The simplest <link linkend="COGL-FOG-MODE-LINEAR--CAPS"><literal>COGL_FOG_MODE_LINEAR</literal></link> mode
974
<informalexample><programlisting>
975
f = end - eye_distance / end - start
976
</programlisting></informalexample>
979
Where eye_distance is the distance of the current fragment in eye
980
coordinates from the origin.</para>
982
</para><variablelist role="enum">
983
<varlistentry id="COGL-FOG-MODE-LINEAR--CAPS" role="constant">
984
<term><literal>COGL_FOG_MODE_LINEAR</literal></term>
985
<listitem><simpara> Calculates the fog blend factor as:
986
<informalexample><programlisting>
987
f = end - eye_distance / end - start
988
</programlisting></informalexample>
989
</simpara></listitem>
991
<varlistentry id="COGL-FOG-MODE-EXPONENTIAL--CAPS" role="constant">
992
<term><literal>COGL_FOG_MODE_EXPONENTIAL</literal></term>
993
<listitem><simpara> Calculates the fog blend factor as:
994
<informalexample><programlisting>
995
f = e ^ -(density * eye_distance)
996
</programlisting></informalexample>
997
</simpara></listitem>
999
<varlistentry id="COGL-FOG-MODE-EXPONENTIAL-SQUARED--CAPS" role="constant">
1000
<term><literal>COGL_FOG_MODE_EXPONENTIAL_SQUARED</literal></term>
1001
<listitem><simpara> Calculates the fog blend factor as:
1002
<informalexample><programlisting>
1003
f = e ^ -(density * eye_distance)^2
1004
</programlisting></informalexample>
1005
</simpara></listitem>
1007
</variablelist><para role="since">Since 1.0</para></refsect2>
1008
<refsect2 id="cogl-set-fog" role="function">
1009
<title>cogl_set_fog ()</title>
1010
<indexterm zone="cogl-set-fog"><primary sortas="set_fog">cogl_set_fog</primary></indexterm><programlisting><link linkend="void">void</link> cogl_set_fog (const <link linkend="CoglColor">CoglColor</link> *fog_color,
1011
<link linkend="CoglFogMode">CoglFogMode</link> mode,
1012
<link linkend="float">float</link> density,
1013
<link linkend="float">float</link> z_near,
1014
<link linkend="float">float</link> z_far);</programlisting>
1016
Enables fogging. Fogging causes vertices that are further away from the eye
1017
to be rendered with a different color. The color is determined according to
1018
the chosen fog mode; at it's simplest the color is linearly interpolated so
1019
that vertices at <parameter>z_near</parameter> are drawn fully with their original color and
1020
vertices at <parameter>z_far</parameter> are drawn fully with <parameter>fog_color</parameter>. Fogging will remain
1021
enabled until you call <link linkend="cogl-disable-fog"><function>cogl_disable_fog()</function></link>.
1024
<note>The fogging functions only work correctly when primitives use
1025
unmultiplied alpha colors. By default Cogl will premultiply textures
1026
and <link linkend="cogl-set-source-color"><function>cogl_set_source_color()</function></link> will premultiply colors, so unless you
1027
explicitly load your textures requesting an unmultiplied internal format
1028
and use <link linkend="cogl-material-set-color"><function>cogl_material_set_color()</function></link> you can only use fogging with fully
1029
opaque primitives. This might improve in the future when we can depend
1030
on fragment shaders.</note></para>
1032
</para><variablelist role="params">
1033
<varlistentry><term><parameter>fog_color</parameter> :</term>
1034
<listitem><simpara> The color of the fog
1035
</simpara></listitem></varlistentry>
1036
<varlistentry><term><parameter>mode</parameter> :</term>
1037
<listitem><simpara> A CoglFogMode that determines the equation used to calculate the
1038
fogging blend factor.
1039
</simpara></listitem></varlistentry>
1040
<varlistentry><term><parameter>density</parameter> :</term>
1041
<listitem><simpara> Used by the EXPONENTIAL and EXPONENTIAL_SQUARED CoglFogMode
1043
</simpara></listitem></varlistentry>
1044
<varlistentry><term><parameter>z_near</parameter> :</term>
1045
<listitem><simpara> Position along z-axis where no fogging should be applied
1046
</simpara></listitem></varlistentry>
1047
<varlistentry><term><parameter>z_far</parameter> :</term>
1048
<listitem><simpara> Position along z-axes where full fogging should be applied
1049
</simpara></listitem></varlistentry>
1050
</variablelist></refsect2>
1051
<refsect2 id="cogl-disable-fog" role="function">
1052
<title>cogl_disable_fog ()</title>
1053
<indexterm zone="cogl-disable-fog"><primary sortas="disable_fog">cogl_disable_fog</primary></indexterm><programlisting><link linkend="void">void</link> cogl_disable_fog (void);</programlisting>
1055
This function disables fogging, so primitives drawn afterwards will not be
1056
blended with any previously set fog color.</para>
1059
<refsect2 id="cogl-set-source" role="function">
1060
<title>cogl_set_source ()</title>
1061
<indexterm zone="cogl-set-source"><primary sortas="set_source">cogl_set_source</primary></indexterm><programlisting><link linkend="void">void</link> cogl_set_source (<link linkend="CoglHandle">CoglHandle</link> material);</programlisting>
1063
This function sets the source material that will be used to fill subsequent
1064
geometry emitted via the cogl API.
1067
Note: in the future we may add the ability to set a front facing material,
1068
and a back facing material, in which case this function will set both to the
1074
</para><variablelist role="params">
1075
<varlistentry><term><parameter>material</parameter> :</term>
1076
<listitem><simpara> A CoglMaterial object
1077
</simpara></listitem></varlistentry>
1078
</variablelist></refsect2>
1079
<refsect2 id="cogl-set-source-color" role="function" condition="since:1.0">
1080
<title>cogl_set_source_color ()</title>
1081
<indexterm zone="cogl-set-source-color" role="1.0"><primary sortas="set_source_color">cogl_set_source_color</primary></indexterm><programlisting><link linkend="void">void</link> cogl_set_source_color (const <link linkend="CoglColor">CoglColor</link> *color);</programlisting>
1083
This is a convenience function for creating a solid fill source material
1084
from the given color. This color will be used for any subsequent drawing
1088
The color will be premultiplied by Cogl, so the color should be
1089
non-premultiplied. For example: use (1.0, 0.0, 0.0, 0.5) for
1090
semi-transparent red.
1093
See also <link linkend="cogl-set-source-color4ub"><function>cogl_set_source_color4ub()</function></link> and <link linkend="cogl-set-source-color4f"><function>cogl_set_source_color4f()</function></link>
1094
if you already have the color components.</para>
1096
</para><variablelist role="params">
1097
<varlistentry><term><parameter>color</parameter> :</term>
1098
<listitem><simpara> a <link linkend="CoglColor"><type>CoglColor</type></link>
1099
</simpara></listitem></varlistentry>
1100
</variablelist><para role="since">Since 1.0</para></refsect2>
1101
<refsect2 id="cogl-set-source-color4ub" role="function" condition="since:1.0">
1102
<title>cogl_set_source_color4ub ()</title>
1103
<indexterm zone="cogl-set-source-color4ub" role="1.0"><primary sortas="set_source_color4ub">cogl_set_source_color4ub</primary></indexterm><programlisting><link linkend="void">void</link> cogl_set_source_color4ub (<link linkend="guint8">guint8</link> red,
1104
<link linkend="guint8">guint8</link> green,
1105
<link linkend="guint8">guint8</link> blue,
1106
<link linkend="guint8">guint8</link> alpha);</programlisting>
1108
This is a convenience function for creating a solid fill source material
1109
from the given color using unsigned bytes for each component. This
1110
color will be used for any subsequent drawing operation.
1113
The value for each component is an unsigned byte in the range
1114
between 0 and 255.</para>
1116
</para><variablelist role="params">
1117
<varlistentry><term><parameter>red</parameter> :</term>
1118
<listitem><simpara> value of the red channel, between 0 and 255
1119
</simpara></listitem></varlistentry>
1120
<varlistentry><term><parameter>green</parameter> :</term>
1121
<listitem><simpara> value of the green channel, between 0 and 255
1122
</simpara></listitem></varlistentry>
1123
<varlistentry><term><parameter>blue</parameter> :</term>
1124
<listitem><simpara> value of the blue channel, between 0 and 255
1125
</simpara></listitem></varlistentry>
1126
<varlistentry><term><parameter>alpha</parameter> :</term>
1127
<listitem><simpara> value of the alpha channel, between 0 and 255
1128
</simpara></listitem></varlistentry>
1129
</variablelist><para role="since">Since 1.0</para></refsect2>
1130
<refsect2 id="cogl-set-source-color4f" role="function" condition="since:1.0">
1131
<title>cogl_set_source_color4f ()</title>
1132
<indexterm zone="cogl-set-source-color4f" role="1.0"><primary sortas="set_source_color4f">cogl_set_source_color4f</primary></indexterm><programlisting><link linkend="void">void</link> cogl_set_source_color4f (<link linkend="float">float</link> red,
1133
<link linkend="float">float</link> green,
1134
<link linkend="float">float</link> blue,
1135
<link linkend="float">float</link> alpha);</programlisting>
1137
This is a convenience function for creating a solid fill source material
1138
from the given color using normalized values for each component. This color
1139
will be used for any subsequent drawing operation.
1142
The value for each component is a fixed point number in the range
1143
between 0 and <link linkend="1--CAPS"><literal>1</literal></link>.0. If the values passed in are outside that
1144
range, they will be clamped.</para>
1146
</para><variablelist role="params">
1147
<varlistentry><term><parameter>red</parameter> :</term>
1148
<listitem><simpara> value of the red channel, between 0 and <link linkend="1--CAPS"><literal>1</literal></link>.0
1149
</simpara></listitem></varlistentry>
1150
<varlistentry><term><parameter>green</parameter> :</term>
1151
<listitem><simpara> value of the green channel, between 0 and <link linkend="1--CAPS"><literal>1</literal></link>.0
1152
</simpara></listitem></varlistentry>
1153
<varlistentry><term><parameter>blue</parameter> :</term>
1154
<listitem><simpara> value of the blue channel, between 0 and <link linkend="1--CAPS"><literal>1</literal></link>.0
1155
</simpara></listitem></varlistentry>
1156
<varlistentry><term><parameter>alpha</parameter> :</term>
1157
<listitem><simpara> value of the alpha channel, between 0 and <link linkend="1--CAPS"><literal>1</literal></link>.0
1158
</simpara></listitem></varlistentry>
1159
</variablelist><para role="since">Since 1.0</para></refsect2>
1160
<refsect2 id="cogl-set-source-texture" role="function">
1161
<title>cogl_set_source_texture ()</title>
1162
<indexterm zone="cogl-set-source-texture"><primary sortas="set_source_texture">cogl_set_source_texture</primary></indexterm><programlisting><link linkend="void">void</link> cogl_set_source_texture (<link linkend="CoglHandle">CoglHandle</link> texture_handle);</programlisting>
1164
This is a convenience function for creating a material with the first
1165
layer set to <link linkend="texture-handle"><type>texture_handle</type></link> and setting that material as the source with
1169
Note: There is no interaction between calls to cogl_set_source_color
1170
and cogl_set_source_texture. If you need to blend a texture with a color then
1171
you can create a simple material like this:
1173
material = cogl_material_new ();
1174
cogl_material_set_color4ub (material, 0xff, 0x00, 0x00, 0x80);
1175
cogl_material_set_layer (material, 0, tex_handle);
1176
cogl_set_source (material);
1182
</para><variablelist role="params">
1183
<varlistentry><term><parameter>texture_handle</parameter> :</term>
1184
<listitem><simpara> The Cogl texture you want as your source
1185
</simpara></listitem></varlistentry>
1186
</variablelist></refsect2>
1187
<refsect2 id="CoglReadPixelsFlags" role="enum" condition="since:1.0">
1188
<title>enum CoglReadPixelsFlags</title>
1189
<indexterm zone="CoglReadPixelsFlags" role="1.0"><primary sortas="ReadPixelsFlags">CoglReadPixelsFlags</primary></indexterm><programlisting>typedef enum { /*< prefix=COGL_READ_PIXELS >*/
1190
COGL_READ_PIXELS_COLOR_BUFFER = 1L << 0
1191
} CoglReadPixelsFlags;
1194
Flags for <link linkend="cogl-read-pixels"><function>cogl_read_pixels()</function></link></para>
1196
</para><variablelist role="enum">
1197
<varlistentry id="COGL-READ-PIXELS-COLOR-BUFFER--CAPS" role="constant">
1198
<term><literal>COGL_READ_PIXELS_COLOR_BUFFER</literal></term>
1199
<listitem><simpara> Read from the color buffer
1200
</simpara></listitem>
1202
</variablelist><para role="since">Since 1.0</para></refsect2>
1203
<refsect2 id="cogl-read-pixels" role="function">
1204
<title>cogl_read_pixels ()</title>
1205
<indexterm zone="cogl-read-pixels"><primary sortas="read_pixels">cogl_read_pixels</primary></indexterm><programlisting><link linkend="void">void</link> cogl_read_pixels (<link linkend="int">int</link> x,
1206
<link linkend="int">int</link> y,
1207
<link linkend="int">int</link> width,
1208
<link linkend="int">int</link> height,
1209
<link linkend="CoglReadPixelsFlags">CoglReadPixelsFlags</link> source,
1210
<link linkend="CoglPixelFormat">CoglPixelFormat</link> format,
1211
<link linkend="guint8">guint8</link> *pixels);</programlisting>
1213
This reads a rectangle of pixels from the current draw buffer where
1214
position (0, 0) is the top left. The pixel at (x, y) is the first
1215
read, and the data is returned with a rowstride of (width * 4)</para>
1217
</para><variablelist role="params">
1218
<varlistentry><term><parameter>x</parameter> :</term>
1219
<listitem><simpara> The window x position to start reading from
1220
</simpara></listitem></varlistentry>
1221
<varlistentry><term><parameter>y</parameter> :</term>
1222
<listitem><simpara> The window y position to start reading from
1223
</simpara></listitem></varlistentry>
1224
<varlistentry><term><parameter>width</parameter> :</term>
1225
<listitem><simpara> The width of the rectangle you want to read
1226
</simpara></listitem></varlistentry>
1227
<varlistentry><term><parameter>height</parameter> :</term>
1228
<listitem><simpara> The height of the rectangle you want to read
1229
</simpara></listitem></varlistentry>
1230
<varlistentry><term><parameter>source</parameter> :</term>
1231
<listitem><simpara> Identifies which auxillary buffer you want to read
1232
(only COGL_READ_PIXELS_COLOR_BUFFER supported currently)
1233
</simpara></listitem></varlistentry>
1234
<varlistentry><term><parameter>format</parameter> :</term>
1235
<listitem><simpara> The pixel format you want the result in
1236
(only COGL_PIXEL_FORMAT_RGBA_8888 supported currently)
1237
</simpara></listitem></varlistentry>
1238
<varlistentry><term><parameter>pixels</parameter> :</term>
1239
<listitem><simpara> The location to write the pixel data.
1240
</simpara></listitem></varlistentry>
1241
</variablelist></refsect2>
1242
<refsect2 id="cogl-flush" role="function" condition="since:1.0">
1243
<title>cogl_flush ()</title>
1244
<indexterm zone="cogl-flush" role="1.0"><primary sortas="flush">cogl_flush</primary></indexterm><programlisting><link linkend="void">void</link> cogl_flush (void);</programlisting>
1246
This function should only need to be called in exceptional circumstances.
1249
As an optimization Cogl drawing functions may batch up primitives
1250
internally, so if you are trying to use raw GL outside of Cogl you stand a
1251
better chance of being successful if you ask Cogl to flush any batched
1252
geometry before making your state changes.
1255
It only ensure that the underlying driver is issued all the commands
1256
necessary to draw the batched primitives. It provides no guarantees about
1257
when the driver will complete the rendering.
1260
This provides no guarantees about the GL state upon returning and to avoid
1261
confusing Cogl you should aim to restore any changes you make before
1262
resuming use of Cogl.
1265
If you are making state changes with the intention of affecting Cogl drawing
1266
primitives you are 100% on your own since you stand a good chance of
1267
conflicting with Cogl internals. For example clutter-gst which currently
1268
uses direct GL calls to bind ARBfp programs will very likely break when Cogl
1269
starts to use ARBfb programs itself for the material API.</para>
1271
</para><para role="since">Since 1.0</para></refsect2>
1272
<refsect2 id="cogl-begin-gl" role="function" condition="since:1.0">
1273
<title>cogl_begin_gl ()</title>
1274
<indexterm zone="cogl-begin-gl" role="1.0"><primary sortas="begin_gl">cogl_begin_gl</primary></indexterm><programlisting><link linkend="void">void</link> cogl_begin_gl (void);</programlisting>
1276
We do not advise nor reliably support the interleaving of raw GL drawing and
1277
Cogl drawing functions, but if you insist, <link linkend="cogl-begin-gl"><function>cogl_begin_gl()</function></link> and <link linkend="cogl-end-gl"><function>cogl_end_gl()</function></link>
1278
provide a simple mechanism that may at least give you a fighting chance of
1282
Note: this doesn't help you modify the behaviour of Cogl drawing functions
1283
through the modification of GL state; that will never be reliably supported,
1284
but if you are trying to do something like:
1287
- setup some OpenGL state.
1288
- draw using OpenGL (e.g. glDrawArrays() )
1289
- reset modified OpenGL state.
1290
- continue using Cogl to draw
1293
You should surround blocks of drawing using raw GL with <link linkend="cogl-begin-gl"><function>cogl_begin_gl()</function></link>
1294
and <link linkend="cogl-end-gl"><function>cogl_end_gl()</function></link>:
1298
- setup some OpenGL state.
1299
- draw using OpenGL (e.g. glDrawArrays() )
1300
- reset modified OpenGL state.
1302
- continue using Cogl to draw
1307
Don't ever try and do:
1310
- setup some OpenGL state.
1312
- reset modified OpenGL state.
1315
When the internals of Cogl evolves, this is very liable to break.
1318
This function will flush all batched primitives, and subsequently flush
1319
all internal Cogl state to OpenGL as if it were going to draw something
1323
The result is that the OpenGL modelview matrix will be setup; the state
1324
corresponding to the current source material will be set up and other world
1325
state such as backface culling, depth and fogging enabledness will be sent
1329
Note: no special material state is flushed, so if you want Cogl to setup a
1330
simplified material state it is your responsibility to set a simple source
1331
material before calling cogl_begin_gl. E.g. by calling
1332
<link linkend="cogl-set-source-color4ub"><function>cogl_set_source_color4ub()</function></link>.
1335
Note: It is your responsibility to restore any OpenGL state that you modify
1336
to how it was after calling <link linkend="cogl-begin-gl"><function>cogl_begin_gl()</function></link> if you don't do this then the
1337
result of further Cogl calls is undefined.
1340
Note: You can not nest begin/end blocks.
1343
Again we would like to stress, we do not advise the use of this API and if
1344
possible we would prefer to improve Cogl than have developers require raw
1347
</para><para role="since">Since 1.0</para></refsect2>
1348
<refsect2 id="cogl-end-gl" role="function" condition="since:1.0">
1349
<title>cogl_end_gl ()</title>
1350
<indexterm zone="cogl-end-gl" role="1.0"><primary sortas="end_gl">cogl_end_gl</primary></indexterm><programlisting><link linkend="void">void</link> cogl_end_gl (void);</programlisting>
1352
This is the counterpart to <link linkend="cogl-begin-gl"><function>cogl_begin_gl()</function></link> used to delimit blocks of drawing
1353
code using raw OpenGL. Please refer to <link linkend="cogl-begin-gl"><function>cogl_begin_gl()</function></link> for full details.</para>
1355
</para><para role="since">Since 1.0</para></refsect2>
added
removed
doc/reference/cogl/xml/cogl.xml
