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/props/props.hxx>
41 SG_SAMPLE_16BITS = 16,
43 SG_SAMPLE_UNCOMPRESSED = 0,
44 SG_SAMPLE_COMPRESSED = 256,
46 SG_SAMPLE_MONO8 = (SG_SAMPLE_MONO|SG_SAMPLE_8BITS),
47 SG_SAMPLE_MONO16 = (SG_SAMPLE_MONO|SG_SAMPLE_16BITS),
48 SG_SAMPLE_MULAW = (SG_SAMPLE_MONO|SG_SAMPLE_8BITS|SG_SAMPLE_COMPRESSED),
49 SG_SAMPLE_ADPCM = (SG_SAMPLE_MONO|SG_SAMPLE_4BITS|SG_SAMPLE_COMPRESSED)
54 * manages everything we need to know for an individual audio sample
57 class SGSoundSampleInfo
61 ~SGSoundSampleInfo() {}
64 * Returns the format of this audio sample.
65 * @return SimGear format-id
67 unsigned int get_format_AL();
70 * Returns the format of this audio sample.
71 * @return SimGear format-id
73 inline unsigned int get_format() { return (_tracks | _bits | _compressed*256); }
76 * Get the reference name of this audio sample.
79 inline std::string get_sample_name() const { return _refname; }
82 * Returns the frequency (in Herz) of this audio sample.
85 inline unsigned int get_frequency() { return _frequency; }
88 * Get the current pitch value of this audio sample.
91 inline float get_pitch() { return _pitch; }
94 * Get the final volume value of this audio sample.
97 inline float get_volume() { return _volume * _master_volume; }
100 * Returns the size (in bytes) of this audio sample.
103 inline size_t get_size() const {
104 return (_samples * _tracks * _bits)/8;
109 * Get the absolute position of this sound.
110 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
111 * @return Absolute position
113 inline SGVec3d& get_position() { return _absolute_pos; }
116 * Get the orientation vector of this sound.
117 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right
118 * @return Orientaton vector
120 inline SGVec3f& get_orientation() { return _orivec; }
123 * Get the inner angle of the audio cone.
124 * @return Inner angle in degrees
126 inline float get_innerangle() { return _inner_angle; }
129 * Get the outer angle of the audio cone.
130 * @return Outer angle in degrees
132 inline float get_outerangle() { return _outer_angle; }
135 * Get the remaining gain at the edge of the outer cone.
138 inline float get_outergain() { return _outer_gain; }
141 * Get velocity vector (in meters per second) of this sound.
142 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right
143 * @return Velocity vector
145 inline SGVec3f& get_velocity() { return _velocity; }
148 * Get reference distance ((in meters) of this sound.
149 * This is the distance where the gain will be half.
150 * @return Reference distance
152 inline float get_reference_dist() { return _reference_dist; }
155 * Get maximum distance (in meters) of this sound.
156 * This is the distance where this sound is no longer audible.
157 * @return dist Maximum distance
159 inline float get_max_dist() { return _max_dist; }
162 * Test if static data of audio sample configuration has changed.
163 * Calling this function will reset the flag so calling it a second
164 * time in a row will return false.
165 * @return Return true is the static data has changed in the mean time.
167 bool has_static_data_changed() {
168 bool b = _static_changed; _static_changed = false; return b;
172 // static sound emitter info
173 std::string _refname;
175 unsigned int _tracks;
176 unsigned int _samples;
177 unsigned int _frequency;
181 // dynamic sound emitter info (non 3d)
182 bool _static_changed;
187 float _master_volume;
189 // dynamic sound emitter info (3d)
197 float _reference_dist;
200 SGPropertyNode_ptr _pos_prop[3];
201 SGVec3d _absolute_pos; // absolute position
202 SGVec3d _relative_pos; // position relative to the base position
203 SGVec3d _direction; // orientation offset
204 SGVec3f _velocity; // Velocity of the source sound.
206 // The position and orientation of this sound
207 SGQuatd _orientation; // base orientation
208 SGVec3f _orivec; // orientation vector
209 SGVec3d _base_pos; // base position
214 static std::string random_string();
218 class SGSoundSample : public SGSoundSampleInfo, public SGReferenced {
222 * Empty constructor, can be used to read data to the systems
223 * memory and not to the driver.
229 * @param file File name of sound
230 Buffer data is freed by the sample group
232 SGSoundSample(const char *file, const SGPath& currentDir);
236 * @param data Pointer to a memory buffer containing this audio sample data
237 The application may free the data by calling free_data(), otherwise it
238 will be resident until the class is destroyed. This pointer will be
239 set to NULL after calling this function.
240 * @param len Byte length of array
241 * @param freq Frequency of the provided data (bytes per second)
242 * @param format SimGear format id of the data
244 SGSoundSample( void** data, int len, int freq, int format=SG_SAMPLE_MONO8 );
245 SGSoundSample( const unsigned char** data, int len, int freq,
246 int format = SG_SAMPLE_MONO8 );
251 virtual ~SGSoundSample ();
254 * Test if this audio sample configuration has changed since the last call.
255 * Calling this function will reset the flag so calling it a second
256 * time in a row will return false.
257 * @return Return true is the configuration has changed in the mean time.
260 bool b = _changed; _changed = false; return b;
264 * Detect whether this audio sample holds the information of a sound file.
265 * @return Return true if this sample is to be constructed from a file.
267 inline bool is_file() const { return _is_file; }
269 SGPath file_path() const;
272 * Schedule this audio sample for playing. Actual playing will only start
273 * at the next call op SoundGroup::update()
274 * @param _loop Define whether this sound should be played in a loop.
276 void play( bool loop = false ) {
277 _playing = true; _loop = loop; _changed = true; _static_changed = true;
281 * Check if this audio sample is set to be continuous looping.
282 * @return Return true if this audio sample is set to looping.
284 inline bool is_looping() { return _loop; }
287 * Schedule this audio sample to stop playing.
289 virtual void stop() {
290 _playing = false; _changed = true;
294 * Schedule this audio sample to play once.
297 inline void play_once() { play(false); }
300 * Schedule this audio sample to play looped.
303 inline void play_looped() { play(true); }
306 * Test if a audio sample is scheduled for playing.
307 * @return true if this audio sample is playing, false otherwise.
309 inline bool is_playing() { return _playing; }
313 * Set this sample to out-of-range (or not) and
314 * Schedule this audio sample to stop (or start) playing.
316 inline void set_out_of_range(bool oor = true) {
317 _out_of_range = oor; _playing = (!oor && _loop); _changed = true;
321 * Test if this sample to out-of-range or not.
323 inline bool test_out_of_range() {
324 return _out_of_range;
328 * Set the data associated with this audio sample
329 * @param data Pointer to a memory block containg this audio sample data.
330 This pointer will be set to NULL after calling this function.
332 inline void set_data( const unsigned char **data ) {
333 _data = (unsigned char*)*data; *data = NULL;
335 inline void set_data( const void **data ) {
336 _data = (unsigned char*)*data; *data = NULL;
340 * Return the data associated with this audio sample.
341 * @return A pointer to this sound data of this audio sample.
343 inline void* get_data() const { return _data; }
346 * Free the data associated with this audio sample
351 * Set the source id of this source
352 * @param sid source-id
354 virtual void set_source(unsigned int sid) {
355 _source = sid; _valid_source = true; _changed = true;
359 * Get the source id of this source
362 virtual unsigned int get_source() { return _source; }
365 * Test if the source-id of this audio sample is usable.
366 * @return true if the source-id is valid
368 virtual bool is_valid_source() const { return _valid_source; }
371 * Set the source-id of this audio sample to invalid.
373 virtual void no_valid_source() { _valid_source = false; }
376 * Set the buffer-id of this source
377 * @param bid buffer-id
379 inline void set_buffer(unsigned int bid) {
380 _buffer = bid; _valid_buffer = true; _changed = true;
384 * Get the buffer-id of this source
387 inline unsigned int get_buffer() { return _buffer; }
390 * Test if the buffer-id of this audio sample is usable.
391 * @return true if the buffer-id is valid
393 inline bool is_valid_buffer() const { return _valid_buffer; }
396 * Set the buffer-id of this audio sample to invalid.
398 inline void no_valid_buffer() { _valid_buffer = false; }
401 * Set the playback pitch of this audio sample.
402 * Should be between 0.0 and 2.0 for maximum compatibility.
405 inline void set_pitch( float p ) {
406 if (p > 2.0) p = 2.0; else if (p < 0.01) p = 0.01;
407 _pitch = p; _changed = true;
411 * Set the master volume of this sample. Should be between 0.0 and 1.0.
412 * The final volume is calculated by multiplying the master and audio sample
416 inline void set_master_volume( float v ) {
417 if (v > 1.0) v = 1.0; else if (v < 0.0) v = 0.0;
418 _master_volume = v; _changed = true;
422 * Set the volume of this audio sample. Should be between 0.0 and 1.0.
423 * The final volume is calculated by multiplying the master and audio sample
427 inline void set_volume( float v ) {
428 if (v > 1.0) v = 1.0; else if (v < 0.0) v = 0.0;
429 _volume = v; _changed = true;
433 * Set the SimGear format of this audio sample.
434 * @param format SimGear format-id
436 inline void set_format( int fmt ) {
437 _tracks = fmt & 0x3; _bits = fmt & 0x1C; _compressed = fmt & 0x100;
440 void set_format_AL( int fmt );
443 * Set the frequency (in Herz) of this audio sample.
444 * @param freq Frequency
446 inline void set_frequency( int freq ) { _frequency = freq; }
449 * Sets the size (in bytes) of this audio sample.
450 * @param size Data size
452 inline void set_size( size_t size ) {
453 _samples = size*8/(_bits*_tracks);
455 inline void set_no_samples(size_t samples) { _samples = samples; }
458 * Set the position of this sound relative to the base position.
459 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
460 * @param pos Relative position of this sound
462 inline void set_relative_position( const SGVec3f& pos ) {
463 _relative_pos = toVec3d(pos); _changed = true;
467 * Set the base position in Cartesian coordinates
468 * @param pos position in Cartesian coordinates
470 inline void set_position( const SGVec3d& pos ) {
471 _base_pos = pos; _changed = true;
474 inline void set_position_properties(SGPropertyNode_ptr pos[3]) {
475 _pos_prop[0] = pos[0]; _pos_prop[1] = pos[1]; _pos_prop[2] = pos[2];
476 if (pos[0] || pos[1] || pos[2]) _use_pos_props = true;
481 * Set the orientation of this sound.
482 * @param ori Quaternation containing the orientation information
484 inline void set_orientation( const SGQuatd& ori ) {
485 _orientation = ori; _changed = true;
488 inline void set_rotation( const SGQuatd& ec2body ) {
489 _rotation = ec2body; _changed = true;
493 * Set direction of this sound relative to the orientation.
494 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right
495 * @param dir Sound emission direction
497 inline void set_direction( const SGVec3f& dir ) {
498 _direction = toVec3d(dir); _static_changed = true;
502 * Define the audio cone parameters for directional audio.
503 * Note: setting it to 2 degree will result in 1 degree to both sides.
504 * @param inner Inner cone angle (0 - 360 degrees)
505 * @param outer Outer cone angle (0 - 360 degrees)
506 * @param gain Remaining gain at the edge of the outer cone (0.0 - 1.0)
508 void set_audio_cone( float inner, float outer, float gain ) {
509 _inner_angle = inner; _outer_angle = outer; _outer_gain = gain;
510 _static_changed = true;
514 * Set the velocity vector (in meters per second) of this sound.
515 * This is in the local frame coordinate system; x=north, y=east, z=down
516 * @param Velocity vector
518 inline void set_velocity( const SGVec3f& vel ) {
519 _velocity = vel; _changed = true;
523 * Set reference distance (in meters) of this sound.
524 * This is the distance where the gain will be half.
525 * @param dist Reference distance
527 inline void set_reference_dist( float dist ) {
528 _reference_dist = dist; _static_changed = true;
532 * Set maximum distance (in meters) of this sound.
533 * This is the distance where this sound is no longer audible.
534 * @param dist Maximum distance
536 inline void set_max_dist( float dist ) {
537 _max_dist = dist; _static_changed = true;
540 inline virtual bool is_queue() const { return false; }
542 void update_pos_and_orientation();
548 // Sources are points emitting sound.
550 unsigned int _source;
553 unsigned char* _data;
555 // Buffers hold sound data.
557 unsigned int _buffer;
560 #endif // _SG_SAMPLE_HXX