Struct Encoder

pub struct Encoder {
    quantizer: u8,
    alpha_quantizer: u8,
    speed: u8,
    premultiplied_alpha: bool,
    color_model: ColorModel,
    threads: Option<usize>,
    alpha_color_mode: AlphaColorMode,
    output_depth: BitDepth,
}

Encoder config builder

Fields

quantizer: u8

0-255 scale

alpha_quantizer: u8

0-255 scale

speed: u8

rav1e preset 1 (slow) 10 (fast but crappy)

premultiplied_alpha: bool

True if RGBA input has already been premultiplied. It inserts appropriate metadata.

color_model: ColorModel

Which pixel format to use in AVIF file. RGB tends to give larger files.

threads: Option<usize>

How many threads should be used (0 = match core count), None - use global rayon thread pool

alpha_color_mode: AlphaColorMode

AlphaColorMode

output_depth: BitDepth

8 or 10

Implementations

impl Encoder

Builder methods

pub fn new() -> Self

Start here

pub fn with_quality(self, quality: f32) -> Self

Quality 1..=100. Panics if out of range.

pub fn with_bit_depth(self, depth: BitDepth) -> Self

Internal precision to use in the encoded AV1 data, for both color and alpha. 10-bit depth works best, even for 8-bit inputs/outputs.

Use 8-bit depth only as a workaround for decoders that need it.

This setting does not affect pixel inputs for this library.

pub fn with_alpha_quality(self, quality: f32) -> Self

Quality for the alpha channel only. 1..=100. Panics if out of range.

pub fn with_speed(self, speed: u8) -> Self

• 1 = very very slow, but max compression.
• 10 = quick, but larger file sizes and lower quality.

Panics if outside 1..=10.

pub fn with_internal_color_model(self, color_model: ColorModel) -> Self

Changes how color channels are stored in the image. The default is YCbCr.

Note that this is only internal detail for the AVIF file, and doesn’t change color model of inputs to encode functions.

pub fn with_num_threads(self, num_threads: Option<usize>) -> Self

Configures rayon thread pool size. The default None is to use all threads in the default rayon thread pool.

pub fn with_alpha_color_mode(self, mode: AlphaColorMode) -> Self

Configure handling of color channels in transparent images

Note that this doesn’t affect input format for this library, which for RGBA is always uncorrelated alpha.

impl Encoder

Once done with config, call one of the encode_* functions

pub fn encode_rgba( &self, in_buffer: Img<&[RGBA<u8>]>, ) -> Result<EncodedImage, Error>

Make a new AVIF image from RGBA pixels (non-premultiplied, alpha last)

Make the Img for the buffer like this:

Img::new(&pixels_rgba[..], width, height)

If you have pixels as u8 slice, then use the rgb crate, and do:

use rgb::ComponentSlice;
let pixels_rgba = pixels_u8.as_rgba();

If all pixels are opaque, the alpha channel will be left out automatically.

This function takes 8-bit inputs, but will generate an AVIF file using 10-bit depth.

returns AVIF file with info about sizes about AV1 payload.

fn convert_alpha_8bit(&self, in_buffer: Img<&[RGBA8]>) -> Option<ImgVec<RGBA8>>

pub fn encode_rgb(&self, buffer: Img<&[RGB8]>) -> Result<EncodedImage, Error>

Make a new AVIF image from RGB pixels

Make the Img for the buffer like this:

Img::new(&pixels_rgb[..], width, height)

If you have pixels as u8 slice, then first do:

use rgb::ComponentSlice;
let pixels_rgb = pixels_u8.as_rgb();

returns AVIF file, size of color metadata

fn encode_rgb_internal_from_8bit( &self, width: usize, height: usize, pixels: impl Iterator<Item = RGB8> + Send + Sync, ) -> Result<EncodedImage, Error>

pub fn encode_raw_planes_8_bit( &self, width: usize, height: usize, planes: impl IntoIterator<Item = [u8; 3]> + Send, alpha: Option<impl IntoIterator<Item = u8> + Send>, color_pixel_range: PixelRange, matrix_coefficients: MatrixCoefficients, ) -> Result<EncodedImage, Error>

Encodes AVIF from 3 planar channels that are in the color space described by matrix_coefficients, with sRGB transfer characteristics and color primaries.

Alpha always uses full range. Chroma subsampling is not supported, and it’s a bad idea for AVIF anyway. If there’s no alpha, use None::<[_; 0]>.

color_pixel_range should be PixelRange::Full to avoid worsening already small 8-bit dynamic range. Support for limited range may be removed in the future.

If AlphaColorMode::Premultiplied has been set, the alpha pixels must be premultiplied. AlphaColorMode::UnassociatedClean has no effect in this function, and is equivalent to AlphaColorMode::UnassociatedDirty.

returns AVIF file, size of color metadata, size of alpha metadata overhead

pub fn encode_raw_planes_10_bit( &self, width: usize, height: usize, planes: impl IntoIterator<Item = [u16; 3]> + Send, alpha: Option<impl IntoIterator<Item = u16> + Send>, color_pixel_range: PixelRange, matrix_coefficients: MatrixCoefficients, ) -> Result<EncodedImage, Error>

Encodes AVIF from 3 planar channels that are in the color space described by matrix_coefficients, with sRGB transfer characteristics and color primaries.

The pixels are 10-bit (values 0.=1023).

Alpha always uses full range. Chroma subsampling is not supported, and it’s a bad idea for AVIF anyway. If there’s no alpha, use None::<[_; 0]>.

color_pixel_range should be PixelRange::Full. Support for limited range may be removed in the future.

If AlphaColorMode::Premultiplied has been set, the alpha pixels must be premultiplied. AlphaColorMode::UnassociatedClean has no effect in this function, and is equivalent to AlphaColorMode::UnassociatedDirty.

returns AVIF file, size of color metadata, size of alpha metadata overhead

fn encode_raw_planes_internal<P: Pixel + Default>( &self, width: usize, height: usize, planes: impl IntoIterator<Item = [P; 3]> + Send, alpha: Option<impl IntoIterator<Item = P> + Send>, color_pixel_range: PixelRange, matrix_coefficients: MatrixCoefficients, input_pixels_bit_depth: u8, ) -> Result<EncodedImage, Error>

Trait Implementations

impl Clone for Encoder

fn clone(&self) -> Encoder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Encoder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.