binauraliser_nf.c File Reference

Convolves input audio (up to 64 channels) with interpolated HRTFs in the time-frequency domain, and applies optional near-field binaural filtering, as described in [1]. More...

#include "binauraliser_nf_internal.h"

Go to the source code of this file.

Functions
void	binauraliserNF_create (void **const phBin)
	Creates an instance of the binauraliser.
void	binauraliserNF_destroy (void **const phBin)
	Destroys an instance of the binauraliser.
void	binauraliserNF_init (void *const hBin, int sampleRate)
	Initialises an instance of binauraliser with default settings.
void	binauraliserNF_initCodec (void *const hBin)
	Intialises the codec variables, based on current global/user parameters.
void	binauraliserNF_process (void *const hBin, const float *const *inputs, float *const *const outputs, int nInputs, int nOutputs, int nSamples)
	Binauralises the input signals at the user specified directions.
void	binauraliserNF_setSourceDist_m (void *const hBin, int index, float newDist_m)
	Sets the panning distance for a specific channel index, in METERS.
void	binauraliserNF_setInputConfigPreset (void *const hBin, int newPresetID)
	Loads an input preset (see SOURCE_CONFIG_PRESETS enum)
float	binauraliserNF_getSourceDist_m (void *const hBin, int index)
	Returns the source elevation for a given index, in METERS.
float	binauraliserNF_getFarfieldThresh_m (void *const hBin)
	Returns the distance considered to be the far field (beyond which no near field filtering is applied), in METERS.
float	binauraliserNF_getFarfieldHeadroom (void *const hBin)
	Returns the scaling factor to give the far field threshold headroom (useful for UI range limits)
float	binauraliserNF_getNearfieldLimit_m (void *const hBin)
	Returns the minimum distance possible for near field filter, in METERS.

Detailed Description

Convolves input audio (up to 64 channels) with interpolated HRTFs in the time-frequency domain, and applies optional near-field binaural filtering, as described in [1].

The HRTFs are interpolated by applying amplitude-preserving VBAP gains to the HRTF magnitude responses and inter-aural time differences (ITDs) individually, before being re-combined. The example also allows the user to specify an external SOFA file for the convolution, and rotations of the source directions to accomodate head-tracking.

See also

[1] S. Spagnol, E. Tavazzi, and F. Avanzini, “Distance rendering and perception of nearby virtual sound sources with a near-field filter model,” Applied Acoustics, vol. 115, pp. 61–73, Jan. 2017, doi: 10.1016/j.apacoust.2016.08.015.

Author

Michael McCrea, Leo McCormack

Date

22.02.2022

License

ISC

Definition in file binauraliser_nf.c.

Function Documentation

binauraliserNF_create()

void binauraliserNF_create

(

void **const

phBin

)

Creates an instance of the binauraliser.

Parameters

[in]

phBin

(&) address of binauraliserNF handle

Definition at line 41 of file binauraliser_nf.c.

binauraliserNF_destroy()

void binauraliserNF_destroy

(

void **const

phBin

)

Destroys an instance of the binauraliser.

Parameters

[in]

phBin

(&) address of binauraliser handle

Definition at line 139 of file binauraliser_nf.c.

binauraliserNF_getFarfieldHeadroom()

float binauraliserNF_getFarfieldHeadroom

(

void *const

hBin

)

Returns the scaling factor to give the far field threshold headroom (useful for UI range limits)

Definition at line 418 of file binauraliser_nf.c.

binauraliserNF_getFarfieldThresh_m()

float binauraliserNF_getFarfieldThresh_m

(

void *const

hBin

)

Returns the distance considered to be the far field (beyond which no near field filtering is applied), in METERS.

Definition at line 411 of file binauraliser_nf.c.

binauraliserNF_getNearfieldLimit_m()

float binauraliserNF_getNearfieldLimit_m

(

void *const

hBin

)

Returns the minimum distance possible for near field filter, in METERS.

Definition at line 425 of file binauraliser_nf.c.

binauraliserNF_getSourceDist_m()

float binauraliserNF_getSourceDist_m	(	void *const	hBin,
		int	index )

Returns the source elevation for a given index, in METERS.

Parameters

[in]	hBin	binauraliserNF handle
[in]	index	source index

Definition at line 404 of file binauraliser_nf.c.

binauraliserNF_init()

void binauraliserNF_init	(	void *const	hBin,
		int	samplerate )

Initialises an instance of binauraliser with default settings.

Warning

This should not be called while _process() is on-going!

Parameters

[in]	hBin	binauraliserNF handle
[in]	samplerate	Host samplerate.

Definition at line 175 of file binauraliser_nf.c.

binauraliserNF_initCodec()

void binauraliserNF_initCodec

(

void *const

hBin

)

Intialises the codec variables, based on current global/user parameters.

Note

This function is fully threadsafe. It can even be called periodically via a timer on one thread, while calling _process() on another thread. Since, if a set function is called (that warrants a re-init), then a flag is triggered internally and the next time this function is called, it will wait until the current process() function has completed before reinitialising the relevant parameters. If the _initCodec() takes longer than the time it takes for process() to be called again, then process() is simply bypassed until the codec is ready.

This function does nothing if no re-initialisations are required.

Parameters

[in]

hBin

binauraliser handle

Definition at line 190 of file binauraliser_nf.c.

binauraliserNF_process()

void binauraliserNF_process	(	void *const	hBin,
		const float *const *	inputs,
		float *const *	outputs,
		int	nInputs,
		int	nOutputs,
		int	nSamples )

Binauralises the input signals at the user specified directions.

Parameters

[in]	hBin	binauraliserNF handle
[in]	inputs	Input channel buffers; 2-D array: nInputs x nSamples
[in]	outputs	Output channel buffers; 2-D array: nOutputs x nSamples
[in]	nInputs	Number of input channels
[in]	nOutputs	Number of output channels
[in]	nSamples	Number of samples in 'inputs'/'output' matrices

Definition at line 226 of file binauraliser_nf.c.

binauraliserNF_setInputConfigPreset()

void binauraliserNF_setInputConfigPreset	(	void *const	hBin,
		int	newPresetID )

Loads an input preset (see SOURCE_CONFIG_PRESETS enum)

Parameters

[in]	hBin	binauraliserNF handle
[in]	newPresetID	index of the source preset

Definition at line 387 of file binauraliser_nf.c.

binauraliserNF_setSourceDist_m()

void binauraliserNF_setSourceDist_m	(	void *const	hBin,
		int	index,
		float	newDist_m )

Sets the panning distance for a specific channel index, in METERS.

Parameters

[in]	hBin	binauraliserNF handle
[in]	index	source index
[in]	newDist_m	source distance in meter

Definition at line 377 of file binauraliser_nf.c.