OSDLAudio.h

Go to the documentation of this file.

/* 
 * Copyright (C) 2003-2009 Olivier Boudeville
 *
 * This file is part of the OSDL library.
 *
 * The OSDL library is free software: you can redistribute it and/or modify
 * it under the terms of either the GNU Lesser General Public License or
 * the GNU General Public License, as they are published by the Free Software
 * Foundation, either version 3 of these Licenses, or (at your option) 
 * any later version.
 *
 * The OSDL library 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 Lesser General Public License and the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License and of the GNU General Public License along with the OSDL library.
 * If not, see <http://www.gnu.org/licenses/>.
 *
 * Author: Olivier Boudeville (olivier.boudeville@esperide.com)
 *
 */


#ifndef OSDL_AUDIO_H_
#define OSDL_AUDIO_H_


#include "OSDLAudioCommon.h" // for AudioException, etc.
#include "OSDLMusic.h"       // for MusicType, etc.

#include "Ceylan.h"          // for inheritance, Hertz

#include <string>
#include <vector>




namespace OSDL
{

    
    
    // Manager of the audio module.
    class CommonModule ;
        
    
    
    namespace Audio 
    {
            
            
        
        // The audio module uses channels to mix input sources.
        class AudioChannel ;
                    
    
    
        std::string sampleFormatToString( SampleFormat format ) ;
            
            
    
        std::string channelFormatToString( ChannelFormat format ) ;

    
    
                                
        class OSDL_DLL AudioModule : public Ceylan::Module
        {
        
        
        
            // The common module has to create the audio module.
            friend class OSDL::CommonModule ;
        
            
        
            OSDL_DLL friend AudioModule & getExistingAudioModule() ;
        
        
        
            public:



                /*
                 * Sample format section.
                 *
                 * Unless specified otherwise, sample formats are PCM-based.
                 *
                 */
                
                
                static const SampleFormat Uint8SampleFormat ;
                
                
                static const SampleFormat Sint8SampleFormat ;
                

                
                static const SampleFormat LittleUint16SampleFormat ;


                static const SampleFormat LittleSint16SampleFormat ;



                static const SampleFormat BigUint16SampleFormat ;
            
            
                static const SampleFormat BigSint16SampleFormat ;
            
            
            
                static const SampleFormat NativeUint16SampleFormat ;
            
            
                static const SampleFormat NativeSint16SampleFormat ;
            
            
            
                static const SampleFormat IMAADPCMSampleFormat ;
            




                // Channel format section.
                
            
            
                static const ChannelFormat Mono ;


                static const ChannelFormat Stereo ;
                
                

                static const Volume MinVolume ;
                
                
                static const Volume MaxVolume ;



                typedef Ceylan::Uint16 ChannelNumber ;
                
                
                                
                virtual void setMode( 
                    Ceylan::Maths::Hertz outputFrequency,
                    SampleFormat         outputSampleFormat,
                    ChannelFormat        outputChannel,
                    ChunkSize            outputBufferSize,
                    ChannelNumber        mixingChannelNumber = 16 ) ;



                virtual Ceylan::System::Millisecond getObtainedMode( 
                    Ceylan::Maths::Hertz & actualOutputFrequency,
                    SampleFormat & actualOutputSampleFormat,
                    ChannelNumber & actualOutputChannelNumber ) ;
                 
                 
                 
                virtual void unsetMode() ; 


                    
                virtual void setPanning( 
                    Ceylan::Maths::Percentage leftPercentage ) ;
                    
                    
                    
                virtual void unsetPanning() ;



                virtual void setReverseStereo( bool reverse = true ) ;
                    

                    
                virtual void setDistanceAttenuation( 
                    ListenerDistance distance ) ;
                    
                
                    
                virtual void unsetDistanceAttenuation() ;



                virtual void setPositionAttenuation( ListenerDistance distance,
                    ListenerAngle angle ) ;
                    
                    
                    
                virtual void unsetPositionAttenuation() ;



                    
                virtual bool isGUIEnabled() const ;
                
                    
                
                virtual void setGUIEnableStatus( bool newStatus ) ;
                



                // Channel section.



                virtual ChannelNumber getMixingChannelCount() const ; 



                virtual AudioChannel & getMixingChannelAt( ChannelNumber index )
                    const ; 



                virtual void setVolumeForAllMixingChannels( Volume newVolume ) ;
                    
                
                
                virtual ChannelNumber getPlayingChannelCount() const ;
                    
                    
                    
                virtual ChannelNumber getPausedChannelCount() const  ;
                    
                    
                    
                virtual void pauseAllChannels() ;
                    
                    
                    
                virtual void resumeAllChannels() ;
                    
                    
                    
                virtual void haltAllChannels() ;
                    
                    
                    
                virtual ChannelNumber expireAllChannelsIn( 
                    Ceylan::System::Millisecond expireDuration ) ;
        
        
        
                virtual ChannelNumber fadeOutAllChannelsDuring( 
                    Ceylan::System::Millisecond fadeOutDuration ) ;
        
                    
                    
                    
                
                // Music section.
                
                
                
                virtual MusicType getTypeOfCurrentMusic() const ;
                    
                    
                
                virtual bool isMusicPlaying() const ;



                virtual bool isMusicPaused() const ;



                virtual FadingStatus getMusicFadingStatus() const ;
                
                
                
                virtual std::string getDriverName() const ; 
        
        
            
                virtual const std::string toString( 
                    Ceylan::VerbosityLevels level = Ceylan::high ) const ;
            
            
            
            
                
                // Static section.
                
                    
                    
                    
                // Audio locator section.
            
            

                static std::string AudioPathEnvironmentVariable ;
                 
                 
                 
                static Ceylan::System::FileLocator AudioFileLocator ;
                
                
                
                static std::string DescribeEnvironmentVariables() ; 
                    
                
                
                static bool IsAudioInitialized() ;
                    


                static std::string GetDriverName() ;
                
                
                
                static const Ceylan::Uint16 DriverNameMaximumLength ;
                
                
                    
                    
            protected:
    
                
                
                bool _mixerInitialized ;
                
                
                ChunkSize _chunkSize ;
                
                
                bool _controlMusicManager ;
                
                
/* 
 * Takes care of the awful issue of Windows DLL with templates.
 *
 * @see Ceylan's developer guide and README-build-for-windows.txt 
 * to understand it, and to be aware of the associated risks. 
 * 
 */
#pragma warning( push )
#pragma warning( disable: 4251 )
            

                std::vector<AudioChannel *> _inputChannels ;                
                
#pragma warning( pop ) 
                
                
                bool _isGuiEnabled ;

                
                virtual void onMusicPlaybackFinished() ;
            
                    
                
                static ChannelNumber GetChannelCountFor( ChannelFormat format );
    
    
    
                static ChunkSize GetSampleSizeFor( SampleFormat format ) ;
    


                static bool _AudioInitialized ;




            private:



                static void HandleMusicPlaybackFinishedCallback() ;


    
                AudioModule() ;



                virtual ~AudioModule() throw() ;
    
    
    
                explicit AudioModule( const AudioModule & source ) ;
            
            
            
                AudioModule & operator = ( const AudioModule & source ) ;
    


        
                static const std::string SDLEnvironmentVariables[] ;
                            
                            
                // Common module must be able to create the audio module.       
                friend class CommonModule ;
            
            
            
        } ;

    
    
    
        OSDL_DLL AudioModule & getExistingAudioModule() ;
        
        
        
    }   
    
    
}   



#endif // OSDL_AUDIO_H_

---