Meziantou.FrameworkWebPEncoder Class
Immutable settings for WebP encoding (still images and animations).
public sealed class WebPEncoder : ImageEncoderRemarks
WebPEncoder.Compression selects the bitstream: WebPCompression.Lossless (the default) preserves every 8-bit sample; WebPCompression.Lossy trades fidelity for size according to WebPEncoder.Quality. WebPEncoder.Effort trades encoding time for size and never changes the decoded pixels of lossless output.
WebP stores 8-bit RGB(A): gray pixel formats are written as RGB (R = G = B, decoded as RGB), and 16-bit pixel formats require WebPEncoder.AllowBitDepthReduction. Alpha is always stored when the pixel format has alpha: exactly, unless WebPEncoder.AlphaQuality (lossy output) is below 100. WebPEncoder.NearLossless makes lossless output smaller by allowing small color errors.
The modes of lossy output (VP8 prediction modes) are stored in a first partition of at most 524,287 bytes. When the modes chosen freely do not fit, which only happens for very large detailed images (photographs of about 40 megapixels and more at high quality), the frame is encoded once more with a budget for the mode bits: the macroblocks where 4x4 prediction gains least switch to cheaper modes, spread over the whole image. The quantizer stays the same; the decoded quality decreases gradually with the image size, and every size up to the 16,383x16,383 limit fits.
An image with several frames or animation settings is written as an animation of full-canvas frames that replace the canvas ("do not blend", "do not dispose"), or of the regions that change with WebPEncoder.OptimizeFrames, with freshly computed control data. A still image (one frame, no animation settings) can be written to any stream. Animations need a seekable destination: the RIFF size and the alpha flag are patched once every frame is written. A writer with an unknown frame count produces an animation; set ImageWriterOptions.ExpectedFrameCount to 1 to write a still image to a non-seekable stream. Path outputs are always seekable.
Metadata (subject to ImageEncoder.MetadataHandling): ICC profile (ICCP, RGB profiles only), EXIF (EXIF, orientation and dimensions reconciled) and XMP (XMP ). WebP has no text or resolution chunk.
- Inheritance
ImageEncoderWebPEncoder
Constructors
| Name | Description |
|---|---|
| WebPEncoder() |
WebPEncoder()
WebPEncoder.cspublic WebPEncoder()No documentation is available.
Properties
| Name | Description |
|---|---|
| AllowBitDepthReduction | Gets a value indicating whether 16-bit pixel formats may be reduced to 8 bits per component (nearest rounding). Defaults to false. |
| AlphaQuality | Gets the quality of the alpha channel of WebPCompression.Lossy output, from 0 (2 alpha levels) to 100 (exact alpha). Defaults to 100. Ignored by lossless output and by images without transparency. |
| ClearTransparentColors | Gets a value indicating whether the color of fully transparent pixels is replaced with transparent black before encoding. Defaults to false: lossless output then preserves the color of fully transparent pixels exactly. |
| Compression | Gets the bitstream used for every frame. Defaults to WebPCompression.Lossless. |
| DurationRounding | Gets how frame durations are converted to WebP milliseconds (24-bit values). Defaults to FrameDurationRounding.RoundToNearest. |
| Effort | Gets the compression effort, from 0 (fastest, largest output) to 9 (slowest, smallest output). Defaults to 5. The effort never changes the decoded pixels of lossless output; for lossy output it changes the mode decisions, not the quality setting. |
| Format | Gets the format produced by this encoder. |
| NearLossless | Gets the near-lossless level of WebPCompression.Lossless output, from 0 (largest color errors, smallest output) to 100 (exact). Defaults to 100. Ignored by lossy output. |
| 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. Defaults to false: every frame covers the canvas and replaces it. |
| Quality | Gets the quality of WebPCompression.Lossy output, from 0 (smallest) to 100 (best). Defaults to 75. Ignored by lossless output. |
AllowBitDepthReduction
WebPEncoder.csAlphaQuality
WebPEncoder.csGets the quality of the alpha channel of WebPCompression.Lossy output, from 0 (2 alpha levels) to 100 (exact alpha). Defaults to 100. Ignored by lossless output and by images without transparency.
public int AlphaQuality { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not between 0 and 100.
Remarks
Below 100, the alpha values are reduced to fewer levels (the levels of smallest squared error) before they are compressed losslessly: 2 + quality / 5 levels up to 70, then 8 more levels per point, as cwebp -alpha_q. The reduced alpha is kept only when it compresses smaller than the exact alpha (fewer levels can break smooth ramps). Fully transparent and fully opaque pixels stay exact.
ClearTransparentColors
WebPEncoder.csGets a value indicating whether the color of fully transparent pixels is replaced with transparent black before encoding. Defaults to false: lossless output then preserves the color of fully transparent pixels exactly.
public bool ClearTransparentColors { get; init; }Property value
Remarks
Setting it usually makes the output smaller; the visible pixels and every alpha value are unchanged.
Compression
WebPEncoder.csGets the bitstream used for every frame. Defaults to WebPCompression.Lossless.
public WebPCompression Compression { get; init; }DurationRounding
WebPEncoder.csGets how frame durations are converted to WebP milliseconds (24-bit values). Defaults to FrameDurationRounding.RoundToNearest.
public FrameDurationRounding DurationRounding { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not a defined
FrameDurationRounding.
Effort
WebPEncoder.csGets the compression effort, from 0 (fastest, largest output) to 9 (slowest, smallest output). Defaults to 5. The effort never changes the decoded pixels of lossless output; for lossy output it changes the mode decisions, not the quality setting.
public int Effort { get; init; }Format
WebPEncoder.csNearLossless
WebPEncoder.csGets the near-lossless level of WebPCompression.Lossless output, from 0 (largest color errors, smallest output) to 100 (exact). Defaults to 100. Ignored by lossy output.
public int NearLossless { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not between 0 and 100.
Remarks
Below 100, the color of the pixels that differ from a neighbor (edges and texture) is rounded before lossless compression, which makes it repeat; smooth areas keep their colors. Each color component stays within 1 (levels 80 to 99), 2 (60 to 79), 4 (40 to 59), 8 (20 to 39) or 16 (0 to 19) of the source. Alpha, and the pixels of the image border, stay exact.
OptimizeFrames
WebPEncoder.csGets a value indicating whether the frames of an animation after the first one are written as the region of the canvas that changes. Defaults to false: every frame covers the canvas and replaces it.
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, grown to even coordinates (a WebP frame starts at an even offset), with the disposal of the previous frame ("do not dispose" or "dispose to the background color", transparent black) that gives the smallest box. The box is blended over the canvas, its unchanged pixels fully transparent, when every pixel that changes is opaque and some pixels do not; otherwise it replaces the canvas ("do not blend"), which reproduces every pixel, the transparent ones and their colors included. A frame equal to the previous one is a 1x1 frame. The first frame covers the canvas, and the durations, the play count and the number of frames are the same as without the setting.
The pixels are compared as they are given (after WebPEncoder.ClearTransparentColors): lossless output reproduces every displayed frame exactly. Lossy output, and lossless output with WebPEncoder.NearLossless below 100, compresses only the box: a pixel that does not change keeps the decoded color of the frame that drew it, so a blended box carries an alpha channel (exact, whatever WebPEncoder.AlphaQuality, since its pixels are opaque or transparent).
The encoder keeps a copy of the displayed frame (4 bytes per pixel), and the disposal chosen by a frame is written into the frame before it, in the seekable destination that every animation needs.
Quality
WebPEncoder.csGets the quality of WebPCompression.Lossy output, from 0 (smallest) to 100 (best). Defaults to 75. Ignored by lossless output.
public int Quality { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not between 0 and 100.
Remarks
The quality selects the quantizer index (100 is the finest quantizer, still lossy: chroma subsampling, color conversion and rounding remain) and the loop-filter strength. It is not a target distortion or file size. Its scale is not libwebp's: measured on photographs, cwebp -q 75 matches a quality of about 80, -q 50 about 70 and -q 25 about 54; lower values of this scale are coarser than the same cwebp values.