Files
file	saf_vbap.c
	Public source for the VBAP/MDAP module (SAF_VBAP_MODULE)

file	saf_vbap.h
	Main header for the VBAP/MDAP module (SAF_VBAP_MODULE)

file	saf_vbap_internal.c
	Internal source for the VBAP/MDAP module (SAF_VBAP_MODULE)

file	saf_vbap_internal.h
	Internal header for the VBAP/MDAP module (SAF_VBAP_MODULE)

Functions
void	generateVBAPgainTable3D_srcs (float src_dirs_deg, int S, float ls_dirs_deg, int L, int omitLargeTriangles, int enableDummies, float spread, float *gtable, int N_gtable, int *nTriangles)
	Generates a 3-D VBAP [1] gain table based on specified source and loudspeaker directions, with optional spreading [2].

void	generateVBAPgainTable3D (float ls_dirs_deg, int L, int az_res_deg, int el_res_deg, int omitLargeTriangles, int enableDummies, float spread, float gtable, int N_gtable, int *nTriangles)
	Generates a 3-D VBAP gain table based on specified loudspeaker directions, with optional spreading [2].

void	compressVBAPgainTable3D (float vbap_gtable, int nTable, int nDirs, float vbap_gtableComp, int *vbap_gtableIdx)
	Compresses a VBAP gain table to use less memory and CPU (by removing the elements which are just zero)

void	VBAPgainTable2InterpTable (float *vbap_gtable, int nTable, int nDirs)
	Renormalises a VBAP gain table (in-place) so it may be utilised for interpolation of data (for example, powermaps or HRTFs)

void	generateVBAPgainTable2D_srcs (float src_dirs_deg, int S, float ls_dirs_deg, int L, float *gtable, int N_gtable, int *nPairs)
	Generates a 2-D VBAP gain table based on specified source and loudspeaker directions.

void	generateVBAPgainTable2D (float ls_dirs_deg, int L, int az_res_deg, float gtable, int N_gtable, int *nPairs)
	Generates a 2-D VBAP gain table based on specified loudspeaker directions.

void	getPvalues (float DTT, float freq, int nFreq, float pValues)
	Calculates the frequency dependent pValues, which can be applied to ENERGY normalised VBAP gains, to compensate for the room effect on the perceived loudness fluctuations of sources when panning between loudspeakers.

void	findLsTriplets (float ls_dirs_deg, int L, int omitLargeTriangles, float out_vertices, int numOutVertices, int *out_faces, int numOutFaces)
	Computes the 3D convex-hull of a spherical grid of loudspeaker directions.

void	invertLsMtx3D (float U_spkr, int ls_groups, int N_group, float **layoutInvMtx)
	Inverts a 3x3 loudspeaker matrix.

void	getSpreadSrcDirs3D (float src_azi_rad, float src_elev_rad, float spread, int num_src, int num_rings_3d, float *U_spread)
	Computes a set of points which surround the source direction given a specific degree of spread.

void	vbap3D (float src_dirs, int src_num, int ls_num, int ls_groups, int nFaces, float spread, float layoutInvMtx, float *GainMtx)
	Calculates 3D VBAP gains given pre-computed loudspeaker triangles for each source direction.

void	findLsPairs (float ls_dirs_deg, int L, int out_pairs, int numOutPairs)
	Calculates loudspeaker pairs for a circular grid of loudspeaker directions.

void	invertLsMtx2D (float U_spkr, int ls_pairs, int N_pairs, float **layoutInvMtx)
	Inverts a 2x2 loudspeaker matrix.

void	vbap2D (float src_dirs, int src_num, int ls_num, int ls_pairs, int N_pairs, float layoutInvMtx, float *GainMtx)
	Calculates 2D VBAP gains for pre-calculated loudspeaker pairs and predefined source positions.

Detailed Description

Vector-base Amplitude Panning (VBAP) module

Function Documentation

◆ compressVBAPgainTable3D()

void compressVBAPgainTable3D	(	float *	vbap_gtable,
		int	nTable,
		int	nDirs,
		float *	vbap_gtableComp,
		int *	vbap_gtableIdx )

Compresses a VBAP gain table to use less memory and CPU (by removing the elements which are just zero)

Handy for large grid sizes for interpolation purposes. Therefore, the gains are also re-normalised to have the AMPLITUDE-preserving property. If vbap_gtable is generated by generateVBAPgainTable3D(), then the compressed tables should be accessed as:

N_azi = (int)(360.0f / aziRes + 0.5f) + 1;
aziIndex = (int)(matlab_fmodf(AZI + 180.0f, 360.0f)/az_res_deg + 0.5f);
elevIndex = (int)((ELEV + 90.0f) / el_res_deg + 0.5f);
idx3d = elevIndex * N_azi + aziIndex;
for (i = 0; i < 3; i++){
    gains[i] =  vbap_gtableComp[idx3d*3+i];
    idx[i]   =  vbap_gtableIdx[idx3d*3+i];
}

where 'gains' are then the gains for loudspeakers('idx') to pan the source to [AZI ELEV], using the nearest grid point

Note: The VBAP gains are AMPLITUDE normalised; i.e. sum(gains) = 1

Parameters

[in]	vbap_gtable	The 3D VBAP gain table; FLAT: nTable x nDirs
[in]	nTable	number of points in the gain table
[in]	nDirs	number of loudspeakers
[out]	vbap_gtableComp	The compressed 3D VBAP gain table amplitude- normalised; FLAT: nTable x 3
[out]	vbap_gtableIdx	The indices for the compressed 3D VBAP gain table; FLAT: nTable x 3

Definition at line 312 of file saf_vbap.c.

◆ findLsPairs()

void findLsPairs	(	float *	ls_dirs_deg,
		int	L,
		int **	out_pairs,
		int *	numOutPairs )

Calculates loudspeaker pairs for a circular grid of loudspeaker directions.

Parameters

[in]	ls_dirs_deg	Loudspeaker directions in degrees; FLAT: L x 1
[in]	L	Number of loudspeakers
[out]	out_pairs	(&) loudspeaker pair indices; FLAT: numOutPairs x 2
[out]	numOutPairs	(&) number of loudspeaker pairs

Definition at line 898 of file saf_vbap.c.

◆ findLsTriplets()

void findLsTriplets	(	float *	ls_dirs_deg,
		int	L,
		int	omitLargeTriangles,
		float **	out_vertices,
		int *	numOutVertices,
		int **	out_faces,
		int *	numOutFaces )

Computes the 3D convex-hull of a spherical grid of loudspeaker directions.

Note: Compared with sphDelaunay(), this function also omits triangles where the normals and the centroid to the triangles have an angle larger than pi/2. Trianges which have an aperture larger than APERTURE_LIMIT_DEG are also ommited.

Parameters

[in]	ls_dirs_deg	Loudspeaker directions in degrees; FLAT: L x 2
[in]	L	Number of loudspeakers
[in]	omitLargeTriangles	'0' normal triangulation, '1' remove large triangles
[out]	out_vertices	(&) loudspeaker directions in cartesian coordinates; FLAT: L x 3
[out]	numOutVertices	(&) number of loudspeakers
[out]	out_faces	(&) loudspeaker triangle indices; FLAT: numOutFaces x 3
[out]	numOutFaces	(&) number of true loudspeaker triangles

Definition at line 499 of file saf_vbap.c.

◆ generateVBAPgainTable2D()

void generateVBAPgainTable2D	(	float *	ls_dirs_deg,
		int	L,
		int	az_res_deg,
		float **	gtable,
		int *	N_gtable,
		int *	nPairs )

Generates a 2-D VBAP gain table based on specified loudspeaker directions.

This function generates the VBAP gains for a grid: -180:az_res_deg:180 azimuths, which should be accessed as:

aziIndex = (int)(matlab_fmodf(AZI + 180.0f, 360.0f)/az_res_deg + 0.5f);
idx2d = aziIndex;
for (ls = 0; ls < L; ls++){
    gains2D[ls] =  gtable[idx2d*L+ls];}

'gains2D' are then the loudspeaker gains to pan the source to [AZI 0], using the nearest grid point.

Note: The VBAP gains are ENERGY normalised; i.e. sum(gains^2) = 1

Parameters

[in]	ls_dirs_deg	Loudspeaker directions in degrees (elev assumed to be 0 for all); FLAT: L x 2
[in]	L	Number of loudspeakers
[in]	az_res_deg	Azimuthal resolution in degrees
[out]	gtable	(&) The 2D VBAP gain table energy normalised; FLAT: S x L
[out]	N_gtable	(&) number of points in the gain table, N_gtable=S
[out]	nPairs	(&) number of loudspeaker pairs

Definition at line 428 of file saf_vbap.c.

◆ generateVBAPgainTable2D_srcs()

void generateVBAPgainTable2D_srcs	(	float *	src_dirs_deg,
		int	S,
		float *	ls_dirs_deg,
		int	L,
		float **	gtable,
		int *	N_gtable,
		int *	nPairs )

Generates a 2-D VBAP gain table based on specified source and loudspeaker directions.

Note: source and loudspeaker directions are required to be inter-leaved with zeros, i.e. [src_az1, 0; src_az2, 0; src_az3, 0;]. The VBAP gains are also ENERGY normalised; i.e. sum(gains^2) = 1

Parameters

[in]	src_dirs_deg	Source directions in degrees (elev assumed to be 0 for all); FLAT: S x 2
[in]	S	Number of Sources
[in]	ls_dirs_deg	Loudspeaker directions in degrees (elev assumed to be 0 for all); FLAT: L x 2
[in]	L	Number of loudspeakers
[out]	gtable	(&) The 2D VBAP gain table energy normalised; FLAT: S x L
[out]	N_gtable	(&) number of points in the gain table, N_gtable=S
[out]	nPairs	(&) number of loudspeaker pairs

Definition at line 390 of file saf_vbap.c.

◆ generateVBAPgainTable3D()

void generateVBAPgainTable3D	(	float *	ls_dirs_deg,
		int	L,
		int	az_res_deg,
		int	el_res_deg,
		int	omitLargeTriangles,
		int	enableDummies,
		float	spread,
		float **	gtable,
		int *	N_gtable,
		int *	nTriangles )

Generates a 3-D VBAP gain table based on specified loudspeaker directions, with optional spreading [2].

This function generates the VBAP gains for a grid: -180:az_res_deg:180 azimuths and -90:el_res_deg:90 elevations, which should be accessed as:

N_azi = (int)(360.0f / aziRes + 0.5f) + 1;
aziIndex = (int)(matlab_fmodf(AZI + 180.0f, 360.0f)/az_res_deg + 0.5f);
elevIndex = (int)((ELEV + 90.0f) / el_res_deg + 0.5f);
idx3d = elevIndex * N_azi + aziIndex;
for (ls = 0; ls < L; ls++)
    gains3D[ls] =  gtable[idx3d*L+ls];}

where 'gains3D' are the loudspeaker gains to pan the source to [AZI ELEV], using the nearest grid point

Note: 'gtable' is returned as NULL if the triangulation fails. The VBAP gains are also ENERGY normalised; i.e. sum(gains^2) = 1

Parameters

[in]	ls_dirs_deg	Loudspeaker directions in degrees; FLAT: L x 2
[in]	L	Number of loudspeakers
[in]	az_res_deg	Azimuthal resolution in degrees
[in]	el_res_deg	Elevation resolution in degrees
[in]	omitLargeTriangles	'0' normal triangulation, '1' remove large triangles
[in]	enableDummies	'0' disabled, '1' enabled. Dummies are placed at +/-90 elevation if required
[in]	spread	Spreading factor in degrees, 0: VBAP, >0: MDAP
[out]	gtable	(&) The 3D VBAP gain table ENERGY normalised; FLAT: N_gtable x L
[out]	N_gtable	(&) number of points in the gain table
[out]	nTriangles	(&) number of loudspeaker triangles

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.

Definition at line 171 of file saf_vbap.c.

◆ generateVBAPgainTable3D_srcs()

void generateVBAPgainTable3D_srcs	(	float *	src_dirs_deg,
		int	S,
		float *	ls_dirs_deg,
		int	L,
		int	omitLargeTriangles,
		int	enableDummies,
		float	spread,
		float **	gtable,
		int *	N_gtable,
		int *	nTriangles )

Generates a 3-D VBAP [1] gain table based on specified source and loudspeaker directions, with optional spreading [2].

Note: gtable is returned as NULL if the triangulation fails. The VBAP gains are also ENERGY normalised; i.e. sum(gains^2) = 1

Parameters

[in]	src_dirs_deg	Source directions in degrees; FLAT: S x 2
[in]	S	Number of Sources
[in]	ls_dirs_deg	Loudspeaker directions in degrees; FLAT: L x 2
[in]	L	Number of loudspeakers
[in]	omitLargeTriangles	'0' normal triangulation, '1' remove large triangles
[in]	enableDummies	'0' disabled, '1' enabled, and dummies are placed at +/-90 elevation if required
[in]	spread	Spreading factor in degrees, 0: VBAP, >0: MDAP
[out]	gtable	(&) The 3D VBAP gain table energy normalised; FLAT: N_gtable x L
[out]	N_gtable	(&) number of points in the gain table
[out]	nTriangles	(&) number of loudspeaker triangles

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.

Definition at line 52 of file saf_vbap.c.

◆ getPvalues()

void getPvalues	(	float	DTT,
		float *	freq,
		int	nFreq,
		float *	pValues )

Calculates the frequency dependent pValues, which can be applied to ENERGY normalised VBAP gains, to compensate for the room effect on the perceived loudness fluctuations of sources when panning between loudspeakers.

This should be applied as:

if(pValues[band] != 2.0f){
   gains3D_sum_pvf = 0.0f;
   for (i = 0; i < nLoudspeakers; i++){
       gains3D_sum_pvf += powf(MAX(gains[i], 0.0f), pValues[band]);}
   gains3D_sum_pvf = powf(gains3D_sum_pvf, 1.0f/(pValues[band]+2.23e-13f));
   for (i = 0; i < nLoudspeakers; i++){
       gains_p[i] = gains[i] / (gains3D_sum_pvf+2.23e-13f);}
}

Where "gains" are the original energy normalised VBAP gains and "gains_p" have amplitude normalisation for the low frequencies, and energy normalisation at the high frequencies [1].

Parameters

[in]	DTT	0..1 '0': for normal room, '1' for anechoic room, '0.5' for listening room
[in]	freq	Frequency vector in Hz; nFreq x 1
[in]	nFreq	Number of frequencies in the frequency vector
[out]	pValues	pValues for each frequency; nFreq x 1

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 475 of file saf_vbap.c.

◆ getSpreadSrcDirs3D()

void getSpreadSrcDirs3D	(	float	src_azi_rad,
		float	src_elev_rad,
		float	spread,
		int	num_src,
		int	num_rings_3d,
		float *	U_spread )

Computes a set of points which surround the source direction given a specific degree of spread.

Parameters

[in]	src_azi_rad	Source azimuth, in radians
[in]	src_elev_rad	Source elevation, in radians
[in]	spread	Spread in DEGREES
[in]	num_src	Number of auxiliary sources to use for spreading
[in]	num_rings_3d	Number of concentric rings of num_src each to generate inside the spreading surface
[out]	U_spread	Spread directions Cartesian coordinates; FLAT: (num_src*num_rings_3d+1) x 3

Definition at line 707 of file saf_vbap.c.

◆ invertLsMtx2D()

void invertLsMtx2D	(	float *	U_spkr,
		int *	ls_pairs,
		int	N_pairs,
		float **	layoutInvMtx )

Inverts a 2x2 loudspeaker matrix.

Parameters

[in]	U_spkr	Loudspeaker directions in cartesian (xy) coordinates; FLAT: L x 2
[in]	ls_pairs	Loudspeaker pair indices; FLAT: N_pairs x 3
[in]	N_pairs	Number of loudspeaker pairs
[out]	layoutInvMtx	(&) inverted 2x2 loudspeaker matrix flattened; FLAT: N_group x 4

Definition at line 930 of file saf_vbap.c.

◆ invertLsMtx3D()

void invertLsMtx3D	(	float *	U_spkr,
		int *	ls_groups,
		int	N_group,
		float **	layoutInvMtx )

Inverts a 3x3 loudspeaker matrix.

Parameters

[in]	U_spkr	Loudspeaker directions as cartesian coordinates (unit length); FLAT: L x 3
[in]	ls_groups	True loudspeaker triangle indices; FLAT: N_group x 3
[in]	N_group	Number of true loudspeaker triangles
[out]	layoutInvMtx	(&) inverted 3x3 loudspeaker matrices per group; FLAT: N_group x 9

Definition at line 676 of file saf_vbap.c.

◆ vbap2D()

void vbap2D	(	float *	src_dirs,
		int	src_num,
		int	ls_num,
		int *	ls_pairs,
		int	N_pairs,
		float *	layoutInvMtx,
		float **	GainMtx )

Calculates 2D VBAP gains for pre-calculated loudspeaker pairs and predefined source positions.

Parameters

[in]	src_dirs	Source directions in degrees; FLAT: src_num x 1
[in]	src_num	Number of sources
[in]	ls_num	Number of loudspeakers
[in]	ls_pairs	Loudspeaker pair indices; FLAT: N_pairs x 2
[in]	N_pairs	Number of loudspeaker pairs
[in]	layoutInvMtx	Inverted 2x2 loudspeaker matrix flattened; FLAT: N_pairs x 4
[out]	GainMtx	(&) Loudspeaker VBAP gain table; FLAT: src_num x ls_num

Definition at line 962 of file saf_vbap.c.

◆ vbap3D()

void vbap3D	(	float *	src_dirs,
		int	src_num,
		int	ls_num,
		int *	ls_groups,
		int	nFaces,
		float	spread,
		float *	layoutInvMtx,
		float **	GainMtx )

Calculates 3D VBAP gains given pre-computed loudspeaker triangles for each source direction.

Parameters

[in]	src_dirs	Source directions in degrees; FLAT: src_num x 2
[in]	src_num	Number of sources
[in]	ls_num	Number of loudspeakers
[in]	ls_groups	Loudspeaker triangle indices, see findLsTriplets(); FLAT: nFaces x 3
[in]	nFaces	Number of true loudspeaker triangles
[in]	spread	Spreading in degrees, 0: VBAP, >0: MDAP
[in]	layoutInvMtx	Inverted 3x3 loudspeaker matrix flattened, see invertLsMtx3D(); FLAT: nFaces x 9
[out]	GainMtx	(&) Loudspeaker VBAP gain table; FLAT: src_num x ls_num

Definition at line 786 of file saf_vbap.c.

◆ VBAPgainTable2InterpTable()

void VBAPgainTable2InterpTable	(	float *	vbap_gtable,
		int	nTable,
		int	nDirs )

Renormalises a VBAP gain table (in-place) so it may be utilised for interpolation of data (for example, powermaps or HRTFs)

Note: The VBAP gains are AMPLITUDE normalised; i.e. sum(gains) = 1.

Parameters

[in,out]	vbap_gtable	The 3D VBAP gain table; FLAT: nTable x nDirs
[in]	nTable	Number of points in the gain table
[in]	nDirs	Number of loudspeaker directions

Definition at line 369 of file saf_vbap.c.

Files

Functions

Detailed Description

Function Documentation

◆ compressVBAPgainTable3D()

◆ findLsPairs()

◆ findLsTriplets()

◆ generateVBAPgainTable2D()

◆ generateVBAPgainTable2D_srcs()

◆ generateVBAPgainTable3D()

◆ generateVBAPgainTable3D_srcs()

◆ getPvalues()

◆ getSpreadSrcDirs3D()

◆ invertLsMtx2D()

◆ invertLsMtx3D()

◆ vbap2D()

◆ vbap3D()

◆ VBAPgainTable2InterpTable()