Image<TPixel> Class

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

An owned, disposable image whose frames store pixels of type TPixel.

public sealed class Image<TPixel> : Image where TPixel : unmanaged

Type parameters

TPixel: The pixel type: Rgba32, Bgra32, Rgb24, Rgba64, Gray8, Gray16, RgbaFloat, RgbaHalf, La16, La32, Rgb48, A8, Argb32, Abgr32, Bgr565 or Rgba1010102. Other unmanaged types are rejected with a NotSupportedException.

Remarks

See Image for the ownership, frame and atomicity contract.

Inheritance: Image Image<TPixel>

Constructors

Name	Description
Image(int, int, ImageConfiguration?)	Initializes a new single-frame still image whose pixels are all zero (transparent black, or black for formats without alpha).
Image(int, int, TPixel, ImageConfiguration?)	Initializes a new single-frame still image filled with the specified pixel value.

Image overloads

Image(int, int, ImageConfiguration?)

Image{TPixel}.cs

Initializes a new single-frame still image whose pixels are all zero (transparent black, or black for formats without alpha).

public Image(int width, int height, ImageConfiguration? configuration = null)

Parameters

width int: The width. Must be positive.
height int: The height. Must be positive.
configuration ImageConfiguration?: The configuration, or null for ImageConfiguration.Default.

Exceptions

NotSupportedException: TPixel is not a built-in pixel struct.
ArgumentOutOfRangeException: width or height is not positive.
ImageResourceLimitException: The image exceeds a configured limit.

Remarks

An image of a floating-point pixel type is labeled as linear light (ColorTransferFunction.Linear).

Image(int, int, TPixel, ImageConfiguration?)

Image{TPixel}.cs

Initializes a new single-frame still image filled with the specified pixel value.

public Image(int width, int height, TPixel fill, ImageConfiguration? configuration = null)

Parameters

width int: The width. Must be positive.
height int: The height. Must be positive.
fill TPixel: The value of every pixel.
configuration ImageConfiguration?: The configuration, or null for ImageConfiguration.Default.

Exceptions

NotSupportedException: TPixel is not a built-in pixel struct.
ArgumentOutOfRangeException: width or height is not positive.
ImageResourceLimitException: The image exceeds a configured limit.

Remarks

An image of a floating-point pixel type is labeled as linear light (ColorTransferFunction.Linear).

Properties

Name	Description
Frames	Gets the typed view of the displayed frames. The frame objects are the same as those of the untyped `Image.Frames`.
PixelFormat	Gets the pixel format shared by every frame.
PosterFrame	Gets the typed poster frame, or `null` if none.

Frames

Image{TPixel}.cs

Gets the typed view of the displayed frames. The frame objects are the same as those of the untyped Image.Frames.

public override ImageFrameCollection<TPixel> Frames { get; }

Gets the pixel format shared by every frame.

public override PixelFormat PixelFormat { get; }

Property value

PixelFormat

PosterFrame

Image{TPixel}.cs

Gets the typed poster frame, or null if none.

public override ImageFrame<TPixel>? PosterFrame { get; }

Property value

ImageFrame<TPixel>?

Exceptions

ObjectDisposedException: The image is disposed.

Methods

Name	Description
AppendFrame()	Appends a new frame whose pixels are all zero (transparent black, or black for formats without alpha) and whose duration is zero.
AppendFrame(ImageFrame)	Appends a copy of a frame. Pixels and frame metadata are copied; the source is not attached.
Clone()	Creates an independent deep copy of the image: frames, poster frame, metadata and animation settings.
CloneFrame(int)	Extracts a copy of one displayed frame as a new single-frame still image. The copy keeps the frame duration and the image-wide metadata, but not the animation settings or the poster frame.
ClonePosterFrame()	Extracts a copy of the poster frame as a new single-frame still image with the image-wide metadata.
InsertFrame(int, ImageFrame)	Inserts a copy of a frame at the specified index. Pixels and frame metadata are copied; the source is not attached.
SetPosterFrame(ImageFrame)	Sets the poster frame to a copy of a frame, replacing (and invalidating) any existing poster frame. Creates default animation settings when none exist.

AppendFrame overloads

AppendFrame()

Image{TPixel}.cs

Appends a new frame whose pixels are all zero (transparent black, or black for formats without alpha) and whose duration is zero.

public override ImageFrame<TPixel> AppendFrame()

Returns

ImageFrame<TPixel> The attached frame.

Exceptions

ImageResourceLimitException: The frame would exceed the configured frame count (displayed frames plus poster) or allocation limit; the image is unchanged.
InvalidOperationException: A pixel lease is active.
ObjectDisposedException: The image is disposed.

AppendFrame(ImageFrame)

Image{TPixel}.cs

Appends a copy of a frame. Pixels and frame metadata are copied; the source is not attached.

public override ImageFrame<TPixel> AppendFrame(ImageFrame source)

Parameters

source ImageFrame: The frame to copy. It must have the canvas size and the pixel format of this image; it may belong to this image.

Returns

ImageFrame<TPixel> The attached copy.

Exceptions

ArgumentException: source has a different size or pixel format. Frames are never resized or converted implicitly.
ImageResourceLimitException: The frame would exceed the configured frame count (displayed frames plus poster) or allocation limit; the image is unchanged.
InvalidOperationException: A pixel lease of the image is active, or the source frame is leased.
ObjectDisposedException: The image or the source is disposed.

Clone()

Image{TPixel}.cs

Creates an independent deep copy of the image: frames, poster frame, metadata and animation settings.

public override Image<TPixel> Clone()

Returns

Image<TPixel> A new image owned by the caller, with its own allocation scope.

Exceptions

ObjectDisposedException: The image is disposed.
ImageResourceLimitException: The copy would exceed the configured allocation limit.

CloneFrame(int)

Image{TPixel}.cs

Extracts a copy of one displayed frame as a new single-frame still image. The copy keeps the frame duration and the image-wide metadata, but not the animation settings or the poster frame.

public override Image<TPixel> CloneFrame(int index)

Parameters

index int: The index of the frame in Image.Frames.

Returns

Image<TPixel> A new image owned by the caller.

Exceptions

ArgumentOutOfRangeException: index is out of range.
ObjectDisposedException: The image is disposed.

ClonePosterFrame()

Image{TPixel}.cs

Extracts a copy of the poster frame as a new single-frame still image with the image-wide metadata.

public override Image<TPixel> ClonePosterFrame()

Returns

Image<TPixel> A new image owned by the caller.

Exceptions

InvalidOperationException: The image has no poster frame.
ObjectDisposedException: The image is disposed.

InsertFrame(int, ImageFrame)

Image{TPixel}.cs

Inserts a copy of a frame at the specified index. Pixels and frame metadata are copied; the source is not attached.

public override ImageFrame<TPixel> InsertFrame(int index, ImageFrame source)

Parameters

index int: The index at which the copy is inserted, from 0 to Frames.Count.
source ImageFrame: The frame to copy. It must have the canvas size and the pixel format of this image; it may belong to this image.

Returns

ImageFrame<TPixel> The attached copy.

Exceptions

ArgumentOutOfRangeException: index is out of range.
ArgumentException: source has a different size or pixel format.
ImageResourceLimitException: The frame would exceed the configured frame count (displayed frames plus poster) or allocation limit; the image is unchanged.
InvalidOperationException: A pixel lease of the image is active, or the source frame is leased.
ObjectDisposedException: The image or the source is disposed.

SetPosterFrame(ImageFrame)

Image{TPixel}.cs

Sets the poster frame to a copy of a frame, replacing (and invalidating) any existing poster frame. Creates default animation settings when none exist.

public override ImageFrame<TPixel> SetPosterFrame(ImageFrame source)

Parameters

source ImageFrame: The frame to copy. It must have the canvas size and the pixel format of this image.

Returns

ImageFrame<TPixel> The attached poster frame.

Exceptions

ArgumentException: source has a different size or pixel format.
ImageResourceLimitException: The frame would exceed the configured frame count (displayed frames plus poster) or allocation limit; the image is unchanged.
InvalidOperationException: A pixel lease of the image is active, or the source frame is leased.
ObjectDisposedException: The image or the source is disposed.