1
0
forked from 0ad/0ad

improved dox a bit; explicit deque_finished_bufs call, instead of changing update behavior via VS_ flags.

This was SVN commit r1278.
This commit is contained in:
janwas 2004-10-25 13:07:34 +00:00
parent 728e6e1f10
commit 4e7b6bd165
2 changed files with 42 additions and 32 deletions

View File

@ -1098,17 +1098,14 @@ enum VSrcFlags
// SndData has reported EOF. will close down after last buffer completes. // SndData has reported EOF. will close down after last buffer completes.
VS_EOF = 1, VS_EOF = 1,
// indicates the VSrc is being closed.
VS_CLOSING = 2,
// tell SndData to open the sound as a stream. // tell SndData to open the sound as a stream.
// require caller to pass this explicitly, so they're aware // require caller to pass this explicitly, so they're aware
// of the limitation that there can only be 1 instance of those. // of the limitation that there can only be 1 instance of those.
VS_IS_STREAM = 4, VS_IS_STREAM = 2,
// fn passed to VSrc_reload is the actual sound file name, // fn passed to VSrc_reload is the actual sound file name,
// not a definition file. // not a definition file.
VS_NO_DEF = 8 VS_NO_DEF = 4
}; };
struct VSrc struct VSrc
@ -1255,14 +1252,12 @@ static void vsrc_latch(VSrc* vs)
} }
static int vsrc_update(VSrc* vs) // return number removed.
static int vsrc_deque_finished_bufs(VSrc* vs)
{ {
int num_processed, num_queued; int num_processed;
alGetSourcei(vs->al_src, AL_BUFFERS_PROCESSED, &num_processed); alGetSourcei(vs->al_src, AL_BUFFERS_PROCESSED, &num_processed);
alGetSourcei(vs->al_src, AL_BUFFERS_QUEUED, &num_queued);
al_check("vsrc_update alGetSourcei");
// remove already processed buffers from queue.
for(int i = 0; i < num_processed; i++) for(int i = 0; i < num_processed; i++)
{ {
ALuint al_buf; ALuint al_buf;
@ -1270,9 +1265,18 @@ static int vsrc_update(VSrc* vs)
snd_data_buf_free(vs->hsd, al_buf); snd_data_buf_free(vs->hsd, al_buf);
} }
// closing the source; we just wanted to deque buffers - bail. al_check("vsrc_deque_finished_bufs");
if(vs->flags & VS_CLOSING) return num_processed;
return 0; }
static int vsrc_update(VSrc* vs)
{
int num_queued;
alGetSourcei(vs->al_src, AL_BUFFERS_QUEUED, &num_queued);
al_check("vsrc_update alGetSourcei");
int num_processed = vsrc_deque_finished_bufs(vs);
if(vs->flags & VS_EOF) if(vs->flags & VS_EOF)
{ {
@ -1360,11 +1364,10 @@ static int vsrc_reclaim(VSrc* vs)
alSourceStop(vs->al_src); alSourceStop(vs->al_src);
al_check("src_stop"); al_check("src_stop");
// (note: all queued buffers are now considered 'processed') // (note: all queued buffers are now considered 'processed')
// deque and free all buffers in queue // deque and free remaining buffers (if sound was closed abruptly).
// (there may be some left if we were closed abruptly). vsrc_deque_finished_bufs(vs);
vsrc_update(vs);
al_src_free(vs->al_src); al_src_free(vs->al_src);
return 0; return 0;
@ -1485,7 +1488,7 @@ int snd_free(Handle& hvs)
// or in the case of looped sounds, later. // or in the case of looped sounds, later.
// priority (min 0 .. max 1, default 0) indicates which sounds are // priority (min 0 .. max 1, default 0) indicates which sounds are
// considered more important; this is attenuated by distance to the // considered more important; this is attenuated by distance to the
// listener (see snd_update) // listener (see snd_update).
int snd_play(Handle hs, float static_pri) int snd_play(Handle hs, float static_pri)
{ {
H_DEREF(hs, VSrc, vs); H_DEREF(hs, VSrc, vs);

View File

@ -41,15 +41,22 @@ extern const char* snd_dev_next();
// sound system setup // sound system setup
// //
// tell OpenAL to use the specified device (0 for default) in future. // tell OpenAL to use the specified device in future.
// if OpenAL hasn't been initialized yet, we only remember the device // name = 0 reverts to OpenAL's default choice, which will also
// name, which will be set when oal_init is later called; otherwise, // be used if this routine is never called.
// OpenAL is reinitialized to use the desired device. //
// (this is to speed up the common case of retrieving a device name from // the device name is typically taken from a config file at init-time;
// config files and setting it; OpenAL doesn't have to be loaded until // the snd_dev* enumeration routines below are used to present a list
// sounds are actually played). // of choices to the user in the options screen.
// return 0 to indicate success, or the status returned while initializing //
// OpenAL. // if OpenAL hasn't yet been initialized (i.e. no sounds have been opened),
// this just stores the device name for use when init does occur.
// note: we can't check now if it's invalid (if so, init will fail).
// otherwise, we shut OpenAL down (thereby stopping all sounds) and
// re-initialize with the new device. that's fairly time-consuming,
// so preferably call this routine before sounds are loaded.
//
// return 0 on success, or the status returned by OpenAL re-init.
extern int snd_dev_set(const char* alc_new_dev_name); extern int snd_dev_set(const char* alc_new_dev_name);
// set maximum number of voices to play simultaneously, // set maximum number of voices to play simultaneously,
@ -72,18 +79,18 @@ extern int snd_set_master_gain(float gain);
// //
// is_stream (default false) forces the sound to be opened as a stream: // is_stream (default false) forces the sound to be opened as a stream:
// opening is faster, it won't be kept in memory, but only one instance // opening is faster, it won't be kept in memory, but only one instance
// can be open at a time. // of the sound file, and 2 streams total, are allowed at a time.
extern Handle snd_open_def(const char* def_fn, bool stream = false); extern Handle snd_open_def(const char* def_fn, bool stream = false);
// open and return a handle to the sound <snd_fn>. // open and return a handle to the sound file <snd_fn>.
// gain is set to the default, and may be changed via snd_set_gain. // gain is set to the default, and may be changed via snd_set_gain.
// //
// is_stream (default false) forces the sound to be opened as a stream: // is_stream (default false) forces the sound to be opened as a stream:
// opening is faster, it won't be kept in memory, but only one instance // opening is faster, it won't be kept in memory, but only one instance
// can be open at a time. // of the sound file, and 2 streams total, are allowed at a time.
extern Handle snd_open(const char* snd_fn, bool stream = false); extern Handle snd_open(const char* snd_fn, bool stream = false);
// close the sound <hvs> and set hvs to 0. if it was playing, // close the sound <hs> and set hs to 0. if it was playing,
// it will be stopped. sounds are closed automatically when done // it will be stopped. sounds are closed automatically when done
// playing; this is provided for completeness only. // playing; this is provided for completeness only.
extern int snd_free(Handle& hs); extern int snd_free(Handle& hs);
@ -94,7 +101,7 @@ extern int snd_free(Handle& hs);
// or in the case of looped sounds, later. // or in the case of looped sounds, later.
// priority (min 0 .. max 1, default 0) indicates which sounds are // priority (min 0 .. max 1, default 0) indicates which sounds are
// considered more important; this is attenuated by distance to the // considered more important; this is attenuated by distance to the
// listener (see snd_update) // listener (see snd_update).
extern int snd_play(Handle hs, float priority = 0.0f); extern int snd_play(Handle hs, float priority = 0.0f);
// change 3d position of the sound source. // change 3d position of the sound source.