Om
1.0.0
A universal framework for multimedia simulation
|
A class that represents an acyclic graph of sound processing filters. More...
#include <omSoundFilterGraph.h>
Public Member Functions | |
FilterGraph () | |
Create a new graph of sound filters with no connections. More... | |
FilterGraph (const FilterGraph &other) | |
Create a copy of the specified sound filter graph, duplicating all of its connections. More... | |
~FilterGraph () | |
Destroy this sound filter graph, releasing all internal state. More... | |
FilterGraph & | operator= (const FilterGraph &other) |
Assign a copy of the specified sound filter graph to this graph, duplicating all of its connections. More... | |
Size | getNodeCount () const |
Return the total number of nodes in the filter graph. More... | |
Bool | connect (SoundFilter *from, SoundFilter *to) |
Connect as many outputs of the first filter to the inputs of the second filter as possible. More... | |
Bool | connect (SoundFilter *from, Index outputIndex, SoundFilter *to, Index inputIndex) |
Connect the specified output of the first filter to the specified input of the second filter. More... | |
Bool | disconnect (const SoundFilter *from, const SoundFilter *to) |
Disconnect the first output of the first filter from the first input of the second filter. More... | |
Bool | disconnect (const SoundFilter *from, Index outputIndex, const SoundFilter *to, Index inputIndex) |
Disconnect the specified output of the first filter from the specified input of the second filter. More... | |
Bool | isConnected (const SoundFilter *from, const SoundFilter *to) const |
Return whether or not the specified output filter is directly connected to the input of another filter. More... | |
Bool | isConnected (const SoundFilter *from, Index outputIndex, const SoundFilter *to, Index inputIndex) const |
Return whether or not the specified output of one filter is directly connected to an input of another filter. More... | |
void | clear () |
Clear all connections (and nodes/filters) from this filter graph. More... | |
virtual UTF8String | getName () const |
Return a human-readable name for this sound filter graph. More... | |
virtual UTF8String | getManufacturer () const |
Return the manufacturer name of this sound filter graph. More... | |
virtual FilterVersion | getVersion () const |
Return an object representing the version of this sound filter graph. More... | |
virtual FilterCategory | getCategory () const |
Return an object that describes the category of effect that this filter implements. 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 Size | getParameterCount () const |
Return the total number of generic accessible parameters this filter has. More... | |
virtual Bool | getParameterIndex (const UTF8String ¶meterName, Index ¶meterIndex) 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... | |
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 sound filter graph. More... | |
static const UTF8String | MANUFACTURER |
A string indicating the manufacturer name of this sound filter graph. More... | |
static const FilterVersion | VERSION |
An object indicating the version of this sound filter graph. 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... | |
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... | |
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... | |
A class that represents an acyclic graph of sound processing filters.
This class is provided to make complex graphs of audio processing filters easy to construct and maintain. A filter graph consists of any number of inputs and outputs (determined by the connections made) which are exposed to the user, plus internal SoundFilter objects which perform audio processing on the input and output sound of the filter graph. A filter graph initially has no connections and thus won't produce or process any audio. The user must make connections from filters to the graph's external inputs and outputs and amongst the filters in order for a filter graph to function properly.
The FilterGraph class is provided as a convenience in doing complex audio processing. It handles all temporary buffer allocation and management and enables efficient communication between filters in the processing graph. While using a filter graph is efficient, it will not be as fast as a hand-coded processing graph that is specifically optimized for the task at hand.
It must be noted that the filter graph class does not own or know anything about the lifetime of the SoundFilter objects which it is connecting. The filter object pointers which are connected are expected to be valid until they are either removed from the graph or the graph is destroyed.
om::sound::filters::FilterGraph::FilterGraph | ( | ) |
Create a new graph of sound filters with no connections.
As is, this graph will not be able to process any sound. The user must connect filters within the graph, forming a chain to the output in order for it to function properly.
om::sound::filters::FilterGraph::FilterGraph | ( | const FilterGraph & | other | ) |
Create a copy of the specified sound filter graph, duplicating all of its connections.
om::sound::filters::FilterGraph::~FilterGraph | ( | ) |
Destroy this sound filter graph, releasing all internal state.
FilterGraph& om::sound::filters::FilterGraph::operator= | ( | const FilterGraph & | other | ) |
Assign a copy of the specified sound filter graph to this graph, duplicating all of its connections.
|
inline |
Return the total number of nodes in the filter graph.
This number includes the main input/output node, so this value is usually equal to the number of filters in the graph plus one unless the main input/output node is not yet connected, in which case it is equal to the number of filters.
Bool om::sound::filters::FilterGraph::connect | ( | SoundFilter * | from, |
SoundFilter * | to | ||
) |
Connect as many outputs of the first filter to the inputs of the second filter as possible.
A 1-to-1 connection is made between the outputs of the first filter and the inputs of the second filter.
The method returns whether or not the connection was successfully made. The connection can fail if the output filter doesn't have an output or if the input filter doesn't have an input.
Specifying NULL for the first filter connects the graph's global filter input to the second filter's input. Likewise, a NULL second filter pointer connects the first filter to the main graph output. Specifying NULL for both pointers connects the graph's inputs to its outputs directly.
Bool om::sound::filters::FilterGraph::connect | ( | SoundFilter * | from, |
Index | outputIndex, | ||
SoundFilter * | to, | ||
Index | inputIndex | ||
) |
Connect the specified output of the first filter to the specified input of the second filter.
The method returns whether or not the connection was successfully made. The connection can fail if the output filter doesn't have an output or if the input filter doesn't have an input.
Specifying NULL for the first filter connects the graph's global filter input to the second filter's input. Likewise, a NULL second filter pointer connects the first filter to the main graph output. Specifying NULL for both pointers connects the graph's input to its output directly.
Bool om::sound::filters::FilterGraph::disconnect | ( | const SoundFilter * | from, |
const SoundFilter * | to | ||
) |
Disconnect the first output of the first filter from the first input of the second filter.
Bool om::sound::filters::FilterGraph::disconnect | ( | const SoundFilter * | from, |
Index | outputIndex, | ||
const SoundFilter * | to, | ||
Index | inputIndex | ||
) |
Disconnect the specified output of the first filter from the specified input of the second filter.
The method returns whether or not the connection was successfully disconnected. The disconnection can fail if the output filter doesn't have an output, if the input filter doesn't have an input, or if there was no such connection before the method was called.
Specifying NULL for the first filter disconnects the graph's global input from the second filter's input. Likewise, a NULL second filter pointer disconnects the first filter from the main graph output. Specifying NULL for both pointers disconnects the graph's input from its output.
Bool om::sound::filters::FilterGraph::isConnected | ( | const SoundFilter * | from, |
const SoundFilter * | to | ||
) | const |
Return whether or not the specified output filter is directly connected to the input of another filter.
The method returns TRUE if any output of the first filter is directly connected to the input of the second filter.
Bool om::sound::filters::FilterGraph::isConnected | ( | const SoundFilter * | from, |
Index | outputIndex, | ||
const SoundFilter * | to, | ||
Index | inputIndex | ||
) | const |
Return whether or not the specified output of one filter is directly connected to an input of another filter.
void om::sound::filters::FilterGraph::clear | ( | ) |
Clear all connections (and nodes/filters) from this filter graph.
|
virtual |
Return a human-readable name for this sound filter graph.
The method returns the string "Sound Filter Graph".
Reimplemented from om::sound::filters::SoundFilter.
|
virtual |
Return the manufacturer name of this sound filter graph.
The method returns the string "Om Sound".
Reimplemented from om::sound::filters::SoundFilter.
|
virtual |
Return an object representing the version of this sound filter graph.
Reimplemented from om::sound::filters::SoundFilter.
|
virtual |
Return an object that describes the category of effect that this filter implements.
This method returns the value FilterCategory::ROUTING.
Reimplemented from om::sound::filters::SoundFilter.
|
static |
A string indicating the human-readable name of this sound filter graph.
|
static |
A string indicating the manufacturer name of this sound filter graph.
|
static |
An object indicating the version of this sound filter graph.