The gdk-pixbuf Library
<<< Previous Page | Home | Up | Next Page >>>

# Animations

## Name

Animations -- Animations as multi-frame structures.

## Synopsis

    #include <gdk-pixbuf/gdk-pixbuf.h>

    enum        GdkPixbufFrameAction;
    GdkPixbufAnimation* gdk_pixbuf_animation_new_from_file
                                                (const char *filename);
    GdkPixbufAnimation* gdk_pixbuf_animation_ref
                                                (GdkPixbufAnimation *animation);
    void        gdk_pixbuf_animation_unref      (GdkPixbufAnimation *animation);
    GList*      gdk_pixbuf_animation_get_frames (GdkPixbufAnimation *animation);
    int         gdk_pixbuf_animation_get_width  (GdkPixbufAnimation *animation);
    int         gdk_pixbuf_animation_get_num_frames
                                                (GdkPixbufAnimation *animation);
    int         gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation);
    GdkPixbuf*  gdk_pixbuf_frame_get_pixbuf     (GdkPixbufFrame *frame);
    GdkPixbufFrameAction gdk_pixbuf_frame_get_action
                                                (GdkPixbufFrame *frame);
    int         gdk_pixbuf_frame_get_y_offset   (GdkPixbufFrame *frame);
    int         gdk_pixbuf_frame_get_delay_time (GdkPixbufFrame *frame);
    int         gdk_pixbuf_frame_get_x_offset   (GdkPixbufFrame *frame);

## Description

The gdk-pixbuf library provides a simple mechanism to load and represent animations, primarily animated GIF files. Animations are represented as lists of GdkPixbufFrame structures. Each frame structure contains a GdkPixbuf structure and information about the frame's overlay mode and duration.

## Details

### enum GdkPixbufFrameAction

    typedef enum {
    	GDK_PIXBUF_FRAME_RETAIN,
    	GDK_PIXBUF_FRAME_DISPOSE,
    	GDK_PIXBUF_FRAME_REVERT
    } GdkPixbufFrameAction;

Each animation frame can have several things happen to it when the next frame is displayed. The GdkPixbufFrameAction determines this. These are essentially the overlay modes supported by GIF animations.

`GDK_PIXBUF_FRAME_RETAIN` | The previous image should remain displayed, and will potentially be occluded by the new frame.
`GDK_PIXBUF_FRAME_DISPOSE` | The animation will be reverted to the state before the frame was shown.
`GDK_PIXBUF_FRAME_REVERT` | The animation will be reverted to the first frame.

### gdk_pixbuf_animation_new_from_file ()

    GdkPixbufAnimation* gdk_pixbuf_animation_new_from_file
                                                (const char *filename);

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.

`filename` : | Name of file to load.
Returns : | A newly created animation with a reference count of 1, or `NULL` 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.

### gdk_pixbuf_animation_ref ()

    GdkPixbufAnimation* gdk_pixbuf_animation_ref
                                                (GdkPixbufAnimation *animation);

Adds a reference to an animation. It must be released afterwards using gdk_pixbuf_animation_unref().

`animation` : | An animation.
Returns : | The same as the `animation` argument.

### gdk_pixbuf_animation_unref ()

    void        gdk_pixbuf_animation_unref      (GdkPixbufAnimation *animation);

Removes a reference from an animation. It will be destroyed when the reference count drops to zero. At that point, all the frames in the animation will be freed and their corresponding pixbufs will be unreferenced.

`animation` : | An animation.

### gdk_pixbuf_animation_get_frames ()

    GList*      gdk_pixbuf_animation_get_frames (GdkPixbufAnimation *animation);

Queries the list of frames of an animation.

`animation` : | An animation.
Returns : | List of frames in the animation; this is a GList of GdkPixbufFrame structures.

### gdk_pixbuf_animation_get_width ()

    int         gdk_pixbuf_animation_get_width  (GdkPixbufAnimation *animation);

Queries the width of the bounding box of a pixbuf animation.

`animation` : | An animation.
Returns : | Width of the bounding box of the animation.

### gdk_pixbuf_animation_get_num_frames ()

    int         gdk_pixbuf_animation_get_num_frames
                                                (GdkPixbufAnimation *animation);

Queries the number of frames in a pixbuf animation.

`animation` : | An animation.
Returns : | Number of frames in the animation.

### gdk_pixbuf_animation_get_height ()

    int         gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation);

Queries the height of the bounding box of a pixbuf animation.

`animation` : | An animation.
Returns : | Height of the bounding box of the animation.

### gdk_pixbuf_frame_get_pixbuf ()

    GdkPixbuf*  gdk_pixbuf_frame_get_pixbuf     (GdkPixbufFrame *frame);

Queries the pixbuf of an animation frame.

`frame` : | A pixbuf animation frame.
Returns : | A pixbuf.

### gdk_pixbuf_frame_get_action ()

    GdkPixbufFrameAction gdk_pixbuf_frame_get_action
                                                (GdkPixbufFrame *frame);

Queries the overlay action of an animation frame.

`frame` : | A pixbuf animation frame.
Returns : | Overlay action for this frame.

### gdk_pixbuf_frame_get_y_offset ()

    int         gdk_pixbuf_frame_get_y_offset   (GdkPixbufFrame *frame);

Queries the Y offset of an animation frame.

`frame` : | A pixbuf animation frame.
Returns : | Y offset from the top left corner of the animation.

### gdk_pixbuf_frame_get_delay_time ()

    int         gdk_pixbuf_frame_get_delay_time (GdkPixbufFrame *frame);

Queries the delay time in milliseconds of an animation frame.

`frame` : | A pixbuf animation frame.
Returns : | Delay time in milliseconds.

### gdk_pixbuf_frame_get_x_offset ()

    int         gdk_pixbuf_frame_get_x_offset   (GdkPixbufFrame *frame);

Queries the X offset of an animation frame.

`frame` : | A pixbuf animation frame.
Returns : | X offset from the top left corner of the animation.

## See Also

GdkPixbufLoader

<<< Previous Page | Home | Up | Next Page >>>
Utilities | GdkPixbufLoader