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