ImageReader<TPixel> Class

Namespace: Meziantou.Framework.Imaging
Assembly: Meziantou.Framework.Imaging.dll
Package: Meziantou.Framework.Imaging 1.2.11
Source: ImageReader{TPixel}.cs
Available in package assets: net10.0net11.0

Decodes the displayed frames of an image sequentially, with memory bounded by one frame of compositor state.

public sealed class ImageReader<TPixel> : IAsyncDisposable, IDisposable where TPixel : unmanaged

Type parameters

TPixel: The pixel type of the frames returned by the reader.

Remarks

Create readers with Image.OpenReader. Frames are produced in playback order as complete full-canvas displayed images; the reader resolves encoded delta rectangles, blending and disposal internally, and its compositor state is independent of anything the caller does with returned images.

Images returned by ImageReader<TPixel>.ReadFrame and ImageReader<TPixel>.ReadPosterFrame are single-frame still images owned by the caller: they keep the frame duration and image-wide metadata, but not the animation-wide settings, which are exposed by ImageReader<TPixel>.Info. They remain valid after the reader is disposed and stay charged to the reader's allocation scope until they are disposed.

A reader supports one operation at a time; overlapping calls throw an InvalidOperationException. Argument validation failures leave the reader usable. Any other failure (malformed data, limit, I/O error, cancellation) after an operation starts faults the reader: subsequent calls throw an InvalidOperationException. A null or false result always means a clean end of input, never an error.

Implements

Properties

Name	Description
FramesRead	Gets the number of displayed frames read so far (excluding the poster frame).
Info	Gets the information read from the header: format, canvas size, frame count when known, animation settings and image-wide metadata found before the first frame. The snapshot does not change as frames are read.

FramesRead

ImageReader{TPixel}.cs

Gets the number of displayed frames read so far (excluding the poster frame).

public int FramesRead { get; }

Property value

int

Info

ImageReader{TPixel}.cs

Gets the information read from the header: format, canvas size, frame count when known, animation settings and image-wide metadata found before the first frame. The snapshot does not change as frames are read.

public ImageInfo Info { get; }

Property value

ImageInfo

Methods

Name	Description
Dispose()	Releases the reader and its compositor state, and closes the input when owned. Images already returned remain valid.
DisposeAsync()	Asynchronously releases the reader and closes the input when owned. Images already returned remain valid.
ReadFrame()	Reads the next displayed frame as a new image.
ReadFrameAsync(CancellationToken)	Asynchronously reads the next displayed frame as a new image.
ReadFrameInto(Image<TPixel>)	Reads the next displayed frame into an existing image, reusing its pixel storage. The destination's frame duration and image-wide metadata are replaced by those of the decoded frame.
ReadFrameIntoAsync(Image<TPixel>, CancellationToken)	Asynchronously reads the next displayed frame into an existing image, reusing its pixel storage.
ReadFrameRefinementInto(Image<TPixel>)	Reads the next rendering of the current displayed frame into an existing image: an intermediate rendering, when the format stores the frame at increasing levels of detail and the part that was read allows one, otherwise the frame.
ReadFrameRefinementIntoAsync(Image<TPixel>, CancellationToken)	Asynchronously reads the next rendering of the current displayed frame into an existing image (see `ImageReader<TPixel>.ReadFrameRefinementInto`).
ReadPosterFrame()	Reads the separate poster frame, if the input has one. Must be called before the first displayed frame is read; it can be called at most once. Skipping it is allowed: the poster frame is then discarded.
ReadPosterFrameAsync(CancellationToken)	Asynchronously reads the separate poster frame, if the input has one.

Dispose()

ImageReader{TPixel}.cs

Releases the reader and its compositor state, and closes the input when owned. Images already returned remain valid.

public void Dispose()

Exceptions

InvalidOperationException: An operation is in progress.

DisposeAsync()

ImageReader{TPixel}.cs

Asynchronously releases the reader and closes the input when owned. Images already returned remain valid.

public ValueTask DisposeAsync()

Returns

ValueTask A task that completes when the reader is released.

Exceptions

InvalidOperationException: An operation is in progress.

ReadFrame()

ImageReader{TPixel}.cs

Reads the next displayed frame as a new image.

public Image<TPixel>? ReadFrame()

Returns

Image<TPixel>? A new single-frame image owned by the caller, or null at the clean end of input (or once ImageReaderOptions.FrameLimit frames were read).

Exceptions

InvalidOperationException: Another operation is in progress or the reader is faulted.
InvalidImageContentException: The data is malformed or truncated.
UnsupportedImageFeatureException: The frame uses an unsupported feature, or the conversion to TPixel would drop information without an explicit policy.
ImageResourceLimitException: A configured limit is exceeded.
IOException: An I/O error occurred.
ObjectDisposedException: The reader is disposed.

ReadFrameAsync(CancellationToken)

ImageReader{TPixel}.cs

Asynchronously reads the next displayed frame as a new image.

net10.0

public ValueTask<Image<TPixel>?> ReadFrameAsync(CancellationToken cancellationToken = default)

net11.0

public ValueTask<Image<TPixel>?> ReadFrameAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

ValueTask<Image<TPixel>?> A new single-frame image owned by the caller, or null at the clean end of input.

Exceptions

InvalidOperationException: Another operation is in progress or the reader is faulted.
OperationCanceledException: The operation was canceled. The reader is faulted.

ReadFrameInto(Image<TPixel>)

ImageReader{TPixel}.cs

Reads the next displayed frame into an existing image, reusing its pixel storage. The destination's frame duration and image-wide metadata are replaced by those of the decoded frame.

public bool ReadFrameInto(Image<TPixel> destination)

Parameters

destination Image<TPixel>: A single-frame still image with the canvas size: exactly one frame, no poster frame and no animation settings. It stays charged to its own allocation scope.

Returns

bool true if a frame was read; false at the clean end of input, in which case the destination is unchanged.

Exceptions

ArgumentException: destination does not have the canvas size, has several frames, a poster frame, or animation settings.
InvalidOperationException: Another operation is in progress, the reader is faulted, or a lease is active on the destination.
InvalidImageContentException: The data is malformed or truncated. The destination may be partially updated but remains valid.
UnsupportedImageFeatureException: The frame uses an unsupported feature. A feature that is only declared after the pixels (premultiplied alpha in a TGA trailer) is reported once the rows were written: the destination may be updated but remains valid.
ImageResourceLimitException: A configured limit is exceeded.
ObjectDisposedException: The reader or the destination is disposed.

ReadFrameIntoAsync(Image<TPixel>, CancellationToken)

ImageReader{TPixel}.cs

Asynchronously reads the next displayed frame into an existing image, reusing its pixel storage.

public ValueTask<bool> ReadFrameIntoAsync(Image<TPixel> destination, CancellationToken cancellationToken = default)

Parameters

destination Image<TPixel>: A single-frame still image with the canvas size.
cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

ValueTask<bool> true if a frame was read; false at the clean end of input.

Exceptions

ArgumentException: destination is not a compatible single-frame still image.
OperationCanceledException: The operation was canceled. The reader is faulted; the destination may be partially updated but remains valid.

ReadFrameRefinementInto(Image<TPixel>)

ImageReader{TPixel}.cs

Reads the next rendering of the current displayed frame into an existing image: an intermediate rendering, when the format stores the frame at increasing levels of detail and the part that was read allows one, otherwise the frame.

public FrameRefinement? ReadFrameRefinementInto(Image<TPixel> destination)

Parameters

destination Image<TPixel>: A single-frame still image with the canvas size. Every rendering is a full image at the size of the frame; its metadata are replaced like ImageReader<TPixel>.ReadFrameInto replaces them.

Returns

FrameRefinement? What was written to the destination, or null at the clean end of input, in which case the destination is unchanged. After a rendering whose FrameRefinement.IsFinal is set, the next read starts the next frame.

Exceptions

ArgumentException: destination does not have the canvas size, has several frames, a poster frame, or animation settings.
InvalidOperationException: Another operation is in progress, the reader is faulted, or a lease is active on the destination.
InvalidImageContentException: The data is malformed or truncated. The destination may be partially updated but remains valid.
UnsupportedImageFeatureException: The frame uses an unsupported feature.
ImageResourceLimitException: A configured limit is exceeded.
ObjectDisposedException: The reader or the destination is disposed.

Remarks

Call the method until it returns a final rendering to show an image while its data arrive: a progressive JPEG XL frame gives the image at one eighth of its detail, then one rendering for each of its passes, then the frame; a progressive JPEG frame gives one rendering after each scan once every component has its DC coefficients; an interlaced PNG image gives the Adam7 passes completed so far, every other pixel taking the value of the pixel of its block in them. Other formats, and frames that are not progressive, give the frame at once. ImageReader<TPixel>.ReadFrame and ImageReader<TPixel>.ReadFrameInto may be called at any time: they read the frame itself. The destination may change between two reads.

An input that ends before the frame is complete is malformed: the renderings that were returned stay valid. The read that reaches the end of the input returns a last intermediate rendering of what was decoded, when the format allows it (the rows decoded so far of a GIF image, of a PNG image that is not interlaced, of a JPEG frame coded in one scan and of a still lossy WebP image, the other rows being zero; the passes of an interlaced PNG image; the coefficients of a progressive JPEG frame), and the next read throws InvalidImageContentException; otherwise that read throws. The renderings of the passes and the scans of a frame count toward ImageResourceLimits.MaxTotalPixels.

ReadFrameRefinementIntoAsync(Image<TPixel>, CancellationToken)

ImageReader{TPixel}.cs

Asynchronously reads the next rendering of the current displayed frame into an existing image (see ImageReader<TPixel>.ReadFrameRefinementInto).

public ValueTask<FrameRefinement?> ReadFrameRefinementIntoAsync(Image<TPixel> destination, CancellationToken cancellationToken = default)

Parameters

destination Image<TPixel>: A single-frame still image with the canvas size.
cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

ValueTask<FrameRefinement?> What was written to the destination, or null at the clean end of input.

Exceptions

ArgumentException: destination is not a compatible single-frame still image.
OperationCanceledException: The operation was canceled. The reader is faulted; the destination may be partially updated but remains valid.

ReadPosterFrame()

ImageReader{TPixel}.cs

Reads the separate poster frame, if the input has one. Must be called before the first displayed frame is read; it can be called at most once. Skipping it is allowed: the poster frame is then discarded.

public Image<TPixel>? ReadPosterFrame()

Returns

Image<TPixel>? A new single-frame image owned by the caller, or null if the input has no poster frame.

Exceptions

InvalidOperationException: A displayed frame was already read, the poster frame was already read, or the reader is faulted.
InvalidImageContentException: The data is malformed or truncated.
ImageResourceLimitException: A configured limit is exceeded.
ObjectDisposedException: The reader is disposed.

ReadPosterFrameAsync(CancellationToken)

ImageReader{TPixel}.cs

Asynchronously reads the separate poster frame, if the input has one.

net10.0

public ValueTask<Image<TPixel>?> ReadPosterFrameAsync(CancellationToken cancellationToken = default)

net11.0

public ValueTask<Image<TPixel>?> ReadPosterFrameAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

ValueTask<Image<TPixel>?> A new single-frame image owned by the caller, or null if the input has no poster frame.

Exceptions

InvalidOperationException: A displayed frame was already read, the poster frame was already read, or the reader is faulted.
OperationCanceledException: The operation was canceled. The reader is faulted.