FS2_Open
Open source remastering of the Freespace 2 engine
ds.h File Reference
#include "globalincs/pstypes.h"
#include "sound/ogg/ogg.h"
#include "cfile/cfile.h"

Go to the source code of this file.

Classes

struct  sound_info
 
struct  EFXREVERBPROPERTIES_list
 
struct  EFXREVERBPROPERTIES
 
struct  EAX_REVERBPROPERTIES
 

Macros

#define MIN_PITCH   100
 
#define MAX_PITCH   100000
 
#define DS_SQ_LOW   0
 
#define DS_SQ_MEDIUM   1
 
#define DS_SQ_HIGH   2
 
#define DS_MUST_PLAY   0
 
#define DS_LIMIT_ONE   1
 
#define DS_LIMIT_TWO   2
 
#define DS_LIMIT_THREE   3
 
#define DS_3D   (1<<0)
 
#define EAX_MAX_ENVIRONMENT   (EAX_ENVIRONMENT_COUNT - 1)
 

Typedefs

typedef struct sound_info sound_info
 
typedef struct EFXREVERBPROPERTIES_list EFXREVERBPROPERTIES_list
 
typedef struct EFXREVERBPROPERTIES EFXREVERBPROPERTIES
 

Enumerations

enum  {
  EAX_ENVIRONMENT_GENERIC, EAX_ENVIRONMENT_PADDEDCELL, EAX_ENVIRONMENT_ROOM, EAX_ENVIRONMENT_BATHROOM,
  EAX_ENVIRONMENT_LIVINGROOM, EAX_ENVIRONMENT_STONEROOM, EAX_ENVIRONMENT_AUDITORIUM, EAX_ENVIRONMENT_CONCERTHALL,
  EAX_ENVIRONMENT_CAVE, EAX_ENVIRONMENT_ARENA, EAX_ENVIRONMENT_HANGAR, EAX_ENVIRONMENT_CARPETEDHALLWAY,
  EAX_ENVIRONMENT_HALLWAY, EAX_ENVIRONMENT_STONECORRIDOR, EAX_ENVIRONMENT_ALLEY, EAX_ENVIRONMENT_FOREST,
  EAX_ENVIRONMENT_CITY, EAX_ENVIRONMENT_MOUNTAINS, EAX_ENVIRONMENT_QUARRY, EAX_ENVIRONMENT_PLAIN,
  EAX_ENVIRONMENT_PARKINGLOT, EAX_ENVIRONMENT_SEWERPIPE, EAX_ENVIRONMENT_UNDERWATER, EAX_ENVIRONMENT_DRUGGED,
  EAX_ENVIRONMENT_DIZZY, EAX_ENVIRONMENT_PSYCHOTIC, EAX_ENVIRONMENT_COUNT
}
 

Functions

int ds_init ()
 
void ds_close ()
 
int ds_parse_sound (CFILE *fp, ubyte **dest, uint *dest_size, WAVEFORMATEX **header, bool ogg=false, OggVorbis_File *ovf=NULL)
 Parse a wave file. More...
 
int ds_parse_sound_info (char *real_filename, sound_info *s_info)
 
int ds_load_buffer (int *sid, int *final_size, void *header, sound_info *si, int flags)
 Load a secondary buffer with sound data. More...
 
void ds_unload_buffer (int sid)
 
int ds_play (int sid, int snd_id, int priority, const EnhancedSoundData *enhanced_sound_data, float volume, float pan, int looping, bool is_voice_msg=false)
 
int ds_get_channel (int sig)
 
int ds_is_channel_playing (int channel)
 
void ds_stop_channel (int channel)
 
void ds_stop_channel_all ()
 
void ds_set_volume (int channel, float vol)
 Set the volume for a channel. The volume is expected to be in linear scale. More...
 
void ds_set_pan (int channel, float pan)
 
int ds_get_pitch (int channel)
 
void ds_set_pitch (int channel, int pitch)
 
void ds_chg_loop_status (int channel, int loop)
 
void ds_set_position (int channel, unsigned int offset)
 
unsigned int ds_get_play_position (int channel)
 
unsigned int ds_get_write_position (int channel)
 
int ds_get_data (int sid, char *data)
 
int ds_get_size (int sid, int *size)
 
int ds_create_buffer (int frequency, int bits_per_sample, int nchannels, int nseconds)
 
int ds_lock_data (int sid, unsigned char *data, int size)
 
int ds_play_easy (int sid, float volume)
 
void ds_stop_easy (int sid)
 
int ds_get_channel_size (int channel)
 
int ds_get_sound_id (int channel)
 
int ds_get_number_channels ()
 
int ds3d_play (int sid, int snd_id, vec3d *pos, vec3d *vel, float min, float max, int looping, float max_volume, float estimated_vol, const EnhancedSoundData *enhanced_sound_data, int priority=DS_MUST_PLAY, bool is_ambient=false)
 
void ds_do_frame ()
 
int ds_eax_init ()
 
void ds_eax_close ()
 
int ds_eax_get_preset_id (const char *name)
 
int ds_eax_get_prop (EFXREVERBPROPERTIES **props, const char *name, const char *template_name=NULL)
 
int ds_eax_set_volume (float volume)
 
int ds_eax_set_decay_time (float seconds)
 
int ds_eax_set_damping (float damp)
 
int ds_eax_set_environment (unsigned long envid)
 
int ds_eax_set_all (unsigned long id, float volume, float damping, float decay)
 
int ds_eax_get_all (EAX_REVERBPROPERTIES *er, int id=-1)
 
int ds_eax_is_inited ()
 

Variables

int Ds_sound_quality
 
int Ds_float_supported
 
int ds_initialized
 
SCP_vector< EFXREVERBPROPERTIESEFX_presets
 

Macro Definition Documentation

#define DS_3D   (1<<0)

Definition at line 47 of file ds.h.

#define DS_LIMIT_ONE   1

Definition at line 41 of file ds.h.

#define DS_LIMIT_THREE   3

Definition at line 43 of file ds.h.

#define DS_LIMIT_TWO   2

Definition at line 42 of file ds.h.

#define DS_MUST_PLAY   0

Definition at line 40 of file ds.h.

#define DS_SQ_HIGH   2

Definition at line 34 of file ds.h.

#define DS_SQ_LOW   0

Definition at line 32 of file ds.h.

#define DS_SQ_MEDIUM   1

Definition at line 33 of file ds.h.

#define EAX_MAX_ENVIRONMENT   (EAX_ENVIRONMENT_COUNT - 1)

Definition at line 211 of file ds.h.

#define MAX_PITCH   100000

Definition at line 28 of file ds.h.

#define MIN_PITCH   100

Definition at line 27 of file ds.h.

Typedef Documentation

typedef struct sound_info sound_info

Enumeration Type Documentation

anonymous enum
Enumerator
EAX_ENVIRONMENT_GENERIC 
EAX_ENVIRONMENT_PADDEDCELL 
EAX_ENVIRONMENT_ROOM 
EAX_ENVIRONMENT_BATHROOM 
EAX_ENVIRONMENT_LIVINGROOM 
EAX_ENVIRONMENT_STONEROOM 
EAX_ENVIRONMENT_AUDITORIUM 
EAX_ENVIRONMENT_CONCERTHALL 
EAX_ENVIRONMENT_CAVE 
EAX_ENVIRONMENT_ARENA 
EAX_ENVIRONMENT_HANGAR 
EAX_ENVIRONMENT_CARPETEDHALLWAY 
EAX_ENVIRONMENT_HALLWAY 
EAX_ENVIRONMENT_STONECORRIDOR 
EAX_ENVIRONMENT_ALLEY 
EAX_ENVIRONMENT_FOREST 
EAX_ENVIRONMENT_CITY 
EAX_ENVIRONMENT_MOUNTAINS 
EAX_ENVIRONMENT_QUARRY 
EAX_ENVIRONMENT_PLAIN 
EAX_ENVIRONMENT_PARKINGLOT 
EAX_ENVIRONMENT_SEWERPIPE 
EAX_ENVIRONMENT_UNDERWATER 
EAX_ENVIRONMENT_DRUGGED 
EAX_ENVIRONMENT_DIZZY 
EAX_ENVIRONMENT_PSYCHOTIC 
EAX_ENVIRONMENT_COUNT 

Definition at line 180 of file ds.h.

Function Documentation

int ds3d_play ( int  sid,
int  snd_id,
vec3d pos,
vec3d vel,
float  min,
float  max,
int  looping,
float  max_volume,
float  estimated_vol,
const EnhancedSoundData enhanced_sound_data,
int  priority,
bool  is_ambient 
)

Starts a ds3d sound playing

Parameters
sidSoftware id for sound to play
snd_idIdentifies what type of sound is playing
posWorld pos of sound
velVelocity of object emitting sound
minDistance at which sound doesn't get any louder
maxDistance at which sound becomes inaudible
loopingWhether to loop the sound or not
max_volumeVolume (0 to 1) for 3d sound at maximum
estimated_volManual estimated volume
priorityDS_MUST_PLAY, DS_LIMIT_ONE, DS_LIMIT_TWO, DS_LIMIT_THREE
Returns
0 if sound started successfully, -1 if sound could not be played

Definition at line 2044 of file ds.cpp.

void ds_chg_loop_status ( int  channel_id,
int  loop 
)
Todo:
Documentation

Definition at line 2017 of file ds.cpp.

void ds_close ( )

Close the sound system

Definition at line 1344 of file ds.cpp.

int ds_create_buffer ( int  frequency,
int  bits_per_sample,
int  nchannels,
int  nseconds 
)

Create a sound buffer in software, without locking any data in

Definition at line 1667 of file ds.cpp.

void ds_do_frame ( )

Called once per game frame to make sure voice messages aren't looping

Definition at line 2606 of file ds.cpp.

void ds_eax_close ( )

Close down EAX, freeing any allocated resources

Definition at line 2500 of file ds.cpp.

int ds_eax_get_all ( EAX_REVERBPROPERTIES er,
int  id 
)

Get up the parameters for the current environment

Parameters
er(output) Hold environment parameters
idIf set will get specified preset env, otherwise current env
Returns
0 if successful, otherwise return -1

Definition at line 2468 of file ds.cpp.

int ds_eax_get_preset_id ( const char *  name)

Definition at line 2376 of file ds.cpp.

int ds_eax_get_prop ( EFXREVERBPROPERTIES **  props,
const char *  name,
const char *  template_name = NULL 
)

Definition at line 2393 of file ds.cpp.

int ds_eax_init ( )

Initialize EAX

Returns
0 if initialization is successful, otherwise return -1

Definition at line 2521 of file ds.cpp.

int ds_eax_is_inited ( )
Todo:
Documentation

Definition at line 2598 of file ds.cpp.

int ds_eax_set_all ( unsigned long  id,
float  vol,
float  damping,
float  decay 
)

Set up all the parameters for an environment

Parameters
idValue from the EAX_ENVIRONMENT_* enumeration
volVolume for the environment (0 to 1.0)
dampingDamp value for the environment (0 to 2.0)
decayDecay time in seconds (0.1 to 20.0)
Returns
0 if successful, otherwise return -1

Definition at line 2348 of file ds.cpp.

int ds_eax_set_damping ( float  damp)

Set the damping value for the EAX environment (ie all sound sources)

Parameters
dampDamp value from 0 to 2.0
Returns
0 if the damp value is successfully set, otherwise return -1

Definition at line 2310 of file ds.cpp.

int ds_eax_set_decay_time ( float  seconds)

Set the decay time for the EAX environment (ie all sound sources)

Parameters
secondsDecay time in seconds
Returns
0 if decay time is successfully set, otherwise return -1

Definition at line 2289 of file ds.cpp.

int ds_eax_set_environment ( unsigned long  envid)

Set up the environment type for all sound sources.

Parameters
envidValue from the EAX_ENVIRONMENT_* enumeration in ds_eax.h
Returns
Always returns 0.
Todo:
Proper error reporting, otherwise make a void return type.

Definition at line 2332 of file ds.cpp.

int ds_eax_set_volume ( float  volume)

Set the master volume for the reverb added to all sound sources.

Parameters
volumeVolume, range from 0 to 1.0
Returns
0 if the volume is set successfully, otherwise return -1

Definition at line 2268 of file ds.cpp.

int ds_get_channel ( int  sig)

Return the channel number that is playing the sound identified by sig.

Returns
Channel number, if not playing, return -1.

Definition at line 1870 of file ds.cpp.

int ds_get_channel_size ( int  channel_id)
Todo:
Documentation

Definition at line 2177 of file ds.cpp.

int ds_get_data ( int  sid,
char *  data 
)

Retreive raw data from a sound buffer

Definition at line 2225 of file ds.cpp.

int ds_get_number_channels ( )

Returns the number of channels that are actually playing

Definition at line 2202 of file ds.cpp.

int ds_get_pitch ( int  channel_id)

Get the pitch of a channel

Definition at line 1965 of file ds.cpp.

unsigned int ds_get_play_position ( int  channel_id)
Todo:
Documentation

Definition at line 2127 of file ds.cpp.

int ds_get_size ( int  sid,
int size 
)

Return the size of the raw sound data

Definition at line 2233 of file ds.cpp.

int ds_get_sound_id ( int  channel_id)

Given a valid channel return the sound id

Definition at line 2639 of file ds.cpp.

unsigned int ds_get_write_position ( int  channel_id)
Todo:
Documentation

Definition at line 2169 of file ds.cpp.

int ds_init ( )

Sound initialisation

Returns
-1 if init failed, 0 if init success

Definition at line 1060 of file ds.cpp.

int ds_is_channel_playing ( int  channel_id)
Todo:
Documentation

Definition at line 1888 of file ds.cpp.

int ds_load_buffer ( int sid,
int final_size,
void header,
sound_info si,
int  flags 
)

Load a secondary buffer with sound data.

The sounds data for game sounds are stored in the DirectSound secondary buffers, and are duplicated as needed and placed in the Channels[] array to be played.

Parameters
sidPointer to software id for sound ( output parm)
final_sizePointer to storage to receive uncompressed sound size (output parm)
headerPointer to a WAVEFORMATEX structure
sisound_info structure, contains details on the sound format
flagsBuffer properties ( DS_HARDWARE , DS_3D )
Returns
1 if sound effect could not loaded into a secondary buffer, 0 if sound effect successfully loaded into a secondary buffer

NOTE: this function is slow, especially when sounds are loaded into hardware. Don't call this function from within gameplay.

Definition at line 676 of file ds.cpp.

int ds_lock_data ( int  sid,
unsigned char *  data,
int  size 
)

Lock data into an existing buffer

Definition at line 1698 of file ds.cpp.

int ds_parse_sound ( CFILE fp,
ubyte **  dest,
uint dest_size,
WAVEFORMATEX **  header,
bool  ogg,
OggVorbis_File *  ovf 
)

Parse a wave file.

Parameters
fpFile of sound to parse
destAddress of pointer of where to store raw sound data (output parm)
dest_sizeNumber of bytes of sound data stored (output parm)
headerAddress of pointer to a WAVEFORMATEX struct (output parm)
oggBoolean to indicate OGG vorbis file, if false assume Wave file
ovfPointer to a OggVorbis_File struct, OGG vorbis only (output parm)
Returns
0 if wave file successfully parsed, -1 if an error occurred
 NOTE: memory is malloced for the header and dest (if not OGG) in this function.  It is the responsibility
 of the caller to free this memory later.

Definition at line 246 of file ds.cpp.

int ds_parse_sound_info ( char *  real_filename,
sound_info s_info 
)

Parse a sound file, any format, and store the info in s_info.

Parameters
real_filenameFilename to parse
s_infoStorage for the sound file info

Definition at line 457 of file ds.cpp.

int ds_play ( int  sid,
int  snd_id,
int  priority,
const EnhancedSoundData enhanced_sound_data,
float  volume,
float  pan,
int  looping,
bool  is_voice_msg 
)

Play a sound secondary buffer.

Parameters
sidSoftware id of sound
snd_idWhat kind of sound this is
priorityDS_MUST_PLAY, DS_LIMIT_ONE, DS_LIMIT_TWO, DS_LIMIT_THREE
volumeVolume of sound effect in DirectSound units
panPan of sound in sound units
loopingWhether the sound effect is looping or not
is_voice_msgIf a voice message
Returns
1 if sound effect could not be started, >=0 sig for sound effect successfully started

Definition at line 1794 of file ds.cpp.

int ds_play_easy ( int  sid,
float  volume 
)

Play a sound without the usual baggage (used for playing back real-time voice)

Parameters
sidSoftware id of sound
volumeVolume of sound effect in linear scale

Definition at line 1738 of file ds.cpp.

void ds_set_pan ( int  channel_id,
float  pan 
)

Set the pan for a channel. The pan is expected to be in DirectSound units

Definition at line 1946 of file ds.cpp.

void ds_set_pitch ( int  channel_id,
int  pitch 
)

Set the pitch of a channel

Definition at line 1990 of file ds.cpp.

void ds_set_position ( int  channel_id,
unsigned int  offset 
)
Todo:
Documentation

Definition at line 2115 of file ds.cpp.

void ds_set_volume ( int  channel_id,
float  vol 
)

Set the volume for a channel. The volume is expected to be in linear scale.

If the sound is a 3D sound buffer, this is like re-establishing the maximum volume.

Definition at line 1929 of file ds.cpp.

void ds_stop_channel ( int  channel_id)
Todo:
Documentation

Definition at line 1904 of file ds.cpp.

void ds_stop_channel_all ( )
Todo:
Documentation

Definition at line 1914 of file ds.cpp.

void ds_stop_easy ( int  sid)

Stop a buffer from playing directly

Definition at line 1720 of file ds.cpp.

void ds_unload_buffer ( int  sid)

Unload a buffer

Definition at line 1307 of file ds.cpp.

Variable Documentation

int Ds_float_supported

Definition at line 62 of file ds.cpp.

int ds_initialized

Definition at line 229 of file ds.cpp.

int Ds_sound_quality

Definition at line 61 of file ds.cpp.

Definition at line 128 of file ds.cpp.