1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>ClutterOffscreenEffect</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7 <link rel="home" href="index.html" title="Clutter Reference Manual">
8 <link rel="up" href="ch06.html" title="Effects">
9 <link rel="prev" href="ch06.html" title="Effects">
10 <link rel="next" href="ClutterShaderEffect.html" title="ClutterShaderEffect">
11 <meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
17 <td><a accesskey="p" href="ch06.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
18 <td><a accesskey="u" href="ch06.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
20 <th width="100%" align="center">Clutter Reference Manual</th>
21 <td><a accesskey="n" href="ClutterShaderEffect.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
23 <tr><td colspan="5" class="shortcuts">
24 <a href="#ClutterOffscreenEffect.synopsis" class="shortcut">Top</a>
26 <a href="#ClutterOffscreenEffect.description" class="shortcut">Description</a>
28 <a href="#ClutterOffscreenEffect.object-hierarchy" class="shortcut">Object Hierarchy</a>
31 <div class="refentry">
32 <a name="ClutterOffscreenEffect"></a><div class="titlepage"></div>
33 <div class="refnamediv"><table width="100%"><tr>
35 <h2><span class="refentrytitle"><a name="ClutterOffscreenEffect.top_of_page"></a>ClutterOffscreenEffect</span></h2>
36 <p>ClutterOffscreenEffect — Base class for effects using offscreen buffers</p>
38 <td valign="top" align="right"></td>
40 <div class="refsynopsisdiv">
41 <a name="ClutterOffscreenEffect.synopsis"></a><h2>Synopsis</h2>
42 <pre class="synopsis">struct <a class="link" href="ClutterOffscreenEffect.html#ClutterOffscreenEffect-struct" title="struct ClutterOffscreenEffect">ClutterOffscreenEffect</a>;
43 struct <a class="link" href="ClutterOffscreenEffect.html#ClutterOffscreenEffectClass" title="struct ClutterOffscreenEffectClass">ClutterOffscreenEffectClass</a>;
44 <span class="returnvalue">CoglMaterial</span> * <a class="link" href="ClutterOffscreenEffect.html#clutter-offscreen-effect-get-target" title="clutter_offscreen_effect_get_target ()">clutter_offscreen_effect_get_target</a> (<em class="parameter"><code><a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> *effect</code></em>);
45 <span class="returnvalue">CoglHandle</span> <a class="link" href="ClutterOffscreenEffect.html#clutter-offscreen-effect-get-texture" title="clutter_offscreen_effect_get_texture ()">clutter_offscreen_effect_get_texture</a>
46 (<em class="parameter"><code><a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> *effect</code></em>);
47 <span class="returnvalue">CoglHandle</span> <a class="link" href="ClutterOffscreenEffect.html#clutter-offscreen-effect-create-texture" title="clutter_offscreen_effect_create_texture ()">clutter_offscreen_effect_create_texture</a>
48 (<em class="parameter"><code><a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> *effect</code></em>,
49 <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gfloat"><span class="type">gfloat</span></a> width</code></em>,
50 <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gfloat"><span class="type">gfloat</span></a> height</code></em>);
51 <span class="returnvalue">void</span> <a class="link" href="ClutterOffscreenEffect.html#clutter-offscreen-effect-paint-target" title="clutter_offscreen_effect_paint_target ()">clutter_offscreen_effect_paint_target</a>
52 (<em class="parameter"><code><a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> *effect</code></em>);
53 <a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> <a class="link" href="ClutterOffscreenEffect.html#clutter-offscreen-effect-get-target-size" title="clutter_offscreen_effect_get_target_size ()">clutter_offscreen_effect_get_target_size</a>
54 (<em class="parameter"><code><a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> *effect</code></em>,
55 <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gfloat"><span class="type">gfloat</span></a> *width</code></em>,
56 <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gfloat"><span class="type">gfloat</span></a> *height</code></em>);
59 <div class="refsect1">
60 <a name="ClutterOffscreenEffect.object-hierarchy"></a><h2>Object Hierarchy</h2>
61 <pre class="synopsis">
62 <a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>
63 +----<a href="../gobject/gobject-The-Base-Object-Type.html#GInitiallyUnowned">GInitiallyUnowned</a>
64 +----<a class="link" href="ClutterActorMeta.html" title="ClutterActorMeta">ClutterActorMeta</a>
65 +----<a class="link" href="ClutterEffect.html" title="ClutterEffect">ClutterEffect</a>
66 +----ClutterOffscreenEffect
67 +----<a class="link" href="ClutterBlurEffect.html" title="ClutterBlurEffect">ClutterBlurEffect</a>
68 +----<a class="link" href="ClutterBrightnessContrastEffect.html" title="ClutterBrightnessContrastEffect">ClutterBrightnessContrastEffect</a>
69 +----<a class="link" href="ClutterColorizeEffect.html" title="ClutterColorizeEffect">ClutterColorizeEffect</a>
70 +----<a class="link" href="ClutterDeformEffect.html" title="ClutterDeformEffect">ClutterDeformEffect</a>
71 +----<a class="link" href="ClutterDesaturateEffect.html" title="ClutterDesaturateEffect">ClutterDesaturateEffect</a>
72 +----<a class="link" href="ClutterShaderEffect.html" title="ClutterShaderEffect">ClutterShaderEffect</a>
75 <div class="refsect1">
76 <a name="ClutterOffscreenEffect.description"></a><h2>Description</h2>
78 <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> is an abstract class that can be used by
79 <a class="link" href="ClutterEffect.html" title="ClutterEffect"><span class="type">ClutterEffect</span></a> sub-classes requiring access to an offscreen buffer.
82 Some effects, like the fragment shader based effects, can only use GL
83 textures, and in order to apply those effects to any kind of actor they
84 require that all drawing operations are applied to an offscreen framebuffer
85 that gets redirected to a texture.
88 <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> provides all the heavy-lifting for creating the
89 offscreen framebuffer, the redirection and the final paint of the texture on
94 <div class="refsect2">
95 <a name="ClutterOffscreenEffect-implementing"></a><h3>Implementing a ClutterOffscreenEffect</h3>
96 <p>Creating a sub-class of <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> requires, in case
97 of overriding the <a class="link" href="ClutterEffect.html" title="ClutterEffect"><span class="type">ClutterEffect</span></a> virtual functions, to chain up to the
98 <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a>'s implementation.</p>
99 <p>On top of the <a class="link" href="ClutterEffect.html" title="ClutterEffect"><span class="type">ClutterEffect</span></a>'s virtual functions,
100 <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> also provides a <code class="function"><code class="function">paint_target()</code></code>
101 function, which encapsulates the effective painting of the texture that
102 contains the result of the offscreen redirection.</p>
103 <p>The size of the target material is defined to be as big as the
104 transformed size of the <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> using the offscreen effect.
105 Sub-classes of <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> can change the texture creation
106 code to provide bigger textures by overriding the
107 <code class="function"><code class="function">create_texture()</code></code> virtual function; no chain up
108 to the <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> implementation is required in this
114 <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> is available since Clutter 1.4
117 <div class="refsect1">
118 <a name="ClutterOffscreenEffect.details"></a><h2>Details</h2>
119 <div class="refsect2">
120 <a name="ClutterOffscreenEffect-struct"></a><h3>struct ClutterOffscreenEffect</h3>
121 <pre class="programlisting">struct ClutterOffscreenEffect;</pre>
123 The <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> structure contains only private data
124 and should be accessed using the provided API
126 <p class="since">Since 1.4</p>
129 <div class="refsect2">
130 <a name="ClutterOffscreenEffectClass"></a><h3>struct ClutterOffscreenEffectClass</h3>
131 <pre class="programlisting">struct ClutterOffscreenEffectClass {
132 CoglHandle (* create_texture) (ClutterOffscreenEffect *effect,
135 void (* paint_target) (ClutterOffscreenEffect *effect);
139 The <a class="link" href="ClutterOffscreenEffect.html#ClutterOffscreenEffectClass" title="struct ClutterOffscreenEffectClass"><span class="type">ClutterOffscreenEffectClass</span></a> structure contains only private data
141 <div class="variablelist"><table border="0">
142 <col align="left" valign="top">
145 <td><p><span class="term"><em class="structfield"><code><a name="ClutterOffscreenEffectClass.create-texture"></a>create_texture</code></em> ()</span></p></td>
146 <td>virtual function</td>
149 <td><p><span class="term"><em class="structfield"><code><a name="ClutterOffscreenEffectClass.paint-target"></a>paint_target</code></em> ()</span></p></td>
150 <td>virtual function</td>
154 <p class="since">Since 1.4</p>
157 <div class="refsect2">
158 <a name="clutter-offscreen-effect-get-target"></a><h3>clutter_offscreen_effect_get_target ()</h3>
159 <pre class="programlisting"><span class="returnvalue">CoglMaterial</span> * clutter_offscreen_effect_get_target (<em class="parameter"><code><a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> *effect</code></em>);</pre>
161 Retrieves the material used as a render target for the offscreen
162 buffer created by <em class="parameter"><code>effect</code></em>
165 You should only use the returned <span class="type">CoglMaterial</span> when painting. The
166 returned material might change between different frames.
168 <div class="variablelist"><table border="0">
169 <col align="left" valign="top">
172 <td><p><span class="term"><em class="parameter"><code>effect</code></em> :</span></p></td>
173 <td>a <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a>
177 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
178 <td>a <span class="type">CoglMaterial</span> or <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>. The
179 returned material is owned by Clutter and it should not be
180 modified or freed. <span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
185 <p class="since">Since 1.4</p>
188 <div class="refsect2">
189 <a name="clutter-offscreen-effect-get-texture"></a><h3>clutter_offscreen_effect_get_texture ()</h3>
190 <pre class="programlisting"><span class="returnvalue">CoglHandle</span> clutter_offscreen_effect_get_texture
191 (<em class="parameter"><code><a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> *effect</code></em>);</pre>
193 Retrieves the texture used as a render target for the offscreen
194 buffer created by <em class="parameter"><code>effect</code></em>
197 You should only use the returned texture when painting. The texture
198 may change after ClutterEffect::pre_paint is called so the effect
199 implementation should update any references to the texture after
200 chaining-up to the parent's pre_paint implementation. This can be
201 used instead of <a class="link" href="ClutterOffscreenEffect.html#clutter-offscreen-effect-get-target" title="clutter_offscreen_effect_get_target ()"><code class="function">clutter_offscreen_effect_get_target()</code></a> when the
202 effect subclass wants to paint using its own material.
204 <div class="variablelist"><table border="0">
205 <col align="left" valign="top">
208 <td><p><span class="term"><em class="parameter"><code>effect</code></em> :</span></p></td>
209 <td>a <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a>
213 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
214 <td>a <span class="type">CoglHandle</span> or <code class="literal">COGL_INVALID_HANDLE</code>. The
215 returned texture is owned by Clutter and it should not be
216 modified or freed. <span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span>
221 <p class="since">Since 1.10</p>
224 <div class="refsect2">
225 <a name="clutter-offscreen-effect-create-texture"></a><h3>clutter_offscreen_effect_create_texture ()</h3>
226 <pre class="programlisting"><span class="returnvalue">CoglHandle</span> clutter_offscreen_effect_create_texture
227 (<em class="parameter"><code><a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> *effect</code></em>,
228 <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gfloat"><span class="type">gfloat</span></a> width</code></em>,
229 <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gfloat"><span class="type">gfloat</span></a> height</code></em>);</pre>
231 Calls the <code class="function">create_texture()</code> virtual function of the <em class="parameter"><code>effect</code></em>
233 <div class="variablelist"><table border="0">
234 <col align="left" valign="top">
237 <td><p><span class="term"><em class="parameter"><code>effect</code></em> :</span></p></td>
238 <td>a <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a>
242 <td><p><span class="term"><em class="parameter"><code>width</code></em> :</span></p></td>
243 <td>the minimum width of the target texture</td>
246 <td><p><span class="term"><em class="parameter"><code>height</code></em> :</span></p></td>
247 <td>the minimum height of the target texture</td>
250 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
251 <td>a handle to a Cogl texture, or
252 <code class="literal">COGL_INVALID_HANDLE</code>. The returned handle has its reference
253 count increased. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
258 <p class="since">Since 1.4</p>
261 <div class="refsect2">
262 <a name="clutter-offscreen-effect-paint-target"></a><h3>clutter_offscreen_effect_paint_target ()</h3>
263 <pre class="programlisting"><span class="returnvalue">void</span> clutter_offscreen_effect_paint_target
264 (<em class="parameter"><code><a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> *effect</code></em>);</pre>
266 Calls the <code class="function">paint_target()</code> virtual function of the <em class="parameter"><code>effect</code></em>
268 <div class="variablelist"><table border="0">
269 <col align="left" valign="top">
271 <td><p><span class="term"><em class="parameter"><code>effect</code></em> :</span></p></td>
272 <td>a <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a>
276 <p class="since">Since 1.4</p>
279 <div class="refsect2">
280 <a name="clutter-offscreen-effect-get-target-size"></a><h3>clutter_offscreen_effect_get_target_size ()</h3>
281 <pre class="programlisting"><a href="../glib/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> clutter_offscreen_effect_get_target_size
282 (<em class="parameter"><code><a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> *effect</code></em>,
283 <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gfloat"><span class="type">gfloat</span></a> *width</code></em>,
284 <em class="parameter"><code><a href="../glib/glib-Basic-Types.html#gfloat"><span class="type">gfloat</span></a> *height</code></em>);</pre>
286 Retrieves the size of the offscreen buffer used by <em class="parameter"><code>effect</code></em> to
287 paint the actor to which it has been applied.
290 This function should only be called by <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a>
291 implementations, from within the <code class="function"><code class="function">paint_target()</code></code>
294 <div class="variablelist"><table border="0">
295 <col align="left" valign="top">
298 <td><p><span class="term"><em class="parameter"><code>effect</code></em> :</span></p></td>
299 <td>a <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a>
303 <td><p><span class="term"><em class="parameter"><code>width</code></em> :</span></p></td>
304 <td>return location for the target width, or <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span>
308 <td><p><span class="term"><em class="parameter"><code>height</code></em> :</span></p></td>
309 <td>return location for the target height, or <a href="/home/ebassi/gnome3/install/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span>
313 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
315 <a href="../glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the offscreen buffer has a valid size,
316 and <a href="../glib/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise</td>
320 <p class="since">Since 1.8</p>
323 <div class="refsect1">
324 <a name="ClutterOffscreenEffect.see-also"></a><h2>See Also</h2>
325 <a class="link" href="ClutterBlurEffect.html" title="ClutterBlurEffect"><span class="type">ClutterBlurEffect</span></a>, <a class="link" href="ClutterEffect.html" title="ClutterEffect"><span class="type">ClutterEffect</span></a>
330 Generated by GTK-Doc V1.18.1</div>