om::sound::base::Convolution Class Reference

A class that implements multi-output dynamic streaming convolution. More...

#include <omSoundConvolution.h>

Classes
class	IRDelegate
	A class that opaquely provides an IR from an external source. More...
class	IRRequest
	A class that holds parameters for how an impulse response is updated. More...
class	Request
	A class that manages parameters for a convolution instance. More...

Public Types
typedef Index	ID
	A type that is used to represent the ID of a convolution instance. More...

Public Member Functions
	Convolution ()
	Create a new convolution system with the default initial state. More...
	~Convolution ()
	Destroy a convolution system and release all internal resources. More...
Size	getThreadCount () const
	Return the number of threads that this convolution system is using to process convolution. More...
void	setThreadCount (Size newThreadCount)
	Set the number of threads that this convolution system is using to process convolution. More...
Size	getInstanceCount () const
	Return the number of active convolution instances there are in this convolution system. More...
ID	newInstance (const Request &request)
	Create a new convolution instance that uses the specified convolution request parameters. More...
Bool	deleteInstance (ID instanceID)
	Delete the convolution instance with the specified ID. More...
void	clearInstances ()
	Delete all convolution instances and stop all convolution processing. More...
Request	getRequest (ID instanceID) const
	Get the convolution request for the specified instance. More...
Bool	getRequest (ID instanceID, Request &request) const
	Get the convolution request for the specified instance. More...
Bool	setRequest (ID instanceID, const Request &request)
	Modify the convolution request for the specified instance. More...
Bool	getIR (ID instanceID, SoundBuffer &ir) const
	Get the impulse response for the specified convolution instance. More...
Bool	prepareIR (ID instanceID, const SoundBuffer &ir, const IRRequest &request)
	Prepare the impulse response for the specified convolution instance with custom parameters. More...
Bool	setIR (ID instanceID, const SoundBuffer &ir)
	Update the impulse response for the specified convolution instance. More...
Bool	setIR (ID instanceID, const SoundBuffer &ir, const IRRequest &request)
	Update the impulse response for the specified convolution instance with custom parameters. More...
Bool	setIR (ID instanceID, const IRDelegate &delegate, const IRRequest &request)
	Update the impulse response for the specified convolution instance with custom parameters. More...
Bool	convolve (ID instanceID, const SoundBuffer &input, SoundBuffer &output, Size numSamples)
	Render the convolution for a single instance using the specified input and output buffers. More...

Static Public Attributes
static const ID	INVALID_ID = -1
	An invalid convolution instance ID. More...

Detailed Description

A class that implements multi-output dynamic streaming convolution.

Member Typedef Documentation

typedef Index om::sound::base::Convolution::ID

A type that is used to represent the ID of a convolution instance.

Constructor & Destructor Documentation

om::sound::base::Convolution::Convolution

(

)

Create a new convolution system with the default initial state.

om::sound::base::Convolution::~Convolution

(

)

Destroy a convolution system and release all internal resources.

Member Function Documentation

Size om::sound::base::Convolution::getThreadCount ( ) const

inline

Return the number of threads that this convolution system is using to process convolution.

void om::sound::base::Convolution::setThreadCount

(

Size

newThreadCount

)

Set the number of threads that this convolution system is using to process convolution.

Size om::sound::base::Convolution::getInstanceCount ( ) const

inline

Return the number of active convolution instances there are in this convolution system.

ID om::sound::base::Convolution::newInstance

(

const Request &

request

)

Create a new convolution instance that uses the specified convolution request parameters.

If the method succeeds, an opaque integer ID for the convolution instance is returned. Otherwise, INVALID_ID is returned and no instance is created.

Bool om::sound::base::Convolution::deleteInstance

(

ID

instanceID

)

Delete the convolution instance with the specified ID.

The method waits for background thread processing for the instance to finish, then stops the convolution for the instance and frees all resources.

The method returns whether or not the instance was successfully deleted.

void om::sound::base::Convolution::clearInstances

(

)

Delete all convolution instances and stop all convolution processing.

The method waits for background thread processing to finish, then stops the convolution for all instances and frees all resources.

Request om::sound::base::Convolution::getRequest

(

ID

instanceID

)

const

Get the convolution request for the specified instance.

The method returns the current convolution request for the instance.

Bool om::sound::base::Convolution::getRequest	(	ID	instanceID,
		Request &	request
	)		const

Get the convolution request for the specified instance.

The method writes the current convolution request for the specified instance to the output parameter.

The method returns whether or not the instance request was able to be accessed.

Bool om::sound::base::Convolution::setRequest	(	ID	instanceID,
		const Request &	request
	)

Modify the convolution request for the specified instance.

The method potentially halts background processing for the specified instance and then restarts convolution using the new parameters.

The method returns whether or not the instance request was able to be changed.

Bool om::sound::base::Convolution::getIR	(	ID	instanceID,
		SoundBuffer &	ir
	)		const

Get the impulse response for the specified convolution instance.

If the method succeeds, it writes the current impulse response for the given convolution instance to the output sound buffer.

The method returns whether or not the IR was able to be accessed.

Bool om::sound::base::Convolution::prepareIR	(	ID	instanceID,
		const SoundBuffer &	ir,
		const IRRequest &	request
	)

Prepare the impulse response for the specified convolution instance with custom parameters.

The method allocates the necessary space for the IR, but does not copy the data or perform other IR preprocessing. This method CANNOT be called concurrently with the conolve() method.

The method returns whether or not the IR was able to be updated.

Bool om::sound::base::Convolution::setIR ( ID  instanceID, const SoundBuffer &  ir  )

inline

Update the impulse response for the specified convolution instance.

The default IRRequest is used for the update. The method returns whether or not the IR was able to be updated.

Bool om::sound::base::Convolution::setIR	(	ID	instanceID,
		const SoundBuffer &	ir,
		const IRRequest &	request
	)

Update the impulse response for the specified convolution instance with custom parameters.

The provided IRRequest is used to determine how the update is handled.

This method CANNOT be called concurrently with the convolve() method, HOWEVER, if the method prepareIR() is called before setIR() (and synchronized via external mutex), then this method can be called without synchronization. If prepareIR() is not called beforehand, the method must be synchronized with convolve().

The method returns whether or not the IR was able to be updated.

Bool om::sound::base::Convolution::setIR	(	ID	instanceID,
		const IRDelegate &	delegate,
		const IRRequest &	request
	)

Update the impulse response for the specified convolution instance with custom parameters.

The IR is requested by the convolution system from the IR delegate. The provided IRRequest indicates the length of the opaque IR and is used to determine how the update is handled. Since not every part of the IR will be updated if the update is asynchronous, using a delegate allows computation to be saved when it is expensive to compute the new IR.

This method CANNOT be called concurrently with the convolve() method, HOWEVER, if the method prepareIR() is called before setIR() (and synchronized via external mutex), then this method can be called without synchronization. If prepareIR() is not called beforehand, the method must be synchronized with convolve().

The method returns whether or not the IR was able to be updated.

Bool om::sound::base::Convolution::convolve	(	ID	instanceID,
		const SoundBuffer &	input,
		SoundBuffer &	output,
		Size	numSamples
	)

Render the convolution for a single instance using the specified input and output buffers.

If the method succeeds, it uses the specified number of samples from the input buffer as input for the convolution and writes the same number of samples to the output buffer.

The method returns whether or not the operation was successful.

Member Data Documentation

const ID om::sound::base::Convolution::INVALID_ID = -1

static

An invalid convolution instance ID.

---

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

• omSoundConvolution.h