doc/reference/clutter/html/ClutterOffscreenEffect.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   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">
  13 </head>
  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">
  16 <tr valign="middle">
  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>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#ClutterOffscreenEffect.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#ClutterOffscreenEffect.description" class="shortcut">Description</a>
  27                    |
  28                   <a href="#ClutterOffscreenEffect.object-hierarchy" class="shortcut">Object Hierarchy</a>
  29 </td></tr>
  30 </table>
  31 <div class="refentry">
  32 <a name="ClutterOffscreenEffect"></a><div class="titlepage"></div>
  33 <div class="refnamediv"><table width="100%"><tr>
  34 <td valign="top">
  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>
  37 </td>
  38 <td valign="top" align="right"></td>
  39 </tr></table></div>
  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><span class="type">gfloat</span> width</code></em>,
  50                                                          <em class="parameter"><code><span class="type">gfloat</span> 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 <span class="returnvalue">gboolean</span>            <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><span class="type">gfloat</span> *width</code></em>,
  56                                                          <em class="parameter"><code><span class="type">gfloat</span> *height</code></em>);
  57 </pre>
  58 </div>
  59 <div class="refsect1">
  60 <a name="ClutterOffscreenEffect.object-hierarchy"></a><h2>Object Hierarchy</h2>
  61 <pre class="synopsis">
  62   GObject
  63    +----GInitiallyUnowned
  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>
  73 </pre>
  74 </div>
  75 <div class="refsect1">
  76 <a name="ClutterOffscreenEffect.description"></a><h2>Description</h2>
  77 <p>
  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.
  80 </p>
  81 <p>
  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.
  86 </p>
  87 <p>
  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
  90 the desired stage.
  91 </p>
  92 <p>
  93 </p>
  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
 109   case.</p>
 110 </div>
 111 <p>
 112 </p>
 113 <p>
 114 <a class="link" href="ClutterOffscreenEffect.html" title="ClutterOffscreenEffect"><span class="type">ClutterOffscreenEffect</span></a> is available since Clutter 1.4
 115 </p>
 116 </div>
 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>
 122 <p>
 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
 125 </p>
 126 <p class="since">Since 1.4</p>
 127 </div>
 128 <hr>
 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,
 133                                  gfloat                  width,
 134                                  gfloat                  height);
 135   void       (* paint_target)   (ClutterOffscreenEffect *effect);
 136 };
 137 </pre>
 138 <p>
 139 The <a class="link" href="ClutterOffscreenEffect.html#ClutterOffscreenEffectClass" title="struct ClutterOffscreenEffectClass"><span class="type">ClutterOffscreenEffectClass</span></a> structure contains only private data
 140 </p>
 141 <div class="variablelist"><table border="0">
 142 <col align="left" valign="top">
 143 <tbody>
 144 <tr>
 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>
 147 </tr>
 148 <tr>
 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>
 151 </tr>
 152 </tbody>
 153 </table></div>
 154 <p class="since">Since 1.4</p>
 155 </div>
 156 <hr>
 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>
 160 <p>
 161 Retrieves the material used as a render target for the offscreen
 162 buffer created by <em class="parameter"><code>effect</code></em>
 163 </p>
 164 <p>
 165 You should only use the returned <span class="type">CoglMaterial</span> when painting. The
 166 returned material might change between different frames.
 167 </p>
 168 <div class="variablelist"><table border="0">
 169 <col align="left" valign="top">
 170 <tbody>
 171 <tr>
 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>
 174 </td>
 175 </tr>
 176 <tr>
 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>
 181 </td>
 182 </tr>
 183 </tbody>
 184 </table></div>
 185 <p class="since">Since 1.4</p>
 186 </div>
 187 <hr>
 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>
 192 <p>
 193 Retrieves the texture used as a render target for the offscreen
 194 buffer created by <em class="parameter"><code>effect</code></em>
 195 </p>
 196 <p>
 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.
 203 </p>
 204 <div class="variablelist"><table border="0">
 205 <col align="left" valign="top">
 206 <tbody>
 207 <tr>
 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>
 210 </td>
 211 </tr>
 212 <tr>
 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>
 217 </td>
 218 </tr>
 219 </tbody>
 220 </table></div>
 221 <p class="since">Since 1.10</p>
 222 </div>
 223 <hr>
 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><span class="type">gfloat</span> width</code></em>,
 229                                                          <em class="parameter"><code><span class="type">gfloat</span> height</code></em>);</pre>
 230 <p>
 231 Calls the <code class="function">create_texture()</code> virtual function of the <em class="parameter"><code>effect</code></em>
 232 </p>
 233 <div class="variablelist"><table border="0">
 234 <col align="left" valign="top">
 235 <tbody>
 236 <tr>
 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>
 239 </td>
 240 </tr>
 241 <tr>
 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>
 244 </tr>
 245 <tr>
 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>
 248 </tr>
 249 <tr>
 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>
 254 </td>
 255 </tr>
 256 </tbody>
 257 </table></div>
 258 <p class="since">Since 1.4</p>
 259 </div>
 260 <hr>
 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>
 265 <p>
 266 Calls the <code class="function">paint_target()</code> virtual function of the <em class="parameter"><code>effect</code></em>
 267 </p>
 268 <div class="variablelist"><table border="0">
 269 <col align="left" valign="top">
 270 <tbody><tr>
 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>
 273 </td>
 274 </tr></tbody>
 275 </table></div>
 276 <p class="since">Since 1.4</p>
 277 </div>
 278 <hr>
 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"><span class="returnvalue">gboolean</span>            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><span class="type">gfloat</span> *width</code></em>,
 284                                                          <em class="parameter"><code><span class="type">gfloat</span> *height</code></em>);</pre>
 285 <p>
 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.
 288 </p>
 289 <p>
 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>
 292 virtual function.
 293 </p>
 294 <div class="variablelist"><table border="0">
 295 <col align="left" valign="top">
 296 <tbody>
 297 <tr>
 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>
 300 </td>
 301 </tr>
 302 <tr>
 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>
 305 </td>
 306 </tr>
 307 <tr>
 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>
 310 </td>
 311 </tr>
 312 <tr>
 313 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 314 <td>
 315 <code class="literal">TRUE</code> if the offscreen buffer has a valid size,
 316 and <code class="literal">FALSE</code> otherwise</td>
 317 </tr>
 318 </tbody>
 319 </table></div>
 320 <p class="since">Since 1.8</p>
 321 </div>
 322 </div>
 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>
 326 </div>
 327 </div>
 328 <div class="footer">
 329 <hr>
 330           Generated by GTK-Doc V1.18.1</div>
 331 </body>
 332 </html>