j2k-native 0.13.1

// SPDX-License-Identifier: MIT OR Apache-2.0
// j2k-coverage: shared-accelerator-host

use super::super::allocation::{checked_add_bytes, checked_element_bytes, host_allocation_failed};
use super::super::{
    encode_forward_dwt, forward_mct, profile, try_deinterleave_to_f32, try_encode_forward_ict,
    try_encode_forward_rct, validate_deinterleaved_components, BlockCodingMode,
    EncodeComponentSampleInfo, EncodeOptions, EncodeRoiRegion, ForwardDwtRequest,
    J2kDeinterleaveMctToF32Job, J2kDeinterleaveToF32Job, J2kEncodeStageAccelerator,
    J2kHtj2kTileEncodeJob, J2kResidentEncodeInput, J2kResidentHtj2kTileEncodeJob,
    NativeEncodePipelineError, NativeEncodePipelineResult, NativeEncodeSession,
    ResidentHtj2kEncodeError, Vec,
};
use super::coefficient_source::{
    validate_component_sampling_dwt_geometry, OwnedDwtComponent, PackedF32DwtComponent,
};
use super::ownership::{
    component_planes_retained_bytes, dwt_component_sources_retained_bytes,
    single_tile_plan_retained_bytes,
};
use super::plan::SingleTilePlan;
use super::resident::resident_error_from_encode_error;

pub(super) struct PreparedComponentTransforms {
    pub(super) decompositions: Vec<OwnedDwtComponent>,
    pub(super) deinterleave_us: u128,
    pub(super) mct_us: u128,
    pub(super) dwt_us: u128,
}

pub(super) struct AcceleratedComponentRequest<'a, 'input> {
    pub(super) pixels: &'a [u8],
    pub(super) width: u32,
    pub(super) height: u32,
    pub(super) num_components: u16,
    pub(super) bit_depth: u8,
    pub(super) signed: bool,
    pub(super) options: &'a EncodeOptions,
    pub(super) plan: &'a SingleTilePlan,
    pub(super) profile_enabled: bool,
    pub(super) session: &'a NativeEncodeSession<'input>,
}

#[expect(
    clippy::too_many_arguments,
    reason = "this codec boundary keeps geometry, state buffers, and validated options explicit without allocation or indirection"
)]
pub(super) fn try_encode_complete_ht_tile(
    pixels: &[u8],
    width: u32,
    height: u32,
    num_components: u16,
    bit_depth: u8,
    signed: bool,
    options: &EncodeOptions,
    component_sample_info: &[EncodeComponentSampleInfo],
    roi_regions: &[EncodeRoiRegion],
    plan: &mut SingleTilePlan,
    profile_enabled: bool,
    session: &NativeEncodeSession<'_>,
    accelerator: &mut impl J2kEncodeStageAccelerator,
) -> NativeEncodePipelineResult<Option<(Vec<u8>, u128)>> {
    let stage_start = profile::profile_now(profile_enabled);
    if complete_ht_tile_supported(options, plan)
        // Built-in fused host encoders emit one implicit precinct per resolution.
        // Wider host tiles use the staged path, which partitions all precincts.
        && plan.params.width <= (1 << 15)
        && plan.params.height <= (1 << 15)
        && component_sample_info.is_empty()
        && plan.roi_component_shifts.iter().all(|shift| *shift == 0)
        && roi_regions.is_empty()
    {
        let input =
            J2kResidentEncodeInput::new(width, height, num_components, bit_depth, signed)
                .map_err(|error| NativeEncodePipelineError::internal_invariant(error.reason()))?;
        let resident_job = resident_htj2k_tile_job(input, options, plan);
        let phase = session.checked_phase(
            single_tile_plan_retained_bytes(plan)?,
            "retained single-tile accelerator plan",
        )?;
        if let Some(tile_data) = accelerator
            .encode_htj2k_tile(J2kHtj2kTileEncodeJob {
                pixels,
                width: resident_job.input.width(),
                height: resident_job.input.height(),
                num_components: resident_job.input.num_components(),
                bit_depth: resident_job.input.bit_depth(),
                signed: resident_job.input.signed(),
                num_decomposition_levels: resident_job.num_decomposition_levels,
                reversible: resident_job.reversible,
                use_mct: resident_job.use_mct,
                guard_bits: resident_job.guard_bits,
                code_block_width: resident_job.code_block_width,
                code_block_height: resident_job.code_block_height,
                progression_order: resident_job.progression_order,
                component_sampling: resident_job.component_sampling,
                quantization_steps: resident_job.quantization_steps,
            })
            .map_err(|source| crate::EncodeError::Accelerator {
                operation: "whole-tile HTJ2K encode",
                source,
            })?
        {
            phase.reconcile_accelerator_vec(&tile_data, "accelerator whole-tile HTJ2K output")?;
            if let Some(bound) = accelerator.ht_tile_required_magnitude_bound() {
                plan.params.required_ht_magnitude_bound = Some(bound);
            }
            return Ok(Some((tile_data, profile::elapsed_us(stage_start))));
        }
    }

    Ok(None)
}

pub(super) fn encode_complete_resident_ht_tile(
    input: J2kResidentEncodeInput,
    options: &EncodeOptions,
    plan: &mut SingleTilePlan,
    profile_enabled: bool,
    session: &NativeEncodeSession<'_>,
    accelerator: &mut impl J2kEncodeStageAccelerator,
) -> Result<(Vec<u8>, u128), ResidentHtj2kEncodeError> {
    if !complete_ht_tile_supported(options, plan)
        || plan.roi_component_shifts.iter().any(|shift| *shift != 0)
    {
        return Err(ResidentHtj2kEncodeError::Unsupported(
            "resident HTJ2K encode options require the staged host pipeline",
        ));
    }

    let stage_start = profile::profile_now(profile_enabled);
    let job = resident_htj2k_tile_job(input, options, plan);
    let phase = session
        .checked_phase(
            single_tile_plan_retained_bytes(plan).map_err(resident_error_from_encode_error)?,
            "retained resident single-tile accelerator plan",
        )
        .map_err(resident_error_from_encode_error)?;
    match accelerator
        .encode_resident_htj2k_tile(job)
        .map_err(ResidentHtj2kEncodeError::Accelerator)?
    {
        Some(tile_data) => {
            phase
                .reconcile_accelerator_vec(
                    &tile_data,
                    "resident accelerator whole-tile HTJ2K output",
                )
                .map_err(resident_error_from_encode_error)?;
            if let Some(bound) = accelerator.ht_tile_required_magnitude_bound() {
                plan.params.required_ht_magnitude_bound = Some(bound);
            }
            Ok((tile_data, profile::elapsed_us(stage_start)))
        }
        None => Err(ResidentHtj2kEncodeError::Declined),
    }
}

fn complete_ht_tile_supported(options: &EncodeOptions, plan: &SingleTilePlan) -> bool {
    // Preserve the fused route wherever its zero-origin partition is equivalent.
    // Other tiles use the staged GPU transforms and code-block encoders.
    zero_origin_equivalent(plan)
        && plan.params.block_coding_mode == BlockCodingMode::HighThroughput
        && plan.params.num_layers == 1
        // Whole-tile jobs have no precinct partition metadata.
        && options.precinct_exponents.is_empty()
        // Whole-tile jobs do not carry byte targets or a pass-allocation contract.
        && options.quality_layer_byte_targets.is_empty()
        && !(plan.params.write_plt
            || plan.params.write_plm
            || plan.params.write_ppm
            || plan.params.write_ppt
            || plan.params.write_sop
            || plan.params.write_eph
            || options.tile_part_packet_limit.is_some())
}

fn zero_origin_equivalent(plan: &SingleTilePlan) -> bool {
    let Some(x1) = plan.tile_origin.0.checked_add(plan.params.width) else {
        return false;
    };
    let Some(y1) = plan.tile_origin.1.checked_add(plan.params.height) else {
        return false;
    };
    super::super::tile_grid::component_tile_axis_is_aligned(
        plan.tile_origin.0,
        x1,
        plan.num_levels,
        plan.params.code_block_width_exp + 2,
        |r| {
            plan.params
                .precinct_exponents
                .get(usize::from(r))
                .map_or(15, |p| p.0)
        },
    ) && super::super::tile_grid::component_tile_axis_is_aligned(
        plan.tile_origin.1,
        y1,
        plan.num_levels,
        plan.params.code_block_height_exp + 2,
        |r| {
            plan.params
                .precinct_exponents
                .get(usize::from(r))
                .map_or(15, |p| p.1)
        },
    )
}

fn resident_htj2k_tile_job<'a>(
    input: J2kResidentEncodeInput,
    options: &EncodeOptions,
    plan: &'a SingleTilePlan,
) -> J2kResidentHtj2kTileEncodeJob<'a> {
    J2kResidentHtj2kTileEncodeJob {
        input,
        num_decomposition_levels: plan.num_levels,
        reversible: options.reversible,
        use_mct: plan.use_mct,
        guard_bits: plan.guard_bits,
        code_block_width: plan.cb_width,
        code_block_height: plan.cb_height,
        progression_order: options.progression_order.packetization_order(),
        component_sampling: &plan.params.component_sampling,
        quantization_steps: &plan.quant_params,
    }
}

pub(super) fn prepare_accelerated_components(
    request: &AcceleratedComponentRequest<'_, '_>,
    accelerator: &mut impl J2kEncodeStageAccelerator,
) -> NativeEncodePipelineResult<PreparedComponentTransforms> {
    let plan_bytes = single_tile_plan_retained_bytes(request.plan)?;
    if let Some(prepared) = try_prepare_rgb8_dwt_components(request, plan_bytes, accelerator)? {
        return Ok(prepared);
    }
    let (mut components, component_bytes, deinterleave_us, mct_applied) =
        prepare_deinterleaved_components(request, plan_bytes, accelerator)?;
    let mct_us = if mct_applied {
        0
    } else {
        apply_forward_mct(request, &mut components, accelerator)?
    };
    let (decompositions, dwt_us) = prepare_dwt_components(
        request,
        components,
        component_bytes,
        plan_bytes,
        accelerator,
    )?;
    Ok(PreparedComponentTransforms {
        decompositions,
        deinterleave_us,
        mct_us,
        dwt_us,
    })
}

/// 8-bit RGB under the forward MCT with every stage on the CPU: the first DWT
/// level of all three components reads the pixels in one pass, so no
/// component plane is written and read back and no spare plane is needed.
/// `None` leaves other requests to the staged deinterleave, MCT and DWT.
fn try_prepare_rgb8_dwt_components(
    request: &AcceleratedComponentRequest<'_, '_>,
    plan_bytes: usize,
    accelerator: &impl J2kEncodeStageAccelerator,
) -> NativeEncodePipelineResult<Option<PreparedComponentTransforms>> {
    let origin = request.plan.component_origin(0);
    if !(request.plan.use_mct
        && request.num_components == 3
        && request.bit_depth == 8
        && !request.signed
        && accelerator.declines_every_stage()
        && (1..3).all(|component| request.plan.component_origin(component) == origin))
    {
        return Ok(None);
    }
    let stage_start = profile::profile_now(request.profile_enabled);
    let samples = request.plan.num_pixels;
    let planes_bytes = checked_add_bytes(
        checked_element_bytes::<Vec<f32>>(3, "transform component plane owners")?,
        checked_element_bytes::<f32>(
            samples
                .checked_mul(3)
                .ok_or(crate::EncodeError::ArithmeticOverflow {
                    what: "transform component sample count",
                })?,
            "transform component plane samples",
        )?,
        "transform component planes",
    )?;
    let owner_bytes =
        checked_element_bytes::<OwnedDwtComponent>(3, "transform DWT component owners")?;
    let owner_phase_bytes = checked_add_bytes(plan_bytes, owner_bytes, "DWT owner phase")?;
    let scratch_count = dwt_scratch_count(
        request,
        crate::j2c::fdwt::packed_rgb8_dwt_scratch_len,
        checked_add_bytes(owner_phase_bytes, planes_bytes, "DWT owner phase")?,
        accelerator.prefer_parallel_cpu_code_block_fallback(),
    )?;
    let scratch_bytes = checked_element_bytes::<f32>(scratch_count, "packed DWT line scratch")?;
    request.session.checked_phase(
        checked_add_bytes(
            checked_add_bytes(owner_phase_bytes, scratch_bytes, "DWT input phase")?,
            planes_bytes,
            "DWT input phase",
        )?,
        "native encode packed DWT phase",
    )?;
    let mut decompositions = Vec::new();
    decompositions
        .try_reserve_exact(3)
        .map_err(|_| host_allocation_failed("transform DWT component owners", owner_bytes))?;
    let mut line_scratch = Vec::new();
    line_scratch
        .try_reserve_exact(scratch_count)
        .map_err(|_| host_allocation_failed("packed DWT line scratch", scratch_bytes))?;
    line_scratch.resize(scratch_count, 0.0);
    let mut planes = try_rgb_planes(samples, planes_bytes)?;
    let [luma, blue, red] = planes.as_mut_slice() else {
        return Err(NativeEncodePipelineError::internal_invariant(
            "RGB DWT needs three component planes",
        ));
    };
    let shape = crate::j2c::fdwt::try_forward_dwt_packed_f32_from_rgb8(
        request.pixels,
        [luma, blue, red].map(Vec::as_mut_slice),
        request.width,
        request.height,
        request.plan.num_levels,
        request.options.reversible,
        &mut line_scratch,
        origin,
    )?;
    drop(line_scratch);
    for coefficients in planes {
        let geometry = crate::j2c::fdwt::PackedDwtGeometry::try_new(
            request.width,
            request.height,
            coefficients.len(),
            shape,
        )?;
        decompositions.push(OwnedDwtComponent::Packed(PackedF32DwtComponent {
            coefficients,
            geometry,
        }));
    }
    request.session.checked_phase(
        checked_add_bytes(
            plan_bytes,
            dwt_component_sources_retained_bytes(&decompositions, decompositions.capacity())?,
            "DWT output phase",
        )?,
        "native encode DWT output phase",
    )?;
    validate_component_sampling_dwt_geometry(
        &decompositions,
        request.width,
        request.height,
        &request.plan.params.component_sampling,
    )?;
    Ok(Some(PreparedComponentTransforms {
        decompositions,
        deinterleave_us: 0,
        mct_us: 0,
        dwt_us: profile::elapsed_us(stage_start),
    }))
}

/// Three zeroed planes of `samples` samples, `bytes` in all with their owners.
fn try_rgb_planes(samples: usize, bytes: usize) -> NativeEncodePipelineResult<Vec<Vec<f32>>> {
    let failed = || host_allocation_failed("transform component planes", bytes);
    let mut planes = Vec::new();
    planes.try_reserve_exact(3).map_err(|_| failed())?;
    for _ in 0..3 {
        let mut plane = Vec::new();
        plane.try_reserve_exact(samples).map_err(|_| failed())?;
        plane.resize(samples, 0.0);
        planes.push(plane);
    }
    Ok(planes)
}

fn prepare_deinterleaved_components(
    request: &AcceleratedComponentRequest<'_, '_>,
    plan_bytes: usize,
    accelerator: &mut impl J2kEncodeStageAccelerator,
) -> NativeEncodePipelineResult<(Vec<Vec<f32>>, usize, u128, bool)> {
    let requested_sample_count = request
        .plan
        .num_pixels
        .checked_mul(usize::from(request.num_components))
        .ok_or(crate::EncodeError::ArithmeticOverflow {
            what: "transform component sample count",
        })?;
    let requested_bytes = checked_add_bytes(
        checked_element_bytes::<Vec<f32>>(
            usize::from(request.num_components),
            "transform component plane owners",
        )?,
        checked_element_bytes::<f32>(requested_sample_count, "transform component plane samples")?,
        "transform component plane owners",
    )?;
    request.session.checked_phase(
        checked_add_bytes(plan_bytes, requested_bytes, "deinterleave phase")?,
        "native encode deinterleave phase",
    )?;

    let stage_start = profile::profile_now(request.profile_enabled);
    let combined_eligible = request.plan.use_mct && request.num_components == 3;
    let combined_components = if combined_eligible {
        accelerator
            .encode_deinterleave_mct(J2kDeinterleaveMctToF32Job {
                pixels: request.pixels,
                num_pixels: request.plan.num_pixels,
                bit_depth: request.bit_depth,
                signed: request.signed,
                reversible: request.options.reversible,
            })
            .map_err(|source| crate::EncodeError::Accelerator {
                operation: "pixel deinterleave and forward MCT",
                source,
            })?
    } else {
        None
    };
    let mct_applied = combined_components.is_some();
    let components = if let Some(components) = combined_components {
        validate_deinterleaved_components(components, 3, request.plan.num_pixels).map_err(
            |detail| crate::EncodeError::Accelerator {
                operation: "pixel deinterleave and forward MCT",
                source: crate::J2kEncodeStageError::internal_invariant(detail),
            },
        )?
    } else {
        let components = accelerator
            .encode_deinterleave(J2kDeinterleaveToF32Job {
                pixels: request.pixels,
                num_pixels: request.plan.num_pixels,
                num_components: request.num_components,
                bit_depth: request.bit_depth,
                signed: request.signed,
            })
            .map_err(|source| crate::EncodeError::Accelerator {
                operation: "pixel deinterleave",
                source,
            })?;
        match components {
            Some(components) => validate_deinterleaved_components(
                components,
                request.num_components,
                request.plan.num_pixels,
            )
            .map_err(|detail| crate::EncodeError::Accelerator {
                operation: "pixel deinterleave",
                source: crate::J2kEncodeStageError::internal_invariant(detail),
            })?,
            None => try_deinterleave_to_f32(
                request.pixels,
                request.plan.num_pixels,
                request.num_components,
                request.bit_depth,
                request.signed,
                accelerator.prefer_parallel_cpu_code_block_fallback(),
            )?,
        }
    };
    let actual_bytes = component_planes_retained_bytes(&components, components.capacity())?;
    request.session.checked_phase(
        checked_add_bytes(plan_bytes, actual_bytes, "deinterleave output phase")?,
        "native encode deinterleave output",
    )?;
    Ok((
        components,
        actual_bytes,
        profile::elapsed_us(stage_start),
        mct_applied,
    ))
}

fn apply_forward_mct(
    request: &AcceleratedComponentRequest<'_, '_>,
    components: &mut [Vec<f32>],
    accelerator: &mut impl J2kEncodeStageAccelerator,
) -> NativeEncodePipelineResult<u128> {
    let stage_start = profile::profile_now(request.profile_enabled);
    if request.plan.use_mct {
        if request.options.reversible {
            if !try_encode_forward_rct(components, accelerator).map_err(|source| {
                crate::EncodeError::Accelerator {
                    operation: "forward RCT",
                    source,
                }
            })? {
                forward_mct::forward_rct(components);
            }
        } else if !try_encode_forward_ict(components, accelerator).map_err(|source| {
            crate::EncodeError::Accelerator {
                operation: "forward ICT",
                source,
            }
        })? {
            forward_mct::forward_ict(components);
        }
    }
    Ok(profile::elapsed_us(stage_start))
}

fn prepare_dwt_components(
    request: &AcceleratedComponentRequest<'_, '_>,
    mut components: Vec<Vec<f32>>,
    component_bytes: usize,
    plan_bytes: usize,
    accelerator: &mut impl J2kEncodeStageAccelerator,
) -> NativeEncodePipelineResult<(Vec<OwnedDwtComponent>, u128)> {
    let stage_start = profile::profile_now(request.profile_enabled);
    let mut workspace = try_dwt_workspace(
        request,
        components.len(),
        component_bytes,
        plan_bytes,
        accelerator.prefer_parallel_cpu_code_block_fallback(),
    )?;
    for component_index in 0..components.len() {
        let component = core::mem::take(&mut components[component_index]);
        let remaining_component_bytes =
            component_planes_retained_bytes(&components, components.capacity())?;
        let current_component_bytes = checked_element_bytes::<f32>(
            component.capacity(),
            "transform current component samples",
        )?;
        let prior_dwt_bytes = dwt_component_sources_retained_bytes(
            &workspace.decompositions,
            workspace.decompositions.capacity(),
        )?;
        let live_before_dwt = checked_add_bytes(
            checked_add_bytes(
                plan_bytes,
                checked_add_bytes(
                    remaining_component_bytes,
                    current_component_bytes,
                    "DWT input phase",
                )?,
                "DWT input phase",
            )?,
            checked_add_bytes(prior_dwt_bytes, workspace.scratch_bytes, "DWT input phase")?,
            "DWT input phase",
        )?;
        request
            .session
            .checked_phase(live_before_dwt, "native encode packed DWT phase")?;
        workspace.decompositions.push(encode_forward_dwt(
            ForwardDwtRequest {
                origin: request.plan.component_origin(component_index),
                component,
                width: request.width,
                height: request.height,
                num_levels: request.plan.num_levels,
                reversible: request.options.reversible,
                session: request.session,
                retained_base_bytes: live_before_dwt,
                line_scratch: &mut workspace.line_scratch,
                spare: workspace.spare.as_mut(),
            },
            accelerator,
        )?);
        workspace.scratch_bytes =
            dwt_scratch_bytes(&workspace.line_scratch, workspace.spare.as_ref())?;
        let actual_dwt_bytes = dwt_component_sources_retained_bytes(
            &workspace.decompositions,
            workspace.decompositions.capacity(),
        )?;
        request.session.checked_phase(
            checked_add_bytes(
                checked_add_bytes(plan_bytes, remaining_component_bytes, "DWT output phase")?,
                checked_add_bytes(
                    actual_dwt_bytes,
                    workspace.scratch_bytes,
                    "DWT output phase",
                )?,
                "DWT output phase",
            )?,
            "native encode DWT output phase",
        )?;
    }
    drop(components);
    drop(workspace.line_scratch);
    drop(workspace.spare);
    validate_component_sampling_dwt_geometry(
        &workspace.decompositions,
        request.width,
        request.height,
        &request.plan.params.component_sampling,
    )?;
    Ok((workspace.decompositions, profile::elapsed_us(stage_start)))
}

struct DwtWorkspace {
    decompositions: Vec<OwnedDwtComponent>,
    line_scratch: Vec<f32>,
    spare: Option<Vec<f32>>,
    scratch_bytes: usize,
}

fn try_dwt_workspace(
    request: &AcceleratedComponentRequest<'_, '_>,
    component_count: usize,
    component_bytes: usize,
    plan_bytes: usize,
    parallel: bool,
) -> NativeEncodePipelineResult<DwtWorkspace> {
    let requested_owner_bytes = checked_element_bytes::<OwnedDwtComponent>(
        component_count,
        "transform DWT component owners",
    )?;
    let owner_phase_bytes = checked_add_bytes(
        checked_add_bytes(plan_bytes, component_bytes, "DWT owner phase")?,
        requested_owner_bytes,
        "DWT owner phase",
    )?;
    let scratch_count = dwt_scratch_count(
        request,
        crate::j2c::fdwt::packed_dwt_scratch_len,
        owner_phase_bytes,
        parallel,
    )?;
    let requested_scratch_bytes =
        checked_element_bytes::<f32>(scratch_count, "packed DWT line scratch")?;
    request.session.checked_phase(
        checked_add_bytes(
            owner_phase_bytes,
            requested_scratch_bytes,
            "DWT owner phase",
        )?,
        "native encode DWT owner phase",
    )?;
    let mut decompositions = Vec::new();
    decompositions
        .try_reserve_exact(component_count)
        .map_err(|_| {
            host_allocation_failed("transform DWT component owners", requested_owner_bytes)
        })?;
    let mut line_scratch = Vec::new();
    line_scratch
        .try_reserve_exact(scratch_count)
        .map_err(|_| host_allocation_failed("packed DWT line scratch", requested_scratch_bytes))?;
    line_scratch.resize(scratch_count, 0.0);
    let spare = try_dwt_spare(
        request,
        checked_add_bytes(
            owner_phase_bytes,
            requested_scratch_bytes,
            "DWT spare phase",
        )?,
        parallel,
    )?;
    let scratch_bytes = dwt_scratch_bytes(&line_scratch, spare.as_ref())?;
    request.session.checked_phase(
        checked_add_bytes(
            checked_add_bytes(plan_bytes, component_bytes, "DWT scratch phase")?,
            checked_add_bytes(
                checked_element_bytes::<OwnedDwtComponent>(
                    decompositions.capacity(),
                    "transform DWT component owners",
                )?,
                scratch_bytes,
                "DWT scratch phase",
            )?,
            "DWT scratch phase",
        )?,
        "native encode DWT scratch phase",
    )?;
    Ok(DwtWorkspace {
        decompositions,
        line_scratch,
        spare,
        scratch_bytes,
    })
}

/// One strip scratch of `scratch_len` samples per Rayon worker, so the CPU
/// transform runs in parallel, when that fits the cap; otherwise one, so
/// success never depends on the thread count.
fn dwt_scratch_count(
    request: &AcceleratedComponentRequest<'_, '_>,
    scratch_len: fn(u32, u32) -> crate::EncodeResult<usize>,
    owner_phase_bytes: usize,
    parallel: bool,
) -> NativeEncodePipelineResult<usize> {
    let serial = scratch_len(request.width, request.height)?;
    #[cfg(feature = "parallel")]
    if let Some(count) = serial
        .checked_mul(rayon::current_num_threads())
        .filter(|&count| parallel && count > serial)
    {
        let phase_bytes = checked_element_bytes::<f32>(count, "parallel packed DWT scratch")
            .and_then(|bytes| checked_add_bytes(owner_phase_bytes, bytes, "DWT owner phase"));
        match phase_bytes.and_then(|bytes| {
            request
                .session
                .checked_phase(bytes, "native encode DWT owner phase")
        }) {
            Ok(_) => return Ok(count),
            Err(
                crate::EncodeError::AllocationTooLarge { .. }
                | crate::EncodeError::ArithmeticOverflow { .. },
            ) => {}
            Err(error) => return Err(error.into()),
        }
    }
    let _ = (owner_phase_bytes, parallel);
    Ok(serial)
}

/// A plane-sized spare lets the first DWT level run out of place in
/// cache-sized bands when it fits the cap; otherwise the transform runs in
/// place, so success never depends on the headroom. Without decomposition
/// levels no transform runs and no spare is needed.
fn try_dwt_spare(
    request: &AcceleratedComponentRequest<'_, '_>,
    live_bytes: usize,
    parallel: bool,
) -> NativeEncodePipelineResult<Option<Vec<f32>>> {
    if !parallel || request.plan.num_levels == 0 {
        return Ok(None);
    }
    let samples =
        usize::try_from(u64::from(request.width) * u64::from(request.height)).map_err(|_| {
            crate::EncodeError::ArithmeticOverflow {
                what: "out-of-place DWT spare plane",
            }
        })?;
    let bytes = checked_element_bytes::<f32>(samples, "out-of-place DWT spare plane")?;
    match checked_add_bytes(live_bytes, bytes, "DWT spare phase").and_then(|bytes| {
        request
            .session
            .checked_phase(bytes, "native encode DWT spare phase")
    }) {
        Ok(_) => {}
        Err(
            crate::EncodeError::AllocationTooLarge { .. }
            | crate::EncodeError::ArithmeticOverflow { .. },
        ) => return Ok(None),
        Err(error) => return Err(error.into()),
    }
    let mut spare = Vec::new();
    spare
        .try_reserve_exact(samples)
        .map_err(|_| host_allocation_failed("out-of-place DWT spare plane", bytes))?;
    spare.resize(samples, 0.0);
    Ok(Some(spare))
}

fn dwt_scratch_bytes(
    line_scratch: &Vec<f32>,
    spare: Option<&Vec<f32>>,
) -> NativeEncodePipelineResult<usize> {
    Ok(checked_add_bytes(
        checked_element_bytes::<f32>(line_scratch.capacity(), "packed DWT line scratch")?,
        checked_element_bytes::<f32>(spare.map_or(0, Vec::capacity), "DWT spare plane")?,
        "packed DWT scratch",
    )?)
}

#[cfg(test)]
#[path = "accelerator/tests.rs"]
mod tests;