tmp
[blender.git] / extern / audaspace / include / devices / I3DDevice.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 I3DDevice.h
21  * @ingroup devices
22  * Defines the I3DDevice interface as well as the different distance models.
23  */
24
25 #include "util/Math3D.h"
26
27 AUD_NAMESPACE_BEGIN
28
29 /**
30  * Possible distance models for the 3D device.
31  *
32  * The distance models supported are the same as documented in the [OpenAL Specification](http://openal.org/).
33  */
34 enum DistanceModel
35 {
36         DISTANCE_MODEL_INVALID = 0,
37         DISTANCE_MODEL_INVERSE,
38         DISTANCE_MODEL_INVERSE_CLAMPED,
39         DISTANCE_MODEL_LINEAR,
40         DISTANCE_MODEL_LINEAR_CLAMPED,
41         DISTANCE_MODEL_EXPONENT,
42         DISTANCE_MODEL_EXPONENT_CLAMPED
43 };
44
45 /**
46  * @interface I3DDevice
47  * The I3DDevice interface represents an output device for 3D sound.
48  *
49  * The interface has been modelled after the OpenAL 1.1 API,
50  * see the [OpenAL Specification](http://openal.org/) for lots of details.
51  */
52 class AUD_API I3DDevice
53 {
54 public:
55         /**
56          * Retrieves the listener location.
57          * \return The listener location.
58          */
59         virtual Vector3 getListenerLocation() const=0;
60
61         /**
62          * Sets the listener location.
63          * \param location The new location.
64          * \note The location is not updated with the velocity and
65          *       remains constant until the next call of this method.
66          */
67         virtual void setListenerLocation(const Vector3& location)=0;
68
69         /**
70          * Retrieves the listener velocity.
71          * \return The listener velocity.
72          */
73         virtual Vector3 getListenerVelocity() const=0;
74
75         /**
76          * Sets the listener velocity.
77          * \param velocity The new velocity.
78          * \note This velocity does not change the position of the listener
79          *       over time, it is simply used for the calculation of the doppler effect.
80          */
81         virtual void setListenerVelocity(const Vector3& velocity)=0;
82
83         /**
84          * Retrieves the listener orientation.
85          * \return The listener orientation as quaternion.
86          */
87         virtual Quaternion getListenerOrientation() const=0;
88
89         /**
90          * Sets the listener orientation.
91          * \param orientation The new orientation as quaternion.
92          * \note The coordinate system used is right handed and the listener
93          * by default is oriented looking in the negative z direction with the
94          * positive y axis as up direction.
95          */
96         virtual void setListenerOrientation(const Quaternion& orientation)=0;
97
98
99         /**
100          * Retrieves the speed of sound.
101          * This value is needed for doppler effect calculation.
102          * \return The speed of sound.
103          */
104         virtual float getSpeedOfSound() const=0;
105
106         /**
107          * Sets the speed of sound.
108          * This value is needed for doppler effect calculation.
109          * \param speed The new speed of sound.
110          */
111         virtual void setSpeedOfSound(float speed)=0;
112
113         /**
114          * Retrieves the doppler factor.
115          * This value is a scaling factor for the velocity vectors of sources and
116          * listener which is used while calculating the doppler effect.
117          * \return The doppler factor.
118          */
119         virtual float getDopplerFactor() const=0;
120
121         /**
122          * Sets the doppler factor.
123          * This value is a scaling factor for the velocity vectors of sources and
124          * listener which is used while calculating the doppler effect.
125          * \param factor The new doppler factor.
126          */
127         virtual void setDopplerFactor(float factor)=0;
128
129         /**
130          * Retrieves the distance model.
131          * \return The distance model.
132          */
133         virtual DistanceModel getDistanceModel() const=0;
134
135         /**
136          * Sets the distance model.
137          * \param model distance model.
138          */
139         virtual void setDistanceModel(DistanceModel model)=0;
140 };
141
142 AUD_NAMESPACE_END