<refentry id="gdk-pixbuf-animation">
<refmeta>
<refentrytitle>Animations</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Animations</refname><refpurpose>Animated images.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gdk-pixbuf/gdk-pixbuf.h&gt;


struct      <link linkend="GdkPixbufFrame">GdkPixbufFrame</link>;
struct      <link linkend="GdkPixbufAnimation-struct">GdkPixbufAnimation</link>;
struct      <link linkend="GdkPixbufAnimationIter-struct">GdkPixbufAnimationIter</link>;
<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>* <link linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file</link>
                                            (const char *filename,
                                             <link linkend="GError">GError</link> **error);
<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>* <link linkend="gdk-pixbuf-animation-ref">gdk_pixbuf_animation_ref</link>
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
void        <link linkend="gdk-pixbuf-animation-unref">gdk_pixbuf_animation_unref</link>      (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
int         <link linkend="gdk-pixbuf-animation-get-width">gdk_pixbuf_animation_get_width</link>  (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
int         <link linkend="gdk-pixbuf-animation-get-height">gdk_pixbuf_animation_get_height</link> (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
<link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link>* <link linkend="gdk-pixbuf-animation-get-iter">gdk_pixbuf_animation_get_iter</link>
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation,
                                             const <link linkend="GTimeVal">GTimeVal</link> *start_time);
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-pixbuf-animation-is-static-image">gdk_pixbuf_animation_is_static_image</link>
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-animation-get-static-image">gdk_pixbuf_animation_get_static_image</link>
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-pixbuf-animation-iter-advance">gdk_pixbuf_animation_iter_advance</link>
                                            (<link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link> *iter,
                                             const <link linkend="GTimeVal">GTimeVal</link> *current_time);
int         <link linkend="gdk-pixbuf-animation-iter-get-delay-time">gdk_pixbuf_animation_iter_get_delay_time</link>
                                            (<link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link> *iter);
<link linkend="gboolean">gboolean</link>    <link linkend="gdk-pixbuf-animation-iter-on-currently-loading-frame">gdk_pixbuf_animation_iter_on_currently_loading_frame</link>
                                            (<link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link> *iter);
<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-animation-iter-get-pixbuf">gdk_pixbuf_animation_iter_get_pixbuf</link>
                                            (<link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link> *iter);


</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
  <para><anchor id="GdkPixbufAnimation">
    The &gdk-pixbuf; library provides a simple mechanism to load and represent
    animations. An animation is conceptually a series of frames to be displayed
    over time. Each frame is the same size. The animation may not be represented
    as a series of frames internally; for example, it may be stored as a 
    sprite and instructions for moving the sprite around a background. To display 
    an animation you don't need to understand its representation, however; you just
    ask &gdk-pixbuf; what should be displayed at a given point in time. 
  </para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GdkPixbufFrame">struct GdkPixbufFrame</title>
<programlisting>struct GdkPixbufFrame;</programlisting>
<para>
 This object describes an individual frame of an animation.
</para></refsect2>
<refsect2>
<title><anchor id="GdkPixbufAnimation-struct">struct GdkPixbufAnimation</title>
<programlisting>struct GdkPixbufAnimation;</programlisting>
  <para>
    This object describes an animation.
  </para></refsect2>
<refsect2>
<title><anchor id="GdkPixbufAnimationIter-struct">struct GdkPixbufAnimationIter</title>
<programlisting>struct GdkPixbufAnimationIter;</programlisting>
<para>
A <link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link> provides the necessary functionality to
display an animation. See <link linkend="gdk-pixbuf-animation-get-iter">gdk_pixbuf_animation_get_iter</link>().
</para></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file ()</title>
<programlisting><link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>* gdk_pixbuf_animation_new_from_file
                                            (const char *filename,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Creates a new animation by loading it from a file.  The file format is
detected automatically.  If the file's format does not support multi-frame
images, then an animation with a single frame will be created. Possible errors
are in the <link linkend="GDK-PIXBUF-ERROR-CAPS">GDK_PIXBUF_ERROR</link> and <link linkend="G-FILE-ERROR-CAPS">G_FILE_ERROR</link> domains.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> Name of file to load.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> return location for error
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A newly-created animation with a reference count of 1, or <literal>NULL</literal>
if any of several error conditions ocurred:  the file could not be opened,
there was no loader for the file's format, there was not enough memory to
allocate the image buffer, or the image file contained invalid data.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-ref">gdk_pixbuf_animation_ref ()</title>
<programlisting><link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>* gdk_pixbuf_animation_ref
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
<warning>
<para>
<literal>gdk_pixbuf_animation_ref</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Adds a reference to an animation. Deprecated; use
<link linkend="g-object-ref">g_object_ref</link>(). The reference must be released afterwards using
<link linkend="g-object-unref">g_object_unref</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
<entry> An animation.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The same as the <parameter>animation</parameter> argument.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-unref">gdk_pixbuf_animation_unref ()</title>
<programlisting>void        gdk_pixbuf_animation_unref      (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
<warning>
<para>
<literal>gdk_pixbuf_animation_unref</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
Removes a reference from an animation. Deprecated; use <link linkend="g-object-unref">g_object_unref</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
<entry> An animation.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-get-width">gdk_pixbuf_animation_get_width ()</title>
<programlisting>int         gdk_pixbuf_animation_get_width  (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
<para>
Queries the width of the bounding box of a pixbuf animation.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
<entry> An animation.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Width of the bounding box of the animation.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-get-height">gdk_pixbuf_animation_get_height ()</title>
<programlisting>int         gdk_pixbuf_animation_get_height (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
<para>
Queries the height of the bounding box of a pixbuf animation.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
<entry> An animation.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Height of the bounding box of the animation.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-get-iter">gdk_pixbuf_animation_get_iter ()</title>
<programlisting><link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link>* gdk_pixbuf_animation_get_iter
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation,
                                             const <link linkend="GTimeVal">GTimeVal</link> *start_time);</programlisting>
<para>
Get an iterator for displaying an animation. The iterator provides
the frames that should be displayed at a given time.
It should be freed after use with <link linkend="g-object-unref">g_object_unref</link>().
</para>
<para>
<parameter>start_time</parameter> would normally come from <link linkend="g-get-current-time">g_get_current_time</link>(), and
marks the beginning of animation playback. After creating an
iterator, you should immediately display the pixbuf returned by
<link linkend="gdk-pixbuf-animation-iter-get-pixbuf">gdk_pixbuf_animation_iter_get_pixbuf</link>(). Then, you should install a
timeout (with <link linkend="g-timeout-add">g_timeout_add</link>()) or by some other mechanism ensure
that you'll update the image after
<link linkend="gdk-pixbuf-animation-iter-get-delay-time">gdk_pixbuf_animation_iter_get_delay_time</link>() milliseconds. Each time
the image is updated, you should reinstall the timeout with the new,
possibly-changed delay time.
</para>
<para>
As a shortcut, if <parameter>start_time</parameter> is <literal>NULL</literal>, the result of
<link linkend="g-get-current-time">g_get_current_time</link>() will be used automatically.
</para>
<para>
To update the image (i.e. possibly change the result of
<link linkend="gdk-pixbuf-animation-iter-get-pixbuf">gdk_pixbuf_animation_iter_get_pixbuf</link>() to a new frame of the animation),
call <link linkend="gdk-pixbuf-animation-iter-advance">gdk_pixbuf_animation_iter_advance</link>().
</para>
<para>
If you're using <link linkend="GdkPixbufLoader">GdkPixbufLoader</link>, in addition to updating the image
after the delay time, you should also update it whenever you
receive the area_updated signal and
<link linkend="gdk-pixbuf-animation-iter-on-currently-loading-frame">gdk_pixbuf_animation_iter_on_currently_loading_frame</link>() returns
<literal>TRUE</literal>. In this case, the frame currently being fed into the loader
has received new data, so needs to be refreshed. The delay time for
a frame may also be modified after an area_updated signal, for
example if the delay time for a frame is encoded in the data after
the frame itself. So your timeout should be reinstalled after any
area_updated signal.
</para>
<para>
A delay time of -1 is possible, indicating "infinite."</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>
</entry></row>
<row><entry align="right"><parameter>start_time</parameter>&nbsp;:</entry>
<entry> time when the animation starts playing
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> an iterator to move over the animation
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-is-static-image">gdk_pixbuf_animation_is_static_image ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_pixbuf_animation_is_static_image
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
<para>
If you load a file with <link linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file</link>() and it turns
out to be a plain, unanimated image, then this function will return
<literal>TRUE</literal>. Use <link linkend="gdk-pixbuf-animation-get-static-image">gdk_pixbuf_animation_get_static_image</link>() to retrieve
the image.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the "animation" was really just an image
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-get-static-image">gdk_pixbuf_animation_get_static_image ()</title>
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_animation_get_static_image
                                            (<link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link> *animation);</programlisting>
<para>
If an animation is really just a plain image (has only one frame),
this function returns that image. If the animation is an animation,
this function returns a reasonable thing to display as a static
unanimated image, which might be the first frame, or something more
sophisticated. If an animation hasn't loaded any frames yet, this
function will return <literal>NULL</literal>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>animation</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixbufAnimation">GdkPixbufAnimation</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> unanimated image representing the animation
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-iter-advance">gdk_pixbuf_animation_iter_advance ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_pixbuf_animation_iter_advance
                                            (<link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link> *iter,
                                             const <link linkend="GTimeVal">GTimeVal</link> *current_time);</programlisting>
<para>
Possibly advances an animation to a new frame. Chooses the frame based
on the start time passed to <link linkend="gdk-pixbuf-animation-get-iter">gdk_pixbuf_animation_get_iter</link>().
</para>
<para>
<parameter>current_time</parameter> would normally come from <link linkend="g-get-current-time">g_get_current_time</link>(), and
must be greater than or equal to the time passed to
<link linkend="gdk-pixbuf-animation-get-iter">gdk_pixbuf_animation_get_iter</link>(), and must increase or remain
unchanged each time <link linkend="gdk-pixbuf-animation-iter-get-pixbuf">gdk_pixbuf_animation_iter_get_pixbuf</link>() is
called. That is, you can't go backward in time; animations only
play forward.
</para>
<para>
As a shortcut, pass <literal>NULL</literal> for the current time and <link linkend="g-get-current-time">g_get_current_time</link>()
will be invoked on your behalf. So you only need to explicitly pass
<parameter>current_time</parameter> if you're doing something odd like playing the animation
at double speed.
</para>
<para>
If this function returns <literal>FALSE</literal>, there's no need to update the animation
display, assuming the display had been rendered prior to advancing;
if <literal>TRUE</literal>, you need to call <link linkend="gdk-animation-iter-get-pixbuf">gdk_animation_iter_get_pixbuf</link>() and update the
display with the new pixbuf.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link>
</entry></row>
<row><entry align="right"><parameter>current_time</parameter>&nbsp;:</entry>
<entry> current time
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the image may need updating

</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-iter-get-delay-time">gdk_pixbuf_animation_iter_get_delay_time ()</title>
<programlisting>int         gdk_pixbuf_animation_iter_get_delay_time
                                            (<link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link> *iter);</programlisting>
<para>
Gets the number of milliseconds the current pixbuf should be displayed,
or -1 if the current pixbuf should be displayed forever. <link linkend="g-timeout-add">g_timeout_add</link>()
conveniently takes a timeout in milliseconds, so you can use a timeout
to schedule the next update.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> an animation iterator
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> delay time in milliseconds (thousandths of a second)
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-iter-on-currently-loading-frame">gdk_pixbuf_animation_iter_on_currently_loading_frame ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    gdk_pixbuf_animation_iter_on_currently_loading_frame
                                            (<link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link> *iter);</programlisting>
<para>
Used to determine how to respond to the area_updated signal on
<link linkend="GdkPixbufLoader">GdkPixbufLoader</link> when loading an animation. area_updated is emitted
for an area of the frame currently streaming in to the loader. So if
you're on the currently loading frame, you need to redraw the screen for
the updated area.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the frame we're on is partially loaded, or the last frame
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-animation-iter-get-pixbuf">gdk_pixbuf_animation_iter_get_pixbuf ()</title>
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_animation_iter_get_pixbuf
                                            (<link linkend="GdkPixbufAnimationIter">GdkPixbufAnimationIter</link> *iter);</programlisting>
<para>
Gets the current pixbuf which should be displayed; the pixbuf will
be the same size as the animation itself
(<link linkend="gdk-pixbuf-animation-get-width">gdk_pixbuf_animation_get_width</link>(),
<link linkend="gdk-pixbuf-animation-get-height">gdk_pixbuf_animation_get_height</link>()). This pixbuf should be displayed
for <link linkend="gdk-pixbuf-animation-get-delay-time">gdk_pixbuf_animation_get_delay_time</link>() milliseconds.  The caller
of this function does not own a reference to the returned pixbuf;
the returned pixbuf will become invalid when the iterator advances
to the next frame, which may happen anytime you call
<link linkend="gdk-pixbuf-animation-iter-advance">gdk_pixbuf_animation_iter_advance</link>(). Copy the pixbuf to keep it
(don't just add a reference), as it may get recycled as you advance
the iterator.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>iter</parameter>&nbsp;:</entry>
<entry> an animation iterator
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the pixbuf to be displayed
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
  <para>
    <link linkend="GdkPixbufLoader">GdkPixbufLoader</link>
  </para>
</refsect1>

</refentry>
