From: ehofman Date: Sat, 17 Oct 2009 12:36:48 +0000 (+0000) Subject: documentation, licensing, copyright and small api updates. X-Git-Url: https://git.mxchange.org/?a=commitdiff_plain;h=e2b8a21ff51630ad3c437d5cde927a3879654bd6;p=simgear.git documentation, licensing, copyright and small api updates. --- diff --git a/simgear/sound/sample_group.cxx b/simgear/sound/sample_group.cxx index fb2f31f0..1c63e3ee 100644 --- a/simgear/sound/sample_group.cxx +++ b/simgear/sound/sample_group.cxx @@ -1,3 +1,25 @@ +// sample_group.cxx -- Manage a group of samples relative to a base position +// +// Written for the new SoundSystem by Erik Hofman, October 2009 +// +// Copyright (C) 2009 Erik Hofman +// +// 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +// +// $Id$ + #ifdef HAVE_CONFIG_H # include #endif @@ -47,8 +69,8 @@ SGSampleGroup::SGSampleGroup () : _active(false), _tied_to_listener(false), _velocity(SGVec3d::zeros()), - _position(SGGeod()), - _orientation(SGQuatd::zeros()) + _orientation(SGQuatd::zeros()), + _position(SGGeod()) { _samples.clear(); } @@ -59,8 +81,8 @@ SGSampleGroup::SGSampleGroup ( SGSoundMgr *smgr, const string &refname ) : _active(false), _tied_to_listener(false), _velocity(SGVec3d::zeros()), - _position(SGGeod()), - _orientation(SGQuatd::zeros()) + _orientation(SGQuatd::zeros()), + _position(SGGeod()) { _smgr->add(this, refname); _samples.clear(); @@ -288,7 +310,7 @@ bool SGSampleGroup::stop( const string& refname ) { } // set source velocity of all managed sounds -void SGSampleGroup::set_velocity( SGVec3d &vel ) { +void SGSampleGroup::set_velocity( const SGVec3d &vel ) { if ( isnan(vel[0]) || isnan(vel[1]) || isnan(vel[2]) ) { SG_LOG( SG_GENERAL, SG_ALERT, "NAN's found in SampleGroup velocity"); @@ -307,7 +329,7 @@ void SGSampleGroup::set_velocity( SGVec3d &vel ) { } // set the source position of all managed sounds -void SGSampleGroup::set_position( SGGeod pos ) { +void SGSampleGroup::set_position( const SGGeod& pos ) { sample_map_iterator sample_current = _samples.begin(); sample_map_iterator sample_end = _samples.end(); @@ -320,7 +342,7 @@ void SGSampleGroup::set_position( SGGeod pos ) { // set the source orientation of all managed sounds -void SGSampleGroup::set_orientation( SGQuatd ori ) { +void SGSampleGroup::set_orientation( const SGQuatd& ori ) { if (_orientation != ori) { sample_map_iterator sample_current = _samples.begin(); diff --git a/simgear/sound/sample_group.hxx b/simgear/sound/sample_group.hxx index 9cfd8dfb..e98596c3 100644 --- a/simgear/sound/sample_group.hxx +++ b/simgear/sound/sample_group.hxx @@ -1,8 +1,8 @@ -// soundmgr.hxx -- Sound effect management class +// sample_group.hxx -- Manage a group of samples relative to a base position // -// Sampel Group handler initially written by Erik Hofman +// Written for the new SoundSystem by Erik Hofman, October 2009 // -// Copyright (C) 2009 Erik Hofman - +// Copyright (C) 2009 Erik Hofman // // This program is free software; you can redistribute it and/or // modify it under the terms of the GNU General Public License as @@ -64,99 +64,150 @@ class SGSoundMgr; class SGSampleGroup : public SGReferenced { public: + + /** + * Empty constructor for class encapsulation. + * Note: The sample group should still be activated before use + */ SGSampleGroup (); + + /** + * Constructor + * Register this sample group at the sound manager using refname + * Note: The sample group should still be activated before use + * @param smgr Pointer to a pre-initialized sound manager class + * @param refname Name of this group for reference purposes. + */ SGSampleGroup ( SGSoundMgr *smgr, const string &refname ); + + /** + * Destructor + */ ~SGSampleGroup (); + /** + * Set the status of this sample group to active. + */ + inline void activate() { _active = true; } + + /** + * Update function. + * Call this function periodically to update the OpenAL state of all + * samples associated with this class. None op the configuration changes + * take place without a call to this function. + */ virtual void update (double dt); /** - * add a sound effect, return true if successful + * Register an audio sample to this group. + * @param sound Pointer to a pre-initialized audio sample + * @param refname Name of this audio sample for reference purposes + * @return return true if successful */ bool add( SGSoundSample *sound, const string& refname ); /** - * remove a sound effect, return true if successful + * Remove an audio sample from this group. + * @param refname Reference name of the audio sample to remove + * @return return true if successful */ bool remove( const string& refname ); /** - * return true of the specified sound exists in the sound manager system + * Test if a specified audio sample is registered at this sample group + * @param refname Reference name of the audio sample to test for + * @return true if the specified audio sample exists */ bool exists( const string& refname ); /** - * return a pointer to the SGSoundSample if the specified sound - * exists in the sound manager system, otherwise return NULL + * Find a specified audio sample in this sample group + * @param refname Reference name of the audio sample to find + * @return A pointer to the SGSoundSample */ SGSoundSample *find( const string& refname ); /** - * request to stop playing all associated samples until further notice + * Request to stop playing all audio samples until further notice. */ void suspend(); /** - * request to resume playing all associated samples + * Request to resume playing all audio samples. */ void resume(); - /** - * request to start playing the associated samples + * Request to start playing the refered audio sample. + * @param refname Reference name of the audio sample to start playing + * @param looping Define if the sound should loop continuously + * @return true if the audio sample exsists and is scheduled for playing */ bool play( const string& refname, bool looping ); /** - * tell the scheduler to play the indexed sample in a continuous - * loop + * Request to start playing the refered audio sample looping. + * @param refname Reference name of the audio sample to start playing + * @return true if the audio sample exsists and is scheduled for playing */ inline bool play_looped( const string& refname ) { return play( refname, true ); } /** - * tell the scheduler to play the indexed sample once + * Request to start playing the refered audio sample once. + * @param refname Reference name of the audio sample to start playing + * @return true if the audio sample exsists and is scheduled for playing */ inline bool play_once( const string& refname ) { return play( refname, false ); } /** - * return true of the specified sound is currently being played + * Test if a referenced sample is playing or not. + * @param refname Reference name of the audio sample to test for + * @return True of the specified sound is currently playing */ bool is_playing( const string& refname ); /** - * request to stop playing the associated samples + * Request to stop playing the refered audio sample. + * @param refname Reference name of the audio sample to stop + * @return true if the audio sample exsists and is scheduled to stop */ bool stop( const string& refname ); /** - * set overall volume for the application. - * @param must be between 0.0 and 1.0 + * Set the master volume for this sample group. + * @param vol Volume (must be between 0.0 and 1.0) */ void set_volume( float vol ); /** - * set the velocities of all managed sound sources + * Set the velocity vector of this sample group. + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right. + * @param vel Velocity vector */ - void set_velocity( SGVec3d& vel ); + void set_velocity( const SGVec3d& vel ); /** - * set the position of all managed sound sources + * Set the position of this sample group. + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right. + * @param pos Base position */ - void set_position( SGGeod pos ); + void set_position( const SGGeod& pos ); /** - * set the orientation of all managed sound sources + * Set the orientation of this sample group. + * @param ori Quaternation containing the orientation information */ - void set_orientation( SGQuatd ori ); + void set_orientation( const SGQuatd& ori ); + /** + * Tie this sample group to the listener position, orientation and velocity + */ void tie_to_listener() { _tied_to_listener = true; } - void activate() { _active = true; } - protected: SGSoundMgr *_smgr; string _refname; @@ -167,8 +218,8 @@ private: bool _tied_to_listener; SGVec3d _velocity; - SGGeod _position; SGQuatd _orientation; + SGGeod _position; sample_map _samples; diff --git a/simgear/sound/sample_openal.cxx b/simgear/sound/sample_openal.cxx index 655a7e27..191877ae 100644 --- a/simgear/sound/sample_openal.cxx +++ b/simgear/sound/sample_openal.cxx @@ -1,8 +1,10 @@ -// sample.cxx -- Sound sample encapsulation class +// sample_openal.cxx -- Audio sample encapsulation class // // Written by Curtis Olson, started April 2004. +// Modified to match the new SoundSystem by Erik Hofman, October 2009 // // Copyright (C) 2004 Curtis L. Olson - http://www.flightgear.org/~curt +// Copyright (C) 2009 Erik Hofman // // This program is free software; you can redistribute it and/or // modify it under the terms of the GNU General Public License as @@ -43,9 +45,10 @@ SGSoundSample::SGSoundSample() : _relative_pos(SGVec3d::zeros()), _direction(SGVec3d::zeros()), _velocity(SGVec3d::zeros()), - _base_pos(SGGeod()), _orientation(SGQuatd::zeros()), - _sample_name(""), + _orivec(SGVec3f::zeros()), + _base_pos(SGGeod()), + _refname(""), _data(NULL), _format(AL_FORMAT_MONO8), _size(0), @@ -66,8 +69,7 @@ SGSoundSample::SGSoundSample() : _playing(false), _changed(true), _static_changed(true), - _is_file(false), - _orivec(SGVec3f::zeros()) + _is_file(false) { } @@ -77,8 +79,9 @@ SGSoundSample::SGSoundSample( const char *path, const char *file ) : _relative_pos(SGVec3d::zeros()), _direction(SGVec3d::zeros()), _velocity(SGVec3d::zeros()), - _base_pos(SGGeod()), _orientation(SGQuatd::zeros()), + _orivec(SGVec3f::zeros()), + _base_pos(SGGeod()), _format(AL_FORMAT_MONO8), _size(0), _freq(0), @@ -98,14 +101,13 @@ SGSoundSample::SGSoundSample( const char *path, const char *file ) : _playing(false), _changed(true), _static_changed(true), - _is_file(true), - _orivec(SGVec3f::zeros()) + _is_file(true) { SGPath samplepath( path ); if ( strlen(file) ) { samplepath.append( file ); } - _sample_name = samplepath.str(); + _refname = samplepath.str(); SG_LOG( SG_GENERAL, SG_DEBUG, "From file sounds sample = " << samplepath.str() ); @@ -117,8 +119,9 @@ SGSoundSample::SGSoundSample( unsigned char *data, int len, int freq, int format _relative_pos(SGVec3d::zeros()), _direction(SGVec3d::zeros()), _velocity(SGVec3d::zeros()), - _base_pos(SGGeod()), _orientation(SGQuatd::zeros()), + _orivec(SGVec3f::zeros()), + _base_pos(SGGeod()), _data(data), _format(format), _size(len), @@ -139,10 +142,9 @@ SGSoundSample::SGSoundSample( unsigned char *data, int len, int freq, int format _playing(false), _changed(true), _static_changed(true), - _is_file(false), - _orivec(SGVec3f::zeros()) + _is_file(false) { - _sample_name = "unknown, data supplied by caller"; + _refname = "unknown, data supplied by caller"; SG_LOG( SG_GENERAL, SG_DEBUG, "In memory sounds sample" ); } @@ -151,25 +153,25 @@ SGSoundSample::SGSoundSample( unsigned char *data, int len, int freq, int format SGSoundSample::~SGSoundSample() { } -void SGSoundSample::set_orientation( SGQuatd ori ) { +void SGSoundSample::set_orientation( const SGQuatd& ori ) { _orientation = ori; update_absolute_position(); _changed = true; } -void SGSoundSample::set_direction( SGVec3d dir ) { +void SGSoundSample::set_direction( const SGVec3d& dir ) { _direction = dir; update_absolute_position(); _changed = true; } -void SGSoundSample::set_relative_position( SGVec3f pos ) { +void SGSoundSample::set_relative_position( const SGVec3f& pos ) { _relative_pos = toVec3d(pos); update_absolute_position(); _changed = true; } -void SGSoundSample::set_position( SGGeod pos ) { +void SGSoundSample::set_position( const SGGeod& pos ) { _base_pos = pos; update_absolute_position(); _changed = true; diff --git a/simgear/sound/sample_openal.hxx b/simgear/sound/sample_openal.hxx index acc7fb73..448e0812 100644 --- a/simgear/sound/sample_openal.hxx +++ b/simgear/sound/sample_openal.hxx @@ -1,8 +1,10 @@ -// sample.hxx -- Sound sample encapsulation class +// sample_openal.hxx -- Audio sample encapsulation class // // Written by Curtis Olson, started April 2004. +// Modified to match the new SoundSystem by Erik Hofman, October 2009 // // Copyright (C) 2004 Curtis L. Olson - http://www.flightgear.org/~curt +// Copyright (C) 2009 Erik Hofman // // This program is free software; you can redistribute it and/or // modify it under the terms of the GNU General Public License as @@ -15,14 +17,14 @@ // 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +// along with this program; if not, write to the Free Software Foundation, +// Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. // // $Id$ /** - * \file sample.hxx - * Provides a sound sample encapsulation + * \file audio sample.hxx + * Provides a audio sample encapsulation */ #ifndef _SG_SAMPLE_HXX @@ -43,59 +45,10 @@ // #include /** - * manages everything we need to know for an individual sound sample + * manages everything we need to know for an individual audio sample */ class SGSoundSample : public SGReferenced { - -private: - - // Position of the source sound. - SGVec3d _absolute_pos; // absolute position - SGVec3d _relative_pos; // position relative to the base position - SGVec3d _direction; // orientation offset - SGVec3d _velocity; // Velocity of the source sound. - - // The position and orientation of the sound - SGGeod _base_pos; - SGQuatd _orientation; // base orientation - - std::string _sample_name; - unsigned char *_data; - - // configuration values - int _format; - int _size; - int _freq; - - // Buffers hold sound data. - bool _valid_buffer; - unsigned int _buffer; - - // Sources are points emitting sound. - bool _valid_source; - unsigned int _source; - - // The orientation of the sound (direction and cut-off angles) - float _inner_angle; - float _outer_angle; - float _outer_gain; - - float _pitch; - float _volume; - float _master_volume; - float _reference_dist; - float _max_dist; - bool _loop; - - bool _playing; - bool _changed; - bool _static_changed; - bool _is_file; - - SGVec3f _orivec; - void update_absolute_position(); - public: /** @@ -115,241 +68,269 @@ public: /** * Constructor. - * @param _data Pointer to a memory buffer containing the sample data - the application is responsible for freeing the buffer data. + * @param data Pointer to a memory buffer containing this audio sample data + buffer data is freed by this audio sample manager. * @param len Byte length of array - * @param _freq Frequency of the provided data (bytes per second) - should usually be true unless you want to manipulate the data - later.) + * @param freq Frequency of the provided data (bytes per second) + * @param format OpenAL format id of the data */ - SGSoundSample( unsigned char *data, int len, int freq, int format = AL_FORMAT_MONO8 ); + SGSoundSample( unsigned char *data, int len, int freq, + int format = AL_FORMAT_MONO8 ); + /** + * Destructor + */ ~SGSoundSample (); /** - * detect wheter the sample holds the information of a sound file + * Detect wheter this audio sample holds the information of a sound file. + * @return Return true if this audio sample is to be constructed from a file. */ inline bool is_file() const { return _is_file; } /** - * Test whether this sample has a changed configuration since the last - * call. (Calling this function resets the value). + * Test if this audio sample configuration has changed since the last call. + * Calling this function will reset the flag so calling it a second + * time in a row will return false. + * @return Return true is the configuration has changed in the mean time. */ - inline bool has_changed() { + bool has_changed() { bool b = _changed; _changed = false; return b; } - inline bool has_static_data_changed() { + /** + * Test if static dataa of audio sample configuration has changed. + * Calling this function will reset the flag so calling it a second + * time in a row will return false. + * @return Return true is the static data has changed in the mean time. + */ + bool has_static_data_changed() { bool b = _static_changed; _static_changed = false; return b; } - /** - * Start playing this sample. - * - * @param _loop Define whether the sound should be played in a loop. + * Schedule this audio sample for playing. Actual playing will only start + * at the next call op SoundGroup::update() + * @param _loop Define whether this sound should be played in a loop. */ - inline void play( bool loop ) { + void play( bool loop ) { _playing = true; _loop = loop; _changed = true; } /** - * Return if the sample is looping or not. + * Check if this audio sample is set to be continuous looping. + * @return Return true if this audio sample is set to looping. */ inline bool get_looping() { return _loop; } /** - * Stop playing this sample. - * - * @param sched A pointer to the appropriate scheduler. + * Schedule this audio sample to stop playing. */ - inline void stop() { + void stop() { _playing = false; _changed = true; } /** - * Play this sample once. + * Schedule this audio sample to play once. * @see #play */ inline void play_once() { play(false); } /** - * Play this sample looped. + * Schedule this audio sample to play looped. * @see #play */ inline void play_looped() { play(true); } /** - * Test if a sample is currently playing. - * @return true if is is playing, false otherwise. + * Test if a audio sample is scheduled for playing. + * @return true if this audio sample is playing, false otherwise. */ inline bool is_playing() { return _playing; } /** - * set the data associated with this sample + * sSt the data associated with this audio sample + * @param data Pointer to a memory block containg this audio sample data. */ - inline void set_data( unsigned char* data ) { - _data = data; - } + inline void set_data( unsigned char* data ) { _data = data; } /** - * @return the data associated with this sample + * Return the data associated with this audio sample. + * @return A pointer to this sound data of this audio sample. */ inline void* get_data() const { return _data; } /** - * free the data associated with this sample + * Free the data associated with this audio sample */ - inline void free_data() { + void free_data() { if (_data != NULL) { delete _data; _data = NULL; } } /** - * set the source id of this source + * Set the source id of this source + * @param sid OpenAL source-id */ - inline void set_source(unsigned int s) { - _source = s; _valid_source = true; _changed = true; + void set_source(unsigned int sid) { + _source = sid; _valid_source = true; _changed = true; } /** - * get the source id of this source + * Get the OpenAL source id of this source + * @return OpenAL source-id */ inline unsigned int get_source() { return _source; } /** - * detect wheter the source id of the sample is valid + * Test if the source-id of this audio sample may be passed to OpenAL. + * @return true if the source-id is valid */ inline bool is_valid_source() const { return _valid_source; } /** - * set the source id of the sample to invalid. + * Set the source-id of this audio sample to invalid. */ - inline void no_valid_source() { - _valid_source = false; - } + inline void no_valid_source() { _valid_source = false; } /** - * set the buffer id of this source + * Set the OpenAL buffer-id of this source + * @param bid OpenAL buffer-id */ - inline void set_buffer(unsigned int b) { - _buffer = b; _valid_buffer = true; _changed = true; + void set_buffer(unsigned int bid) { + _buffer = bid; _valid_buffer = true; _changed = true; } /** - * get the buffer id of this source + * Get the OpenAL buffer-id of this source + * @return OpenAL buffer-id */ inline unsigned int get_buffer() { return _buffer; } /** - * detect wheter the source id of the sample is valid + * Test if the buffer-id of this audio sample may be passed to OpenAL. + * @return true if the buffer-id is valid */ inline bool is_valid_buffer() const { return _valid_buffer; } /** - * set the source id of the sample to invalid. + * Set the buffer-id of this audio sample to invalid. */ - inline void no_valid_buffer() { - _valid_buffer = false; - } + inline void no_valid_buffer() { _valid_buffer = false; } /** - * Get the current pitch setting of this sample. + * Set the playback pitch of this audio sample. + * Should be between 0.0 and 2.0 for maximum compatibility. + * @param p Pitch */ - inline float get_pitch() { return _pitch; } + inline void set_pitch( float p ) { _pitch = p; _changed = true; } /** - * Set the pitch of this sample. + * Get the current pitch value of this audio sample. + * @return Pitch */ - inline void set_pitch( float p ) { - _pitch = p; _changed = true; - } - - /** - * Get the current volume setting of this sample. - */ - inline float get_volume() { return _volume * _master_volume; } + inline float get_pitch() { return _pitch; } /** - * Set the master (sampel group) volume of this sample. + * Set the master volume of this sample. Should be between 0.0 and 1.0. + * The final volume is calculated by multiplying the master and audio sample + * volume. + * @param v Volume */ inline void set_master_volume( float v ) { _master_volume = v; _changed = true; } /** - * Set the volume of this sample. + * Set the volume of this audio sample. Should be between 0.0 and 1.0. + * The final volume is calculated by multiplying the master and audio sample + * volume. + * @param v Volume */ - inline void set_volume( float v ) { - _volume = v; _changed = true; - } + inline void set_volume( float v ) { _volume = v; _changed = true; } /** - * Set the format of the sounds sample + * Get the final volume value of this audio sample. + * @return Volume */ - inline void set_format( int format ) { - _format = format; - } + inline float get_volume() { return _volume * _master_volume; } /** - * Returns the format of the sounds sample + * Set the OpenAL format of this audio sample. + * @param format OpenAL format-id */ - inline int get_format() { return _format; } + inline void set_format( int format ) { _format = format; } + /** + * Returns the format of this audio sample. + * @return OpenAL format-id + */ + inline int get_format() { return _format; } /** - * Set the frequency of the sounds sample + * Set the frequency (in Herz) of this audio sample. + * @param freq Frequency */ - inline void set_frequency( int freq ) { - _freq = freq; _changed = true; - } + inline void set_frequency( int freq ) { _freq = freq; _changed = true; } /** - * Returns the frequency of the sounds sample + * Returns the frequency (in Herz) of this audio sample. + * @return Frequency */ inline int get_frequency() { return _freq; } /** - * Returns the size of the sounds sample + * Sets the size (in bytes) of this audio sample. + * @param size Data size */ - inline void set_size( int size ) { - _size = size; - } + inline void set_size( size_t size ) { _size = size; } /** - * Returns the size of the sounds sample + * Returns the size (in bytes) of this audio sample. + * @return Data size */ - inline int get_size() const { return _size; } + inline size_t get_size() const { return _size; } /** - * Set position of the sound source (uses same coordinate system as opengl) + * Set the position of this sound relative to the base position. + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right. + * @param pos Relative position of this sound */ - void set_relative_position( SGVec3f pos ); + void set_relative_position( const SGVec3f& pos ); /** - * Get position of the sound source (uses same coordinate system as opengl) + * Set the base position of this sound in Geodetic coordinates. + * @param pos Geodetic position */ - inline float *get_position() const { return toVec3f(_absolute_pos).data(); } + void set_position( const SGGeod& pos ); /** - * Set the position of the sound source + * Get the absolute position of this sound. + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right. + * @return Absolute position */ - void set_position( SGGeod pos ); + float *get_position() const { return toVec3f(_absolute_pos).data(); } /** - * Set the orientation of the sound source + * Set the orientation of this sound. + * @param ori Quaternation containing the orientation information */ - void set_orientation( SGQuatd ori ); + void set_orientation( const SGQuatd& ori ); /** - * Set the relative direction of the sound source, both for direction - * and audio cut-off angles. + * Set direction of this sound relative to the orientation. + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right + * @param dir Sound emission direction */ - void set_direction( SGVec3d dir ); + void set_direction( const SGVec3d& dir ); /** - * Define the audio cone parameters for directional audio + * Define the audio cone parameters for directional audio. + * Note: setting it to 1 degree will result in 0.5 degrees to both sides. + * @param inner Inner cone angle (0 - 360 degrees) + * @param outer Outer cone angle (0 - 360 degrees) + * @param gain Remaining gain at the edge of the outer cone (0.0 - 1.0) */ - inline void set_audio_cone( float inner, float outer, float gain ) { + void set_audio_cone( float inner, float outer, float gain ) { _inner_angle = inner; _outer_angle = outer; _outer_gain = gain; @@ -357,61 +338,133 @@ public: } /** - * Get the orientation of the sound source, the inner or outer angle - * or outer gain. + * Get the orientation vector of this sound. + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right + * @return Orientaton vector */ float *get_orientation() { return _orivec.data(); } + + /** + * Get the inner angle of the audio cone. + * @return Inner angle in degrees + */ float get_innerangle() { return _inner_angle; } + + /** + * Get the outer angle of the audio cone. + * @return Outer angle in degrees + */ float get_outerangle() { return _outer_angle; } + + /** + * Get the remaining gain at the edge of the outer cone. + * @return Gain + */ float get_outergain() { return _outer_gain; } /** - * Set velocity of the sound source (uses same coordinate system as opengl) + * Set the velocity vector (in meters per second) of this sound. + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right + * @param Velocity vector */ - inline void set_velocity( SGVec3d& vel ) { - _velocity = vel; - _changed = true; + inline void set_velocity( const SGVec3d& vel ) { + _velocity = vel; _changed = true; } /** - * Get velocity of the sound source (uses same coordinate system as opengl) + * Get velocity vector (in meters per second) of this sound. + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right + * @return Velocity vector */ - inline float *get_velocity() { return toVec3f(_velocity).data(); } + float *get_velocity() { return toVec3f(_velocity).data(); } /** - * Set reference distance of sound (the distance where the gain - * will be half.) + * Set reference distance (in meters) of this sound. + * This is the distance where the gain will be half. + * @param dist Reference distance */ inline void set_reference_dist( float dist ) { _reference_dist = dist; _static_changed = true; } /** - * Get reference distance of sound (the distance where the gain - * will be half.) + * Get reference distance ((in meters) of this sound. + * This is the distance where the gain will be half. + * @return Reference distance */ inline float get_reference_dist() { return _reference_dist; } /** - * Set maximum distance of sound (the distance where the sound is - * no longer audible. + * Set maximum distance (in meters) of this sound. + * This is the distance where this sound is no longer audible. + * @param dist Maximum distance */ - void set_max_dist( float dist ) { + inline void set_max_dist( float dist ) { _max_dist = dist; _static_changed = true; } /** - * Get maximum istance of sound (the distance where the sound is - * no longer audible. + * Get maximum distance (in meters) of this sound. + * This is the distance where this sound is no longer audible. + * @return dist Maximum distance */ inline float get_max_dist() { return _max_dist; } /** - * Get the name of this sample + * Get the reference name of this audio sample. + * @return Sample name */ - inline std::string get_sample_name() { return _sample_name; } + inline std::string get_sample_name() const { return _refname; } + +private: + + // Position of the source sound. + SGVec3d _absolute_pos; // absolute position + SGVec3d _relative_pos; // position relative to the base position + SGVec3d _direction; // orientation offset + SGVec3d _velocity; // Velocity of the source sound. + + // The position and orientation of this sound + SGQuatd _orientation; // base orientation + SGVec3f _orivec; // orientation vector for OpenAL + SGGeod _base_pos; // base position + + std::string _refname; // name or file path + unsigned char *_data; + + // configuration values + int _format; + size_t _size; + int _freq; + + // Buffers hold sound data. + bool _valid_buffer; + unsigned int _buffer; + + // Sources are points emitting sound. + bool _valid_source; + unsigned int _source; + + // The orientation of this sound (direction and cut-off angles) + float _inner_angle; + float _outer_angle; + float _outer_gain; + + float _pitch; + float _volume; + float _master_volume; + float _reference_dist; + float _max_dist; + bool _loop; + + bool _playing; + bool _changed; + bool _static_changed; + bool _is_file; + + void update_absolute_position(); }; diff --git a/simgear/sound/soundmgr_openal.cxx b/simgear/sound/soundmgr_openal.cxx index cbb137ef..10d406e0 100644 --- a/simgear/sound/soundmgr_openal.cxx +++ b/simgear/sound/soundmgr_openal.cxx @@ -4,8 +4,10 @@ // 2001 // // C++-ified by Curtis Olson, started March 2001. +// Modified for the new SoundSystem by Erik Hofman, October 2009 // // Copyright (C) 2001 Curtis L. Olson - http://www.flightgear.org/~curt +// Copyright (C) 2009 Erik Hofman // // This program is free software; you can redistribute it and/or // modify it under the terms of the GNU General Public License as @@ -218,13 +220,6 @@ void SGSoundMgr::unbind () _sources_in_use.clear(); } -void SGSoundMgr::update( double dt ) -{ - // nothing to do in the regular update, everything is done on the following - // function -} - - // run the audio scheduler void SGSoundMgr::update_late( double dt ) { if (_working) { @@ -420,7 +415,7 @@ unsigned int SGSoundMgr::request_buffer(SGSoundSample *sample) // sample name was not found in the buffer cache. if ( sample->is_file() ) { - unsigned int size; + size_t size; int freq, format; void *data; @@ -476,7 +471,7 @@ void SGSoundMgr::release_buffer(SGSoundSample *sample) } bool SGSoundMgr::load(string &samplepath, void **dbuf, int *fmt, - unsigned int *sz, int *frq ) + size_t *sz, int *frq ) { ALenum format; ALsizei size; @@ -514,7 +509,7 @@ bool SGSoundMgr::load(string &samplepath, void **dbuf, int *fmt, *dbuf = (void *)data; *fmt = (int)format; - *sz = (unsigned int)size; + *sz = (size_t)size; *frq = (int)freq; return true; diff --git a/simgear/sound/soundmgr_openal.hxx b/simgear/sound/soundmgr_openal.hxx index e2e2be40..3b4572be 100644 --- a/simgear/sound/soundmgr_openal.hxx +++ b/simgear/sound/soundmgr_openal.hxx @@ -4,8 +4,10 @@ // 2001 // // C++-ified by Curtis Olson, started March 2001. +// Modified for the new SoundSystem by Erik Hofman, October 2009 // // Copyright (C) 2001 Curtis L. Olson - http://www.flightgear.org/~curt +// Copyright (C) 2009 Erik Hofman // // This program is free software; you can redistribute it and/or // modify it under the terms of the GNU General Public License as @@ -96,7 +98,7 @@ public: void init(); void bind(); void unbind(); - void update(double dt); + void update(double dt) {}; void update_late(double dt); void suspend(); @@ -106,59 +108,92 @@ public: inline void reinit() { stop(); init(); } /** - * is audio working? + * Test is the sound manager is in a working condition. + * @return true is the sound manager is working */ inline bool is_working() const { return _working; } /** - * add a sample group, return true if successful + * Register a sample group to the sound manager. + * @para sgrp Pointer to a sample group to add + * @param refname Reference name of the sample group + * @return true if successful, false otherwise */ bool add( SGSampleGroup *sgrp, const string& refname ); /** - * remove a sample group, return true if successful + * Remove a sample group from the sound manager. + * @param refname Reference name of the sample group to remove + * @return true if successful, false otherwise */ bool remove( const string& refname ); /** - * return true of the specified sound exists in the sound manager system + * Test if a specified sample group is registered at the sound manager + * @param refname Reference name of the sample group test for + * @return true if the specified sample group exists */ bool exists( const string& refname ); /** - * return a pointer to the SGSampleGroup if the specified sound - * exists in the sound manager system, otherwise return NULL + * Find a specified sample group in the sound manager + * @param refname Reference name of the sample group to find + * @return A pointer to the SGSampleGroup */ SGSampleGroup *find( const string& refname, bool create = false ); /** - * set the position of the listener (in opengl coordinates) + * Set the position of the sound manager. + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right. + * @param pos OpenAL listener position */ void set_position( const SGVec3d& pos ) { _position = -pos; _changed = true; } - inline SGVec3f get_position() { return toVec3f(_position); } + /** + * Get the position of the sound manager. + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right + * @return OpenAL listener position + */ + SGVec3f get_position() { return toVec3f(_position); } /** - * set the velocity direction of the listener (in opengl coordinates) + * Set the velocity vector of the sound manager + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right. + * @param vel Velocity vector of the OpenAL listener */ void set_velocity( SGVec3d& dir ) { _velocity = dir; _changed = true; } + /** + * Get the velocity vector of the sound manager + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right. + * @return Velocity vector of the OpenAL listener + */ inline SGVec3f get_velocity() { return toVec3f(_velocity); } /** - * set the orientation of the listener (in opengl coordinates) + * Set the orientation of the sound manager + * @param ori Quaternation containing the orientation information */ void set_orientation( SGQuatd ori ); + /** + * Get the orientation of the sound manager + * @return Quaternation containing the orientation information + */ inline const SGQuatd& get_orientation() { return _orientation; } - inline SGVec3f get_direction() { + /** + * Get the direction vector of the sound manager + * This is in the same coordinate system as OpenGL; y=up, z=back, x=right. + * @return Look-at direction of the OpenAL listener + */ + SGVec3f get_direction() { return SGVec3f(_at_up_vec[0], _at_up_vec[1], _at_up_vec[2]); } @@ -167,42 +202,62 @@ public: NO_BUFFER = (unsigned int)-1 }; - void set_volume( float v ); + /** + * Set the master volume. + * @param vol Volume (must be between 0.0 and 1.0) + */ + void set_volume( float vol ); + + /** + * Get the master volume. + * @return Volume (must be between 0.0 and 1.0) + */ inline float get_volume() { return _volume; } /** - * get a new OpenAL source id - * returns NO_SOURCE if no source is available + * Get a free OpenAL source-id + * @return NO_SOURCE if no source is available */ unsigned int request_source(); /** - * give back an OpenAL source id for further use. + * Free an OpenAL source-id for future use + * @param source OpenAL source-id to free */ void release_source( unsigned int source ); /** - * get a new OpenAL buffer id - * returns NO_BUFFER if loading of the buffer failed. + * Get a free OpenAL buffer-id + * The buffer-id will be asigned to the sample by calling this function. + * @param sample Pointer to an audio sample to assign the buffer-id to + * @return NO_BUFFER if loading of the buffer failed. */ unsigned int request_buffer(SGSoundSample *sample); /** - * give back an OpenAL source id for further use. + * Free an OpenAL buffer-id for this sample + * @param sample Pointer to an audio sample for which to free the buffer */ void release_buffer( SGSoundSample *sample ); - - /** - * returns true if the position has changed + * Test if the position of the sound manager has changed. + * The value will be set to false upon the next call to update_late() + * @return true if the position has changed */ inline bool has_changed() { return _changed; } + /** + * Load a sample file and return it's configuration and data. + * @param samplepath Path to the file to load + * @param data Pointer to a variable that points to the allocated data + * @param format Pointer to a vairable that gets the OpenAL format + * @param size Pointer to a vairable that gets the sample size in bytes + * @param freq Pointer to a vairable that gets the sample frequency in Herz + * @return true if succesful, false on error + */ bool load(string &samplepath, void **data, int *format, - unsigned int*size, int *freq ); - - + size_t *size, int *freq ); private: static int _alut_init; @@ -237,6 +292,7 @@ private: bool testForALCError(string s); bool testForALUTError(string s); bool testForError(void *p, string s); + void update_sample_config( SGSampleGroup *sound ); };