CSL 5.2

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

SpeakerLayout.h
Go to the documentation of this file.
1 //
2 // SpeakerLayout.h -- Class for loading and parsing loudspeaker position information used
3 // by the Spatializer and Auralizer classes.
4 // See the copyright notice and acknowledgment of authors in the file COPYRIGHT
5 // Created by Jorge Castellanos on 6/16/06. Hacked 8/09 by STP.
6 //
7
8 #ifndef SPEAKERLAYOUT_H
9 #define SPEAKERLAYOUT_H
10
11 #include "CSL_Core.h"
12 #include "CPoint.h"
13
14 namespace csl {
15
16 class Speaker; // Forward declaration. See below.
17
18 /**
19 A speaker layout holds a set of loudspeakers.
20 Each speaker has a position (in a space, where measurements are assumed to be from the center point of the space (also the center of the coordinate system).
21 To simplify usage, a default layout will be created when instantiating any object that uses the speaker layout.
22 If the user does not specify a layout then the default layout is used.
23 Any layout can be set to become default (by calling setDefaultSpeakerLayout()) so new objects that require a SpeakerLayout
24 make use of this prefered layout without the need of passing it explicitly per instance.
25 Using multiple layouts is still possible by passing the desired layout to the object that will use it.
26 In that case, this object will go with this layout instead of the default.
27
28 Conventions used in this code:
29 Coordinate system:
30 - Left oriented
31 - Internal angle representation: spherical radians
32 - Azimuth = 0 on the x/z plane and increasing towards the positive y direction
33 - Elevation = 0 on x/y plane and increasing towards the positive z direction
34
35 the layout is a passive object, meaning that it doesn't deal with processing any audio data. It only provides speaker positions.
36 An "ActiveSpeakerLayout" is active and can be used as a UnitGenerator that compensates for speaker positions, etc.
37
38 */
39 class SpeakerLayout : public Model {
40 public:
41 // Constructors & destructor:
42 SpeakerLayout(const char *filePath = NULL); ///< Creates an empty speaker layout. Optionally reads loudspeaker layout from file.
43 virtual ~SpeakerLayout(); ///< destructor
44
45 /// Reads the speaker listing file according to the specification
46 void readSpeakerFile(const char *filePath);
47
48 /// Returns a pointer to the default layout. If no default exists, it creates one.
49 static SpeakerLayout *defaultSpeakerLayout();
50 /// Use it to set a layout as default. Clients (e.g. a Panner) can then make use of this layout.
51 static void setDefaultSpeakerLayout(SpeakerLayout *defaultLayout);
52
53 /// Add a speaker specifying its position in degrees from the center of the listening space.
54 void addSpeaker(float azimuth, float elevation = 0.0, float radius = 1.0);
55 /// Add a WFS speaker
56 void addSpeaker(float x, float y, float z, float xNorm, float yNorm, float zNorm, float gain);
57
58 unsigned numSpeakers() const { return mSpeakers.size(); }; ///< Returns the number of loudspeakers in the layout
59
60 /// Sets speaker distances to a fixed distance from the center of the listening space.
61 /// @param radius is optional. If not set, it finds the best radius by analyzing the layout.
62 void normalizeSpeakerDistances(float radius = 0);
63
64 /// Returns the speaker at the specified index.
65 Speaker *speakerAtIndex(unsigned speakerIndex) const { return mSpeakers[speakerIndex]; };
66
67 bool isPeriphonic() { return (mDimensions == 3); }; ///< If any of the speakers in the layout has an elevation other than 0, it returns true.
68 void dump();
69
70 protected:
71 vector<Speaker *> mSpeakers; ///< Vector of pointers to the loudspeakers
72
73
74 private:
75 unsigned mDimensions;
76 // void cartesianToSphericalRadians(); // convert speaker layout given in cartesian coordinates to spherical radians
77 static SpeakerLayout *sDefaultSpeakerLayout;
78 float *mSpeakerDistanceDeltas; ///< Holds the diference of the optimal speaker distance and the real one. Only used if distances are normalized.
79
80 public:
81 SpeakerLayout &operator=(const SpeakerLayout &layout); ///< Overloaded "=" operator allows copying the layout.
82 };
83
84 /// Standard "Stereo Speaker Layout", where two speakers are positioned 30¼ left, 30¼ right and no elevation (0¼).
85
86 class StereoSpeakerLayout : public SpeakerLayout {
87 public:
88 StereoSpeakerLayout();
89 };
90
91 /// "Headphone Layout", where two phones are positioned 90¼ left, 90¼ right and no elevation (0¼).
92
93 class HeadphoneSpeakerLayout : public SpeakerLayout {
94 public:
95 HeadphoneSpeakerLayout();
96 };
97
98
99 /// Represents a speaker as a position relative to the center of a space.
100 class Speaker {
101 public:
102 /// Speaker constructor.
103 /// The speaker class should only be used by the speaker layout. Clients should modify speakers using the Speaker layout
104 /// and not deal with speakers directly. The speaker positions have to be specified in (spherical) radians.
105 Speaker(float azimuth, float elevation, float radius = 1.0);
106
107 // constructor with normal point. x,y,z are position, xNorm,yNorm,zNorm are a point to which the speaker is facing. converted to a normalized vector by Speaker class.
108 Speaker(float x, float y, float z, float xNorm, float yNorm, float zNorm, float gain = 1.0);
109
110 ~Speaker() { };
111
112 CPoint position() { return mPosition; }; // Return the position of the speaker.
113 float azimuth() { return mPosition.theta(); };
114 float elevation() { return mPosition.ele(); };
115 float radius() { return mPosition.r(); };
116 void setRadius(float radius); ///< Specify the distance from the center of the coordinate space to the speaker.
117
118 CPoint normal() { return mNormal; }; // Return the normal of the speaker.
119 float speakerGain() { return mGain;};
120
121 void dump(); ///< Print speaker information.
122
123 protected:
124 CPoint mPosition;
125 CPoint mNormal; // normal vector for speaker
126 float mGain; // a speaker dependant gain, defaults to 1.
127 };
128
129 }
130
131 #endif