Meziantou.FrameworkAvifEncoder Class
Immutable settings for AVIF encoding.
public sealed class AvifEncoder : ImageEncoderRemarks
AvifEncoder.Compression selects the AV1 coding: AvifCompression.Lossless (the default) preserves every sample; AvifCompression.Lossy trades fidelity for size according to AvifEncoder.Quality. AvifEncoder.Effort trades encoding time for size and never changes the decoded pixels of lossless output. Lossless AVIF files are large: select the lossy coding for photographs.
AVIF stores 8, 10 or 12 bits per sample. 8-bit pixel formats are written with 8 bits unless AvifEncoder.BitDepth asks for more; 16-bit pixel formats need AvifEncoder.BitDepth or AvifEncoder.AllowBitDepthReduction, because they lose precision. Gray pixel formats are written as monochrome images. Alpha is always stored when the image has a pixel that is not opaque, losslessly, as an auxiliary image.
An image with several frames is written as an image sequence: every frame is a full image, with its exact duration, and the play count of the animation. The first frame is a key frame; the others are predicted from the frame that precedes them, unless AvifEncoder.KeyFrameInterval asks for more key frames. A sequence needs a seekable destination and the number of its frames (ImageWriterOptions.ExpectedFrameCount for a writer), because the box that describes the frames precedes them and is written last. A still image goes to any stream. An image sequence of one image cannot store animation settings: it is read back as a still image.
Metadata (subject to ImageEncoder.MetadataHandling): the CICP color description (colr box, with the matrix coefficients and the range that the encoder used), the ICC profile, EXIF and XMP items, the orientation (irot and imir properties of a still image, the matrix of the track headers of an image sequence), the content light level, the mastering display color volume and the pixel aspect ratio (clli, mdcv and pasp boxes). AVIF has no text or resolution field.
A frame is coded in the fewest AV1 tiles that the format allows, unless AvifEncoder.AutoTiling asks for more: one tile up to 4096 pixels of width and 9,437,184 pixels of area. With ImageConfiguration.MaxDegreeOfParallelism above 1 (the configuration of the saved image), the tiles of a frame of at least 65,536 pixels that has several are coded by up to that many workers, each with buffers of its own (charged to ImageResourceLimits.MaxLiveAllocationBytes), except for a lossless frame of screen content that copies blocks; the output is byte-identical to the one of one worker.
- Inheritance
ImageEncoderAvifEncoder
Constructors
| Name | Description |
|---|---|
| AvifEncoder() |
AvifEncoder()
AvifEncoder.cspublic AvifEncoder()No documentation is available.
Properties
| Name | Description |
|---|---|
| AllowBitDepthReduction | Gets a value indicating whether 16-bit pixel formats may be reduced to 12 bits per sample (nearest rounding) when AvifEncoder.BitDepth is not set. Defaults to false. |
| AutoTiling | Gets a value indicating whether the AV1 frames are split into tiles from their size, so that they are coded and decoded by several workers at once. Defaults to false: a frame has the fewest tiles that the format allows, which is one tile up to 4096 pixels of width. |
| BitDepth | Gets the number of bits of a sample: 8, 10 or 12, or null (the default) for the depth of the pixel format. 8-bit pixels are scaled up exactly. A value for a 16-bit pixel format is the consent to reduce its samples to this depth (nearest rounding). |
| ChromaSubsampling | Gets the chroma subsampling of AvifCompression.Lossy color output. Defaults to AvifChromaSubsampling.Auto (4:2:0). Ignored by lossless output (4:4:4) and by gray pixel formats. |
| CleanAperture | Gets the clean aperture of the image: the rectangle that readers show, or null (the default) for the whole image. Every pixel is encoded; the ones outside the rectangle stay in the file and are hidden (clap property of a still image, clap box of the tracks of an image sequence), so that loading the file gives the rectangle. |
| 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 AV1 coding of every image. Defaults to AvifCompression.Lossless. |
| DurationRounding | Gets how the durations of the images of a sequence are stored. Defaults to FrameDurationRounding.RequireExact: the time scale of the sequence is the smallest one that holds every duration exactly, and a sequence whose durations have no common time scale of 32 bits is an error. FrameDurationRounding.RoundToNearest then rounds the durations to microseconds. |
| 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. |
| Format | Gets the format produced by this encoder. |
| GridTileSize | Gets the size of the tiles of a still image that is coded as a grid, or null (the default) for an image that is coded whole. An image that is larger than a tile is cut into tiles of this size, each one coded on its own, which a grid item assembles; an image that one tile holds is coded whole. |
| KeyFrameInterval | Gets the number of images from a key frame to the next one in an image sequence. Defaults to 0: the first image is the only key frame. 1 makes every image a key frame. An image that is not a key frame is predicted from the image that precedes it, which makes it smaller; a reader that seeks decodes from the last key frame. Ignored by a still image, and never changes the decoded pixels of lossless output. |
| PremultiplyAlpha | Gets a value indicating whether the color of every pixel is stored multiplied by its alpha (premultiplied alpha). Defaults to false: colors and alpha are stored independently. |
| Quality | Gets the quality of AvifCompression.Lossy output, from 0 (smallest) to 100 (best). Defaults to 75. Ignored by lossless output. |
AllowBitDepthReduction
AvifEncoder.csGets a value indicating whether 16-bit pixel formats may be reduced to 12 bits per sample (nearest rounding) when AvifEncoder.BitDepth is not set. Defaults to false.
public bool AllowBitDepthReduction { get; init; }Property value
AutoTiling
AvifEncoder.csGets a value indicating whether the AV1 frames are split into tiles from their size, so that they are coded and decoded by several workers at once. Defaults to false: a frame has the fewest tiles that the format allows, which is one tile up to 4096 pixels of width.
public bool AutoTiling { get; init; }Property value
Remarks
A frame has the largest power of two of tiles, up to 8, that leaves 512x512 pixels (262,144) to each tile, split along the longer side of the tiles first: one tile below 524,288 pixels, 2x2 tiles for 1920x1080, 4x2 tiles for 3840x2160, like the --autotiling option of libavif. The layout depends on the size of the frame only (the size of a tile of AvifEncoder.GridTileSize, the alpha plane too), never on ImageConfiguration.MaxDegreeOfParallelism: the file is the same whatever the number of workers.
A tile is coded without its neighbors, which costs size whatever the number of workers: on a 3840x2160 photo, 4x2 tiles make the file 0.33% larger at the default effort and 0.59% larger at effort 0, at the same PSNR, and 0.04% larger losslessly. In exchange, with ImageConfiguration.MaxDegreeOfParallelism set to 8 (Apple M5 Pro), that photo is encoded about 6.5 times faster at the default effort and losslessly and about 2 times faster at effort 0, and the library decodes the file about 1.9 times faster with 8 workers.
BitDepth
AvifEncoder.csGets the number of bits of a sample: 8, 10 or 12, or null (the default) for the depth of the pixel format. 8-bit pixels are scaled up exactly. A value for a 16-bit pixel format is the consent to reduce its samples to this depth (nearest rounding).
public int? BitDepth { get; init; }ChromaSubsampling
AvifEncoder.csGets the chroma subsampling of AvifCompression.Lossy color output. Defaults to AvifChromaSubsampling.Auto (4:2:0). Ignored by lossless output (4:4:4) and by gray pixel formats.
public AvifChromaSubsampling ChromaSubsampling { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not a defined
AvifChromaSubsampling.
CleanAperture
AvifEncoder.csGets the clean aperture of the image: the rectangle that readers show, or null (the default) for the whole image. Every pixel is encoded; the ones outside the rectangle stay in the file and are hidden (clap property of a still image, clap box of the tracks of an image sequence), so that loading the file gives the rectangle.
public Rectangle? CleanAperture { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The rectangle is empty, or its left or top coordinate is negative.
Remarks
The rectangle is in the coordinates of the stored pixels, before the orientation of the image. It must be inside the image. With subsampled chroma (AvifEncoder.ChromaSubsampling), its left coordinate must be even, and its top coordinate too for 4:2:0: the aperture then selects whole chroma samples, which the format requires.
ClearTransparentColors
AvifEncoder.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
AvifEncoder.csGets the AV1 coding of every image. Defaults to AvifCompression.Lossless.
public AvifCompression Compression { get; init; }DurationRounding
AvifEncoder.csGets how the durations of the images of a sequence are stored. Defaults to FrameDurationRounding.RequireExact: the time scale of the sequence is the smallest one that holds every duration exactly, and a sequence whose durations have no common time scale of 32 bits is an error. FrameDurationRounding.RoundToNearest then rounds the durations to microseconds.
public FrameDurationRounding DurationRounding { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not a defined
FrameDurationRounding.
Effort
AvifEncoder.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.
public int Effort { get; init; }Format
AvifEncoder.csGridTileSize
AvifEncoder.csGets the size of the tiles of a still image that is coded as a grid, or null (the default) for an image that is coded whole. An image that is larger than a tile is cut into tiles of this size, each one coded on its own, which a grid item assembles; an image that one tile holds is coded whole.
public Size? GridTileSize { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- A side of the tiles is not between 64 and 65,536.
Remarks
A grid bounds the size of what a decoder decodes at once, and the memory that encoding takes (one tile at a time): it is what the profiles of the format expect of large images. The tiles of the right column and of the bottom row extend past the image, whose last column and last row they repeat. A tile is coded without its neighbors: lossy output can show the edges of the tiles, and is larger than the image coded whole.
With ImageConfiguration.MaxDegreeOfParallelism above 1, the tiles of a grid of at least 65,536 samples are coded by up to that many workers at once, each with encoders of its own (charged to ImageResourceLimits.MaxLiveAllocationBytes); the output is byte-identical to the one of one worker.
Each side of a tile is between 64 and 65,536 pixels, and a grid has at most 256 columns and 256 rows. With subsampled chroma (AvifEncoder.ChromaSubsampling), the widths of the tiles and of the image must be even, and their heights too for 4:2:0. Ignored by an image sequence.
KeyFrameInterval
AvifEncoder.csGets the number of images from a key frame to the next one in an image sequence. Defaults to 0: the first image is the only key frame. 1 makes every image a key frame. An image that is not a key frame is predicted from the image that precedes it, which makes it smaller; a reader that seeks decodes from the last key frame. Ignored by a still image, and never changes the decoded pixels of lossless output.
public int KeyFrameInterval { get; init; }PremultiplyAlpha
AvifEncoder.csGets a value indicating whether the color of every pixel is stored multiplied by its alpha (premultiplied alpha). Defaults to false: colors and alpha are stored independently.
public bool PremultiplyAlpha { get; init; }Property value
Remarks
The multiplication is rounded to nearest at the precision of the pixels, then coded like any color, so it is the consent to that rounding: a reader divides the colors by the alpha, which does not give the original color back for the pixels that are nearly transparent, and nothing is left of the color of a fully transparent pixel (AvifEncoder.ClearTransparentColors then changes nothing). The alpha values are unchanged. Lossless output codes the multiplied samples exactly. Ignored when the image has no alpha.
Quality
AvifEncoder.csGets the quality of AvifCompression.Lossy output, from 0 (smallest) to 100 (best). Defaults to 75. Ignored by lossless output.
public int Quality { get; init; }