Meziantou.FrameworkCustomImageEncoder Class
The base class of the encoders of the formats the library does not write itself. Pass an encoder to Image.Save and its overloads, or let Image.Save create it from the file extension (CustomImageCodec.CreateEncoder).
public abstract class CustomImageEncoder : ImageEncoderRemarks
The library validates the arguments, opens the destination and, for a path, publishes the file only once CustomImageEncoder.Encode returns (an existing file is left unchanged on failure); the encoder writes the whole image. ImageFrame.Save gives it a still copy of the frame. Sequential writers (ImageWriter<TPixel>) and ImageCollection do not use custom encoders.
ImageEncoder.MetadataHandling and ImageEncoder.FloatingPointConversion are settings the encoder reads itself: the library does not apply them to a custom format. Like the built-in encoders, an encoder must be immutable and thread-safe, and must reject what it cannot write without a loss instead of dropping it (UnsupportedImageFeatureException).
- Inheritance
ImageEncoderCustomImageEncoder
Constructors
| Name | Description |
|---|---|
| CustomImageEncoder(ImageFormatInfo) | Initializes an encoder of a format. |
CustomImageEncoder(ImageFormatInfo)
CustomImageEncoder.csInitializes an encoder of a format.
protected CustomImageEncoder(ImageFormatInfo formatInfo)Parameters
formatInfoImageFormatInfo- The description of the format, created with the public constructor of
ImageFormatInfo.
Exceptions
ArgumentNullExceptionformatInfoisnull.ArgumentExceptionformatInfodescribes a built-in format.
Properties
| Name | Description |
|---|---|
| Format | Gets ImageFormat.Custom. |
| FormatInfo | Gets the description of the format the encoder writes. |
Format
CustomImageEncoder.csFormatInfo
CustomImageEncoder.csGets the description of the format the encoder writes.
public ImageFormatInfo FormatInfo { get; }Property value
Methods
| Name | Description |
|---|---|
| Encode(Image, Stream) | Writes an image. |
| EncodeAsync(Image, Stream, CancellationToken) | Asynchronously writes an image. |
Encode(Image, Stream)
EncodeAsync(Image, Stream, CancellationToken)
CustomImageEncoder.csAsynchronously writes an image.
public virtual ValueTask EncodeAsync(Image image, Stream destination, CancellationToken cancellationToken = default)Parameters
imageImage- The image: its frames, poster frame, animation settings and metadata. It must not be modified.
destinationStream- The writable destination, at the position where the file starts. Do not close it.
cancellationTokenCancellationToken- The token to monitor for cancellation requests.
Returns
ValueTask A task that completes when the image is written.
Remarks
The default implementation calls CustomImageEncoder.Encode, which writes to destination synchronously. Override it when the destination may not support synchronous writes (an HTTP response body).