svn merge -r 30913:30953 https://svn.blender.org/svnroot/bf-blender/trunk/blender
[blender.git] / intern / audaspace / intern / AUD_I3DDevice.h
1 /*
2  * $Id$
3  *
4  * ***** BEGIN LGPL LICENSE BLOCK *****
5  *
6  * Copyright 2009 Jörg Hermann Müller
7  *
8  * This file is part of AudaSpace.
9  *
10  * AudaSpace is free software: you can redistribute it and/or modify
11  * it under the terms of the GNU Lesser General Public License as published by
12  * the Free Software Foundation, either version 3 of the License, or
13  * (at your option) any later version.
14  *
15  * AudaSpace is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU Lesser General Public License for more details.
19  *
20  * You should have received a copy of the GNU Lesser General Public License
21  * along with AudaSpace.  If not, see <http://www.gnu.org/licenses/>.
22  *
23  * ***** END LGPL LICENSE BLOCK *****
24  */
25
26 #ifndef AUD_I3DDEVICE
27 #define AUD_I3DDEVICE
28
29 #include "AUD_Space.h"
30 #include "AUD_3DMath.h"
31
32 struct AUD_Handle;
33
34 /**
35  * This class represents an output device for 3D sound.
36  */
37 class AUD_I3DDevice
38 {
39 public:
40         /**
41          * Retrieves the listener location.
42          * \return The listener location.
43          */
44         virtual AUD_Vector3 getListenerLocation() const=0;
45
46         /**
47          * Sets the listener location.
48          * \param location The new location.
49          */
50         virtual void setListenerLocation(const AUD_Vector3& location)=0;
51
52         /**
53          * Retrieves the listener velocity.
54          * \return The listener velocity.
55          */
56         virtual AUD_Vector3 getListenerVelocity() const=0;
57
58         /**
59          * Sets the listener velocity.
60          * \param velocity The new velocity.
61          */
62         virtual void setListenerVelocity(const AUD_Vector3& velocity)=0;
63
64         /**
65          * Retrieves the listener orientation.
66          * \return The listener orientation as quaternion.
67          */
68         virtual AUD_Quaternion getListenerOrientation() const=0;
69
70         /**
71          * Sets the listener orientation.
72          * \param orientation The new orientation as quaternion.
73          */
74         virtual void setListenerOrientation(const AUD_Quaternion& orientation)=0;
75
76
77         /**
78          * Retrieves the speed of sound.
79          * This value is needed for doppler effect calculation.
80          * \return The speed of sound.
81          */
82         virtual float getSpeedOfSound() const=0;
83
84         /**
85          * Sets the speed of sound.
86          * This value is needed for doppler effect calculation.
87          * \param speed The new speed of sound.
88          */
89         virtual void setSpeedOfSound(float speed)=0;
90
91         /**
92          * Retrieves the doppler factor.
93          * This value is a scaling factor for the velocity vectors of sources and
94          * listener which is used while calculating the doppler effect.
95          * \return The doppler factor.
96          */
97         virtual float getDopplerFactor() const=0;
98
99         /**
100          * Sets the doppler factor.
101          * This value is a scaling factor for the velocity vectors of sources and
102          * listener which is used while calculating the doppler effect.
103          * \param factor The new doppler factor.
104          */
105         virtual void setDopplerFactor(float factor)=0;
106
107         /**
108          * Retrieves the distance model.
109          * \return The distance model.
110          */
111         virtual AUD_DistanceModel getDistanceModel() const=0;
112
113         /**
114          * Sets the distance model.
115          * \param model distance model.
116          */
117         virtual void setDistanceModel(AUD_DistanceModel model)=0;
118
119
120
121         /**
122          * Retrieves the location of a source.
123          * \param handle The handle of the source.
124          * \return The location.
125          */
126         virtual AUD_Vector3 getSourceLocation(AUD_Handle* handle)=0;
127
128         /**
129          * Sets the location of a source.
130          * \param handle The handle of the source.
131          * \param location The new location.
132          * \return Whether the action succeeded.
133          */
134         virtual bool setSourceLocation(AUD_Handle* handle, const AUD_Vector3& location)=0;
135
136         /**
137          * Retrieves the velocity of a source.
138          * \param handle The handle of the source.
139          * \return The velocity.
140          */
141         virtual AUD_Vector3 getSourceVelocity(AUD_Handle* handle)=0;
142
143         /**
144          * Sets the velocity of a source.
145          * \param handle The handle of the source.
146          * \param velocity The new velocity.
147          * \return Whether the action succeeded.
148          */
149         virtual bool setSourceVelocity(AUD_Handle* handle, const AUD_Vector3& velocity)=0;
150
151         /**
152          * Retrieves the orientation of a source.
153          * \param handle The handle of the source.
154          * \return The orientation as quaternion.
155          */
156         virtual AUD_Quaternion getSourceOrientation(AUD_Handle* handle)=0;
157
158         /**
159          * Sets the orientation of a source.
160          * \param handle The handle of the source.
161          * \param orientation The new orientation as quaternion.
162          * \return Whether the action succeeded.
163          */
164         virtual bool setSourceOrientation(AUD_Handle* handle, const AUD_Quaternion& orientation)=0;
165
166
167         /**
168          * Checks whether the source location, velocity and orientation are relative
169          * to the listener.
170          * \param handle The handle of the source.
171          * \return Whether the source is relative.
172          */
173         virtual bool isRelative(AUD_Handle* handle)=0;
174
175         /**
176          * Sets whether the source location, velocity and orientation are relative
177          * to the listener.
178          * \param handle The handle of the source.
179          * \param relative Whether the source is relative.
180          * \return Whether the action succeeded.
181          */
182         virtual bool setRelative(AUD_Handle* handle, bool relative)=0;
183
184         /**
185          * Retrieves the maximum volume of a source.
186          * \param handle The handle of the source.
187          * \return The maximum volume.
188          */
189         virtual float getVolumeMaximum(AUD_Handle* handle)=0;
190
191         /**
192          * Sets the maximum volume of a source.
193          * \param handle The handle of the source.
194          * \param volume The new maximum volume.
195          * \return Whether the action succeeded.
196          */
197         virtual bool setVolumeMaximum(AUD_Handle* handle, float volume)=0;
198
199         /**
200          * Retrieves the minimum volume of a source.
201          * \param handle The handle of the source.
202          * \return The minimum volume.
203          */
204         virtual float getVolumeMinimum(AUD_Handle* handle)=0;
205
206         /**
207          * Sets the minimum volume of a source.
208          * \param handle The handle of the source.
209          * \param volume The new minimum volume.
210          * \return Whether the action succeeded.
211          */
212         virtual bool setVolumeMinimum(AUD_Handle* handle, float volume)=0;
213
214         /**
215          * Retrieves the maximum distance of a source.
216          * If a source is further away from the reader than this distance, the
217          * volume will automatically be set to 0.
218          * \param handle The handle of the source.
219          * \return The maximum distance.
220          */
221         virtual float getDistanceMaximum(AUD_Handle* handle)=0;
222
223         /**
224          * Sets the maximum distance of a source.
225          * If a source is further away from the reader than this distance, the
226          * volume will automatically be set to 0.
227          * \param handle The handle of the source.
228          * \param distance The new maximum distance.
229          * \return Whether the action succeeded.
230          */
231         virtual bool setDistanceMaximum(AUD_Handle* handle, float distance)=0;
232
233         /**
234          * Retrieves the reference distance of a source.
235          * \param handle The handle of the source.
236          * \return The reference distance.
237          */
238         virtual float getDistanceReference(AUD_Handle* handle)=0;
239
240         /**
241          * Sets the reference distance of a source.
242          * \param handle The handle of the source.
243          * \param distance The new reference distance.
244          * \return Whether the action succeeded.
245          */
246         virtual bool setDistanceReference(AUD_Handle* handle, float distance)=0;
247
248         /**
249          * Retrieves the attenuation of a source.
250          * \param handle The handle of the source.
251          * \return The attenuation.
252          */
253         virtual float getAttenuation(AUD_Handle* handle)=0;
254
255         /**
256          * Sets the attenuation of a source.
257          * This value is used for distance calculation.
258          * \param handle The handle of the source.
259          * \param factor The new attenuation.
260          * \return Whether the action succeeded.
261          */
262         virtual bool setAttenuation(AUD_Handle* handle, float factor)=0;
263
264         /**
265          * Retrieves the outer angle of the cone of a source.
266          * \param handle The handle of the source.
267          * \return The outer angle of the cone.
268          */
269         virtual float getConeAngleOuter(AUD_Handle* handle)=0;
270
271         /**
272          * Sets the outer angle of the cone of a source.
273          * \param handle The handle of the source.
274          * \param angle The new outer angle of the cone.
275          * \return Whether the action succeeded.
276          */
277         virtual bool setConeAngleOuter(AUD_Handle* handle, float angle)=0;
278
279         /**
280          * Retrieves the inner angle of the cone of a source.
281          * \param handle The handle of the source.
282          * \return The inner angle of the cone.
283          */
284         virtual float getConeAngleInner(AUD_Handle* handle)=0;
285
286         /**
287          * Sets the inner angle of the cone of a source.
288          * \param handle The handle of the source.
289          * \param angle The new inner angle of the cone.
290          * \return Whether the action succeeded.
291          */
292         virtual bool setConeAngleInner(AUD_Handle* handle, float angle)=0;
293
294         /**
295          * Retrieves the outer volume of the cone of a source.
296          * The volume between inner and outer angle is interpolated between inner
297          * volume and this value.
298          * \param handle The handle of the source.
299          * \return The outer volume of the cone.
300          */
301         virtual float getConeVolumeOuter(AUD_Handle* handle)=0;
302
303         /**
304          * Sets the outer volume of the cone of a source.
305          * The volume between inner and outer angle is interpolated between inner
306          * volume and this value.
307          * \param handle The handle of the source.
308          * \param volume The new outer volume of the cone.
309          * \return Whether the action succeeded.
310          */
311         virtual bool setConeVolumeOuter(AUD_Handle* handle, float volume)=0;
312 };
313
314 #endif //AUD_I3DDEVICE