SAF
Loading...
Searching...
No Matches
Functions
panner.c File Reference

A frequency-dependent 3D panner based on the Vector-base Amplitude Panning (VBAP) method [1], with an optional spread control [2]. More...

#include "panner_internal.h"

Go to the source code of this file.

Functions

void panner_create (void **const phPan)
 Creates an instance of the panner.
 
void panner_destroy (void **const phPan)
 Destroys an instance of the panner.
 
void panner_init (void *const hPan, int sampleRate)
 Initialises an instance of panner with default settings.
 
void panner_initCodec (void *const hPan)
 Intialises the codec variables, based on current global/user parameters.
 
void panner_process (void *const hPan, const float *const *inputs, float *const *const outputs, int nInputs, int nOutputs, int nSamples)
 Pans the input signals/sources to the loudspeaker channels using VBAP [1], and optional spreading [2] and frequency-dependent normalisation as a function of the room reverberation [3].
 
void panner_refreshSettings (void *const hPan)
 Sets all intialisation flags to 1; re-initialising all settings/variables as panner is currently configured, at next available opportunity.
 
void panner_setSourceAzi_deg (void *const hPan, int index, float newAzi_deg)
 Sets the azimuth of a specific input/source index, in DEGREES.
 
void panner_setSourceElev_deg (void *const hPan, int index, float newElev_deg)
 Sets the elevation of a specific input/source index, in DEGREES.
 
void panner_setNumSources (void *const hPan, int new_nSources)
 Sets the number of inputs/sources to pan.
 
void panner_setLoudspeakerAzi_deg (void *const hPan, int index, float newAzi_deg)
 Sets the azimuth of a specific loudspeaker index, in DEGREES.
 
void panner_setLoudspeakerElev_deg (void *const hPan, int index, float newElev_deg)
 Sets the elevation of a specific loudspeaker index, in DEGREES.
 
void panner_setNumLoudspeakers (void *const hPan, int new_nLoudspeakers)
 Sets the number of loudspeakers to pan to.
 
void panner_setOutputConfigPreset (void *const hPan, int newPresetID)
 Sets a preset for the output configuration (see LOUDSPEAKER_ARRAY_PRESETS enum)
 
void panner_setInputConfigPreset (void *const hPan, int newPresetID)
 Sets a preset for the input configuration (see SOURCE_CONFIG_PRESETS enum)
 
void panner_setDTT (void *const hPan, float newValue)
 Sets the room coefficient value 0..1 [1]; 0: normal room, 0.5: dry listening room, 1: anechoic.
 
void panner_setSpread (void *const hPan, float newValue)
 Sets the degree of spread, in DEGREES.
 
void panner_setYaw (void *const hBin, float newYaw)
 Sets the 'yaw' rotation angle, in DEGREES.
 
void panner_setPitch (void *const hBin, float newPitch)
 Sets the 'pitch' rotation angle, in DEGREES.
 
void panner_setRoll (void *const hBin, float newRoll)
 Sets the 'roll' rotation angle, in DEGREES.
 
void panner_setFlipYaw (void *const hBin, int newState)
 Sets a flag as to whether to "flip" the sign of the current 'yaw' angle (0: do not flip sign, 1: flip the sign)
 
void panner_setFlipPitch (void *const hBin, int newState)
 Sets a flag as to whether to "flip" the sign of the current 'pitch' angle (0: do not flip sign, 1: flip the sign)
 
void panner_setFlipRoll (void *const hBin, int newState)
 Sets a flag as to whether to "flip" the sign of the current 'roll' angle (0: do not flip sign, 1: flip the sign)
 
int panner_getFrameSize (void)
 Returns the processing framesize (i.e., number of samples processed with every _process() call )
 
CODEC_STATUS panner_getCodecStatus (void *const hPan)
 Returns current codec status (see CODEC_STATUS enum)
 
float panner_getProgressBar0_1 (void *const hPan)
 (Optional) Returns current intialisation/processing progress, between 0..1
 
void panner_getProgressBarText (void *const hPan, char *text)
 (Optional) Returns current intialisation/processing progress text
 
float panner_getSourceAzi_deg (void *const hPan, int index)
 Returns the input/source azimuth for a given index, in DEGREES.
 
float panner_getSourceElev_deg (void *const hPan, int index)
 Returns the input/source elevation for a given index, in DEGREES.
 
int panner_getNumSources (void *const hPan)
 Returns the number of inputs/sources in the current layout.
 
int panner_getMaxNumSources ()
 Returns the maximum number of inputs/sources permitted by panner.
 
float panner_getLoudspeakerAzi_deg (void *const hPan, int index)
 Returns the loudspeaker azimuth for a given index, in DEGREES.
 
float panner_getLoudspeakerElev_deg (void *const hPan, int index)
 Returns the loudspeaker elevation for a given index, in DEGREES.
 
int panner_getNumLoudspeakers (void *const hPan)
 Returns the number of loudspeakers in the current layout.
 
int panner_getMaxNumLoudspeakers ()
 Returns the maximum number of loudspeakers permitted.
 
int panner_getDAWsamplerate (void *const hPan)
 Returns the DAW/Host sample rate.
 
float panner_getDTT (void *const hPan)
 Returns the room coefficient value 0..1.
 
float panner_getSpread (void *const hPan)
 Returns the spread value, in DEGREES.
 
float panner_getYaw (void *const hBin)
 Returns the 'yaw' rotation angle, in DEGREES.
 
float panner_getPitch (void *const hBin)
 Returns the 'pitch' rotation angle, in DEGREES.
 
float panner_getRoll (void *const hBin)
 Returns the 'roll' rotation angle, in DEGREES.
 
int panner_getFlipYaw (void *const hBin)
 Returns a flag as to whether to "flip" the sign of the current 'yaw' angle (0: do not flip sign, 1: flip the sign)
 
int panner_getFlipPitch (void *const hBin)
 Returns a flag as to whether to "flip" the sign of the current 'pitch' angle (0: do not flip sign, 1: flip the sign)
 
int panner_getFlipRoll (void *const hBin)
 Returns a flag as to whether to "flip" the sign of the current 'roll' angle (0: do not flip sign, 1: flip the sign)
 
int panner_getProcessingDelay ()
 Returns the processing delay in samples (may be used for delay compensation features)
 

Detailed Description

A frequency-dependent 3D panner based on the Vector-base Amplitude Panning (VBAP) method [1], with an optional spread control [2].

Depending on the listening room, it may be beneficial to employ amplitude- normalised gains for low frequencies, and energy-normalised gains for high frequencies. Therefore, this VBAP implementation also uses the method described in [3], to do just that.

See also
[1] Pulkki, V. (1997). Virtual sound source positioning using vector base amplitude panning. Journal of the audio engineering society, 45(6), 456-466.
[2] Pulkki, V. (1999). Uniform spreading of amplitude panned virtual sources. In Proceedings of the 1999 IEEE Workshop on Applications of Signal Processing to Audio and Acoustics. WASPAA'99 (Cat. No. 99TH8452) (pp. 187-190). IEEE.
[3] Laitinen, M., Vilkamo, J., Jussila, K., Politis, A., Pulkki, V. (2014). Gain normalisation in amplitude panning as a function of frequency and room reverberance. 55th International Conference of the AES. Helsinki, Finland.
Author
Leo McCormack
Date
25.09.2017
License
ISC

Definition in file panner.c.

Function Documentation

◆ panner_create()

void panner_create ( void **const phPan)

Creates an instance of the panner.

Parameters
[in]phPan(&) address of panner handle

Definition at line 46 of file panner.c.

◆ panner_destroy()

void panner_destroy ( void **const phPan)

Destroys an instance of the panner.

Parameters
[in]phPan(&) address of panner handle

Definition at line 90 of file panner.c.

◆ panner_getCodecStatus()

CODEC_STATUS panner_getCodecStatus ( void *const hPan)

Returns current codec status (see CODEC_STATUS enum)

Definition at line 545 of file panner.c.

◆ panner_getDAWsamplerate()

int panner_getDAWsamplerate ( void *const hPan)

Returns the DAW/Host sample rate.

Definition at line 609 of file panner.c.

◆ panner_getDTT()

float panner_getDTT ( void *const hPan)

Returns the room coefficient value 0..1.

Definition at line 615 of file panner.c.

◆ panner_getFlipPitch()

int panner_getFlipPitch ( void *const hBin)

Returns a flag as to whether to "flip" the sign of the current 'pitch' angle (0: do not flip sign, 1: flip the sign)

Definition at line 651 of file panner.c.

◆ panner_getFlipRoll()

int panner_getFlipRoll ( void *const hBin)

Returns a flag as to whether to "flip" the sign of the current 'roll' angle (0: do not flip sign, 1: flip the sign)

Definition at line 657 of file panner.c.

◆ panner_getFlipYaw()

int panner_getFlipYaw ( void *const hBin)

Returns a flag as to whether to "flip" the sign of the current 'yaw' angle (0: do not flip sign, 1: flip the sign)

Definition at line 645 of file panner.c.

◆ panner_getFrameSize()

int panner_getFrameSize ( void )

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

Definition at line 540 of file panner.c.

◆ panner_getLoudspeakerAzi_deg()

float panner_getLoudspeakerAzi_deg ( void *const hPan,
int index )

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

Definition at line 586 of file panner.c.

◆ panner_getLoudspeakerElev_deg()

float panner_getLoudspeakerElev_deg ( void *const hPan,
int index )

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

Definition at line 592 of file panner.c.

◆ panner_getMaxNumLoudspeakers()

int panner_getMaxNumLoudspeakers ( void )

Returns the maximum number of loudspeakers permitted.

Definition at line 604 of file panner.c.

◆ panner_getMaxNumSources()

int panner_getMaxNumSources ( void )

Returns the maximum number of inputs/sources permitted by panner.

Definition at line 581 of file panner.c.

◆ panner_getNumLoudspeakers()

int panner_getNumLoudspeakers ( void *const hPan)

Returns the number of loudspeakers in the current layout.

Definition at line 598 of file panner.c.

◆ panner_getNumSources()

int panner_getNumSources ( void *const hPan)

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

Definition at line 575 of file panner.c.

◆ panner_getPitch()

float panner_getPitch ( void *const hBin)

Returns the 'pitch' rotation angle, in DEGREES.

Definition at line 633 of file panner.c.

◆ panner_getProcessingDelay()

int panner_getProcessingDelay ( void )

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

Definition at line 663 of file panner.c.

◆ panner_getProgressBar0_1()

float panner_getProgressBar0_1 ( void *const hPan)

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

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

Definition at line 551 of file panner.c.

◆ panner_getProgressBarText()

void panner_getProgressBarText ( void *const hPan,
char * text )

(Optional) Returns current intialisation/processing progress text

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

Definition at line 557 of file panner.c.

◆ panner_getRoll()

float panner_getRoll ( void *const hBin)

Returns the 'roll' rotation angle, in DEGREES.

Definition at line 639 of file panner.c.

◆ panner_getSourceAzi_deg()

float panner_getSourceAzi_deg ( void *const hPan,
int index )

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

Definition at line 563 of file panner.c.

◆ panner_getSourceElev_deg()

float panner_getSourceElev_deg ( void *const hPan,
int index )

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

Definition at line 569 of file panner.c.

◆ panner_getSpread()

float panner_getSpread ( void *const hPan)

Returns the spread value, in DEGREES.

Definition at line 621 of file panner.c.

◆ panner_getYaw()

float panner_getYaw ( void *const hBin)

Returns the 'yaw' rotation angle, in DEGREES.

Definition at line 627 of file panner.c.

◆ panner_init()

void panner_init ( void *const hPan,
int samplerate )

Initialises an instance of panner with default settings.

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

Definition at line 120 of file panner.c.

◆ panner_initCodec()

void panner_initCodec ( void *const hPan)

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

Definition at line 139 of file panner.c.

◆ panner_process()

void panner_process ( void *const hPan,
const float *const * inputs,
float *const * outputs,
int nInputs,
int nOutputs,
int nSamples )

Pans the input signals/sources to the loudspeaker channels using VBAP [1], and optional spreading [2] and frequency-dependent normalisation as a function of the room reverberation [3].

Parameters
[in]hPanpanner 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
See also
[1] Pulkki, V. (1997). Virtual sound source positioning using vector base amplitude panning. Journal of the audio engineering society, 45(6), 456-466.
[2] Pulkki, V. (1999). Uniform spreading of amplitude panned virtual sources. In Proceedings of the 1999 IEEE Workshop on Applications of Signal Processing to Audio and Acoustics. WASPAA'99 (Cat. No. 99TH8452) (pp. 187-190). IEEE.
[3] Laitinen, M., Vilkamo, J., Jussila, K., Politis, A., Pulkki, V. (2014). Gain normalisation in amplitude panning as a function of frequency and room reverberance. 55th International Conference of the AES. Helsinki, Finland.

Definition at line 175 of file panner.c.

◆ panner_refreshSettings()

void panner_refreshSettings ( void *const hPan)

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

Definition at line 337 of file panner.c.

◆ panner_setDTT()

void panner_setDTT ( void *const hPan,
float newValue )

Sets the room coefficient value 0..1 [1]; 0: normal room, 0.5: dry listening room, 1: anechoic.

See also
[1] Laitinen, M., Vilkamo, J., Jussila, K., Politis, A., Pulkki, V. (2014). Gain normalisation in amplitude panning as a function of frequency and room reverberance. 55th International Conference of the AES. Helsinki, Finland.

Definition at line 461 of file panner.c.

◆ panner_setFlipPitch()

void panner_setFlipPitch ( void *const hBin,
int newState )

Sets a flag as to whether to "flip" the sign of the current 'pitch' angle (0: do not flip sign, 1: flip the sign)

Definition at line 519 of file panner.c.

◆ panner_setFlipRoll()

void panner_setFlipRoll ( void *const hBin,
int newState )

Sets a flag as to whether to "flip" the sign of the current 'roll' angle (0: do not flip sign, 1: flip the sign)

Definition at line 528 of file panner.c.

◆ panner_setFlipYaw()

void panner_setFlipYaw ( void *const hBin,
int newState )

Sets a flag as to whether to "flip" the sign of the current 'yaw' angle (0: do not flip sign, 1: flip the sign)

Definition at line 510 of file panner.c.

◆ panner_setInputConfigPreset()

void panner_setInputConfigPreset ( void *const hPan,
int newPresetID )

Sets a preset for the input configuration (see SOURCE_CONFIG_PRESETS enum)

Definition at line 450 of file panner.c.

◆ panner_setLoudspeakerAzi_deg()

void panner_setLoudspeakerAzi_deg ( void *const hPan,
int index,
float newAzi_deg )

Sets the azimuth of a specific loudspeaker index, in DEGREES.

Definition at line 388 of file panner.c.

◆ panner_setLoudspeakerElev_deg()

void panner_setLoudspeakerElev_deg ( void *const hPan,
int index,
float newElev_deg )

Sets the elevation of a specific loudspeaker index, in DEGREES.

Definition at line 406 of file panner.c.

◆ panner_setNumLoudspeakers()

void panner_setNumLoudspeakers ( void *const hPan,
int new_nLoudspeakers )

Sets the number of loudspeakers to pan to.

Definition at line 422 of file panner.c.

◆ panner_setNumSources()

void panner_setNumSources ( void *const hPan,
int new_nSources )

Sets the number of inputs/sources to pan.

Definition at line 373 of file panner.c.

◆ panner_setOutputConfigPreset()

void panner_setOutputConfigPreset ( void *const hPan,
int newPresetID )

Sets a preset for the output configuration (see LOUDSPEAKER_ARRAY_PRESETS enum)

Definition at line 438 of file panner.c.

◆ panner_setPitch()

void panner_setPitch ( void *const hBin,
float newPitch )

Sets the 'pitch' rotation angle, in DEGREES.

Definition at line 496 of file panner.c.

◆ panner_setRoll()

void panner_setRoll ( void *const hBin,
float newRoll )

Sets the 'roll' rotation angle, in DEGREES.

Definition at line 503 of file panner.c.

◆ panner_setSourceAzi_deg()

void panner_setSourceAzi_deg ( void *const hPan,
int index,
float newAzi_deg )

Sets the azimuth of a specific input/source index, in DEGREES.

Definition at line 347 of file panner.c.

◆ panner_setSourceElev_deg()

void panner_setSourceElev_deg ( void *const hPan,
int index,
float newElev_deg )

Sets the elevation of a specific input/source index, in DEGREES.

Definition at line 361 of file panner.c.

◆ panner_setSpread()

void panner_setSpread ( void *const hPan,
float newValue )

Sets the degree of spread, in DEGREES.

Definition at line 475 of file panner.c.

◆ panner_setYaw()

void panner_setYaw ( void *const hBin,
float newYaw )

Sets the 'yaw' rotation angle, in DEGREES.

Definition at line 489 of file panner.c.