1=head1 NAME 2 3Prima::image-load - Using image subsystem 4 5=head1 DESCRIPTION 6 7Details on image subsystem - image loading, saving, and codec managements 8 9=head1 Loading 10 11=head2 Simple loading 12 13Simplest case, loading a single image would look like: 14 15 my $x = Prima::Image-> load( 'filename.duf'); 16 die "$@" unless $x; 17 18Image functions can work being either invoked from package, 19or from existing Prima::Image object, in latter case the caller 20object itself is changing. The code above could be also written as 21 22 my $x = Prima::Image-> create; 23 die "$@" unless $x-> load( 'filename.duf'); 24 25In both cases $x contains image data upon success. 26Error is returned into $@ variable ( see perldoc perlvar for more info). 27 28=head2 Loading from stream 29 30C<Prima::Image> can also load image by reading from a stream: 31 32 open FILE, 'a.jpeg' or die "Cannot open:$!"; 33 binmode FILE; 34 my $x = Prima::Image-> load( \*FILE); 35 die "$@" unless $x; 36 37=head2 Multiframe loading 38 39Multiframe load call can be also issued in two ways: 40 41 42 my @x = Prima::Image-> load( 'filename.duf', loadAll => 1); 43 die "$@" unless $x[-1]; 44 45 my $x = Prima::Image-> create; 46 my @x = $x-> load( 'filename.duf', loadAll => 1); 47 die "$@" unless $x[-1]; 48 49In second case, the content of the first frame comes to $x and $x[0]. 50Sufficient check for error is whether last item of a returned 51array is defined. This check works also if an empty array is returned. 52Only this last item can be an undefined value, others are guaranteed 53to be valid objects. 54 55Multiframe syntax is expressed in a set of extra hash keys. 56These keys are: 57 58=over 59 60=item loadAll 61 62Request for loading all frames that can be read from a file. 63Example: 64 65 loadAll => 1 66 67=item index 68 69If present, returns a single frame with index given. 70Example: 71 72 index => 8 73 74=item map 75 76Contains an anonymous array of frame indices to load. 77Valid indices are above zero, negative ones can't be counted in a way 78perl array indices are. Example: 79 80 map => [0, 10, 15..20] 81 82=back 83 84=head2 Querying extra information 85 86By default Prima loads image data and palette only. For any other information 87that can be loaded, anonymous hash 'extras' can be defined. To notify a codec 88that this extra information is desired, loadExtras boolean value is used. 89Example: 90 91 my $x = Prima::Image-> load( $f, loadExtras => 1); 92 die "$@" unless $x; 93 for ( keys %{$x-> {extras}}) { 94 print " $_ : $x->{extras}->{$_}\n"; 95 } 96 97The code above loads and prints extra information read from a file. 98Typical output, for example, from a gif codec based on libgif would look 99like: 100 101 codecID : 1 102 transparentColorIndex : 1 103 comment : created by GIMP 104 frames : 18 105 106'codecID' is a Prima-defined extra field, which is an index of the codec 107which have loaded the file. This field's value is useful for explicit 108indication of codec on the save request. 109 110'frames' is also a Prima-defined extra field, with integer value set to 111a number of frames in the image. It might be set to -1, 112signaling that codec is incapable of quick reading of the frame count. 113If, however, it is necessary to get actual frame count, a 'wantFrames' 114profile boolean value should be set to 1 - then frames is guaranteed to 115be set to a 0 or positive value, but the request may take longer time, especially 116on a large file with sequential access. Real life example is a gif file 117with more than thousand frames. 'wantFrames' is useful in null load requests. 118 119 120=head2 Multiprofile loading requests 121 122The parameters that are accepted by load, are divided into several 123categories - first, those that apply to all loading process and those 124who apply only to a particular frame. Those who are defined by Prima, are 125enumerated above - loadExtras, loadAll etc. Only loadExtras, noImageData, 126noIncomplete and iconUnmask are applicable to 127a frame, other govern the loading process. A codec may as well define its own 128parameters, however it is not possible to tell what parameter belongs to what 129group - this information is to be found in codec documentation; 130 131The parameters that applicable to any frame, can be specified separately to 132every desirable frame in single call. For that purpose, parameter 'profiles' 133is defined. 'profiles' is expected to be an anonymous array of hashes, each 134hash where corresponds to a request number. Example: 135 136 $x-> load( $f, loadAll => 1, profiles => [ 137 {loadExtras => 0}, 138 {loadExtras => 1}, 139 ]); 140 141First hash there applies to frame index 0, second - to frame index 1. 142Note that in code 143 144 $x-> load( $f, 145 map => [ 5, 10], 146 profiles => [ 147 {loadExtras => 0}, 148 {loadExtras => 1}, 149 ]); 150 151first hash applies to frame index 5, and second - to frame index 10. 152 153=head2 Null load requests 154 155If it is desired to peek into image, reading type and dimensions only, one 156should set 'noImageData' boolean value to 1. Using 'noImageData', empty 157objects with read type are returned, and with extras 'width' and 'height' 158set to image dimensions. Example: 159 160 $x-> load( $f, noImageData => 1); 161 die "$@" unless $x; 162 print $x-> {extras}-> {width} , 'x' , $x-> {extras}-> {height}, 'x', 163 $x-> type & im::BPP, "\n"; 164 165Some information about image can be loaded even without frame loading - if the 166codec provides such a functionality. This is the only request that cannot be issued 167on a package: 168 169 $x-> load( $f, map => [], loadExtras => 1); 170 171Since no frames are required to load, an empty array is returned 172upon success and an array with one undefined value on failure. 173 174=head2 Using Prima::Image descendants 175 176If Prima needs to create a storage object, it is by default 177Prima::Image, or a class name of an caller object, or a package 178the request was issued on. This behavior can be altered 179using parameter 'className', which defines the class to be used 180for the frame. 181 182 my @x = Prima::Image-> load( $f, 183 map => [ 1..3], 184 className => 'Prima::Icon', 185 profiles => [ 186 {}, 187 { className => 'Prima::Image' }, 188 {} 189 ], 190 191In this example @x will be ( Icon, Image, Icon) upon success. 192 193When loading to an Icon object, the default toolkit action is 194to build the transparency mask based on image data. When it is 195not the desired behavior, e.g., there is no explicit knowledge 196of image, but the image may or may not contain transparency 197information, C<iconUnmask> boolean option can be used. When set 198to a C<true> value, and the object is C<Prima::Icon> descendant, 199C<Prima::Icon::autoMasking> is set to C<am::None> prior to the 200file loading. By default this options is turned off. 201 202=head2 Loading with progress indicator 203 204Some codecs (PNG,TIFF,JPEG) can notify the caller as they read image data. For 205this purpose, C<Prima::Image> has two events, C<onHeaderReady> and 206C<onDataReady>. If either (or both) are present on image object that is issuing 207load call, and the codec supports progressive loading, these events are called. 208C<onHeaderReady> is called when image header data is acquired, and empty image 209with the dimensions and pixel type is allocated. C<onDataReady> is called 210whenever a part of image is ready and is loaded in the memory of the object; 211the position and dimensions of the loaded area is reported also. The format of 212the events is: 213 214 onHeaderReady $OBJECT 215 onDataReady $OBJECT, $X, $Y, $WIDTH, $HEIGHT 216 217C<onHeaderReady> is called only once, but C<onDataReady> is called as soon as 218new image data is available. To reduce frequency of these calls, that otherwise 219would be issued on every scanline loaded, C<load> has parameter C<eventDelay>, 220a number of seconds, which limits event rate. The default C<eventDelay> is 0.1 . 221 222The handling on C<onDataReady> must be performed with care. First, the image 223must be accessed read-only, which means no transformations with image size and 224type are allowed. Currently there is no protection for such actions ( because 225codec must perform these ), so a crash will most surely issue. 226Second, loading and saving of images is not in general reentrant, and although 227some codecs are reentrant, loading and saving images inside image events is 228not recommended. 229 230There are two techniques to display partial image as it loads. All of these 231share overloading of C<onHeaderReady> and C<onDataReady>. The simpler is to 232call C<put_image> from inside C<onDataReady>: 233 234 $i = Prima::Image-> new( 235 onDataReady => sub { 236 $progress_widget-> put_image( 0, 0, $i); 237 }, 238 ); 239 240but that will most probably loads heavily underlying OS-dependent conversion of 241image data to native display bitmap data. A more smarter, but more complex 242solution is to copy loaded (and only loaded) bits to a preexisting device 243bitmap: 244 245 $i = Prima::Image-> new( 246 onHeaderReady => sub { 247 $bitmap = Prima::DeviceBitmap-> new( 248 width => $i-> width, 249 height => $i-> height, 250 )); 251 }, 252 onDataReady => sub { 253 my ( $i, $x, $y, $w, $h) = @_; 254 $bitmap-> put_image( $x, $y, $i-> extract( $x, $y, $w, $h)); 255 }, 256 ); 257 258The latter technique is used by C<Prima::ImageViewer> when it is setup to monitor 259image loading progress. See L<Prima::ImageViewer/watch_load_progress> for details. 260 261=head2 Truncated files 262 263By default, codecs are not specified whether they would fail on premature end 264of file or omit the error and return truncated image. C<noIncomplete> boolean 265flag tells that a codec must always fail if the image cannot be red in full. It 266is off by default. If indeed the codec detected that the file was incomplete, 267it sets C<truncated> error string in the C<extras> profile, if C<loadExtras> 268was requested. 269 270=head1 Saving 271 272=head2 Simple saving 273 274Typical saving code will be: 275 276 die "$@" unless $x-> save( 'filename.duf'); 277 278Upon a single-frame invocation save returns 1 upon success an 0 on failure. 279Save requests also can be performed with package syntax: 280 281 die "$@" unless Prima::Image-> save( 'filename.duf', 282 images => [ $x]); 283 284=head2 Saving to a stream 285 286Saving to a stream requires explicit C<codecID> to be supplied. When an image 287is loaded with C<loadExtras>, this field is always present on the image object, 288and is an integer that selects image encoding format. 289 290 my @png_id = 291 map { $_-> {codecID} } 292 grep { $_-> {fileShortType} =~ /^png$/i } 293 @{ Prima::Image-> codecs }; 294 die "No png codec installed" unless @png_id; 295 296 open FILE, "> a.png" or die "Cannot save:$!"; 297 binmode FILE; 298 $image-> save( \*FILE, codecID => $png_id[0]) 299 or die "Cannot save:$@"; 300 301=head2 Multiframe saving 302 303In multiframe invocation save returns number of successfully saved frames. 304File is erased though, if error occurred, even after some successfully 305written frames. 306 307 die "$@" if scalar(@images) > Prima::Image-> save( $f, 308 images => \@images); 309 310=head2 Saving extras information 311 312All information, that is found in object hash reference 'extras', is 313assumed to be saved as an extra information. It is a codec's own business 314how it reacts on invalid and/or inacceptable information - but typical behavior is 315that keys that were not recognized by the codec just get ignored, and invalid values 316raise an error. 317 318 $x-> {extras}-> {comments} = 'Created by Prima'; 319 $x-> save( $f); 320 321=head2 Selecting a codec 322 323Extras field 'codecID', the same one that is defined after load requests, 324selects explicitly a codec for an image to handle. If the codec 325selected is incapable of saving an error is returned. Selecting a codec 326is only possible with the object-driven syntax, and this information 327is never extracted from objects but passed to 'images' array instead. 328 329 $x-> {extras}-> {codecID} = 1; 330 $x-> save( $f); 331 332Actual correspondence between codecs and their indices is described latter. 333 334NB - if codecID is not given, codec is selected by the file extension. 335 336=head2 Type conversion 337 338Codecs usually are incapable of saving images in all formats, so Prima 339either converts an image to an appropriate format or signals an error. 340This behavior is governed by profile key 'autoConvert', which is 1 by 341default. 'autoConvert' can be present in image 'extras' structures. 342With autoConvert set it is guaranteed that image will be saved, but original image 343information may be lost. With autoConvert unset, no information will be lost, 344but Prima may signal an error. Therefore general-purpose save routines should 345be planned carefully. As an example the C<Prima::Dialog::ImageDialog::SaveImageDialog> 346code might be useful. 347 348When the conversion takes place, Image property 'conversion' is used 349for selection of an error distribution algorithm, if down-sampling 350is required. 351 352=head2 Appending frames to an existing file 353 354This functionality is under design, but the common outlines are already set. 355Profile key 'append' ( 0 by default ) triggers this behavior - if it is set, 356then an append attempt is made. 357 358=head1 Managing codecs 359 360Prima provides single function, Prima::Image-> codecs, which returns an 361anonymous array of hashes, where every hash entry corresponds to a 362registered codec. 'codecID' parameter on load and save requests is actually 363an index in this array. Indexes for a codecs registered once never change, 364so it is safe to manipulate these numbers within single program run. 365 366Codec information that is contained in these hashes is divided into 367following parameters: 368 369=over 370 371=item codecID 372 373Unique integer value for a codec, same as index of the codec entry in 374results of C<< Prima::Image->codecs >>; 375 376=item name 377 378codec full name, string 379 380=item vendor 381 382codec vendor, string 383 384=item versionMajor and versionMinor 385 386usually underlying library versions, integers 387 388=item fileExtensions 389 390array of strings, with file extensions that are typical to a codec. 391example: ['tif', 'tiff'] 392 393=item fileType 394 395Description of a type of a file, that codec is designed to work with. 396String. 397 398=item fileShortType 399 400Short description of a type of a file, that codec is designed to work with. 401( short means 3-4 characters ). String. 402 403=item featuresSupported 404 405Array of strings, with some features description that a codec supports - 406usually codecs implement only a part of file format specification, so it is 407always interesting to know, what part it is. 408 409=item module and package 410 411Specify a perl module, usually inside Prima/Image directory into Prima distribution, 412and a package inside the module. The package contains some specific functions 413for work with codec-specific parameters. Current implementation defines 414only ::save_dialog() function, that returns a dialog that allows to change 415these parameters. See C<Prima::Dialog::ImageDialog::SaveImageDialog> for details. 416Strings, undefined if empty. 417 418=item canLoad 419 4201 if a codec can load images, 0 if not 421 422=item canLoadStream 423 4241 if a codec can load images from streams, 0 otherwise 425 426=item canLoadMultiple 427 4281 if a codec can handle multiframe load requests and load frames with 429index more than zero. 0 if not. 430 431=item canSave 432 4331 if a codec can save images, 0 if not. 434 435=item canSaveStream 436 4371 if a codec can save images to streams, 0 otherwise 438 439=item canSaveMultiple 440 441Set if a codec can save more that one frame 442 443=item canAppend 444 445Set if a codec can append frames to an exising file 446 447=item types 448 449Array of integers - each is a combination of im:: flags, an image type, 450which a codec is capable of saving. First type in list is a default one; 451if image type that to be saved is not in that list, the image will be 452converted to this default type. 453 454=item loadInput 455 456Hash, where keys are those that are accepted by Prima::Image-> load, 457and values are default values for these keys. 458 459=item loadOutput 460 461Array of strings, each of those is a name of extra information entry 462in 'extras' hash. 463 464=item saveInput 465 466Hash, where keys are those that are accepted by Prima::Image-> save, 467and values are default values for these keys. 468 469=item mime 470 471array of strings, with file extensions that are typical to a codec. 472example: ['image/xbm', 'image/x-bitmap'] 473 474=back 475 476=head1 API 477 478This section describes parameters accepted and data returned by C<Prima::Image::load> 479 480=head2 Common 481 482=head3 Loading parameters 483 484=over 485 486=item blending BOOLEAN = 1 487 488Affects how to treat alpha channel bits, if any. 489 490If set, mixes the alpha channel with background color in case if loading to 491an image, or premultiplies color bits (either data or palette) with alpha, if 492loading to icon. Note that saving back the object will result in different 493image, but the object is ready to be displayed immediately. 494 495If unset, color and eventual alpha bits, if loaded to an icon, will not be 496affected in any way. Note that saving back the object will result in the same 497image, but the object is not ready to be displayed immediately. See also: 498L<Prima::Image/premultiply_alpha>. 499 500=item className STRING 501 502When loading more than one image, this string is used to create 503instances of image containers. By default the calling class is 504used (i.e. C<Prima::Image> or C<Prima::Icon>). 505 506=item eventDelay INT 507 508Specifies C<onDataReady> event granularity in microseconds, if 509image codec is capable of triggering this event. 510 511Default: 100 512 513=item iconUnmask BOOL 514 515If set, C<Prima::Icon::autoMasking> is set to C<am::None> prior to the 516file loading. 517 518Default: false. Only actual for C<Prima::Icon> loading. 519 520=item index INT 521 522When loading from a multiframe file, selects the frame index to load. 523 524Default: 0 525 526=item map [INT] 527 528When loading from a multiframe file, selects set of frame indexes to load. 529 530Default: undef 531 532=item loadExtras BOOL 533 534If set, all available extra information will be stored in C<{extras}> hash 535on the loaded object. 536 537Default: false 538 539=item loadAll BOOL 540 541When loading from a multiframe file, selects that all frames are to be loaded 542 543Default: false 544 545=item noImageData BOOL 546 547When set, neither image data is not loaded, nor image dimensions are changed 548(newly created images have size of 1x1). Instead, C<{extras}> contains C<width> 549and C<height> integers. 550 551Default: false 552 553=item noIncomplete BOOL 554 555Affects the action when image is incomplete, truncated, etc. 556If set, signals an error. Otherwise no error is signalled and whatever 557data could be recovered from the image are returned, and C<truncated> flag 558is set. 559 560Default: false 561 562=item profiles [HASH] 563 564Array of hashes passed down to each frame in multiframe loads. Each 565frame load request will be passed an individual hash, a result of 566hash join of all profiles passed to C<Image::load> and the nth hash 567in the array. 568 569=item wantFrames BOOL 570 571Affects how the number of frames in a file is reported in C<frames> flag. If 572set, always scans the file for exact number. Otherwise it is up to the codec to 573do that. 574 575Default: false 576 577See also: L<frames>. 578 579=back 580 581=head3 Load output 582 583=over 584 585=item codecID INT 586 587Indicates the internal codec ID used to load the image. Can be used for C<Image::save>. 588 589=item frames INT 590 591If set to a positive integer, indicates number of frames in a file. Otherwise 592signals that there are frames, but codec needs an expensive scan to calculate 593the frames (and C<wantFrames> set). 594 595=item height INT 596 597When C<noImageData> is in action, contains image height. 598 599=item truncated BOOL 600 601When C<noIncomplete> is in action, is set if image was truncated. 602The value is the error string. 603 604=item width INT 605 606When C<noImageData> is in action, contains image width. 607 608=back 609 610=head3 Saving parameters 611 612=over 613 614=item autoConvert BOOL 615 616Affects the action when image cannot be stored in file format in its existing pixel format. 617If set, the system tries to convert image into a pixel format understood by the selected 618codec. Fails otherwise. 619 620Default: true 621 622=item codecID INT 623 624Overrides codec selection based on filename extension. 625 626Default: undef 627 628=back 629 630=head2 BMP codec 631 632BMP, the bitmap codec is not depended on external libraries and is always available. 633 634=over 635 636=item BitDepth INT 637 638Original bit depth, may differ from C<Image::bpp>. 639 640Not valid as a saving parameter. 641 642=item Compression STRING 643 644Bitmap compressing method. 645 646Not valid as a saving parameter. 647 648=item HotSpotX, HotSpotY INT 649 650If loading from cursor file, contains pointer hotspot coordinates 651 652=item ImportantColors INT 653 654Minimal number of colors needed to display the image 655 656=item OS2 BOOL 657 658Set when loading OS/2 bitmap 659 660=item XResolution, YResolution INT 661 662Image resolution in PPM 663 664=back 665 666=head2 X11 codec 667 668X11, the X Consortium data file codec may depend on external libraries, but is implement 669internally if these are not found, and is thus always available. 670 671=over 672 673=item hotSpotX, hotSpotY INT 674 675Contains pointer hotspot coordinates, if any 676 677=back 678 679=head2 XPM codec 680 681=over 682 683=item extensions HASH 684 685Set of xpm-specific extension strings. Cannot be used for saving. 686 687=item hintsComment, colorsComment, pixelsComment STRING 688 689Contains comments to different sections 690 691=item hotSpotX, hotSpotY INT 692 693Contains pointer hotspot coordinates 694 695=item transparentColors [COLOR] 696 697Array or transparent colors. Cannot be used for saving. 698 699=back 700 701=head2 JPEG codec 702 703=head3 Load parameteres 704 705=over 706 707=item exifTransform none|auto|wipe 708 709If set to C<auto> or C<wipe>, tries to detect whether there is are any exif 710tags hinting that the image has to be rotated and/or mirrored. If found, applies 711the transformation accordingly. 712 713When set to C<wipe>, in addition to that, removes the exif tags so that subsequent 714image save won't result in transformed images with exifs tags still present. 715 716This parameter requires C<loadExtras> flag set, because exif tags are stored in extra JPEG data. 717 718=back 719 720=head3 Load output and save input 721 722=over 723 724=item appdata [STRING] 725 726Array of raw binary strings found in extra JPEG data. 727 728=item comment STRING 729 730Any comment text found in file. 731 732=item progressive BOOL 733 734If set, produces a progressively encoded JPEG file. 735 736Default: 0 737 738Only used for saving. 739 740=item quality INT 741 742JPEG quality, 1-100. 743 744Default: 75 745 746Only used for saving. 747 748=back 749 750=head2 PNG codec 751 752=head3 Load input 753 754=over 755 756=item background COLOR 757 758When PNG file contains alpha channel, and C<alpha> is set to C<blend>, 759this color is used to blend the background. If set to C<clInvalid>, 760default PNG library background color is used. 761 762Default: clInvalid 763 764Not applicable for C<Prima::Icon>. 765 766=item gamma REAL 767 768Override gamma value applied to the loaded image 769 770Default: 0.45455 771 772=item screen_gamma REAL 773 774Current gamma value for the operating system, if specified. 775 776Default: 2.2 777 778=back 779 780=head3 Load output and save input 781 782=over 783 784=item background COLOR 785 786Default PNG library background color 787 788Default: clInvalid, which means PNG library default 789 790=item blendMethod blend|no_blend|unknown 791 792Signals whether the new frame to be blended over 793the existing animation, or replace it. 794 795=item delayTime $milliseconds 796 797Delay time between frames 798 799=item default_frame BOOLEAN 800 801When set, means that the first image is a "default" frame, a special 802backward-compatibility image that is supposed to be excluded from the animation 803sequence, to be displayed only when all animation frames cannot be loaded 804for whatever reason. 805 806=item disposalMethod none|background|restore|unknown 807 808Signals whether the frame, before being replaced, is to be erased by the background 809color, previous frame, or none. 810 811=item gamma REAL 812 813Gamma value found in file. 814 815Default: 0.45455 816 817=item hasAlpha BOOLEAN 818 819If set, image contains alpha channel 820 821=item iccp_name, iccp_profile STRING 822 823Embedded ICC color profiles in raw format 824 825Default: C<unspecified> and C<"">. 826 827=item interlaced BOOL 828 829If set, PNG file is interlaced 830 831Default: 0 832 833=item left INTEGER 834 835Frame horizontal offset from the screen 836 837=item loopCount INTEGER 838 839How many times the animation sequence should run, or 0 for forever. 840 841=item mng_datastream BOOL 842 843If set, file contains a MNG datastream 844 845Default: 0 846 847=item offset_x, offset_y INT 848 849Positive offset from the left edge of the screen to offset_x and the positive 850offset from the left edge of the screen to offset_y 851 852Default: 0 853 854=item offset_dimension pixel|micrometer 855 856Offset units 857 858Default: pixel 859 860=item render_intent none|saturation|perceptual|relative|absolute 861 862See PNG docs. 863 864Default: none 865 866=item resolution_x, resolution_y INT 867 868Image resolution 869 870Default: 0 871 872=item resolution_dimension meter|unknown 873 874Image resolution units 875 876Default: meter 877 878=item scale_x, scale_y 879 880Image scale factors 881 882Default: 1 883 884=item scale_unit meter|radian|unknown 885 886Image scale factor units 887 888Default: unknown 889 890=item screenWidth, screenHeight INTEGER 891 892=item text HASH 893 894Free-text comments found in the file 895 896Default: C<{}> 897 898=item top INTEGER 899 900Frame vertical offset from the screen 901 902=item transparency_table [INT] 903 904When a paletted image contains transparent colors, returns array of palette indexes 905(C<transparency_table>) in 0-255 range, where each number is an alpha value. 906 907Default value: empty array 908 909=item transparent_color COLOR 910 911One transparent color value for 24-bit PNG images. 912 913Default value: clInvalid (i.e. none) 914 915=item transparent_color_index INT 916 917One transparent color value, as palette index for 8- or less- bit PNG images. 918 919Default value: -1 (i.e. none) 920 921Not applicable for load. 922 923=back 924 925=head2 TIFF codec 926 927=head3 Load input 928 929=over 930 931=item MinIsWhite BOOL 932 933Automatically invert C<PHOTOMETRIC_MINISWHITE> images 934 935Default: 1 936 937=item Fax BOOL 938 939If set, converts 1-bit grayscale with ratio 2:1 into 2-bit grayscale (alglorithm also known as I<faxpect>). 940 941Default: 0 942 943=back 944 945=head3 Load output 946 947=over 948 949=item Photometric STRING 950 951TIFF C<PHOTOMETRIC_XXX> constant. One of: 952 953 MinIsWhite 954 MinIsBlack 955 Palette 956 YCbCr 957 RGB 958 LogL 959 LogLUV 960 Separated 961 MASK 962 CIELAB 963 DEPTH 964 Unknown 965 966=item BitsPerSample INT 967 968Bits used to represent a single sample, 1-64 969 970=item SamplesPerPixel INT 971 972Number of samples per pixel, 1-4. F.ex. most images have 1 sample. Planar 973TIFFs may split low and high bytes in 2 samples. RGB has 3 samples, YCbCr and 974RGBA has 4. 975 976=item PlanarConfig contiguous|separate 977 978C<separate> images split individual samples or components (f.ex. R and G and B) 979into individual planes. C<contiguous> mix sample bytes one after another. 980 981=item SampleFormat STRING 982 983Pixel sample format, one of: 984 985 unsigned integer 986 signed integer 987 floating point 988 untyped data 989 complex signed int 990 complex floating point 991 992=item Tiled BOOL 993 994If set, TIFF is tiled 995 996=item Faxpect BOOL 997 998When C<Fax> option set set to C<true>, and indeed the image was converted from 1 to 2 bits, 999this parameter will be set to signal this. 1000 1001=item CompressionType STRING 1002 1003Compression algorithm used for reading TIFF. One of: 1004 1005 NONE 1006 CCITTRLE 1007 CCITTFAX3 1008 CCITTFAX4 1009 LZW 1010 OJPEG 1011 JPEG 1012 NEXT 1013 CCITTRLEW 1014 PACKBITS 1015 THUNDERSCAN 1016 IT8CTPAD 1017 IT8LW 1018 IT8MP 1019 IT8BL 1020 PIXARFILM 1021 PIXARLOG 1022 DEFLATE 1023 ADOBE_DEFLATE 1024 DCS 1025 JBIG 1026 SGILOG 1027 SGILOG24 1028 1029=back 1030 1031=head3 Save input 1032 1033=over 1034 1035=item Compression STRING 1036 1037Same values as in C<CompressionType>. Different names are used 1038to avoid implicit but impossible compression selection, because 1039tibtiff can decompress many types, but compress only a few. 1040 1041=back 1042 1043=head3 Load output and save input 1044 1045=over 1046 1047=item generic strings 1048 1049The following keys have no specific meanings for Prima, but are both recognized 1050for loading and saving: 1051 1052 Artist 1053 Copyright 1054 DateTime 1055 DocumentName 1056 HostComputer 1057 ImageDescription 1058 Make 1059 Model 1060 PageName 1061 PageNumber 1062 PageNumber2 1063 1064=item PageNumber, PageNumber2 INT 1065 1066Default: 1 1067 1068=item ResolutionUnit inch|centimeter|none 1069 1070Default: none 1071 1072=item Software 1073 1074Default: Prima 1075 1076=item XPosition, YPosition INT 1077 1078Default: 0 1079 1080=item XResolution, YResolution INT 1081 1082Default: 1200 1083 1084=back 1085 1086=head2 GIF codec 1087 1088For GIF animation see L<Prima::Image::Animate>. 1089 1090The following load output and save input keys are recognized: 1091 1092=over 1093 1094=item comment STRING 1095 1096GIF comment text 1097 1098=item delayTime INT 1099 1100Delay in hundredth of a second between frames 1101 1102Default: 1 1103 1104=item disposalMethod INT 1105 1106Animation frame disposal method 1107 1108 DISPOSE_NOT_SPECIFIED = 0; # Leave frame, let new frame draw on top 1109 DISPOSE_KEEP = 1; # Leave frame, let new frame draw on top 1110 DISPOSE_CLEAR = 2; # Clear the frame's area, revealing bg 1111 DISPOSE_RESTORE_PREVIOUS = 3; # Restore the previous (composited) frame 1112 1113Default: 0 1114 1115=item interlaced BOOL 1116 1117If set, GIF is interlaced 1118 1119Default: 0 1120 1121=item left, top INT 1122 1123Frame offset in pixels 1124 1125Default: 0 1126 1127=item loopCount INT 1128 1129How many times the GIF animation loops. 0 means indefinite. 1130 1131Default: 1 1132 1133=item screenBackGroundColor COLOR 1134 1135GIF screen background color 1136 1137Default: 0 1138 1139=item screenColorResolution INT 1140 1141Default: 256 1142 1143=item screenWidth, screenHeight INT 1144 1145Default: -1, i.e. use image width and height 1146 1147=item screenPalette [INT] 1148 1149Default: 0,0,0,255,255,255 1150 1151=item transparentColorIndex INT 1152 1153Index of GIF transparent color 1154 1155Default: 0 1156 1157=item userInput INT 1158 1159User input flag 1160 1161Default: 0 1162 1163=back 1164 1165=head2 WebP codec 1166 1167=head3 Load input 1168 1169=over 1170 1171=item background $ARGB_color 1172 1173Integer constant encoded as ARGB, hints the background to be used 1174 1175=item blendMethod blend|no_blend|unknown 1176 1177Signals whether the new frame to be blended over 1178the existing animation, or replace it. 1179 1180=item delayTime $milliseconds 1181 1182Delay time between frames 1183 1184=item disposalMethod none|background|unknown 1185 1186Signals whether the frame, before being replaced, is to be erased by the background 1187color or not. 1188 1189=item hasAlpha BOOLEAN 1190 1191If set, image contains alpha channel 1192 1193=item left INTEGER 1194 1195Frame horizontal offset from the screen 1196 1197=item loopCount INTEGER 1198 1199How many times the animation sequence should run, or 0 for forever. 1200 1201=item screenWidth INTEGER 1202 1203=item screenHeight INTEGER 1204 1205=item top INTEGER 1206 1207Frame vertical offset from the screen 1208 1209=back 1210 1211=head3 Save input 1212 1213WebP requires all images to have same dimensions. Also, saving the webp 1214loading result might fail because loaded frames might only contains parts to be 1215superimposed on each other, while saving requires always full frames. To convert 1216webp loaded frames to something that can be saved later more-or-less 1217identically, use C<Prima::Image::webp::animation_to_frames> converter: 1218 1219 use Prima qw(Image::webp); 1220 my @i = Prima::Icon->load('source.webp', loadAll => 1, loadExtras => 1) or die $@; 1221 @i = Prima::Image::webp::animation_to_frames(@i); 1222 die $@ if @i != Prima::Icon->save('target.webp', images => \@i); 1223 1224=over 1225 1226=item background $ARGB_color 1227 1228Integer constant encoded as ARGB, hints the background to be used 1229 1230=item compression lossless (default)|lossy|mixed 1231 1232=item delay $milliseconds 1233 1234=item filter_strength INTEGER 1235 1236Setting between 0 and 100, 0 means off. 1237 1238=item kmax INTEGER 1239 1240Min distance between key frames. Default is 9 for lossless compression, and 3 for lossy 1241 1242=item kmin INTEGER 1243 1244Max distance between key frames. Default is 17 for lossless compression, and 5 for lossy 1245 1246=item loopCount 0 1247 1248How many times the animation sequence should run, or 0 for forever. 1249 1250=item method INTEGER 1251 1252Compression method vs size, 0 (fast) to 6 (slow) 1253 1254=item minimize_size BOOLEAN 1255 1256Minimize output size (off by default) 1257 1258=item quality INTEGER 1259 1260Quality factor (0:small..100:big) 1261 1262=item thread_level BOOLEAN 1263 1264Use multi-threading if available (off by default) 1265 1266=back 1267 1268=head1 AUTHOR 1269 1270Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>. 1271 1272=head1 SEE ALSO 1273 1274L<Prima>, L<Prima::Image>, L<Prima::codecs> 1275