← Back to branch summary

~oem-solutions-group/unity-2d/clutter-1.0

« back to all changes in this revision

Viewing changes to doc/reference/cogl/html/cogl-Clipping.html

  • Committer: Bazaar Package Importer
  • Author(s): Emilio Pozuelo Monfort
  • Date: 2010-03-21 13:27:56 UTC
  • mto: (2.1.3 experimental)
  • mto: This revision was merged to the branch mainline in revision 8.
  • Revision ID: james.westby@ubuntu.com-20100321132756-nf8yd30yxo3zzwcm
Tags: upstream-1.2.2
Import upstream version 1.2.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/reference/cogl/html/cogl-Clipping.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>Clipping</title>
 
6
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
 
7
<link rel="home" href="index.html" title="COGL Reference Manual">
 
8
<link rel="up" href="ch01.html" title="COGL - GL Abstraction API">
 
9
<link rel="prev" href="cogl-Primitives.html" title="Primitives">
 
10
<link rel="next" href="cogl-Vertex-Buffers.html" title="Vertex Buffers">
 
11
<meta name="generator" content="GTK-Doc V1.13 (XML mode)">
 
12
<link rel="stylesheet" href="style.css" type="text/css">
 
13
<link rel="chapter" href="ch01.html" title="COGL - GL Abstraction API">
 
14
<link rel="chapter" href="ch02.html" title="COGL experimental API">
 
15
<link rel="index" href="ix01.html" title="Index of all symbols">
 
16
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
 
17
<link rel="index" href="ix03.html" title="Index of new symbols in 0.8">
 
18
<link rel="index" href="ix04.html" title="Index of new symbols in 1.0">
 
19
<link rel="index" href="ix05.html" title="Index of new symbols in 1.2">
 
20
<link rel="appendix" href="license.html" title="Appendix A. License">
 
21
</head>
 
22
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
 
23
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
 
24
<tr valign="middle">
 
25
<td><a accesskey="p" href="cogl-Primitives.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
 
26
<td><a accesskey="u" href="ch01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
 
27
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
 
28
<th width="100%" align="center">COGL Reference Manual</th>
 
29
<td><a accesskey="n" href="cogl-Vertex-Buffers.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
 
30
</tr>
 
31
<tr><td colspan="5" class="shortcuts">
 
32
<a href="#cogl-Clipping.synopsis" class="shortcut">Top</a>
 
33
                   | 
 
34
                  <a href="#cogl-Clipping.description" class="shortcut">Description</a>
 
35
</td></tr>
 
36
</table>
 
37
<div class="refentry" title="Clipping">
 
38
<a name="cogl-Clipping"></a><div class="titlepage"></div>
 
39
<div class="refnamediv"><table width="100%"><tr>
 
40
<td valign="top">
 
41
<h2><span class="refentrytitle"><a name="cogl-Clipping.top_of_page"></a>Clipping</span></h2>
 
42
<p>Clipping — Fuctions for manipulating a stack of clipping regions</p>
 
43
</td>
 
44
<td valign="top" align="right"></td>
 
45
</tr></table></div>
 
46
<div class="refsynopsisdiv" title="Synopsis">
 
47
<a name="cogl-Clipping.synopsis"></a><h2>Synopsis</h2>
 
48
<pre class="synopsis"><span class="returnvalue">void</span>                <a class="link" href="cogl-Clipping.html#cogl-clip-push-rectangle" title="cogl_clip_push_rectangle ()">cogl_clip_push_rectangle</a>            (<span class="returnvalue">float</span> x0,
 
49
                                                         <span class="returnvalue">float</span> y0,
 
50
                                                         <span class="returnvalue">float</span> x1,
 
51
                                                         <span class="returnvalue">float</span> y1);
 
52
<span class="returnvalue">void</span>                <a class="link" href="cogl-Clipping.html#cogl-clip-push-window-rectangle" title="cogl_clip_push_window_rectangle ()">cogl_clip_push_window_rectangle</a>     (<span class="returnvalue">int</span> x_offset,
 
53
                                                         <span class="returnvalue">int</span> y_offset,
 
54
                                                         <span class="returnvalue">int</span> width,
 
55
                                                         <span class="returnvalue">int</span> height);
 
56
<span class="returnvalue">void</span>                <a class="link" href="cogl-Clipping.html#cogl-clip-push-from-path" title="cogl_clip_push_from_path ()">cogl_clip_push_from_path</a>            (void);
 
57
<span class="returnvalue">void</span>                <a class="link" href="cogl-Clipping.html#cogl-clip-push-from-path-preserve" title="cogl_clip_push_from_path_preserve ()">cogl_clip_push_from_path_preserve</a>   (void);
 
58
<span class="returnvalue">void</span>                <a class="link" href="cogl-Clipping.html#cogl-clip-pop" title="cogl_clip_pop ()">cogl_clip_pop</a>                       (void);
 
59
 
 
60
<span class="returnvalue">void</span>                <a class="link" href="cogl-Clipping.html#cogl-clip-push" title="cogl_clip_push ()">cogl_clip_push</a>                      (<span class="returnvalue">float</span> x_offset,
 
61
                                                         <span class="returnvalue">float</span> y_offset,
 
62
                                                         <span class="returnvalue">float</span> width,
 
63
                                                         <span class="returnvalue">float</span> height);
 
64
<span class="returnvalue">void</span>                <a class="link" href="cogl-Clipping.html#cogl-clip-push-window-rect" title="cogl_clip_push_window_rect ()">cogl_clip_push_window_rect</a>          (<span class="returnvalue">float</span> x_offset,
 
65
                                                         <span class="returnvalue">float</span> y_offset,
 
66
                                                         <span class="returnvalue">float</span> width,
 
67
                                                         <span class="returnvalue">float</span> height);
 
68
<span class="returnvalue">void</span>                <a class="link" href="cogl-Clipping.html#cogl-clip-ensure" title="cogl_clip_ensure ()">cogl_clip_ensure</a>                    (void);
 
69
<span class="returnvalue">void</span>                <a class="link" href="cogl-Clipping.html#cogl-clip-stack-save" title="cogl_clip_stack_save ()">cogl_clip_stack_save</a>                (void);
 
70
<span class="returnvalue">void</span>                <a class="link" href="cogl-Clipping.html#cogl-clip-stack-restore" title="cogl_clip_stack_restore ()">cogl_clip_stack_restore</a>             (void);
 
71
</pre>
 
72
</div>
 
73
<div class="refsect1" title="Description">
 
74
<a name="cogl-Clipping.description"></a><h2>Description</h2>
 
75
<p>
 
76
To support clipping your geometry to rectangles or paths Cogl exposes a
 
77
stack based API whereby each clip region you push onto the stack is
 
78
intersected with the previous region.</p>
 
79
</div>
 
80
<div class="refsect1" title="Details">
 
81
<a name="cogl-Clipping.details"></a><h2>Details</h2>
 
82
<div class="refsect2" title="cogl_clip_push_rectangle ()">
 
83
<a name="cogl-clip-push-rectangle"></a><h3>cogl_clip_push_rectangle ()</h3>
 
84
<pre class="programlisting"><span class="returnvalue">void</span>                cogl_clip_push_rectangle            (<span class="returnvalue">float</span> x0,
 
85
                                                         <span class="returnvalue">float</span> y0,
 
86
                                                         <span class="returnvalue">float</span> x1,
 
87
                                                         <span class="returnvalue">float</span> y1);</pre>
 
88
<p>
 
89
Specifies a rectangular clipping area for all subsequent drawing
 
90
operations. Any drawing commands that extend outside the rectangle
 
91
will be clipped so that only the portion inside the rectangle will
 
92
be displayed. The rectangle dimensions are transformed by the
 
93
current model-view matrix.
 
94
</p>
 
95
<p>
 
96
The rectangle is intersected with the current clip region. To undo
 
97
the effect of this function, call <a class="link" href="cogl-Clipping.html#cogl-clip-pop" title="cogl_clip_pop ()"><code class="function">cogl_clip_pop()</code></a>.</p>
 
98
<div class="variablelist"><table border="0">
 
99
<col align="left" valign="top">
 
100
<tbody>
 
101
<tr>
 
102
<td><p><span class="term"><em class="parameter"><code>x0</code></em> :</span></p></td>
 
103
<td> x coordinate for top left corner of the clip rectangle
 
104
</td>
 
105
</tr>
 
106
<tr>
 
107
<td><p><span class="term"><em class="parameter"><code>y0</code></em> :</span></p></td>
 
108
<td> y coordinate for top left corner of the clip rectangle
 
109
</td>
 
110
</tr>
 
111
<tr>
 
112
<td><p><span class="term"><em class="parameter"><code>x1</code></em> :</span></p></td>
 
113
<td> x coordinate for bottom right corner of the clip rectangle
 
114
</td>
 
115
</tr>
 
116
<tr>
 
117
<td><p><span class="term"><em class="parameter"><code>y1</code></em> :</span></p></td>
 
118
<td> y coordinate for bottom right corner of the clip rectangle
 
119
</td>
 
120
</tr>
 
121
</tbody>
 
122
</table></div>
 
123
<p class="since">Since 1.2</p>
 
124
</div>
 
125
<hr>
 
126
<div class="refsect2" title="cogl_clip_push_window_rectangle ()">
 
127
<a name="cogl-clip-push-window-rectangle"></a><h3>cogl_clip_push_window_rectangle ()</h3>
 
128
<pre class="programlisting"><span class="returnvalue">void</span>                cogl_clip_push_window_rectangle     (<span class="returnvalue">int</span> x_offset,
 
129
                                                         <span class="returnvalue">int</span> y_offset,
 
130
                                                         <span class="returnvalue">int</span> width,
 
131
                                                         <span class="returnvalue">int</span> height);</pre>
 
132
<p>
 
133
Specifies a rectangular clipping area for all subsequent drawing
 
134
operations. Any drawing commands that extend outside the rectangle
 
135
will be clipped so that only the portion inside the rectangle will
 
136
be displayed. The rectangle dimensions are not transformed by the
 
137
current model-view matrix.
 
138
</p>
 
139
<p>
 
140
The rectangle is intersected with the current clip region. To undo
 
141
the effect of this function, call <a class="link" href="cogl-Clipping.html#cogl-clip-pop" title="cogl_clip_pop ()"><code class="function">cogl_clip_pop()</code></a>.</p>
 
142
<div class="variablelist"><table border="0">
 
143
<col align="left" valign="top">
 
144
<tbody>
 
145
<tr>
 
146
<td><p><span class="term"><em class="parameter"><code>x_offset</code></em> :</span></p></td>
 
147
<td> left edge of the clip rectangle in window coordinates
 
148
</td>
 
149
</tr>
 
150
<tr>
 
151
<td><p><span class="term"><em class="parameter"><code>y_offset</code></em> :</span></p></td>
 
152
<td> top edge of the clip rectangle in window coordinates
 
153
</td>
 
154
</tr>
 
155
<tr>
 
156
<td><p><span class="term"><em class="parameter"><code>width</code></em> :</span></p></td>
 
157
<td> width of the clip rectangle
 
158
</td>
 
159
</tr>
 
160
<tr>
 
161
<td><p><span class="term"><em class="parameter"><code>height</code></em> :</span></p></td>
 
162
<td> height of the clip rectangle
 
163
</td>
 
164
</tr>
 
165
</tbody>
 
166
</table></div>
 
167
<p class="since">Since 1.2</p>
 
168
</div>
 
169
<hr>
 
170
<div class="refsect2" title="cogl_clip_push_from_path ()">
 
171
<a name="cogl-clip-push-from-path"></a><h3>cogl_clip_push_from_path ()</h3>
 
172
<pre class="programlisting"><span class="returnvalue">void</span>                cogl_clip_push_from_path            (void);</pre>
 
173
<p>
 
174
Sets a new clipping area using the current path. The current path
 
175
is then cleared. The clipping area is intersected with the previous
 
176
clipping area. To restore the previous clipping area, call
 
177
<a class="link" href="cogl-Clipping.html#cogl-clip-pop" title="cogl_clip_pop ()"><code class="function">cogl_clip_pop()</code></a>.</p>
 
178
<p class="since">Since 1.0</p>
 
179
</div>
 
180
<hr>
 
181
<div class="refsect2" title="cogl_clip_push_from_path_preserve ()">
 
182
<a name="cogl-clip-push-from-path-preserve"></a><h3>cogl_clip_push_from_path_preserve ()</h3>
 
183
<pre class="programlisting"><span class="returnvalue">void</span>                cogl_clip_push_from_path_preserve   (void);</pre>
 
184
<p>
 
185
Sets a new clipping area using the current path. The current path
 
186
is then cleared. The clipping area is intersected with the previous
 
187
clipping area. To restore the previous clipping area, call
 
188
<a class="link" href="cogl-Clipping.html#cogl-clip-pop" title="cogl_clip_pop ()"><code class="function">cogl_clip_pop()</code></a>.</p>
 
189
<p class="since">Since 1.0</p>
 
190
</div>
 
191
<hr>
 
192
<div class="refsect2" title="cogl_clip_pop ()">
 
193
<a name="cogl-clip-pop"></a><h3>cogl_clip_pop ()</h3>
 
194
<pre class="programlisting"><span class="returnvalue">void</span>                cogl_clip_pop                       (void);</pre>
 
195
<p>
 
196
Reverts the clipping region to the state before the last call to
 
197
<a class="link" href="cogl-Clipping.html#cogl-clip-push" title="cogl_clip_push ()"><code class="function">cogl_clip_push()</code></a>.</p>
 
198
</div>
 
199
<hr>
 
200
<div class="refsect2" title="cogl_clip_push ()">
 
201
<a name="cogl-clip-push"></a><h3>cogl_clip_push ()</h3>
 
202
<pre class="programlisting"><span class="returnvalue">void</span>                cogl_clip_push                      (<span class="returnvalue">float</span> x_offset,
 
203
                                                         <span class="returnvalue">float</span> y_offset,
 
204
                                                         <span class="returnvalue">float</span> width,
 
205
                                                         <span class="returnvalue">float</span> height);</pre>
 
206
<div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 
207
<h3 class="title">Warning</h3>
 
208
<p><code class="literal">cogl_clip_push</code> has been deprecated since version 1.2 and should not be used in newly-written code. The x, y, width, height arguments are inconsistent
 
209
  with other API that specify rectangles in model space, and when used
 
210
  with a coordinate space that puts the origin at the center and y+
 
211
  extending up, it's awkward to use. Please use <a class="link" href="cogl-Clipping.html#cogl-clip-push-rectangle" title="cogl_clip_push_rectangle ()"><code class="function">cogl_clip_push_rectangle()</code></a>
 
212
  instead</p>
 
213
</div>
 
214
<p>
 
215
Specifies a rectangular clipping area for all subsequent drawing
 
216
operations. Any drawing commands that extend outside the rectangle
 
217
will be clipped so that only the portion inside the rectangle will
 
218
be displayed. The rectangle dimensions are transformed by the
 
219
current model-view matrix.
 
220
</p>
 
221
<p>
 
222
The rectangle is intersected with the current clip region. To undo
 
223
the effect of this function, call <a class="link" href="cogl-Clipping.html#cogl-clip-pop" title="cogl_clip_pop ()"><code class="function">cogl_clip_pop()</code></a>.</p>
 
224
<div class="variablelist"><table border="0">
 
225
<col align="left" valign="top">
 
226
<tbody>
 
227
<tr>
 
228
<td><p><span class="term"><em class="parameter"><code>x_offset</code></em> :</span></p></td>
 
229
<td> left edge of the clip rectangle
 
230
</td>
 
231
</tr>
 
232
<tr>
 
233
<td><p><span class="term"><em class="parameter"><code>y_offset</code></em> :</span></p></td>
 
234
<td> top edge of the clip rectangle
 
235
</td>
 
236
</tr>
 
237
<tr>
 
238
<td><p><span class="term"><em class="parameter"><code>width</code></em> :</span></p></td>
 
239
<td> width of the clip rectangle
 
240
</td>
 
241
</tr>
 
242
<tr>
 
243
<td><p><span class="term"><em class="parameter"><code>height</code></em> :</span></p></td>
 
244
<td> height of the clip rectangle
 
245
</td>
 
246
</tr>
 
247
</tbody>
 
248
</table></div>
 
249
</div>
 
250
<hr>
 
251
<div class="refsect2" title="cogl_clip_push_window_rect ()">
 
252
<a name="cogl-clip-push-window-rect"></a><h3>cogl_clip_push_window_rect ()</h3>
 
253
<pre class="programlisting"><span class="returnvalue">void</span>                cogl_clip_push_window_rect          (<span class="returnvalue">float</span> x_offset,
 
254
                                                         <span class="returnvalue">float</span> y_offset,
 
255
                                                         <span class="returnvalue">float</span> width,
 
256
                                                         <span class="returnvalue">float</span> height);</pre>
 
257
<div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 
258
<h3 class="title">Warning</h3>
 
259
<p><code class="literal">cogl_clip_push_window_rect</code> has been deprecated since version 1.2 and should not be used in newly-written code. Use <a class="link" href="cogl-Clipping.html#cogl-clip-push-window-rectangle" title="cogl_clip_push_window_rectangle ()"><code class="function">cogl_clip_push_window_rectangle()</code></a> instead</p>
 
260
</div>
 
261
<p>
 
262
Specifies a rectangular clipping area for all subsequent drawing
 
263
operations. Any drawing commands that extend outside the rectangle
 
264
will be clipped so that only the portion inside the rectangle will
 
265
be displayed. The rectangle dimensions are not transformed by the
 
266
current model-view matrix.
 
267
</p>
 
268
<p>
 
269
The rectangle is intersected with the current clip region. To undo
 
270
the effect of this function, call <a class="link" href="cogl-Clipping.html#cogl-clip-pop" title="cogl_clip_pop ()"><code class="function">cogl_clip_pop()</code></a>.</p>
 
271
<div class="variablelist"><table border="0">
 
272
<col align="left" valign="top">
 
273
<tbody>
 
274
<tr>
 
275
<td><p><span class="term"><em class="parameter"><code>x_offset</code></em> :</span></p></td>
 
276
<td> left edge of the clip rectangle in window coordinates
 
277
</td>
 
278
</tr>
 
279
<tr>
 
280
<td><p><span class="term"><em class="parameter"><code>y_offset</code></em> :</span></p></td>
 
281
<td> top edge of the clip rectangle in window coordinates
 
282
</td>
 
283
</tr>
 
284
<tr>
 
285
<td><p><span class="term"><em class="parameter"><code>width</code></em> :</span></p></td>
 
286
<td> width of the clip rectangle
 
287
</td>
 
288
</tr>
 
289
<tr>
 
290
<td><p><span class="term"><em class="parameter"><code>height</code></em> :</span></p></td>
 
291
<td> height of the clip rectangle
 
292
</td>
 
293
</tr>
 
294
</tbody>
 
295
</table></div>
 
296
</div>
 
297
<hr>
 
298
<div class="refsect2" title="cogl_clip_ensure ()">
 
299
<a name="cogl-clip-ensure"></a><h3>cogl_clip_ensure ()</h3>
 
300
<pre class="programlisting"><span class="returnvalue">void</span>                cogl_clip_ensure                    (void);</pre>
 
301
<div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 
302
<h3 class="title">Warning</h3>
 
303
<p><code class="literal">cogl_clip_ensure</code> has been deprecated since version 1.2 and should not be used in newly-written code. Calling this function has no effect</p>
 
304
</div>
 
305
<p>
 
306
Ensures that the current clipping region has been set in GL. This
 
307
will automatically be called before any Cogl primitives but it
 
308
maybe be neccessary to call if you are using raw GL calls with
 
309
clipping.</p>
 
310
<p class="since">Since 1.0</p>
 
311
</div>
 
312
<hr>
 
313
<div class="refsect2" title="cogl_clip_stack_save ()">
 
314
<a name="cogl-clip-stack-save"></a><h3>cogl_clip_stack_save ()</h3>
 
315
<pre class="programlisting"><span class="returnvalue">void</span>                cogl_clip_stack_save                (void);</pre>
 
316
<div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 
317
<h3 class="title">Warning</h3>
 
318
<p><code class="literal">cogl_clip_stack_save</code> has been deprecated since version 1.2 and should not be used in newly-written code. This was originally added to allow us to save the
 
319
  clip stack when switching to an offscreen framebuffer, but it's
 
320
  not necessary anymore given that framebuffers now own separate
 
321
  clip stacks which will be automatically switched between when a
 
322
  new buffer is set. Calling this function has no effect</p>
 
323
</div>
 
324
<p>
 
325
Save the entire state of the clipping stack and then clear all
 
326
clipping. The previous state can be returned to with
 
327
<a class="link" href="cogl-Clipping.html#cogl-clip-stack-restore" title="cogl_clip_stack_restore ()"><code class="function">cogl_clip_stack_restore()</code></a>. Each call to <a class="link" href="cogl-Clipping.html#cogl-clip-push" title="cogl_clip_push ()"><code class="function">cogl_clip_push()</code></a> after this
 
328
must be matched by a call to <a class="link" href="cogl-Clipping.html#cogl-clip-pop" title="cogl_clip_pop ()"><code class="function">cogl_clip_pop()</code></a> before calling
 
329
<a class="link" href="cogl-Clipping.html#cogl-clip-stack-restore" title="cogl_clip_stack_restore ()"><code class="function">cogl_clip_stack_restore()</code></a>.</p>
 
330
<p class="since">Since 0.8.2</p>
 
331
</div>
 
332
<hr>
 
333
<div class="refsect2" title="cogl_clip_stack_restore ()">
 
334
<a name="cogl-clip-stack-restore"></a><h3>cogl_clip_stack_restore ()</h3>
 
335
<pre class="programlisting"><span class="returnvalue">void</span>                cogl_clip_stack_restore             (void);</pre>
 
336
<div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 
337
<h3 class="title">Warning</h3>
 
338
<p><code class="literal">cogl_clip_stack_restore</code> has been deprecated since version 1.2 and should not be used in newly-written code. This was originally added to allow us to restore
 
339
  the clip stack when switching back from an offscreen framebuffer,
 
340
  but it's not necessary anymore given that framebuffers now own
 
341
  separate clip stacks which will be automatically switched between
 
342
  when a new buffer is set. Calling this function has no effect</p>
 
343
</div>
 
344
<p>
 
345
Restore the state of the clipping stack that was previously saved
 
346
by <a class="link" href="cogl-Clipping.html#cogl-clip-stack-save" title="cogl_clip_stack_save ()"><code class="function">cogl_clip_stack_save()</code></a>.</p>
 
347
<p class="since">Since 0.8.2</p>
 
348
</div>
 
349
</div>
 
350
</div>
 
351
<div class="footer">
 
352
<hr>
 
353
          Generated by GTK-Doc V1.13</div>
 
354
</body>
 
355
</html>
 
 
b'\\ No newline at end of file'