ImageFrame Class

Namespace: Meziantou.Framework.Imaging
Assembly: Meziantou.Framework.Imaging.dll
Package: Meziantou.Framework.Imaging 1.2.11
Source: ImageFrame.cs
Available in package assets: net10.0net11.0

A borrowed view of one full-canvas displayed frame (or of the poster frame) of an Image.

public abstract class ImageFrame

Remarks

Frames are owned by their image and are not disposable. A frame reference becomes invalid when the frame is removed, when the poster frame is replaced, or when the image is disposed; using an invalid reference throws an ObjectDisposedException. Moving frames and geometry operations keep frame identity: a reference keeps designating the same logical frame after a successful resize or reorder.

Pixel access goes through scoped leases (ImageFrame.ProcessPixelBytes, ImageFrame<TPixel>.ProcessPixelRows): the spans handed to a callback are valid only during that callback. While a lease is active, disposing the image, structural edits, storage replacement and conflicting pixel access throw an InvalidOperationException. Rows are contiguous, but the frame as a whole is not guaranteed to be stored contiguously.

Properties

Name	Description
Height	Gets the frame height, in pixels (always the canvas height).
Metadata	Gets the mutable per-frame metadata, such as the display duration and the cursor hotspot.
PixelFormat	Gets the pixel format (always the image pixel format).
Size	Gets the frame size (always the canvas size).
Width	Gets the frame width, in pixels (always the canvas width).

Height

ImageFrame.cs

Gets the frame height, in pixels (always the canvas height).

public int Height { get; }

Property value

int

Metadata

ImageFrame.cs

Gets the mutable per-frame metadata, such as the display duration and the cursor hotspot.

public FrameMetadata Metadata { get; }

Property value

FrameMetadata

Exceptions

ObjectDisposedException: The frame is no longer attached to a live image.

PixelFormat

Gets the pixel format (always the image pixel format).

public abstract PixelFormat PixelFormat { get; }

Property value

PixelFormat

Size

ImageFrame.cs

Gets the frame size (always the canvas size).

public Size Size { get; }

Property value

Size

Exceptions

ObjectDisposedException: The frame is no longer attached to a live image.

Width

ImageFrame.cs

Gets the frame width, in pixels (always the canvas width).

public int Width { get; }

Property value

int

Methods

Name	Description
CopyPixelBytesTo(Span<byte>, int)	Copies the visible pixel bytes to a caller buffer. Bytes between rows (stride padding) are left untouched.
Draw(DrawingAction, CancellationToken)	Draws on this frame only.
Draw<TState>(TState, DrawingAction<TState>, CancellationToken)	Draws on this frame only, passing caller state to avoid closure allocations.
ProcessPixelBytes(PixelBytesAction)	Gives scoped access to the visible pixel bytes, row by row, in the layout of `ImageFrame.PixelFormat` (16-bit components in native endianness).
ProcessPixelBytes<TState>(TState, PixelBytesAction<TState>)	Gives scoped access to the visible pixel bytes, passing caller state to avoid closure allocations.
Save(Stream, ImageEncoder)	Encodes this frame to a stream as a still image, without copying its pixels, starting at the current position of the stream. The stream is left open.
Save(string, ImageEncoder?)	Encodes this frame to a file as a still image, without copying its pixels. The file is written to a temporary file in the same directory and published only after encoding succeeds; on failure an existing file at `path` is left unchanged.
SaveAsync(Stream, ImageEncoder, CancellationToken)	Asynchronously encodes this frame to a stream as a still image, starting at the current position of the stream. The stream is left open.
SaveAsync(string, ImageEncoder?, CancellationToken)	Asynchronously encodes this frame to a file as a still image, with the output and the atomic-publication guarantees of `ImageFrame.Save`.

CopyPixelBytesTo(Span<byte>, int)

ImageFrame.cs

Copies the visible pixel bytes to a caller buffer. Bytes between rows (stride padding) are left untouched.

public void CopyPixelBytesTo(Span<byte> destination, int strideInBytes = 0)

Parameters

destination Span<byte>: The destination buffer.
strideInBytes int: The distance between the starts of two consecutive destination rows, in bytes, or 0 for tightly packed rows. Must be 0 or at least Width * bytesPerPixel.

Exceptions

ArgumentOutOfRangeException: strideInBytes is invalid.
ArgumentException: destination is too short (the last row only needs Width * bytesPerPixel bytes).
InvalidOperationException: A conflicting lease is active.
ObjectDisposedException: The frame is no longer attached to a live image.

Draw overloads

Draw(DrawingAction, CancellationToken)

ImageFrame.cs

Draws on this frame only.

public void Draw(DrawingAction action, CancellationToken cancellationToken = default)

Parameters

action DrawingAction: The callback that draws. It must not be asynchronous and must not retain the canvas.
cancellationToken CancellationToken: The token to monitor for cancellation requests. It is checked by every drawing call.

Exceptions

ArgumentNullException: action is null.
InvalidOperationException: A conflicting lease is active.
ImageResourceLimitException: The working storage would exceed the allocation limit.
OperationCanceledException: The operation was canceled. The shapes already drawn stay, and some rows of the one being drawn may be painted.
ObjectDisposedException: The frame is no longer attached to a live image.

Remarks

The callback runs once, while the pixels of the frame are leased. See DrawingCanvas for the coordinates and the rendering rules, and Image.Draw to draw on every frame of an image.

Draw<TState>(TState, DrawingAction<TState>, CancellationToken)

ImageFrame.cs

Draws on this frame only, passing caller state to avoid closure allocations.

public void Draw<TState>(TState state, DrawingAction<TState> action, CancellationToken cancellationToken = default) where TState : allows ref struct

Type parameters

TState: The type of the state.

Parameters

state TState: The state passed to action.
action DrawingAction<TState>: The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
cancellationToken CancellationToken: The token to monitor for cancellation requests. It is checked by every drawing call.

Exceptions

ArgumentNullException: action is null.
InvalidOperationException: A conflicting lease is active.
ImageResourceLimitException: The working storage would exceed the allocation limit.
OperationCanceledException: The operation was canceled. The shapes already drawn stay, and some rows of the one being drawn may be painted.
ObjectDisposedException: The frame is no longer attached to a live image.

ProcessPixelBytes overloads

ProcessPixelBytes(PixelBytesAction)

ImageFrame.cs

Gives scoped access to the visible pixel bytes, row by row, in the layout of ImageFrame.PixelFormat (16-bit components in native endianness).

public void ProcessPixelBytes(PixelBytesAction action)

Parameters

action PixelBytesAction: The callback. It must not be asynchronous and must not retain the spans.

Exceptions

InvalidOperationException: A conflicting lease is active.
ObjectDisposedException: The frame is no longer attached to a live image.

ProcessPixelBytes<TState>(TState, PixelBytesAction<TState>)

ImageFrame.cs

Gives scoped access to the visible pixel bytes, passing caller state to avoid closure allocations.

public void ProcessPixelBytes<TState>(TState state, PixelBytesAction<TState> action) where TState : allows ref struct

Type parameters

TState: The type of the state.

Parameters

state TState: The state passed to action.
action PixelBytesAction<TState>: The callback. Use a static lambda to avoid allocations. It must not retain the spans.

Exceptions

InvalidOperationException: A conflicting lease is active.
ObjectDisposedException: The frame is no longer attached to a live image.

Save overloads

Save(Stream, ImageEncoder)

ImageFrame.cs

Encodes this frame to a stream as a still image, without copying its pixels, starting at the current position of the stream. The stream is left open.

public void Save(Stream stream, ImageEncoder encoder)

Parameters

stream Stream: The writable destination stream.
encoder ImageEncoder: The encoder. Required, as a stream has no file name to infer the format from.

Exceptions

ArgumentNullException: stream or encoder is null.
ArgumentException: stream is not writable, or not seekable and the output needs to seek (TIFF, ANI, compressed OpenEXR).
UnsupportedImageFeatureException: The frame cannot be encoded without a loss that the encoder settings do not allow.
InvalidOperationException: A pixel lease is active on this frame.
IOException: An I/O error occurred.
ObjectDisposedException: The frame is no longer attached to a live image.

Remarks

The output is the one of ImageFrame.Save.

Save(string, ImageEncoder?)

ImageFrame.cs

Encodes this frame to a file as a still image, without copying its pixels. The file is written to a temporary file in the same directory and published only after encoding succeeds; on failure an existing file at path is left unchanged.

public void Save(string path, ImageEncoder? encoder = null)

Parameters

path string: The destination path.
encoder ImageEncoder?: The encoder, or null to select it from the file extension, as Image.Save does.

Exceptions

ArgumentNullException: path is null.
ArgumentException: path is empty, or encoder is null and the extension is not recognized.
UnsupportedImageFeatureException: The frame cannot be encoded without a loss that the encoder settings do not allow (alpha, precision, metadata, canvas size).
InvalidOperationException: A pixel lease is active on this frame.
IOException: An I/O error occurred.
ObjectDisposedException: The frame is no longer attached to a live image.

Remarks

The output is the one of image.CloneFrame(index).Save(path, encoder) (or of Image.ClonePosterFrame for the poster frame): the pixels and the metadata of this frame (duration, cursor hotspot) with the metadata of its image, and no animation settings and no poster. The rules that prevent a silent loss apply to the frame as they apply to that image: for example, alpha needs JpegEncoder.BackgroundColor to be written to JPEG.

SaveAsync overloads

SaveAsync(Stream, ImageEncoder, CancellationToken)

ImageFrame.cs

Asynchronously encodes this frame to a stream as a still image, starting at the current position of the stream. The stream is left open.

public Task SaveAsync(Stream stream, ImageEncoder encoder, CancellationToken cancellationToken = default)

Parameters

stream Stream: The writable destination stream.
encoder ImageEncoder: The encoder.
cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

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

Exceptions

ArgumentNullException: stream or encoder is null.
ArgumentException: stream is not writable, or not seekable and the output needs to seek.
UnsupportedImageFeatureException: The frame cannot be encoded without a loss that the encoder settings do not allow.
InvalidOperationException: A pixel lease is active on this frame.
OperationCanceledException: The operation was canceled.
ObjectDisposedException: The frame is no longer attached to a live image.

SaveAsync(string, ImageEncoder?, CancellationToken)

ImageFrame.cs

Asynchronously encodes this frame to a file as a still image, with the output and the atomic-publication guarantees of ImageFrame.Save.

public Task SaveAsync(string path, ImageEncoder? encoder = null, CancellationToken cancellationToken = default)

Parameters

path string: The destination path.
encoder ImageEncoder?: The encoder, or null to select it from the file extension.
cancellationToken CancellationToken: The token to monitor for cancellation requests. On cancellation, no file is published.

Returns

Task A task that completes when the file has been published.

Exceptions

ArgumentNullException: path is null.
ArgumentException: path is empty, or encoder is null and the extension is not recognized.
UnsupportedImageFeatureException: The frame cannot be encoded without a loss that the encoder settings do not allow.
InvalidOperationException: A pixel lease is active on this frame.
OperationCanceledException: The operation was canceled.
ObjectDisposedException: The frame is no longer attached to a live image.