NAME

Prima::Image::Animate - animate gif,webp,png files

DESCRIPTION

The module provides high-level access to GIF, APNG, and WebP animation sequences.

SYNOPSIS

        use Prima qw(Application Image::Animate);
        my $x = Prima::Image::Animate->load($ARGV[0]);
        die $@ unless $x;
        my ( $X, $Y) = ( 0, 100);
        my $want_background = 1; # 0 for eventual transparency
        my $background = $::application-> get_image( $X, $Y, $x-> size);
        $::application-> begin_paint;

        while ( my $info = $x-> next) {
                my $frame = $background-> dup;
                $frame-> begin_paint;
                $x-> draw_background( $frame, 0, 0) if $want_background;
                $x-> draw( $frame, 0, 0);
                $::application-> put_image( $X, $Y, $frame);

                $::application-> sync;
                select(undef, undef, undef, $info-> {delay});
        }

        $::application-> put_image( $X, $Y, $g);

new $CLASS, %OPTIONS

Creates an empty animation container. If $OPTIONS{images} is given, it is expected to be an array of images, best if loaded from files with the loadExtras and iconUnmask parameters set ( see Prima::image-load for details).

detect_animation $HASH

Checks the {extras} hash obtained from an image loaded with the loadExtras flag set to detect whether the image is an animation or not, and if loading of all of its frame is supported by the module. Returns the file format name on success, undef otherwise.

load $SOURCE, %OPTIONS

Loads a GIF, APNG, or WebP animation sequence from $SOURCE which is either a file or a stream. Options are the same as used by the Prima::Image::load method.

Depending on the loadAll option, either loads all frames at once (1), or uses Prima::Image::Loader to load only a single frame at a time (0, default). Depending on the loading mode, some properties may not be available.

add $IMAGE

Appends an image frame to the container.

Only available if the loadAll option is on.

bgColor

Returns the background color specified by the sequence as the preferred color to use when there is no specific background to superimpose the animation on.

current

Returns the index of the current frame

draw $CANVAS, $X, $Y

Draws the current composite frame on $CANVAS at the given coordinates

draw_background $CANVAS, $X, $Y

Fills the background on $CANVAS at the given coordinates if the file provides the color to fill. Returns a boolean value whether the canvas was drawn on or not.

height

Returns the height of the composite frame

icon

Returns a new icon object created from the current composite frame

image

Returns a new image object created from the current composite frame The transparent pixels on the image are replaced with the preferred background color

is_stopped

Returns true if the animation sequence was stopped, false otherwise. If the sequence was stopped, the only way to restart it is to call reset.

length

Returns the total animation length (without repeats) in seconds.

loopCount [ INTEGER ]

Sets and returns the number of loops left, undef for indefinite.

next

Advances one animation frame. The step triggers changes to the internally kept buffer image that creates the effect of transparency if needed. The method returns a hash, where the following fields are initialized:

left, bottom, right, top

Coordinates of the changed area since the last frame was updated

delay

Time in seconds how long the frame is expected to be displayed

reset

Resets the animation sequence. This call is necessary either when the image sequence was altered, or when the sequence display restart is needed.

size

Returns the width and height of the composite frame

total

Return the number of frames

warning

If an error occured during frame loading, it will be stored in the warning property. The animation will stop at the last successfully loaded frame

Only available if the loadAll option is off.

width

Returns the width of the composite frame

SEE ALSO

Prima::image-load, Prima::Image::Loader.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.