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).
open FILE, 'a.jpeg' or die "Cannot open:$!";
binmode FILE;
my $x = Prima::Image-> load( \*FILE);
die "$@" unless $x;
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 => 1
index => 8
map => [0, 10, 15..20]
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.
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.
$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.
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.
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.
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]);
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:$@";
die "$@" if scalar(@images) > Prima::Image-> save( $f,
images => \@images);
$x-> {extras}-> {comments} = 'Created by Prima';
$x-> save( $f);
$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.
When the conversion takes place, Image property 'conversion' is used for selection of an error distribution algorithm, if down-sampling is required.
Codec information that is contained in these hashes is divided into following parameters: