NAME

Prima::image-load - Using image subsystem

DESCRIPTION

Details on image subsystem - image loading, saving, and codec managements

Loading

Simple loading

Simplest case, loading a single image would look like:

my $x = Prima::Image-> load( 'filename.duf');
die "$@" unless $x;

Image functions can work being either invoked from package, or from existing Prima::Image object, in latter case the caller object itself is changing. The code above could be also written as

my $x = Prima::Image-> create;
die "$@" unless $x-> load( 'filename.duf');

In both cases $x contains image data upon success. Error is returned into $@ variable ( see perldoc perlvar for more info).

Loading from stream

Prima::Image can also load image by reading from a stream:

	open FILE, 'a.jpeg' or die "Cannot open:$!";
	binmode FILE;
	my $x = Prima::Image-> load( \*FILE);
        die "$@" unless $x;

Multiframe loading

Multiframe load call can be also issued in two ways:

my @x = Prima::Image-> load( 'filename.duf', loadAll => 1);
die "$@" unless $x[-1];

my $x = Prima::Image-> create;
my @x = $x-> load( 'filename.duf', loadAll => 1);
die "$@" unless $x[-1];

In second case, the content of the first frame comes to $x and $x[0]. Sufficient check for error is whether last item of a returned array is defined. This check works also if an empty array is returned. Only this last item can be an undefined value, others are guaranteed to be valid objects.

Multiframe syntax is expressed in a set of extra hash keys. These keys are:

loadAll

Request for loading all frames that can be read from a file. Example:

loadAll => 1

index

If present, returns a single frame with index given. Example:

index => 8

map

Contains an anonymous array of frame indices to load. Valid indices are above zero, negative ones can't be counted in a way perl array indices are. Example:

map => [0, 10, 15..20]

Querying extra information

By default Prima loads image data and palette only. For any other information that can be loaded, anonymous hash 'extras' can be defined. To notify a codec that this extra information is desired, loadExtras boolean value is used. Example:

my $x = Prima::Image-> load( $f, loadExtras => 1);
die "$@" unless $x;
for ( keys %{$x-> {extras}}) {
   print " $_ : $x->{extras}->{$_}\n";
}

The code above loads and prints extra information read from a file. Typical output, for example, from a gif codec based on libgif would look like:

codecID : 1
transparentColorIndex : 1
comment : created by GIMP
frames : 18

'codecID' is a Prima-defined extra field, which is an index of the codec which have loaded the file. This field's value is useful for explicit indication of codec on the save request.

'frames' is also a Prima-defined extra field, with integer value set to a number of frames in the image. It might be set to -1, signaling that codec is incapable of quick reading of the frame count. If, however, it is necessary to get actual frame count, a 'wantFrames' profile boolean value should be set to 1 - then frames is guaranteed to be set to a 0 or positive value, but the request may take longer time, especially on a large file with sequential access. Real life example is a gif file with more than thousand frames. 'wantFrames' is useful in null load requests.

Multiprofile loading requests

The parameters that are accepted by load, are divided into several categories - first, those that apply to all loading process and those who apply only to a particular frame. Those who are defined by Prima, are enumerated above - loadExtras, loadAll etc. Only loadExtras, noImageData, noIncomplete and iconUnmask are applicable to a frame, other govern the loading process. A codec may as well define its own parameters, however it is not possible to tell what parameter belongs to what group - this information is to be found in codec documentation;

The parameters that applicable to any frame, can be specified separately to every desirable frame in single call. For that purpose, parameter 'profiles' is defined. 'profiles' is expected to be an anonymous array of hashes, each hash where corresponds to a request number. Example:

$x-> load( $f, loadAll => 1, profiles => [
     {loadExtras => 0},
     {loadExtras => 1},
]);

First hash there applies to frame index 0, second - to frame index 1. Note that in code

$x-> load( $f,
   map => [ 5, 10],
   profiles => [
     {loadExtras => 0},
     {loadExtras => 1},
]);

first hash applies to frame index 5, and second - to frame index 10.

Null load requests

If it is desired to peek into image, reading type and dimensions only, one should set 'noImageData' boolean value to 1. Using 'noImageData', empty objects with read type are returned, and with extras 'width' and 'height' set to image dimensions. Example:

$x-> load( $f, noImageData => 1);
die "$@" unless $x;
print $x-> {extras}-> {width} , 'x' , $x-> {extras}-> {height}, 'x',
   $x-> type & im::BPP, "\n";

Some information about image can be loaded even without frame loading - if the codec provides such a functionality. This is the only request that cannot be issued on a package:

$x-> load( $f, map => [], loadExtras => 1);

Since no frames are required to load, an empty array is returned upon success and an array with one undefined value on failure.

Using Prima::Image descendants

If Prima needs to create a storage object, it is by default Prima::Image, or a class name of an caller object, or a package the request was issued on. This behavior can be altered using parameter 'className', which defines the class to be used for the frame.

my @x = Prima::Image-> load( $f,
    map => [ 1..3],
    className => 'Prima::Icon',
    profiles => [
        {},
        { className => 'Prima::Image' },
        {}
    ],

In this example @x will be ( Icon, Image, Icon) upon success.

When loading to an Icon object, the default toolkit action is to build the transparency mask based on image data. When it is not the desired behavior, e.g., there is no explicit knowledge of image, but the image may or may not contain transparency information, iconUnmask boolean option can be used. When set to a true value, and the object is Prima::Icon descendant, Prima::Icon::autoMasking is set to am::None prior to the file loading. By default this options is turned off.

Loading with progress indicator

Some codecs (PNG,TIFF,JPEG) can notify the caller as they read image data. For this purpose, Prima::Image has two events, onHeaderReady and onDataReady. If either (or both) are present on image object that is issuing load call, and the codec supports progressive loading, these events are called. onHeaderReady is called when image header data is acquired, and empty image with the dimensions and pixel type is allocated. onDataReady is called whenever a part of image is ready and is loaded in the memory of the object; the position and dimensions of the loaded area is reported also. The format of the events is:

onHeaderReady $OBJECT
onDataReady   $OBJECT, $X, $Y, $WIDTH, $HEIGHT

onHeaderReady is called only once, but onDataReady is called as soon as new image data is available. To reduce frequency of these calls, that otherwise would be issued on every scanline loaded, load has parameter eventDelay, a number of seconds, which limits event rate. The default eventDelay is 0.1 .

The handling on onDataReady must be performed with care. First, the image must be accessed read-only, which means no transformations with image size and type are allowed. Currently there is no protection for such actions ( because codec must perform these ), so a crash will most surely issue. Second, loading and saving of images is not in general reentrant, and although some codecs are reentrant, loading and saving images inside image events is not recommended.

There are two techniques to display partial image as it loads. All of these share overloading of onHeaderReady and onDataReady. The simpler is to call put_image from inside onDataReady:

$i = Prima::Image-> new(
	onDataReady => sub {
		$progress_widget-> put_image( 0, 0, $i);
	},
);

but that will most probably loads heavily underlying OS-dependent conversion of image data to native display bitmap data. A more smarter, but more complex solution is to copy loaded (and only loaded) bits to a preexisting device bitmap:

$i = Prima::Image-> new(
	onHeaderReady => sub {
		$bitmap = Prima::DeviceBitmap-> new(
			width    => $i-> width,
			height   => $i-> height,
		));
	},
	onDataReady => sub {
		my ( $i, $x, $y, $w, $h) = @_;
		$bitmap-> put_image( $x, $y, $i-> extract( $x, $y, $w, $h));
	},
);

The latter technique is used by Prima::ImageViewer when it is setup to monitor image loading progress. See "watch_load_progress" in Prima::ImageViewer for details.

Truncated files

By default, codecs are not specified whether they would fail on premature end of file or omit the error and return truncated image. noIncomplete boolean flag tells that a codec must always fail if the image cannot be red in full. It is off by default. If indeed the codec detected that the file was incomplete, it sets truncated error string in the extras profile, if loadExtras was requested.

Inline files

Using Prima::Image::base64 it is possible to convert images into an base64 format, and embed the result directly into the source. Assuming an appropriate codec was compiled, the following would work:

my $icon = Prima::Icon->load_stream(<<~'ICON');
	R0lGODdhIAAgAIAAAAAAAP///ywAAAAAIAAgAIAAAAD///8CT4SPqcvtD6OctNqLcwogcK91nEhq
	3gim2Umm4+W2IBzX0fvl8jTr9SeZiU5E4a1XLHZ4yaal6XwFoSwMVUVzhoZSaQW6ZXjD5LL5jE6r
	DQUAOw==
	ICON

print $icon->save_stream;

Saving

Simple saving

Typical saving code will be:

die "$@" unless $x-> save( 'filename.duf');

Upon a single-frame invocation save returns 1 upon success an 0 on failure. Save requests also can be performed with package syntax:

die "$@" unless Prima::Image-> save( 'filename.duf',
    images => [ $x]);

Saving to a stream

Saving to a stream requires explicit codecID to be supplied. When an image is loaded with loadExtras, this field is always present on the image object, and is an integer that selects image encoding format.

my @png_id =
   map  { $_-> {codecID} }
   grep { $_-> {fileShortType} =~ /^png$/i }
   @{ Prima::Image-> codecs };
die "No png codec installed" unless @png_id;

open FILE, "> a.png" or die "Cannot save:$!";
binmode FILE;
$image-> save( \*FILE, codecID => $png_id[0])
   or die "Cannot save:$@";

Multiframe saving

In multiframe invocation save returns number of successfully saved frames. File is erased though, if error occurred, even after some successfully written frames.

die "$@" if scalar(@images) > Prima::Image-> save( $f,
   images => \@images);

Saving extras information

All information, that is found in object hash reference 'extras', is assumed to be saved as an extra information. It is a codec's own business how it reacts on invalid and/or unacceptable information - but typical behavior is that keys that were not recognized by the codec just get ignored, and invalid values raise an error.

$x-> {extras}-> {comments} = 'Created by Prima';
$x-> save( $f);

Selecting a codec

Extras field 'codecID', the same one that is defined after load requests, selects explicitly a codec for an image to handle. If the codec selected is incapable of saving an error is returned. Selecting a codec is only possible with the object-driven syntax, and this information is never extracted from objects but passed to 'images' array instead.

$x-> {extras}-> {codecID} = 1;
$x-> save( $f);

Actual correspondence between codecs and their indices is described latter.

NB - if codecID is not given, codec is selected by the file extension.

Type conversion

Codecs usually are incapable of saving images in all formats, so Prima either converts an image to an appropriate format or signals an error. This behavior is governed by profile key 'autoConvert', which is 1 by default. 'autoConvert' can be present in image 'extras' structures. With autoConvert set it is guaranteed that image will be saved, but original image information may be lost. With autoConvert unset, no information will be lost, but Prima may signal an error. Therefore general-purpose save routines should be planned carefully. As an example the Prima::Dialog::ImageDialog::SaveImageDialog code might be useful.

When the conversion takes place, Image property 'conversion' is used for selection of an error distribution algorithm, if down-sampling is required.

Appending frames to an existing file

This functionality is under design, but the common outlines are already set. Profile key 'append' ( 0 by default ) triggers this behavior - if it is set, then an append attempt is made.

Managing codecs

Prima provides single function, Prima::Image-> codecs, which returns an anonymous array of hashes, where every hash entry corresponds to a registered codec. 'codecID' parameter on load and save requests is actually an index in this array. Indexes for a codecs registered once never change, so it is safe to manipulate these numbers within single program run.

Codec information that is contained in these hashes is divided into following parameters:

codecID: Unique integer value for a codec, same as index of the codec entry in results of Prima::Image->codecs;
name: codec full name, string
vendor: codec vendor, string
versionMajor and versionMinor: usually underlying library versions, integers
fileExtensions: array of strings, with file extensions that are typical to a codec. example: ['tif', 'tiff']
fileType: Description of a type of a file, that codec is designed to work with. String.
fileShortType: Short description of a type of a file, that codec is designed to work with. ( short means 3-4 characters ). String.
featuresSupported: Array of strings, with some features description that a codec supports - usually codecs implement only a part of file format specification, so it is always interesting to know, what part it is.
module and package: Specify a perl module, usually inside Prima/Image directory into Prima distribution, and a package inside the module. The package contains some specific functions for work with codec-specific parameters. Current implementation defines only ::save_dialog() function, that returns a dialog that allows to change these parameters. See Prima::Dialog::ImageDialog::SaveImageDialog for details. Strings, undefined if empty.
canLoad: 1 if a codec can load images, 0 if not
canLoadStream: 1 if a codec can load images from streams, 0 otherwise
canLoadMultiple: 1 if a codec can handle multiframe load requests and load frames with index more than zero. 0 if not.
canSave: 1 if a codec can save images, 0 if not.
canSaveStream: 1 if a codec can save images to streams, 0 otherwise
canSaveMultiple: Set if a codec can save more that one frame
canAppend: Set if a codec can append frames to an existing file
types: Array of integers - each is a combination of im:: flags, an image type, which a codec is capable of saving. First type in list is a default one; if image type that to be saved is not in that list, the image will be converted to this default type.
loadInput: Hash, where keys are those that are accepted by Prima::Image-> load, and values are default values for these keys.
loadOutput: Array of strings, each of those is a name of extra information entry in 'extras' hash.
saveInput: Hash, where keys are those that are accepted by Prima::Image-> save, and values are default values for these keys.
mime: array of strings, with file extensions that are typical to a codec. example: ['image/xbm', 'image/x-bitmap']

API

This section describes parameters accepted and data returned by Prima::Image::load

Common

Loading parameters

blending BOOLEAN = 1

Affects how to treat alpha channel bits, if any.

If set, mixes the alpha channel with background color in case if loading to an image, or premultiplies color bits (either data or palette) with alpha, if loading to icon. Note that saving back the object will result in different image, but the object is ready to be displayed immediately.

If unset, color and eventual alpha bits, if loaded to an icon, will not be affected in any way. Note that saving back the object will result in the same image, but the object is not ready to be displayed immediately. See also: "premultiply_alpha" in Prima::Image.

className STRING

When loading more than one image, this string is used to create instances of image containers. By default the calling class is used (i.e. Prima::Image or Prima::Icon).

eventDelay INT

Specifies onDataReady event granularity in microseconds, if image codec is capable of triggering this event.

Default: 100

iconUnmask BOOL

If set, Prima::Icon::autoMasking is set to am::None prior to the file loading.

Default: false. Only actual for Prima::Icon loading.

index INT

When loading from a multiframe file, selects the frame index to load.

Default: 0

map [INT]

When loading from a multiframe file, selects set of frame indexes to load.

Default: undef

loadExtras BOOL

If set, all available extra information will be stored in {extras} hash on the loaded object.

Default: false

loadAll BOOL

When loading from a multiframe file, selects that all frames are to be loaded

Default: false

noImageData BOOL

When set, neither image data is not loaded, nor image dimensions are changed (newly created images have size of 1x1). Instead, {extras} contains width and height integers.

Default: false

noIncomplete BOOL

Affects the action when image is incomplete, truncated, etc. If set, signals an error. Otherwise no error is signaled and whatever data could be recovered from the image are returned, and truncated flag is set.

Default: false

profiles [HASH]

Array of hashes passed down to each frame in multiframe loads. Each frame load request will be passed an individual hash, a result of hash join of all profiles passed to Image::load and the nth hash in the array.

wantFrames BOOL

Affects how the number of frames in a file is reported in frames flag. If set, always scans the file for exact number. Otherwise it is up to the codec to do that.

Default: false

Load output

codecID INT: Indicates the internal codec ID used to load the image. Can be used for Image::save.
frames INT: If set to a positive integer, indicates number of frames in a file. Otherwise signals that there are frames, but codec needs an expensive scan to calculate the frames (and wantFrames set).
height INT: When noImageData is in action, contains image height.
truncated BOOL: When noIncomplete is in action, is set if image was truncated. The value is the error string.
width INT: When noImageData is in action, contains image width.

Saving parameters

autoConvert BOOL

Affects the action when image cannot be stored in file format in its existing pixel format. If set, the system tries to convert image into a pixel format understood by the selected codec. Fails otherwise.

Default: true

codecID INT

Overrides codec selection based on filename extension.

Default: undef

BMP codec

BMP, the bitmap codec is not depended on external libraries and is always available.

BitDepth INT

Original bit depth, may differ from Image::bpp.

Not valid as a saving parameter.

Compression STRING

Bitmap compressing method.

Not valid as a saving parameter.

HotSpotX, HotSpotY INT

If loading from cursor file, contains pointer hotspot coordinates

ImportantColors INT

Minimal number of colors needed to display the image

OS2 BOOL

Set when loading OS/2 bitmap

XResolution, YResolution INT

Image resolution in PPM

X11 codec

X11, the X Consortium data file codec may depend on external libraries, but is implement internally if these are not found, and is thus always available.

hotSpotX, hotSpotY INT: Contains pointer hotspot coordinates, if any

XPM codec

extensions HASH: Set of xpm-specific extension strings. Cannot be used for saving.
hintsComment, colorsComment, pixelsComment STRING: Contains comments to different sections
hotSpotX, hotSpotY INT: Contains pointer hotspot coordinates
transparentColors [COLOR]: Array or transparent colors. Cannot be used for saving.

JPEG codec

Load parameters

exifTransform none|auto|wipe

If set to auto or wipe, tries to detect whether there is are any exif tags hinting that the image has to be rotated and/or mirrored. If found, applies the transformation accordingly.

When set to wipe, in addition to that, removes the exif tags so that subsequent image save won't result in transformed images with exifs tags still present.

This parameter requires loadExtras flag set, because exif tags are stored in extra JPEG data.

Load output and save input

appdata [STRING]

Array of raw binary strings found in extra JPEG data.

comment STRING

Any comment text found in file.

progressive BOOL

If set, produces a progressively encoded JPEG file.

Default: 0

Only used for saving.

quality INT

JPEG quality, 1-100.

Default: 75

Only used for saving.

PNG codec

Load input

background COLOR

When PNG file contains alpha channel, and alpha is set to blend, this color is used to blend the background. If set to clInvalid, default PNG library background color is used.

Default: clInvalid

Not applicable for Prima::Icon.

gamma REAL

Override gamma value applied to the loaded image

Default: 0.45455

screen_gamma REAL

Current gamma value for the operating system, if specified.

Default: 2.2

Load output and save input

background COLOR

Default PNG library background color

Default: clInvalid, which means PNG library default

blendMethod blend|no_blend|unknown

Signals whether the new frame to be blended over the existing animation, or replace it.

delayTime $milliseconds

Delay time between frames

default_frame BOOLEAN

When set, means that the first image is a "default" frame, a special backward-compatibility image that is supposed to be excluded from the animation sequence, to be displayed only when all animation frames cannot be loaded for whatever reason.

disposalMethod none|background|restore|unknown

Signals whether the frame, before being replaced, is to be erased by the background color, previous frame, or none.

gamma REAL

Gamma value found in file.

Default: 0.45455

hasAlpha BOOLEAN

If set, image contains alpha channel

iccp_name, iccp_profile STRING

Embedded ICC color profiles in raw format

Default: unspecified and "".

interlaced BOOL

If set, PNG file is interlaced

Default: 0

left INTEGER

Frame horizontal offset from the screen

loopCount INTEGER

How many times the animation sequence should run, or 0 for forever.

mng_datastream BOOL

If set, file contains a MNG datastream

Default: 0

offset_x, offset_y INT

Positive offset from the left edge of the screen to offset_x and the positive offset from the left edge of the screen to offset_y

Default: 0

offset_dimension pixel|micrometer

Offset units

Default: pixel

render_intent none|saturation|perceptual|relative|absolute

See PNG docs.

Default: none

resolution_x, resolution_y INT

Image resolution

Default: 0

resolution_dimension meter|unknown

Image resolution units

Default: meter

scale_x, scale_y

Image scale factors

Default: 1

scale_unit meter|radian|unknown

Image scale factor units

Default: unknown

screenWidth, screenHeight INTEGER

text HASH

Free-text comments found in the file

Default: {}

top INTEGER

Frame vertical offset from the screen

transparency_table [INT]

When a paletted image contains transparent colors, returns array of palette indexes (transparency_table) in 0-255 range, where each number is an alpha value.

Default value: empty array

transparent_color COLOR

One transparent color value for 24-bit PNG images.

Default value: clInvalid (i.e. none)

transparent_color_index INT

One transparent color value, as palette index for 8- or less- bit PNG images.

Default value: -1 (i.e. none)

Not applicable for load.

TIFF codec

Load input

MinIsWhite BOOL

Automatically invert PHOTOMETRIC_MINISWHITE images

Default: 1

Fax BOOL

If set, converts 1-bit grayscale with ratio 2:1 into 2-bit grayscale (algorithm also known as faxpect).

Default: 0

Load output

Photometric STRING

TIFF PHOTOMETRIC_XXX constant. One of:

MinIsWhite
MinIsBlack
Palette
YCbCr
RGB
LogL
LogLUV
Separated
MASK
CIELAB
DEPTH
Unknown

BitsPerSample INT

Bits used to represent a single sample, 1-64

SamplesPerPixel INT

Number of samples per pixel, 1-4. F.ex. most images have 1 sample. Planar TIFFs may split low and high bytes in 2 samples. RGB has 3 samples, YCbCr and RGBA has 4.

PlanarConfig contiguous|separate

separate images split individual samples or components (f.ex. R and G and B) into individual planes. contiguous mix sample bytes one after another.

SampleFormat STRING

Pixel sample format, one of:

unsigned integer
signed integer
floating point
untyped data
complex signed int
complex floating point

Tiled BOOL

If set, TIFF is tiled

Faxpect BOOL

When Fax option set set to true, and indeed the image was converted from 1 to 2 bits, this parameter will be set to signal this.

CompressionType STRING

Compression algorithm used for reading TIFF. One of:

NONE
CCITTRLE
CCITTFAX3
CCITTFAX4
LZW
OJPEG
JPEG
NEXT
CCITTRLEW
PACKBITS
THUNDERSCAN
IT8CTPAD
IT8LW
IT8MP
IT8BL
PIXARFILM
PIXARLOG
DEFLATE
ADOBE_DEFLATE
DCS
JBIG
SGILOG
SGILOG24

Save input

Compression STRING: Same values as in CompressionType. Different names are used to avoid implicit but impossible compression selection, because tibtiff can decompress many types, but compress only a few.

Load output and save input

generic strings

The following keys have no specific meanings for Prima, but are both recognized for loading and saving:

Artist
Copyright
DateTime
DocumentName
HostComputer
ImageDescription
Make
Model
PageName
PageNumber
PageNumber2

PageNumber, PageNumber2 INT

Default: 1

ResolutionUnit inch|centimeter|none

Default: none

Software

Default: Prima

XPosition, YPosition INT

Default: 0

XResolution, YResolution INT

Default: 1200

GIF codec

For GIF animation see Prima::Image::Animate.

The following load output and save input keys are recognized:

comment STRING

GIF comment text

delayTime INT

Delay in hundredth of a second between frames

Default: 1

disposalMethod INT

Animation frame disposal method

DISPOSE_NOT_SPECIFIED    = 0; # Leave frame, let new frame draw on top
DISPOSE_KEEP             = 1; # Leave frame, let new frame draw on top
DISPOSE_CLEAR            = 2; # Clear the frame's area, revealing bg
DISPOSE_RESTORE_PREVIOUS = 3; # Restore the previous (composited) frame

Default: 0

interlaced BOOL

If set, GIF is interlaced

Default: 0

left, top INT

Frame offset in pixels

Default: 0

loopCount INT

How many times the GIF animation loops. 0 means indefinite.

Default: 1

screenBackGroundColor COLOR

GIF screen background color

Default: 0

screenColorResolution INT

Default: 256

screenWidth, screenHeight INT

Default: -1, i.e. use image width and height

screenPalette [INT]

Default: 0,0,0,255,255,255

transparentColorIndex INT

Index of GIF transparent color

Default: 0

userInput INT

User input flag

Default: 0

WebP codec

Load input

background $ARGB_color: Integer constant encoded as ARGB, hints the background to be used
blendMethod blend|no_blend|unknown: Signals whether the new frame to be blended over the existing animation, or replace it.
delayTime $milliseconds: Delay time between frames
disposalMethod none|background|unknown: Signals whether the frame, before being replaced, is to be erased by the background color or not.
hasAlpha BOOLEAN: If set, image contains alpha channel
left INTEGER: Frame horizontal offset from the screen
loopCount INTEGER: How many times the animation sequence should run, or 0 for forever.
screenWidth INTEGER
screenHeight INTEGER
top INTEGER: Frame vertical offset from the screen

Save input

WebP requires all images to have same dimensions. Also, saving the webp loading result might fail because loaded frames might only contains parts to be superimposed on each other, while saving requires always full frames. To convert webp loaded frames to something that can be saved later more-or-less identically, use Prima::Image::webp::animation_to_frames converter:

use Prima qw(Image::webp);
my @i = Prima::Icon->load('source.webp', loadAll => 1, loadExtras => 1) or die $@;
@i = Prima::Image::webp::animation_to_frames(@i);
die $@ if @i != Prima::Icon->save('target.webp', images => \@i);

background $ARGB_color: Integer constant encoded as ARGB, hints the background to be used
compression lossless (default)|lossy|mixed
delay $milliseconds
filter_strength INTEGER: Setting between 0 and 100, 0 means off.
kmax INTEGER: Min distance between key frames. Default is 9 for lossless compression, and 3 for lossy
kmin INTEGER: Max distance between key frames. Default is 17 for lossless compression, and 5 for lossy
loopCount 0: How many times the animation sequence should run, or 0 for forever.
method INTEGER: Compression method vs size, 0 (fast) to 6 (slow)
minimize_size BOOLEAN: Minimize output size (off by default)
quality INTEGER: Quality factor (0:small..100:big)
thread_level BOOLEAN: Use multi-threading if available (off by default)

HEIF codec

Load output

chroma_bits_per_pixel
depth_images: Number of depth images available for the frame
has_alpha
ispe_height, ispe_width: Original image size before tranformations (crop, rotation, etc) are applied
is_primary: Set if this is the primary image
luma_bits_per_pixel
premultiplied_alpha: Set if alpha is premultiplied
thumbnails: Array of hashes with keys type, content_type, and content.
aux
metadata
thumbnail_of INDEX: Set it is thumbnail of the INDEXth toplevel frame

Save input

quality: 0-100
compression: HEIC,AV1,AVC
is_primary: 0 gets to be a primary by default, but an be set explicitly
premultiplied_alpha: True if alpha is premultiplied
metadata: Array of hashes with keys type, content_type, and content.
thumbnail_of INDEX: Sets this images as a thumbnail of the INDEXth toplevel frame

AUTHOR

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

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

Loading

Simple loading

Loading from stream

Multiframe loading

Querying extra information

Multiprofile loading requests

Null load requests

Using Prima::Image descendants

Loading with progress indicator

Truncated files

Inline files

Saving

Simple saving

Saving to a stream

Multiframe saving

Saving extras information

Selecting a codec

Type conversion

Appending frames to an existing file

Managing codecs

API

Common

Loading parameters

Load output

Saving parameters

BMP codec

X11 codec

XPM codec

JPEG codec

Load parameters

Load output and save input

PNG codec

Load input

Load output and save input

TIFF codec

Load input

Load output

Save input

Load output and save input

GIF codec

WebP codec

Load input

Save input

HEIF codec

Load output

Save input

AUTHOR

SEE ALSO

Module Install Instructions