Files
file	saf_reverb.c
	Public source for the reverb processing module (SAF_REVERB_MODULE)

file	saf_reverb.h
	Main header for the reverb processing module (SAF_REVERB_MODULE)

file	saf_reverb_internal.c
	Internal source for the reverb processing module (SAF_REVERB_MODULE)

file	saf_reverb_internal.h
	Internal header for the reverb processing module (SAF_REVERB_MODULE)

Data Structures
struct	ims_rir
	Output format of the rendered room impulse responses (RIR) More...

Macros
#define	IMS_MAX_NUM_SOURCES 128
	TODO: Arbitrary array receiver option; Directional source option; finish ims_shoebox_renderRIRs() function;.

#define	IMS_MAX_NUM_RECEIVERS 16
	Maximum number of receivers supported by an instance of the IMS simulator.

Functions
void	ims_shoebox_create (void *phIms, float roomDimensions[3], float abs_wall, float lowestOctaveBand, int nOctBands, float c_ms, float fs)
	Creates an instance of ims_shoebox room simulator.

void	ims_shoebox_destroy (void **phIms)
	Destroys an instance of ims_shoebox room simulator.

void	ims_shoebox_computeEchograms (void *hIms, int maxN, float maxTime_s)
	Computes echograms for all active source/receiver combinations.

void	ims_shoebox_renderRIRs (void *hIms, int fractionalDelaysFLAG)
	Renders room impulse responses for all active source/receiver combinations.

void	ims_shoebox_applyEchogramTD (void *hIms, long receiverID, int nSamples, int fractionalDelaysFLAG)
	Applies the currently computed echograms in the time-domain, for all sources, for one specified receiver.

void	ims_shoebox_setRoomDimensions (void *hIms, float new_roomDimensions[3])
	Sets new room dimensions.

void	ims_shoebox_setWallAbsCoeffs (void hIms, float abs_wall)
	Sets new wall absorption coefficients per wall and per band.

int	ims_shoebox_addSource (void hIms, float position_xyz[3], float *pSrc_sig)
	Adds a source object to the simulator, and returns a unique ID corresponding to it.

int	ims_shoebox_addReceiverSH (void hIms, int sh_order, float position_xyz[3], float **pSH_sigs)
	Adds a spherical harmonic (SH) receiver object to the simulator of a given order, and returns a unique ID corresponding to it.

void	ims_shoebox_updateSource (void *hIms, int sourceID, float position_xyz[3])
	Updates the position of a specific source in the simulation.

void	ims_shoebox_updateReceiver (void *hIms, int receiverID, float position_xyz[3])
	Updates the position of a specific receiver in the simulation.

void	ims_shoebox_removeSource (void *hIms, int sourceID)
	Removes a specific source from the simulation.

void	ims_shoebox_removeReceiver (void *hIms, int receiverID)
	Removes a specific receiver from the simulation.

Detailed Description

Reverb and room simulation module

Macro Definition Documentation

◆ IMS_MAX_NUM_RECEIVERS

#define IMS_MAX_NUM_RECEIVERS 16

Maximum number of receivers supported by an instance of the IMS simulator.

Definition at line 55 of file saf_reverb.h.

◆ IMS_MAX_NUM_SOURCES

#define IMS_MAX_NUM_SOURCES 128

TODO: Arbitrary array receiver option; Directional source option; finish ims_shoebox_renderRIRs() function;.

Maximum number of sources supported by an instance of the IMS simulator

Definition at line 52 of file saf_reverb.h.

Function Documentation

◆ ims_shoebox_addReceiverSH()

int ims_shoebox_addReceiverSH	(	void *	hIms,
		int	sh_order,
		float	position_xyz[3],
		float ***	pSH_sigs )

Adds a spherical harmonic (SH) receiver object to the simulator of a given order, and returns a unique ID corresponding to it.

Warning: There is currently no checking whether the source/receiver coordinates fall inside the boundaries of the room!; You are responsible for making sure that the signal pointers actually point to allocated memory of sufficient size, before calling ims_shoebox_applyEchogramTD()!

Parameters

[in]	hIms	ims_shoebox handle
[in]	sh_order	Spherical harmonic order of the receiver
[in]	position_xyz	Starting receiver position, in metres, x,y,z
[in]	pSH_sigs	(&) address of the pointer to the 2-D output buffer for this receiver: (sh_order+1)^2 x nSamples

Returns: A unique ID corresponding to this receiver object

Definition at line 649 of file saf_reverb.c.

◆ ims_shoebox_addSource()

int ims_shoebox_addSource	(	void *	hIms,
		float	position_xyz[3],
		float **	pSrc_sig )

Adds a source object to the simulator, and returns a unique ID corresponding to it.

Warning: There is currently no checking whether the source/receiver coordinates fall inside the boundaries of the room!; You are responsible for making sure that the signal pointers actually point to allocated memory of sufficient size, before calling ims_shoebox_applyEchogramTD()!

Parameters

[in]	hIms	ims_shoebox handle
[in]	position_xyz	Starting source position, in metres, x,y,z
[in]	pSrc_sig	(&) address of the pointer to the 1-D input buffer for this source: nSamples x 1

Returns: A unique ID corresponding to this source object

Definition at line 598 of file saf_reverb.c.

◆ ims_shoebox_applyEchogramTD()

void ims_shoebox_applyEchogramTD	(	void *	hIms,
		long	receiverID,
		int	nSamples,
		int	fractionalDelaysFLAG )

Applies the currently computed echograms in the time-domain, for all sources, for one specified receiver.

Note the following:

The signal pointers for all the sources and the specified receiver must be valid, and have allocated enough memory for the number of channels and be of (at least) nSamples in length.
The given receiverID must exist in the simulation. If it does not, then an assertion error is triggered.

Parameters

[in]	hIms	ims_shoebox handle
[in]	receiverID	ID of the receiver you wish to render
[in]	nSamples	Number of samples to process
[in]	fractionalDelaysFLAG	0: disabled, 1: use Lagrange interpolation

Definition at line 297 of file saf_reverb.c.

◆ ims_shoebox_computeEchograms()

void ims_shoebox_computeEchograms	(	void *	hIms,
		int	maxN,
		float	maxTime_s )

Computes echograms for all active source/receiver combinations.

The sources are omnidirectional point sources, whereas the receiver will have the directivity of whatever they are configured to have

Note: Set either the maximum reflection order (maxN) or the maximum IR length in seconds (maxTime_s). The option you don't want to use: set to <0.; The echograms are only updated if needed, so it is OK to call this function as many times as you wish, since there will be virtually no CPU overhead incurred if no update is required.

Parameters

[in]	hIms	ims_shoebox handle
[in]	maxN	Maximum reflection order
[in]	maxTime_s	Maximum length of time to compute the echograms, seconds

Definition at line 184 of file saf_reverb.c.

◆ ims_shoebox_create()

void ims_shoebox_create	(	void **	phIms,
		float	roomDimensions[3],
		float *	abs_wall,
		float	lowestOctaveBand,
		int	nOctBands,
		float	c_ms,
		float	fs )

Creates an instance of ims_shoebox room simulator.

Here you first set up the scene parameters, room boundaries, and the wall absorption coefficients per octave band.

Note that the room is initialised to be empty. Therefore, use the ims_shoebox_addSource and ims_shoebox_addReceiverX functions to add sources and recievers to the simulator. The source/receiver positions should be given with respect to the bottom left corner of the room (top view), with positive x+ extending to the east, and positive y+ extending to the north, while z+ is extending purpendicular to them towards the viewer (right-hand rule).

*
*   length/width
*   |----------|
*   ^ y           .
*   |    ^z      /height
*   |   /       /
*   .__/_______.           _
*   | /        |           |
*   |/         |           | width/length
*   o__________.------> x  _
*
*

Warning: There is currently no checking whether the source/receiver coordinates fall inside the boundaries of the room!

Test: test__ims_shoebox_RIR(), test__ims_shoebox_TD()

Parameters

[in]	phIms	(&) address of the ims_shoebox handle
[in]	roomDimensions	Room Length x Width x Height, in meters; 3 x 1
[in]	abs_wall	Absorption coefficents per octave band and wall; FLAT: nOctBands x 6
[in]	lowestOctaveBand	lowest octave band centre freq, in Hz (e.g. 125)
[in]	nOctBands	Number of octave bands (i.e. doublings of "lowestOctaveBand")
[in]	c_ms	Speed of sound, meters per second
[in]	fs	SampleRate, Hz

Definition at line 36 of file saf_reverb.c.

◆ ims_shoebox_destroy()

void ims_shoebox_destroy ( void ** phIms )

Destroys an instance of ims_shoebox room simulator.

Parameters

[in] phIms (&) address of the ims_shoebox handle

Definition at line 140 of file saf_reverb.c.

◆ ims_shoebox_removeReceiver()

void ims_shoebox_removeReceiver	(	void *	hIms,
		int	receiverID )

Removes a specific receiver from the simulation.

Note: This does NOT free the receiver signals pointer 'pSH_sigs'.

Definition at line 825 of file saf_reverb.c.

◆ ims_shoebox_removeSource()

void ims_shoebox_removeSource	(	void *	hIms,
		int	sourceID )

Removes a specific source from the simulation.

Note: This does NOT free the source signal pointer 'pSrc_sig'.

Definition at line 792 of file saf_reverb.c.

◆ ims_shoebox_renderRIRs()

void ims_shoebox_renderRIRs	(	void *	hIms,
		int	fractionalDelaysFLAG )

Renders room impulse responses for all active source/receiver combinations.

Parameters

[in]	hIms	ims_shoebox handle
[in]	fractionalDelaysFLAG	0: disabled, 1: use Lagrange interpolation

Definition at line 259 of file saf_reverb.c.

◆ ims_shoebox_setRoomDimensions()

void ims_shoebox_setRoomDimensions	(	void *	hIms,
		float	new_roomDimensions[3] )

Sets new room dimensions.

Definition at line 541 of file saf_reverb.c.

◆ ims_shoebox_setWallAbsCoeffs()

void ims_shoebox_setWallAbsCoeffs	(	void *	hIms,
		float *	abs_wall )

Sets new wall absorption coefficients per wall and per band.

Definition at line 567 of file saf_reverb.c.

◆ ims_shoebox_updateReceiver()

void ims_shoebox_updateReceiver	(	void *	hIms,
		int	receiverID,
		float	position_xyz[3] )

Updates the position of a specific receiver in the simulation.

Definition at line 748 of file saf_reverb.c.

◆ ims_shoebox_updateSource()

void ims_shoebox_updateSource	(	void *	hIms,
		int	sourceID,
		float	position_xyz[3] )

Updates the position of a specific source in the simulation.

Definition at line 704 of file saf_reverb.c.

Files

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ IMS_MAX_NUM_RECEIVERS

◆ IMS_MAX_NUM_SOURCES

Function Documentation

◆ ims_shoebox_addReceiverSH()

◆ ims_shoebox_addSource()

◆ ims_shoebox_applyEchogramTD()

◆ ims_shoebox_computeEchograms()

◆ ims_shoebox_create()

◆ ims_shoebox_destroy()

◆ ims_shoebox_removeReceiver()

◆ ims_shoebox_removeSource()

◆ ims_shoebox_renderRIRs()

◆ ims_shoebox_setRoomDimensions()

◆ ims_shoebox_setWallAbsCoeffs()

◆ ims_shoebox_updateReceiver()

◆ ims_shoebox_updateSource()