#include <JPLSpatial/Panning/PannerBase.h>

Classes
struct	ChannelGroup

struct	PanUpdateData
	Parameters to update VBAP data for a source. More...

struct	PanUpdateDataWithOrientation

struct	VBAPLayoutBase

struct	VirtualSource

Public Types
using	Vec3Type = typename Traits::Vec3Type
	Aliases to avoid typing wordy templates.

template<class T >
using	Array = std::pmr::vector<T>

using	ChannelGainsRef = typename Traits::ChannelGains&

using	PanSourceOrientation = OrientationData<Vec3Type>

using	PanType = PannerType

using	LUTType = typename PanType::LUTType

using	LUTInterface = typename PanType::LUTInterface

using	SourceLayoutType = typename PanType::SourceLayout

Public Member Functions
bool	Initialize (ChannelMap channelMap)

JPL_INLINE bool	IsLUTInitialized () const noexcept

JPL_INLINE const LUTType *	GetLUT () const noexcept
	Get the look-up table. Can be nullptr, if hasn't been initialized yet.

JPL_INLINE bool	InitializeSourceLayout (ChannelMap channelMap, SourceLayoutType &outLayout) const
	Create/initialize SourceLayout for given source `channelMap`

JPL_INLINE void	GetSpeakerGains (const Vec3Type &direction, std::span< float > outGains) const

JPL_INLINE void	GetSpeakerGains (const simd &dirX, const simd &dirY, const simd &dirZ, std::span< simd > outGains) const

JPL_INLINE bool	IsInitialized () const noexcept

JPL_INLINE uint32	GetNumChannels () const noexcept

JPL_INLINE ChannelMap	GetChannelMap () const noexcept
	Get the channel map the panner is initialized to.

JPL_INLINE float	GetShortestSpeakerAperture () const noexcept

template<class OnChannelGeneratedCallback = std::identity>
JPL_INLINE void	ProcessVBAPData (const SourceLayoutType &sourceLayout, const PanUpdateData &updateData, std::span< float > outChannelMixMap, OnChannelGeneratedCallback &&onVSsGeneratedCb={}) const

template<class OnChannelGeneratedCallback = std::identity>
JPL_INLINE void	ProcessVBAPData (const SourceLayoutType &sourceLayout, const PanUpdateDataWithOrientation &updateData, std::span< float > outChannelMixMap, OnChannelGeneratedCallback &&onVSsGeneratedCb={}) const

JPL_INLINE void	ProcessVirtualSources (std::span< const VirtualSource > virtualSources, std::span< float > outGains) const

Static Public Member Functions
static JPL_INLINE void	NormalizeWeights (std::span< VirtualSource > virtualSources)
	Normalize weights of the virtual sources to ensure consistent energy.

Detailed Description

template<class PannerType, class Traits>
class JPL::VBAPannerBase< PannerType, Traits >

Vector Based Amplitude Panner that can handle panning from any source channel map to any target/output channel map.

Internally uses MDAP (Multiple Directions Amplitude Panning) with virtual sources (aka virtual positions).

SourceLayout and ProcessVBAPData function can be used for a more conventional channel map -> channel map panning, based on parameters like spread and focus, which can be driven by, for example, distance from the soruce to the listener (on the client side).

While VirtualSource(s) can be used directly with ProcessVirtualSources function for a more customizable spatialization, e.g. for volumetric sound sources, or any other cases where position and spatial extend of each channel needed to be manually cotrolled.

Instead of using VBAPannerBase directly, it is adviced to use 'VBAPanner2D' and 'VBAPanner3D' aliases from the similarly named files.

Member Typedef Documentation

◆ Array

template<class PannerType , class Traits >

template<class T >

using JPL::VBAPannerBase< PannerType, Traits >::Array = std::pmr::vector<T>

◆ ChannelGainsRef

template<class PannerType , class Traits >

using JPL::VBAPannerBase< PannerType, Traits >::ChannelGainsRef = typename Traits::ChannelGains&

◆ LUTInterface

template<class PannerType , class Traits >

using JPL::VBAPannerBase< PannerType, Traits >::LUTInterface = typename PanType::LUTInterface

◆ LUTType

template<class PannerType , class Traits >

using JPL::VBAPannerBase< PannerType, Traits >::LUTType = typename PanType::LUTType

◆ PanSourceOrientation

template<class PannerType , class Traits >

using JPL::VBAPannerBase< PannerType, Traits >::PanSourceOrientation = OrientationData<Vec3Type>

◆ PanType

template<class PannerType , class Traits >

using JPL::VBAPannerBase< PannerType, Traits >::PanType = PannerType

◆ SourceLayoutType

template<class PannerType , class Traits >

using JPL::VBAPannerBase< PannerType, Traits >::SourceLayoutType = typename PanType::SourceLayout

◆ Vec3Type

template<class PannerType , class Traits >

using JPL::VBAPannerBase< PannerType, Traits >::Vec3Type = typename Traits::Vec3Type

Aliases to avoid typing wordy templates.

Member Function Documentation

◆ GetChannelMap()

template<class PannerType , class Traits >

JPL_INLINE ChannelMap JPL::VBAPannerBase< PannerType, Traits >::GetChannelMap ( ) const

inlinenodiscardnoexcept

Get the channel map the panner is initialized to.

◆ GetLUT()

template<class PannerType , class Traits >

JPL_INLINE const LUTType * JPL::VBAPannerBase< PannerType, Traits >::GetLUT ( ) const

inlinenodiscardnoexcept

Get the look-up table. Can be nullptr, if hasn't been initialized yet.

◆ GetNumChannels()

template<class PannerType , class Traits >

JPL_INLINE uint32 JPL::VBAPannerBase< PannerType, Traits >::GetNumChannels ( ) const

inlinenodiscardnoexcept

Get number of channels the LUT is initialized for. Effectively this is the channel count of the channel map the panner is initialized for, including LFE (though LFE gain is always 0.0).

◆ GetShortestSpeakerAperture()

template<class PannerType , class Traits >

JPL_INLINE float JPL::VBAPannerBase< PannerType, Traits >::GetShortestSpeakerAperture ( ) const

inlinenodiscardnoexcept

Get shortest aperture between two speakers (dot product for 3D, angle for 2D panner). This is mainly useful for debuggint and verification.

◆ GetSpeakerGains() [1/2]

template<class PannerType , class Traits >

JPL_INLINE void JPL::VBAPannerBase< PannerType, Traits >::GetSpeakerGains	(	const simd &	dirX,
		const simd &	dirY,
		const simd &	dirZ,
		std::span< simd >	outGains ) const

Get speaker gains from LUT based on 'direction' vector. Vectorized version. Each SIMD lane must describe a normalized, non-zero unit vector; invalid input is undefined behavior.

Parameters

dirX	X components of the direction vectors.
dirY	Y components of the direction vectors.
dirZ	Z components of the direction vectors.
outGains	Must have one entry per target channel of this panner.

◆ GetSpeakerGains() [2/2]

template<class PannerType , class Traits >

JPL_INLINE void JPL::VBAPannerBase< PannerType, Traits >::GetSpeakerGains	(	const Vec3Type &	direction,
		std::span< float >	outGains ) const

Get speaker gains from LUT based on 'direction' vector.

Parameters

direction	: must be a normalized, non-zero unit vector; invalid input is undefined behavior
outGains	: must be of size equals to number of target channels of this panner

◆ Initialize()

template<class PannerType , class Traits >

bool JPL::VBAPannerBase< PannerType, Traits >::Initialize ( ChannelMap channelMap )

inline

Initialize the panner specific output layout.

Parameters

channelMap : target channel map to initialize the panner for

◆ InitializeSourceLayout()

template<class PannerType , class Traits >

JPL_INLINE bool JPL::VBAPannerBase< PannerType, Traits >::InitializeSourceLayout	(	ChannelMap	channelMap,
		SourceLayoutType &	outLayout ) const

Create/initialize SourceLayout for given source channelMap

◆ IsInitialized()

template<class PannerType , class Traits >

JPL_INLINE bool JPL::VBAPannerBase< PannerType, Traits >::IsInitialized ( ) const

inlinenodiscardnoexcept

Returns: true if LUT has been initialized and the panner can be used

◆ IsLUTInitialized()

template<class PannerType , class Traits >

JPL_INLINE bool JPL::VBAPannerBase< PannerType, Traits >::IsLUTInitialized ( ) const

inlinenodiscardnoexcept

◆ NormalizeWeights()

template<class PannerType , class Traits >

JPL_INLINE void JPL::VBAPannerBase< PannerType, Traits >::NormalizeWeights ( std::span< VirtualSource > virtualSources )

static

Normalize weights of the virtual sources to ensure consistent energy.

◆ ProcessVBAPData() [1/2]

template<class PannerType , class Traits >

template<class OnChannelGeneratedCallback >

JPL_INLINE void JPL::VBAPannerBase< PannerType, Traits >::ProcessVBAPData	(	const SourceLayoutType &	sourceLayout,
		const PanUpdateData &	updateData,
		std::span< float >	outChannelMixMap,
		OnChannelGeneratedCallback &&	onVSsGeneratedCb = {} ) const

This function should be called whenever pan data changes to update set gains based on PanUpdateData for each source channel retrieved by getOutGains callback. SourceLayout must be initialized beforehand. E.g. this would be called for each source that has unique channel layout or panning state

Parameters

sourceLayout	Initialized layout of the source channels.
updateData	Direction, focus, and spread parameters to process.
outChannelMixMap	: outptut channel mixing map, where for each source chanel there's a set of gain values for each target (e.g. for Stereo->Stereo [ sl_tl, sl_tr, sr_tl, sr_tr ])
onVSsGeneratedCb	Optional callback receiving the generated virtual-source directions and source-channel index.

◆ ProcessVBAPData() [2/2]

template<class PannerType , class Traits >

template<class OnChannelGeneratedCallback >

JPL_INLINE void JPL::VBAPannerBase< PannerType, Traits >::ProcessVBAPData	(	const SourceLayoutType &	sourceLayout,
		const PanUpdateDataWithOrientation &	updateData,
		std::span< float >	outChannelMixMap,
		OnChannelGeneratedCallback &&	onVSsGeneratedCb = {} ) const

◆ ProcessVirtualSources()

template<class PannerType , class Traits >

JPL_INLINE void JPL::VBAPannerBase< PannerType, Traits >::ProcessVirtualSources	(	std::span< const VirtualSource >	virtualSources,
		std::span< float >	outGains ) const

Get and accumulate speaker gains for all virtual sources. Weights of the virtual sources must be L1 normalized.

Parameters

virtualSources	Virtual sources to process.
outGains	Accumulated speaker gains.

The documentation for this class was generated from the following file:

JPLSpatial/Panning/PannerBase.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Array

◆ ChannelGainsRef

◆ LUTInterface

◆ LUTType

◆ PanSourceOrientation

◆ PanType

◆ SourceLayoutType

◆ Vec3Type

Member Function Documentation

◆ GetChannelMap()

◆ GetLUT()

◆ GetNumChannels()

◆ GetShortestSpeakerAperture()

◆ GetSpeakerGains() [1/2]

◆ GetSpeakerGains() [2/2]

◆ Initialize()

◆ InitializeSourceLayout()

◆ IsInitialized()

◆ IsLUTInitialized()

◆ NormalizeWeights()

◆ ProcessVBAPData() [1/2]

◆ ProcessVBAPData() [2/2]

◆ ProcessVirtualSources()