1 // sample_openal.hxx -- Audio sample encapsulation class
3 // Written by Curtis Olson, started April 2004.
4 // Modified to match the new SoundSystem by Erik Hofman, October 2009
6 // Copyright (C) 2004 Curtis L. Olson - http://www.flightgear.org/~curt
7 // Copyright (C) 2009 Erik Hofman <erik@ehofman.com>
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.
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.
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.
26 * \file audio sample.hxx
27 * Provides a audio sample encapsulation
30 #ifndef _SG_SAMPLE_HXX
31 #define _SG_SAMPLE_HXX 1
33 #include <simgear/math/SGMath.hxx>
34 #include <simgear/props/props.hxx>
42 SG_SAMPLE_16BITS = 16,
44 SG_SAMPLE_UNCOMPRESSED = 0,
45 SG_SAMPLE_COMPRESSED = 256,
47 SG_SAMPLE_MONO8 = (SG_SAMPLE_MONO|SG_SAMPLE_8BITS),
48 SG_SAMPLE_MONO16 = (SG_SAMPLE_MONO|SG_SAMPLE_16BITS),
49 SG_SAMPLE_MULAW = (SG_SAMPLE_MONO|SG_SAMPLE_8BITS|SG_SAMPLE_COMPRESSED),
50 SG_SAMPLE_ADPCM = (SG_SAMPLE_MONO|SG_SAMPLE_4BITS|SG_SAMPLE_COMPRESSED)
55 * manages everything we need to know for an individual audio sample
58 class SGSoundSampleInfo
62 ~SGSoundSampleInfo() {}
65 * Returns the format of this audio sample.
66 * @return SimGear format-id
68 inline unsigned int get_format() { return (_tracks | _bits | _compressed*256); }
71 * Get the reference name of this audio sample.
74 inline std::string get_sample_name() const { return _refname; }
77 * Returns the frequency (in Herz) of this audio sample.
80 inline unsigned int get_frequency() { return _frequency; }
83 * Get the current pitch value of this audio sample.
86 inline float get_pitch() { return _pitch; }
89 * Get the final volume value of this audio sample.
92 inline float get_volume() { return _volume * _master_volume; }
95 * Returns the size (in bytes) of this audio sample.
98 inline size_t get_size() const {
99 return (_samples * _tracks * _bits)/8;
104 * Get the absolute position of this sound.
105 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
106 * @return Absolute position
108 inline SGVec3d& get_position() { return _absolute_pos; }
111 * Get the orientation vector of this sound.
112 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right
113 * @return Orientaton vector
115 inline SGVec3f& get_orientation() { return _orivec; }
118 * Get the inner angle of the audio cone.
119 * @return Inner angle in degrees
121 inline float get_innerangle() { return _inner_angle; }
124 * Get the outer angle of the audio cone.
125 * @return Outer angle in degrees
127 inline float get_outerangle() { return _outer_angle; }
130 * Get the remaining gain at the edge of the outer cone.
133 inline float get_outergain() { return _outer_gain; }
136 * Get velocity vector (in meters per second) of this sound.
137 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right
138 * @return Velocity vector
140 inline SGVec3f& get_velocity() { return _velocity; }
143 * Get reference distance ((in meters) of this sound.
144 * This is the distance where the gain will be half.
145 * @return Reference distance
147 inline float get_reference_dist() { return _reference_dist; }
150 * Get maximum distance (in meters) of this sound.
151 * This is the distance where this sound is no longer audible.
152 * @return dist Maximum distance
154 inline float get_max_dist() { return _max_dist; }
157 * Test if static data of audio sample configuration has changed.
158 * Calling this function will reset the flag so calling it a second
159 * time in a row will return false.
160 * @return Return true is the static data has changed in the mean time.
162 bool has_static_data_changed() {
163 bool b = _static_changed; _static_changed = false; return b;
167 // static sound emitter info
168 std::string _refname;
170 unsigned int _tracks;
171 unsigned int _samples;
172 unsigned int _frequency;
176 // dynamic sound emitter info (non 3d)
177 bool _static_changed;
182 float _master_volume;
184 // dynamic sound emitter info (3d)
192 float _reference_dist;
195 SGPropertyNode_ptr _pos_prop[3];
196 SGVec3d _absolute_pos; // absolute position
197 SGVec3d _relative_pos; // position relative to the base position
198 SGVec3d _direction; // orientation offset
199 SGVec3f _velocity; // Velocity of the source sound.
201 // The position and orientation of this sound
202 SGQuatd _orientation; // base orientation
203 SGVec3f _orivec; // orientation vector
204 SGVec3d _base_pos; // base position
209 static std::string random_string();
213 class SGSoundSample : public SGSoundSampleInfo, public SGReferenced {
217 * Empty constructor, can be used to read data to the systems
218 * memory and not to the driver.
224 * @param file File name of sound
225 Buffer data is freed by the sample group
227 SGSoundSample(const char *file, const SGPath& currentDir);
231 * @param data Pointer to a memory buffer containing this audio sample data
232 The application may free the data by calling free_data(), otherwise it
233 will be resident until the class is destroyed. This pointer will be
234 set to NULL after calling this function.
235 * @param len Byte length of array
236 * @param freq Frequency of the provided data (bytes per second)
237 * @param format SimGear format id of the data
239 SGSoundSample( void** data, int len, int freq, int format=SG_SAMPLE_MONO8 );
240 SGSoundSample( const unsigned char** data, int len, int freq,
241 int format = SG_SAMPLE_MONO8 );
246 virtual ~SGSoundSample ();
249 * Test if this audio sample configuration has changed since the last call.
250 * Calling this function will reset the flag so calling it a second
251 * time in a row will return false.
252 * @return Return true is the configuration has changed in the mean time.
255 bool b = _changed; _changed = false; return b;
259 * Detect whether this audio sample holds the information of a sound file.
260 * @return Return true if this sample is to be constructed from a file.
262 inline bool is_file() const { return _is_file; }
264 SGPath file_path() const;
267 * Schedule this audio sample for playing. Actual playing will only start
268 * at the next call op SoundGroup::update()
269 * @param _loop Define whether this sound should be played in a loop.
271 void play( bool loop = false ) {
272 _playing = true; _loop = loop; _changed = true; _static_changed = true;
276 * Check if this audio sample is set to be continuous looping.
277 * @return Return true if this audio sample is set to looping.
279 inline bool is_looping() { return _loop; }
282 * Schedule this audio sample to stop playing.
284 virtual void stop() {
285 _playing = false; _changed = true;
289 * Schedule this audio sample to play once.
292 inline void play_once() { play(false); }
295 * Schedule this audio sample to play looped.
298 inline void play_looped() { play(true); }
301 * Test if a audio sample is scheduled for playing.
302 * @return true if this audio sample is playing, false otherwise.
304 inline bool is_playing() { return _playing; }
308 * Set this sample to out-of-range (or not) and
309 * Schedule this audio sample to stop (or start) playing.
311 inline void set_out_of_range(bool oor = true) {
312 _out_of_range = oor; _playing = (!oor && _loop); _changed = true;
316 * Test if this sample to out-of-range or not.
318 inline bool test_out_of_range() {
319 return _out_of_range;
323 * Set the data associated with this audio sample
324 * @param data Pointer to a memory block containg this audio sample data.
325 This pointer will be set to NULL after calling this function.
327 inline void set_data( const unsigned char **data ) {
328 _data = (unsigned char*)*data; *data = NULL;
330 inline void set_data( const void **data ) {
331 _data = (unsigned char*)*data; *data = NULL;
335 * Return the data associated with this audio sample.
336 * @return A pointer to this sound data of this audio sample.
338 inline void* get_data() const { return _data; }
341 * Free the data associated with this audio sample
346 * Set the source id of this source
347 * @param sid source-id
349 virtual void set_source(unsigned int sid) {
350 _source = sid; _valid_source = true; _changed = true;
354 * Get the source id of this source
357 virtual unsigned int get_source() { return _source; }
360 * Test if the source-id of this audio sample is usable.
361 * @return true if the source-id is valid
363 virtual bool is_valid_source() const { return _valid_source; }
366 * Set the source-id of this audio sample to invalid.
368 virtual void no_valid_source() { _valid_source = false; }
371 * Set the buffer-id of this source
372 * @param bid buffer-id
374 inline void set_buffer(unsigned int bid) {
375 _buffer = bid; _valid_buffer = true; _changed = true;
379 * Get the buffer-id of this source
382 inline unsigned int get_buffer() { return _buffer; }
385 * Test if the buffer-id of this audio sample is usable.
386 * @return true if the buffer-id is valid
388 inline bool is_valid_buffer() const { return _valid_buffer; }
391 * Set the buffer-id of this audio sample to invalid.
393 inline void no_valid_buffer() { _valid_buffer = false; }
396 * Set the playback pitch of this audio sample.
397 * Should be between 0.0 and 2.0 for maximum compatibility.
400 inline void set_pitch( float p ) {
401 if (p > 2.0) p = 2.0; else if (p < 0.01) p = 0.01;
402 _pitch = p; _changed = true;
406 * Set the master volume of this sample. Should be between 0.0 and 1.0.
407 * The final volume is calculated by multiplying the master and audio sample
411 inline void set_master_volume( float v ) {
412 if (v > 1.0) v = 1.0; else if (v < 0.0) v = 0.0;
413 _master_volume = v; _changed = true;
417 * Set the volume of this audio sample. Should be between 0.0 and 1.0.
418 * The final volume is calculated by multiplying the master and audio sample
422 inline void set_volume( float v ) {
423 if (v > 1.0) v = 1.0; else if (v < 0.0) v = 0.0;
424 _volume = v; _changed = true;
428 * Set the SimGear format of this audio sample.
429 * @param format SimGear format-id
431 inline void set_format( int fmt ) {
432 _tracks = fmt & 0x3; _bits = fmt & 0x1C; _compressed = fmt & 0x100;
436 * Set the frequency (in Herz) of this audio sample.
437 * @param freq Frequency
439 inline void set_frequency( int freq ) { _frequency = freq; }
442 * Sets the size (in bytes) of this audio sample.
443 * @param size Data size
445 inline void set_size( size_t size ) {
446 _samples = size*8/(_bits*_tracks);
448 inline void set_no_samples(size_t samples) { _samples = samples; }
451 * Set the position of this sound relative to the base position.
452 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
453 * @param pos Relative position of this sound
455 inline void set_relative_position( const SGVec3f& pos ) {
456 _relative_pos = toVec3d(pos); _changed = true;
460 * Set the base position in Cartesian coordinates
461 * @param pos position in Cartesian coordinates
463 inline void set_position( const SGVec3d& pos ) {
464 _base_pos = pos; _changed = true;
467 inline void set_position_properties(SGPropertyNode_ptr pos[3]) {
468 _pos_prop[0] = pos[0]; _pos_prop[1] = pos[1]; _pos_prop[2] = pos[2];
469 if (pos[0] || pos[1] || pos[2]) _use_pos_props = true;
474 * Set the orientation of this sound.
475 * @param ori Quaternation containing the orientation information
477 inline void set_orientation( const SGQuatd& ori ) {
478 _orientation = ori; _changed = true;
481 inline void set_rotation( const SGQuatd& ec2body ) {
482 _rotation = ec2body; _changed = true;
486 * Set direction of this sound relative to the orientation.
487 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right
488 * @param dir Sound emission direction
490 inline void set_direction( const SGVec3f& dir ) {
491 _direction = toVec3d(dir); _static_changed = true;
495 * Define the audio cone parameters for directional audio.
496 * Note: setting it to 2 degree will result in 1 degree to both sides.
497 * @param inner Inner cone angle (0 - 360 degrees)
498 * @param outer Outer cone angle (0 - 360 degrees)
499 * @param gain Remaining gain at the edge of the outer cone (0.0 - 1.0)
501 void set_audio_cone( float inner, float outer, float gain ) {
502 _inner_angle = inner; _outer_angle = outer; _outer_gain = gain;
503 _static_changed = true;
507 * Set the velocity vector (in meters per second) of this sound.
508 * This is in the local frame coordinate system; x=north, y=east, z=down
509 * @param Velocity vector
511 inline void set_velocity( const SGVec3f& vel ) {
512 _velocity = vel; _changed = true;
516 * Set reference distance (in meters) of this sound.
517 * This is the distance where the gain will be half.
518 * @param dist Reference distance
520 inline void set_reference_dist( float dist ) {
521 _reference_dist = dist; _static_changed = true;
525 * Set maximum distance (in meters) of this sound.
526 * This is the distance where this sound is no longer audible.
527 * @param dist Maximum distance
529 inline void set_max_dist( float dist ) {
530 _max_dist = dist; _static_changed = true;
533 inline virtual bool is_queue() const { return false; }
535 void update_pos_and_orientation();
541 // Sources are points emitting sound.
543 unsigned int _source;
546 unsigned char* _data;
548 // Buffers hold sound data.
550 unsigned int _buffer;
553 #endif // _SG_SAMPLE_HXX