Struct Scaler 

pub struct Scaler {
    pub workload_strategy: WorkloadStrategy,
    /* private fields */
}

Represents base scaling structure

Fields

workload_strategy: WorkloadStrategy

Implementations

impl Scaler

pub fn new(filter: ResamplingFunction) -> Self

Creates new Scaler instance with corresponding filter

Creates default crate::Scaler with corresponding filter and default ThreadingPolicy::Single

pub fn set_workload_strategy( &mut self, workload_strategy: WorkloadStrategy, ) -> Self

Sets preferred workload strategy

This is hint only, it may change something, or may be not.

pub fn set_multi_step_upsampling(&mut self, value: bool) -> Self

Enables multistep upscaling for large magnification ratios.

When upscaling by a large factor (e.g. 10× or more), a single-pass filter does not have enough source samples to interpolate smoothly — the kernel spans so few real pixels that the result looks blocky or rings heavily. Multistep upscaling breaks the operation into a chain of smaller steps, each within the filter’s optimal range, so every pass has enough source data to produce a smooth result.

The number of steps and the intermediate sizes are chosen automatically based on the resampling function’s support width.

This has no effect on downscaling or on ResamplingFunction::Nearest, which are always single-pass. For modest upscale ratios already within the filter’s safe range the plan degenerates to a single step with no overhead.

pub fn set_supersampling(&mut self, value: bool) -> Self

Enables a cheap pre-filter pass before large downscales to improve quality and performance.

When downscaling by a large ratio (≥ 3×) the quality filter must average a very large number of source pixels per output pixel, which is slow and can produce aliasing. With supersampling enabled, a fast pre-filter first reduces the image to approximately twice the target size, then the quality filter performs a final clean 2× reduction. This keeps the quality filter in its optimal range while the cheap pre-filter handles the heavy lifting.

The pre-filter is chosen automatically based on the downscale ratio:

• ≥ 4×: ResamplingFunction::Nearest — fastest, no blending.
• 3–4×: ResamplingFunction::Box (area average) — slightly higher quality than nearest for non-integer ratios.

Has no effect on upscaling or on ResamplingFunction::Nearest, which is always single-pass.

impl Scaler

pub fn plan_planar_resampling( &self, source_size: ImageSize, target_size: ImageSize, ) -> Result<Arc<Resampling<u8, 1>>, PicScaleError>

Creates a resampling plan for a single-channel (planar/grayscale) u8 image.

The returned Arc<Resampling<u8, 1>> can be executed repeatedly against images of source_size to produce output of target_size without recomputing filter weights.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.

Example

let plan = scaler.plan_planar_resampling(source_size, target_size)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_gray_alpha_resampling( &self, source_size: ImageSize, target_size: ImageSize, premultiply_alpha: bool, ) -> Result<Arc<Resampling<u8, 2>>, PicScaleError>

Creates a resampling plan for a two-channel grayscale + alpha (GA) u8 image.

When premultiply_alpha is true the alpha channel is pre-multiplied into the gray channel before resampling and un-multiplied afterward.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• premultiply_alpha — Whether to premultiply alpha before resampling.

Example

// Resample with alpha-aware filtering to avoid dark fringing
let plan = scaler.plan_gray_alpha_resampling(source_size, target_size, true)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_cbcr_resampling( &self, source_size: ImageSize, target_size: ImageSize, ) -> Result<Arc<Resampling<u8, 2>>, PicScaleError>

Creates a resampling plan for a two-channel chroma (CbCr) u8 image.

Intended for the chroma planes of YCbCr images (e.g. the Cb/Cr planes in 4:2:0 or 4:2:2 video), where both channels are treated as independent signals with no alpha relationship. For the luma plane use [plan_planar_resampling].

Arguments

• source_size — Dimensions of the input chroma plane.
• target_size — Desired dimensions of the output chroma plane.

Example

let plan = scaler.plan_cbcr_resampling(source_size, target_size)?;
plan.resample(&cbcr_store, &mut target_cbcr_store)?;

pub fn plan_rgb_resampling( &self, source_size: ImageSize, target_size: ImageSize, ) -> Result<Arc<Resampling<u8, 3>>, PicScaleError>

Creates a resampling plan for a three-channel RGB u8 image.

The returned Arc<Resampling<u8, 3>> encodes all filter weights for scaling from source_size to target_size and can be reused across many frames without recomputation.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.

Example

let plan = scaler.plan_rgb_resampling(source_size, target_size)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_rgba_resampling( &self, source_size: ImageSize, target_size: ImageSize, premultiply_alpha: bool, ) -> Result<Arc<Resampling<u8, 4>>, PicScaleError>

Creates a resampling plan for a four-channel RGBA u8 image.

When premultiply_alpha is true the RGB channels are pre-multiplied by alpha before resampling and un-multiplied afterward.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• premultiply_alpha — Whether to premultiply alpha before resampling.

Example

// Resample a sprite sheet with correct alpha blending
let plan = scaler.plan_rgba_resampling(source_size, target_size, true)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_planar_resampling16( &self, source_size: ImageSize, target_size: ImageSize, bit_depth: usize, ) -> Result<Arc<Resampling<u16, 1>>, PicScaleError>

Creates a resampling plan for a single-channel (planar/grayscale) u16 image.

The 16-bit variant of [plan_planar_resampling], suitable for high-bit-depth grayscale content such as HDR images or luma planes from 10/12-bit video.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• bit_depth — Effective bit depth of the pixel data (e.g. 10, 12, or 16). Must not exceed 16.

Example

let plan = scaler.plan_planar_resampling16(source_size, target_size, 12)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_planar_resampling_s16( &self, source_size: ImageSize, target_size: ImageSize, bit_depth: usize, ) -> Result<Arc<Resampling<i16, 1>>, PicScaleError>

Creates a resampling plan for a single-channel (planar/grayscale) i16 image.

The 16-bit variant of [plan_planar_resampling], suitable for high-bit-depth grayscale content such as HDR images or luma planes from 10/12-bit video.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• bit_depth — Effective bit depth of the pixel data (e.g. 10, 12, or 16). Must not exceed 16.

Example

let plan = scaler.plan_planar_resampling_s16(source_size, target_size, 12)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_cbcr_resampling16( &self, source_size: ImageSize, target_size: ImageSize, bit_depth: usize, ) -> Result<Arc<Resampling<u16, 2>>, PicScaleError>

Creates a resampling plan for a two-channel chroma (CbCr) u16 image.

The 16-bit variant of [plan_cbcr_resampling], intended for high-bit-depth chroma planes of YCbCr content (e.g. 10-bit 4:2:0 or 4:2:2 video). Both channels are treated as independent signals with no alpha relationship.

Arguments

• source_size — Dimensions of the input chroma plane.
• target_size — Desired dimensions of the output chroma plane.
• bit_depth — Effective bit depth of the pixel data (e.g. 10, 12, or 16). Must not exceed 16.

Example

let plan = scaler.plan_cbcr_resampling16(source_size, target_size, 10)?;
plan.resample(&cbcr_store, &mut target_cbcr_store)?;

pub fn plan_gray_alpha_resampling16( &self, source_size: ImageSize, target_size: ImageSize, premultiply_alpha: bool, bit_depth: usize, ) -> Result<Arc<Resampling<u16, 2>>, PicScaleError>

Creates a resampling plan for a two-channel grayscale + alpha (GA) u16 image.

The 16-bit variant of [plan_gray_alpha_resampling]. When premultiply_alpha is true the gray channel is pre-multiplied by alpha before resampling and un-multiplied afterward.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• premultiply_alpha — Whether to premultiply alpha before resampling.
• bit_depth — Effective bit depth of the pixel data (e.g. 10, 12, or 16). Must not exceed 16.

Example

let plan = scaler.plan_gray_alpha_resampling16(source_size, target_size, true, 16)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_rgb_resampling16( &self, source_size: ImageSize, target_size: ImageSize, bit_depth: usize, ) -> Result<Arc<Resampling<u16, 3>>, PicScaleError>

Creates a resampling plan for a three-channel RGB u16 image.

The 16-bit variant of [plan_rgb_resampling], suitable for high-bit-depth color images such as 10/12-bit HDR or wide-gamut content. All three channels are resampled independently with no alpha relationship.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• bit_depth — Effective bit depth of the pixel data (e.g. 10, 12, or 16). Must not exceed 16.

Example

let plan = scaler.plan_rgb_resampling16(source_size, target_size, 12)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_rgba_resampling16( &self, source_size: ImageSize, target_size: ImageSize, premultiply_alpha: bool, bit_depth: usize, ) -> Result<Arc<Resampling<u16, 4>>, PicScaleError>

Creates a resampling plan for a four-channel RGBA u16 image.

The 16-bit variant of [plan_rgba_resampling]. When premultiply_alpha is true the RGB channels are pre-multiplied by alpha before resampling and un-multiplied afterward.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• premultiply_alpha — Whether to premultiply alpha before resampling.
• bit_depth — Effective bit depth of the pixel data (e.g. 10, 12, or 16). Must not exceed 16.

Example

let plan = scaler.plan_rgba_resampling16(source_size, target_size, true, 10)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_planar_resampling_f32( &self, source_size: ImageSize, target_size: ImageSize, ) -> Result<Arc<Resampling<f32, 1>>, PicScaleError>

Creates a resampling plan for a single-channel (planar/grayscale) f32 image.

The f32 variant of [plan_planar_resampling], suitable for HDR or linear-light grayscale content where full floating-point precision is required.

The internal accumulator precision is selected automatically based on the scaler’s WorkloadStrategy:

• PreferQuality — accumulates in f64 for maximum numerical accuracy.
• PreferSpeed — accumulates in f32 for faster throughput at a small precision cost.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.

Example

let plan = scaler.plan_planar_resampling_f32(source_size, target_size)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_cbcr_resampling_f32( &self, source_size: ImageSize, target_size: ImageSize, ) -> Result<Arc<dyn ResamplingPlan<f32, 2> + Send + Sync>, PicScaleError>

Creates a resampling plan for a two-channel chroma (CbCr) f32 image.

The f32 variant of [plan_cbcr_resampling], intended for floating-point chroma planes of YCbCr content. Both channels are treated as independent signals with no alpha relationship.

The internal accumulator precision is selected automatically based on the scaler’s WorkloadStrategy:

• PreferQuality — accumulates in f64 for maximum numerical accuracy.
• PreferSpeed — accumulates in f32 for faster throughput at a small precision cost.

Arguments

• source_size — Dimensions of the input chroma plane.
• target_size — Desired dimensions of the output chroma plane.

Example

let plan = scaler.plan_cbcr_resampling_f32(source_size, target_size)?;
plan.resample(&cbcr_store, &mut target_cbcr_store)?;

pub fn plan_gray_alpha_resampling_f32( &self, source_size: ImageSize, target_size: ImageSize, premultiply_alpha: bool, ) -> Result<Arc<Resampling<f32, 2>>, PicScaleError>

Creates a resampling plan for a two-channel grayscale + alpha (GA) f32 image.

The f32 variant of [plan_gray_alpha_resampling]. When premultiply_alpha is true the gray channel is pre-multiplied by alpha before resampling and un-multiplied afterward, preventing dark fringing around transparent edges. Set it to false if the image uses straight alpha or the channels should be filtered independently.

The internal accumulator precision is selected automatically based on the scaler’s WorkloadStrategy:

• PreferQuality — accumulates in f64 for maximum numerical accuracy.
• PreferSpeed — accumulates in f32 for faster throughput at a small precision cost.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• premultiply_alpha — Whether to premultiply alpha before resampling.

Example

let plan = scaler.plan_gray_alpha_resampling_f32(source_size, target_size, true)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_rgb_resampling_f32( &self, source_size: ImageSize, target_size: ImageSize, ) -> Result<Arc<Resampling<f32, 3>>, PicScaleError>

Creates a resampling plan for a three-channel RGB f32 image.

The f32 variant of [plan_rgb_resampling], suitable for HDR or linear-light color images where full floating-point precision is required. All three channels are resampled independently with no alpha relationship.

The internal accumulator precision is selected automatically based on the scaler’s WorkloadStrategy:

• PreferQuality — accumulates in f64 for maximum numerical accuracy.
• PreferSpeed — accumulates in f32 for faster throughput at a small precision cost.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.

Example

let plan = scaler.plan_rgb_resampling_f32(source_size, target_size)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_rgba_resampling_f32( &self, source_size: ImageSize, target_size: ImageSize, premultiply_alpha: bool, ) -> Result<Arc<Resampling<f32, 4>>, PicScaleError>

Creates a resampling plan for a four-channel RGBA f32 image.

The f32 variant of [plan_rgba_resampling]. When premultiply_alpha is true the RGB channels are pre-multiplied by alpha before resampling and un-multiplied afterward, preventing dark halos around semi-transparent edges. Set it to false if the image uses straight alpha or the channels should be filtered independently.

The internal accumulator precision is selected automatically based on the scaler’s WorkloadStrategy:

• PreferQuality — accumulates in f64 for maximum numerical accuracy.
• PreferSpeed — accumulates in f32 for faster throughput at a small precision cost.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• premultiply_alpha — Whether to premultiply alpha before resampling.

Example

let plan = scaler.plan_rgba_resampling_f32(source_size, target_size, true)?;
plan.resample(&store, &mut target_store)?;

pub fn set_threading_policy( &mut self, threading_policy: ThreadingPolicy, ) -> Self

impl Scaler

pub fn plan_ar30_resampling( &self, source_size: ImageSize, target_size: ImageSize, order: Ar30ByteOrder, ) -> Result<Arc<Resampling<u8, 4>>, PicScaleError>

Creates a resampling plan for an AR30 (RGBA2101010) packed 10-bit image.

AR30 stores each pixel as a 32-bit word with 10 bits per RGB channel and a 2-bit alpha.

The order argument controls the byte layout of the packed word:

• Ar30ByteOrder::Host — native endianness of the current platform.
• Ar30ByteOrder::Network — big-endian (network) byte order.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• order — Byte order of the packed AR30 words.

Example

let plan = scaler.plan_ar30_resampling(source_size, target_size, Ar30ByteOrder::Host)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_ra30_resampling( &self, source_size: ImageSize, target_size: ImageSize, order: Ar30ByteOrder, ) -> Result<Arc<Resampling<u8, 4>>, PicScaleError>

Creates a resampling plan for an RA30 (RGBA1010102) packed 10-bit image.

RA30 stores each pixel as a 32-bit word with 10 bits per RGB channel and a 2-bit alpha in the least-significant position.

The order argument controls the byte layout of the packed word:

• Ar30ByteOrder::Host — native endianness of the current platform.
• Ar30ByteOrder::Network — big-endian (network) byte order.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• order — Byte order of the packed RA30 words.

Example

let plan = scaler.resize_ra30(source_size, target_size, Ar30ByteOrder::Host)?;
plan.resample(&store, &mut target_store)?;

impl Scaler

Implements f16 type support

pub fn plan_planar_resampling_f16( &self, source_size: ImageSize, target_size: ImageSize, ) -> Result<Arc<Resampling<f16, 1>>, PicScaleError>

Available on crate feature nightly_f16 only.

Creates a resampling plan for a single-channel (planar/grayscale) f16 image.

The f16 variant of [plan_planar_resampling], suitable for half-precision grayscale content such as HDR render targets or compressed texture data. Filter weights are accumulated in f32 to avoid precision loss during convolution.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.

Example

let plan = scaler.plan_planar_resampling_f16(source_size, target_size)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_cbcr_resampling_f16( &self, source_size: ImageSize, target_size: ImageSize, ) -> Result<Arc<Resampling<f16, 2>>, PicScaleError>

Available on crate feature nightly_f16 only.

Creates a resampling plan for a two-channel chroma (CbCr) f16 image.

The f16 variant of [plan_cbcr_resampling], intended for half-precision chroma planes of YCbCr content. Both channels are treated as independent signals with no alpha relationship. Filter weights are accumulated in f32 to avoid precision loss during convolution.

Arguments

• source_size — Dimensions of the input chroma plane.
• target_size — Desired dimensions of the output chroma plane.

Example

let plan = scaler.plan_cbcr_resampling_f16(source_size, target_size)?;
plan.resample(&cbcr_store, &mut target_cbcr_store)?;

pub fn plan_rgb_resampling_f16( &self, source_size: ImageSize, target_size: ImageSize, ) -> Result<Arc<Resampling<f16, 3>>, PicScaleError>

Available on crate feature nightly_f16 only.

Creates a resampling plan for a three-channel RGB f16 image.

The f16 variant of [plan_rgb_resampling], suitable for half-precision color images such as HDR render targets or OpenEXR content. All three channels are resampled independently with no alpha relationship. Filter weights are accumulated in f32 to avoid precision loss during convolution.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.

Example

let plan = scaler.plan_rgb_resampling_f16(source_size, target_size)?;
plan.resample(&store, &mut target_store)?;

pub fn plan_rgba_resampling_f16( &self, source_size: ImageSize, target_size: ImageSize, premultiply_alpha: bool, ) -> Result<Arc<Resampling<f16, 4>>, PicScaleError>

Available on crate feature nightly_f16 only.

Creates a resampling plan for a four-channel RGBA f16 image.

The f16 variant of [plan_rgba_resampling]. Alpha premultiplication is always applied — RGB channels are pre-multiplied by alpha before resampling and un-multiplied afterward — regardless of the premultiply_alpha flag.

Arguments

• source_size — Dimensions of the input image.
• target_size — Desired dimensions of the output image.
• premultiply_alpha — Whether to premultiply alpha before resampling.

Example

let plan = scaler.plan_rgba_resampling_f16(source_size, target_size, true)?;
plan.resample(&store, &mut target_store)?;

Trait Implementations

impl Clone for Scaler

fn clone(&self) -> Scaler

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Scaler

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

Formats the value using the given formatter.

impl Copy for Scaler