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