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-Primitives">
8
<refentrytitle role="top_of_page" id="cogl-Primitives.top_of_page">Primitives</refentrytitle>
9
<manvolnum>3</manvolnum>
10
<refmiscinfo>COGL Library</refmiscinfo>
14
<refname>Primitives</refname>
15
<refpurpose>Functions that draw various primitive shapes and
16
allow for construction of more complex paths.</refpurpose>
19
<refsynopsisdiv id="cogl-Primitives.synopsis" role="synopsis">
20
<title role="synopsis.title">Synopsis</title>
23
<link linkend="void">void</link> <link linkend="cogl-rectangle">cogl_rectangle</link> (<link linkend="float">float</link> x_1,
24
<link linkend="float">float</link> y_1,
25
<link linkend="float">float</link> x_2,
26
<link linkend="float">float</link> y_2);
27
<link linkend="void">void</link> <link linkend="cogl-rectangles">cogl_rectangles</link> (const <link linkend="float">float</link> *verts,
28
<link linkend="guint">guint</link> n_rects);
29
<link linkend="void">void</link> <link linkend="cogl-rectangle-with-texture-coords">cogl_rectangle_with_texture_coords</link> (<link linkend="float">float</link> x1,
30
<link linkend="float">float</link> y1,
31
<link linkend="float">float</link> x2,
32
<link linkend="float">float</link> y2,
33
<link linkend="float">float</link> tx1,
34
<link linkend="float">float</link> ty1,
35
<link linkend="float">float</link> tx2,
36
<link linkend="float">float</link> ty2);
37
<link linkend="void">void</link> <link linkend="cogl-rectangles-with-texture-coords">cogl_rectangles_with_texture_coords</link> (const <link linkend="float">float</link> *verts,
38
<link linkend="guint">guint</link> n_rects);
39
<link linkend="void">void</link> <link linkend="cogl-rectangle-with-multitexture-coords">cogl_rectangle_with_multitexture_coords</link>
40
(<link linkend="float">float</link> x1,
41
<link linkend="float">float</link> y1,
42
<link linkend="float">float</link> x2,
43
<link linkend="float">float</link> y2,
44
const <link linkend="float">float</link> *tex_coords,
45
<link linkend="gint">gint</link> tex_coords_len);
46
<link linkend="void">void</link> <link linkend="cogl-polygon">cogl_polygon</link> (<link linkend="CoglTextureVertex">CoglTextureVertex</link> *vertices,
47
<link linkend="guint">guint</link> n_vertices,
48
<link linkend="gboolean">gboolean</link> use_color);
50
<link linkend="void">void</link> <link linkend="cogl-path-new">cogl_path_new</link> (void);
51
<link linkend="void">void</link> <link linkend="cogl-path-move-to">cogl_path_move_to</link> (<link linkend="float">float</link> x,
52
<link linkend="float">float</link> y);
53
<link linkend="void">void</link> <link linkend="cogl-path-close">cogl_path_close</link> (void);
54
<link linkend="void">void</link> <link linkend="cogl-path-line-to">cogl_path_line_to</link> (<link linkend="float">float</link> x,
55
<link linkend="float">float</link> y);
56
<link linkend="void">void</link> <link linkend="cogl-path-curve-to">cogl_path_curve_to</link> (<link linkend="float">float</link> x_1,
57
<link linkend="float">float</link> y_1,
58
<link linkend="float">float</link> x_2,
59
<link linkend="float">float</link> y_2,
60
<link linkend="float">float</link> x_3,
61
<link linkend="float">float</link> y_3);
62
<link linkend="void">void</link> <link linkend="cogl-path-arc">cogl_path_arc</link> (<link linkend="float">float</link> center_x,
63
<link linkend="float">float</link> center_y,
64
<link linkend="float">float</link> radius_x,
65
<link linkend="float">float</link> radius_y,
66
<link linkend="float">float</link> angle_1,
67
<link linkend="float">float</link> angle_2);
68
<link linkend="void">void</link> <link linkend="cogl-path-rel-move-to">cogl_path_rel_move_to</link> (<link linkend="float">float</link> x,
69
<link linkend="float">float</link> y);
70
<link linkend="void">void</link> <link linkend="cogl-path-rel-line-to">cogl_path_rel_line_to</link> (<link linkend="float">float</link> x,
71
<link linkend="float">float</link> y);
72
<link linkend="void">void</link> <link linkend="cogl-path-rel-curve-to">cogl_path_rel_curve_to</link> (<link linkend="float">float</link> x_1,
73
<link linkend="float">float</link> y_1,
74
<link linkend="float">float</link> x_2,
75
<link linkend="float">float</link> y_2,
76
<link linkend="float">float</link> x_3,
77
<link linkend="float">float</link> y_3);
78
<link linkend="void">void</link> <link linkend="cogl-path-line">cogl_path_line</link> (<link linkend="float">float</link> x_1,
79
<link linkend="float">float</link> y_1,
80
<link linkend="float">float</link> x_2,
81
<link linkend="float">float</link> y_2);
82
<link linkend="void">void</link> <link linkend="cogl-path-polyline">cogl_path_polyline</link> (<link linkend="float">float</link> *coords,
83
<link linkend="gint">gint</link> num_points);
84
<link linkend="void">void</link> <link linkend="cogl-path-polygon">cogl_path_polygon</link> (<link linkend="float">float</link> *coords,
85
<link linkend="gint">gint</link> num_points);
86
<link linkend="void">void</link> <link linkend="cogl-path-rectangle">cogl_path_rectangle</link> (<link linkend="float">float</link> x_1,
87
<link linkend="float">float</link> y_1,
88
<link linkend="float">float</link> x_2,
89
<link linkend="float">float</link> y_2);
90
<link linkend="void">void</link> <link linkend="cogl-path-round-rectangle">cogl_path_round_rectangle</link> (<link linkend="float">float</link> x_1,
91
<link linkend="float">float</link> y_1,
92
<link linkend="float">float</link> x_2,
93
<link linkend="float">float</link> y_2,
94
<link linkend="float">float</link> radius,
95
<link linkend="float">float</link> arc_step);
96
<link linkend="void">void</link> <link linkend="cogl-path-ellipse">cogl_path_ellipse</link> (<link linkend="float">float</link> center_x,
97
<link linkend="float">float</link> center_y,
98
<link linkend="float">float</link> radius_x,
99
<link linkend="float">float</link> radius_y);
101
<link linkend="void">void</link> <link linkend="cogl-path-fill">cogl_path_fill</link> (void);
102
<link linkend="void">void</link> <link linkend="cogl-path-fill-preserve">cogl_path_fill_preserve</link> (void);
103
<link linkend="void">void</link> <link linkend="cogl-path-stroke">cogl_path_stroke</link> (void);
104
<link linkend="void">void</link> <link linkend="cogl-path-stroke-preserve">cogl_path_stroke_preserve</link> (void);
105
#define <link linkend="cogl-color">cogl_color</link>
117
<refsect1 id="cogl-Primitives.description" role="desc">
118
<title role="desc.title">Description</title>
120
There are three levels on which drawing with cogl can be used. The
121
highest level functions construct various simple primitive shapes
122
to be either filled or stroked. Using a lower-level set of functions
123
more complex and arbitrary paths can be constructed by concatenating
124
straight line, bezier curve and arc segments. Additionally there
125
are utility functions that draw the most common primitives - rectangles
126
and trapezoids - in a maximaly optimized fashion.
129
When constructing arbitrary paths, the current pen location is
130
initialized using the move_to command. The subsequent path segments
131
implicitly use the last pen location as their first vertex and move
132
the pen location to the last vertex they produce at the end. Also
133
there are special versions of functions that allow specifying the
134
vertices of the path segments relative to the last pen location
135
rather then in the absolute coordinates.</para>
140
<refsect1 id="cogl-Primitives.details" role="details">
141
<title role="details.title">Details</title>
142
<refsect2 id="cogl-rectangle" role="function">
143
<title>cogl_rectangle ()</title>
144
<indexterm zone="cogl-rectangle"><primary sortas="rectangle">cogl_rectangle</primary></indexterm><programlisting><link linkend="void">void</link> cogl_rectangle (<link linkend="float">float</link> x_1,
145
<link linkend="float">float</link> y_1,
146
<link linkend="float">float</link> x_2,
147
<link linkend="float">float</link> y_2);</programlisting>
149
Fills a rectangle at the given coordinates with the current source material</para>
151
</para><variablelist role="params">
152
<varlistentry><term><parameter>x_1</parameter> :</term>
153
<listitem><simpara> X coordinate of the top-left corner
154
</simpara></listitem></varlistentry>
155
<varlistentry><term><parameter>y_1</parameter> :</term>
156
<listitem><simpara> Y coordinate of the top-left corner
157
</simpara></listitem></varlistentry>
158
<varlistentry><term><parameter>x_2</parameter> :</term>
159
<listitem><simpara> X coordinate of the bottom-right corner
160
</simpara></listitem></varlistentry>
161
<varlistentry><term><parameter>y_2</parameter> :</term>
162
<listitem><simpara> Y coordinate of the bottom-right corner
163
</simpara></listitem></varlistentry>
164
</variablelist></refsect2>
165
<refsect2 id="cogl-rectangles" role="function" condition="since:1.0">
166
<title>cogl_rectangles ()</title>
167
<indexterm zone="cogl-rectangles" role="1.0"><primary sortas="rectangles">cogl_rectangles</primary></indexterm><programlisting><link linkend="void">void</link> cogl_rectangles (const <link linkend="float">float</link> *verts,
168
<link linkend="guint">guint</link> n_rects);</programlisting>
170
Draws a series of rectangles in the same way that
171
<link linkend="cogl-rectangle"><function>cogl_rectangle()</function></link> does. In some situations it can give a
172
significant performance boost to use this function rather than
173
calling <link linkend="cogl-rectangle"><function>cogl_rectangle()</function></link> separately for each rectangle.
176
<parameter>verts</parameter> should point to an array of <link linkend="float"><type>float</type></link><!-- -->s with
177
<parameter>n_rects</parameter> * 4 elements. Each group of 4 values corresponds to the
178
parameters x1, y1, x2, and y2, and have the same
179
meaning as in <link linkend="cogl-rectangle"><function>cogl_rectangle()</function></link>.</para>
181
</para><variablelist role="params">
182
<varlistentry><term><parameter>verts</parameter> :</term>
183
<listitem><simpara> an array of vertices. <acronym>in</acronym>. <acronym>array</acronym>. <acronym>transfer</acronym> none. </simpara></listitem></varlistentry>
184
<varlistentry><term><parameter>n_rects</parameter> :</term>
185
<listitem><simpara> number of rectangles to draw
186
</simpara></listitem></varlistentry>
187
</variablelist><para role="since">Since 1.0</para></refsect2>
188
<refsect2 id="cogl-rectangle-with-texture-coords" role="function">
189
<title>cogl_rectangle_with_texture_coords ()</title>
190
<indexterm zone="cogl-rectangle-with-texture-coords"><primary sortas="rectangle_with_texture_coords">cogl_rectangle_with_texture_coords</primary></indexterm><programlisting><link linkend="void">void</link> cogl_rectangle_with_texture_coords (<link linkend="float">float</link> x1,
191
<link linkend="float">float</link> y1,
192
<link linkend="float">float</link> x2,
193
<link linkend="float">float</link> y2,
194
<link linkend="float">float</link> tx1,
195
<link linkend="float">float</link> ty1,
196
<link linkend="float">float</link> tx2,
197
<link linkend="float">float</link> ty2);</programlisting>
199
Draw a rectangle using the current material and supply texture coordinates
200
to be used for the first texture layer of the material. To draw the entire
201
texture pass in <parameter>tx1</parameter>=0.0 <parameter>ty1</parameter>=0.0 <parameter>tx2</parameter>=1.0 <parameter>ty2</parameter>=1.0.
206
</para><variablelist role="params">
207
<varlistentry><term><parameter>x1</parameter> :</term>
208
<listitem><simpara> x coordinate upper left on screen.
209
</simpara></listitem></varlistentry>
210
<varlistentry><term><parameter>y1</parameter> :</term>
211
<listitem><simpara> y coordinate upper left on screen.
212
</simpara></listitem></varlistentry>
213
<varlistentry><term><parameter>x2</parameter> :</term>
214
<listitem><simpara> x coordinate lower right on screen.
215
</simpara></listitem></varlistentry>
216
<varlistentry><term><parameter>y2</parameter> :</term>
217
<listitem><simpara> y coordinate lower right on screen.
218
</simpara></listitem></varlistentry>
219
<varlistentry><term><parameter>tx1</parameter> :</term>
220
<listitem><simpara> x part of texture coordinate to use for upper left pixel
221
</simpara></listitem></varlistentry>
222
<varlistentry><term><parameter>ty1</parameter> :</term>
223
<listitem><simpara> y part of texture coordinate to use for upper left pixel
224
</simpara></listitem></varlistentry>
225
<varlistentry><term><parameter>tx2</parameter> :</term>
226
<listitem><simpara> x part of texture coordinate to use for lower right pixel
227
</simpara></listitem></varlistentry>
228
<varlistentry><term><parameter>ty2</parameter> :</term>
229
<listitem><simpara> y part of texture coordinate to use for left pixel
230
</simpara></listitem></varlistentry>
231
</variablelist></refsect2>
232
<refsect2 id="cogl-rectangles-with-texture-coords" role="function" condition="since:0.8.6">
233
<title>cogl_rectangles_with_texture_coords ()</title>
234
<indexterm zone="cogl-rectangles-with-texture-coords" role="0.8.6"><primary sortas="rectangles_with_texture_coords">cogl_rectangles_with_texture_coords</primary></indexterm><programlisting><link linkend="void">void</link> cogl_rectangles_with_texture_coords (const <link linkend="float">float</link> *verts,
235
<link linkend="guint">guint</link> n_rects);</programlisting>
237
Draws a series of rectangles in the same way that
238
<link linkend="cogl-rectangle-with-texture-coords"><function>cogl_rectangle_with_texture_coords()</function></link> does. In some situations it can give a
239
significant performance boost to use this function rather than
240
calling <link linkend="cogl-rectangle-with-texture-coords"><function>cogl_rectangle_with_texture_coords()</function></link> separately for each rectangle.
243
<parameter>verts</parameter> should point to an array of <link linkend="float"><type>float</type></link><!-- -->s with
244
<parameter>n_rects</parameter> * 8 elements. Each group of 8 values corresponds to the
245
parameters x1, y1, x2, y2, tx1, ty1, tx2 and ty2 and have the same
246
meaning as in <link linkend="cogl-rectangle-with-texture-coords"><function>cogl_rectangle_with_texture_coords()</function></link>.</para>
248
</para><variablelist role="params">
249
<varlistentry><term><parameter>verts</parameter> :</term>
250
<listitem><simpara> an array of vertices. <acronym>in</acronym>. <acronym>array</acronym>. <acronym>transfer</acronym> none. </simpara></listitem></varlistentry>
251
<varlistentry><term><parameter>n_rects</parameter> :</term>
252
<listitem><simpara> number of rectangles to draw
253
</simpara></listitem></varlistentry>
254
</variablelist><para role="since">Since 0.8.6</para></refsect2>
255
<refsect2 id="cogl-rectangle-with-multitexture-coords" role="function">
256
<title>cogl_rectangle_with_multitexture_coords ()</title>
257
<indexterm zone="cogl-rectangle-with-multitexture-coords"><primary sortas="rectangle_with_multitexture_coords">cogl_rectangle_with_multitexture_coords</primary></indexterm><programlisting><link linkend="void">void</link> cogl_rectangle_with_multitexture_coords
258
(<link linkend="float">float</link> x1,
259
<link linkend="float">float</link> y1,
260
<link linkend="float">float</link> x2,
261
<link linkend="float">float</link> y2,
262
const <link linkend="float">float</link> *tex_coords,
263
<link linkend="gint">gint</link> tex_coords_len);</programlisting>
265
This function draws a rectangle using the current source material to
266
texture or fill with. As a material may contain multiple texture layers
267
this interface lets you supply texture coordinates for each layer of the
271
The first pair of coordinates are for the first layer (with the smallest
272
layer index) and if you supply less texture coordinates than there are
273
layers in the current source material then default texture coordinates
274
(0.0, 0.0, 1.0, 1.0) are generated.
279
</para><variablelist role="params">
280
<varlistentry><term><parameter>x1</parameter> :</term>
281
<listitem><simpara> x coordinate upper left on screen.
282
</simpara></listitem></varlistentry>
283
<varlistentry><term><parameter>y1</parameter> :</term>
284
<listitem><simpara> y coordinate upper left on screen.
285
</simpara></listitem></varlistentry>
286
<varlistentry><term><parameter>x2</parameter> :</term>
287
<listitem><simpara> x coordinate lower right on screen.
288
</simpara></listitem></varlistentry>
289
<varlistentry><term><parameter>y2</parameter> :</term>
290
<listitem><simpara> y coordinate lower right on screen.
291
</simpara></listitem></varlistentry>
292
<varlistentry><term><parameter>tex_coords</parameter> :</term>
293
<listitem><simpara>in) (array) (transfer none. <acronym>in</acronym>. <acronym>array</acronym>. <acronym>transfer</acronym> none. </simpara></listitem></varlistentry>
294
<varlistentry><term><parameter>tex_coords_len</parameter> :</term>
295
<listitem><simpara> The length of the tex_coords array. (e.g. for one layer
296
and one group of texture coordinates, this would be 4)
297
</simpara></listitem></varlistentry>
298
</variablelist></refsect2>
299
<refsect2 id="cogl-polygon" role="function">
300
<title>cogl_polygon ()</title>
301
<indexterm zone="cogl-polygon"><primary sortas="polygon">cogl_polygon</primary></indexterm><programlisting><link linkend="void">void</link> cogl_polygon (<link linkend="CoglTextureVertex">CoglTextureVertex</link> *vertices,
302
<link linkend="guint">guint</link> n_vertices,
303
<link linkend="gboolean">gboolean</link> use_color);</programlisting>
305
Draws a convex polygon using the current source material to fill / texture
306
with according to the texture coordinates passed.
309
If <parameter>use_color</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> then the color will be changed for each vertex using
310
the value specified in the color member of <link linkend="CoglTextureVertex"><type>CoglTextureVertex</type></link>. This can be
311
used for example to make the texture fade out by setting the alpha value of
315
All of the texture coordinates must be in the range [0,1] and repeating the
316
texture is not supported.
319
Because of the way this function is implemented it will currently only work
320
if either the texture is not sliced or the backend is not OpenGL ES and the
321
minifying and magnifying functions are both set to CGL_NEAREST.
326
</para><variablelist role="params">
327
<varlistentry><term><parameter>vertices</parameter> :</term>
328
<listitem><simpara> An array of <link linkend="CoglTextureVertex"><type>CoglTextureVertex</type></link> structs
329
</simpara></listitem></varlistentry>
330
<varlistentry><term><parameter>n_vertices</parameter> :</term>
331
<listitem><simpara> The length of the vertices array
332
</simpara></listitem></varlistentry>
333
<varlistentry><term><parameter>use_color</parameter> :</term>
334
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the color member of <link linkend="CoglTextureVertex"><type>CoglTextureVertex</type></link> should be used
335
</simpara></listitem></varlistentry>
336
</variablelist></refsect2>
337
<refsect2 id="cogl-path-new" role="function" condition="since:1.0">
338
<title>cogl_path_new ()</title>
339
<indexterm zone="cogl-path-new" role="1.0"><primary sortas="path_new">cogl_path_new</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_new (void);</programlisting>
341
Clears the current path and starts a new one.</para>
343
</para><para role="since">Since 1.0</para></refsect2>
344
<refsect2 id="cogl-path-move-to" role="function">
345
<title>cogl_path_move_to ()</title>
346
<indexterm zone="cogl-path-move-to"><primary sortas="path_move_to">cogl_path_move_to</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_move_to (<link linkend="float">float</link> x,
347
<link linkend="float">float</link> y);</programlisting>
349
Moves the pen to the given location. If there is an existing path
350
this will start a new disjoint subpath.</para>
352
</para><variablelist role="params">
353
<varlistentry><term><parameter>x</parameter> :</term>
354
<listitem><simpara> X coordinate of the pen location to move to.
355
</simpara></listitem></varlistentry>
356
<varlistentry><term><parameter>y</parameter> :</term>
357
<listitem><simpara> Y coordinate of the pen location to move to.
358
</simpara></listitem></varlistentry>
359
</variablelist></refsect2>
360
<refsect2 id="cogl-path-close" role="function">
361
<title>cogl_path_close ()</title>
362
<indexterm zone="cogl-path-close"><primary sortas="path_close">cogl_path_close</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_close (void);</programlisting>
364
Closes the path being constructed by adding a straight line segment
365
to it that ends at the first vertex of the path.</para>
368
<refsect2 id="cogl-path-line-to" role="function">
369
<title>cogl_path_line_to ()</title>
370
<indexterm zone="cogl-path-line-to"><primary sortas="path_line_to">cogl_path_line_to</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_line_to (<link linkend="float">float</link> x,
371
<link linkend="float">float</link> y);</programlisting>
373
Adds a straight line segment to the current path that ends at the
374
given coordinates.</para>
376
</para><variablelist role="params">
377
<varlistentry><term><parameter>x</parameter> :</term>
378
<listitem><simpara> X coordinate of the end line vertex
379
</simpara></listitem></varlistentry>
380
<varlistentry><term><parameter>y</parameter> :</term>
381
<listitem><simpara> Y coordinate of the end line vertex
382
</simpara></listitem></varlistentry>
383
</variablelist></refsect2>
384
<refsect2 id="cogl-path-curve-to" role="function">
385
<title>cogl_path_curve_to ()</title>
386
<indexterm zone="cogl-path-curve-to"><primary sortas="path_curve_to">cogl_path_curve_to</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_curve_to (<link linkend="float">float</link> x_1,
387
<link linkend="float">float</link> y_1,
388
<link linkend="float">float</link> x_2,
389
<link linkend="float">float</link> y_2,
390
<link linkend="float">float</link> x_3,
391
<link linkend="float">float</link> y_3);</programlisting>
393
Adds a cubic bezier curve segment to the current path with the given
394
second, third and fourth control points and using current pen location
395
as the first control point.</para>
397
</para><variablelist role="params">
398
<varlistentry><term><parameter>x_1</parameter> :</term>
399
<listitem><simpara> X coordinate of the second bezier control point
400
</simpara></listitem></varlistentry>
401
<varlistentry><term><parameter>y_1</parameter> :</term>
402
<listitem><simpara> Y coordinate of the second bezier control point
403
</simpara></listitem></varlistentry>
404
<varlistentry><term><parameter>x_2</parameter> :</term>
405
<listitem><simpara> X coordinate of the third bezier control point
406
</simpara></listitem></varlistentry>
407
<varlistentry><term><parameter>y_2</parameter> :</term>
408
<listitem><simpara> Y coordinate of the third bezier control point
409
</simpara></listitem></varlistentry>
410
<varlistentry><term><parameter>x_3</parameter> :</term>
411
<listitem><simpara> X coordinate of the fourth bezier control point
412
</simpara></listitem></varlistentry>
413
<varlistentry><term><parameter>y_3</parameter> :</term>
414
<listitem><simpara> Y coordinate of the fourth bezier control point
415
</simpara></listitem></varlistentry>
416
</variablelist></refsect2>
417
<refsect2 id="cogl-path-arc" role="function">
418
<title>cogl_path_arc ()</title>
419
<indexterm zone="cogl-path-arc"><primary sortas="path_arc">cogl_path_arc</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_arc (<link linkend="float">float</link> center_x,
420
<link linkend="float">float</link> center_y,
421
<link linkend="float">float</link> radius_x,
422
<link linkend="float">float</link> radius_y,
423
<link linkend="float">float</link> angle_1,
424
<link linkend="float">float</link> angle_2);</programlisting>
426
Adds an elliptical arc segment to the current path. A straight line
427
segment will link the current pen location with the first vertex
428
of the arc. If you perform a move_to to the arcs start just before
429
drawing it you create a free standing arc.</para>
431
</para><variablelist role="params">
432
<varlistentry><term><parameter>center_x</parameter> :</term>
433
<listitem><simpara> X coordinate of the elliptical arc center
434
</simpara></listitem></varlistentry>
435
<varlistentry><term><parameter>center_y</parameter> :</term>
436
<listitem><simpara> Y coordinate of the elliptical arc center
437
</simpara></listitem></varlistentry>
438
<varlistentry><term><parameter>radius_x</parameter> :</term>
439
<listitem><simpara> X radius of the elliptical arc
440
</simpara></listitem></varlistentry>
441
<varlistentry><term><parameter>radius_y</parameter> :</term>
442
<listitem><simpara> Y radius of the elliptical arc
443
</simpara></listitem></varlistentry>
444
<varlistentry><term><parameter>angle_1</parameter> :</term>
445
<listitem><simpara> Angle in the unit-circle at which the arc begin
446
</simpara></listitem></varlistentry>
447
<varlistentry><term><parameter>angle_2</parameter> :</term>
448
<listitem><simpara> Angle in the unit-circle at which the arc ends
449
</simpara></listitem></varlistentry>
450
</variablelist></refsect2>
451
<refsect2 id="cogl-path-rel-move-to" role="function">
452
<title>cogl_path_rel_move_to ()</title>
453
<indexterm zone="cogl-path-rel-move-to"><primary sortas="path_rel_move_to">cogl_path_rel_move_to</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_rel_move_to (<link linkend="float">float</link> x,
454
<link linkend="float">float</link> y);</programlisting>
456
Moves the pen to the given offset relative to the current pen
457
location. If there is an existing path this will start a new
458
disjoint subpath.</para>
460
</para><variablelist role="params">
461
<varlistentry><term><parameter>x</parameter> :</term>
462
<listitem><simpara> X offset from the current pen location to move the pen to.
463
</simpara></listitem></varlistentry>
464
<varlistentry><term><parameter>y</parameter> :</term>
465
<listitem><simpara> Y offset from the current pen location to move the pen to.
466
</simpara></listitem></varlistentry>
467
</variablelist></refsect2>
468
<refsect2 id="cogl-path-rel-line-to" role="function">
469
<title>cogl_path_rel_line_to ()</title>
470
<indexterm zone="cogl-path-rel-line-to"><primary sortas="path_rel_line_to">cogl_path_rel_line_to</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_rel_line_to (<link linkend="float">float</link> x,
471
<link linkend="float">float</link> y);</programlisting>
473
Adds a straight line segment to the current path that ends at the
474
given coordinates relative to the current pen location.</para>
476
</para><variablelist role="params">
477
<varlistentry><term><parameter>x</parameter> :</term>
478
<listitem><simpara> X offset from the current pen location of the end line vertex
479
</simpara></listitem></varlistentry>
480
<varlistentry><term><parameter>y</parameter> :</term>
481
<listitem><simpara> Y offset from the current pen location of the end line vertex
482
</simpara></listitem></varlistentry>
483
</variablelist></refsect2>
484
<refsect2 id="cogl-path-rel-curve-to" role="function">
485
<title>cogl_path_rel_curve_to ()</title>
486
<indexterm zone="cogl-path-rel-curve-to"><primary sortas="path_rel_curve_to">cogl_path_rel_curve_to</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_rel_curve_to (<link linkend="float">float</link> x_1,
487
<link linkend="float">float</link> y_1,
488
<link linkend="float">float</link> x_2,
489
<link linkend="float">float</link> y_2,
490
<link linkend="float">float</link> x_3,
491
<link linkend="float">float</link> y_3);</programlisting>
493
Adds a cubic bezier curve segment to the current path with the given
494
second, third and fourth control points and using current pen location
495
as the first control point. The given coordinates are relative to the
496
current pen location.</para>
498
</para><variablelist role="params">
499
<varlistentry><term><parameter>x_1</parameter> :</term>
500
<listitem><simpara> X coordinate of the second bezier control point
501
</simpara></listitem></varlistentry>
502
<varlistentry><term><parameter>y_1</parameter> :</term>
503
<listitem><simpara> Y coordinate of the second bezier control point
504
</simpara></listitem></varlistentry>
505
<varlistentry><term><parameter>x_2</parameter> :</term>
506
<listitem><simpara> X coordinate of the third bezier control point
507
</simpara></listitem></varlistentry>
508
<varlistentry><term><parameter>y_2</parameter> :</term>
509
<listitem><simpara> Y coordinate of the third bezier control point
510
</simpara></listitem></varlistentry>
511
<varlistentry><term><parameter>x_3</parameter> :</term>
512
<listitem><simpara> X coordinate of the fourth bezier control point
513
</simpara></listitem></varlistentry>
514
<varlistentry><term><parameter>y_3</parameter> :</term>
515
<listitem><simpara> Y coordinate of the fourth bezier control point
516
</simpara></listitem></varlistentry>
517
</variablelist></refsect2>
518
<refsect2 id="cogl-path-line" role="function">
519
<title>cogl_path_line ()</title>
520
<indexterm zone="cogl-path-line"><primary sortas="path_line">cogl_path_line</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_line (<link linkend="float">float</link> x_1,
521
<link linkend="float">float</link> y_1,
522
<link linkend="float">float</link> x_2,
523
<link linkend="float">float</link> y_2);</programlisting>
525
Constructs a straight line shape starting and ending at the given
526
coordinates. If there is an existing path this will start a new
527
disjoint sub-path.</para>
529
</para><variablelist role="params">
530
<varlistentry><term><parameter>x_1</parameter> :</term>
531
<listitem><simpara> X coordinate of the start line vertex
532
</simpara></listitem></varlistentry>
533
<varlistentry><term><parameter>y_1</parameter> :</term>
534
<listitem><simpara> Y coordinate of the start line vertex
535
</simpara></listitem></varlistentry>
536
<varlistentry><term><parameter>x_2</parameter> :</term>
537
<listitem><simpara> X coordinate of the end line vertex
538
</simpara></listitem></varlistentry>
539
<varlistentry><term><parameter>y_2</parameter> :</term>
540
<listitem><simpara> Y coordinate of the end line vertex
541
</simpara></listitem></varlistentry>
542
</variablelist></refsect2>
543
<refsect2 id="cogl-path-polyline" role="function">
544
<title>cogl_path_polyline ()</title>
545
<indexterm zone="cogl-path-polyline"><primary sortas="path_polyline">cogl_path_polyline</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_polyline (<link linkend="float">float</link> *coords,
546
<link linkend="gint">gint</link> num_points);</programlisting>
548
Constructs a series of straight line segments, starting from the
549
first given vertex coordinate. If there is an existing path this
550
will start a new disjoint sub-path. Each subsequent segment starts
551
where the previous one ended and ends at the next given vertex
555
The coords array must contain 2 * num_points values. The first value
556
represents the X coordinate of the first vertex, the second value
557
represents the Y coordinate of the first vertex, continuing in the same
558
fashion for the rest of the vertices. (num_points - 1) segments will
559
be constructed.</para>
561
</para><variablelist role="params">
562
<varlistentry><term><parameter>coords</parameter> :</term>
563
<listitem><simpara>in) (array) (transfer none. <acronym>in</acronym>. <acronym>array</acronym>. <acronym>transfer</acronym> none. </simpara></listitem></varlistentry>
564
<varlistentry><term><parameter>num_points</parameter> :</term>
565
<listitem><simpara> The total number of vertices.
566
</simpara></listitem></varlistentry>
567
</variablelist></refsect2>
568
<refsect2 id="cogl-path-polygon" role="function">
569
<title>cogl_path_polygon ()</title>
570
<indexterm zone="cogl-path-polygon"><primary sortas="path_polygon">cogl_path_polygon</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_polygon (<link linkend="float">float</link> *coords,
571
<link linkend="gint">gint</link> num_points);</programlisting>
573
Constructs a polygonal shape of the given number of vertices. If
574
there is an existing path this will start a new disjoint sub-path.
577
The coords array must contain 2 * num_points values. The first value
578
represents the X coordinate of the first vertex, the second value
579
represents the Y coordinate of the first vertex, continuing in the same
580
fashion for the rest of the vertices.</para>
582
</para><variablelist role="params">
583
<varlistentry><term><parameter>coords</parameter> :</term>
584
<listitem><simpara>in) (array) (transfer none. <acronym>in</acronym>. <acronym>array</acronym>. <acronym>transfer</acronym> none. </simpara></listitem></varlistentry>
585
<varlistentry><term><parameter>num_points</parameter> :</term>
586
<listitem><simpara> The total number of vertices.
587
</simpara></listitem></varlistentry>
588
</variablelist></refsect2>
589
<refsect2 id="cogl-path-rectangle" role="function">
590
<title>cogl_path_rectangle ()</title>
591
<indexterm zone="cogl-path-rectangle"><primary sortas="path_rectangle">cogl_path_rectangle</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_rectangle (<link linkend="float">float</link> x_1,
592
<link linkend="float">float</link> y_1,
593
<link linkend="float">float</link> x_2,
594
<link linkend="float">float</link> y_2);</programlisting>
596
Constructs a rectangular shape at the given coordinates. If there
597
is an existing path this will start a new disjoint sub-path.</para>
599
</para><variablelist role="params">
600
<varlistentry><term><parameter>x_1</parameter> :</term>
601
<listitem><simpara> X coordinate of the top-left corner.
602
</simpara></listitem></varlistentry>
603
<varlistentry><term><parameter>y_1</parameter> :</term>
604
<listitem><simpara> Y coordinate of the top-left corner.
605
</simpara></listitem></varlistentry>
606
<varlistentry><term><parameter>x_2</parameter> :</term>
607
<listitem><simpara> X coordinate of the bottom-right corner.
608
</simpara></listitem></varlistentry>
609
<varlistentry><term><parameter>y_2</parameter> :</term>
610
<listitem><simpara> Y coordinate of the bottom-right corner.
611
</simpara></listitem></varlistentry>
612
</variablelist></refsect2>
613
<refsect2 id="cogl-path-round-rectangle" role="function">
614
<title>cogl_path_round_rectangle ()</title>
615
<indexterm zone="cogl-path-round-rectangle"><primary sortas="path_round_rectangle">cogl_path_round_rectangle</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_round_rectangle (<link linkend="float">float</link> x_1,
616
<link linkend="float">float</link> y_1,
617
<link linkend="float">float</link> x_2,
618
<link linkend="float">float</link> y_2,
619
<link linkend="float">float</link> radius,
620
<link linkend="float">float</link> arc_step);</programlisting>
622
Constructs a rectangular shape with rounded corners. If there is an
623
existing path this will start a new disjoint sub-path.</para>
625
</para><variablelist role="params">
626
<varlistentry><term><parameter>x_1</parameter> :</term>
627
<listitem><simpara> X coordinate of the top-left corner.
628
</simpara></listitem></varlistentry>
629
<varlistentry><term><parameter>y_1</parameter> :</term>
630
<listitem><simpara> Y coordinate of the top-left corner.
631
</simpara></listitem></varlistentry>
632
<varlistentry><term><parameter>x_2</parameter> :</term>
633
<listitem><simpara> X coordinate of the bottom-right corner.
634
</simpara></listitem></varlistentry>
635
<varlistentry><term><parameter>y_2</parameter> :</term>
636
<listitem><simpara> Y coordinate of the bottom-right corner.
637
</simpara></listitem></varlistentry>
638
<varlistentry><term><parameter>radius</parameter> :</term>
639
<listitem><simpara> Radius of the corner arcs.
640
</simpara></listitem></varlistentry>
641
<varlistentry><term><parameter>arc_step</parameter> :</term>
642
<listitem><simpara> Angle increment resolution for subdivision of
644
</simpara></listitem></varlistentry>
645
</variablelist></refsect2>
646
<refsect2 id="cogl-path-ellipse" role="function">
647
<title>cogl_path_ellipse ()</title>
648
<indexterm zone="cogl-path-ellipse"><primary sortas="path_ellipse">cogl_path_ellipse</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_ellipse (<link linkend="float">float</link> center_x,
649
<link linkend="float">float</link> center_y,
650
<link linkend="float">float</link> radius_x,
651
<link linkend="float">float</link> radius_y);</programlisting>
653
Constructs an ellipse shape. If there is an existing path this will
654
start a new disjoint sub-path.</para>
656
</para><variablelist role="params">
657
<varlistentry><term><parameter>center_x</parameter> :</term>
658
<listitem><simpara> X coordinate of the ellipse center
659
</simpara></listitem></varlistentry>
660
<varlistentry><term><parameter>center_y</parameter> :</term>
661
<listitem><simpara> Y coordinate of the ellipse center
662
</simpara></listitem></varlistentry>
663
<varlistentry><term><parameter>radius_x</parameter> :</term>
664
<listitem><simpara> X radius of the ellipse
665
</simpara></listitem></varlistentry>
666
<varlistentry><term><parameter>radius_y</parameter> :</term>
667
<listitem><simpara> Y radius of the ellipse
668
</simpara></listitem></varlistentry>
669
</variablelist></refsect2>
670
<refsect2 id="cogl-path-fill" role="function">
671
<title>cogl_path_fill ()</title>
672
<indexterm zone="cogl-path-fill"><primary sortas="path_fill">cogl_path_fill</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_fill (void);</programlisting>
674
Fills the constructed shape using the current drawing color. The
675
current path is then cleared. To use the path again, call
676
<link linkend="cogl-path-fill-preserve"><function>cogl_path_fill_preserve()</function></link> instead.</para>
679
<refsect2 id="cogl-path-fill-preserve" role="function" condition="since:1.0">
680
<title>cogl_path_fill_preserve ()</title>
681
<indexterm zone="cogl-path-fill-preserve" role="1.0"><primary sortas="path_fill_preserve">cogl_path_fill_preserve</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_fill_preserve (void);</programlisting>
683
Fills the constructed shape using the current drawing color and
684
preserves the path to be used again.</para>
686
</para><para role="since">Since 1.0</para></refsect2>
687
<refsect2 id="cogl-path-stroke" role="function">
688
<title>cogl_path_stroke ()</title>
689
<indexterm zone="cogl-path-stroke"><primary sortas="path_stroke">cogl_path_stroke</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_stroke (void);</programlisting>
691
Strokes the constructed shape using the current drawing color and a
692
width of 1 pixel (regardless of the current transformation
693
matrix). To current path is then cleared. To use the path again,
694
call <link linkend="cogl-path-stroke-preserve"><function>cogl_path_stroke_preserve()</function></link> instead.</para>
697
<refsect2 id="cogl-path-stroke-preserve" role="function" condition="since:1.0">
698
<title>cogl_path_stroke_preserve ()</title>
699
<indexterm zone="cogl-path-stroke-preserve" role="1.0"><primary sortas="path_stroke_preserve">cogl_path_stroke_preserve</primary></indexterm><programlisting><link linkend="void">void</link> cogl_path_stroke_preserve (void);</programlisting>
701
Strokes the constructed shape using the current drawing color and
702
preserves the path to be used again.</para>
704
</para><para role="since">Since 1.0</para></refsect2>
705
<refsect2 id="cogl-color" role="macro">
706
<title>cogl_color</title>
707
<indexterm zone="cogl-color"><primary sortas="color">cogl_color</primary></indexterm><programlisting>#define cogl_color cogl_color_REPLACED_BY_cogl_set_source_color
added
removed
doc/reference/cogl/xml/cogl-primitives.xml
