VISR  0.11.7
Versatile Interactive Scene Renderer
visr::panning::LoudspeakerArray Class Reference

#include <LoudspeakerArray.h>

Public Types

using LoudspeakerIdType = std::string
 
using LoudspeakerIndexType = std::size_t
 
using SampleType = visr::SampleType
 
using TripletType = std::array< LoudspeakerIndexType, 3 >
 
using ChannelIndex = std::size_t
 

Public Member Functions

 LoudspeakerArray ()
 
 LoudspeakerArray (std::string const &xmlConfiguration)
 
LoudspeakerArray const & operator= (LoudspeakerArray const &rhs)
 
 ~LoudspeakerArray ()
 
void loadXmlFile (std::string const &filePath)
 
void loadXmlStream (std::istream &stream)
 
void loadXmlString (std::string const &xmlString)
 
XYZgetPosition (std::size_t iSpk)
 
XYZ const & getPosition (std::size_t iSpk) const
 
XYZgetPosition (LoudspeakerIdType const &id)
 
XYZ const & getPosition (LoudspeakerIdType const &id) const
 
XYZgetPositions ()
 
XYZ const * getPositions () const
 
LoudspeakerIdType const & loudspeakerId (LoudspeakerIndexType const &index) const
 
ChannelIndex channelIndex (std::size_t spkIndex) const
 
LoudspeakerIndexType getSpeakerIndexFromId (LoudspeakerIdType const &id) const
 
ChannelIndex getSpeakerChannel (std::size_t spkIndex) const
 
ChannelIndex getSpeakerChannelFromId (LoudspeakerIdType const &id) const
 
std::size_t setTriplet (std::size_t iTri, std::size_t l1, std::size_t l2, std::size_t l3)
 
TripletTypegetTriplet (std::size_t iTri)
 
TripletType const & getTriplet (std::size_t iTri) const
 
std::size_t getNumSpeakers () const
 
std::size_t getNumRegularSpeakers () const
 
ChannelIndex const * getLoudspeakerChannels () const
 
std::size_t getNumTriplets () const
 
bool is2D () const
 
bool isInfinite () const
 
std::size_t getNumSubwoofers () const
 
ChannelIndex const * getSubwooferChannels () const
 
ChannelIndex getSubwooferChannel (std::size_t subIdx) const
 
efl::BasicMatrix< SampleType > const & getSubwooferGains () const
 
SampleType getSubwooferGain (std::size_t subIdx, std::size_t spkIdx) const
 
efl::BasicMatrix< SampleType > const & getReroutingCoefficients () const
 
SampleType getReroutingCoefficient (std::size_t virtIdx, std::size_t realIdx) const
 
SampleType getLoudspeakerGainAdjustment (std::size_t spkIdx) const
 
SampleType getLoudspeakerDelayAdjustment (std::size_t spkIdx) const
 
SampleType getSubwooferGainAdjustment (std::size_t spkIdx) const
 
SampleType getSubwooferDelayAdjustment (std::size_t spkIdx) const
 
efl::BasicVector< SampleType > const & getGainAdjustment () const
 
efl::BasicVector< SampleType > const & getDelayAdjustment () const
 
bool outputEqualisationPresent () const
 
std::size_t outputEqualisationNumberOfBiquads () const
 
rbbl::BiquadCoefficientMatrix< SampleType > const & outputEqualisationBiquads () const
 

Member Typedef Documentation

◆ ChannelIndex

Type to denote the output signal channels for a regular loudspeaker.

Note
the channels are assumed to be specified and stored as one-offset numbers.

◆ LoudspeakerIdType

Id type to denote loudspeakers by name. This name is also used in the triplet (or polygon) specifications to define the VBAP triangulation.

◆ LoudspeakerIndexType

Type for specifying loudspeaker indices in triplets. At the moment, we use 'int' to let negative numbers denote invalid/unused triplets.

◆ SampleType

Typ used for all numeric quantities such as as positions coordinates.

◆ TripletType

Constructor & Destructor Documentation

◆ LoudspeakerArray() [1/2]

visr::panning::LoudspeakerArray::LoudspeakerArray ( )

Default contructor, initialises numbers of elements and channel indices to safe values.

◆ LoudspeakerArray() [2/2]

visr::panning::LoudspeakerArray::LoudspeakerArray ( std::string const &  xmlConfiguration)
explicit

Construct an initialised array configuration.

Exceptions
std::invalid_argumentif the file xmlConfiguration is not found or inconsistent.

◆ ~LoudspeakerArray()

visr::panning::LoudspeakerArray::~LoudspeakerArray ( )

Destructor.

Note
We need to provide a destructor implementation because we use a unique_ptr to the forward-declared class BiquadParameterMatrix.

Member Function Documentation

◆ channelIndex()

ChannelIndex visr::panning::LoudspeakerArray::channelIndex ( std::size_t  spkIndex) const
inline

Return the loudspeaker index associated with a loudspeaker at a given position in the loudspeaker array.

Note
the indices are assigned to speaker positions during the setup process and do not necessarily the order in which they are specified in the configuration file.
Exceptions
std::out_of_rangeIf index exceeds the number of regular loudspeaker.

◆ getDelayAdjustment()

efl::BasicVector<SampleType> const& visr::panning::LoudspeakerArray::getDelayAdjustment ( ) const
inline

Return the delay adjustment vector (in seconds) holding the delays for all regular loudspeakers and subwoofers. The loudspeaker delays are ordered according to their zero-offset logical speaker numbers, followed by the subwoofers in their order of definition in the configuration file.

◆ getGainAdjustment()

efl::BasicVector<SampleType> const& visr::panning::LoudspeakerArray::getGainAdjustment ( ) const
inline

Return the gain adjustment vector (linear scale) holding the gains for all regular loudspeakers and subwoofers. The loudspeaker gains are ordered according to their zero-offset logical speaker numbers, followed by the subwoofers in their order of definition in the configuration file.

◆ getLoudspeakerChannels()

ChannelIndex const* visr::panning::LoudspeakerArray::getLoudspeakerChannels ( ) const
inline

◆ getLoudspeakerDelayAdjustment()

SampleType visr::panning::LoudspeakerArray::getLoudspeakerDelayAdjustment ( std::size_t  spkIdx) const
inline

◆ getLoudspeakerGainAdjustment()

SampleType visr::panning::LoudspeakerArray::getLoudspeakerGainAdjustment ( std::size_t  spkIdx) const
inline

Gain and delay adjustments.

◆ getNumRegularSpeakers()

std::size_t visr::panning::LoudspeakerArray::getNumRegularSpeakers ( ) const
inline

Retrieve the number of regular loudspeakers, excluding virtual loudspeakers and subwoofers.

◆ getNumSpeakers()

std::size_t visr::panning::LoudspeakerArray::getNumSpeakers ( ) const
inline

Return the total number of loudspeakers, including virtual speaker positions. Subwoofers are not considered as regular louspeakers.

◆ getNumSubwoofers()

std::size_t visr::panning::LoudspeakerArray::getNumSubwoofers ( ) const
inline

Subwoofer configuration support. Supported only by the XML configuration format. Return the number of subwoofers.

◆ getNumTriplets()

std::size_t visr::panning::LoudspeakerArray::getNumTriplets ( ) const
inline

◆ getPosition() [1/4]

XYZ& visr::panning::LoudspeakerArray::getPosition ( std::size_t  iSpk)
inline

Return the position of a loudspeaker based on its sorted position.

◆ getPosition() [2/4]

XYZ const& visr::panning::LoudspeakerArray::getPosition ( std::size_t  iSpk) const
inline

◆ getPosition() [3/4]

XYZ& visr::panning::LoudspeakerArray::getPosition ( LoudspeakerIdType const &  id)
inline

Return the position of a loudspeaker given its string id

◆ getPosition() [4/4]

XYZ const& visr::panning::LoudspeakerArray::getPosition ( LoudspeakerIdType const &  id) const
inline

◆ getPositions() [1/2]

XYZ* visr::panning::LoudspeakerArray::getPositions ( )
inline

◆ getPositions() [2/2]

XYZ const* visr::panning::LoudspeakerArray::getPositions ( ) const
inline

◆ getReroutingCoefficient()

SampleType visr::panning::LoudspeakerArray::getReroutingCoefficient ( std::size_t  virtIdx,
std::size_t  realIdx 
) const
inline

Retrieve the rereouting coefficient from a virtual to a real loudspeaker

Parameters
virtIdxvirtual loudspeaker index (zero-offset)
realIdxreal loudspeaker index (zero-offset) This is the logical speaker index, not the channel index used for routing.
Returns
Rerouting coefficient as a linear-scale gain value (not incorporating gain corrections applied to the channel signal).
Exceptions
std::out_of_rangeif either virtIdx or realIdx is out of the respective admissible range.

◆ getReroutingCoefficients()

efl::BasicMatrix<SampleType> const& visr::panning::LoudspeakerArray::getReroutingCoefficients ( ) const
inline

Virtual speaker rerouting matrix configuration support. Retrieve the matrix of rereouting coefficients from virtual to real loudspeakers

Returns
Reference to rereouting matrix, dimension number of virtual loudspeakers * number of physical loudspeakers.

◆ getSpeakerChannel()

ChannelIndex visr::panning::LoudspeakerArray::getSpeakerChannel ( std::size_t  spkIndex) const
inline

Return the output channel index from a the speaker id of a regular loudspeaker.

Parameters
spkIndexThe index into the loudspeaker array.
Exceptions
std::out_of_rangeIf spkIndex exceeds the number of regular loudspeakers.
Note
The indices into the loudspeakers are assigned during construction and do not necessarily match the order in the configuration file.

◆ getSpeakerChannelFromId()

ChannelIndex visr::panning::LoudspeakerArray::getSpeakerChannelFromId ( LoudspeakerIdType const &  id) const
inline

Return the output channel index (one-offset) from a loudspeaker string id.

Parameters
idString id corresponding to an existing regular loudspeaker.
Exceptions
std::out_of_rangeIf id does not correspond to an existing regular loudspeaker.

◆ getSpeakerIndexFromId()

LoudspeakerIndexType visr::panning::LoudspeakerArray::getSpeakerIndexFromId ( LoudspeakerIdType const &  id) const

Return the index into the loudspeaker array for a speaker denoted by its string id.

Parameters
idloudspeaker id for either a regular or virtual loudspeaker.
Exceptions
std::out_of_rangeIf index exceeds the range of regular and virtual loudspeakers.

◆ getSubwooferChannel()

ChannelIndex visr::panning::LoudspeakerArray::getSubwooferChannel ( std::size_t  subIdx) const
inline

◆ getSubwooferChannels()

ChannelIndex const* visr::panning::LoudspeakerArray::getSubwooferChannels ( ) const
inline

◆ getSubwooferDelayAdjustment()

SampleType visr::panning::LoudspeakerArray::getSubwooferDelayAdjustment ( std::size_t  spkIdx) const
inline

◆ getSubwooferGain()

SampleType visr::panning::LoudspeakerArray::getSubwooferGain ( std::size_t  subIdx,
std::size_t  spkIdx 
) const
inline

Retrieve the matrix gain from a given loudspeaker to a given subwoofer.

Parameters
subIdxSubwoofer index (zero-offset)
spkIdxLoudspeaker index (zero-offset) This is the logical speaker index, not the channel index used for routing.
Returns
Linear-scale gain value (not incorporating gain corrections applied to the channel signal).
Exceptions
std::out_of_rangeif either subIdx or spkIdx is out of the respective admissible range.

◆ getSubwooferGainAdjustment()

SampleType visr::panning::LoudspeakerArray::getSubwooferGainAdjustment ( std::size_t  spkIdx) const
inline

◆ getSubwooferGains()

efl::BasicMatrix<SampleType> const& visr::panning::LoudspeakerArray::getSubwooferGains ( ) const
inline

Retrieve the gain matrix for panning loudspeaker signals into the subwoofers.

Returns
Reference to gain matrix, dimension number of subwoofers * number of physical loudspeakers.

◆ getTriplet() [1/2]

TripletType& visr::panning::LoudspeakerArray::getTriplet ( std::size_t  iTri)
inline

◆ getTriplet() [2/2]

TripletType const& visr::panning::LoudspeakerArray::getTriplet ( std::size_t  iTri) const
inline

◆ is2D()

bool visr::panning::LoudspeakerArray::is2D ( ) const
inline

◆ isInfinite()

bool visr::panning::LoudspeakerArray::isInfinite ( ) const
inline

◆ loadXmlFile()

void visr::panning::LoudspeakerArray::loadXmlFile ( std::string const &  filePath)

Initialise the loudspeaker array object from a file containing an array configuration in XML format

Parameters
filePathFull file path(including path and file extension).

◆ loadXmlStream()

void visr::panning::LoudspeakerArray::loadXmlStream ( std::istream &  stream)

Initialise the loudspeaker array object from a stream holding the array configuration in XML format.

Parameters
streamInitialised stream object holding an XML configuration.

◆ loadXmlString()

void visr::panning::LoudspeakerArray::loadXmlString ( std::string const &  xmlString)

Initialise the loudspeaker array object from a string containg the array configuration in XML format.

Parameters
xmlStringString containing a XML array configuration as the top-level node.

◆ loudspeakerId()

LoudspeakerIdType const& visr::panning::LoudspeakerArray::loudspeakerId ( LoudspeakerIndexType const &  index) const

Return the loudspeaker id (a string label) corresponding to the given (sorted) loudspeaker label.

Parameters
indexzero-offset index into the loudspeaker array.
Exceptions
std::out_of_rangeIf index exceeds the range of regular and virt ual loudspeakers.

◆ operator=()

LoudspeakerArray const& visr::panning::LoudspeakerArray::operator= ( LoudspeakerArray const &  rhs)

Assignment operator We need an explicitly defined assignment operator because some members (BasicMatrix) intentionally do not have a copy constructor.

◆ outputEqualisationBiquads()

rbbl::BiquadCoefficientMatrix<SampleType> const& visr::panning::LoudspeakerArray::outputEqualisationBiquads ( ) const

Return a matrix containing the biquad parameters for all output sections. The dimension of the matrix is (numRegularSpeakers()+getNumSubwoofers()) x outputEqualisationNumberOfBiquads()

Exceptions
std::logic_errorif no output EQ configuration is present, i.e., outputEqualisationPresent() is false.

◆ outputEqualisationNumberOfBiquads()

std::size_t visr::panning::LoudspeakerArray::outputEqualisationNumberOfBiquads ( ) const

Query the number of biquads per output channel. Returns 0 if no equalisation configuration is present.

◆ outputEqualisationPresent()

bool visr::panning::LoudspeakerArray::outputEqualisationPresent ( ) const

Optional support for equalization of ouput channels. Query if the array configuration contained an output equalisation configuration. Technically, that means that the XML file contains a outputEqConfiguration section.

◆ setTriplet()

std::size_t visr::panning::LoudspeakerArray::setTriplet ( std::size_t  iTri,
std::size_t  l1,
std::size_t  l2,
std::size_t  l3 
)
inline

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