Meziantou.FrameworkCustomImageCodec Class
The base class of the codecs of the formats the library does not read or write itself. Register a codec in ImageConfiguration.Codecs to detect, identify, load and save its format through the entry points of the built-in formats.
public abstract class CustomImageCodecRemarks
A codec recognizes its files from their first bytes (CustomImageCodec.IsMatch), never from their names. The library reads the whole file, within ImageResourceLimits.MaxEncodedBytes, before it calls CustomImageCodec.Decode or CustomImageCodec.Identify with the bytes: a codec never performs I/O, and the same code serves the span, stream and path overloads, synchronous and asynchronous.
The decoder creates its image with CustomImageDecodeContext.CreateImage, which applies the resource limits of the configuration and charges the pixels to the load, fills its pixels (for example with ImageFrame<TPixel>.ProcessPixelRows) and returns it. The library then applies the frame limit and the pixel type of a typed load (Image.Load), so a codec can always produce the pixel format that holds its samples best.
Throw InvalidImageContentException for malformed data, UnsupportedImageFeatureException for valid data the codec does not support, with ImageFormat.Custom as their format: the library propagates the exceptions of a codec unchanged.
A codec is shared by every operation of its configurations: it must be immutable and thread-safe.
Constructors
| Name | Description |
|---|---|
| CustomImageCodec(ImageFormatInfo) | Initializes a codec of a format. |
CustomImageCodec(ImageFormatInfo)
CustomImageCodec.csInitializes a codec of a format.
protected CustomImageCodec(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 |
|---|---|
| FormatInfo | Gets the description of the format: its name, its media types and its file extensions. |
FormatInfo
CustomImageCodec.csGets the description of the format: its name, its media types and its file extensions.
public ImageFormatInfo FormatInfo { get; }Property value
Methods
| Name | Description |
|---|---|
| CreateEncoder() | Creates the encoder of the format with its default settings, which Image.Save uses for the file extensions of CustomImageCodec.FormatInfo, or null (the default) when the codec only reads the format. |
| CreateImageInfo(Image) | Creates the description of a decoded image of this format. |
| CreateImageInfo(int, int, PixelFormat, int?, ImageMetadata?) | Creates the description of a file of this format from its header. |
| Decode(ReadOnlySpan<byte>, CustomImageDecodeContext) | Decodes a file. |
| Identify(ReadOnlySpan<byte>, CustomImageDecodeContext) | Describes a file without returning its pixels. |
| IsMatch(ReadOnlySpan<byte>) | Determines whether data starts with the signature of the format. |
CreateEncoder()
CustomImageCodec.csCreates the encoder of the format with its default settings, which Image.Save uses for the file extensions of CustomImageCodec.FormatInfo, or null (the default) when the codec only reads the format.
public virtual CustomImageEncoder? CreateEncoder()Returns
CustomImageEncoder? A new encoder, or null.
CreateImageInfo overloads
CreateImageInfo(Image)
CustomImageCodec.csCreates the description of a decoded image of this format.
Parameters
imageImage- The image.
Returns
ImageInfo The description of its size, pixel format, frames, animation settings and metadata.
Exceptions
ArgumentNullExceptionimageisnull.ObjectDisposedExceptionimageis disposed.
CreateImageInfo(int, int, PixelFormat, int?, ImageMetadata?)
CustomImageCodec.csCreates the description of a file of this format from its header.
protected ImageInfo CreateImageInfo(int width, int height, PixelFormat pixelFormat, int? frameCount = 1, ImageMetadata? metadata = null)Parameters
widthint- The width of the image.
heightint- The height of the image.
pixelFormatPixelFormat- The pixel format
CustomImageCodec.Decodeproduces. frameCountint?- The number of displayed frames, or
nullwhen the header does not tell it. metadataImageMetadata?- The metadata of the file, or
nullfor none. The description stores a copy.
Returns
ImageInfo The description, whose ImageInfo.FormatInfo is CustomImageCodec.FormatInfo.
Exceptions
ArgumentOutOfRangeException- A dimension or the frame count is not positive, or
pixelFormatis not defined.
Decode(ReadOnlySpan<byte>, CustomImageDecodeContext)
Decodes a file.
public abstract Image Decode(ReadOnlySpan<byte> data, CustomImageDecodeContext context)Parameters
dataReadOnlySpan<byte>- The whole file.
contextCustomImageDecodeContext- The context of the load: create the image with it.
Returns
Image An image created by CustomImageDecodeContext.CreateImage.
Identify(ReadOnlySpan<byte>, CustomImageDecodeContext)
CustomImageCodec.csDescribes a file without returning its pixels.
public virtual ImageInfo Identify(ReadOnlySpan<byte> data, CustomImageDecodeContext context)Parameters
dataReadOnlySpan<byte>- The whole file.
contextCustomImageDecodeContext- The context of the identification; its
CustomImageDecodeContext.IdentifyModeis set.
Returns
ImageInfo The description, created by CustomImageCodec.CreateImageInfo or CustomImageCodec.CreateImageInfo.
Remarks
The default implementation decodes the file and describes the image (CustomImageCodec.CreateImageInfo). Override it to read the header only.
IsMatch(ReadOnlySpan<byte>)
Determines whether data starts with the signature of the format.
public abstract bool IsMatch(ReadOnlySpan<byte> prefix)Parameters
prefixReadOnlySpan<byte>- The first bytes of the data:
Image.FormatDetectionPrefixLengthbytes, or the whole data when it is shorter (at least 8 bytes: a shorter input is never recognized).
Returns
bool true if the codec reads the data.