A class that implements a band-pass or band-reject filter of various types. More...

#include <omSoundBandFilter.h>

Inheritance diagram for om::sound::filters::BandFilter:

Public Types
enum	Type { BUTTERWORTH = 0, LINKWITZ_RILEY = 1, CHEBYSHEV_I = 2 }
	An enum type that denotes a certain class of band filter. More...

enum	Direction { BAND_PASS = 0, BAND_REJECT = 1 }
	An enum type that specifies if a filter is high-pass or low-pass. More...

Public Member Functions
	BandFilter ()
	Create a default 1st order butterworth band pass filter with band frequencies at 0 Hz and 20000 Hz. More...

	BandFilter (Type newFilterType, Direction newFilterDirection, Size newFilterOrder, Float newFrequency1, Float newFrequency2)
	Create a band filter with the specified type, direction, order, and corner frequencies. More...

Type	getType () const
	Return the type of filter that is being used. More...

void	setType (Type newFilterType)
	Set the type of filter that is being used. More...

Direction	getDirection () const
	Return the direction of the filter that is being used. More...

void	setDirection (Direction newFilterDirection)
	Set the type of filter that is being used. More...

Size	getOrder () const
	Return the order of this band filter. More...

void	setOrder (Size newFilterOrder)
	Set the order of this band filter. More...

Size	getMaximumOrder () const
	Return the maximum filter order allowed. More...

Float	getFrequency1 () const
	Return the first corner frequency of this band filter. More...

void	setFrequency1 (Float newCornerFrequency)
	Set the first corner frequency of this band filter. More...

Float	getFrequency2 () const
	Return the first corner frequency of this band filter. More...

void	setFrequency2 (Float newCornerFrequency)
	Set the first corner frequency of this band filter. More...

Float	getRipple () const
	Return the ripple of this band filter in dB. More...

void	setRipple (Float newRipple)
	Set the ripple of this band filter in dB. More...

virtual UTF8String	getName () const
	Return a human-readable name for this band filter. More...

virtual UTF8String	getManufacturer () const
	Return the manufacturer name of this band filter. More...

virtual FilterVersion	getVersion () const
	Return an object representing the version of this band filter. More...

virtual FilterCategory	getCategory () const
	Return an object that describes the category of effect that this filter implements. More...

virtual Bool	allowsInPlaceProcessing () const
	Return whether or not this band filter can process audio data in-place. More...

virtual Size	getParameterCount () const
	Return the total number of generic accessible parameters this filter has. More...

virtual Bool	getParameterInfo (Index parameterIndex, FilterParameterInfo &info) const
	Get information about the 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...

Static Public Attributes
static const UTF8String	NAME
	A string indicating the human-readable name of this band filter. More...

static const UTF8String	MANUFACTURER
	A string indicating the manufacturer name of this band filter. More...

static const FilterVersion	VERSION
	An object indicating the version of this band 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 implements a band-pass or band-reject filter of various types.

Member Enumeration Documentation

enum om::sound::filters::BandFilter::Type

An enum type that denotes a certain class of band filter.

Enumerator

BUTTERWORTH

A type of band filter that uses a Bufferworth design.

A Butterworth filter is a type of filter that is designed to be as flat as possible in the passband with no ripple in the stopband. The filter is -3dB at the corner frequency.

LINKWITZ_RILEY

A type of band filter that uses a Linkwitz-Riley design.

A Linkwitz-Riley filter is a type of filter that is designed to be allpass when summed with a corresponding opposite filter at the crossover frequency. The filter is -6dB at the corner frequency.

Linkwitz-Riley filters only support orders 2, 4, 6, and 8 because of their special properties. Attempting to use an invalid order will result in the next highest valid order being used.

CHEBYSHEV_I

A type of band filter that uses a Chebyshev type I design.

A Chebyshev type I filter is a filter that has a steeper rolloff but at the expense of ripple in the passband.

enum om::sound::filters::BandFilter::Direction

An enum type that specifies if a filter is high-pass or low-pass.

Enumerator
BAND_PASS	A type of filter that filters out all frequencies outside the cutoff frequencies.
BAND_REJECT	A type of filter that filters out all frequencies between the cutoff frequencies.

Constructor & Destructor Documentation

om::sound::filters::BandFilter::BandFilter ( )

Create a default 1st order butterworth band pass filter with band frequencies at 0 Hz and 20000 Hz.

om::sound::filters::BandFilter::BandFilter	(	Type	newFilterType,
		Direction	newFilterDirection,
		Size	newFilterOrder,
		Float	newFrequency1,
		Float	newFrequency2
	)

Create a band filter with the specified type, direction, order, and corner frequencies.

The filter order is clamped between 1 and the maximum allowed filter order, and the corner frequencies are clamped to the range of [0,+infinity].

Member Function Documentation

Type om::sound::filters::BandFilter::getType ( ) const

inline

Return the type of filter that is being used.

Since different types of filters have different characteristics in frequency and phase response, this value allows the user to pick the filter type best suited for their needs.

void om::sound::filters::BandFilter::setType ( Type newFilterType )

inline

Set the type of filter that is being used.

Since different types of filters have different characteristics in frequency and phase response, this value allows the user to pick the filter type best suited for their needs.

Direction om::sound::filters::BandFilter::getDirection ( ) const

inline

Return the direction of the filter that is being used.

This value determines whether the filter behaves as a high-pass or low-pass filter.

void om::sound::filters::BandFilter::setDirection ( Direction newFilterDirection )

inline

Set the type of filter that is being used.

This value determines whether the filter behaves as a high-pass or low-pass filter.

Size om::sound::filters::BandFilter::getOrder ( ) const

inline

Return the order of this band filter.

void om::sound::filters::BandFilter::setOrder ( Size newFilterOrder )

inline

Set the order of this band filter.

If the specified order is not supported by this filter, the closest order to the desired order is used.

The new filter order is clamped betwee 1 and the maximum allowed filter order.

Size om::sound::filters::BandFilter::getMaximumOrder ( ) const

inline

Return the maximum filter order allowed.

All created filters will have an order less than or equal to this value and it is impossible to set the order of a filter to be greater than this value.

Float om::sound::filters::BandFilter::getFrequency1 ( ) const

inline

Return the first corner frequency of this band filter.

This is the frequency at which the frequency begins to be cut off by the filter. This is usually the point at which the filter is -3dB down, but can be -6dB or other for some filter types.

void om::sound::filters::BandFilter::setFrequency1 ( Float newCornerFrequency )

inline

Set the first corner frequency of this band filter.

This is the frequency at which the frequency begins to be cut off by the filter. This is usually the point at which the filter is -3dB down, but can be -6dB or other for some filter types.

The new corner frequency is clamped to be in the range [0,+infinity].

Float om::sound::filters::BandFilter::getFrequency2 ( ) const

inline

Return the first corner frequency of this band filter.

This is the frequency at which the frequency begins to be cut off by the filter. This is usually the point at which the filter is -3dB down, but can be -6dB or other for some filter types.

void om::sound::filters::BandFilter::setFrequency2 ( Float newCornerFrequency )

inline

Set the first corner frequency of this band filter.

This is the frequency at which the frequency begins to be cut off by the filter. This is usually the point at which the filter is -3dB down, but can be -6dB or other for some filter types.

The new corner frequency is clamped to be in the range [0,+infinity].

Float om::sound::filters::BandFilter::getRipple ( ) const

inline

Return the ripple of this band filter in dB.

This parameter is only used by the Chebyshev type I and type II filters. It determines the amount of ripple in the passband (for type I) or in the stopband (for type II). A smaller ripple results in a slower rolloff in the frequency response for any given filter order.

The ripple amount is initially equal to 1 dB and must be greater than 0.

void om::sound::filters::BandFilter::setRipple ( Float newRipple )

inline

Set the ripple of this band filter in dB.

This parameter is only used by the Chebyshev type I and type II filters. It determines the amount of ripple in the passband (for type I) or in the stopband (for type II). A smaller ripple results in a slower rolloff in the frequency response for any given filter order.

The ripple amount is initially equal to 1 dB and is clamped to be greater than 0.

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

virtual

Return a human-readable name for this band filter.

The method returns the string "Band Filter".

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

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

virtual

Return the manufacturer name of this band filter.

The method returns the string "Om Sound".

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

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