tmp
[blender.git] / extern / audaspace / include / devices / I3DHandle.h
1 /*******************************************************************************
2  * Copyright 2009-2016 Jörg Müller
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *   http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  ******************************************************************************/
16
17 #pragma once
18
19 /**
20  * @file I3DHandle.h
21  * @ingroup devices
22  * The I3DHandle interface.
23  */
24
25 #include "util/Math3D.h"
26
27 AUD_NAMESPACE_BEGIN
28
29 /**
30  * @interface I3DHandle
31  * The I3DHandle interface represents a playback handle for 3D sources.
32  * If the playback IDevice class also implements the I3DDevice interface
33  * then all playback IHandle instances also implement this interface.
34  *
35  * The interface has been modelled after the OpenAL 1.1 API,
36  * see the [OpenAL Specification](http://openal.org/) for lots of details.
37  */
38 class AUD_API I3DHandle
39 {
40 public:
41         /**
42          * Destroys the handle.
43          */
44         virtual ~I3DHandle() {}
45
46         /**
47          * Retrieves the location of the source.
48          * \return The location.
49          */
50         virtual Vector3 getLocation()=0;
51
52         /**
53          * Sets the location of the source.
54          * \param location The new location.
55          * \return Whether the action succeeded.
56          * \note The location is not updated with the velocity and
57          *       remains constant until the next call of this method.
58          */
59         virtual bool setLocation(const Vector3& location)=0;
60
61         /**
62          * Retrieves the velocity of the source.
63          * \return The velocity.
64          */
65         virtual Vector3 getVelocity()=0;
66
67         /**
68          * Sets the velocity of the source.
69          * \param velocity The new velocity.
70          * \return Whether the action succeeded.
71          * \note This velocity does not change the position of the listener
72          *       over time, it is simply used for the calculation of the doppler effect.
73          */
74         virtual bool setVelocity(const Vector3& velocity)=0;
75
76         /**
77          * Retrieves the orientation of the source.
78          * \return The orientation as quaternion.
79          */
80         virtual Quaternion getOrientation()=0;
81
82         /**
83          * Sets the orientation of the source.
84          * \param orientation The new orientation as quaternion.
85          * \return Whether the action succeeded.
86          * \note The coordinate system used is right handed and the source
87          * by default is oriented looking in the negative z direction with the
88          * positive y axis as up direction.
89          * \note This setting currently only affects sounds with non-default cone settings.
90          */
91         virtual bool setOrientation(const Quaternion& orientation)=0;
92
93
94         /**
95          * Checks whether the source location, velocity and orientation are relative
96          * to the listener.
97          * \return Whether the source is relative.
98          */
99         virtual bool isRelative()=0;
100
101         /**
102          * Sets whether the source location, velocity and orientation are relative
103          * to the listener.
104          * \param relative Whether the source is relative.
105          * \return Whether the action succeeded.
106          * \note The default value is true as this setting is used to play sounds ordinarily without 3D.
107          */
108         virtual bool setRelative(bool relative)=0;
109
110         /**
111          * Retrieves the maximum volume of a source.
112          * \return The maximum volume.
113          */
114         virtual float getVolumeMaximum()=0;
115
116         /**
117          * Sets the maximum volume of a source.
118          * \param volume The new maximum volume.
119          * \return Whether the action succeeded.
120          */
121         virtual bool setVolumeMaximum(float volume)=0;
122
123         /**
124          * Retrieves the minimum volume of a source.
125          * \return The minimum volume.
126          */
127         virtual float getVolumeMinimum()=0;
128
129         /**
130          * Sets the minimum volume of a source.
131          * \param volume The new minimum volume.
132          * \return Whether the action succeeded.
133          */
134         virtual bool setVolumeMinimum(float volume)=0;
135
136         /**
137          * Retrieves the maximum distance of a source.
138          * If a source is further away from the reader than this distance, the
139          * volume will automatically be set to 0.
140          * \return The maximum distance.
141          */
142         virtual float getDistanceMaximum()=0;
143
144         /**
145          * Sets the maximum distance of a source.
146          * If a source is further away from the reader than this distance, the
147          * volume will automatically be set to 0.
148          * \param distance The new maximum distance.
149          * \return Whether the action succeeded.
150          */
151         virtual bool setDistanceMaximum(float distance)=0;
152
153         /**
154          * Retrieves the reference distance of a source.
155          * \return The reference distance.
156          */
157         virtual float getDistanceReference()=0;
158
159         /**
160          * Sets the reference distance of a source.
161          * \param distance The new reference distance.
162          * \return Whether the action succeeded.
163          */
164         virtual bool setDistanceReference(float distance)=0;
165
166         /**
167          * Retrieves the attenuation of a source.
168          * \return The attenuation.
169          */
170         virtual float getAttenuation()=0;
171
172         /**
173          * Sets the attenuation of a source.
174          * This value is used for distance calculation.
175          * \param factor The new attenuation.
176          * \return Whether the action succeeded.
177          */
178         virtual bool setAttenuation(float factor)=0;
179
180         /**
181          * Retrieves the outer opening angle of the cone of a source.
182          * \return The outer angle of the cone.
183          * \note This angle is defined in degrees.
184          */
185         virtual float getConeAngleOuter()=0;
186
187         /**
188          * Sets the outer opening angle of the cone of a source.
189          * \param angle The new outer angle of the cone.
190          * \return Whether the action succeeded.
191          * \note This angle is defined in degrees.
192          */
193         virtual bool setConeAngleOuter(float angle)=0;
194
195         /**
196          * Retrieves the inner opening angle of the cone of a source.
197          * The volume inside this cone is unaltered.
198          * \return The inner angle of the cone.
199          * \note This angle is defined in degrees.
200          */
201         virtual float getConeAngleInner()=0;
202
203         /**
204          * Sets the inner opening angle of the cone of a source.
205          * The volume inside this cone is unaltered.
206          * \param angle The new inner angle of the cone.
207          * \return Whether the action succeeded.
208          * \note This angle is defined in degrees.
209          */
210         virtual bool setConeAngleInner(float angle)=0;
211
212         /**
213          * Retrieves the outer volume of the cone of a source.
214          * The volume between inner and outer angle is interpolated between inner
215          * volume and this value.
216          * \return The outer volume of the cone.
217          * \note The general volume of the handle still applies on top of this.
218          */
219         virtual float getConeVolumeOuter()=0;
220
221         /**
222          * Sets the outer volume of the cone of a source.
223          * The volume between inner and outer angle is interpolated between inner
224          * volume and this value.
225          * \param volume The new outer volume of the cone.
226          * \return Whether the action succeeded.
227          * \note The general volume of the handle still applies on top of this.
228          */
229         virtual bool setConeVolumeOuter(float volume)=0;
230 };
231
232 AUD_NAMESPACE_END