code.vuplus.com Git - vuplus_xbmc/blob - xbmc/cores/AudioEngine/Interfaces/AE.h

   1 #pragma once
   2 /*
   3  *      Copyright (C) 2010-2013 Team XBMC
   4  *      http://xbmc.org
   5  *
   6  *  This Program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2, or (at your option)
   9  *  any later version.
  10  *
  11  *  This Program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with XBMC; see the file COPYING.  If not, see
  18  *  <http://www.gnu.org/licenses/>.
  19  *
  20  */
  21
  22 #include <list>
  23 #include <map>
  24
  25 #include "system.h"
  26 #include "threads/CriticalSection.h"
  27
  28 #include "cores/AudioEngine/Utils/AEAudioFormat.h"
  29
  30 typedef std::pair<std::string, std::string> AEDevice;
  31 typedef std::vector<AEDevice> AEDeviceList;
  32
  33 /* forward declarations */
  34 class IAEStream;
  35 class IAESound;
  36 class IAEPacketizer;
  37 class IAudioCallback;
  38
  39 /* sound options */
  40 #define AE_SOUND_OFF    0 /* disable sounds */
  41 #define AE_SOUND_IDLE   1 /* only play sounds while no streams are running */
  42 #define AE_SOUND_ALWAYS 2 /* always play sounds */
  43
  44 /* config options */
  45 #define AE_CONFIG_FIXED 1
  46 #define AE_CONFIG_AUTO  2
  47 #define AE_CONFIG_MATCH 3
  48
  49 enum AEQuality
  50 {
  51   AE_QUALITY_UNKNOWN    = -1, /* Unset, unknown or incorrect quality level */
  52   AE_QUALITY_DEFAULT    =  0, /* Engine's default quality level */
  53
  54   /* Basic quality levels */
  55   AE_QUALITY_LOW        = 20, /* Low quality level */
  56   AE_QUALITY_MID        = 30, /* Standard quality level */
  57   AE_QUALITY_HIGH       = 50, /* Best sound processing quality */
  58
  59   /* Optional quality levels */
  60   AE_QUALITY_REALLYHIGH = 100 /* Uncompromised optional quality level,
  61                                usually with unmeasurable and unnoticeable improvement */
  62 };
  63
  64 /**
  65  * IAE Interface
  66  */
  67 class IAE
  68 {
  69 protected:
  70   friend class CAEFactory;
  71
  72   IAE() {}
  73   virtual ~IAE() {}
  74
  75   /**
  76    * Returns true when it should be possible to initialize this engine, if it returns false
  77    * CAEFactory can possibly fall back to a different one
  78    */
  79   virtual bool CanInit() { return true; }
  80
  81   /**
  82    * Initializes the AudioEngine, called by CFactory when it is time to initialize the audio engine.
  83    * Do not call this directly, CApplication will call this when it is ready
  84    */
  85   virtual bool Initialize() = 0;
  86 public:
  87   /**
  88    * Called when the application needs to terminate the engine
  89    */
  90   virtual void Shutdown() { }
  91
  92   /**
  93    * Suspends output and de-initializes sink
  94    * Used to avoid conflicts with external players or to reduce power consumption
  95    * @return True if successful
  96    */
  97   virtual bool Suspend() = 0;
  98
  99   /**
 100    * Resumes output and re-initializes sink
 101    * Used to resume output from Suspend() state above
 102    * @return True if successful
 103    */
 104   virtual bool Resume() = 0;
 105
 106   /**
 107    * Get the current Suspend() state
 108    * Used by players to determine if audio is being processed
 109    * Default is true so players drop audio or pause if engine unloaded
 110    * @return True if processing suspended
 111    */
 112   virtual bool IsSuspended() {return true;}
 113
 114   /**
 115    * Callback to alert the AudioEngine of setting changes
 116    * @param setting The name of the setting that was changed
 117    */
 118   virtual void OnSettingsChange(const std::string& setting) {}
 119
 120   /**
 121    * Returns the current master volume level of the AudioEngine
 122    * @return The volume level between 0.0 and 1.0
 123    */
 124   virtual float GetVolume() = 0;
 125
 126   /**
 127    * Sets the master volume level of the AudioEngine
 128    * @param volume The new volume level between 0.0 and 1.0
 129    */
 130   virtual void SetVolume(const float volume) = 0;
 131
 132   /**
 133    * Set the mute state (does not affect volume level value)
 134    * @param enabled The mute state
 135    */
 136   virtual void SetMute(const bool enabled) = 0;
 137
 138   /**
 139    * Get the current mute state
 140    * @return The current mute state
 141    */
 142   virtual bool IsMuted() = 0;
 143
 144   /**
 145    * Sets the sound mode
 146    * @param mode One of AE_SOUND_OFF, AE_SOUND_IDLE or AE_SOUND_ALWAYS
 147    */
 148   virtual void SetSoundMode(const int mode) = 0;
 149
 150   /**
 151    * Creates and returns a new IAEStream in the format specified, this function should never fail
 152    * @param dataFormat The data format the incoming audio will be in (eg, AE_FMT_S16LE)
 153    * @param sampleRate The sample rate of the audio data (eg, 48000)
 154    * @prarm encodedSampleRate The sample rate of the encoded audio data if AE_IS_RAW(dataFormat)
 155    * @param channelLayout The order of the channels in the audio data
 156    * @param options A bit field of stream options (see: enum AEStreamOptions)
 157    * @return a new IAEStream that will accept data in the requested format
 158    */
 159   virtual IAEStream *MakeStream(enum AEDataFormat dataFormat, unsigned int sampleRate, unsigned int encodedSampleRate, CAEChannelInfo channelLayout, unsigned int options = 0) = 0;
 160
 161   /**
 162    * This method will remove the specifyed stream from the engine.
 163    * For OSX/IOS this is essential to reconfigure the audio output.
 164    * @param stream The stream to be altered
 165    * @return NULL
 166    */
 167   virtual IAEStream *FreeStream(IAEStream *stream) = 0;
 168
 169   /**
 170    * Creates a new IAESound that is ready to play the specified file
 171    * @param file The WAV file to load, this supports XBMC's VFS
 172    * @return A new IAESound if the file could be loaded, otherwise NULL
 173    */
 174   virtual IAESound *MakeSound(const std::string &file) = 0;
 175
 176   /**
 177    * Free the supplied IAESound object
 178    * @param sound The IAESound object to free
 179    */
 180   virtual void FreeSound(IAESound *sound) = 0;
 181
 182   /**
 183    * Callback by CApplication for Garbage Collection. This method is called by CApplication every 500ms and can be used to clean up and free no-longer used resources.
 184    */
 185   virtual void GarbageCollect() = 0;
 186
 187   /**
 188    * Enumerate the supported audio output devices
 189    * @param devices The device list to append supported devices to
 190    * @param passthrough True if only passthrough devices are wanted
 191    */
 192   virtual void EnumerateOutputDevices(AEDeviceList &devices, bool passthrough) = 0;
 193
 194   /**
 195    * Returns the default audio device
 196    * @param passthrough True if the default passthrough device is wanted
 197    * @return the default audio device
 198    */
 199   virtual std::string GetDefaultDevice(bool passthrough) { return "default"; }
 200
 201   /**
 202    * Returns true if the AudioEngine supports AE_FMT_RAW streams for use with formats such as IEC61937
 203    * @see CAEPackIEC61937::CAEPackIEC61937()
 204    * @returns true if the AudioEngine is capable of RAW output
 205    */
 206   virtual bool SupportsRaw(AEDataFormat format) { return false; }
 207
 208    /**
 209    * Returns true if the AudioEngine supports drain mode which is not streaming silence when idle
 210    * @returns true if the AudioEngine is capable of drain mode
 211    */
 212   virtual bool SupportsSilenceTimeout() { return false; }
 213
 214   virtual void RegisterAudioCallback(IAudioCallback* pCallback) {}
 215
 216   virtual void UnregisterAudioCallback() {}
 217
 218   /**
 219    * Returns true if AudioEngine supports specified quality level
 220    * @return true if specified quality level is supported, otherwise false
 221    */
 222   virtual bool SupportsQualityLevel(enum AEQuality level) { return false; }
 223
 224   /**
 225    * AE decides whether this settings should be displayed
 226    * @return true if AudioEngine wants to display this setting
 227    */
 228   virtual bool IsSettingVisible(const std::string &settingId) {return false; }
 229
 230   /**
 231    * Instruct AE to keep configuration for a specified time
 232    * @param millis time for which old configuration should be kept
 233    */
 234   virtual void KeepConfiguration(unsigned int millis) {return; }
 235 };
 236