Meziantou.FrameworkImageEncoder Class
The base class of the immutable encoder settings accepted by the save and writer APIs.
public abstract class ImageEncoderRemarks
Encoders are immutable and thread-safe; a single instance can be reused for any number of save operations. The set of encoders is closed in this version: there is no codec plug-in interface.
Properties
| Name | Description |
|---|---|
| FloatingPointConversion | Gets the conversion that reduces floating-point pixels (RgbaFloat, RgbaHalf) to 16-bit integer ones (Rgba64) before they are encoded, or null (the default) to reject them. It only applies to the outputs that do not store floating-point samples: every format but OpenEXR and TIFF, and the TIFF settings that cannot (TiffEncoder). OpenExrEncoder always stores them. |
| Format | Gets the format produced by this encoder. |
| MetadataHandling | Gets the policy applied to metadata the format cannot represent. Defaults to MetadataHandling.Strict. |
FloatingPointConversion
ImageEncoder.csGets the conversion that reduces floating-point pixels (RgbaFloat, RgbaHalf) to 16-bit integer ones (Rgba64) before they are encoded, or null (the default) to reject them. It only applies to the outputs that do not store floating-point samples: every format but OpenEXR and TIFF, and the TIFF settings that cannot (TiffEncoder). OpenExrEncoder always stores them.
public PixelConversionOptions? FloatingPointConversion { get; init; }Property value
Remarks
The reduction is the one of Image.CloneAs with these options: samples that are not numbers are rejected, and samples outside [0, 1] are rejected unless PixelConversionOptions.OutOfRangeSamples clips them or PixelConversionOptions.ToneMapping compresses the highlights first. The peak of the tone mapping of an eager save is the one of all its frames; a sequential writer takes the one of each frame, unless the options give it. The reduced pixels are then encoded like any Rgba64 pixels, with the rules of the encoder (an 8-bit format also needs its AllowBitDepthReduction), and the labels of the image (such as ColorTransferFunction.Linear) follow ImageEncoder.MetadataHandling.
Every frame is reduced before it is encoded, in memory charged to the writer: an eager save holds the reduced copy of all of its frames.
Format
MetadataHandling
ImageEncoder.csGets the policy applied to metadata the format cannot represent. Defaults to MetadataHandling.Strict.
public MetadataHandling MetadataHandling { get; init; }Methods
| Name | Description |
|---|---|
| Create(ImageFormat) | Creates the encoder of a format with its default settings. |
| FromFileExtension(string) | Creates the encoder a file extension selects: the one Save(path) uses when no encoder is given. |
Create(ImageFormat)
ImageEncoder.csCreates the encoder of a format with its default settings.
public static ImageEncoder Create(ImageFormat format)Parameters
formatImageFormat- The format to write.
Returns
ImageEncoder A new encoder whose ImageEncoder.Format is format, such as a PngEncoder for ImageFormat.Png. ImageFormat.Ico and ImageFormat.Cur both give an IcoEncoder, of the matching IcoEncoder.Kind.
Exceptions
ArgumentOutOfRangeExceptionformatisImageFormat.Unknownor not a defined value.
Remarks
This method is thread-safe. To change a setting, create the encoder type directly with an object initializer.
FromFileExtension(string)
ImageEncoder.csCreates the encoder a file extension selects: the one Save(path) uses when no encoder is given.
public static ImageEncoder FromFileExtension(string extension)Parameters
extensionstring- The extension, with or without its leading period (
.pngorpng), compared without regard to ASCII case. A path is not an extension: usePath.GetExtensionfirst.
Returns
ImageEncoder The default encoder of the format of the extension (ImageEncoder.Create), with the settings of the variant some extensions name: .apng gives an animated PngEncoder (PngAnimationMode.Animated), .pbm a PnmEncoder of PnmPixelLayout.Bitmap pixels, .j2k, .j2c and .jpc a Jpeg2000Encoder of a bare codestream (Jpeg2000Container.Codestream), and .jph and .jhc a Jpeg2000Encoder of the high-throughput block coder (Jpeg2000BlockCoder.HighThroughput), which writes a JPH file or a bare codestream.
Exceptions
ArgumentNullExceptionextensionisnull.ArgumentException- The extension is not recognized, or names files the library reads but does not write (
.jpx,.jpf).
Remarks
The extensions are those of ImageFormatInfo.FileExtensions. This method is thread-safe.