← Back to branch summary

~ubuntu-branches/ubuntu/precise/gdk-pixbuf/precise-proposed

« back to all changes in this revision

Viewing changes to doc/sgml/animation.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-07-23 11:26:25 UTC
  • mto: (4.1.1 sid) (33.1.2 sid) (1.2.2 experimental)
  • mto: This revision was merged to the branch mainline in revision 5.
  • Revision ID: james.westby@ubuntu.com-20100723112625-1ybus2sr4hyhmlku
Tags: upstream-2.21.6
Import upstream version 2.21.6

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/sgml/animation.sgml
1
 
<refentry id="gdk-pixbuf-animation">
2
 
<refmeta>
3
 
<refentrytitle>Animations</refentrytitle>
4
 
<manvolnum>3</manvolnum>
5
 
<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
6
 
</refmeta>
7
 
 
8
 
<refnamediv>
9
 
<refname>Animations</refname><refpurpose>Animations as multi-frame structures.</refpurpose>
10
 
</refnamediv>
11
 
 
12
 
<refsynopsisdiv><title>Synopsis</title>
13
 
<synopsis>
14
 
 
15
 
#include &lt;gdk-pixbuf/gdk-pixbuf.h&gt;
16
 
 
17
 
 
18
 
enum        <link linkend="GdkPixbufFrameAction">GdkPixbufFrameAction</link>;
19
 
<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>* <link linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file</link>
20
 
                                            (const char *filename);
21
 
<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>* <link linkend="gdk-pixbuf-animation-ref">gdk_pixbuf_animation_ref</link>
22
 
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
23
 
void        <link linkend="gdk-pixbuf-animation-unref">gdk_pixbuf_animation_unref</link>      (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
24
 
<link linkend="GList">GList</link>*      <link linkend="gdk-pixbuf-animation-get-frames">gdk_pixbuf_animation_get_frames</link> (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
25
 
int         <link linkend="gdk-pixbuf-animation-get-width">gdk_pixbuf_animation_get_width</link>  (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
26
 
int         <link linkend="gdk-pixbuf-animation-get-num-frames">gdk_pixbuf_animation_get_num_frames</link>
27
 
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
28
 
int         <link linkend="gdk-pixbuf-animation-get-height">gdk_pixbuf_animation_get_height</link> (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
29
 
<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-frame-get-pixbuf">gdk_pixbuf_frame_get_pixbuf</link>     (<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> *frame);
30
 
<link linkend="GdkPixbufFrameAction">GdkPixbufFrameAction</link> <link linkend="gdk-pixbuf-frame-get-action">gdk_pixbuf_frame_get_action</link>
31
 
                                            (<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> *frame);
32
 
int         <link linkend="gdk-pixbuf-frame-get-y-offset">gdk_pixbuf_frame_get_y_offset</link>   (<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> *frame);
33
 
int         <link linkend="gdk-pixbuf-frame-get-delay-time">gdk_pixbuf_frame_get_delay_time</link> (<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> *frame);
34
 
int         <link linkend="gdk-pixbuf-frame-get-x-offset">gdk_pixbuf_frame_get_x_offset</link>   (<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> *frame);
35
 
 
36
 
</synopsis>
37
 
</refsynopsisdiv>
38
 
 
39
 
 
40
 
 
41
 
 
42
 
 
43
 
<refsect1>
44
 
<title>Description</title>
45
 
  <para>
46
 
    The &gdk-pixbuf; library provides a simple mechanism to load and
47
 
    represent animations, primarily animated GIF files.  Animations
48
 
    are represented as lists of <link linkend="GdkPixbufFrame">GdkPixbufFrame</link> structures.  Each
49
 
    frame structure contains a <link linkend="GdkPixbuf">GdkPixbuf</link> structure and information
50
 
    about the frame's overlay mode and duration.
51
 
  </para>
52
 
</refsect1>
53
 
 
54
 
<refsect1>
55
 
<title>Details</title>
56
 
<refsect2>
57
 
<title><anchor id="GdkPixbufFrameAction">enum GdkPixbufFrameAction</title>
58
 
<programlisting>typedef enum {
59
 
        GDK_PIXBUF_FRAME_RETAIN,
60
 
        GDK_PIXBUF_FRAME_DISPOSE,
61
 
        GDK_PIXBUF_FRAME_REVERT
62
 
} GdkPixbufFrameAction;
63
 
</programlisting>
64
 
  <para>
65
 
    Each animation frame can have several things happen to it when the
66
 
    next frame is displayed.  The <link linkend="GdkPixbufFrameAction">GdkPixbufFrameAction</link> determines
67
 
    this.  These are essentially the overlay modes supported by GIF
68
 
    animations.
69
 
  </para><informaltable pgwide=1 frame="none" role="enum">
70
 
<tgroup cols="2">
71
 
<colspec colwidth="2*">
72
 
<colspec colwidth="8*">
73
 
<tbody>
74
 
<row>
75
 
<entry><literal>GDK_PIXBUF_FRAME_RETAIN</literal></entry>
76
 
<entry>The previous image should remain displayed,
77
 
and will potentially be occluded by the new frame.
78
 
</entry>
79
 
</row>
80
 
<row>
81
 
<entry><literal>GDK_PIXBUF_FRAME_DISPOSE</literal></entry>
82
 
<entry>The animation will be reverted to the state
83
 
before the frame was shown.
84
 
</entry>
85
 
</row>
86
 
<row>
87
 
<entry><literal>GDK_PIXBUF_FRAME_REVERT</literal></entry>
88
 
<entry>The animation will be reverted to the first
89
 
frame.
90
 
 
91
 
</entry>
92
 
</row>
93
 
</tbody></tgroup></informaltable></refsect2>
94
 
<refsect2>
95
 
<title><anchor id="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file ()</title>
96
 
<programlisting><link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>* gdk_pixbuf_animation_new_from_file
97
 
                                            (const char *filename);</programlisting>
98
 
<para>
99
 
Creates a new animation by loading it from a file.  The file format is
100
 
detected automatically.  If the file's format does not support multi-frame
101
 
images, then an animation with a single frame will be created.</para>
102
 
<para>
103
 
 
104
 
</para><informaltable pgwide=1 frame="none" role="params">
105
 
<tgroup cols="2">
106
 
<colspec colwidth="2*">
107
 
<colspec colwidth="8*">
108
 
<tbody>
109
 
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
110
 
<entry> Name of file to load.
111
 
</entry></row>
112
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A newly created animation with a reference count of 1, or <literal>NULL</literal>
113
 
if any of several error conditions ocurred:  the file could not be opened,
114
 
there was no loader for the file's format, there was not enough memory to
115
 
allocate the image buffer, or the image file contained invalid data.
116
 
</entry></row>
117
 
</tbody></tgroup></informaltable></refsect2>
118
 
<refsect2>
119
 
<title><anchor id="gdk-pixbuf-animation-ref">gdk_pixbuf_animation_ref ()</title>
120
 
<programlisting><link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>* gdk_pixbuf_animation_ref
121
 
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
122
 
<para>
123
 
Adds a reference to an animation.  It must be released afterwards using
124
 
<link linkend="gdk-pixbuf-animation-unref">gdk_pixbuf_animation_unref</link>().</para>
125
 
<para>
126
 
 
127
 
</para><informaltable pgwide=1 frame="none" role="params">
128
 
<tgroup cols="2">
129
 
<colspec colwidth="2*">
130
 
<colspec colwidth="8*">
131
 
<tbody>
132
 
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
133
 
<entry> An animation.
134
 
</entry></row>
135
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The same as the <parameter>animation</parameter> argument.
136
 
</entry></row>
137
 
</tbody></tgroup></informaltable></refsect2>
138
 
<refsect2>
139
 
<title><anchor id="gdk-pixbuf-animation-unref">gdk_pixbuf_animation_unref ()</title>
140
 
<programlisting>void        gdk_pixbuf_animation_unref      (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
141
 
<para>
142
 
Removes a reference from an animation.  It will be destroyed when the
143
 
reference count drops to zero.  At that point, all the frames in the
144
 
animation will be freed and their corresponding pixbufs will be unreferenced.</para>
145
 
<para>
146
 
 
147
 
</para><informaltable pgwide=1 frame="none" role="params">
148
 
<tgroup cols="2">
149
 
<colspec colwidth="2*">
150
 
<colspec colwidth="8*">
151
 
<tbody>
152
 
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
153
 
<entry> An animation.
154
 
</entry></row>
155
 
</tbody></tgroup></informaltable></refsect2>
156
 
<refsect2>
157
 
<title><anchor id="gdk-pixbuf-animation-get-frames">gdk_pixbuf_animation_get_frames ()</title>
158
 
<programlisting><link linkend="GList">GList</link>*      gdk_pixbuf_animation_get_frames (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
159
 
<para>
160
 
Queries the list of frames of an animation.</para>
161
 
<para>
162
 
 
163
 
</para><informaltable pgwide=1 frame="none" role="params">
164
 
<tgroup cols="2">
165
 
<colspec colwidth="2*">
166
 
<colspec colwidth="8*">
167
 
<tbody>
168
 
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
169
 
<entry> An animation.
170
 
</entry></row>
171
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> List of frames in the animation; this is a <link linkend="GList">GList</link> of
172
 
<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> structures.
173
 
</entry></row>
174
 
</tbody></tgroup></informaltable></refsect2>
175
 
<refsect2>
176
 
<title><anchor id="gdk-pixbuf-animation-get-width">gdk_pixbuf_animation_get_width ()</title>
177
 
<programlisting>int         gdk_pixbuf_animation_get_width  (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
178
 
<para>
179
 
Queries the width of the bounding box of a pixbuf animation.</para>
180
 
<para>
181
 
 
182
 
</para><informaltable pgwide=1 frame="none" role="params">
183
 
<tgroup cols="2">
184
 
<colspec colwidth="2*">
185
 
<colspec colwidth="8*">
186
 
<tbody>
187
 
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
188
 
<entry> An animation.
189
 
</entry></row>
190
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Width of the bounding box of the animation.
191
 
</entry></row>
192
 
</tbody></tgroup></informaltable></refsect2>
193
 
<refsect2>
194
 
<title><anchor id="gdk-pixbuf-animation-get-num-frames">gdk_pixbuf_animation_get_num_frames ()</title>
195
 
<programlisting>int         gdk_pixbuf_animation_get_num_frames
196
 
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
197
 
<para>
198
 
Queries the number of frames in a pixbuf animation.</para>
199
 
<para>
200
 
 
201
 
</para><informaltable pgwide=1 frame="none" role="params">
202
 
<tgroup cols="2">
203
 
<colspec colwidth="2*">
204
 
<colspec colwidth="8*">
205
 
<tbody>
206
 
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
207
 
<entry> An animation.
208
 
</entry></row>
209
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Number of frames in the animation.
210
 
</entry></row>
211
 
</tbody></tgroup></informaltable></refsect2>
212
 
<refsect2>
213
 
<title><anchor id="gdk-pixbuf-animation-get-height">gdk_pixbuf_animation_get_height ()</title>
214
 
<programlisting>int         gdk_pixbuf_animation_get_height (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
215
 
<para>
216
 
Queries the height of the bounding box of a pixbuf animation.</para>
217
 
<para>
218
 
 
219
 
</para><informaltable pgwide=1 frame="none" role="params">
220
 
<tgroup cols="2">
221
 
<colspec colwidth="2*">
222
 
<colspec colwidth="8*">
223
 
<tbody>
224
 
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
225
 
<entry> An animation.
226
 
</entry></row>
227
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Height of the bounding box of the animation.
228
 
</entry></row>
229
 
</tbody></tgroup></informaltable></refsect2>
230
 
<refsect2>
231
 
<title><anchor id="gdk-pixbuf-frame-get-pixbuf">gdk_pixbuf_frame_get_pixbuf ()</title>
232
 
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_frame_get_pixbuf     (<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> *frame);</programlisting>
233
 
<para>
234
 
Queries the pixbuf of an animation frame.</para>
235
 
<para>
236
 
 
237
 
</para><informaltable pgwide=1 frame="none" role="params">
238
 
<tgroup cols="2">
239
 
<colspec colwidth="2*">
240
 
<colspec colwidth="8*">
241
 
<tbody>
242
 
<row><entry align="right"><parameter>frame</parameter>&nbsp;:</entry>
243
 
<entry> A pixbuf animation frame.
244
 
</entry></row>
245
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A pixbuf.
246
 
</entry></row>
247
 
</tbody></tgroup></informaltable></refsect2>
248
 
<refsect2>
249
 
<title><anchor id="gdk-pixbuf-frame-get-action">gdk_pixbuf_frame_get_action ()</title>
250
 
<programlisting><link linkend="GdkPixbufFrameAction">GdkPixbufFrameAction</link> gdk_pixbuf_frame_get_action
251
 
                                            (<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> *frame);</programlisting>
252
 
<para>
253
 
Queries the overlay action of an animation frame.</para>
254
 
<para>
255
 
 
256
 
</para><informaltable pgwide=1 frame="none" role="params">
257
 
<tgroup cols="2">
258
 
<colspec colwidth="2*">
259
 
<colspec colwidth="8*">
260
 
<tbody>
261
 
<row><entry align="right"><parameter>frame</parameter>&nbsp;:</entry>
262
 
<entry> A pixbuf animation frame.
263
 
</entry></row>
264
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Overlay action for this frame.
265
 
</entry></row>
266
 
</tbody></tgroup></informaltable></refsect2>
267
 
<refsect2>
268
 
<title><anchor id="gdk-pixbuf-frame-get-y-offset">gdk_pixbuf_frame_get_y_offset ()</title>
269
 
<programlisting>int         gdk_pixbuf_frame_get_y_offset   (<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> *frame);</programlisting>
270
 
<para>
271
 
Queries the Y offset of an animation frame.</para>
272
 
<para>
273
 
 
274
 
</para><informaltable pgwide=1 frame="none" role="params">
275
 
<tgroup cols="2">
276
 
<colspec colwidth="2*">
277
 
<colspec colwidth="8*">
278
 
<tbody>
279
 
<row><entry align="right"><parameter>frame</parameter>&nbsp;:</entry>
280
 
<entry> A pixbuf animation frame.
281
 
</entry></row>
282
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Y offset from the top left corner of the animation.
283
 
</entry></row>
284
 
</tbody></tgroup></informaltable></refsect2>
285
 
<refsect2>
286
 
<title><anchor id="gdk-pixbuf-frame-get-delay-time">gdk_pixbuf_frame_get_delay_time ()</title>
287
 
<programlisting>int         gdk_pixbuf_frame_get_delay_time (<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> *frame);</programlisting>
288
 
<para>
289
 
Queries the delay time in milliseconds of an animation frame.</para>
290
 
<para>
291
 
 
292
 
</para><informaltable pgwide=1 frame="none" role="params">
293
 
<tgroup cols="2">
294
 
<colspec colwidth="2*">
295
 
<colspec colwidth="8*">
296
 
<tbody>
297
 
<row><entry align="right"><parameter>frame</parameter>&nbsp;:</entry>
298
 
<entry> A pixbuf animation frame.
299
 
</entry></row>
300
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Delay time in milliseconds.
301
 
</entry></row>
302
 
</tbody></tgroup></informaltable></refsect2>
303
 
<refsect2>
304
 
<title><anchor id="gdk-pixbuf-frame-get-x-offset">gdk_pixbuf_frame_get_x_offset ()</title>
305
 
<programlisting>int         gdk_pixbuf_frame_get_x_offset   (<link linkend="GdkPixbufFrame">GdkPixbufFrame</link> *frame);</programlisting>
306
 
<para>
307
 
Queries the X offset of an animation frame.</para>
308
 
<para>
309
 
 
310
 
</para><informaltable pgwide=1 frame="none" role="params">
311
 
<tgroup cols="2">
312
 
<colspec colwidth="2*">
313
 
<colspec colwidth="8*">
314
 
<tbody>
315
 
<row><entry align="right"><parameter>frame</parameter>&nbsp;:</entry>
316
 
<entry> A pixbuf animation frame.
317
 
</entry></row>
318
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> X offset from the top left corner of the animation.
319
 
</entry></row>
320
 
</tbody></tgroup></informaltable></refsect2>
321
 
 
322
 
</refsect1>
323
 
 
324
 
 
325
 
 
326
 
<refsect1>
327
 
<title>See Also</title>
328
 
  <para>
329
 
    <link linkend="GdkPixbufLoader">GdkPixbufLoader</link>
330
 
  </para>
331
 
</refsect1>
332
 
 
333
 
</refentry>