HOA_Rotator.h

Go to the documentation of this file.

/*

HOA_Rotator.h -- Higher Order Ambisonic rotator 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 rotating an Ambisonic encoded sound field (e.g. the output of the HOA_Encoder)
around any combination of x, y and z axes. Rotation is applied by using the method "setNthInput" with the flags
HOA_TILT, HOA_TUMBLE, HOA_ROTATE as desired. The order of the incoming Ambisonic framestream can be degraded to
match the maximum order of the available decoding system (number of available speakers). It is possible to specify
either one uniform Ambisonic order or to define the horizontal and vertical order separately (hybrid order rotating).
If no order(s) is/are specified, the order(s) of the Ambisonic encoded input framestream will be used.


*/

#ifndef HOA_ROTATOR_H
#define HOA_ROTATOR_H

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

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_TILT = 0, HOA_TUMBLE, HOA_ROTATE    // to be used with the "setNthInput" method to add control sources
} Axes;                                     // tilt -> x axis, tumble -> y axis, rotate -> z axis


class HOA_Rotator : public FrameStream, public Processor, public HOA_AmbisonicFramestream {
private:

    sample mRotate, mTumble, mTilt;                 // the current amount of rotation in each axis (in radians)
    sample *mSinAngle, *mCosAngle;                  // Used to hold sines/cosines of tilt, tumble, rotate angles during audio processing
    sample **mOutPtr, **mInPtr;                     // pointers to Ambisonic encoded input and Ambisonic encoded & rotated output buffers
    sample mTemp1, mTemp2, mTemp3, mTemp4, mTemp5;  // temp variables used in audio processing (to avoid creating temporaries during DSP)
    int mNumFrames;                                 // current block size
    
    void initialize(FrameStream &input);    
    
    // functions for tilt, tumble & rotate at each order
    void tiltFirstOrder();
    void tiltSecondOrder();
    void tiltThirdOrder();
    
    void tumbleFirstOrder();
    void tumbleSecondOrder();
    void tumbleThirdOrder();
    
    // methods for rotation at each order
    // separated by horizontal & vertical for hybrid order systems (which can be rotated, but not tilted or tumbled)
    void rotateZerothOrder();
    void rotateFirstOrderHorizontal();  
    void rotateSecondOrderHorizontal();
    void rotateThirdOrderHorizontal();
    void rotateFirstOrderVertical();    
    void rotateSecondOrderVertical();
    void rotateThirdOrderVertical();

                
protected:

    unsigned mNumChannels;          // the number of Ambisonic channels.
    unsigned mNumControlChannels;   // how many control inputs to use (3 for uniform, 1 for hybrid order)
    unsigned *mChannelIndex;        // index to the output buffer in the encoding functions.
    unsigned *mInputChannelIndex;   // index to the input buffer in the encoding functions (in case input order != output order)
    bool rotBool, tumBool, tilBool; // flags to note whether rotation in each axis is being used
    Buffer *mInBuffer;              // Ambisonic encoded multi-channel audio input
    Buffer *mCtrlBuffer;            // the buffers of input control data (tilt, tumble, rotation angles)
    FrameStream **mCtrlPtr;         // input controllers for tilt, tumble and rotation.
     
public:
    
    // Constructors & destructor:
    
    // default constructor, initializes to 1st order with no rotation 
    HOA_Rotator();
    
    // initializes with no rotation
    HOA_Rotator(FrameStream &input);
    
    // initializes with uniform Ambisonic order and no rotation
    HOA_Rotator(FrameStream &input, unsigned order);
    
    // initializes with hybrid Ambisonic  order and no rotation
    HOA_Rotator(FrameStream &input, unsigned vorder, unsigned horder);
    ~HOA_Rotator(); // destructor
    
    
    // set control input sources according axis flag
    void setNthInput(float input, Axes axis);
    void setTilt(float input);
    void setTumble(float input);
    void setRotate(float input);
    
    // Overriding Framestream::next_buffer(). Does the DSP processing for the Ambisonic Rotator.
    virtual status next_buffer(Buffer &inputBuffer, Buffer &outputBuffer);
    
};

}

#endif

---