This file is indexed.

/usr/share/perl5/Prima/image-load.pod is in libprima-perl 1.28-1.2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
=for rcs $Id: image-load.pod,v 1.15 2008/10/25 07:44:48 dk Exp $

=head1 NAME

Prima::image-load - Using image subsystem

=head1 DESCRIPTION

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

=head1 Loading

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

=head2 Loading from stream

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

=head2 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:

=over

=item loadAll

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

        loadAll => 1

=item index

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

        index => 8

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

=back

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


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

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

=head2 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, C<iconUnmask> boolean option can be used. When set
to a C<true> value, and the object is C<Prima::Icon> descendant,
C<Prima::Icon::autoMasking> is set to C<am::None> prior to the
file loading. By default this options is turned off.

=head2 Loading with progress indicator

Some codecs (PNG,TIFF,JPEG) can notify the caller as they read image data.  For
this purpose, C<Prima::Image> has two events, C<onHeaderReady> and
C<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.
C<onHeaderReady> is called when image header data is acquired, and empty image
with the dimensions and pixel type is allocated. C<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

C<onHeaderReady> is called only once, but C<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, C<load> has parameter C<eventDelay>,
a number of seconds, which limits event rate. The default C<eventDelay> is 0.1 .

The handling on C<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 C<onHeaderReady> and C<onDataReady>. The simpler is to
call C<put_image> from inside C<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 C<Prima::ImageViewer> when it is setup to monitor
image loading progress. See L<Prima::ImageViewer/watch_load_progress> for details.

=head1 Saving

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

=head2 Saving to a stream

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

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

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

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

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

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

=head1 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:

=over

=item codecID 

Unique integer value for a codec, same as index of the codec entry in
results of C<< Prima::Image->codecs >>;

=item name

codec full name, string

=item vendor

codec vendor, string

=item versionMajor and versionMinor

usually underlying library versions, integers

=item fileExtensions

array of strings, with file extensions that are typical to a codec.
example: ['tif', 'tiff']

=item fileType

Description of a type of a file, that codec is designed to work with.
String.

=item fileShortType

Short description of a type of a file, that codec is designed to work with.
( short means 3-4 characters ). String.

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

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

=item canLoad

1 if a codec can load images, 0 if not

=item canLoadStream

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

=item canLoadMultiple

1 if a codec can handle multiframe load requests and load frames with
index more than zero. 0 if not.

=item canSave

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

=item canSaveStream

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

=item canSaveMultiple

Set if a codec can save more that one frame

=item canAppend

Set if a codec can append frames to an exising file

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

=item loadInput

Hash, where keys are those that are accepted by Prima::Image-> load,
and values are default values for these keys.

=item loadOutput

Array of strings, each of those is a name of extra information entry 
in 'extras' hash.

=item saveInput

Hash, where keys are those that are accepted by Prima::Image-> save,
and values are default values for these keys.


=back

=head1 AUTHOR

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

=head1 SEE ALSO

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