Struct HCDistortion 

pub struct HCDistortion { /* private fields */ }

Hard-Clipping Distortion Effect

HCDistortion implements a classic hard-clipping distortion pedal with two controllable parameters: Drive (clipping threshold) and Level (output boost).

Signal Chain

The processing happens in two stages:

1. Hard Clipping

   • Any sample whose absolute value exceeds the threshold is clamped to ±threshold
   • This produces the characteristic flat-top waveform of hard clipping distortion
   • Lower thresholds produce heavier distortion (more clipping)
   • Higher thresholds produce lighter distortion (less clipping)

2. Output Level Boost (via GainProcessor)

   • After clipping, the signal passes through a GainProcessor
   • The gain is controlled by a normalised level parameter [0.0, 1.0]
   • Maps to a linear gain range of 1.0 (unity) to 2.0 (double amplitude)
   • Uses smoothed transitions (one-pole filter) to avoid clicks and pops

Parameter Ranges

Parameter	Range	UI Display	Effect
threshold	(0.0, 1.0]	Drive 0–100%	Lower = heavier distortion
level	[0.0, 1.0]	Level 0–100%	0 = no boost, 1.0 = ×2 boost

Thread-Safe Atomic Updates

All mutable parameters are stored as lock-free atomics:

• is_active: Arc<AtomicBool> — enable/bypass the effect
• limit: Arc<AtomicF32> — clipping threshold (shared with f32_params)
• level: Arc<AtomicF32> — internal gain value [1.0, 2.0] (shared with GainProcessor)

This allows the audio thread to read parameter changes from command handlers without any locks or synchronisation overhead.

Implementations

impl HCDistortion

pub fn new( id: u32, name: String, is_active: bool, threshold: f32, level: f32, color: String, ) -> Self

Creates a new HCDistortion effect.

Parameters

• id — Unique identifier for this effect instance
• name — Human-readable name (e.g., “Distortion”)
• is_active — Whether the effect is initially enabled
• threshold — Clip level in (0.0, 1.0]. Will be clamped to [0.001, 1.0]. Lower values produce heavier distortion.
• level — Initial output boost in [0.0, 1.0]. Will be clamped to [0.0, 1.0]. Maps internally to gain [1.0, 2.0].
• color — Hex colour string for UI pedal chassis (e.g., "#e67e22")

pub fn threshold(&self) -> f32

Returns the current clipping threshold in range (0.0, 1.0].

Returns

The threshold value; lower values produce heavier clipping.

pub fn set_threshold(&self, threshold: f32)

Sets the clipping threshold. Value is clamped to [0.001, 1.0].

The change takes effect on the very next audio sample — no synchronisation needed.

Parameters

• threshold — New clipping level in (0.0, 1.0]

pub fn level(&self) -> f32

Returns the normalised output level in range [0.0, 1.0].

Internally the gain is stored as [1.0, 2.0]; this method reverses that mapping to give the external normalised value.

Returns

Normalised level: 0.0 = no boost (unity gain), 1.0 = ×2.0 boost

pub fn set_level(&self, level: f32)

Sets the output level from a normalised value [0.0, 1.0].

Internally maps to gain [1.0, 2.0] and stores it in the atomic. The change takes effect on the very next audio sample — no synchronisation needed.

Parameters

• level — Normalised level in [0.0, 1.0]. Will be clamped.

Trait Implementations

impl AudioProcessor for HCDistortion

fn process(&mut self, sample: f32) -> f32

Processes a single audio sample through hard clipping and level boost.

Algorithm

1. Load clipping threshold atomically (lock-free)
2. Clamp sample to [-threshold, threshold] (hard clipping)
3. Apply gain boost via the GainProcessor with smoothed transitions

Parameters

• sample — Normalised audio sample, typically -1.0 to 1.0

Returns

Processed sample: clipped and boosted by the level knob

impl Effect for HCDistortion

fn f32_params(&self) -> HashMap<&'static str, Arc<AtomicF32>>

Returns a map of named f32 parameters for command infrastructure.

This enables the generic command dispatcher to update effect parameters without needing to know about specific effect types.

Returns

HashMap with keys:

• "threshold" — points to limit atomic; external code can write new thresholds
• "level" — points to internal gain atomic [1.0, 2.0]

Note

The "level" key stores the raw gain value. Command handlers should convert the external normalised [0, 1] range to internal gain [1, 2] before writing.

fn to_dto(&self) -> EffectDto

Converts this effect into its serialisable DTO representation.

Called when sending effect state to the frontend or external clients.

Returns

EffectDto::HCDistortion with all current parameters

fn process_if_active(&mut self, sample: f32) -> f32

Processes a sample only if the effect is currently active.

If inactive (bypassed), the sample is returned unchanged.

Parameters

• sample — Input audio sample

Returns

Processed sample if active, otherwise the input unchanged (unity bypass)

fn id(&self) -> u32

Returns the unique numeric identifier for this specific effect instance.

fn name(&self) -> &str

Returns the human-readable name of the effect (e.g., “Overdrive”, “Delay”).

fn get_color(&self) -> String

Returns a color code (hex) associated with this effect for UI representation.

fn active_flag(&self) -> Arc<AtomicBool>

Returns the shared Arc<AtomicBool> that drives process_if_active. Command handlers write to it; the audio thread reads it lock-free.

fn is_active(&self) -> bool

Returns true if the effect is currently enabled and processing audio.

fn set_active(&self, active: bool)

Sets whether the effect is active or bypassed.

fn u32_params(&self) -> HashMap<&'static str, Arc<AtomicU32>>

Returns named u32 parameter Arcs shared with the audio thread. Defaults to an empty map — override for effects with extra parameters.