A class that represents a lightweight audio processing unit. More...

#include <omSoundFilter.h>

Inheritance diagram for om::sound::filters::SoundFilter:

Public Member Functions
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 UTF8String	getName () const
	Return a human-readable name for this filter. More...

virtual UTF8String	getManufacturer () const
	Return a human-readable name for this filter's manufacturer. More...

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

virtual Time	getLatency () const
	Return a Time value indicating the latency of this sound filter in seconds. More...

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

virtual Bool	getParameterIndex (const UTF8String &parameterName, Index &parameterIndex) const
	Query the index of the parameter with the specified name. More...

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

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...

virtual FilterCategory	getCategory () const
	Return an object that describes the category of effect that this filter implements. 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 Member Functions
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...

Static Public Attributes
static const om::resources::ResourceType	RESOURCE_TYPE
	The resource type for a sound filter. More...

Protected Member Functions
	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...

virtual Bool	getParameterValue (Index parameterIndex, FilterParameter &value) const
	Place the value of the parameter at the specified index in the output parameter. More...

virtual Bool	setParameterValue (Index parameterIndex, const FilterParameter &value)
	Attempt to set the parameter value at the specified index. More...

virtual void	resetStream ()
	A method that is called whenever the filter's stream of audio is being reset. More...

virtual SoundResult	processFrame (const SoundFrame &inputFrame, SoundFrame &outputFrame, Size numSamples)=0
	Process the given input frame and write the resulting audio to the given output frame. 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 represents a lightweight audio processing unit.

A SoundFilter object takes a buffer of N input channels and performs some DSP computation on those samples and places some number of samples in an output buffer of M channels.

Typically, implementors of this class's interface should perform a single DSP computation such as applying an EQ filter or delay filter, but they are also allowed to perform sample rate conversion, pitch shit, and other time-related functions.

The number of input and output channels do not have to match. Each filter is responsible for determining the format of its output(s) given the input buffer format(s). This includes the channel count, number of samples, and sample rate.

For filters that have no inputs that could inform the output format (such as a tone generator or sound player), the filter should use the format of the output buffer(s) as a hint for determining the output format. The filter is of course able to ignore this hint and change the buffer format(s) to something else.

The SoundFilter object is expected to tolerate input buffers of any sample rate. If the sample rate or channel count of a stream changes mid-stream, the sound filter is allowed to reset its internal processing (possibly with audible glitches).

Constructor & Destructor Documentation

virtual om::sound::filters::SoundFilter::~SoundFilter ( )

virtual

Destroy this sound filter object.

om::sound::filters::SoundFilter::SoundFilter ( )

protected

Create a new sound filter with 1 audio input and output, and no MIDI inputs or outputs.

om::sound::filters::SoundFilter::SoundFilter	(	Size	numInputs,
		Size	numOutputs
	)

protected

Create a new sound filter with the specified number of audio inputs and outputs.

om::sound::filters::SoundFilter::SoundFilter	(	Size	numInputs,
		Size	numOutputs,
		Size	numMIDIInputs,
		Size	numMIDIOutputs
	)

protected

Create a new sound filter with the specified number of audio inputs and outputs.

Member Function Documentation

SoundResult om::sound::filters::SoundFilter::read	(	SoundBuffer &	outputBuffer,
		Size	numSamples
	)

Fill the specified output buffer with the requested number of samples, based on internal filter state.

Calling this method causes this filter to behave as a sound output (with no input). Samples are read from the filter and written to the output buffer. The filter is not provided any input buffers and must generate its own output sample data.

The output buffer is enlarged to the specified number of samples if it is smaller than that number of samples. The method returns the number of valid samples written to the output buffer.

SoundResult om::sound::filters::SoundFilter::read	(	SoundFrame &	outputFrame,
		Size	numSamples
	)

Fill the specified output frame with the requested number of samples, based on internal filter state.

Calling this method causes this filter to behave as a sound output (with no input). Samples are read from the filter and written to the output frame. The filter is not provided any input buffers and must generate its own output sample data.

The output frame is enlarged to the specified number of samples if it is smaller than that number of samples. The method returns the number of valid samples written to the output frame.

SoundResult om::sound::filters::SoundFilter::write	(	const SoundBuffer &	inputBuffer,
		Size	numSamples
	)

Process the specified input buffer samples and do something with them.

The specified number of samples to process is clamped to be no larger than the size of the input buffer. Calling this method causes this filter to behave as a sound input (with no output). The default implementation doesn't do anything with the input samples but classes may inherit from this class to provide specific functionality (such as a signal analyzer or sound file encoder).

SoundResult om::sound::filters::SoundFilter::write	(	const SoundFrame &	inputFrame,
		Size	numSamples
	)

Process the specified input frame samples and do something with them.

The specified number of samples to process is clamped to be no larger than the size of the input frame. Calling this method causes this filter to behave as a sound input (with no output). The default implementation doesn't do anything with the input samples but classes may inherit from this class to provide specific functionality (such as a signal analyzer or sound file encoder).

SoundResult om::sound::filters::SoundFilter::process	(	const SoundBuffer &	inputBuffer,
		SoundBuffer &	outputBuffer,
		Size	numSamples
	)

Apply this filter to the specified input buffer data, placing the result in the output buffer.

The specified number of samples to process is clamped to be no larger than the size of the input buffer.

Call this method when using a sound filter that has 1 input and 1 output.

This method returns an object indicating the result of the filter processing step. This result contains the number of valid samples that were placed in the output buffer.

SoundResult om::sound::filters::SoundFilter::process	(	const SoundBuffer &	inputBuffer,
		SoundFrame &	outputFrame,
		Size	numSamples
	)

Apply this filter to the specified input buffer data, placing the result in the output frame.

The specified number of samples to process is clamped to be no larger than the size of the input buffer.

Call this method when using a sound filter that has 1 input and more than one output.

This method returns an object indicating the result of the filter processing step. This result contains the number of valid samples that were placed in the output frame.

SoundResult om::sound::filters::SoundFilter::process	(	const SoundFrame &	inputFrame,
		SoundFrame &	outputFrame,
		Size	numSamples
	)

Apply this filter to the specified input frame data, placing the result in the output frame.

The specified number of samples to process is clamped to be no larger than the size of the smallest buffer in the input frame.

Call this method when using a sound filter that has multiple inputs or multiple outputs.

This method returns an object indicating the result of the filter processing step. This result contains the number of valid samples that were placed in the output frame.

SoundResult om::sound::filters::SoundFilter::process	(	const SoundFrame &	inputBuffer,
		SoundBuffer &	outputBuffer,
		Size	numSamples
	)

Apply this filter to the specified input frame data, placing the result in the output buffer.

The specified number of samples to process is clamped to be no larger than the size of the input frame.

Call this method when using a sound filter that has more than one input and only one output.

This method returns an object indicating the result of the filter processing step. This result contains the number of valid samples that were placed in the output buffer.

void om::sound::filters::SoundFilter::reset ( )

Signal to the filter that the audio stream is restarting.

This method allows the filter to reset all parameter interpolation and processing to its initial state to avoid coloration from previous audio or parameter values.

UInt64 om::sound::filters::SoundFilter::getFrameIndex ( ) const

inline

Return the index of the next frame to be processed (or the current one if currently processing).

Size om::sound::filters::SoundFilter::getInputCount ( ) const

inline

Return the current number of audio inputs that this filter has.

virtual UTF8String om::sound::filters::SoundFilter::getInputName ( Index inputIndex ) const

virtual

Return a human-readable name of the filter audio input at the specified index.

The default implementation for this method returns a string consisting of 'Input N' where N is the input index when the number of inputs is more than 1. If the number of inputs is 1, 'Main Input' is returned. If the index is invalid, the empty string is returned.

Subclasses may override this method to return a more descriptive name (such as 'Sidechain').

Reimplemented in om::sound::filters::Compressor, om::sound::filters::Expander, and om::sound::filters::FilterSeries.

Size om::sound::filters::SoundFilter::getOutputCount ( ) const

inline

Return the current number of audio outputs that this filter has.

virtual UTF8String om::sound::filters::SoundFilter::getOutputName ( Index outputIndex ) const

virtual

Return a human-readable name of the filter audio output at the specified index.

The default implementation for this method returns a string consisting of 'Output N' where N is the output index when the number of outputs is more than 1. If the number of outputs is 1, 'Main Output' is returned. If the index is invalid, the empty string is returned.

Subclasses may override this method to return a more descriptive name.

Reimplemented in om::sound::filters::Crossover, and om::sound::filters::FilterSeries.

Size om::sound::filters::SoundFilter::getMIDIInputCount ( ) const

inline

Return the current number of MIDI inputs that this filter has.

virtual UTF8String om::sound::filters::SoundFilter::getMIDIInputName ( Index inputIndex ) const

virtual

Return a human-readable name of the filter MIDI input at the specified index.

The default implementation for this method returns a string consisting of 'MIDI Input N' where N is the input index when the number of MIDI inputs is more than 1. If the number of inputs is 1, 'Main MIDI Input' is returned. If the index is invalid, the empty string is returned.

Subclasses may override this method to return a more descriptive name.

Size om::sound::filters::SoundFilter::getMIDIOutputCount ( ) const

inline

Return the current number of MIDI outputs that this filter has.

virtual UTF8String om::sound::filters::SoundFilter::getMIDIOutputName ( Index outputIndex ) const

virtual

Return a human-readable name of the filter MIDI output at the specified index.

The default implementation for this method returns a string consisting of 'MIDI Output N' where N is the output index when the number of MIDI outputs is more than 1. If the number of outputs is 1, 'Main MIDI Output' is returned. If the index is invalid, the empty string is returned.

Subclasses may override this method to return a more descriptive name.

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

virtual

Return a human-readable name for this filter.

The default implementation uses typeinfo to determine the actual subclass type of the filter and returns a string representing that type. This string usually is not formatted properly so the filter subclass should override this method to return a proper name.

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

virtual

Return a human-readable name for this filter's manufacturer.

The default implementation returns the empty string.

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

virtual

Return an object representing the version of this sound filter.

The default version returned is '0.0.0'. Subclasses should override this method to return a more meaningful version number.

virtual Time om::sound::filters::SoundFilter::getLatency ( ) const

virtual

Return a Time value indicating the latency of this sound filter in seconds.

The default implementation returns a latency of 0. Filter subclasses should override this implementation if they have a non-zero latency.

Reimplemented in om::sound::filters::Flanger, om::sound::filters::PitchShifter, and om::sound::filters::Vibrato.

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

virtual

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

The default implementation for this method returns that the filter has 0 parameters. SoundFilter subclasses should override this method to provide generic access to their parameters.

virtual Bool om::sound::filters::SoundFilter::getParameterIndex	(	const UTF8String &	parameterName,
		Index &	parameterIndex
	)		const

virtual

Query the index of the parameter with the specified name.

If a parameter with the name exists in the SoundFilter, TRUE is returned and the index of that parameter is placed in the output parameter index parameter. Otherwise, FALSE is returned and no parameter index is set.

The default implementation calls getParameterInfo() for all each declared parameter and checks to see if its name is equal to the specified name. This is rather inefficient but is provided so that SoundFilter subclasses don't have to implement this method if they don't want to.

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

virtual

Get information about the filter parameter at the specified index.

If a parameter with the specified index exists in this filter, the method should return TRUE and place information about the parameter in the output parameter information object. Otherwise, the method should return FALSE and return no parameter information.

SoundFilter subclasses should override this method to provide information about their generic parameters.

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

virtual

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

If a parameter with the specified index exists in this filter and there is a special name associated with the given value, TRUE is returned and the output string is set to reflect the name of the special value. Otherwise, the method fails and returns FALSE, indicating that there is no special name for that parameter value.

Reimplemented in om::sound::filters::Bitcrusher, om::sound::filters::Delay, om::sound::filters::Distortion, om::sound::filters::MultichannelDelay, om::sound::filters::BandFilter, om::sound::filters::CutoffFilter, om::sound::filters::ToneGenerator, om::sound::filters::Tremolo, om::sound::filters::ShelfFilter, and om::sound::filters::Resampler.

Bool om::sound::filters::SoundFilter::getParameter	(	Index	parameterIndex,
		FilterParameter &	value
	)		const

Place the value of the parameter at the specified index in the output parameter.

This method accesses the value for a parameter. If if the parameter index is out-of-bounds, FALSE is returned. Otherwise, TRUE is returned and the value is placed in the output parameter.

Bool om::sound::filters::SoundFilter::getParameter	(	Index	parameterIndex,
		Bool &	value
	)		const

Place the value of the parameter at the specified index in the output parameter.

This method accesses the value for a boolean parameter. If this type is not allowed for the given parameter index (or no suitable conversion is possible), or if the parameter index is out-of-bounds, FALSE is returned. Otherwise, TRUE is returned and the value is placed in the output parameter.

Bool om::sound::filters::SoundFilter::getParameter	(	Index	parameterIndex,
		Int64 &	value
	)		const

Place the value of the parameter at the specified index in the output parameter.

This method accesses the value for an integer or enumeration parameter. If this type is not allowed for the given parameter index (or no suitable conversion is possible), or if the parameter index is out-of-bounds, FALSE is returned. Otherwise, TRUE is returned and the value is placed in the output parameter.

Bool om::sound::filters::SoundFilter::getParameter	(	Index	parameterIndex,
		Float32 &	value
	)		const

Place the value of the parameter at the specified index in the output parameter.

This method accesses the value for a floating-point parameter. If this type is not allowed for the given parameter index (or no suitable conversion is possible), or if the parameter index is out-of-bounds, FALSE is returned. Otherwise, TRUE is returned and the value is placed in the output parameter.

Bool om::sound::filters::SoundFilter::getParameter	(	Index	parameterIndex,
		Float64 &	value
	)		const

Place the value of the parameter at the specified index in the output parameter.

This method accesses the value for a double floating-point parameter. If this type is not allowed for the given parameter index (or no suitable conversion is possible), or if the parameter index is out-of-bounds, FALSE is returned. Otherwise, TRUE is returned and the value is placed in the output parameter.

template<typename ParameterType >

Bool om::sound::filters::SoundFilter::getParameter	(	const UTF8String &	name,
		ParameterType &	value
	)		const

inline

Place the value of the parameter with the specified name in the output parameter.

This method accesses the value for a template type parameter. If this type is not allowed for the given parameter name (or no suitable conversion is possible), or if the parameter name does not represent a valid parameter, FALSE is returned. Otherwise, TRUE is returned and the value is placed in the output parameter.

template<typename ParameterType >

Bool om::sound::filters::SoundFilter::getParameter	(	const char *	name,
		ParameterType &	value
	)		const

inline

Place the value of the parameter with the specified name in the output parameter.

This method accesses the value for a template type parameter. If this type is not allowed for the given parameter name (or no suitable conversion is possible), or if the parameter name does not represent a valid parameter, FALSE is returned. Otherwise, TRUE is returned and the value is placed in the output parameter.

Bool om::sound::filters::SoundFilter::setParameter	(	Index	parameterIndex,
		const FilterParameter &	value
	)

Attempt to set the parameter value at the specified index.

This method accesses the value for a generic parameter. If if the parameter index is out-of-bounds or if the type of the given value can't be converted to the parameter's type, FALSE is returned. Otherwise, TRUE is returned and the parameter's value is set to the specified value.

Bool om::sound::filters::SoundFilter::setParameter	(	Index	parameterIndex,
		Bool	value
	)

Attempt to set the parameter value at the specified index.

This method accesses the value for a boolean parameter. If if the parameter index is out-of-bounds or if the type of the given value can't be converted to the parameter's type, FALSE is returned. Otherwise, TRUE is returned and the parameter's value is set to the specified value.

Bool om::sound::filters::SoundFilter::setParameter	(	Index	parameterIndex,
		Int64	value
	)

Attempt to set the parameter value at the specified index.

This method accesses the value for an integer or enumeration parameter. If if the parameter index is out-of-bounds or if the type of the given value can't be converted to the parameter's type, FALSE is returned. Otherwise, TRUE is returned and the parameter's value is set to the specified value.

Bool om::sound::filters::SoundFilter::setParameter	(	Index	parameterIndex,
		Float32	value
	)

Attempt to set the parameter value at the specified index.

This method accesses the value for a float parameter. If if the parameter index is out-of-bounds or if the type of the given value can't be converted to the parameter's type, FALSE is returned. Otherwise, TRUE is returned and the parameter's value is set to the specified value.

Bool om::sound::filters::SoundFilter::setParameter	(	Index	parameterIndex,
		Float64	value
	)

Attempt to set the parameter value at the specified index.

This method accesses the value for a double parameter. If if the parameter index is out-of-bounds or if the type of the given value can't be converted to the parameter's type, FALSE is returned. Otherwise, TRUE is returned and the parameter's value is set to the specified value.

template<typename ParameterType >

Bool om::sound::filters::SoundFilter::setParameter	(	const UTF8String &	name,
		ParameterType	value
	)

inline

Attempt to set the parameter value with the specified name.

This method accesses the value for an boolean parameter. If this type is not allowed for the given parameter name (or no suitable conversion is possible), or if the parameter name does not represent a valid parameter, FALSE is returned. Otherwise, TRUE is returned and the new parameter value is set.

template<typename ParameterType >

Bool om::sound::filters::SoundFilter::setParameter	(	const char *	name,
		ParameterType	value
	)

inline

Attempt to set the parameter value with the specified name.

This method accesses the value for an boolean parameter. If this type is not allowed for the given parameter name (or no suitable conversion is possible), or if the parameter name does not represent a valid parameter, FALSE is returned. Otherwise, TRUE is returned and the new parameter value is set.

virtual Bool om::sound::filters::SoundFilter::writeState ( DataOutputStream & stream ) const

virtual

Write the current state of this sound filter to a data output stream.

This method writes the complete current state of the sound filter to the specified output stream. The method returns whether or not the operation was successful. This method is useful for easily serializing the state of a filter. Use the writeState() method to save a filter state.

The base implementation iterates over the filter's public parameters and stores them in a generic representation in the output stream.

Override this method in a subclass to store private data or to store more efficiently. In general, if one overrides this method, one should also override readState() in order to make sure that filter data is stored in an expected manner.

virtual Bool om::sound::filters::SoundFilter::readState ( DataInputStream & stream )

virtual

Read a previously saved filter state from the specified data input stream and replace the filter's state.

This method reads data from the stream and uses it to update all of the filter's parameters with new values. This method is used to deserialize the stored state of a filter.

The base implementation uses the filter's public parameters to update the filter's state from a generic representation.

Override this method in a subclass to restore private data. In general, if one overrides this method, one should also override writeState() in order to make sure that filter data is stored in an expected manner.

virtual Size om::sound::filters::SoundFilter::getPresetCount ( ) const

virtual

Return the number of standard configuration presets that this sound filter has.

A preset is a collection of information which encapsulates the entire state of a filter. Filters can have any number of standard presets which the user can choose from to save time when configuring filters. The preset with index 0 is always considered the default preset.

The base implementation returns that there are 0 presets. Override this method along with the other preset accessor methods to provide a set of standard presets.

Reimplemented in om::sound::filters::GainFilter.

virtual Bool om::sound::filters::SoundFilter::getPreset	(	Index	presetIndex,
		FilterPreset &	preset
	)		const

virtual

Get the standard preset for this sound filter with the specified index.

This method stores the standard preset with the specified index in the output preset parameter. If the method succeeds, TRUE is returned. Otherwise, if the method fails, FALSE is returned and the preset parameter is unmodified.

The base implementation always returns FALSE because are no presets by default.

Reimplemented in om::sound::filters::GainFilter.

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

virtual

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

The base implementation returns FilterCategory::OTHER. Override the method to return more meaningful information. This is used to categorize filters in a host application, or to provide useful metadata to users.

Bool om::sound::filters::SoundFilter::getIsSynchronized ( ) const

inline

Return whether or not this sound filter performs thread synchronization.

If the return value is TRUE, every time that a sound filter parameter is changed or a frame is rendered, a mutex is locked which prevents unsafe thread access to internal state. Otherwise, if the return value is FALSE, the synchronization is disabled. Disabling synchronization can improve performance in situations where the user is sure that there will be no unsafe thread access.

Sound filters are synchronized by default.

void om::sound::filters::SoundFilter::setIsSynchronized ( Bool newIsSynchronized )

inline

Set whether or not this sound filter performs thread synchronization.

If the new value is TRUE, every time that a sound filter parameter is changed or a frame is rendered, a mutex is locked which prevents unsafe thread access to internal state. Otherwise, if the new value is FALSE, the synchronization is disabled. Disabling synchronization can improve performance in situations where the user is sure that there will be no unsafe thread access.

Sound filters are synchronized by default.

virtual Bool om::sound::filters::SoundFilter::allowsInPlaceProcessing ( ) const

virtual

Return whether or not this sound filter can process audio data in-place.

If TRUE, this means that the filter can use the same SoundBuffer for input and output without any processing errors. This reduces memory requirements for the user of the filter and increases the filter's flexibility. If FALSE, the filter requires different input and output sound buffers.

The default implementation returns FALSE, indicating that in-place processing is not supported.

static Size om::sound::filters::SoundFilter::getMaximumNumberOfInputs ( )

inlinestatic

Return the maximum number of audio inputs that a SoundFilter can support.

static Size om::sound::filters::SoundFilter::getMaximumNumberOfOutputs ( )

inlinestatic

Return the maximum number of audio outputs that a SoundFilter can support.

static Size om::sound::filters::SoundFilter::getMaximumNumberOfMIDIInputs ( )

inlinestatic

Return the maximum number of MIDI inputs that a SoundFilter can support.

static Size om::sound::filters::SoundFilter::getMaximumNumberOfMIDIOutputs ( )

inlinestatic

Return the maximum number of MIDI outputs that a SoundFilter can support.

virtual Bool om::sound::filters::SoundFilter::getParameterValue	(	Index	parameterIndex,
		FilterParameter &	value
	)		const

protectedvirtual

Place the value of the parameter at the specified index in the output parameter.

This method accesses the value for a parameter. If if the parameter index is out-of-bounds, FALSE is returned. Otherwise, TRUE is returned and the value is placed in the output parameter.

virtual Bool om::sound::filters::SoundFilter::setParameterValue	(	Index	parameterIndex,
		const FilterParameter &	value
	)

protectedvirtual

Attempt to set the parameter value at the specified index.

This method accesses the value for a parameter. If if the parameter index is out-of-bounds or if the type of the given value can't be converted to the parameter's type, FALSE is returned. Otherwise, TRUE is returned and the parameter's value is set to the specified value.

virtual void om::sound::filters::SoundFilter::resetStream ( )

protectedvirtual

A method that is called whenever the filter's stream of audio is being reset.

This method can be overridden by a subclass to perform any initialization or preprocessing necessary when restarting the filter's audio stream. This can include reseting all parameter interpolation and processing to its initial state to avoid coloration from previous audio or parameter values.

The base implementation does nothing. This method is automatically synchronized with the filter processing method, allowing it to be called from another thread without consequences. As such, calling lockMutex() within this method will cause a deadlock.

virtual SoundResult om::sound::filters::SoundFilter::processFrame	(	const SoundFrame &	inputFrame,
		SoundFrame &	outputFrame,
		Size	numSamples
	)

protectedpure virtual

Process the given input frame and write the resulting audio to the given output frame.

If the number of input frame buffers is 0, it means that the filter should behave as an output only. Likewise, if the number of output frame buffers is 0, the filter should only read and process data from the input frame and not write data to the output frame. The implementator of this method should detect these cases and handle them without error.

This method should return the number of samples successfully written to the output frame. A value less than the number of input samples indicates an error occurred.

The default implementation doesn't write anything to the output buffer and just returns 0. Override it to provide more specific functionality.

This method is automatically synchronized using lockMutex(), which keeps parameter value changes from happening while a frame is being rendered. In order for this to work properly, the filter subclass should call lockMutex() and unlockMutex() around every method that modifies state used when processing frames. Calling lockMutex() within this method will cause a deadlock.

void om::sound::filters::SoundFilter::setInputCount ( Size newNumInputs )

inlineprotected

Set the number of inputs that this filter should have.

Most filters will have only 1 input and 1 output, though some filters may have have no input or no output. Some filters (like a sidechain compressor or crossover) may have multiple inputs or outputs.

This method is not thread synchronized, so subclasses must provide their own means of synchronization when calling this method.

The requested number of inputs is clamped to be no larger than the maximum number of inputs, returned by SoundFilter::getMaximumNumberOfInputs().

void om::sound::filters::SoundFilter::setOutputCount ( Size newNumOutputs )

inlineprotected

Set the number of outputs that this filter should have.

Most filters will have only 1 input and 1 output, though some filters may have have no input or no output. Some filters (like a sidechain compressor or crossover) may have multiple inputs or outputs.

This method is not thread synchronized, so subclasses must provide their own means of synchronization when calling this method.

The requested number of outputs is clamped to be no larger than the maximum number of outputs, returned by SoundFilter::getMaximumNumberOfOutputs().

void om::sound::filters::SoundFilter::setMIDIInputCount ( Size newNumMIDIInputs )

inlineprotected

Set the number of MIDI inputs that this filter should have.

This method can be used by subclasses to change the number of recognized MIDI inputs for the filter. The default number of inputs is 0.

This method is not thread synchronized, so subclasses must provide their own means of synchronization when calling this method.

The requested number of inputs is clamped to be no larger than the maximum number of inputs, returned by SoundFilter::getMaximumNumberOfMIDIInputs().

void om::sound::filters::SoundFilter::setMIDIOutputCount ( Size newNumMIDIOutputs )

inlineprotected

Set the number of MIDI outputs that this filter should have.

This method can be used by subclasses to change the number of recognized MIDI outputs for the filter. The default number of outputs is 0.

This method is not thread synchronized, so subclasses must provide their own means of synchronization when calling this method.

The requested number of outputs is clamped to be no larger than the maximum number of outputs, returned by SoundFilter::getMaximumNumberOfMIDIOutputs().

Bool om::sound::filters::SoundFilter::isFirstFrame ( ) const

inlineprotected

Return whether or not the filter's next frame to be processed is also its first frame.

This method can be queried by subclasses to determine if the filter should reset any parameter interpolation or buffers.

void om::sound::filters::SoundFilter::lockMutex ( ) const

inlineprotected

Acquire a mutex which handles subclass rendering parameter synchronization.

This method should be called before a rendering parameter is modified in a SoundFilter subclass. This operation may potentially block the calling thread if the mutex is already acquired by another thread until the mutex is released with a corresponding call to unlockMutex().

Every call to this method should be paired with a call to unlockMutex(). Failure to observe this requirement will result in application deadlock.

If the filter is not synchronized, via setIsSynchronized(), the method has no effect. This improves performance in situations where the user knows that there will not be any unsafe thread access to the filter.

void om::sound::filters::SoundFilter::unlockMutex ( ) const

inlineprotected

Release a mutex which handles subclass rendering parameter synchronization.

This method should be called after a rendering parameter is modified in a SoundFilter subclass. It releases the parameter change mutex and may potentially awaken threads that are waiting on the mutex.

If the filter is not synchronized, via setIsSynchronized(), the method has no effect. This improves performance in situations where the user knows that there will not be any unsafe thread access to the filter.

Member Data Documentation

const om::resources::ResourceType om::sound::filters::SoundFilter::RESOURCE_TYPE

static

The resource type for a sound filter.

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

omSoundFilter.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation