ImageWriter<TPixel> Class

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

Encodes frames sequentially, keeping only bounded private state between frames.

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

Type parameters

TPixel: The pixel type of the frames written.

Remarks

Create writers with Image.CreateWriter. Write the optional poster frame first (animated PNG only), then the displayed frames in playback order, then call ImageWriter<TPixel>.Complete. Each frame must have the canvas size; its duration is taken from ImageFrame.Metadata. A frame is only borrowed until the write call (or the returned task) completes; the writer never retains caller frames.

ImageWriter<TPixel>.Complete is mandatory: disposing a writer that was not completed aborts the output instead of finalizing it. For path outputs, an aborted or failed writer never replaces an existing destination file. For stream outputs, bytes already written are not removed, but the output is never finalized as a valid file.

A writer supports one operation at a time; overlapping calls throw an InvalidOperationException. Argument validation failures leave the writer usable; any failure after an operation starts faults the writer.

Implements

Properties

Name	Description
CanvasSize	Gets the canvas size of every frame.
Format	Gets the output format.
FramesWritten	Gets the number of displayed frames written so far (excluding the poster frame).

CanvasSize

ImageWriter{TPixel}.cs

Gets the canvas size of every frame.

public Size CanvasSize { get; }

Property value

Size

Format

ImageWriter{TPixel}.cs

Gets the output format.

public ImageFormat Format { get; }

Property value

ImageFormat

FramesWritten

ImageWriter{TPixel}.cs

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

public int FramesWritten { get; }

Property value

int

Methods

Name	Description
Complete()	Verifies that at least one displayed frame (and exactly the expected count, if specified) was written, writes the trailing data and flushes the output. For path outputs, publishes the file. Calling it again after success has no effect.
CompleteAsync(CancellationToken)	Asynchronously completes the output. See `ImageWriter<TPixel>.Complete`.
Dispose()	Releases the writer. If `ImageWriter<TPixel>.Complete` did not succeed, the output is aborted: a path output's temporary file is deleted.
DisposeAsync()	Asynchronously releases the writer, aborting the output if it was not completed.
WriteFrame(ImageFrame<TPixel>)	Writes the next displayed frame.
WriteFrameAsync(ImageFrame<TPixel>, CancellationToken)	Asynchronously writes the next displayed frame.
WritePosterFrame(ImageFrame<TPixel>)	Writes the separate poster frame. Only animated PNG output supports it, and it must be written before the first displayed frame.
WritePosterFrameAsync(ImageFrame<TPixel>, CancellationToken)	Asynchronously writes the separate poster frame.

Complete()

ImageWriter{TPixel}.cs

Verifies that at least one displayed frame (and exactly the expected count, if specified) was written, writes the trailing data and flushes the output. For path outputs, publishes the file. Calling it again after success has no effect.

public void Complete()

Exceptions

InvalidOperationException: No frame was written, the frame count differs from ImageWriterOptions.ExpectedFrameCount, or the writer is faulted.
IOException: An I/O error occurred.
ObjectDisposedException: The writer is disposed.

CompleteAsync(CancellationToken)

ImageWriter{TPixel}.cs

Asynchronously completes the output. See ImageWriter<TPixel>.Complete.

public ValueTask CompleteAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

ValueTask A task that completes when the output is finalized.

Exceptions

InvalidOperationException: No frame was written, the frame count differs from the expected count, or the writer is faulted.
OperationCanceledException: The operation was canceled. The output is not published.

Dispose()

ImageWriter{TPixel}.cs

Releases the writer. If ImageWriter<TPixel>.Complete did not succeed, the output is aborted: a path output's temporary file is deleted.

public void Dispose()

Exceptions

InvalidOperationException: An operation is in progress.

DisposeAsync()

ImageWriter{TPixel}.cs

Asynchronously releases the writer, aborting the output if it was not completed.

public ValueTask DisposeAsync()

Returns

ValueTask A task that completes when the writer is released.

Exceptions

InvalidOperationException: An operation is in progress.

WriteFrame(ImageFrame<TPixel>)

ImageWriter{TPixel}.cs

Writes the next displayed frame.

public void WriteFrame(ImageFrame<TPixel> frame)

Parameters

frame ImageFrame<TPixel>: The frame. Its pixels and duration are encoded; it is not retained.

Exceptions

ArgumentException: frame does not have the canvas size.
InvalidOperationException: The expected frame count was already reached, the format supports a single frame, or the writer is faulted or completed.
UnsupportedImageFeatureException: The frame cannot be encoded without a loss that the encoder settings do not allow.
IOException: An I/O error occurred.
ObjectDisposedException: The writer is disposed.

WriteFrameAsync(ImageFrame<TPixel>, CancellationToken)

ImageWriter{TPixel}.cs

Asynchronously writes the next displayed frame.

public ValueTask WriteFrameAsync(ImageFrame<TPixel> frame, CancellationToken cancellationToken = default)

Parameters

frame ImageFrame<TPixel>: The frame, borrowed until the returned task completes.
cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

ValueTask A task that completes when the frame has been written.

Exceptions

ArgumentException: frame does not have the canvas size.
OperationCanceledException: The operation was canceled. The writer is faulted.

WritePosterFrame(ImageFrame<TPixel>)

ImageWriter{TPixel}.cs

Writes the separate poster frame. Only animated PNG output supports it, and it must be written before the first displayed frame.

public void WritePosterFrame(ImageFrame<TPixel> frame)

Parameters

frame ImageFrame<TPixel>: The poster frame. Its duration is ignored.

Exceptions

ArgumentException: frame does not have the canvas size.
InvalidOperationException: A displayed frame or a poster frame was already written, the output format does not support poster frames, or the writer is faulted or completed.
ObjectDisposedException: The writer is disposed.

WritePosterFrameAsync(ImageFrame<TPixel>, CancellationToken)

ImageWriter{TPixel}.cs

Asynchronously writes the separate poster frame.

public ValueTask WritePosterFrameAsync(ImageFrame<TPixel> frame, CancellationToken cancellationToken = default)

Parameters

frame ImageFrame<TPixel>: The poster frame, borrowed until the returned task completes.
cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

ValueTask A task that completes when the frame has been written.

Exceptions

ArgumentException: frame does not have the canvas size.
OperationCanceledException: The operation was canceled. The writer is faulted.