om::sound::filters::Bitcrusher Class Reference

A class that uses quantization-based methods to produce distortion. More...

#include <omSoundBitcrusher.h>

Inheritance diagram for om::sound::filters::Bitcrusher:

Public Types
enum	ClipMode { HARD = 0, INVERT = 1, WRAP = 2 }
	Define the different kinds of distortion effects that this filter can produce. More...

Public Member Functions
	Bitcrusher ()
	Create a new distortion filter with the default input and output gains of 1 and hardness of 0. More...
	Bitcrusher (const Bitcrusher &other)
	Create an exact copy of another bitcrusher. More...
	~Bitcrusher ()
	Destroy this bitcrusher and clean up any resources. More...
Bitcrusher &	operator= (const Bitcrusher &other)
	Assign the state of another bitcrusher to this one. More...
ClipMode	getClipMode () const
	Return the type of clipping that this bitcrusher is using. More...
void	setClipMode (ClipMode newClipMode)
	Return the type of clipping that this bitcrusher is using. More...
Gain	getInputGain () const
	Return the current linear input gain factor of this bitcrusher. More...
Gain	getInputGainDB () const
	Return the current input gain factor in decibels of this bitcrusher. More...
void	setInputGain (Gain newInputGain)
	Set the target linear input gain for this bitcrusher. More...
void	setInputGainDB (Gain newDBInputGain)
	Set the target input gain in decibels for this bitcrusher. More...
Gain	getOutputGain () const
	Return the current linear output gain factor of this bitcrusher. More...
Gain	getOutputGainDB () const
	Return the current output gain factor in decibels of this bitcrusher. More...
void	setOutputGain (Gain newOutputGain)
	Set the target linear output gain for this bitcrusher. More...
void	setOutputGainDB (Gain newDBOutputGain)
	Set the target output gain in decibels for this bitcrusher. More...
Gain	getMix () const
	Return the ratio of input signal to distorted signal sent to the output of the bitcrusher. More...
void	setMix (Gain newMix)
	Set the ratio of input signal to distorted signal sent to the output of the bitcrusher. More...
Gain	getThreshold () const
	Return the linear full-scale value at which clipping first occurs. More...
Gain	getThresholdDB () const
	Return the full-scale value in decibels at which clipping first occurs. More...
void	setThreshold (Gain newThreshold)
	Set the linear full-scale value at which clipping first occurs. More...
void	setThresholdDB (Gain newThresholdDB)
	Set the full-scale value in decibels at which clipping first occurs. More...
Bool	getBitReductionIsEnabled () const
	Return whether or not this bitcrusher's bit reduction stage is enabled. More...
void	setBitReductionIsEnabled (Bool newBitReduceEnabled)
	Set whether or not this bitcrusher's bit reduction stage is enabled. More...
UInt	getBitResolution () const
	Return the amount of dithering that should be applied before bit reduction. More...
void	setBitResolution (UInt newResolution)
	Set the bit resolution of the bit reduction stage. More...
Bool	getDitherIsEnabled () const
	Return whether or not this bitcrusher's dithering stage is enabled. More...
void	setDitherIsEnabled (Bool newDitherEnabled)
	Set whether or not this bitcrusher's dithering stage is enabled. More...
Float	getDitherAmount () const
	Return the amount of dithering that should be applied before bit reduction. More...
void	setDitherAmount (Float newDither)
	Set the amount of dithering that should be applied before bit reduction. More...
UInt	getDownsampling () const
	Return the amount of dithering that should be applied before bit reduction. More...
void	setDownsampling (UInt newDownsampling)
	Set the amount of downsampling performed. More...
Bool	getLowPassIsEnabled () const
	Return whether or not this bitcrusher's low pass filter is enabled. More...
void	setLowPassIsEnabled (Bool newLowPassIsEnabled)
	Set whether or not this bitcrusher's low pass filter is enabled. More...
Float	getLowPassFrequency () const
	Return the low pass filter frequency of this bitcrusher. More...
void	setLowPassFrequency (Float newLowPassFrequency)
	Set the low pass filter frequency of this bitcrusher. More...
Size	getLowPassOrder () const
	Return the low pass filter order of this distortion filter. More...
void	setLowPassOrder (Size newLowPassOrder)
	Set the low pass filter order of this distortion filter. More...
virtual UTF8String	getName () const
	Return a human-readable name for this bitcrusher. More...
virtual UTF8String	getManufacturer () const
	Return the manufacturer name of this bitcrusher. More...
virtual FilterVersion	getVersion () const
	Return an object representing the version of this bitcrusher. More...
virtual FilterCategory	getCategory () const
	Return an object that describes the category of effect that this filter implements. More...
virtual Size	getParameterCount () const
	Return the total number of generic accessible parameters this bitcrusher has. More...
virtual Bool	getParameterInfo (Index parameterIndex, FilterParameterInfo &info) const
	Get information about the bitcrusher parameter at the specified index. More...
virtual Bool	getParameterValueName (Index parameterIndex, const FilterParameter &value, UTF8String &name) const
	Get any special name associated with the specified value of an indexed parameter. More...
Public Member Functions inherited from om::sound::filters::SoundFilter
virtual	~SoundFilter ()
	Destroy this sound filter object. More...
SoundResult	read (SoundBuffer &outputBuffer, Size numSamples)
	Fill the specified output buffer with the requested number of samples, based on internal filter state. More...
SoundResult	read (SoundFrame &outputFrame, Size numSamples)
	Fill the specified output frame with the requested number of samples, based on internal filter state. More...
SoundResult	write (const SoundBuffer &inputBuffer, Size numSamples)
	Process the specified input buffer samples and do something with them. More...
SoundResult	write (const SoundFrame &inputFrame, Size numSamples)
	Process the specified input frame samples and do something with them. More...
SoundResult	process (const SoundBuffer &inputBuffer, SoundBuffer &outputBuffer, Size numSamples)
	Apply this filter to the specified input buffer data, placing the result in the output buffer. More...
SoundResult	process (const SoundBuffer &inputBuffer, SoundFrame &outputFrame, Size numSamples)
	Apply this filter to the specified input buffer data, placing the result in the output frame. More...
SoundResult	process (const SoundFrame &inputFrame, SoundFrame &outputFrame, Size numSamples)
	Apply this filter to the specified input frame data, placing the result in the output frame. More...
SoundResult	process (const SoundFrame &inputBuffer, SoundBuffer &outputBuffer, Size numSamples)
	Apply this filter to the specified input frame data, placing the result in the output buffer. More...
void	reset ()
	Signal to the filter that the audio stream is restarting. More...
UInt64	getFrameIndex () const
	Return the index of the next frame to be processed (or the current one if currently processing). More...
Size	getInputCount () const
	Return the current number of audio inputs that this filter has. More...
virtual UTF8String	getInputName (Index inputIndex) const
	Return a human-readable name of the filter audio input at the specified index. More...
Size	getOutputCount () const
	Return the current number of audio outputs that this filter has. More...
virtual UTF8String	getOutputName (Index outputIndex) const
	Return a human-readable name of the filter audio output at the specified index. More...
Size	getMIDIInputCount () const
	Return the current number of MIDI inputs that this filter has. More...
virtual UTF8String	getMIDIInputName (Index inputIndex) const
	Return a human-readable name of the filter MIDI input at the specified index. More...
Size	getMIDIOutputCount () const
	Return the current number of MIDI outputs that this filter has. More...
virtual UTF8String	getMIDIOutputName (Index outputIndex) const
	Return a human-readable name of the filter MIDI output at the specified index. More...
virtual Time	getLatency () const
	Return a Time value indicating the latency of this sound filter in seconds. More...
virtual Bool	getParameterIndex (const UTF8String &parameterName, Index &parameterIndex) const
	Query the index of the parameter with the specified name. More...
Bool	getParameter (Index parameterIndex, FilterParameter &value) const
	Place the value of the parameter at the specified index in the output parameter. More...
Bool	getParameter (Index parameterIndex, Bool &value) const
	Place the value of the parameter at the specified index in the output parameter. More...
Bool	getParameter (Index parameterIndex, Int64 &value) const
	Place the value of the parameter at the specified index in the output parameter. More...
Bool	getParameter (Index parameterIndex, Float32 &value) const
	Place the value of the parameter at the specified index in the output parameter. More...
Bool	getParameter (Index parameterIndex, Float64 &value) const
	Place the value of the parameter at the specified index in the output parameter. More...
template<typename ParameterType >
Bool	getParameter (const UTF8String &name, ParameterType &value) const
	Place the value of the parameter with the specified name in the output parameter. More...
template<typename ParameterType >
Bool	getParameter (const char *name, ParameterType &value) const
	Place the value of the parameter with the specified name in the output parameter. More...
Bool	setParameter (Index parameterIndex, const FilterParameter &value)
	Attempt to set the parameter value at the specified index. More...
Bool	setParameter (Index parameterIndex, Bool value)
	Attempt to set the parameter value at the specified index. More...
Bool	setParameter (Index parameterIndex, Int64 value)
	Attempt to set the parameter value at the specified index. More...
Bool	setParameter (Index parameterIndex, Float32 value)
	Attempt to set the parameter value at the specified index. More...
Bool	setParameter (Index parameterIndex, Float64 value)
	Attempt to set the parameter value at the specified index. More...
template<typename ParameterType >
Bool	setParameter (const UTF8String &name, ParameterType value)
	Attempt to set the parameter value with the specified name. More...
template<typename ParameterType >
Bool	setParameter (const char *name, ParameterType value)
	Attempt to set the parameter value with the specified name. More...
virtual Bool	writeState (DataOutputStream &stream) const
	Write the current state of this sound filter to a data output stream. More...
virtual Bool	readState (DataInputStream &stream)
	Read a previously saved filter state from the specified data input stream and replace the filter's state. More...
virtual Size	getPresetCount () const
	Return the number of standard configuration presets that this sound filter has. More...
virtual Bool	getPreset (Index presetIndex, FilterPreset &preset) const
	Get the standard preset for this sound filter with the specified index. More...
Bool	getIsSynchronized () const
	Return whether or not this sound filter performs thread synchronization. More...
void	setIsSynchronized (Bool newIsSynchronized)
	Set whether or not this sound filter performs thread synchronization. More...
virtual Bool	allowsInPlaceProcessing () const
	Return whether or not this sound filter can process audio data in-place. More...

Static Public Attributes
static const UTF8String	NAME
	A string indicating the human-readable name of this bitcrusher. More...
static const UTF8String	MANUFACTURER
	A string indicating the manufacturer name of this bitcrusher. More...
static const FilterVersion	VERSION
	An object indicating the version of this distortion filter. More...
Static Public Attributes inherited from om::sound::filters::SoundFilter
static const om::resources::ResourceType	RESOURCE_TYPE
	The resource type for a sound filter. More...

Additional Inherited Members
Static Public Member Functions inherited from om::sound::filters::SoundFilter
static Size	getMaximumNumberOfInputs ()
	Return the maximum number of audio inputs that a SoundFilter can support. More...
static Size	getMaximumNumberOfOutputs ()
	Return the maximum number of audio outputs that a SoundFilter can support. More...
static Size	getMaximumNumberOfMIDIInputs ()
	Return the maximum number of MIDI inputs that a SoundFilter can support. More...
static Size	getMaximumNumberOfMIDIOutputs ()
	Return the maximum number of MIDI outputs that a SoundFilter can support. More...
Protected Member Functions inherited from om::sound::filters::SoundFilter
	SoundFilter ()
	Create a new sound filter with 1 audio input and output, and no MIDI inputs or outputs. More...
	SoundFilter (Size numInputs, Size numOutputs)
	Create a new sound filter with the specified number of audio inputs and outputs. More...
	SoundFilter (Size numInputs, Size numOutputs, Size numMIDIInputs, Size numMIDIOutputs)
	Create a new sound filter with the specified number of audio inputs and outputs. More...
void	setInputCount (Size newNumInputs)
	Set the number of inputs that this filter should have. More...
void	setOutputCount (Size newNumOutputs)
	Set the number of outputs that this filter should have. More...
void	setMIDIInputCount (Size newNumMIDIInputs)
	Set the number of MIDI inputs that this filter should have. More...
void	setMIDIOutputCount (Size newNumMIDIOutputs)
	Set the number of MIDI outputs that this filter should have. More...
Bool	isFirstFrame () const
	Return whether or not the filter's next frame to be processed is also its first frame. More...
void	lockMutex () const
	Acquire a mutex which handles subclass rendering parameter synchronization. More...
void	unlockMutex () const
	Release a mutex which handles subclass rendering parameter synchronization. More...

Detailed Description

A class that uses quantization-based methods to produce distortion.

The class uses a conversion to/from a lower bit-depth audio stream in order to produce unique kinds of distortion. It also provides a way to process that audio through a conversion to a lower sample rate, effectively producing other kinds of distortion.

Member Enumeration Documentation

enum om::sound::filters::Bitcrusher::ClipMode

Define the different kinds of distortion effects that this filter can produce.

Enumerator
HARD	A kind of clipping where the waveform is chopped off when it goes above the threshold.
INVERT	A kind of clipping where the waveform is inverted when it goes above the threshold.
WRAP	A kind of clipping where the waveform wraps around to 0 when it goes above the threshold.

Constructor & Destructor Documentation

om::sound::filters::Bitcrusher::Bitcrusher

(

)

Create a new distortion filter with the default input and output gains of 1 and hardness of 0.

om::sound::filters::Bitcrusher::Bitcrusher

(

const Bitcrusher &

other

)

Create an exact copy of another bitcrusher.

om::sound::filters::Bitcrusher::~Bitcrusher

(

)

Destroy this bitcrusher and clean up any resources.

Member Function Documentation

Bitcrusher& om::sound::filters::Bitcrusher::operator=

(

const Bitcrusher &

other

)

Assign the state of another bitcrusher to this one.

ClipMode om::sound::filters::Bitcrusher::getClipMode ( ) const

inline

Return the type of clipping that this bitcrusher is using.

This value determines what happens when the waveform exceeds the clipping threshold.

void om::sound::filters::Bitcrusher::setClipMode ( ClipMode  newClipMode )

inline

Return the type of clipping that this bitcrusher is using.

This value determines what happens when the waveform exceeds the clipping threshold.

Gain om::sound::filters::Bitcrusher::getInputGain ( ) const

inline

Return the current linear input gain factor of this bitcrusher.

This is the gain applied to the input signal before being sent to the clipping function. A higher value will result in more noticeable clipping.

Gain om::sound::filters::Bitcrusher::getInputGainDB ( ) const

inline

Return the current input gain factor in decibels of this bitcrusher.

This is the gain applied to the input signal before being sent to the clipping function. A higher value will result in more noticeable clipping.

void om::sound::filters::Bitcrusher::setInputGain ( Gain  newInputGain )

inline

Set the target linear input gain for this bitcrusher.

This is the gain applied to the input signal before being sent to the clipping function. A higher value will result in more noticeable clipping.

void om::sound::filters::Bitcrusher::setInputGainDB ( Gain  newDBInputGain )

inline

Set the target input gain in decibels for this bitcrusher.

This is the gain applied to the input signal before being sent to the clipping function. A higher value will result in more noticeable clipping.

Gain om::sound::filters::Bitcrusher::getOutputGain ( ) const

inline

Return the current linear output gain factor of this bitcrusher.

This is the gain applied to the signal after being sent to the clipping function. This value is used to modify the final level of the clipped signal.

Gain om::sound::filters::Bitcrusher::getOutputGainDB ( ) const

inline

Return the current output gain factor in decibels of this bitcrusher.

This is the gain applied to the signal after being sent to the clipping function. This value is used to modify the final level of the clipped signal.

void om::sound::filters::Bitcrusher::setOutputGain ( Gain  newOutputGain )

inline

Set the target linear output gain for this bitcrusher.

This is the gain applied to the signal after being sent to the clipping function. This value is used to modify the final level of the clipped signal.

void om::sound::filters::Bitcrusher::setOutputGainDB ( Gain  newDBOutputGain )

inline

Set the target output gain in decibels for this bitcrusher.

This is the gain applied to the signal after being sent to the clipping function. This value is used to modify the final level of the clipped signal.

Gain om::sound::filters::Bitcrusher::getMix ( ) const

inline

Return the ratio of input signal to distorted signal sent to the output of the bitcrusher.

Valid mix values are in the range [0,1]. A mix value of 1 indicates that only the output of the distortion should be heard at the output, while a value of 0 indicates that only the input of the distortion should be heard at the output. A value of 0.5 indicates that both should be mixed together equally at -6dB.

void om::sound::filters::Bitcrusher::setMix ( Gain  newMix )

inline

Set the ratio of input signal to distorted signal sent to the output of the bitcrusher.

Valid mix values are in the range [0,1]. A mix value of 1 indicates that only the output of the distortion should be heard at the output, while a value of 0 indicates that only the input of the distortion should be heard at the output. A value of 0.5 indicates that both should be mixed together equally at -6dB.

The new mix value is clamped to the valid range of [0,1].

Gain om::sound::filters::Bitcrusher::getThreshold ( ) const

inline

Return the linear full-scale value at which clipping first occurs.

Gain om::sound::filters::Bitcrusher::getThresholdDB ( ) const

inline

Return the full-scale value in decibels at which clipping first occurs.

void om::sound::filters::Bitcrusher::setThreshold ( Gain  newThreshold )

inline

Set the linear full-scale value at which clipping first occurs.

The value is clamped to the valid range of [0,infinity] before being stored.

void om::sound::filters::Bitcrusher::setThresholdDB ( Gain  newThresholdDB )

inline

Set the full-scale value in decibels at which clipping first occurs.

Bool om::sound::filters::Bitcrusher::getBitReductionIsEnabled ( ) const

inline

Return whether or not this bitcrusher's bit reduction stage is enabled.

void om::sound::filters::Bitcrusher::setBitReductionIsEnabled ( Bool  newBitReduceEnabled )

inline

Set whether or not this bitcrusher's bit reduction stage is enabled.

UInt om::sound::filters::Bitcrusher::getBitResolution ( ) const

inline

Return the amount of dithering that should be applied before bit reduction.

Valid dithering amounts are in the range [1,24].

This value indicates the number of bits of precision used when reducing the bit depth of the input signal.

void om::sound::filters::Bitcrusher::setBitResolution ( UInt  newResolution )

inline

Set the bit resolution of the bit reduction stage.

Valid bit resolutions are in the range [1,24].

This value indicates the number of bits of precision used when reducing the bit depth of the input signal.

The new bit resolution is clamped to the valid range of [1,24].

Bool om::sound::filters::Bitcrusher::getDitherIsEnabled ( ) const

inline

Return whether or not this bitcrusher's dithering stage is enabled.

void om::sound::filters::Bitcrusher::setDitherIsEnabled ( Bool  newDitherEnabled )

inline

Set whether or not this bitcrusher's dithering stage is enabled.

Float om::sound::filters::Bitcrusher::getDitherAmount ( ) const

inline

Return the amount of dithering that should be applied before bit reduction.

Valid dithering amounts are in the range [0,1].

A dither amount of 1 indicates that 100% of the dithering for the current bit resolution should be applied. A value of 0 indicates that no dithering should be applied.

void om::sound::filters::Bitcrusher::setDitherAmount ( Float  newDither )

inline

Set the amount of dithering that should be applied before bit reduction.

Valid dithering amounts are in the range [0,1].

A dither amount of 1 indicates that 100% of the dithering for the current bit resolution should be applied. A value of 0 indicates that no dithering should be applied.

The new dithering amount is clamped to the valid range of [0,1].

UInt om::sound::filters::Bitcrusher::getDownsampling ( ) const

inline

Return the amount of dithering that should be applied before bit reduction.

Valid dithering amounts are in the range [1,24].

This value indicates the effective sample rate divisor used. A value of 1 indicates the current sampling rate is used. A value of 2 indicates the sampling rate is halved, etc.

void om::sound::filters::Bitcrusher::setDownsampling ( UInt  newDownsampling )

inline

Set the amount of downsampling performed.

Valid downsampling amounts are in the range [1,24].

This value indicates the effective sample rate divisor used. A value of 1 indicates the current sampling rate is used. A value of 2 indicates the sampling rate is halved, etc.

The new downsampling amount is clamped to the valid range of [1,24].

Bool om::sound::filters::Bitcrusher::getLowPassIsEnabled ( ) const

inline

Return whether or not this bitcrusher's low pass filter is enabled.

void om::sound::filters::Bitcrusher::setLowPassIsEnabled ( Bool  newLowPassIsEnabled )

inline

Set whether or not this bitcrusher's low pass filter is enabled.

Float om::sound::filters::Bitcrusher::getLowPassFrequency ( ) const

inline

Return the low pass filter frequency of this bitcrusher.

void om::sound::filters::Bitcrusher::setLowPassFrequency ( Float  newLowPassFrequency )

inline

Set the low pass filter frequency of this bitcrusher.

The new low pass frequency is clamped to the range [0,infinity].

Size om::sound::filters::Bitcrusher::getLowPassOrder ( ) const

inline

Return the low pass filter order of this distortion filter.

void om::sound::filters::Bitcrusher::setLowPassOrder ( Size  newLowPassOrder )

inline

Set the low pass filter order of this distortion filter.

The new low pass order is clamped to the range [1,100].

virtual UTF8String om::sound::filters::Bitcrusher::getName ( ) const

virtual

Return a human-readable name for this bitcrusher.

The method returns the string "Bitcrusher".

Reimplemented from om::sound::filters::SoundFilter.

virtual UTF8String om::sound::filters::Bitcrusher::getManufacturer ( ) const

virtual

Return the manufacturer name of this bitcrusher.

The method returns the string "Om Sound".

Reimplemented from om::sound::filters::SoundFilter.

virtual FilterVersion om::sound::filters::Bitcrusher::getVersion ( ) const

virtual

Return an object representing the version of this bitcrusher.

Reimplemented from om::sound::filters::SoundFilter.

virtual FilterCategory om::sound::filters::Bitcrusher::getCategory ( ) const

virtual

Return an object that describes the category of effect that this filter implements.

This method returns the value FilterCategory::DISTORTION.

Reimplemented from om::sound::filters::SoundFilter.

virtual Size om::sound::filters::Bitcrusher::getParameterCount ( ) const

virtual

Return the total number of generic accessible parameters this bitcrusher has.

Reimplemented from om::sound::filters::SoundFilter.

virtual Bool om::sound::filters::Bitcrusher::getParameterInfo ( Index  parameterIndex, FilterParameterInfo &  info  ) const

virtual

Get information about the bitcrusher parameter at the specified index.

Reimplemented from om::sound::filters::SoundFilter.

virtual Bool om::sound::filters::Bitcrusher::getParameterValueName ( Index  parameterIndex, const FilterParameter &  value, UTF8String &  name  ) const

virtual

Get any special name associated with the specified value of an indexed parameter.

Reimplemented from om::sound::filters::SoundFilter.

Member Data Documentation

const UTF8String om::sound::filters::Bitcrusher::NAME

static

A string indicating the human-readable name of this bitcrusher.

const UTF8String om::sound::filters::Bitcrusher::MANUFACTURER

static

A string indicating the manufacturer name of this bitcrusher.

const FilterVersion om::sound::filters::Bitcrusher::VERSION

static

An object indicating the version of this distortion filter.

---

The documentation for this class was generated from the following file:

• omSoundBitcrusher.h