Files
file	saf_cdf4sap.c
	Public source for the Covariance Domain Framework module (SAF_CDF4SAP_MODULE)

file	saf_cdf4sap.h
	Main header for the Covariance Domain Framework module (SAF_CDF4SAP_MODULE)

Functions
void	cdf4sap_create (void **const phCdf, int nXcols, int nYcols)
	Creates an instance of the Covariance Domain Framework.

void	cdf4sap_cmplx_create (void **const phCdf, int nXcols, int nYcols)
	Creates an instance of the Covariance Domain Framework.

void	cdf4sap_destroy (void **const phCdf)
	Destroys an instance of the Covariance Domain Framework.

void	cdf4sap_cmplx_destroy (void **const phCdf)
	Destroys an instance of the Covariance Domain Framework.

void	formulate_M_and_Cr (void const hCdf, float Cx, float Cy, float Q, int useEnergyFLAG, float reg, float M, float Cr)
	Computes the optimal mixing matrices.

void	formulate_M_and_Cr_cmplx (void const hCdf, float_complex Cx, float_complex Cy, float_complex Q, int useEnergyFLAG, float reg, float_complex M, float_complex Cr)
	Computes the optimal mixing matrices.

Detailed Description

Covariance domain framework processing module

Function Documentation

◆ cdf4sap_cmplx_create()

void cdf4sap_cmplx_create	(	void **const	phCdf,
		int	nXcols,
		int	nYcols )

Creates an instance of the Covariance Domain Framework.

Note: Use this function for complex-valued input/output matrices. For real-valued input/output matrices use cdf4sap_create().

Parameters

[in]	phCdf	The address (&) of the CDF4SAP handle
[in]	nXcols	Number of columns/rows in square input matrix 'Cx'
[in]	nYcols	Number of columns/rows in square input matrix 'Cy'

Definition at line 139 of file saf_cdf4sap.c.

◆ cdf4sap_cmplx_destroy()

void cdf4sap_cmplx_destroy ( void **const phCdf )

Destroys an instance of the Covariance Domain Framework.

Note: Use this function for complex-valued input/output matrices. For real-valued input/output matrices use cdf4sap_destroy().

Parameters

[in] phCdf The address (&) of the CDF4SAP handle

Definition at line 233 of file saf_cdf4sap.c.

◆ cdf4sap_create()

void cdf4sap_create	(	void **const	phCdf,
		int	nXcols,
		int	nYcols )

Creates an instance of the Covariance Domain Framework.

Note: Use this function for real-valued input/output matrices. For complex-valued input/output matrices use cdf4sap_cmplx_create().

Parameters

[in]	phCdf	The address (&) of the CDF4SAP handle
[in]	nXcols	Number of columns/rows in square input matrix 'Cx'
[in]	nYcols	Number of columns/rows in square input matrix 'Cy'

Definition at line 84 of file saf_cdf4sap.c.

◆ cdf4sap_destroy()

void cdf4sap_destroy ( void **const phCdf )

Destroys an instance of the Covariance Domain Framework.

Note: Use this function for real-valued input/output matrices. For complex-valued input/output matrices use cdf4sap_cmplx_destroy().

Parameters

[in] phCdf The address (&) of the CDF4SAP handle

Definition at line 196 of file saf_cdf4sap.c.

◆ formulate_M_and_Cr()

void formulate_M_and_Cr	(	void *const	hCdf,
		float *	Cx,
		float *	Cy,
		float *	Q,
		int	useEnergyFLAG,
		float	reg,
		float *	M,
		float *	Cr )

Computes the optimal mixing matrices.

This function solves the problem of determining the optimal mixing matrices 'M' and 'Mr', such that the covariance matrix of the output: y_out = M*x + Mr*decorrelated(x), is aligned with the target matrix 'Cy', given the covariance matrix of input x, Cx=x*x^H, and a prototype mixing matrix Q. For the derivation and a more detailed description, the reader is referred to [1,2].

Note: Use this function for real-valued input/output matrices. For complex-valued input/output use formulate_M_and_Cr_cmplx().; For an example of how to use this function, one may refer to the implementation of the parametric binaural Ambisonic decoder (described in [3]) found here: https://github.com/leomccormack/CroPaC-Binaural, or the relevant unit tests.

Test: test__formulate_M_and_Cr()

Parameters

[in]	hCdf	Covariance Domain Framework handle
[in]	Cx	Covariance matrix of input 'x'; FLAT: nXcols x nXcols
[in]	Cy	Target covariance matrix; FLAT: nYcols x nYcols
[in]	Q	Prototype matrix; FLAT: nYcols x nXcols
[in]	useEnergyFLAG	Set to '0' to apply energy compensation to 'M' instead of outputing 'Cr'. Set to '1' to output 'Cr'
[in]	reg	Regularisation term (suggested: 0.2f)
[out]	M	Mixing matrix; FLAT: nYcols x nXcols
[out]	Cr	Mixing matrix residual, set to NULL if not needed; FLAT: nYcols x nYcols

See also: [1] Vilkamo, J., Ba"ckstro"m, T., & Kuntz, A. (2013). Optimized covariance domain framework for time–frequency processing of spatial audio. Journal of the Audio Engineering Society, 61(6), 403-411.; [2] Vilkamo, J., & Ba"ckstro"m, T. (2018). Time–Frequency Processing: Methods and Tools. In Parametric Time–Frequency Domain Spatial Audio. John Wiley & Sons.; [3] McCormack, L., Delikaris-Manias, S. (2019). "Parametric first-order ambisonic decoding for headphones utilising the Cross-Pattern Coherence algorithm". inProc 1st EAA Spatial Audio Signal Processing Symposium, Paris, France.

Definition at line 272 of file saf_cdf4sap.c.

◆ formulate_M_and_Cr_cmplx()

void formulate_M_and_Cr_cmplx	(	void *const	hCdf,
		float_complex *	Cx,
		float_complex *	Cy,
		float_complex *	Q,
		int	useEnergyFLAG,
		float	reg,
		float_complex *	M,
		float_complex *	Cr )

Computes the optimal mixing matrices.

This function solves the problem of determining the optimal mixing matrices 'M' and 'Mr', such that the covariance matrix of the output: y_out = M*x + Mr*decorrelated(x), is aligned with the target matrix 'Cy', given the covariance matrix of input x, Cx=x*x^H, and a prototype mixing matrix Q. For the derivation and a more detailed description, the reader is referred to [1,2].

Note: Use this function for complex-valued input/output matrices. For real-valued input/output use formulate_M_and_Cr().; For an example of how to use this function, one may refer to the implementation of the parametric binaural Ambisonic decoder (described in [3]) found here: https://github.com/leomccormack/CroPaC-Binaural, or the relevant unit tests.

Test: test__formulate_M_and_Cr_cmplx()

Parameters

[in]	hCdf	Covariance Domain Framework handle
[in]	Cx	Covariance matrix of input 'x'; FLAT: nXcols x nXcols
[in]	Cy	Target covariance matrix; FLAT: nYcols x nYcols
[in]	Q	Prototype matrix; FLAT: nYcols x nXcols
[in]	useEnergyFLAG	Set to '0' to apply energy compensation to 'M' instead of outputing 'Cr'. Set to '1' to output 'Cr'
[in]	reg	Regularisation term (suggested: 0.2f)
[out]	M	Mixing matrix; FLAT: nYcols x nXcols
[out]	Cr	Mixing matrix residual, set to NULL if not needed; FLAT: nYcols x nYcols

See also: [1] Vilkamo, J., Ba"ckstro"m, T., & Kuntz, A. (2013). Optimized covariance domain framework for time–frequency processing of spatial audio. Journal of the Audio Engineering Society, 61(6), 403-411.; [2] Vilkamo, J., & Ba"ckstro"m, T. (2018). Time–Frequency Processing: Methods and Tools. In Parametric Time–Frequency Domain Spatial Audio. John Wiley & Sons.; [3] McCormack, L., Delikaris-Manias, S. (2019). "Parametric first-order ambisonic decoding for headphones utilising the Cross-Pattern Coherence algorithm". inProc 1st EAA Spatial Audio Signal Processing Symposium, Paris, France.

Definition at line 406 of file saf_cdf4sap.c.

Files

Functions

Detailed Description

Function Documentation

◆ cdf4sap_cmplx_create()

◆ cdf4sap_cmplx_destroy()

◆ cdf4sap_create()

◆ cdf4sap_destroy()

◆ formulate_M_and_Cr()

◆ formulate_M_and_Cr_cmplx()