3D Audio GSoC:
[blender.git] / intern / audaspace / intern / AUD_I3DHandle.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_I3DHandle.h
28  *  \ingroup audaspaceintern
29  */
30
31
32 #ifndef AUD_I3DHANDLE
33 #define AUD_I3DHANDLE
34
35 #include "AUD_Space.h"
36 #include "AUD_3DMath.h"
37
38 /**
39  * This class represents a playback handle for 3D sources.
40  */
41 class AUD_I3DHandle
42 {
43 public:
44         /**
45          * Destroys the handle.
46          */
47         virtual ~AUD_I3DHandle() {}
48
49         /**
50          * Retrieves the location of a source.
51          * \return The location.
52          */
53         virtual AUD_Vector3 getSourceLocation()=0;
54
55         /**
56          * Sets the location of a source.
57          * \param location The new location.
58          * \return Whether the action succeeded.
59          */
60         virtual bool setSourceLocation(const AUD_Vector3& location)=0;
61
62         /**
63          * Retrieves the velocity of a source.
64          * \return The velocity.
65          */
66         virtual AUD_Vector3 getSourceVelocity()=0;
67
68         /**
69          * Sets the velocity of a source.
70          * \param velocity The new velocity.
71          * \return Whether the action succeeded.
72          */
73         virtual bool setSourceVelocity(const AUD_Vector3& velocity)=0;
74
75         /**
76          * Retrieves the orientation of a source.
77          * \return The orientation as quaternion.
78          */
79         virtual AUD_Quaternion getSourceOrientation()=0;
80
81         /**
82          * Sets the orientation of a source.
83          * \param orientation The new orientation as quaternion.
84          * \return Whether the action succeeded.
85          */
86         virtual bool setSourceOrientation(const AUD_Quaternion& orientation)=0;
87
88
89         /**
90          * Checks whether the source location, velocity and orientation are relative
91          * to the listener.
92          * \return Whether the source is relative.
93          */
94         virtual bool isRelative()=0;
95
96         /**
97          * Sets whether the source location, velocity and orientation are relative
98          * to the listener.
99          * \param relative Whether the source is relative.
100          * \return Whether the action succeeded.
101          */
102         virtual bool setRelative(bool relative)=0;
103
104         /**
105          * Retrieves the maximum volume of a source.
106          * \return The maximum volume.
107          */
108         virtual float getVolumeMaximum()=0;
109
110         /**
111          * Sets the maximum volume of a source.
112          * \param volume The new maximum volume.
113          * \return Whether the action succeeded.
114          */
115         virtual bool setVolumeMaximum(float volume)=0;
116
117         /**
118          * Retrieves the minimum volume of a source.
119          * \return The minimum volume.
120          */
121         virtual float getVolumeMinimum()=0;
122
123         /**
124          * Sets the minimum volume of a source.
125          * \param volume The new minimum volume.
126          * \return Whether the action succeeded.
127          */
128         virtual bool setVolumeMinimum(float volume)=0;
129
130         /**
131          * Retrieves the maximum distance of a source.
132          * If a source is further away from the reader than this distance, the
133          * volume will automatically be set to 0.
134          * \return The maximum distance.
135          */
136         virtual float getDistanceMaximum()=0;
137
138         /**
139          * Sets the maximum distance of a source.
140          * If a source is further away from the reader than this distance, the
141          * volume will automatically be set to 0.
142          * \param distance The new maximum distance.
143          * \return Whether the action succeeded.
144          */
145         virtual bool setDistanceMaximum(float distance)=0;
146
147         /**
148          * Retrieves the reference distance of a source.
149          * \return The reference distance.
150          */
151         virtual float getDistanceReference()=0;
152
153         /**
154          * Sets the reference distance of a source.
155          * \param distance The new reference distance.
156          * \return Whether the action succeeded.
157          */
158         virtual bool setDistanceReference(float distance)=0;
159
160         /**
161          * Retrieves the attenuation of a source.
162          * \return The attenuation.
163          */
164         virtual float getAttenuation()=0;
165
166         /**
167          * Sets the attenuation of a source.
168          * This value is used for distance calculation.
169          * \param factor The new attenuation.
170          * \return Whether the action succeeded.
171          */
172         virtual bool setAttenuation(float factor)=0;
173
174         /**
175          * Retrieves the outer angle of the cone of a source.
176          * \return The outer angle of the cone.
177          */
178         virtual float getConeAngleOuter()=0;
179
180         /**
181          * Sets the outer angle of the cone of a source.
182          * \param angle The new outer angle of the cone.
183          * \return Whether the action succeeded.
184          */
185         virtual bool setConeAngleOuter(float angle)=0;
186
187         /**
188          * Retrieves the inner angle of the cone of a source.
189          * \return The inner angle of the cone.
190          */
191         virtual float getConeAngleInner()=0;
192
193         /**
194          * Sets the inner angle of the cone of a source.
195          * \param angle The new inner angle of the cone.
196          * \return Whether the action succeeded.
197          */
198         virtual bool setConeAngleInner(float angle)=0;
199
200         /**
201          * Retrieves the outer volume of the cone of a source.
202          * The volume between inner and outer angle is interpolated between inner
203          * volume and this value.
204          * \return The outer volume of the cone.
205          */
206         virtual float getConeVolumeOuter()=0;
207
208         /**
209          * Sets the outer volume of the cone of a source.
210          * The volume between inner and outer angle is interpolated between inner
211          * volume and this value.
212          * \param volume The new outer volume of the cone.
213          * \return Whether the action succeeded.
214          */
215         virtual bool setConeVolumeOuter(float volume)=0;
216 };
217
218 #endif //AUD_I3DHANDLE