JPL Spatial
Sound spatialization and propagation library
Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
JPL::VBAPannerBase< PannerType, Traits > Class Template Reference

#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 InitializeLUT (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
inlinenoexcept

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
inlinenoexcept

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
inlinenoexcept

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
inlinenoexcept

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. Vecrorized version.

Parameters
outGains: must be of size equals to number of target channels 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
outGains: must be of size equals to number of target channels of this panner

◆ InitializeLUT()

template<class PannerType , class Traits >
bool JPL::VBAPannerBase< PannerType, Traits >::InitializeLUT ( ChannelMap  channelMap)
inline

Initialize LUT for a specific channelMap.

Parameters
channelMap: target channel map to create LUT 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
inlinenoexcept
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
inlinenoexcept

◆ 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
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 ])

◆ 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 soruces into @outGains Weights of the virtual sources must be L1 normalized

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