SAF
Loading...
Searching...
No Matches
spreader.c File Reference

An arbitrary array panner (HRIRs, microphone array IRs, etc.) with coherent and incoherent spreading modes, as described in [1]. More...

Go to the source code of this file.

Functions

void spreader_create (void **const phSpr)
 Creates an instance of the spreader.
 
void spreader_destroy (void **const phSpr)
 Destroys an instance of the spreader.
 
void spreader_init (void *const hSpr, int sampleRate)
 Initialises an instance of spreader with default settings.
 
void spreader_initCodec (void *const hSpr)
 Intialises the codec variables, based on current global/user parameters.
 
void spreader_process (void *const hSpr, const float *const *inputs, float *const *const outputs, int nInputs, int nOutputs, int nSamples)
 Spatialises and spreads the input signals in the user specified directions.
 
void spreader_refreshSettings (void *const hSpr)
 Sets all intialisation flags to 1; re-initialising all settings/variables as spreader is currently configured, at next available opportunity.
 
void spreader_setSpreadingMode (void *const hSpr, int newMode)
 Sets the spreading mode (see SPREADER_PROC_MODES)
 
void spreader_setAveragingCoeff (void *const hSpr, float newValue)
 Sets the averaging coefficient [0..1].
 
void spreader_setSourceAzi_deg (void *const hSpr, int index, float newAzi_deg)
 Sets the panning azimuth for a specific channel index, in DEGREES.
 
void spreader_setSourceElev_deg (void *const hSpr, int index, float newElev_deg)
 Sets the panning elevation for a specific channel index, in DEGREES.
 
void spreader_setSourceSpread_deg (void *const hSpr, int index, float newSpread_deg)
 Sets the source spread for a specific channel index, in DEGREES.
 
void spreader_setNumSources (void *const hSpr, int new_nSources)
 Sets the number of input channels/sources to binauralise.
 
void spreader_setUseDefaultHRIRsflag (void *const hSpr, int newState)
 Sets flag to dictate whether the default HRIRs in the Spatial_Audio_Framework should be used (1), or a custom HRIR set loaded via a SOFA file (0).
 
void spreader_setSofaFilePath (void *const hSpr, const char *path)
 Sets the file path for a .sofa file, in order to employ a custom HRIR set for the decoding.
 
int spreader_getFrameSize (void)
 Returns the processing framesize (i.e., number of samples processed with every _process() call )
 
CODEC_STATUS spreader_getCodecStatus (void *const hSpr)
 Returns current codec status codec status (see CODEC_STATUS enum)
 
float spreader_getProgressBar0_1 (void *const hSpr)
 (Optional) Returns current intialisation/processing progress, between 0..1
 
void spreader_getProgressBarText (void *const hSpr, char *text)
 (Optional) Returns current intialisation/processing progress text
 
int * spreader_getDirectionActivePtr (void *const hSpr, int index)
 Returns the pointer to a vector describing which directions are currently being used for the spreading, for a given source index.
 
int spreader_getSpreadingMode (void *const hSpr)
 Returns the spreading mode (see SPREADER_PROC_MODES)
 
float spreader_getAveragingCoeff (void *const hSpr)
 Returns the averaging coefficient [0..1].
 
float spreader_getSourceAzi_deg (void *const hSpr, int index)
 Returns the source azimuth for a given source index, in DEGREES.
 
float spreader_getSourceElev_deg (void *const hSpr, int index)
 Returns the source elevation for a given source index, in DEGREES.
 
float spreader_getSourceSpread_deg (void *const hSpr, int index)
 Returns the source spread for a given source index, in DEGREES.
 
int spreader_getNumSources (void *const hSpr)
 Returns the number of inputs/sources in the current config.
 
int spreader_getMaxNumSources (void)
 Returns the maximum number of input sources supported by spreader.
 
int spreader_getNumOutputs (void *const hSpr)
 Returns the number of ears possessed by the average homo sapien.
 
int spreader_getNDirs (void *const hSpr)
 Returns the number of directions in the currently used HRIR set.
 
float spreader_getIRAzi_deg (void *const hSpr, int index)
 Returns the IR/TF azimuth for a given index, in DEGREES.
 
float spreader_getIRElev_deg (void *const hSpr, int index)
 Returns the IR/TF elevation for a given index, in DEGREES.
 
int spreader_getIRlength (void *const hSpr)
 Returns the length of IRs in time-domain samples.
 
int spreader_getIRsamplerate (void *const hSpr)
 Returns the IR sample rate.
 
int spreader_getUseDefaultHRIRsflag (void *const hSpr)
 Returns the value of a flag used to dictate whether the default HRIRs in the Spatial_Audio_Framework should be used (1), or a custom HRIR set loaded via a SOFA file (0).
 
char * spreader_getSofaFilePath (void *const hSpr)
 Returns the file path for a .sofa file.
 
int spreader_getDAWsamplerate (void *const hSpr)
 Returns the DAW/Host sample rate.
 
int spreader_getProcessingDelay (void)
 Returns the processing delay in samples (may be used for delay compensation purposes)
 

Detailed Description

An arbitrary array panner (HRIRs, microphone array IRs, etc.) with coherent and incoherent spreading modes, as described in [1].

See also
[1] McCormack, L. Politis, A., and Pulkki, V., 2021, October. Rendering of source spread for arbitrary playback setups based on spatial covariance matching. In 2021 IEEE Workshop on Applications of Signal Processing to Audio and Acoustics (WASPAA). IEEE
Author
Leo McCormack
Date
07.04.2021
License
ISC

Definition in file spreader.c.

Function Documentation

◆ spreader_create()

void spreader_create ( void **const phSpr)

Creates an instance of the spreader.

Parameters
[in]phSpr(&) address of spreader handle

Definition at line 34 of file spreader.c.

◆ spreader_destroy()

void spreader_destroy ( void **const phSpr)

Destroys an instance of the spreader.

Parameters
[in]phSpr(&) address of spreader handle

Definition at line 119 of file spreader.c.

◆ spreader_getAveragingCoeff()

float spreader_getAveragingCoeff ( void *const hSpr)

Returns the averaging coefficient [0..1].

Definition at line 809 of file spreader.c.

◆ spreader_getCodecStatus()

CODEC_STATUS spreader_getCodecStatus ( void *const hSpr)

Returns current codec status codec status (see CODEC_STATUS enum)

Definition at line 779 of file spreader.c.

◆ spreader_getDAWsamplerate()

int spreader_getDAWsamplerate ( void *const hSpr)

Returns the DAW/Host sample rate.

Definition at line 905 of file spreader.c.

◆ spreader_getDirectionActivePtr()

int * spreader_getDirectionActivePtr ( void *const hSpr,
int index )

Returns the pointer to a vector describing which directions are currently being used for the spreading, for a given source index.

Definition at line 797 of file spreader.c.

◆ spreader_getFrameSize()

int spreader_getFrameSize ( void )

Returns the processing framesize (i.e., number of samples processed with every _process() call )

Definition at line 774 of file spreader.c.

◆ spreader_getIRAzi_deg()

float spreader_getIRAzi_deg ( void *const hSpr,
int index )

Returns the IR/TF azimuth for a given index, in DEGREES.

Definition at line 859 of file spreader.c.

◆ spreader_getIRElev_deg()

float spreader_getIRElev_deg ( void *const hSpr,
int index )

Returns the IR/TF elevation for a given index, in DEGREES.

Definition at line 868 of file spreader.c.

◆ spreader_getIRlength()

int spreader_getIRlength ( void *const hSpr)

Returns the length of IRs in time-domain samples.

Definition at line 877 of file spreader.c.

◆ spreader_getIRsamplerate()

int spreader_getIRsamplerate ( void *const hSpr)

Returns the IR sample rate.

Definition at line 883 of file spreader.c.

◆ spreader_getMaxNumSources()

int spreader_getMaxNumSources ( void )

Returns the maximum number of input sources supported by spreader.

Definition at line 842 of file spreader.c.

◆ spreader_getNDirs()

int spreader_getNDirs ( void *const hSpr)

Returns the number of directions in the currently used HRIR set.

Definition at line 853 of file spreader.c.

◆ spreader_getNumOutputs()

int spreader_getNumOutputs ( void *const hSpr)

Returns the number of ears possessed by the average homo sapien.

Definition at line 847 of file spreader.c.

◆ spreader_getNumSources()

int spreader_getNumSources ( void *const hSpr)

Returns the number of inputs/sources in the current config.

Definition at line 836 of file spreader.c.

◆ spreader_getProcessingDelay()

int spreader_getProcessingDelay ( void )

Returns the processing delay in samples (may be used for delay compensation purposes)

Definition at line 911 of file spreader.c.

◆ spreader_getProgressBar0_1()

float spreader_getProgressBar0_1 ( void *const hSpr)

(Optional) Returns current intialisation/processing progress, between 0..1

  • 0: intialisation/processing has started
  • 1: intialisation/processing has ended

Definition at line 785 of file spreader.c.

◆ spreader_getProgressBarText()

void spreader_getProgressBarText ( void *const hSpr,
char * text )

(Optional) Returns current intialisation/processing progress text

Note
"text" string should be (at least) of length: PROGRESSBARTEXT_CHAR_LENGTH

Definition at line 791 of file spreader.c.

◆ spreader_getSofaFilePath()

char * spreader_getSofaFilePath ( void *const hSpr)

Returns the file path for a .sofa file.

Note
If the custom set fails to load correctly, spreader will revert to the defualt set. Use 'spreader_getUseDefaultHRIRsflag()' to check if loading was successful.
Parameters
[in]hSprspreader handle
Returns
File path to .sofa file (WITH file extension)

Definition at line 895 of file spreader.c.

◆ spreader_getSourceAzi_deg()

float spreader_getSourceAzi_deg ( void *const hSpr,
int index )

Returns the source azimuth for a given source index, in DEGREES.

Definition at line 815 of file spreader.c.

◆ spreader_getSourceElev_deg()

float spreader_getSourceElev_deg ( void *const hSpr,
int index )

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

Definition at line 822 of file spreader.c.

◆ spreader_getSourceSpread_deg()

float spreader_getSourceSpread_deg ( void *const hSpr,
int index )

Returns the source spread for a given source index, in DEGREES.

Definition at line 829 of file spreader.c.

◆ spreader_getSpreadingMode()

int spreader_getSpreadingMode ( void *const hSpr)

Returns the spreading mode (see SPREADER_PROC_MODES)

Definition at line 803 of file spreader.c.

◆ spreader_getUseDefaultHRIRsflag()

int spreader_getUseDefaultHRIRsflag ( void *const hSpr)

Returns the value of a flag used to dictate whether the default HRIRs in the Spatial_Audio_Framework should be used (1), or a custom HRIR set loaded via a SOFA file (0).

Note
If the custom set fails to load correctly, spreader will revert to the defualt set, so this will be '1'

Definition at line 889 of file spreader.c.

◆ spreader_init()

void spreader_init ( void *const hSpr,
int samplerate )

Initialises an instance of spreader with default settings.

Warning
This should not be called while _process() is on-going!
Parameters
[in]hSprspreader handle
[in]samplerateHost samplerate.

Definition at line 194 of file spreader.c.

◆ spreader_initCodec()

void spreader_initCodec ( void *const hSpr)

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]hSprspreader handle

Definition at line 207 of file spreader.c.

◆ spreader_process()

void spreader_process ( void *const hSpr,
const float *const * inputs,
float *const * outputs,
int nInputs,
int nOutputs,
int nSamples )

Spatialises and spreads the input signals in the user specified directions.

Parameters
[in]hSprspreader handle
[in]inputsInput channel buffers; 2-D array: nInputs x nSamples
[in]outputsOutput channel buffers; 2-D array: nOutputs x nSamples
[in]nInputsNumber of input channels
[in]nOutputsNumber of output channels
[in]nSamplesNumber of samples in 'inputs'/'output' matrices

Definition at line 360 of file spreader.c.

◆ spreader_refreshSettings()

void spreader_refreshSettings ( void *const hSpr)

Sets all intialisation flags to 1; re-initialising all settings/variables as spreader is currently configured, at next available opportunity.

Definition at line 695 of file spreader.c.

◆ spreader_setAveragingCoeff()

void spreader_setAveragingCoeff ( void *const hSpr,
float newValue )

Sets the averaging coefficient [0..1].

Definition at line 707 of file spreader.c.

◆ spreader_setNumSources()

void spreader_setNumSources ( void *const hSpr,
int new_nSources )

Sets the number of input channels/sources to binauralise.

Definition at line 745 of file spreader.c.

◆ spreader_setSofaFilePath()

void spreader_setSofaFilePath ( void *const hSpr,
const char * path )

Sets the file path for a .sofa file, in order to employ a custom HRIR set for the decoding.

Note
If the custom set fails to load correctly, spreader will revert to the defualt set. Use spreader_getUseDefaultHRIRsflag() to check if loading was successful.
Parameters
[in]hSprspreader handle
[in]pathFile path to .sofa file (WITH file extension)

Definition at line 761 of file spreader.c.

◆ spreader_setSourceAzi_deg()

void spreader_setSourceAzi_deg ( void *const hSpr,
int index,
float newAzi_deg )

Sets the panning azimuth for a specific channel index, in DEGREES.

Definition at line 713 of file spreader.c.

◆ spreader_setSourceElev_deg()

void spreader_setSourceElev_deg ( void *const hSpr,
int index,
float newElev_deg )

Sets the panning elevation for a specific channel index, in DEGREES.

Definition at line 725 of file spreader.c.

◆ spreader_setSourceSpread_deg()

void spreader_setSourceSpread_deg ( void *const hSpr,
int index,
float newSpread_deg )

Sets the source spread for a specific channel index, in DEGREES.

Definition at line 735 of file spreader.c.

◆ spreader_setSpreadingMode()

void spreader_setSpreadingMode ( void *const hSpr,
int newMode )

Sets the spreading mode (see SPREADER_PROC_MODES)

Definition at line 700 of file spreader.c.

◆ spreader_setUseDefaultHRIRsflag()

void spreader_setUseDefaultHRIRsflag ( void *const hSpr,
int newState )

Sets flag to dictate whether the default HRIRs in the Spatial_Audio_Framework should be used (1), or a custom HRIR set loaded via a SOFA file (0).

Note
If the custom set fails to load correctly, spreader will revert to the defualt set. Use spreader_getUseDefaultHRIRsflag() to check if loading was successful.

Definition at line 752 of file spreader.c.