1/**
2 * Copyright (c) 2006-2023 LOVE Development Team
3 *
4 * This software is provided 'as-is', without any express or implied
5 * warranty. In no event will the authors be held liable for any damages
6 * arising from the use of this software.
7 *
8 * Permission is granted to anyone to use this software for any purpose,
9 * including commercial applications, and to alter it and redistribute it
10 * freely, subject to the following restrictions:
11 *
12 * 1. The origin of this software must not be misrepresented; you must not
13 * claim that you wrote the original software. If you use this software
14 * in a product, an acknowledgment in the product documentation would be
15 * appreciated but is not required.
16 * 2. Altered source versions must be plainly marked as such, and must not be
17 * misrepresented as being the original software.
18 * 3. This notice may not be removed or altered from any source distribution.
19 **/
20
21#ifndef LOVE_AUDIO_AUDIO_H
22#define LOVE_AUDIO_AUDIO_H
23
24// STL
25#include <vector>
26
27// LOVE
28#include "common/Module.h"
29#include "common/StringMap.h"
30#include "Source.h"
31#include "Effect.h"
32#include "RecordingDevice.h"
33
34namespace love
35{
36
37namespace sound
38{
39
40class Decoder;
41class SoundData;
42
43} // sound
44
45namespace audio
46{
47
48/*
49 * In some platforms (notably Android), recording from mic
50 * requires user permission. This function sets whetever to
51 * request the permission later or not.
52 */
53void setRequestRecordingPermission(bool rec);
54
55/*
56 * Gets whetever recording permission will be requested.
57 */
58bool getRequestRecordingPermission();
59
60/*
61 * Gets whetever recording permission is granted.
62 */
63bool hasRecordingPermission();
64
65/*
66 * Request recording permission. This is blocking function.
67 */
68void requestRecordingPermission();
69
70/*
71 * In case recording permission is not granted, this
72 * function shows the dialog about the recording permission.
73 */
74void showRecordingPermissionMissingDialog();
75
76/**
77 * The Audio module is responsible for playing back raw sound samples.
78 **/
79class Audio : public Module
80{
81public:
82
83 /**
84 * Attenuation by distance.
85 */
86 enum DistanceModel
87 {
88 DISTANCE_NONE,
89 DISTANCE_INVERSE,
90 DISTANCE_INVERSE_CLAMPED,
91 DISTANCE_LINEAR,
92 DISTANCE_LINEAR_CLAMPED,
93 DISTANCE_EXPONENT,
94 DISTANCE_EXPONENT_CLAMPED,
95 DISTANCE_MAX_ENUM
96 };
97
98 static bool getConstant(const char *in, DistanceModel &out);
99 static bool getConstant(DistanceModel in, const char *&out);
100 static std::vector<std::string> getConstants(DistanceModel);
101
102 virtual ~Audio() {}
103
104 // Implements Module.
105 virtual ModuleType getModuleType() const { return M_AUDIO; }
106
107 virtual Source *newSource(love::sound::Decoder *decoder) = 0;
108 virtual Source *newSource(love::sound::SoundData *soundData) = 0;
109 virtual Source *newSource(int sampleRate, int bitDepth, int channels, int buffers) = 0;
110
111 /**
112 * Gets the current number of simultaneous playing sources.
113 * @return The current number of simultaneous playing sources.
114 **/
115 virtual int getActiveSourceCount() const = 0;
116
117 /**
118 * Gets the maximum supported number of simultaneous playing sources.
119 * @return The maximum supported number of simultaneous playing sources.
120 **/
121 virtual int getMaxSources() const = 0;
122
123 /**
124 * Play the specified Source.
125 * @param source The Source to play.
126 **/
127 virtual bool play(Source *source) = 0;
128
129 /**
130 * Play the specified Sources.
131 * @param sources The Sources to play.
132 **/
133 virtual bool play(const std::vector<Source*> &sources) = 0;
134
135 /**
136 * Stops playback on the specified source.
137 * @param source The source on which to stop the playback.
138 **/
139 virtual void stop(Source *source) = 0;
140
141 /**
142 * Stops playback on the specified sources.
143 * @param sources The sources on which to stop the playback.
144 **/
145 virtual void stop(const std::vector<Source*> &sources) = 0;
146
147 /**
148 * Stops all playing audio.
149 **/
150 virtual void stop() = 0;
151
152 /**
153 * Pauses playback on the specified source.
154 * @param source The source on which to pause the playback.
155 **/
156 virtual void pause(Source *source) = 0;
157
158 /**
159 * Pauses playback on the specified sources.
160 * @param sources The sources on which to pause the playback.
161 **/
162 virtual void pause(const std::vector<Source*> &sources) = 0;
163
164 /**
165 * Pauses all audio.
166 **/
167 virtual std::vector<Source*> pause() = 0;
168
169 /**
170 * Sets the master volume, where 0.0f is min (off) and 1.0f is max.
171 * @param volume The new master volume.
172 **/
173 virtual void setVolume(float volume) = 0;
174
175 /**
176 * Gets the master volume.
177 * @return The current master volume.
178 **/
179 virtual float getVolume() const = 0;
180
181 /**
182 * Gets the position of the listener.
183 * @param v A float array of size 3 containing (x,y,z) in that order.
184 **/
185 virtual void getPosition(float *v) const = 0;
186
187 /**
188 * Sets the position of the listener.
189 * @param v A float array of size 3 containing [x,y,z] in that order.
190 **/
191 virtual void setPosition(float *v) = 0;
192
193 /**
194 * Gets the orientation of the listener.
195 * @param v A float array of size 6 containing [x,y,z] for the forward
196 * vector, followed by [x,y,z] for the up vector.
197 **/
198 virtual void getOrientation(float *v) const = 0;
199
200 /**
201 * Sets the orientation of the listener.
202 * @param v A float array of size 6 containing [x,y,z] for the forward
203 * vector, followed by [x,y,z] for the up vector.
204 **/
205 virtual void setOrientation(float *v) = 0;
206
207 /**
208 * Gets the velocity of the listener.
209 * @param v A float array of size 3 containing [x,y,z] in that order.
210 **/
211 virtual void getVelocity(float *v) const = 0;
212
213 /**
214 * Sets the velocity of the listener.
215 * @param v A float array of size 3 containing [x,y,z] in that order.
216 **/
217 virtual void setVelocity(float *v) = 0;
218
219 virtual void setDopplerScale(float scale) = 0;
220 virtual float getDopplerScale() const = 0;
221 //virtual void setMeter(float scale) = 0;
222 //virtual float getMeter() const = 0;
223 /**
224 * @return Reference to a vector of pointers to recording devices. May be empty.
225 **/
226 virtual const std::vector<RecordingDevice*> &getRecordingDevices() = 0;
227
228 /**
229 * Gets the distance model used for attenuation.
230 * @return Distance model.
231 */
232 virtual DistanceModel getDistanceModel() const = 0;
233
234 /**
235 * Sets the distance model used for attenuation.
236 * @param distanceModel Distance model.
237 */
238 virtual void setDistanceModel(DistanceModel distanceModel) = 0;
239
240 /**
241 * Sets scene EFX effect.
242 * @param name Effect name to use.
243 * @param fxparams Effect description table.
244 * @return true if successful, false otherwise.
245 */
246 virtual bool setEffect(const char *name, std::map<Effect::Parameter, float> &params) = 0;
247
248 /**
249 * Removes scene EFX effect.
250 * @param name Effect name to clear.
251 * @return true if successful, false otherwise.
252 */
253 virtual bool unsetEffect(const char *name) = 0;
254
255 /**
256 * Gets scene EFX effect.
257 * @param name Effect name to get data from.
258 * @param fxparams Effect description table.
259 * @return true if effect was present, false otherwise.
260 */
261 virtual bool getEffect(const char *name, std::map<Effect::Parameter, float> &params) = 0;
262
263 /**
264 * Gets list of EFX effect names.
265 * @param list List of EFX names to fill.
266 * @return true if effect was present, false otherwise.
267 */
268 virtual bool getActiveEffects(std::vector<std::string> &list) const = 0;
269
270 /**
271 * Gets maximum number of scene EFX effects.
272 * @return number of effects.
273 */
274 virtual int getMaxSceneEffects() const = 0;
275
276 /**
277 * Gets maximum number of source EFX effects.
278 * @return number of effects.
279 */
280 virtual int getMaxSourceEffects() const = 0;
281
282 /**
283 * Gets EFX (or analog) availability.
284 * @return true if supported.
285 */
286 virtual bool isEFXsupported() const = 0;
287
288 /**
289 * Sets whether audio from other apps mixes with love.audio or is muted,
290 * on supported platforms.
291 **/
292 static bool setMixWithSystem(bool mix);
293
294 /**
295 * Pause/resume audio context
296 */
297 virtual void pauseContext() = 0;
298 virtual void resumeContext() = 0;
299
300private:
301
302 static StringMap<DistanceModel, DISTANCE_MAX_ENUM>::Entry distanceModelEntries[];
303 static StringMap<DistanceModel, DISTANCE_MAX_ENUM> distanceModels;
304}; // Audio
305
306} // audio
307} // love
308
309#endif // LOVE_AUDIO_AUDIO_H
310