Internal header for the reverb processing module (SAF_REVERB_MODULE) More...

#include "saf_reverb.h"
#include "saf_externals.h"
#include "../saf_utilities/saf_utilities.h"
#include "../saf_sh/saf_sh.h"

Go to the source code of this file.

Data Structures
struct	ims_pos_xyz
	Union struct for Cartesian coordinates (access as .x,.y,.z, or .v[3]) More...

struct	ims_src_obj
	Source object. More...

struct	ims_rec_obj
	Receiver object. More...

struct	echogram_data
	Echogram structure. More...

struct	ims_core_workspace
	Helper structure, comprising variables used when computing echograms and rendering RIRs. More...

struct	ims_scene_data
	Main structure for IMS. More...

Macros
#define	IMS_NUM_WALLS_SHOEBOX ( 6 )
	Number of wall for a shoebox room.

#define	IMS_FIR_FILTERBANK_ORDER ( 400 )
	FIR filter order (must be even)

#define	IMS_IIR_FILTERBANK_ORDER ( 3 )
	IIR filter order (1st or 3rd)

#define	IMS_CIRC_BUFFER_LENGTH ( 4*8192U )
	Circular buffer length.

#define	IMS_CIRC_BUFFER_LENGTH_MASK ( IMS_CIRC_BUFFER_LENGTH - 1U )
	Circular buffer length, minus 1.

#define	IMS_MAX_NSAMPLES_PER_FRAME ( 20000 )
	Maximum number of samples that ims should expect to process at a time.

#define	IMS_LAGRANGE_ORDER ( 2 )
	Order of lagrange interpolation filters.

#define	IMS_LAGRANGE_LOOKUP_TABLE_SIZE ( 100 )
	Lagrange interpolator look-up table size.

#define	IMS_EG_CURRENT ( 0 )
	Index for the current echogram slot.

#define	IMS_EG_PREV ( 1 )
	Index for the previous echogram slot.

#define	IMS_EG_NUM_SLOTS ( 2 )
	Number of echogram slots.

#define	IMS_UNASSIGNED ( -1 )
	While a source or receiver ID is yet to be active, it is "IMS_UNASSIGNED".

Typedefs
typedef void *	voidPtr
	Void pointer (just to improve code readability when working with arrays of handles)

Enumerations
enum	RECEIVER_TYPES { RECEIVER_SH }
	Supported receiver types. More...

Functions
void	ims_shoebox_coreWorkspaceCreate (void **phWork, int nBands)
	Creates an instance of the core workspace.

void	ims_shoebox_coreWorkspaceDestroy (void **phWork)
	Destroys an instance of the core workspace.

void	ims_shoebox_echogramCreate (void **phEcho, int include_rt_vars)
	Creates an instance of an echogram container.

void	ims_shoebox_echogramResize (void *hEcho, int numImageSources, int nChannels)
	Resizes an echogram container.

void	ims_shoebox_echogramCopy (void hEchoX, void hEchoY)
	Copies echogram data from container 'X' into container 'Y' (also resizing 'Y' as needed)

void	ims_shoebox_echogramDestroy (void **phEcho)
	Destroys an instance of an echogram container.

void	ims_shoebox_coreInitT (void *hWork, float room[3], ims_pos_xyz src, ims_pos_xyz rec, float maxTime, float c_ms)
	Calculates an echogram of a rectangular space using the image source method, for a specific source/reciever combination up to a maximum propagation time.

void	ims_shoebox_coreInitN (void *hWork, float room[3], ims_pos_xyz src, ims_pos_xyz rec, int maxN, float c_ms)
	Calculates an echogram of a rectangular space using the image source method, for a specific source/reciever combination up to a maximum reflection order.

void	ims_shoebox_coreRecModuleSH (void *hWork, int sh_order)
	Imposes spherical harmonic directivies onto the echogram computed with ims_shoebox_coreInit() for a specific source/reciever combination.

void	ims_shoebox_coreAbsorptionModule (void hWork, float *abs_wall)
	Applies boundary absoption per frequency band, onto the echogram computed with ims_shoebox_coreRecModuleSH() for a specific source/reciever combination.

void	ims_shoebox_renderRIR (void hWork, int fractionalDelayFLAG, float fs, float H_filt, ims_rir rir)
	Renders a room impulse response for a specific source/reciever combination.

Detailed Description

Internal header for the reverb processing module (SAF_REVERB_MODULE)

A collection of reverb and room simulation algorithms.

Author: Leo McCormack

Date: 06.05.2020

License: ISC

Definition in file saf_reverb_internal.h.

Macro Definition Documentation

◆ IMS_CIRC_BUFFER_LENGTH

#define IMS_CIRC_BUFFER_LENGTH ( 4*8192U )

Circular buffer length.

Definition at line 52 of file saf_reverb_internal.h.

◆ IMS_CIRC_BUFFER_LENGTH_MASK

#define IMS_CIRC_BUFFER_LENGTH_MASK ( IMS_CIRC_BUFFER_LENGTH - 1U )

Circular buffer length, minus 1.

Definition at line 54 of file saf_reverb_internal.h.

◆ IMS_EG_CURRENT

#define IMS_EG_CURRENT ( 0 )

Index for the current echogram slot.

Definition at line 62 of file saf_reverb_internal.h.

◆ IMS_EG_NUM_SLOTS

#define IMS_EG_NUM_SLOTS ( 2 )

Number of echogram slots.

Definition at line 66 of file saf_reverb_internal.h.

◆ IMS_EG_PREV

#define IMS_EG_PREV ( 1 )

Index for the previous echogram slot.

Definition at line 64 of file saf_reverb_internal.h.

◆ IMS_FIR_FILTERBANK_ORDER

#define IMS_FIR_FILTERBANK_ORDER ( 400 )

FIR filter order (must be even)

Definition at line 48 of file saf_reverb_internal.h.

◆ IMS_IIR_FILTERBANK_ORDER

#define IMS_IIR_FILTERBANK_ORDER ( 3 )

IIR filter order (1st or 3rd)

Definition at line 50 of file saf_reverb_internal.h.

◆ IMS_LAGRANGE_LOOKUP_TABLE_SIZE

#define IMS_LAGRANGE_LOOKUP_TABLE_SIZE ( 100 )

Lagrange interpolator look-up table size.

Definition at line 60 of file saf_reverb_internal.h.

◆ IMS_LAGRANGE_ORDER

#define IMS_LAGRANGE_ORDER ( 2 )

Order of lagrange interpolation filters.

Definition at line 58 of file saf_reverb_internal.h.

◆ IMS_MAX_NSAMPLES_PER_FRAME

#define IMS_MAX_NSAMPLES_PER_FRAME ( 20000 )

Maximum number of samples that ims should expect to process at a time.

Definition at line 56 of file saf_reverb_internal.h.

◆ IMS_NUM_WALLS_SHOEBOX

#define IMS_NUM_WALLS_SHOEBOX ( 6 )

Number of wall for a shoebox room.

Definition at line 46 of file saf_reverb_internal.h.

◆ IMS_UNASSIGNED

#define IMS_UNASSIGNED ( -1 )

While a source or receiver ID is yet to be active, it is "IMS_UNASSIGNED".

Definition at line 68 of file saf_reverb_internal.h.

Typedef Documentation

◆ voidPtr

typedef void* voidPtr

Void pointer (just to improve code readability when working with arrays of handles)

Definition at line 72 of file saf_reverb_internal.h.

Enumeration Type Documentation

◆ RECEIVER_TYPES

enum RECEIVER_TYPES

Supported receiver types.

Enumerator
RECEIVER_SH	Spherical harmonic receiver.

Definition at line 86 of file saf_reverb_internal.h.

Function Documentation

◆ ims_shoebox_coreAbsorptionModule()

void ims_shoebox_coreAbsorptionModule	(	void *	hWork,
		float **	abs_wall )

Applies boundary absoption per frequency band, onto the echogram computed with ims_shoebox_coreRecModuleSH() for a specific source/reciever combination.

Absorption coefficients are given for each of the walls on the respective planes [x+ y+ z+; x- y- z-].

Note: Call ims_shoebox_coreRecModuleX before applying the absoption

Parameters

[in]	hWork	workspace handle
[in]	abs_wall	Absorption coefficients; nBands x 6

Definition at line 576 of file saf_reverb_internal.c.

◆ ims_shoebox_coreInitN()

void ims_shoebox_coreInitN	(	void *	hWork,
		float	room[3],
		ims_pos_xyz	src,
		ims_pos_xyz	rec,
		int	maxN,
		float	c_ms )

Calculates an echogram of a rectangular space using the image source method, for a specific source/reciever combination up to a maximum reflection order.

Parameters

[in]	hWork	workspace handle
[in]	room	Room dimensions, in meters
[in]	src	Source position, in meters
[in]	rec	Receiver position, in meters
[in]	maxN	Maximum propagation time to compute the echogram, seconds
[in]	c_ms	Speed of source, in meters per second

Definition at line 399 of file saf_reverb_internal.c.

◆ ims_shoebox_coreInitT()

void ims_shoebox_coreInitT	(	void *	hWork,
		float	room[3],
		ims_pos_xyz	src,
		ims_pos_xyz	rec,
		float	maxTime,
		float	c_ms )

Calculates an echogram of a rectangular space using the image source method, for a specific source/reciever combination up to a maximum propagation time.

Note the coordinates of source/receiver are specified from the left ground corner of the room:

*
*                ^x
*             __|__    _
*             |  |  |   |
*             |  |  |   |
*          y<----.  |   | l
*             |     |   |
*             |     |   |
*             o_____|   -
*
*             |-----|
*                w
*
*

Parameters

[in]	hWork	workspace handle
[in]	room	Room dimensions, in meters
[in]	src	Source position, in meters
[in]	rec	Receiver position, in meters
[in]	maxTime	Maximum propagation time to compute the echogram, seconds
[in]	c_ms	Speed of source, in meters per second

Definition at line 269 of file saf_reverb_internal.c.

◆ ims_shoebox_coreRecModuleSH()

void ims_shoebox_coreRecModuleSH	(	void *	hWork,
		int	sh_order )

Imposes spherical harmonic directivies onto the echogram computed with ims_shoebox_coreInit() for a specific source/reciever combination.

Note: Call ims_shoebox_coreInit() before applying the directivities

Parameters

[in]	hWork	workspace handle
[in]	sh_order	Spherical harmonic order

Definition at line 523 of file saf_reverb_internal.c.

◆ ims_shoebox_coreWorkspaceCreate()

void ims_shoebox_coreWorkspaceCreate	(	void **	phWork,
		int	nBands )

Creates an instance of the core workspace.

The idea is that there is one core workspace instance per source/receiver combination.

Parameters

[in]	phWork	(&) address of the workspace handle
[in]	nBands	Number of bands

Definition at line 173 of file saf_reverb_internal.c.

◆ ims_shoebox_coreWorkspaceDestroy()

void ims_shoebox_coreWorkspaceDestroy ( void ** phWork )

Destroys an instance of the core workspace.

Parameters

[in] phWork (&) address of the workspace handle

Definition at line 224 of file saf_reverb_internal.c.

◆ ims_shoebox_echogramCopy()

void ims_shoebox_echogramCopy	(	void *	hEchoX,
		void *	hEchoY )

Copies echogram data from container 'X' into container 'Y' (also resizing 'Y' as needed)

Warning: Helper variables are resized (if needed), but do not copy values!

Parameters

[in]	hEchoX	echogram container X
[in]	hEchoY	echogram container Y

Definition at line 107 of file saf_reverb_internal.c.

◆ ims_shoebox_echogramCreate()

void ims_shoebox_echogramCreate	(	void **	phEcho,
		int	include_rt_vars )

Creates an instance of an echogram container.

Parameters

[in]	phEcho	(&) address of the echogram container
[in]	include_rt_vars	1: optional run-time helper functions enabled, 0: disabled

Definition at line 36 of file saf_reverb_internal.c.

◆ ims_shoebox_echogramDestroy()

void ims_shoebox_echogramDestroy ( void ** phEcho )

Destroys an instance of an echogram container.

Parameters

[in] phEcho (&) address of the echogram container

Definition at line 138 of file saf_reverb_internal.c.

◆ ims_shoebox_echogramResize()

void ims_shoebox_echogramResize	(	void *	hEcho,
		int	numImageSources,
		int	nChannels )

Resizes an echogram container.

Note: The container is only resized if the number of image sources or channels have changed.

Parameters

[in]	hEcho	echogram container
[in]	numImageSources	New number of image sources
[in]	nChannels	New number of channels

Definition at line 70 of file saf_reverb_internal.c.

◆ ims_shoebox_renderRIR()

void ims_shoebox_renderRIR	(	void *	hWork,
		int	fractionalDelayFLAG,
		float	fs,
		float **	H_filt,
		ims_rir *	rir )

Renders a room impulse response for a specific source/reciever combination.

Note: Call ims_shoebox_coreAbsorptionModule() before rendering rir

Parameters

[in]	hWork	workspace handle
[in]	fractionalDelayFLAG	0: disabled, 1: use Lagrange interpolation
[in]	fs	SampleRate, Hz
[in]	H_filt	filterbank; nBands x (filterOrder+1)
[out]	rir	Room impulse response

Definition at line 640 of file saf_reverb_internal.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ IMS_CIRC_BUFFER_LENGTH

◆ IMS_CIRC_BUFFER_LENGTH_MASK

◆ IMS_EG_CURRENT

◆ IMS_EG_NUM_SLOTS

◆ IMS_EG_PREV

◆ IMS_FIR_FILTERBANK_ORDER

◆ IMS_IIR_FILTERBANK_ORDER

◆ IMS_LAGRANGE_LOOKUP_TABLE_SIZE

◆ IMS_LAGRANGE_ORDER

◆ IMS_MAX_NSAMPLES_PER_FRAME

◆ IMS_NUM_WALLS_SHOEBOX

◆ IMS_UNASSIGNED

Typedef Documentation

◆ voidPtr

Enumeration Type Documentation

◆ RECEIVER_TYPES

Function Documentation

◆ ims_shoebox_coreAbsorptionModule()

◆ ims_shoebox_coreInitN()

◆ ims_shoebox_coreInitT()

◆ ims_shoebox_coreRecModuleSH()

◆ ims_shoebox_coreWorkspaceCreate()

◆ ims_shoebox_coreWorkspaceDestroy()

◆ ims_shoebox_echogramCopy()

◆ ims_shoebox_echogramCreate()

◆ ims_shoebox_echogramDestroy()

◆ ims_shoebox_echogramResize()

◆ ims_shoebox_renderRIR()