Prima::...:Loader(3)

✨ NAME ✨

Hey bestie 💖 you're reading Prima::...:Loader(3), a page from the User Contributed Perl Documentation collection. It's the manual for Prima::Image::Loader — progressive loading and saving for multiframe images. Slay.

🌸 DESCRIPTION 🌸

Okay so the toolkit gives you session-based loading and saving for multiframe images, so you do not have to store all image frames in memory at once. Instead, the Prima::Image::Loader and Prima::Image::Saver classes hand you the API for operating on a single frame at a time. Iconic. 🎀

🧚 Prima::Image::Loader

use Prima::Image::Loader;
my $l = Prima::Image::Loader->new($ARGV[0]);
printf "$ARGV[0]: %d frames\n", $l->frames;
while ( !$l->eof ) {
        my ($i,$err) = $l->next;
        die $err unless $i;
        printf "$n: %d x %d\n", $i->size;
}

• new FILENAME|FILEHANDLE, %OPTIONS — Opens a filename or a file handle, tries to deduce if the toolkit can recognize the image, and creates an image loading handler. The %OPTIONS are the same as recognized by load in Prima::Image except map, loadAll, and profiles. The other options apply to each frame that will be consequently loaded, but these options could be overridden by supplying parameters to the next call.

Returns either a new loader object or undef and an error string.

Note that it is possible to supply the onHeaderReady and onDataReady callbacks in the options, however, note that the first arguments in these callbacks will point to the newly created image, not the loader object.

• close — Releases the image file handle. The image can be reopened again by calling reload.
• current INDEX — Manages the index of the frame that will be loaded next. When set, requests repositioning of the frame pointer so that the next call to next would load the INDEXth image.
• eof — Returns the boolean flag if the end of the file is reached.
• extras — Returns the hash of the extra file data as filled by the codec.
• frames — Returns the number of frames in the file.
• next %OPTIONS — Loads the next image frame.

Returns either a newly loaded image or undef and an error string.

• reload — In case an animation file is defective and cannot be loaded in full, the toolkit will not allow to continue the loading session and will close it automatically. If it is desired to work around this limitation, a new session must be opened. The reload method does this by reopening the loading session with all the parameters supplied to the initial new call. The programmer thus has a chance to record how many successful frames were loaded, and only navigate these after the reload.
• rescue BOOLEAN — If set, reopens the input stream or file on every new frame. This may help recover broken frames.
• source — Returns the filename or the file handle passed to the new call.

🦋 Prima::Image::Saver

my $fn = '1.webp';
open F, ">", $fn or die $!;
my ($s,$err) = Prima::Image::Saver->new(\*F, frames => scalar(@images));
die $err unless $s;
for my $image (@images) {
        my ($ok,$err) = $s->save($image);
        next if $ok;
        unlink $fn;
        die $err;
}

• new FILENAME|FILEHANDLE, %OPTIONS — Opens a filename or a file handle. The %OPTIONS are the same as recognized by save in Prima::Image except the images option. The other options apply to each frame that will be consequently saved, but these options could also be overridden by supplying parameters to the save call.

Returns either a new saver object or undef and an error string.

• save %OPTIONS — Saves the next image frame.

Returns a success boolean flag and an eventual error string.

💌 AUTHOR

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

🌈 SEE ALSO

• Prima::Image::Animate — go look, bestie 🦋

---

xoxo 💋 this page comes from perl v5.42.0, dated 2024-08-20, under the Prima::...:Loader(3) manual slot. Bye bestie! 🫶