Repository navigation
Frame-by-frame reading and writing for plugin formats
Format plugins can now supply a frame reader and a frame writer. Image.OpenFrameReaderAsync and
Image.CreateFrameWriter then work for their formats exactly as for GIF, PNG/APNG and WebP: frames are read forward
one at a time, Current is borrowed, limits and cancellation apply to every frame, and incomplete path output is
deleted. A long animation no longer has to be loaded whole with Image.Load.
using PictureSharp;
// With a plugin that implements IImageFormatModule.FrameDecoder, for example a future PictureSharp.Jxl.
await using ImageFrameReader reader = await Image.OpenFrameReaderAsync("animation.jxl");
await foreach (ImageFrame frame in reader.ReadFramesAsync())
{
Console.WriteLine($"{frame.Duration.TotalMilliseconds} ms");
}MaxPixels now limits one canvas in every frame reader, built-in formats included: a reader holds only a few
canvases however long the animation is, so summing all frames rejected long animations that fit in memory easily.
MaxFrames, MaxInputBytes and MaxMetadataBytes still apply to the whole sequence, and Image.Load still sums the
pixels of all frames. To cap a reader's total work, set MaxFrames.
The plugin change is additive. Plugins built for 0.9.0 keep working, and their formats still report
NotSupportedException from the frame reader and writer until they implement the new members.
For plugin authors
IImageFormatModulegainsFrameDecoderandFrameEncoder, both with a default of null. A frame decoder requires
Decoder, and a frame encoder requiresEncoder, which still writes a sequence declared as a single frame.- New types in
PictureSharp.Formats:IImageFormatFrameDecoder,ImageFrameSource,ImageFrameDecodeContext,
IImageFormatFrameEncoder,ImageFrameSinkandImageFrameSequenceInfo. - The library keeps every cross-format check: frame size, pixel type, ownership, the declared frame count,
MaxPixels
for the canvas,MaxFrames,MaxInputBytes,FirstFrameOnlyand error mapping. Truncated input
(EndOfStreamException) is reported asImageFormatException. Writers get options validation before the file is created, temporary files for
sinks that need to seek, and 8-bit copies of frames the sink does not accept. - These types are new and not yet in the stable plugin SPI. They join it
once a released plugin uses them. A plugin that implements them requires PictureSharp 0.9.1. Plugins that do not
can keep 0.9.0 as their minimum.
See reading and writing frame by frame for an
example and the full contract.
Verification
The x64 Release suite passes: 9428 tests passed, 8 Windows-only tests skipped, including all reference-tool tests.
Package consumers pass full trimming and Native AOT checks for the core, a plugin frame reader and writer, and the
adapters. No SIMD code changed, so the 0.9.0 ARM64 results still apply.