WebPEncoder 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 (nearest rounding, or error diffusion with WebPEncoder.DitherBitDepthReduction): both bitstreams store 8-bit samples only. Lossy output is Y'CbCr 4:2:0, as the VP8 bitstream defines it; WebPEncoder.SharpYuv chooses planes that the chroma upsampling of the decoder turns into sharper edges. 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. An animation declares the size of the file (RIFF) and the alpha flag of the canvas before its frames, and the format has no other way to store them: on a seekable destination, the frames are written as they are encoded and these fields are patched once every frame is written; on a non-seekable stream, the whole file is kept in memory (counted against ImageResourceLimits.MaxLiveAllocationBytes, at most 2 GiB) and written at completion, so nothing is written when the output is aborted. A writer with an unknown frame count produces an animation; set ImageWriterOptions.ExpectedFrameCount to 1 to stream a still image instead.
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, or WebPEncoder.DitherBitDepthReduction). 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. |
| DitherBitDepthReduction | Gets a value indicating whether the color components of samples deeper than 8 bits are reduced with Floyd–Steinberg error diffusion instead of nearest rounding. Defaults to false. It does not allow the reduction by itself: WebPEncoder.AllowBitDepthReduction must be set too. |
| 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. |
| SharpYuv | Gets a value indicating whether WebPCompression.Lossy output converts RGB to Y'CbCr with an iterative refinement that takes the chroma upsampling of the decoder into account ("sharp YUV"). Defaults to false. Ignored by lossless output. |
AllowBitDepthReduction
WebPEncoder.csGets a value indicating whether 16-bit pixel formats may be reduced to 8 bits per component (nearest rounding, or WebPEncoder.DitherBitDepthReduction). Defaults to false.
public bool AllowBitDepthReduction { get; init; }Property value
Remarks
WebP stores 8-bit samples only (VP8L and VP8 bitstreams): a reduction is a property of the format.
AlphaQuality
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; }DitherBitDepthReduction
WebPEncoder.csGets a value indicating whether the color components of samples deeper than 8 bits are reduced with Floyd–Steinberg error diffusion instead of nearest rounding. Defaults to false. It does not allow the reduction by itself: WebPEncoder.AllowBitDepthReduction must be set too.
public bool DitherBitDepthReduction { get; init; }Property value
Remarks
The rounding error of each color component is carried to the pixels to the right and below (7, 3, 5 and 1 sixteenths, left to right on every row from the top row down), so that smooth 16-bit gradients keep their average level instead of showing 8-bit bands. Each component stays within one 8-bit step of its source value (the nearest 8-bit value or the other one around it); gray pixels stay gray. Alpha is rounded to the nearest value, and fully transparent pixels neither receive nor spread error. Lossless output of dithered pixels is larger than with nearest rounding; lossy output keeps the dithering at high qualities and smooths it at low ones. 8-bit pixel formats are never dithered.
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 (a patch of the output, like the file size).
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.
SharpYuv
WebPEncoder.csGets a value indicating whether WebPCompression.Lossy output converts RGB to Y'CbCr with an iterative refinement that takes the chroma upsampling of the decoder into account ("sharp YUV"). Defaults to false. Ignored by lossless output.
public bool SharpYuv { get; init; }Property value
Remarks
Lossy WebP (VP8) stores one chroma sample per 2x2 pixels: averaging the chroma of a block blurs colored edges, and the luminance of thin colored details and saturated edges drifts when the decoder interpolates the chroma back. With this setting, the encoder simulates the decoder (bilinear upsampling with centered siting, BT.601 limited-range conversion, clamping) and corrects the planes in a few passes: the chroma samples move toward the average error of the pixels they cover, and each luma sample absorbs the luminance error left at its pixel. Edges between saturated colors and colored text keep sharper luminance; in flat areas, the planes change by about the rounding of the plain conversion.
It costs a few passes over the image before compression (about 10 bytes of working memory per pixel), and the output is larger at the same WebPEncoder.Quality (a few percent on photographs, more on saturated graphics), for a better quality: compare at equal decoded quality. The stream is an ordinary VP8 stream: every decoder reads it, and the refinement fits decoders that upsample chroma bilinearly (libwebp, browsers and this library); the 4:2:0 subsampling itself is a property of the format.