HOA_Decoder.h

Go to the documentation of this file.

/*

HOA_AmbisonicDecoder.h -- Higher Order Ambisonic decoding class
See the copyright notice and acknowledgment of authors in the file COPYRIGHT
Higher Order Ambisonic classes written by Jorge Castellanos, Graham Wakefield, Florian Hollerweger, 2005

Higher Order Ambisonic class for decoding an Ambisonic encoded soundfield (e.g. the output of the HOA_Encoder or
the HOA_Rotator) to a loudspeaker layout specified by HOA_SpeakerLayout. The Ambisonic order at which the decoder
oprates is derived by the following criteria: If no order is specified in the constructor, the order of the Ambisonic
encoded input framestream is used. This order can be degraded either by specifying a lower order in the constructor
(obviously, it cannot be increased). The decoder might further decrease the such given order to match the maximum
order reproducable on the available loudspeaker layout. One out of two different decoding methods can be chosen by
using the flags HOA_PROJECTION, HOA_PSEUDOINVERSE in the constructor. One out of three available decoder flavors can
be applied by using the flags HOA_BASIC, HOA_INPHASE, HOA_MAXRE.

*/

#ifndef HOA_DECODER_H
#define HOA_DECODER_H

#include "CSL_Core.h"
#include "Variable.h"
#include "CPoint.h"

#include "HOA_Encoder.h"
#include "HOA_Utilities.h"
#include "HOA_SpeakerLayout.h"
#include "HOA_AmbisonicFramestream.h"

#define HOA_MAX_ORDER 2 // maximum order that the CSL HOA will handle

namespace csl {

/*

CONVENTIONS USED IN THIS CODE:
------------------------------

***coordinate system***
Left oriented
Azimuth = 0 on the x/z plane and increasing towards the positive y direction
Elevation = 0 on x/y plane and increasing towards the positive z direction
Internal angle representation: spherical radians

***encoding convention***
following the Furse-Malham set (Ambisonic channel weighting for uniform energy distribution)

***abbreviations used in code and comments***
M   ... Ambisonic order (in uniform order system)
M_h ... horizontal Ambisonic order (in hybrid order systems)
M_v ... horizontal Ambisonic order (in hybrid order systems)
N   ... total number of Ambisonic encoded channels (horizontal and vertical)
N_h ... number of horizontal Ambisonic channels (in hybrid order systems)
N_v ... number of vertical Ambisonic channels (in hybrid order systems)
L   ... number of available loudspeakers

***ordering and naming of Ambisonic channels = spherical harmonics***
These conventions follow the ones used in the thesis by Jerome Daniel.
The 3rd order naming convention (which Daniel doesn't provide) follows the one used in the thesis of David Malham.
Watch out for different conventions in other papers!
index           0   1   2   3   4   5   6   7   8   9   10  11  12  13  14  15
M (order)       0   1   1   1   2   2   2   2   2   3   3   3   3   3   3   3
m (=M)          0   1   1   1   2   2   2   2   2   3   3   3   3   3   3   3
n               0   1   1   0   2   2   1   1   0   3   3   2   2   1   1   0
sigma           '1' 1   -1  '1' 1   -1  1   -1  '1' 1   -1  1   -1  1   -1  '1'
name            W   X   Y   Z   U   V   S   T   R   P   Q   N   O   L   M   K
hor/vert/omni   om  h   h   v   h   h   v   v   v   h   h   v   v   v   v   v

*/

typedef enum {
    HOA_PSEUDOINVERSE = 0, HOA_PROJECTION   // flag for the decoding method
} HOA_DecoderMethod;

typedef enum {
    HOA_BASIC = 0, HOA_INPHASE, HOA_MAXRE   // flag for the decoder flavour
} HOA_DecoderFlavour;

class HOA_Decoder : public FrameStream, public Processor, public HOA_AmbisonicFramestream {

private:

    sample *mOutPtr;        // pointer to decoded output buffers (loudspeaker signals)
    sample **mInPtr;        // pointer to Ambisonic encoded input buffers
    
    void asProjection();    // create the decoding matrix D using the projection method
    void asPseudoInverse(); // create the decoding matrix D using the pseudoinverse method
    
    sample** makeTransposedReEncodingMatrix();  // utility method to create the transposed reencoding matrix C'
    
    void makeInPhase();     // method to adjust the decoding matrix D for in-phase flavour
    void makeMaxRE();       // method to adjust the decoding matrix D for Max rE flavour

protected:

    unsigned mNumSpeakers;      // number of loudspeakers in the provided layout
    float mNumChannelsInv;      // inverse of the numbers of loudspeakers (used for normalization)
    int* mIOChannelMap;         // lookup table from index of actually used Ambisonic channel input Ambisonic channel index
    sample **mDecodingMatrix;   // deccoding matrix D
    Buffer mInBuffer;                   // Ambisonic encoded multi-channel audio input
    HOA_SpeakerLayout *mSpkLayout;      // loudspeaker layout provided by "HOA_SpeakerLayout" class
    HOA_DecoderMethod mDecodingMethod;  // decoding method: projection or pseudoinverse
    HOA_DecoderFlavour mDecoderFlavour; // decoder flavour: basic, in-phase or max-rE

public:
    
    // Constructors & destructor:
    
    // default constructor
    HOA_Decoder();
    
    // defaults to standard speaker layout as defined in "HOA_SpeakerLayout" class and to Ambisonic order of encoded input
    HOA_Decoder(FrameStream &input, HOA_DecoderMethod method = HOA_PSEUDOINVERSE, HOA_DecoderFlavour flavour = HOA_BASIC);
    
    // defaults to Ambisonic order of encoded input
    HOA_Decoder(FrameStream &input, HOA_SpeakerLayout &spkLayout, HOA_DecoderMethod method = HOA_PSEUDOINVERSE, HOA_DecoderFlavour flavour = HOA_BASIC);
    
    // initializes with uniform Ambisonic order, defaults to standard speaker layout as defined in "HOA_SpeakerLayout" class
    HOA_Decoder(FrameStream &input, unsigned order, HOA_DecoderMethod method = HOA_PSEUDOINVERSE, HOA_DecoderFlavour flavour = HOA_BASIC);
    
    // initializes with uniform Ambisonic order
    HOA_Decoder(FrameStream &input, unsigned order, HOA_SpeakerLayout &spkLayout, HOA_DecoderMethod method = HOA_PSEUDOINVERSE, HOA_DecoderFlavour flavour = HOA_BASIC);
    
    // initializes with hybrid Ambisonic order
    HOA_Decoder(FrameStream &input, unsigned horder, unsigned vorder, HOA_DecoderMethod method = HOA_PSEUDOINVERSE, HOA_DecoderFlavour flavour = HOA_BASIC);
    
    // initializes with hybrid Ambisonic order
    HOA_Decoder(FrameStream &input, unsigned horder, unsigned vorder, HOA_SpeakerLayout &spkLayout, HOA_DecoderMethod method = HOA_PSEUDOINVERSE, HOA_DecoderFlavour flavour = HOA_BASIC);
    
    // destructor
    ~HOA_Decoder();
    
    
    // initializing method called by constructors
    void initialize(FrameStream &input, HOA_DecoderMethod method, HOA_DecoderFlavour flavour);
    
    // Overriding Framestream::next_buffer(). Does the DSP processing for the Ambisonic Decoder.
    virtual status next_buffer(Buffer &inputBuffer, Buffer &outputBuffer);
    
};

}

#endif

---