Class AvifWriterOptions

Namespace

Egami.Formats.Avif

Assembly

Egami.dll

Options for writing AVIF. Lossy images are coded on libavif's quality scale, so the same Quality gives about the same file as avifenc -q; lossless images keep every sample of 4:4:4 RGB.

public sealed class AvifWriterOptions : WriterOptions

Inheritance

object

WriterOptions

AvifWriterOptions

Inherited Members

WriterOptions.StripMetadata

WriterOptions.OmitSrgbProfile

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Save picks AVIF from the extension; the defaults are lossy at quality 60 on avifenc's scale, effort 4.
duck.Save("duck-q60.avif");

// Smaller and softer, or every sample exact (4:4:4 RGB with the identity matrix).
duck.Save("duck-q35.avif", new AvifWriterOptions { Quality = 35 });
duck.Save("duck-lossless.avif", new AvifWriterOptions { Lossless = true });

Properties

AlphaQuality

Gets the quality of the alpha plane, 0 to 100 on the same scale as Quality: 100 (the default) keeps alpha exactly. Alpha is written straight, not premultiplied.

public int AlphaQuality { get; init; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

The value is outside 0 to 100.

BitDepth

Gets the bits a sample has, 8, 10, 12 or 16, or null (the default) for 8 with 8-bit pixels and 10 with deeper ones; a lossless file of deeper pixels takes the depth of the AVIF file they were read from, else 12. 16 bits, which AV1 cannot code, are written as a sample transform (AVIF 1.2.0): lossless as an 8-bit image of the high bytes and a hidden 8-bit image of the low bytes, lossy as a 12-bit image and a hidden 8-bit residual that overlaps it by 4 bits. Readers without sample transforms show the 8- or 12-bit image.

public int? BitDepth { get; init; }

Property Value

int?

Examples

// 16 bits a sample, which AV1 cannot code, as a sample transform (AVIF 1.2): a 12-bit image and an 8-bit residual (or,
// lossless, the high and low bytes), with the first image as the fallback for readers without sample transforms.
using Raster<Rgb16> wide = duck.As<Rgb16>();
wide.Save("duck-16bit.avif", new AvifWriterOptions { BitDepth = 16, Quality = 90 });
using Raster deep = Raster.Load("duck-16bit.avif");
bool transformed = ((AvifDetails)deep.Metadata.FormatDetails!).HasSampleTransform;   // true, at 16 bits
using Raster fallback = Raster.Load("duck-16bit.avif", options: new AvifReaderOptions { SampleTransform = false });

Exceptions

ArgumentOutOfRangeException

The value is not 8, 10, 12 or 16.

Chroma

Gets the chroma format of lossy color, or null (the default) to choose: 4:0:0 for gray images, 4:4:4 from Quality 90 up, else 4:2:0. Lossless images are always 4:4:4 (or 4:0:0 when gray). AV1 has no 4:1:1 or 4:1:0, so those choose as null does.

public ChromaFormat? Chroma { get; init; }

Property Value

ChromaFormat?

Default

Gets the default options.

public static AvifWriterOptions Default { get; }

Property Value

AvifWriterOptions

Effort

Gets how hard the encoder works, 0 (fastest) to 10 (smallest files): 10 minus avifenc's speed, so the default 4 matches avifenc's default speed 6.

public int Effort { get; init; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

The value is outside 0 to 10.

FilmGrainDenoise

Gets how strongly to take film grain out before coding and put it back on decoding, 0 (the default, off) to 50, as libaom's denoise-noise-level: the image is denoised, the grain measured and written as AV1 film grain parameters that decoders add back, so the grain costs few bits. A raster loaded without its grain (FilmGrain false) gets its FilmGrain written back when this is 0. Ignored for lossless images.

public int FilmGrainDenoise { get; init; }

Property Value

int

Examples

// Grain is costly to code: denoise first and let decoders add it back from AV1 film grain parameters.
duck.Save("duck-grain.avif", new AvifWriterOptions { Quality = 60, FilmGrainDenoise = 20 });

// A raster loaded without its grain keeps the parameters, and saving writes them back.
using Raster plain = Raster.Load("duck-grain.avif", options: new AvifReaderOptions { FilmGrain = false });
plain.Save("duck-grain-again.avif");

Exceptions

ArgumentOutOfRangeException

The value is outside 0 to 50.

GainMapQuality

Gets the quality of a gain map, 0 to 100 on the same scale as Quality, as avifenc --qgain-map sets it, or null (the default) for the image's quality.

public int? GainMapQuality { get; init; }

Property Value

int?

Examples

// Save picks AVIF from the extension; the defaults are lossy at quality 60 on avifenc's scale, effort 4.
duck.Save("duck-q60.avif");

// Smaller and softer, or every sample exact (4:4:4 RGB with the identity matrix).
duck.Save("duck-q35.avif", new AvifWriterOptions { Quality = 35 });
duck.Save("duck-lossless.avif", new AvifWriterOptions { Lossless = true });

Exceptions

ArgumentOutOfRangeException

The value is outside 0 to 100.

GridTileSize

Gets the size of the cells of a grid image, or null (the default) to write one frame up to 8192 x 4352 and a grid of equal cells only for larger images.

public Size? GridTileSize { get; init; }

Property Value

Size?

Exceptions

ArgumentOutOfRangeException

A side is below 64 or above 8192.

Layers

Gets the layers of a progressive image, 1 to 4, from the first and smallest to the last, each with its own quality and scale; null (the default) for one layer, or the two Progressive makes. The last layer is the image at full size; when the image is lossless it is coded lossless. Images larger than one AV1 frame (written as a grid) are written in one layer.

public IReadOnlyList<AvifLayer>? Layers { get; init; }

Property Value

IReadOnlyList<AvifLayer>

Examples

// A progressive file: a small first layer a viewer can show early, then the image (as avifenc --progressive writes it).
duck.Save("duck-progressive.avif", new AvifWriterOptions { Quality = 60, Progressive = true });

// Or up to four layers, each with its own quality and size; the last is the image at full size.
duck.Save("duck-layers.avif", new AvifWriterOptions
{
    Layers = [new AvifLayer { Quality = 20, Scale = 0.5 }, new AvifLayer { Quality = 45 }, new AvifLayer { Quality = 75 }],
});

// Load gives the best layer; AvifReaderOptions.Layer picks another, at full size.
using Raster best = Raster.Load("duck-layers.avif");
IReadOnlyList<Size> layers = ((AvifDetails)best.Metadata.FormatDetails!).Layers;   // 160x120, 320x240, 320x240
using Raster first = Raster.Load("duck-layers.avif", options: new AvifReaderOptions { Layer = 0 });

Exceptions

ArgumentException

The list is empty, has more than 4 layers, or its last layer is not at scale 1.

Lossless

Gets whether to write lossless (every sample of the RGB or gray image exact, 4:4:4 with the identity matrix) or lossy data, or null (the default) to keep the kind of the AVIF file the raster was read from, and write lossy otherwise.

public bool? Lossless { get; init; }

Property Value

bool?

Progressive

Gets whether to write a progressive image of two layers, as avifenc --progressive does: a small first layer at quality 2, which a viewer can show while the rest arrives, then the image at Quality. Defaults to false. Ignored when Layers is set, and below Quality 10, where a first layer saves nothing.

public bool Progressive { get; init; }

Property Value

bool

Examples

// A progressive file: a small first layer a viewer can show early, then the image (as avifenc --progressive writes it).
duck.Save("duck-progressive.avif", new AvifWriterOptions { Quality = 60, Progressive = true });

// Or up to four layers, each with its own quality and size; the last is the image at full size.
duck.Save("duck-layers.avif", new AvifWriterOptions
{
    Layers = [new AvifLayer { Quality = 20, Scale = 0.5 }, new AvifLayer { Quality = 45 }, new AvifLayer { Quality = 75 }],
});

// Load gives the best layer; AvifReaderOptions.Layer picks another, at full size.
using Raster best = Raster.Load("duck-layers.avif");
IReadOnlyList<Size> layers = ((AvifDetails)best.Metadata.FormatDetails!).Layers;   // 160x120, 320x240, 320x240
using Raster first = Raster.Load("duck-layers.avif", options: new AvifReaderOptions { Layer = 0 });

Quality

Gets the lossy quality, 0 (smallest) to 100 (best), on avifenc's -q scale. Defaults to 60. Ignored for lossless images.

public int Quality { get; init; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

The value is outside 0 to 100.

TargetSize

Gets the largest size the file may have, in bytes, or null (the default) to code at Quality: the quality is searched, as avifenc --target-size searches it, for the largest file not above the size, then the quantizer between that quality and the next (in one layer), so the file lands close under the size. When even quality 0 is larger, that file is written and an Avif.TargetSizeExceeded warning says so. Ignored for lossless images.

public int? TargetSize { get; init; }

Property Value

int?

Examples

// The quality is searched for the largest file not above the size, as avifenc --target-size does.
duck.Save("duck-8k.avif", new AvifWriterOptions { TargetSize = 8000 });

Exceptions

ArgumentOutOfRangeException

The value is below 1.