blender/intern/SoundSystem/SND_C-api.h
Chris Want 5d0a207ecb Patch from GSR that a) fixes a whole bunch of GPL/BL license
blocks that were previously missed; and b) greatly increase my
ohloh stats!
2008-04-16 22:40:48 +00:00

355 lines
9.9 KiB
C

/**
* $Id$
*
* ***** BEGIN GPL 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.
*
* 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 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