diff options
Diffstat (limited to 'intern/SoundSystem/SND_C-api.h')
| -rw-r--r-- | intern/SoundSystem/SND_C-api.h | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/intern/SoundSystem/SND_C-api.h b/intern/SoundSystem/SND_C-api.h new file mode 100644 index 00000000000..9c24438c131 --- /dev/null +++ b/intern/SoundSystem/SND_C-api.h @@ -0,0 +1,356 @@ +/** + * $Id$ + * + * ***** BEGIN GPL/BL DUAL LICENSE BLOCK ***** + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. The Blender + * Foundation also sells licenses for use in proprietary software under + * the Blender License. See http://www.blender.org/BL/ for information + * about this. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software Foundation, + * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * + * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV. + * All rights reserved. + * + * The Original Code is: all of this file. + * + * Contributor(s): none yet. + * + * ***** END GPL/BL DUAL LICENSE BLOCK ***** + */ +#ifndef SND_BLENDER_H +#define SND_BLENDER_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include "SoundDefines.h" + +#define SND_DECLARE_HANDLE(name) typedef struct name##__ { int unused; } *name + +SND_DECLARE_HANDLE(SND_AudioDeviceInterfaceHandle); +SND_DECLARE_HANDLE(SND_SceneHandle); +SND_DECLARE_HANDLE(SND_ObjectHandle); +SND_DECLARE_HANDLE(SND_ListenerHandle); + +/** + * set the specified type + */ +extern void SND_SetDeviceType(int device_type); + +/** + * get an audiodevice + */ +extern SND_AudioDeviceInterfaceHandle SND_GetAudioDevice(void); + +/** + * and let go of it + */ +extern void SND_ReleaseDevice(void); + +/** + * check if playback is desired + */ +extern int SND_IsPlaybackWanted(SND_SceneHandle scene); + +/** + * add memlocation to cache + */ +extern int SND_AddSample(SND_SceneHandle scene, + const char* filename, + void* memlocation, + int size); + +/** + * remove all samples + */ +extern void SND_RemoveAllSamples(SND_SceneHandle scene); + +/** + * forces the object to check its buffer, and fix it if it's wrong + */ +extern int SND_CheckBuffer(SND_SceneHandle scene, SND_ObjectHandle object); + +/** + * Creates a scene, initializes it and returns a handle to that scene. + * + * @param audiodevice: handle to the audiodevice. + */ +extern SND_SceneHandle SND_CreateScene(SND_AudioDeviceInterfaceHandle audiodevice); + +/** + * Stops all sounds, suspends the scene (so all resources will be freed) and deletes the scene. + * + * @param scene: handle to the soundscene. + */ +extern void SND_DeleteScene(SND_SceneHandle scene); + +/** + * Adds a soundobject to the scene, gets the buffer the sample is loaded into. + * + * @param scene: handle to the soundscene. + * @param object: handle to soundobject. + */ +extern void SND_AddSound(SND_SceneHandle scene, SND_ObjectHandle object); + +/** + * Removes a soundobject from the scene. + * + * @param scene: handle to the soundscene. + * @param object: handle to soundobject. + */ +extern void SND_RemoveSound(SND_SceneHandle scene, SND_ObjectHandle object); + +/** + * Removes all soundobjects from the scene. + * + * @param scene: handle to the soundscene. + */ +extern void SND_RemoveAllSounds(SND_SceneHandle scene); + +/** + * Stopss all soundobjects in the scene. + * + * @param scene: handle to the soundscene. + */ +extern void SND_StopAllSounds(SND_SceneHandle scene); + +/** + * Updates the listener, checks the status of all soundobjects, builds a list of all active + * objects, updates the active objects. + * + * @param audiodevice: handle to the audiodevice. + * @param scene: handle to the soundscene. + */ +extern void SND_Proceed(SND_AudioDeviceInterfaceHandle audiodevice, SND_SceneHandle scene); + +/** + * Returns a handle to the listener. + * + * @param scene: handle to the soundscene. + */ +extern SND_ListenerHandle SND_GetListener(SND_SceneHandle scene); + +/** + * Sets the gain of the listener. + * + * @param scene: handle to the soundscene. + * @param gain: factor the gain gets multiplied with. + */ +extern void SND_SetListenerGain(SND_SceneHandle scene, double gain); + +/** + * Sets a scaling to exaggerate or deemphasize the Doppler (pitch) shift resulting from the + * calculation. + * @attention $f' = dopplerfactor * f * frac{dopplervelocity - listener_velocity}{dopplervelocity + object_velocity}$ + * @attention f: frequency in sample (soundobject) + * @attention f': effective Doppler shifted frequency + * + * @param object: handle to soundobject. + * @param dopplerfactor: the dopplerfactor. + */ +extern void SND_SetDopplerFactor(SND_SceneHandle scene, double dopplerfactor); + +/** + * Sets the value of the propagation speed relative to which the source velocities are interpreted. + * @attention $f' = dopplerfactor * f * frac{dopplervelocity - listener_velocity}{dopplervelocity + object_velocity}$ + * @attention f: frequency in sample (soundobject) + * @attention f': effective Doppler shifted frequency + * + * @param object: handle to soundobject. + * @param dopplervelocity: the dopplervelocity. + */ +extern void SND_SetDopplerVelocity(SND_SceneHandle scene, double dopplervelocity); + +/** + * Creates a new soundobject and returns a handle to it. + */ +extern SND_ObjectHandle SND_CreateSound(void); + +/** + * Deletes a soundobject. + * + * @param object: handle to soundobject. + */ +extern void SND_DeleteSound(SND_ObjectHandle object); + +/** + * Sets a soundobject to SND_MUST_PLAY, so with the next proceed it will be updated and played. + * + * @param object: handle to soundobject. + */ +extern void SND_StartSound(SND_SceneHandle scene, SND_ObjectHandle object); + +/** + * Sets a soundobject to SND_MUST_STOP, so with the next proceed it will be stopped. + * + * @param object: handle to soundobject. + */ +extern void SND_StopSound(SND_SceneHandle scene, SND_ObjectHandle object); + +/** + * Sets a soundobject to SND_MUST_PAUSE, so with the next proceed it will be paused. + * + * @param object: handle to soundobject. + */ +extern void SND_PauseSound(SND_SceneHandle scene, SND_ObjectHandle object); + +/** + * Sets the name of the sample to reference the soundobject to it. + * + * @param object: handle to soundobject. + * @param samplename: the name of the sample + */ +extern void SND_SetSampleName(SND_ObjectHandle object, char* samplename); + +/** + * Sets the gain of a soundobject. + * + * @param object: handle to soundobject. + * @param gain: factor the gain gets multiplied with. + */ +extern void SND_SetGain(SND_ObjectHandle object, double gain); + +/** + * Sets the minimum gain of a soundobject. + * + * @param object: handle to soundobject. + * @param minimumgain: lower threshold for the gain. + */ +extern void SND_SetMinimumGain(SND_ObjectHandle object, double minimumgain); + +/** + * Sets the maximum gain of a soundobject. + * + * @param object: handle to soundobject. + * @param maximumgain: upper threshold for the gain. + */ +extern void SND_SetMaximumGain(SND_ObjectHandle object, double maximumgain); + +/** + * Sets the rollofffactor. The rollofffactor is a per-Source parameter the application + * can use to increase or decrease the range of a source by decreasing or increasing the + * attenuation, respectively. The default value is 1. The implementation is free to optimize + * for a rollofffactor value of 0, which indicates that the application does not wish any + * distance attenuation on the respective Source. + * + * @param object: handle to soundobject. + * @param rollofffactor: the rollofffactor. + */ +extern void SND_SetRollOffFactor(SND_ObjectHandle object, double rollofffactor); + +/** + * Sets the referencedistance at which the listener will experience gain. + * @attention G_dB = gain - 20 * log10(1 + rollofffactor * (dist - referencedistance)/referencedistance); + * + * @param object: handle to soundobject. + * @param distance: the reference distance. + */ +extern void SND_SetReferenceDistance(SND_ObjectHandle object, double referencedistance); + +/** + * Sets the pitch of a soundobject. + * + * @param object: handle to soundobject. + * @param pitch: pitchingfactor: 2.0 for doubling the frequency, 0.5 for half the frequency. + */ +extern void SND_SetPitch(SND_ObjectHandle object, double pitch); + +/** + * Sets the position a soundobject. + * + * @param object: handle to soundobject. + * @param position: position[3]. + */ +extern void SND_SetPosition(SND_ObjectHandle object, double* position); + +/** + * Sets the velocity of a soundobject. + * + * @param object: handle to soundobject. + * @param velocity: velocity[3]. + */ +extern void SND_SetVelocity(SND_ObjectHandle object, double* velocity); + +/** + * Sets the orientation of a soundobject. + * + * @param object: handle to soundobject. + * @param orientation: orientation[9]. + */ +extern void SND_SetOrientation(SND_ObjectHandle object, double* orientation); + +/** + * Sets the loopmode of a soundobject. + * + * @param object: handle to soundobject. + * @param loopmode type of the loop (SND_LOOP_OFF, SND_LOOP_NORMAL, SND_LOOP_BIDIRECTIONAL); + */ +extern void SND_SetLoopMode(SND_ObjectHandle object, int loopmode); + +/** + * Sets the looppoints of a soundobject. + * + * @param object: handle to soundobject. + * @param loopstart startpoint of the loop + * @param loopend endpoint of the loop + */ +extern void SND_SetLoopPoints(SND_ObjectHandle object, unsigned int loopstart, unsigned int loopend); + +/** + * Gets the gain of a soundobject. + * + * @param object: handle to soundobject. + */ +extern float SND_GetGain(SND_ObjectHandle object); + +/** + * Gets the pitch of a soundobject. + * + * @param object: handle to soundobject. + */ +extern float SND_GetPitch(SND_ObjectHandle object); + +/** + * Gets the looping of a soundobject. + * 0: SND_LOOP_OFF + * 1: SND_LOOP_NORMAL + * 2: SND_LOOP_BIDIRECTIONAL + * + * @param object: handle to soundobject. + */ +extern int SND_GetLoopMode(SND_ObjectHandle object); + +/** + * Gets the playstate of a soundobject. + * SND_UNKNOWN = -1 + * SND_INITIAL + * SND_MUST_PLAY + * SND_PLAYING + * SND_MUST_STOP + * SND_STOPPED + * SND_MUST_PAUSE + * SND_PAUSED + * SND_MUST_BE_DELETED + * + * @param object: handle to soundobject. + */ +extern int SND_GetPlaystate(SND_ObjectHandle object); + +#ifdef __cplusplus +} +#endif + +#endif |