=head1 NAME

Prima::image-load - using the image subsystem

=head1 DESCRIPTION

This document describes using the Prima image subsystem
for loading and saving images

=head1 Loading

=head2 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, C<$x> contains loaded image data upon success.  If an error
occurs, it is returned in the C<$@> variable ( see L<perlvar> ).

=head2 Loading from stream

C<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;

=head2 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 C<$x> and
C<$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 C<load> function recognizes such I<multiframe> semantics when
certain extra hash keys are used.  These keys are:

=over

=item loadAll

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

        loadAll => 1

=item index

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

        index => 8

=item 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]

=back

=head2 Querying extra information

By default, Prima loads only image pixels and palette. For any other
information that can be loaded, use the hash C<'extras'> bound to the image
object. To notify the image loader that this extra information is expected, the
C<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 I<gif> codec based on the I<libgif> library would look
like this:

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

C<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.

C<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 C<wantFrames> boolean value should be set to
1 - then the C<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 C<wantFrames> flag is also useful in null load requests
(see below).

=head2 Multiprofile loading requests

The parameters that are accepted by the C<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
(C<wantFrames> and C<loadAll>) belong to the first group because they affect the
whole loading session. Some other parameters (C<loadExtras>, C<noImageData>,
C<noIncomplete>, C<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
C<profiles> is defined. The C<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.

=head2 Null load requests

If it is desired to quickly peek into an image, reading only its pixel type and
dimensions, one should set the C<noImageData> boolean value to 1. Using
C<noImageData>, empty image objects are returned, that would have the C<type>
property set to the image type (as the codec would translate it to the Prima
image type), and with the extras C<width> and C<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.

=head2 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
C<Prima::Image> class.  This behavior can be altered using the parameter
C<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, C<@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 C<iconUnmask> boolean
parameter can be used. When set to the C<true> value, and the object is a
C<Prima::Icon> descendant, C<Prima::Icon::autoMasking> is set to C<am::None>
before the file loading which effectively disables any attempt to generate the
icon mask. By default, this option is turned off.

=head2 Loading with the progress indicator

Some codecs (PNG,TIFF,JPEG) can signal their progress as they read image data.
For this purpose, the C<Prima::Image> class defines two events,
C<onHeaderReady> and C<onDataReady>. If either (or both) are present on the
image object issuing the C<load> call, and the codec supports progressive
loading, then these events will be called. The C<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 C<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 C<onHeaderReady> event is called only once while C<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, C<load> has the
parameter C<eventDelay>, the minimum number of seconds that need to pass
between two consecutive C<onDataReady> calls. The default C<eventDelay> is 0.1
.

The handling of the C<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 C<onHeaderReady> and C<onDataReady> callbacks. The
simpler case is to call the C<put_image> method from inside C<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 C<Prima::ImageViewer> widget class when it
is ordered to monitor the image loading progress. See
L<Prima::ImageViewer/watch_load_progress> for details.

=head2 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 C<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 C<truncated> field in the C<extras> profile, if
C<loadExtras> was requested; the field is a string and contains the error
message that occurred when the codec tried to load the truncated field.

=head2 Inline files

Using the C<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;

=head2 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 L<Prima::Image::Loader> .

In order to read one frame at a time, the programmer needs to open a loading
session, by adding the C<< session => 1 >> option to the C<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 C<$@>, as usual. No frames are
loaded yet, though the C<extras> hash on the caller image object may be filled,
depending on the C<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 C<load> with
the C<< session => 1 >> option but with the first parameter set to undef will
load the next frame. Each of those C<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 C<map>, C<profiles> and
C<loadAll> options. The loading session is closed automatically after either a
first loading failure or after the end of file is reached.

=head1 Saving

=head2 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]);

=head2 Saving to a stream

Saving to a stream requires the explicit C<codecID> integer value to be
supplied. When the image is loaded with C<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:$@";

=head2 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);

=head2 Saving extras information

All information that is found in the object hash reference C<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);

=head2 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
L<Prima::Image::Loader/Prima::Image::Saver> .

In order to save one frame at a time, the programmer needs to open a saving
session, by adding the C<< session => 1 >> option to the C<save> call, and the
C<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 C<$@>, 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 C<save> with
the C<< session => 1 >> and the image as the first option option would save the
next frame.  Each of those C<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 C<images> option. The saving session is
closed automatically after a first failure.

=head2 Selecting a codec

The integer field C<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 C<images> array instead.

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

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

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

=head2 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 C<autoConvert>, which is 1 by default.
With the C<autoConvert> set, it is guaranteed that the image will be saved, but
original image information may be lost. With the C<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
C<Prima::Dialog::ImageDialog::SaveImageDialog> code might be useful.

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

=head1 Managing the codecs

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

Codec information that is contained in these hashes contains the
following fields:

=over

=item codecID

A unique integer value for a codec, the same as the index of the codec entry in
the result of the C<< Prima::Image->codecs >> method

=item name

The full codec name, string

=item vendor

The codec vendor, string

=item versionMajor and versionMinor

Usually underlying library versions, integers

=item fileExtensions

An array of strings, with file extensions that are typical to the codec.
Example: ['tif', 'tiff']

=item fileType

Description of the type of file that the codec is designed to work with.  A
string.

=item fileShortType

Short description of the type of file that the codec is designed to work
with ( short means 3-4 characters ). A string.

=item featuresSupported

An array of strings containing string description of the features that the
codec supports - usually they implement only a part of file format
specification, so it is always interesting to know, which part

=item module and package

Specifies the perl module, usually inside the F<Prima/Image> directory in the
Prima distribution, and the package name inside the module. The package
contains some specific functions for working with codec-specific parameters.
The current implementation defines the only C<save_dialog> function that
creates a dialog that allows to change these parameters. See
C<Prima::Dialog::ImageDialog::SaveImageDialog> for details.  Strings or
C<undef>.

=item canLoad

1 if the codec can load images, 0 if not

=item canLoadStream

1 if the codec can load images from streams, 0 otherwise

=item canLoadMultiple

1 if the codec can handle multiframe load requests and load frames with
an index more than zero, 0 otherwise

=item canSave

1 if the codec can save images, 0 if not.

=item canSaveStream

1 if the codec can save images to streams, 0 otherwise

=item canSaveMultiple

Is set if the codec can save more than one frame

=item types

An array of integers - each is a combination of the C<im::XXX> flags, the image
type, that the codec can save. The first type in the list is the default type;
if the type of the image to be saved is not in that list, the image will be
converted to this default type.

=item loadInput

A hash, where the keys are those that are accepted by the C<< Prima::Image-> load >> method
and the values are the default values for these keys.

=item loadOutput

An array of strings, each is the name of an extra information entry
in the C<extras> hash.

=item saveInput

A hash, where the keys are those that are accepted by the C<< Prima::Image-> save >> method
and the values are the default values for these keys.

=item mime

An array of strings, containing the mime identifiers specific to the image format.
An example: ['image/xbm', 'image/x-bitmap']

=back

=head1 API

This section describes the parameters accepted and the data returned by
the C<Prima::Image::load> method

=head2 Common

=head3 Loading parameters

=over

=item 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:
L<Prima::Image/premultiply_alpha>.

=item 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. C<Prima::Image> or
C<Prima::Icon>).

=item eventDelay INT

Specifies C<onDataReady> event granularity in seconds, when the codec is
capable of triggering this event.

Default: 0.1

=item iconUnmask BOOL

If set, C<Prima::Icon::autoMasking> is set to C<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 C<Prima::Icon> loading.

=item index INT

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

Default: 0

=item loadExtras BOOL

If set, all available extra information will be stored in the C<extras> hash
on the loaded object.

Default: false

=item loadAll BOOL

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

Default: false

=item map [INT]

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

Default: undef

=item noImageData BOOL

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

Default: false

=item 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 C<truncated> field
contains the error string.

Default: false

=item 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 C<Image::load> and the nth hash in
the array.

=item wantFrames BOOL

Affects how the number of frames in a file is reported in the C<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: L<frames>.

=back

=head3 Load output

=over

=item codecID INT

Indicates the internal codec ID used to load the image. Can be used for C<Image::save>.

=item 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 C<wantFrames> parameter being set).

=item height INT

When the C<noImageData> parameter is set, contains the image height.

=item truncated BOOL

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

=item width INT

When the C<noImageData> parameter is set, contains the image width.

=back

=head3 Saving parameters

=over

=item 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

=item codecID INT

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

Default: undef

=back

=head2 BMP codec

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

=over

=item BitDepth INT

Original bit depth may differ from C<Image::bpp>.

Not valid as a saving parameter.

=item Compression STRING

Bitmap compression method.

Not valid as a saving parameter.

=item HotSpotX, HotSpotY INT

If loading from a cursor file, contains pointer hotspot coordinates

=item ImportantColors INT

The minimal number of colors is needed to display the image

=item OS2 BOOL

Is set when loading an OS/2 bitmap

=item XResolution, YResolution INT

Image resolution in PPM

=back

=head2 X11 codec

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

=over

=item hotSpotX, hotSpotY INT

Contains pointer hotspot coordinates, if any

=back

=head2 XPM codec

=over

=item extensions HASH

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

=item hintsComment, colorsComment, pixelsComment STRING

Contains comments on different sections

=item hotSpotX, hotSpotY INT

Contains the pointer hotspot coordinates

=item transparentColors [COLOR]

An array of transparent colors. Cannot be used for saving.

=back

=head2 JPEG codec

=head3 Load parameters

=over

=item exifTransform none|auto|wipe

If set to C<auto> or C<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 C<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 C<loadExtras> parameter set because exif tags are stored in
extra JPEG data.

=back

=head3 Output fields of the loader and input parameters for the saver

=over

=item appdata [STRING]

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

=item comment STRING

Any comment text found in the file.

=item progressive BOOL

If set, produces a progressively encoded JPEG file.

Default: 0

Only used for saving.

=item quality INT

JPEG quality, 1-100.

Default: 75

Only used for saving.

=back

=head2 PNG codec

=head3 Load input

=over

=item background COLOR

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

Default: clInvalid

Not applicable to C<Prima::Icon>.

=item gamma REAL

Override gamma value applied to the loaded image

Default: 0.45455

=item screen_gamma REAL

Current gamma value for the operating system, if specified.

Default: 2.2

=back

=head3 Load output and save input

=over

=item background COLOR

Default PNG library background color

Default: clInvalid, which means PNG library default

=item blendMethod blend|no_blend|unknown

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

=item delayTime $milliseconds

Delay between frames

=item 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.

=item 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.

=item gamma REAL

Gamma value found in the file.

Default: 0.45455

=item hasAlpha BOOLEAN

If set, the image contains an alpha channel

=item iccp_name, iccp_profile STRING

Embedded ICC color profiles in raw format

Default: C<unspecified> and C<"">.

=item interlaced BOOL

If set, the PNG file is interlaced

Default: 0

=item left INTEGER

The horizontal offset of the frame from the screen

=item loopCount INTEGER

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

=item mng_datastream BOOL

If set, the file contains an MNG datastream

Default: 0

=item 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

=item offset_dimension pixel|micrometer

Offset units

Default: pixel

=item render_intent none|saturation|perceptual|relative|absolute

See the PNG docs ( L<http://www.libpng.org/pub/png/spec/1.1/PNG-Chunks.html>,
4.2.9. sRGB Standard RGB color space).

Default: none

=item resolution_x, resolution_y INT

Image resolution

Default: 0

=item resolution_dimension meter|unknown

Image resolution units

Default: meter

=item scale_x, scale_y

Image scale factors

Default: 1

=item scale_unit meter|radian|unknown

Image scale factor units

Default: unknown

=item screenWidth, screenHeight INTEGER

=item text HASH

Free-text comments found in the file

Default: C<{}>

=item top INTEGER

The vertical offset of the frame from the screen

=item transparency_table [INT]

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

Default value: empty array

=item transparent_color COLOR

One transparent color value for 24-bit PNG images.

Default value: clInvalid (i.e. none)

=item 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.

=back

=head2 TIFF codec

=head3 Load input

=over

=item MinIsWhite BOOL

Automatically invert C<PHOTOMETRIC_MINISWHITE> images

Default: 1

=item Fax BOOL

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

Default: 0

=back

=head3 Load output

=over

=item Photometric STRING

TIFF C<PHOTOMETRIC_XXX> constant. One of:

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

=item BitsPerSample INT

Bits used to represent a single sample, 1-64

=item 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.

=item PlanarConfig contiguous|separate

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

=item SampleFormat STRING

Pixel sample format, one of:

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

=item Tiled BOOL

If set, TIFF is tiled

=item Faxpect BOOL

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

=item 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

=back

=head3 Save input

=over

=item Compression STRING

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

=back

=head3 Load output and save input

=over

=item 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

=item PageNumber, PageNumber2 INT

Default: 1

=item ResolutionUnit inch|centimeter|none

Default: none

=item Software

Default: Prima

=item XPosition, YPosition INT

Default: 0

=item XResolution, YResolution INT

Default: 1200

=back

=head2 GIF codec

For GIF animation see L<Prima::Image::Animate>.

The following load output and save input keys are recognized:

=over

=item comment STRING

GIF comment text

=item delayTime INT

Delay in a hundredth of a second between frames

Default: 1

=item 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

=item interlaced BOOL

If set, the GIF image is interlaced

Default: 0

=item left, top INT

Frame offset in pixels

Default: 0

=item loopCount INT

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

Default: 1

=item screenBackGroundColor COLOR

GIF screen background color

Default: 0

=item screenColorResolution INT

Default: 256

=item screenWidth, screenHeight INT

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

=item screenPalette [INT]

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

=item transparentColorIndex INT

Index of the GIF transparent color

Default: 0

=item userInput INT

User input flag

Default: 0

=back

=head2 WebP codec

=head3 Load output

=over

=item background $ARGB_color

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

=item blendMethod blend|no_blend|unknown

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

=item delayTime $milliseconds

Delay time between frames

=item disposalMethod none|background|unknown

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

=item hasAlpha BOOLEAN

If set, the image contains an alpha channel

=item left INTEGER

The horizontal offset of the frame from the screen

=item loopCount INTEGER

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

=item screenWidth INTEGER

=item screenHeight INTEGER

=item top INTEGER

The vertical offset of the frame from the screen

=back

=head3 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 C<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);

=over

=item background $ARGB_color

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

=item compression lossless (default)|lossy|mixed

=item delay $milliseconds

=item filter_strength INTEGER

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

=item kmax INTEGER

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

=item kmin INTEGER

Max distance between keyframes. The default is 17 for the lossless compression and
5 for the lossy

=item loopCount 0

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

=item method INTEGER

Compression method vs size, 0 (fast) to 6 (slow)

=item minimize_size BOOLEAN

Minimize the output size (off by default)

=item quality INTEGER

Quality factor (0:small..100:big)

=item thread_level BOOLEAN

Use multi-threading if available (off by default)

=back

=head2 HEIF codec

=head3 Load output

=over

=item chroma_bits_per_pixel

=item depth_images

Number of depth images available for the frame

=item has_alpha

=item ispe_height, ispe_width

Original image size before transformations (crop, rotation, etc) are applied

=item is_primary

Set if this is the primary image

=item luma_bits_per_pixel

=item premultiplied_alpha

Is set if the values of the alpha channel are premultiplied

=item thumbnails

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

=item aux

=item metadata

=item thumbnail_of INDEX

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

=back

=head3 Save input

=over

=item quality

Integer, 0-100

=item compression

HEIC,AV1,AVC

=item is_primary

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

=item premultiplied_alpha

Trueset if the values of the alpha channel are premultiplied

=item metadata

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

=item thumbnail_of INDEX

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

=back

=head1 AUTHOR

Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.

=head1 SEE ALSO

L<Prima>, L<Prima::Image>, L<Prima::codecs>
