Simple loading¶

In the simplest case, loading a single image would look like this:

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

Image functions can be invoked either as package functions or as Prima::Image object methods. The code above could be also written as

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

In both cases, $x contains loaded image data upon success. If an error occurs, it is returned in the $@ variable ( see perlvar ).

Loading from stream¶

"Prima::Image" can also load images 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 calls can be issued in two ways:

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

In the second case, the content of the first frame is stored in $x and $x[0]. To check if the error has occurred during the loading, inspect the last item of the returned array; it is undefined if the error indeed occurred. This check works also if an empty array is returned. Only this last item can be undefined, others are guaranteed to be valid objects.

Prima can load more than one image from a file, assuming the image format allows that. The "load" function recognizes such multiframe semantics when certain extra hash keys are used. These keys are:

loadAll

Requests to load all frames that can be read from the file:

        loadAll => 1
    

index

If present, returns a single frame with the index given:

        index => 8
    

map

Contains an anonymous array of the frame indices to load. The indices must be integers that are greater or equal to zero:

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

Querying extra information¶

By default, Prima loads only image pixels and palette. For any other information that can be loaded, use the hash 'extras' bound to the image object. To notify the image loader that this extra information is expected, the "loadExtras" boolean value is used:

        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 the libgif library would look like this:

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

"codecID" is a Prima-defined integer field, an internal index of the codec which had previously loaded the file. This value is useful for the explicit selection of the codec to be used for saving an image.

"frames" is also a Prima-defined field, with its integer value set to the number of frames in the image. It might be set to -1 signaling that the codec is incapable of quick reading of the frame count. If, however, it is necessary to get the actual frame count, the "wantFrames" boolean value should be set to 1 - then the "frames" field is guaranteed to be set to a 0 or a positive value. Such a request may take longer though, especially on large files with sequential access. A real-life example is a gif file with more than a thousand frames. The "wantFrames" flag is also useful in null load requests (see below).

Multiprofile loading requests¶

The parameters that are accepted by the "load" function are divided into two groups - first, those that apply to the whole loading process, and then those that apply only to a particular frame. Some fields that were already mentioned ("wantFrames" and "loadAll") belong to the first group because they affect the whole loading session. Some other parameters ("loadExtras", "noImageData", "noIncomplete", "iconUnmask") can be applied to each loaded frame, individually. 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 the codec documentation.

The parameters that apply to a frame, can be specified separately for every frame in a single call. For that purpose, the special parameter "profiles" is defined. The "profiles" value is expected to be an anonymous array of hashes, where each hash corresponds to a request number. For example:

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

The first hash there applies to the frame index 0, second - to the frame index 1. Note that in the code below

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

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

Null load requests¶

If it is desired to quickly peek into an image, reading only its pixel type and dimensions, one should set the "noImageData" boolean value to 1. Using "noImageData", empty image objects are returned, that would have the "type" property set to the image type (as the codec would translate it to the Prima image type), and with the extras "width" and "height" set to the 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 image information can be loaded even without frame loading - if the codec provides such a functionality. This is the only request that cannot be issued with the package syntax, an existing image object is required:

        my $x = Prima::Image->new;
        $x-> load( $f, map => [], loadExtras => 1);

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

Using Prima::Image descendants¶

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

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

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

When loading to an Icon object, the default toolkit action is to build the transparency mask based on the image data. When this is not desired, f.ex., there is no explicit knowledge of the image to be loaded, while the image may or may not contain transparency information, the "iconUnmask" boolean parameter can be used. When set to the "true" value, and the object is a "Prima::Icon" descendant, "Prima::Icon::autoMasking" is set to "am::None" before the file loading which effectively disables any attempt to generate the icon mask. By default, this option is turned off.

Loading with the progress indicator¶

Some codecs (PNG,TIFF,JPEG) can signal their progress as they read image data. For this purpose, the "Prima::Image" class defines two events, "onHeaderReady" and "onDataReady". If either (or both) are present on the image object issuing the "load" call, and the codec supports progressive loading, then these events will be called. The "onHeaderReady" event is called when the image header data is acquired, and an empty image with the required pixel dimensions and type is allocated. The "onDataReady" notification is called whenever a part of the image is ready and is loaded in the memory of the object; the position and dimensions of the loaded area are reported also. The format of the events is as follows:

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

The "onHeaderReady" event is called only once while "onDataReady" is called as soon as new image data is available. To reduce the frequency of these calls, which otherwise would be issued after every scanline loaded, "load" has the parameter "eventDelay", the minimum number of seconds that need to pass between two consecutive "onDataReady" calls. The default "eventDelay" is 0.1 .

The handling of the "onDataReady" event must be performed with care. First, the image must be accessed read-only, i e no transformations of any kind are allowed. Currently, there is no protection for such actions ( because the codec must also perform these itself), 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 the image progressively. Both of them require overloading the "onHeaderReady" and "onDataReady" callbacks. The simpler case is to call the "put_image" method from inside "onDataReady":

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

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

        $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 the "Prima::ImageViewer" widget class when it is ordered to monitor the image loading progress. See "watch_load_progress" in Prima::ImageViewer for details.

Truncated files¶

By default, codecs are not told whether they would fail on the premature end of the file or omit the error and return a truncated image. The "noIncomplete" boolean parameter tells that a codec must always fail if the image cannot be read in full. It is off by default. If indeed the codec detects that the file is incomplete, it sets the "truncated" field in the "extras" profile, if "loadExtras" was requested; the field is a string and contains the error message that occurred when the codec tried to load the truncated field.

Inline files¶

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

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

Reading one frame at a time¶

When one needs to load all frames from an image that contains too many frames, or there is a constraint on memory, Prima provides a way to load images one by one, without needing to allocate space for all frames in the file.

This section describes the lower-level API that allows for that functionality, however, an easier-to-use higher level API is documented in Prima::Image::Loader .

In order to read one frame at a time, the programmer needs to open a loading session, by adding the "session => 1" option to the "load" call; that call can only be made on an existing object, not on the package. The call would return the success flag and an eventual error in $@, as usual. No frames are loaded yet, though the "extras" hash on the caller image object may be filled, depending on the "loadExtras" option. The options supplied to the session opening call would apply to all subsequent frames, but these settings may be overridden later.

Having the session successfully opened, the subsequent calls to "load" with the "session => 1" option but with the first parameter set to undef will load the next frame. Each of those "load" call will recognize the options supplied and will apply them to indifidual frames. The session-based loading will recognize all of the function options, except the "map", "profiles" and "loadAll" options. The loading session is closed automatically after either a first loading failure or after the end of file is reached.

Simple saving¶

The typical saving code is

   $x-> save( 'filename.jpg') or die $@;

The function returns 1 on success and 0 on failure. Save requests also can be performed with the package syntax:

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

Saving to a stream¶

Saving to a stream requires the explicit "codecID" integer value to be supplied. When the image is loaded with "loadExtras", this field is always present on the image object and is the integer that selects the image file 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)
      or die "Cannot save:$@";

Multiframe saving¶

When saving more than one image object into a single file the method returns the number of successfully saved frames. The saved image file is erased though, if an error occurs, 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 the object hash reference "extras", is assumed to be saved in the image file too. It is a codec's own business how it reacts to invalid and/or unacceptable information - but a typical behavior is that keys that were not recognized by the codec get ignored, while invalid values raise an error.

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

Saving one frame at a time¶

Similar to the session-based loading, Prima provides the functionality to save a multi-frame image with one frame at a time, using the similar API calls.

This section describes the lower-level API that allows for that functionality, however, an easier-to-use higher level API is documented in "Prima::Image::Saver" in Prima::Image::Loader .

In order to save one frame at a time, the programmer needs to open a saving session, by adding the "session => 1" option to the "save" call, and the "frames" options that signals how many frames are to be saved in total; that call can only be made on an existing object, not on the package. The call would return the success flag and an eventual error in $@, as usual. The options supplied to the session opening call would apply to all subsequent frames, but these settings may be overridden later.

Having the session successfully opened, the subsequent calls to "save" with the "session => 1" and the image as the first option option would save the next frame. Each of those "save" call will recognize the options supplied and will apply them to indifidual frames. The session-based saving will recognize all of the function options, except the "images" option. The saving session is closed automatically after a first failure.

Selecting a codec¶

The integer field "codecID", the same field that is defined after successful load requests, explicitly selects the codec for saving the image. If the codec is incapable of saving then an error is returned. Selecting a codec is only possible with the object-driven syntax, and this information is never extracted from the objects but is passed in the "images" array instead.

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

The actual relation between codecs and their indices is described below.

Note: if "codecID" is not specified, Prima tries to deduce the codec by the file extension.

Type conversion¶

Codecs usually are incapable of saving images in all possible pixel formats, so whenever Prima needs to save an image with an unsupported pixel type it either converts the image to an appropriate pixel format or signals an error. This behavior is managed by the parameter "autoConvert", which is 1 by default. With the "autoConvert" set, it is guaranteed that the image will be saved, but original image information may be lost. With the "autoConvert" field set to 0, no information will be lost, but Prima may signal an error. Therefore general-purpose saving routines should be planned carefully. As an example, the "Prima::Dialog::ImageDialog::SaveImageDialog" code might be useful.

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

Common¶

Loading parameters

blending BOOLEAN = 1

Affects how to treat the alpha channel bits, if present.

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

If unset, the color and eventual alpha bits, if loaded to an icon, will not be affected in any way. Note that saving the object will result in the same image, but the object will not be 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 seconds, when the codec is capable of triggering this event.

Default: 0.1

iconUnmask BOOL

If set, "Prima::Icon::autoMasking" is set to "am::None" before the file loading which disables any attempt to deduce the mask pixels based on the data pixels.

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

index INT

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

Default: 0

loadExtras BOOL

If set, all available extra information will be stored in the "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

map [INT]

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

Default: undef

noImageData BOOL

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

Default: false

noIncomplete BOOL

Affects the action when the image is incomplete, truncated, etc. If set, signals an error. Otherwise, no error is signaled and whatever data could be recovered from the image is returned. In the latter case, the "truncated" field contains the error string.

Default: false

profiles [HASH]

An array of hashes passed down to each frame in multiframe loading sessions. Each frame loading request will be provided with an individual hash, a result of the 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 the "frames" field. If set, Prima always scans the file for the exact number of frames. Otherwise, it is up to the codec to do that.

Default: false

See also: frames.

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 the number of frames in the file. Otherwise signals that there are frames, but the codec needs an expensive scan to calculate the number (and the "wantFrames" parameter being set).

height INT

When the "noImageData" parameter is set, contains the image height.

truncated BOOL

When the "noIncomplete" parameter is set, will be set if the image was truncated. The value is the error string.

width INT

When the "noImageData" parameter is set, contains the image width.

Saving parameters

autoConvert BOOL

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

Default: true

codecID INT

Disables the algorithm where the codec is selected based on the filename extension. Uses the codec number "codecID" instead. Note that when saving images into streams this option must always be present.

Default: undef

BMP codec¶

BMP, the bitmap codec is not dependent 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 compression method.

Not valid as a saving parameter.

HotSpotX, HotSpotY INT

If loading from a cursor file, contains pointer hotspot coordinates

ImportantColors INT

The minimal number of colors is needed to display the image

OS2 BOOL

Is set when loading an OS/2 bitmap

XResolution, YResolution INT

Image resolution in PPM

X11 codec¶

X11, the X Consortium data file codec is implemented internally and is always available.

hotSpotX, hotSpotY INT

Contains pointer hotspot coordinates, if any

XPM codec¶

extensions HASH

A set of xpm-specific extension strings. Cannot be used for saving.

hintsComment, colorsComment, pixelsComment STRING

Contains comments on different sections

hotSpotX, hotSpotY INT

Contains the pointer hotspot coordinates

transparentColors [COLOR]

An array of 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 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 a "loadExtras" parameter set because exif tags are stored in extra JPEG data.

Output fields of the loader and input parameters for the saver

appdata [STRING]

An array of raw binary strings found in extra JPEG data.

comment STRING

Any comment text found in the 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 a PNG file contains an alpha channel, and "alpha" is set to "blend", this color is used to blend the background. If set to "clInvalid", the default PNG library background color is used.

Default: clInvalid

Not applicable to "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 is to be blended over the existing animation, or it should replace that.

delayTime $milliseconds

Delay between frames

default_frame BOOLEAN

When set, means that the first image is the "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, or by the previous frame, or not touched at all.

gamma REAL

Gamma value found in the file.

Default: 0.45455

hasAlpha BOOLEAN

If set, the image contains an alpha channel

iccp_name, iccp_profile STRING

Embedded ICC color profiles in raw format

Default: "unspecified" and "".

interlaced BOOL

If set, the PNG file is interlaced

Default: 0

left INTEGER

The horizontal offset of the frame from the screen

loopCount INTEGER

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

mng_datastream BOOL

If set, the file contains an MNG datastream

Default: 0

offset_x, offset_y INT

A 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 the PNG docs ( <http://www.libpng.org/pub/png/spec/1.1/PNG-Chunks.html>, 4.2.9. sRGB Standard RGB color space).

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

The vertical offset of the frame from the screen

transparency_table [INT]

When a paletted image contains transparent colors, returns an array of palette indexes ("transparency_table") in the 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 the 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. Most images have 1 sample. Planar TIFFs may split low and high bytes in 2 samples. RGB has 3 samples, and YCbCr and RGBA have 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 the "Fax" option was set to "true", and indeed the image was converted from 1 to 2 bits, this parameter will be set to signal this.

CompressionType STRING

The compression algorithm used for reading. 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 a 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, the GIF image is interlaced

Default: 0

left, top INT

Frame offset in pixels

Default: 0

loopCount INT

How many times do 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 the GIF transparent color

Default: 0

userInput INT

User input flag

Default: 0

WebP codec¶

Load output

background $ARGB_color

An integer constant encoded as 32-bit ARGB, hints the background color to be used

blendMethod blend|no_blend|unknown

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

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, the image contains an alpha channel

left INTEGER

The horizontal offset of the frame from the screen

loopCount INTEGER

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

screenWidth INTEGER

screenHeight INTEGER

top INTEGER

The vertical offset of the frame from the screen

Save input

WebP requires all images to have the same dimensions. Also, saving the webp loading result might fail because loaded frames might only contain parts to be superimposed on each other while saving always requires full frames. To convert the loaded frames to something that can be saved later more-or-less identically, use the "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

An integer constant encoded as 32-bit ARGB, hints the background to be used

compression lossless (default)|lossy|mixed

delay $milliseconds

filter_strength INTEGER

The value is between 0 and 100, where 0 means off.

kmax INTEGER

Min distance between keyframes. The default is 9 for the lossless compression and 3 for the lossy

kmin INTEGER

Max distance between keyframes. The default is 17 for the lossless compression and 5 for the 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 the 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 transformations (crop, rotation, etc) are applied

is_primary

Set if this is the primary image

luma_bits_per_pixel

premultiplied_alpha

Is set if the values of the alpha channel are premultiplied

thumbnails

An array of hashes with keys type, content_type, and content.

aux

metadata

thumbnail_of INDEX

Set if this frame is the thumbnail of the INDEXth top-level frame

Save input

quality

Integer, 0-100

compression

HEIC,AV1,AVC

is_primary

The first frame (#0) gets to be the primary by default, but this can be changed explicitly.

premultiplied_alpha

Trueset if the values of the alpha channel are premultiplied

metadata

An array of hashes with keys type, content_type, and content.

thumbnail_of INDEX

Sets this image as the thumbnail of the INDEXth top-level frame