Meziantou.FrameworkPngEncoder Class
Immutable settings for lossless PNG and APNG encoding.
public sealed class PngEncoder : ImageEncoderRemarks
By default the PNG color type and bit depth follow the pixel format: grayscale for Gray8/Gray16, grayscale with alpha for La16/La32 (and A8, written as black with its alpha), RGB for Rgb24/Rgb48, RGBA for Rgba32/Bgra32/Rgba64, and 16-bit samples for the 16-bit pixel formats. PngPixelLayout.Indexed writes a palette instead, for the images whose colors it can hold exactly. PngOptimization.MinimumSize chooses the layout, the filters and the animation frame rectangles that give the smallest file instead, and PngOptimization.Layout only the layout of a still image, from one pass over its pixels. Encoding never reduces precision, never reduces colors and never drops alpha.
Animated output is written with freshly computed control data: full-canvas frames by default, or the rectangles that changed with PngEncoder.OptimizeFrames or PngOptimization.MinimumSize; delta information from a decoded source is never reused. PNG and APNG writers require ImageWriterOptions.ExpectedFrameCount.
The output is always a standard PNG file: Apple's CgBI variant (iOS-optimized PNG), which the decoder reads, is never written.
- Inheritance
ImageEncoderPngEncoder
Constructors
| Name | Description |
|---|---|
| PngEncoder() |
PngEncoder()
PngEncoder.cspublic PngEncoder()No documentation is available.
Properties
| Name | Description |
|---|---|
| AllowColorReduction | Gets a value indicating whether PngPixelLayout.Indexed may reduce the colors of an image that its palette cannot store exactly: more than 256 distinct colors (or than QuantizeOptions.MaxColors), colors that are not in QuantizeOptions.Palette, 16-bit samples that 8 bits cannot represent, or, for a sequential writer, a later frame with colors that are not in the palette of the first image. Defaults to false: such an image is rejected with an UnsupportedImageFeatureException, as without this setting. When true, the colors are reduced as PngEncoder.Quantization says. An image whose colors fit is always stored exactly. Ignored by the other layouts. |
| AnimationMode | Gets the animation mode. Defaults to PngAnimationMode.Auto. |
| CompressionLevel | Gets the zlib compression level. Defaults to CompressionLevel.Optimal. Ignored by PngOptimization.MinimumSize, which tries several levels and keeps the smallest data. |
| DurationRounding | Gets how frame durations are converted to APNG delay_num / delay_den (16-bit unsigned values). Defaults to FrameDurationRounding.RequireExact. |
| Filter | Gets the row filter strategy. Defaults to PngFilter.Adaptive. |
| Format | Gets the format produced by this encoder. |
| Interlaced | Gets a value indicating whether Adam7 interlacing is used. Defaults to false. |
| Optimization | Gets the optimization mode. Defaults to PngOptimization.None. |
| OptimizeFrames | Gets a value indicating whether the frames of an animation after the first one are written as the region of the canvas that changes, with the layout, the filters and the compression level of the other settings. Defaults to false: every frame covers the canvas. PngOptimization.MinimumSize always writes such regions (choosing them by compressing the candidates) and ignores the setting. |
| PixelLayout | Gets the pixel layout. Defaults to PngPixelLayout.Auto. |
| Quantization | Gets how PngPixelLayout.Indexed reduces colors when PngEncoder.AllowColorReduction is set. Defaults to QuantizeOptions.Default: at most 256 entries, without dithering. Ignored otherwise. |
AllowColorReduction
PngEncoder.csGets a value indicating whether PngPixelLayout.Indexed may reduce the colors of an image that its palette cannot store exactly: more than 256 distinct colors (or than QuantizeOptions.MaxColors), colors that are not in QuantizeOptions.Palette, 16-bit samples that 8 bits cannot represent, or, for a sequential writer, a later frame with colors that are not in the palette of the first image. Defaults to false: such an image is rejected with an UnsupportedImageFeatureException, as without this setting. When true, the colors are reduced as PngEncoder.Quantization says. An image whose colors fit is always stored exactly. Ignored by the other layouts.
public bool AllowColorReduction { get; init; }Property value
AnimationMode
PngEncoder.csGets the animation mode. Defaults to PngAnimationMode.Auto.
public PngAnimationMode AnimationMode { get; init; }CompressionLevel
PngEncoder.csGets the zlib compression level. Defaults to CompressionLevel.Optimal. Ignored by PngOptimization.MinimumSize, which tries several levels and keeps the smallest data.
public CompressionLevel CompressionLevel { get; init; }DurationRounding
PngEncoder.csGets how frame durations are converted to APNG delay_num / delay_den (16-bit unsigned values). Defaults to FrameDurationRounding.RequireExact.
public FrameDurationRounding DurationRounding { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not a defined
FrameDurationRounding.
Filter
PngEncoder.csGets the row filter strategy. Defaults to PngFilter.Adaptive.
public PngFilter Filter { get; init; }Format
PngEncoder.csInterlaced
PngEncoder.csOptimization
PngEncoder.csGets the optimization mode. Defaults to PngOptimization.None.
public PngOptimization Optimization { get; init; }OptimizeFrames
PngEncoder.csGets a value indicating whether the frames of an animation after the first one are written as the region of the canvas that changes, with the layout, the filters and the compression level of the other settings. Defaults to false: every frame covers the canvas. PngOptimization.MinimumSize always writes such regions (choosing them by compressing the candidates) and ignores the setting.
public bool OptimizeFrames { get; init; }Property value
Remarks
Each frame stores the bounding box of the pixels that differ from the canvas it is drawn on, with the disposal of the previous frame (APNG_DISPOSE_OP_NONE, BACKGROUND or PREVIOUS) that gives the smallest box. The box is blended with APNG_BLEND_OP_OVER, its unchanged pixels fully transparent, when the layout has a transparent value (an alpha channel, or a fully transparent palette entry), some pixels do not change, and every pixel that changes is opaque, or not fully transparent where the canvas is (both give the pixel exactly); otherwise with APNG_BLEND_OP_SOURCE, which reproduces every pixel. A frame equal to the previous one is a 1x1 region. The first frame and the poster cover the canvas, and the displayed frames, their durations, the play count and the number of frames are exactly the same as without the setting. The palette indexes of PngPixelLayout.Indexed have 8 bits, because some decoders misplace the packed pixels of a frame region.
The encoder keeps two copies of the canvas (4 bytes per pixel, 8 for the 16-bit pixel formats), and the compressed data of each frame until the next one is given: the fcTL chunk of a frame holds the disposal chosen for the next one.
PixelLayout
PngEncoder.csGets the pixel layout. Defaults to PngPixelLayout.Auto.
public PngPixelLayout PixelLayout { get; init; }Quantization
PngEncoder.csGets how PngPixelLayout.Indexed reduces colors when PngEncoder.AllowColorReduction is set. Defaults to QuantizeOptions.Default: at most 256 entries, without dithering. Ignored otherwise.
public QuantizeOptions Quantization { get; init; }Property value
Exceptions
ArgumentNullException- The value is
null.
Remarks
A PNG file has one palette, written before its first image. An eager save computes it from every frame and the poster (a deterministic variance-based median cut of their colors, see PaletteBuilder, or QuantizeOptions.Palette), and a sequential writer from the first image it is given; every image then maps to it, with the dithering of QuantizeOptions.Dithering, as ImageProcessingExtensions.Quantize does. Alpha is reduced with the colors: entries may be translucent (tRNS), and fully transparent pixels share one entry.
Each image is reduced into a copy of 8-bit RGBA pixels, charged to the resource limits of the writer: an eager save keeps the copies of every image until it completes, a sequential writer the copy of the image it writes.