VISR  0.11.6
Versatile Interactive Scene Renderer
visr::rbbl::CoreConvolverUniform< SampleType > Class Template Reference

#include <core_convolver_uniform.hpp>

Public Types

using FrequencyDomainType = typename FftWrapperBase< SampleType >::FrequencyDomainType
 

Public Member Functions

 CoreConvolverUniform (std::size_t numberOfInputs, std::size_t numberOfOutputs, std::size_t blockLength, std::size_t maxFilterLength, std::size_t maxFilterEntries, efl::BasicMatrix< SampleType > const &initialFilters=efl::BasicMatrix< SampleType >(), std::size_t alignment=0, char const *fftImplementation="default")
 
 ~CoreConvolverUniform ()
 
std::size_t numberOfInputs () const
 
std::size_t numberOfOutputs () const
 
std::size_t blockLength () const
 
std::size_t dftBlockRepresentationSize () const
 
std::size_t numberOfFilterPartitions () const
 
std::size_t dftFilterRepresentationSize () const
 
std::size_t maxNumberOfFilterEntries () const
 
std::size_t maxFilterLength () const
 
FrequencyDomainTypegetFdlBlock (std::size_t inputIdx, std::size_t blockIdx)
 
FrequencyDomainType const * getFdlBlock (std::size_t inputIdx, std::size_t blockIdx) const
 
FrequencyDomainTypegetFdFilterPartition (std::size_t filterIdx, std::size_t blockIdx)
 
FrequencyDomainType const * getFdFilterPartition (std::size_t filterIdx, std::size_t blockIdx) const
 
std::size_t alignment () const
 
std::size_t complexAlignment () const
 
void advanceFDL ()
 
void setFilter (FrequencyDomainType const *transformedFilter, std::size_t filterIdx, std::size_t alignment=0)
 
void transformImpulseResponse (SampleType const *ir, std::size_t irLength, FrequencyDomainType *result, std::size_t alignment=0) const
 
void clearFilters ()
 
void initFilters (efl::BasicMatrix< SampleType > const &newFilters)
 
void setImpulseResponse (SampleType const *ir, std::size_t filterLength, std::size_t filterIdx, std::size_t alignment=0)
 
void processInputs (SampleType const *const input, std::size_t channelStride, std::size_t alignment)
 
void processFilter (std::size_t inputIndex, std::size_t filterIndex, SampleType gain, FrequencyDomainType *result, bool add)
 
void transformOutput (FrequencyDomainType const *fdBlock, SampleType *tdResult)
 
SampleType calculateFilterScalingFactor () const
 
static std::size_t calculateNumberOfPartitions (std::size_t filterLength, std::size_t blockLength)
 
static std::size_t calculateDftSize (std::size_t blockLength)
 
static std::size_t calculateDftRepresentationSizePadded (std::size_t blockLength, std::size_t alignment)
 

Detailed Description

template<typename SampleType>
class visr::rbbl::CoreConvolverUniform< SampleType >

Base class for MIMO convolution using a uniformly partioned fast convolution algorithm. It supports a arbitrary numbers of input and output channels and enables filters and an optional gain factor for arbitrary input-output connections.

Template Parameters
SampleTypeThe floating-point type of the signal samples

Member Typedef Documentation

◆ FrequencyDomainType

The representation for the complex frequency-domain elements. Note: The used FFT libraries depend on the fact that arrays of this type can be cast into arrays of the corresponding real types with interleaved real and imaginary elements. SampleType arrays with interleaved real and imaginary components.

Constructor & Destructor Documentation

◆ CoreConvolverUniform()

template<typename SampleType >
visr::rbbl::CoreConvolverUniform< SampleType >::CoreConvolverUniform ( std::size_t  numberOfInputs,
std::size_t  numberOfOutputs,
std::size_t  blockLength,
std::size_t  maxFilterLength,
std::size_t  maxFilterEntries,
efl::BasicMatrix< SampleType > const &  initialFilters = efl::BasicMatrix<SampleType>(),
std::size_t  alignment = 0,
char const *  fftImplementation = "default" 
)
explicit

Constructor.

Parameters
numberOfInputsThe number of input signals processed.
numberOfOutputsThe number of output channels produced.
blockLengthThe numbers of samples processed for each input or output channels in one process() call.
maxFilterLengthThe maximum length of the FIR filters (in samples).
maxFilterEntriesThe maximum number of filters that can be stored within the filter. This number can be different from maxRoutingPoints, as the convolver can both reuse the same filter representation multiple times, or store multiple filter representations to enable switching of the filter characteristics at runtime.
initialFiltersThe initial set of filter coefficients. The matrix rows represent the distinct filters.
alignmentThe alignment (given as a multiple of the sample type size) to be used to allocate all data structure. It also guaranteees the alignment of the input and output samples to the process call.
fftImplementationA string to determine the FFT wrapper to be used. The default value results in using the default FFT implementation for the given data type.

◆ ~CoreConvolverUniform()

template<typename SampleType >
visr::rbbl::CoreConvolverUniform< SampleType >::~CoreConvolverUniform ( )
default

Destructor.

Member Function Documentation

◆ advanceFDL()

template<typename SampleType >
void visr::rbbl::CoreConvolverUniform< SampleType >::advanceFDL ( )

Advance the freuquency-domain delay line by one block.

Postcondition
The zero-indexed block contains the "oldest" data, to be overwritten.

◆ alignment()

template<typename SampleType>
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::alignment ( ) const
inline

◆ blockLength()

template<typename SampleType>
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::blockLength ( ) const
inline

◆ calculateDftRepresentationSizePadded()

template<typename SampleType >
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::calculateDftRepresentationSizePadded ( std::size_t  blockLength,
std::size_t  alignment 
)
static

Return the number of complex values to represent the frequency-domain DFT representation when padded to the requested alignment.

Parameters
blockLengthThe number of values consumed and produced in each process() call.
alignmentThe alignment (in number of complex elements)

◆ calculateDftSize()

template<typename SampleType >
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::calculateDftSize ( std::size_t  blockLength)
static

Return the size of the DFT, i.e., the number of real inputs samples passed to each forward FFT call.

◆ calculateFilterScalingFactor()

template<typename SampleType >
SampleType visr::rbbl::CoreConvolverUniform< SampleType >::calculateFilterScalingFactor ( ) const

Calculate the scaling factor to be applied to the transformed input filters. This factor is necessary to account for the different normalisation strategies used in different FFT libraries (i.e., whether normalization is done in the forward or the inverse transform, distributed between the two (unitary transform), or not at all.

Exceptions
std::logic_errorIf the Fft representation object has not been initialised.

◆ calculateNumberOfPartitions()

template<typename SampleType >
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::calculateNumberOfPartitions ( std::size_t  filterLength,
std::size_t  blockLength 
)
static

Helper functions to calculate the parameters of the partitioned convolution algorithm. Calculate the number of filter partitions for the nonuniformly partitioned convolution algorithm.

◆ clearFilters()

template<typename SampleType >
void visr::rbbl::CoreConvolverUniform< SampleType >::clearFilters ( )

Manipulation of the contained filter representation. Reset all filters to zero.

◆ complexAlignment()

template<typename SampleType>
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::complexAlignment ( ) const
inline

◆ dftBlockRepresentationSize()

template<typename SampleType>
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::dftBlockRepresentationSize ( ) const
inline

Return the size of a DFT block.

Note
that returns the padded size, including padding between DFT blocks introduced for alinment.

◆ dftFilterRepresentationSize()

template<typename SampleType>
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::dftFilterRepresentationSize ( ) const
inline

Return the size of the frequency-domain filter representation (in complex elements )

◆ getFdFilterPartition() [1/2]

template<typename SampleType >
CoreConvolverUniform< SampleType >::FrequencyDomainType * visr::rbbl::CoreConvolverUniform< SampleType >::getFdFilterPartition ( std::size_t  filterIdx,
std::size_t  blockIdx 
)
inline

◆ getFdFilterPartition() [2/2]

template<typename SampleType >
CoreConvolverUniform< SampleType >::FrequencyDomainType const * visr::rbbl::CoreConvolverUniform< SampleType >::getFdFilterPartition ( std::size_t  filterIdx,
std::size_t  blockIdx 
) const
inline

◆ getFdlBlock() [1/2]

template<typename SampleType >
CoreConvolverUniform< SampleType >::FrequencyDomainType * visr::rbbl::CoreConvolverUniform< SampleType >::getFdlBlock ( std::size_t  inputIdx,
std::size_t  blockIdx 
)
inline

◆ getFdlBlock() [2/2]

template<typename SampleType >
CoreConvolverUniform< SampleType >::FrequencyDomainType const * visr::rbbl::CoreConvolverUniform< SampleType >::getFdlBlock ( std::size_t  inputIdx,
std::size_t  blockIdx 
) const
inline

◆ initFilters()

template<typename SampleType >
void visr::rbbl::CoreConvolverUniform< SampleType >::initFilters ( efl::BasicMatrix< SampleType > const &  newFilters)

Load a new set of impulse responses, resetting all prior loaded filters. If there are fewer filters in the matrix than the maximum admissible number, the remaining filters are set to zero. Likewise, if the length of the new filters is less than the maximum allowed filter length, the remaining elements are set to zero.

Parameters
newFiltersThe matrix of new filters, with each row representing a filter.
Exceptions
std::invalid_argumentIf the number of filters (number of rows) exceeds the maximum admissible number of filters.
std::invalid_argumeentIf the length of the filters (number of matrix columns) exceeds the maximum admissible length,

◆ maxFilterLength()

template<typename SampleType>
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::maxFilterLength ( ) const
inline

◆ maxNumberOfFilterEntries()

template<typename SampleType>
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::maxNumberOfFilterEntries ( ) const
inline

◆ numberOfFilterPartitions()

template<typename SampleType>
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::numberOfFilterPartitions ( ) const
inline

◆ numberOfInputs()

template<typename SampleType>
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::numberOfInputs ( ) const
inline

Number of input signals to the MIMO convolution process.

◆ numberOfOutputs()

template<typename SampleType>
std::size_t visr::rbbl::CoreConvolverUniform< SampleType >::numberOfOutputs ( ) const
inline

◆ processFilter()

template<typename SampleType >
void visr::rbbl::CoreConvolverUniform< SampleType >::processFilter ( std::size_t  inputIndex,
std::size_t  filterIndex,
SampleType  gain,
FrequencyDomainType result,
bool  add 
)

Perform the frequency-domain block convolution for the combination of an input and a filter.

◆ processInputs()

template<typename SampleType >
void visr::rbbl::CoreConvolverUniform< SampleType >::processInputs ( SampleType const *const  input,
std::size_t  channelStride,
std::size_t  alignment 
)

◆ setFilter()

template<typename SampleType >
void visr::rbbl::CoreConvolverUniform< SampleType >::setFilter ( FrequencyDomainType const *  transformedFilter,
std::size_t  filterIdx,
std::size_t  alignment = 0 
)

Assign an already transformed filter to a specific index of the the filter matrix.

Parameters
transformedFilterThe frequency-domain representation of the filter.
filterIdxThe filter index to which the filter is assigned.
alignmentThe guaranteed alignment of the transformedFilter argument (as a multiple of the size of the complex data type FrequencyDomainType.

◆ setImpulseResponse()

template<typename SampleType >
void visr::rbbl::CoreConvolverUniform< SampleType >::setImpulseResponse ( SampleType const *  ir,
std::size_t  filterLength,
std::size_t  filterIdx,
std::size_t  alignment = 0 
)

◆ transformImpulseResponse()

template<typename SampleType >
void visr::rbbl::CoreConvolverUniform< SampleType >::transformImpulseResponse ( SampleType const *  ir,
std::size_t  irLength,
FrequencyDomainType result,
std::size_t  alignment = 0 
) const

Compute the frequency-domain representation of an impulse response.

Parameters
irThe impulse response sequence. Must hold at least ir samples.
irLengthThe length of the impulse response, it must not exceed the maximum filter lengthset in the constructor.
resultThe result of the operation. Must hold at least dftFilterRepresentationSize() complex values.
alignmentThe minimum alignment of the input parameter ir and the output parameter result, measured in samples.

◆ transformOutput()

template<typename SampleType >
void visr::rbbl::CoreConvolverUniform< SampleType >::transformOutput ( FrequencyDomainType const *  fdBlock,
SampleType tdResult 
)

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