Provided by: libprima-perl_1.28-1.2_amd64 bug

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

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
       inacceptable 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::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::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 exising 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.

AUTHOR

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

SEE ALSO

       Prima, Prima::Image, Prima::codecs