Windows: fixing user preference window opening full screen
[blender.git] / intern / SoundSystem / SND_C-api.h
1 /**
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
19  *
20  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
21  * All rights reserved.
22  *
23  * The Original Code is: all of this file.
24  *
25  * Contributor(s): none yet.
26  *
27  * ***** END GPL LICENSE BLOCK *****
28  */
29 #ifndef SND_BLENDER_H
30 #define SND_BLENDER_H
31
32 #ifdef __cplusplus
33 extern "C" { 
34 #endif
35
36 #include "SoundDefines.h"
37
38 #define SND_DECLARE_HANDLE(name) typedef struct name##__ { int unused; } *name
39
40 SND_DECLARE_HANDLE(SND_AudioDeviceInterfaceHandle);
41 SND_DECLARE_HANDLE(SND_SceneHandle);
42 SND_DECLARE_HANDLE(SND_ObjectHandle);
43 SND_DECLARE_HANDLE(SND_ListenerHandle);
44
45 /**
46  * set the specified type 
47  */
48 extern void SND_SetDeviceType(int device_type);
49
50 /**
51  * get an audiodevice
52  */
53 extern SND_AudioDeviceInterfaceHandle SND_GetAudioDevice(void);
54
55 /**
56  * and let go of it
57  */
58 extern void SND_ReleaseDevice(void);
59
60 /**
61  * check if playback is desired
62  */
63 extern int SND_IsPlaybackWanted(SND_SceneHandle scene);
64
65 /**
66  *      add memlocation to cache
67  */
68 extern int SND_AddSample(SND_SceneHandle scene,
69                                                  const char* filename,
70                                                  void* memlocation,
71                                                  int size);
72
73 /**
74  *      remove all samples
75  */
76 extern void     SND_RemoveAllSamples(SND_SceneHandle scene);
77
78 /**
79  *  forces the object to check its buffer, and fix it if it's wrong
80  */
81 extern int SND_CheckBuffer(SND_SceneHandle scene, SND_ObjectHandle object);
82
83 /**
84   * Creates a scene, initializes it and returns a handle to that scene.
85   *
86   *     @param audiodevice: handle to the audiodevice.
87   */
88 extern SND_SceneHandle SND_CreateScene(SND_AudioDeviceInterfaceHandle audiodevice);
89
90 /**
91   * Stops all sounds, suspends the scene (so all resources will be freed) and deletes the scene.
92   *
93   *     @param scene: handle to the soundscene.
94   */
95 extern void     SND_DeleteScene(SND_SceneHandle scene); 
96
97 /**
98   * Adds a soundobject to the scene, gets the buffer the sample is loaded into.
99   *
100   *     @param scene: handle to the soundscene.
101   * @param object: handle to soundobject.
102   */
103 extern void     SND_AddSound(SND_SceneHandle scene, SND_ObjectHandle object);
104
105 /**
106   * Removes a soundobject from the scene.
107   *
108   *     @param scene: handle to the soundscene.
109   * @param object: handle to soundobject.
110   */
111 extern void     SND_RemoveSound(SND_SceneHandle scene, SND_ObjectHandle object);
112
113 /**
114   * Removes all soundobjects from the scene.
115   *
116   *     @param scene: handle to the soundscene.
117   */
118 extern void     SND_RemoveAllSounds(SND_SceneHandle scene);
119
120 /**
121   * Stopss all soundobjects in the scene.
122   *
123   *     @param scene: handle to the soundscene.
124   */
125 extern void SND_StopAllSounds(SND_SceneHandle scene);
126
127 /**
128   * Updates the listener, checks the status of all soundobjects, builds a list of all active
129   * objects, updates the active objects.
130   *
131   *     @param audiodevice: handle to the audiodevice.
132   *     @param scene: handle to the soundscene.
133   */
134 extern void     SND_Proceed(SND_AudioDeviceInterfaceHandle audiodevice, SND_SceneHandle scene);
135
136 /**
137   * Returns a handle to the listener.
138   *
139   *     @param scene: handle to the soundscene.
140   */
141 extern SND_ListenerHandle SND_GetListener(SND_SceneHandle scene);
142
143 /**
144   * Sets the gain of the listener.
145   *
146   *     @param scene: handle to the soundscene.
147   * @param gain: factor the gain gets multiplied with.
148   */
149 extern void SND_SetListenerGain(SND_SceneHandle scene, double gain);
150
151 /**
152   * Sets a scaling to exaggerate or deemphasize the Doppler (pitch) shift resulting from the
153   * calculation.
154   * @attention $f' = dopplerfactor * f * frac{dopplervelocity - listener_velocity}{dopplervelocity + object_velocity}$
155   *     @attention f:  frequency in sample (soundobject)
156   * @attention f': effective Doppler shifted frequency
157   *
158   *     @param object: handle to soundobject.
159   * @param dopplerfactor: the dopplerfactor.
160   */
161 extern void     SND_SetDopplerFactor(SND_SceneHandle scene, double dopplerfactor);
162
163 /**
164   * Sets the value of the propagation speed relative to which the source velocities are interpreted.
165   * @attention $f' = dopplerfactor * f * frac{dopplervelocity - listener_velocity}{dopplervelocity + object_velocity}$
166   *     @attention f:  frequency in sample (soundobject)
167   * @attention f': effective Doppler shifted frequency
168   *
169   *     @param object: handle to soundobject.
170   * @param dopplervelocity: the dopplervelocity.
171   */
172 extern void     SND_SetDopplerVelocity(SND_SceneHandle scene, double dopplervelocity);
173
174 /**
175   * Creates a new soundobject and returns a handle to it.
176   */
177 extern SND_ObjectHandle SND_CreateSound(void);
178
179 /**
180   * Deletes a soundobject.
181   *
182   *     @param object: handle to soundobject.
183   */
184 extern void     SND_DeleteSound(SND_ObjectHandle object);
185
186 /**
187   * Sets a soundobject to SND_MUST_PLAY, so with the next proceed it will be updated and played.
188   *
189   *     @param object: handle to soundobject.
190   */
191 extern void     SND_StartSound(SND_SceneHandle scene, SND_ObjectHandle object);
192
193 /**
194   * Sets a soundobject to SND_MUST_STOP, so with the next proceed it will be stopped.
195   *
196   *     @param object: handle to soundobject.
197   */
198 extern void     SND_StopSound(SND_SceneHandle scene, SND_ObjectHandle object);
199
200 /**
201   * Sets a soundobject to SND_MUST_PAUSE, so with the next proceed it will be paused.
202   *
203   *     @param object: handle to soundobject.
204   */
205 extern void     SND_PauseSound(SND_SceneHandle scene, SND_ObjectHandle object);
206
207 /**
208   * Sets the name of the sample to reference the soundobject to it.
209   *
210   *     @param object: handle to soundobject.
211   * @param samplename: the name of the sample
212   */
213 extern void     SND_SetSampleName(SND_ObjectHandle object, char* samplename);
214
215 /**
216   * Sets the gain of a soundobject.
217   *
218   *     @param object: handle to soundobject.
219   * @param gain: factor the gain gets multiplied with.
220   */
221 extern void     SND_SetGain(SND_ObjectHandle object, double gain);
222
223 /**
224   * Sets the minimum gain of a soundobject.
225   *
226   *     @param object: handle to soundobject.
227   * @param minimumgain: lower threshold for the gain.
228   */
229 extern void     SND_SetMinimumGain(SND_ObjectHandle object, double minimumgain);
230
231 /**
232   * Sets the maximum gain of a soundobject.
233   *
234   *     @param object: handle to soundobject.
235   * @param maximumgain: upper threshold for the gain.
236   */
237 extern void     SND_SetMaximumGain(SND_ObjectHandle object, double maximumgain);
238
239 /**
240   * Sets the rollofffactor. The rollofffactor is a per-Source parameter the application 
241   * can use to increase or decrease     the range of a source by decreasing or increasing the
242   * attenuation, respectively. The default value is 1. The implementation is free to optimize
243   * for a rollofffactor value of 0, which indicates that the application does not wish any
244   * distance attenuation on the respective Source.
245   *
246   *     @param object: handle to soundobject.
247   * @param rollofffactor: the rollofffactor.
248   */
249 extern void     SND_SetRollOffFactor(SND_ObjectHandle object, double rollofffactor);
250
251 /**
252   * Sets the referencedistance at which the listener will experience gain.
253   * @attention G_dB = gain - 20 * log10(1 + rollofffactor * (dist - referencedistance)/referencedistance);
254   *
255   *     @param object: handle to soundobject.
256   * @param distance: the reference distance.
257   */
258 extern void     SND_SetReferenceDistance(SND_ObjectHandle object, double referencedistance);
259
260 /**
261   * Sets the pitch of a soundobject.
262   *
263   *     @param object: handle to soundobject.
264   * @param pitch: pitchingfactor: 2.0 for doubling the frequency, 0.5 for half the frequency.
265   */
266 extern void     SND_SetPitch(SND_ObjectHandle object, double pitch);
267
268 /**
269   * Sets the position a soundobject.
270   *
271   *     @param object: handle to soundobject.
272   * @param position: position[3].
273   */
274 extern void SND_SetPosition(SND_ObjectHandle object, double* position);
275
276 /**
277   * Sets the velocity of a soundobject.
278   *
279   *     @param object: handle to soundobject.
280   * @param velocity: velocity[3].
281   */
282 extern void SND_SetVelocity(SND_ObjectHandle object, double* velocity);
283
284 /**
285   * Sets the orientation of a soundobject.
286   *
287   *     @param object: handle to soundobject.
288   * @param orientation: orientation[9].
289   */
290 extern void SND_SetOrientation(SND_ObjectHandle object, double* orientation);
291
292 /**
293   * Sets the loopmode of a soundobject.
294   *
295   *     @param object: handle to soundobject.
296   * @param loopmode     type of the loop (SND_LOOP_OFF, SND_LOOP_NORMAL, SND_LOOP_BIDIRECTIONAL);
297  */
298 extern void SND_SetLoopMode(SND_ObjectHandle object, int loopmode);
299
300 /**
301   * Sets the looppoints of a soundobject.
302   *
303   *     @param object: handle to soundobject.
304   * @param loopstart    startpoint of the loop
305   * @param loopend              endpoint of the loop
306  */
307 extern void SND_SetLoopPoints(SND_ObjectHandle object, unsigned int loopstart, unsigned int loopend);
308
309 /**
310   * Gets the gain of a soundobject.
311   *
312   *     @param object: handle to soundobject.
313   */
314 extern float SND_GetGain(SND_ObjectHandle object);
315
316 /**
317   * Gets the pitch of a soundobject.
318   *
319   *     @param object: handle to soundobject.
320   */
321 extern float SND_GetPitch(SND_ObjectHandle object);
322
323 /**
324   * Gets the looping of a soundobject.
325   * 0: SND_LOOP_OFF
326   * 1: SND_LOOP_NORMAL
327   * 2: SND_LOOP_BIDIRECTIONAL
328   *
329   *     @param object: handle to soundobject.
330   */
331 extern int SND_GetLoopMode(SND_ObjectHandle object);
332
333 /**
334   * Gets the playstate of a soundobject.
335   *     SND_UNKNOWN = -1
336   *     SND_INITIAL
337   *     SND_MUST_PLAY
338   *     SND_PLAYING
339   *     SND_MUST_STOP
340   *     SND_STOPPED
341   *     SND_MUST_PAUSE
342   *     SND_PAUSED
343   *     SND_MUST_BE_DELETED
344   *
345   *     @param object: handle to soundobject.
346   */
347 extern int SND_GetPlaystate(SND_ObjectHandle object);
348
349 #ifdef __cplusplus
350 }
351 #endif
352
353 #endif
354