simgear/sound/sample_openal.hxx

   1 // sample_openal.hxx -- Audio sample encapsulation class
   2 //
   3 // Written by Curtis Olson, started April 2004.
   4 // Modified to match the new SoundSystem by Erik Hofman, October 2009
   5 //
   6 // Copyright (C) 2004  Curtis L. Olson - http://www.flightgear.org/~curt
   7 // Copyright (C) 2009 Erik Hofman <erik@ehofman.com>
   8 //
   9 // This program is free software; you can redistribute it and/or
  10 // modify it under the terms of the GNU General Public License as
  11 // published by the Free Software Foundation; either version 2 of the
  12 // License, or (at your option) any later version.
  13 //
  14 // This program is distributed in the hope that it will be useful, but
  15 // WITHOUT ANY WARRANTY; without even the implied warranty of
  16 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 // General Public License for more details.
  18 //
  19 // You should have received a copy of the GNU General Public License
  20 // along with this program; if not, write to the Free Software Foundation,
  21 // Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  22 //
  23 // $Id$
  24
  25 /**
  26  * \file audio sample.hxx
  27  * Provides a audio sample encapsulation
  28  */
  29
  30 #ifndef _SG_SAMPLE_HXX
  31 #define _SG_SAMPLE_HXX 1
  32
  33 #ifndef __cplusplus
  34 # error This library requires C++
  35 #endif
  36
  37 #include <string>
  38 #include <cstdlib>
  39
  40 #include <simgear/compiler.h>
  41 #include <simgear/debug/logstream.hxx>
  42 #include <simgear/structure/SGReferenced.hxx>
  43 #include <simgear/structure/SGSharedPtr.hxx>
  44 #include <simgear/math/SGMath.hxx>
  45
  46 class SGPath;
  47
  48 /**
  49  * manages everything we need to know for an individual audio sample
  50  */
  51
  52 class SGSoundSample : public SGReferenced {
  53 public:
  54
  55      /**
  56       * Empty constructor, can be used to read data to the systems
  57       * memory and not to the driver.
  58       */
  59     SGSoundSample();
  60
  61     /**
  62      * Constructor
  63      * @param file File name of sound
  64        Buffer data is freed by the sample group
  65      */
  66     SGSoundSample(const char *file, const SGPath& currentDir);
  67
  68     /**
  69      * Constructor.
  70      * @param data Pointer to a memory buffer containing this audio sample data
  71        The application may free the data by calling free_data(), otherwise it
  72        will be resident untill the class is destroyed. This pointer will be
  73        set to NULL after calling this function.
  74      * @param len Byte length of array
  75      * @param freq Frequency of the provided data (bytes per second)
  76      * @param format OpenAL format id of the data
  77      */
  78     SGSoundSample( void** data, int len, int freq, int format=AL_FORMAT_MONO8 );
  79     SGSoundSample( const unsigned char** data, int len, int freq,
  80                    int format = AL_FORMAT_MONO8 );
  81
  82     /**
  83      * Destructor
  84      */
  85     ~SGSoundSample ();
  86
  87     /**
  88      * Detect wheter this audio sample holds the information of a sound file.
  89      * @return Return true if this audio sample is to be constructed from a file.
  90      */
  91     inline bool is_file() const { return _is_file; }
  92
  93     SGPath file_path() const;
  94
  95     /**
  96      * Test if this audio sample configuration has changed since the last call.
  97      * Calling this function will reset the flag so calling it a second
  98      * time in a row will return false.
  99      * @return Return true is the configuration has changed in the mean time.
 100      */
 101     bool has_changed() {
 102         bool b = _changed; _changed = false; return b;
 103     }
 104
 105     /**
 106      * Test if static dataa of audio sample configuration has changed.
 107      * Calling this function will reset the flag so calling it a second
 108      * time in a row will return false.
 109      * @return Return true is the static data has changed in the mean time.
 110      */
 111     bool has_static_data_changed() {
 112         bool b = _static_changed; _static_changed = false; return b;
 113     }
 114
 115     /**
 116      * Schedule this audio sample for playing. Actual playing will only start
 117      * at the next call op SoundGroup::update()
 118      * @param _loop Define whether this sound should be played in a loop.
 119      */
 120     void play( bool loop = false ) {
 121         _playing = true; _loop = loop; _changed = true;
 122     }
 123
 124     /**
 125      * Check if this audio sample is set to be continuous looping.
 126      * @return Return true if this audio sample is set to looping.
 127      */
 128     inline bool is_looping() { return _loop; }
 129
 130     /**
 131      * Schedule this audio sample to stop playing.
 132      */
 133     virtual void stop() {
 134         _playing = false; _changed = true;
 135     }
 136
 137     /**
 138      * Schedule this audio sample to play once.
 139      * @see #play
 140      */
 141     inline void play_once() { play(false); }
 142
 143     /**
 144      * Schedule this audio sample to play looped.
 145      * @see #play
 146      */
 147     inline void play_looped() { play(true); }
 148
 149     /**
 150      * Test if a audio sample is scheduled for playing.
 151      * @return true if this audio sample is playing, false otherwise.
 152      */
 153     inline bool is_playing() { return _playing; }
 154
 155     /**
 156      * Set the data associated with this audio sample
 157      * @param data Pointer to a memory block containg this audio sample data.
 158        This pointer will be set to NULL after calling this function.
 159      */
 160     inline void set_data( const unsigned char **data ) {
 161         _data = (unsigned char*)*data; *data = NULL;
 162     }
 163     inline void set_data( const void **data ) {
 164         _data = (unsigned char*)*data; *data = NULL;
 165     }
 166
 167     /**
 168      * Return the data associated with this audio sample.
 169      * @return A pointer to this sound data of this audio sample.
 170      */
 171     inline void* get_data() const { return _data; }
 172
 173     /**
 174      * Free the data associated with this audio sample
 175      */
 176     void free_data() {
 177         if ( _data != NULL ) free( _data ); _data = NULL;
 178     }
 179
 180     /**
 181      * Set the source id of this source
 182      * @param sid OpenAL source-id
 183      */
 184     virtual inline void set_source(unsigned int sid) {
 185         _source = sid; _valid_source = true; _changed = true;
 186     }
 187
 188     /**
 189      * Get the OpenAL source id of this source
 190      * @return OpenAL source-id
 191      */
 192     virtual inline unsigned int get_source() { return _source; }
 193
 194     /**
 195      * Test if the source-id of this audio sample may be passed to OpenAL.
 196      * @return true if the source-id is valid
 197      */
 198     virtual inline bool is_valid_source() const { return _valid_source; }
 199
 200     /**
 201      * Set the source-id of this audio sample to invalid.
 202      */
 203     virtual inline void no_valid_source() { _valid_source = false; }
 204
 205     /**
 206      * Set the OpenAL buffer-id of this source
 207      * @param bid OpenAL buffer-id
 208      */
 209     inline void set_buffer(unsigned int bid) {
 210         _buffer = bid; _valid_buffer = true; _changed = true;
 211     }
 212
 213     /**
 214      * Get the OpenAL buffer-id of this source
 215      * @return OpenAL buffer-id
 216      */
 217     inline unsigned int get_buffer() { return _buffer; }
 218
 219     /**
 220      * Test if the buffer-id of this audio sample may be passed to OpenAL.
 221      * @return true if the buffer-id is valid
 222      */
 223     inline bool is_valid_buffer() const { return _valid_buffer; }
 224
 225     /**
 226      * Set the buffer-id of this audio sample to invalid.
 227      */
 228     inline void no_valid_buffer() { _valid_buffer = false; }
 229
 230     /**
 231      * Set the playback pitch of this audio sample.
 232      * Should be between 0.0 and 2.0 for maximum compatibility.
 233      * @param p Pitch
 234      */
 235     inline void set_pitch( float p ) {
 236         if (p > 2.0) p = 2.0; else if (p < 0.01) p = 0.01;
 237         _pitch = p; _changed = true;
 238     }
 239
 240     /**
 241      * Get the current pitch value of this audio sample.
 242      * @return Pitch
 243      */
 244     inline float get_pitch() { return _pitch; }
 245
 246     /**
 247      * Set the master volume of this sample. Should be between 0.0 and 1.0.
 248      * The final volume is calculated by multiplying the master and audio sample
 249      * volume.
 250      * @param v Volume
 251      */
 252     inline void set_master_volume( float v ) {
 253         if (v > 1.0) v = 1.0; else if (v < 0.0) v = 0.0;
 254         _master_volume = v; _changed = true;
 255     }
 256
 257     /**
 258      * Set the volume of this audio sample. Should be between 0.0 and 1.0.
 259      * The final volume is calculated by multiplying the master and audio sample
 260      * volume.
 261      * @param v Volume
 262      */
 263     inline void set_volume( float v ) {
 264         if (v > 1.0) v = 1.0; else if (v < 0.0) v = 0.0;
 265         _volume = v; _changed = true;
 266     }
 267
 268     /**
 269      * Get the final volume value of this audio sample.
 270      * @return Volume
 271      */
 272     inline float get_volume() { return _volume * _master_volume; }
 273
 274     /**
 275      * Set the OpenAL format of this audio sample.
 276      * @param format OpenAL format-id
 277      */
 278     inline void set_format( int format ) { _format = format; }
 279
 280     /**
 281      * Returns the format of this audio sample.
 282      * @return OpenAL format-id
 283      */
 284     inline int get_format() { return _format; }
 285
 286     /**
 287      * Set the frequency (in Herz) of this audio sample.
 288      * @param freq Frequency
 289      */
 290     inline void set_frequency( int freq ) { _freq = freq; }
 291
 292     /**
 293      * Returns the frequency (in Herz) of this audio sample.
 294      * @return Frequency
 295      */
 296     inline int get_frequency() { return _freq; }
 297
 298     /**
 299      * Sets the size (in bytes) of this audio sample.
 300      * @param size Data size
 301      */
 302     inline void set_size( size_t size ) { _size = size; }
 303
 304     /**
 305      * Returns the size (in bytes) of this audio sample.
 306      * @return Data size
 307      */
 308     inline size_t get_size() const { return _size; }
 309
 310     /**
 311      * Set the position of this sound relative to the base position.
 312      * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
 313      * @param pos Relative position of this sound
 314      */
 315     inline void set_relative_position( const SGVec3f& pos ) {
 316         _relative_pos = toVec3d(pos); _changed = true;
 317     }
 318
 319     /**
 320      * Set the base position in Cartesian coordinates
 321      * @param pos position in Cartesian coordinates
 322      */
 323     inline void set_position( const SGVec3d& pos ) {
 324        _base_pos = pos; _changed = true;
 325     }
 326
 327     /**
 328      * Get the absolute position of this sound.
 329      * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
 330      * @return Absolute position
 331      */
 332     SGVec3d& get_position() { return _absolute_pos; }
 333
 334     /**
 335      * Set the orientation of this sound.
 336      * @param ori Quaternation containing the orientation information
 337      */
 338     inline void set_orientation( const SGQuatd& ori ) {
 339         _orientation = ori; _changed = true;
 340     }
 341
 342     inline void set_rotation( const SGQuatd& ec2body ) {
 343         _rotation = ec2body; _changed = true;
 344     }
 345
 346     /**
 347      * Set direction of this sound relative to the orientation.
 348      * This is in the same coordinate system as OpenGL; y=up, z=back, x=right
 349      * @param dir Sound emission direction
 350      */
 351     inline void set_direction( const SGVec3f& dir ) {
 352         _direction = toVec3d(dir); _static_changed = true;
 353     }
 354
 355     /**
 356      * Define the audio cone parameters for directional audio.
 357      * Note: setting it to 2 degree will result in 1 degree to both sides.
 358      * @param inner Inner cone angle (0 - 360 degrees)
 359      * @param outer Outer cone angle (0 - 360 degrees)
 360      * @param gain Remaining gain at the edge of the outer cone (0.0 - 1.0)
 361      */
 362     void set_audio_cone( float inner, float outer, float gain ) {
 363         _inner_angle = inner; _outer_angle = outer; _outer_gain = gain;
 364         _static_changed = true;
 365     }
 366
 367     /**
 368      * Get the orientation vector of this sound.
 369      * This is in the same coordinate system as OpenGL; y=up, z=back, x=right
 370      * @return Orientaton vector
 371      */
 372     SGVec3f& get_orientation() { return _orivec; }
 373
 374     /**
 375      * Get the inner angle of the audio cone.
 376      * @return Inner angle in degrees
 377      */
 378     float get_innerangle() { return _inner_angle; }
 379
 380     /**
 381      * Get the outer angle of the audio cone.
 382      * @return Outer angle in degrees
 383      */
 384     float get_outerangle() { return _outer_angle; }
 385
 386     /**
 387      * Get the remaining gain at the edge of the outer cone.
 388      * @return Gain
 389      */
 390     float get_outergain() { return _outer_gain; }
 391
 392     /**
 393      * Set the velocity vector (in meters per second) of this sound.
 394      * This is in the local frame coordinate system; x=north, y=east, z=down
 395      * @param Velocity vector
 396      */
 397     inline void set_velocity( const SGVec3f& vel ) {
 398         _velocity = vel; _changed = true;
 399     }
 400
 401     /**
 402      * Get velocity vector (in meters per second) of this sound.
 403      * This is in the same coordinate system as OpenGL; y=up, z=back, x=right
 404      * @return Velocity vector
 405      */
 406     SGVec3f& get_velocity() { return _velocity; }
 407
 408
 409     /**
 410      * Set reference distance (in meters) of this sound.
 411      * This is the distance where the gain will be half.
 412      * @param dist Reference distance
 413      */
 414     inline void set_reference_dist( float dist ) {
 415         _reference_dist = dist; _static_changed = true;
 416     }
 417
 418     /**
 419      * Get reference distance ((in meters) of this sound.
 420      * This is the distance where the gain will be half.
 421      * @return Reference distance
 422      */
 423     inline float get_reference_dist() { return _reference_dist; }
 424
 425
 426     /**
 427      * Set maximum distance (in meters) of this sound.
 428      * This is the distance where this sound is no longer audible.
 429      * @param dist Maximum distance
 430      */
 431     inline void set_max_dist( float dist ) {
 432         _max_dist = dist; _static_changed = true;
 433     }
 434
 435     /**
 436      * Get maximum distance (in meters) of this sound.
 437      * This is the distance where this sound is no longer audible.
 438      * @return dist Maximum distance
 439      */
 440     inline float get_max_dist() { return _max_dist; }
 441
 442     /**
 443      * Get the reference name of this audio sample.
 444      * @return Sample name
 445      */
 446     inline std::string get_sample_name() const { return _refname; }
 447
 448     inline virtual bool is_queue() const { return false; }
 449
 450     void update_pos_and_orientation();
 451
 452 private:
 453
 454     // Position of the source sound.
 455     SGVec3d _absolute_pos;      // absolute position
 456     SGVec3d _relative_pos;      // position relative to the base position
 457     SGVec3d _direction;         // orientation offset
 458     SGVec3f _velocity;          // Velocity of the source sound.
 459
 460     // The position and orientation of this sound
 461     SGQuatd _orientation;       // base orientation
 462     SGVec3f _orivec;            // orientation vector for OpenAL
 463     SGVec3d _base_pos;          // base position
 464
 465     SGQuatd _rotation;
 466
 467     std::string _refname;       // name or file path
 468     unsigned char* _data;
 469
 470     // configuration values
 471     int _format;
 472     size_t _size;
 473     int _freq;
 474
 475     // Buffers hold sound data.
 476     bool _valid_buffer;
 477     unsigned int _buffer;
 478
 479     // Sources are points emitting sound.
 480     bool _valid_source;
 481     unsigned int _source;
 482
 483     // The orientation of this sound (direction and cut-off angles)
 484     float _inner_angle;
 485     float _outer_angle;
 486     float _outer_gain;
 487
 488     float _pitch;
 489     float _volume;
 490     float _master_volume;
 491     float _reference_dist;
 492     float _max_dist;
 493     bool _loop;
 494
 495     bool _playing;
 496     bool _changed;
 497     bool _static_changed;
 498     bool _is_file;
 499
 500     string random_string();
 501 };
 502
 503
 504 #endif // _SG_SAMPLE_HXX
 505
 506