code.vuplus.com Git - vuplus_xbmc/blob - xbmc/cores/AudioEngine/Interfaces/AEStream.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 "../AEAudioFormat.h"
  23 #include "cores/IAudioCallback.h"
  24 #include <stdint.h>
  25
  26 /**
  27  * Bit options to pass to IAE::GetStream
  28  */
  29 enum AEStreamOptions {
  30   AESTREAM_FORCE_RESAMPLE = 0x01, /* force resample even if rates match */
  31   AESTREAM_PAUSED         = 0x02, /* create the stream paused */
  32   AESTREAM_AUTOSTART      = 0x04  /* autostart the stream when enough data is buffered */
  33 };
  34
  35 /**
  36  * IAEStream Stream Interface for streaming audio
  37  */
  38 class IAEStream
  39 {
  40 protected:
  41   friend class IAE;
  42   IAEStream() {}
  43   virtual ~IAEStream() {}
  44
  45 public:
  46   /**
  47    * Returns the amount of space available in the stream
  48    * @return The number of bytes AddData will consume
  49    */
  50   virtual unsigned int GetSpace() = 0;
  51
  52   /**
  53    * Add interleaved PCM data to the stream
  54    * @param data The interleaved PCM data
  55    * @param size The size in bytes of data, if this is > GetSpace() only up to GetSpace() bytes will be consumed
  56    * @return The number of bytes consumed
  57    */
  58   virtual unsigned int AddData(void *data, unsigned int size) = 0;
  59
  60   /**
  61    * Returns the time in seconds that it will take
  62    * for the next added packet to be heard from the speakers.
  63    * @return seconds
  64    */
  65   virtual double GetDelay() = 0;
  66
  67   /**
  68    * Returns if the stream is buffering
  69    * @return True if the stream is buffering
  70    */
  71   virtual bool IsBuffering() = 0;
  72
  73   /**
  74    * Returns the time in seconds that it will take
  75    * to underrun the cache if no sample is added.
  76    * @return seconds
  77    */
  78   virtual double GetCacheTime() = 0;
  79
  80   /**
  81    * Returns the total time in seconds of the cache
  82    * @return seconds
  83    */
  84   virtual double GetCacheTotal() = 0;
  85
  86   /**
  87    * Pauses the stream playback
  88    */
  89   virtual void Pause() = 0;
  90
  91   /**
  92    * Resumes the stream after pausing
  93    */
  94   virtual void Resume() = 0;
  95
  96   /**
  97    * Start draining the stream
  98    * @note Once called AddData will not consume more data.
  99    */
 100   virtual void Drain() = 0;
 101
 102   /**
 103    * Returns true if the is stream draining
 104    */
 105   virtual bool IsDraining() = 0;
 106
 107   /**
 108    * Returns true if the is stream has finished draining
 109    */
 110   virtual bool IsDrained() = 0;
 111
 112   /**
 113    * Flush all buffers dropping the audio data
 114    */
 115   virtual void Flush() = 0;
 116
 117   /**
 118    * Return the stream's current volume level
 119    * @return The volume level between 0.0 and 1.0
 120    */
 121   virtual float GetVolume() = 0;
 122
 123   /**
 124    * Set the stream's volume level
 125    * @param volume The new volume level between 0.0 and 1.0
 126    */
 127   virtual void  SetVolume(float volume) = 0;
 128
 129   /**
 130    * Returns the stream's current replay gain factor
 131    * @return The replay gain factor between 0.0 and 1.0
 132    */
 133   virtual float GetReplayGain() = 0;
 134
 135   /**
 136    * Sets the stream's replay gain factor, this is used by formats such as MP3 that have attenuation information in their streams
 137    * @param factor The replay gain factor
 138    */
 139   virtual void SetReplayGain(float factor) = 0;
 140
 141   /**
 142    * Gets the stream's volume amplification in linear units.
 143    * @return The volume amplification factor between 1.0 and 1000.0
 144    */
 145   virtual float GetAmplification() = 0;
 146
 147   /**
 148    * Sets the stream's volume amplification in linear units.
 149    * @param The volume amplification factor between 1.0 and 1000.0
 150    */
 151   virtual void SetAmplification(float amplify) = 0;
 152
 153   /**
 154    * Returns the size of one audio frame in bytes (channelCount * resolution)
 155    * @return The size in bytes of one frame
 156   */
 157   virtual const unsigned int GetFrameSize() const = 0;
 158
 159   /**
 160    * Returns the number of channels the stream is configured to accept
 161    * @return The channel count
 162    */
 163   virtual const unsigned int GetChannelCount() const = 0;
 164
 165   /**
 166    * Returns the stream's sample rate, if the stream is using a dynamic sample rate, this value will NOT reflect any changes made by calls to SetResampleRatio()
 167    * @return The stream's sample rate (eg, 48000)
 168    */
 169   virtual const unsigned int GetSampleRate() const = 0;
 170
 171   /**
 172    * Returns the stream's encoded sample rate if the stream is RAW
 173    * @return The stream's encoded sample rate
 174    */
 175   virtual const unsigned int GetEncodedSampleRate() const = 0;
 176
 177   /**
 178    * Return the data format the stream has been configured with
 179    * @return The stream's data format (eg, AE_FMT_S16LE)
 180    */
 181   virtual const enum AEDataFormat GetDataFormat() const = 0;
 182
 183   /**
 184    * Return the resample ratio
 185    * @note This will return an undefined value if the stream is not resampling
 186    * @return the current resample ratio or undefined if the stream is not resampling
 187    */
 188   virtual double GetResampleRatio() = 0;
 189
 190   /**
 191    * Sets the resample ratio
 192    * @note This function may return false if the stream is not resampling, if you wish to use this be sure to set the AESTREAM_FORCE_RESAMPLE option
 193    * @param ratio the new sample rate ratio, calculated by ((double)desiredRate / (double)GetSampleRate())
 194    */
 195   virtual bool SetResampleRatio(double ratio) = 0;
 196
 197   /**
 198    * Registers the audio callback to call with each block of data, this is used by Audio Visualizations
 199    * @warning Currently the callbacks require stereo float data in blocks of 512 samples, any deviation from this may crash XBMC, or cause junk to be rendered
 200    * @param pCallback The callback
 201    */
 202   virtual void RegisterAudioCallback(IAudioCallback* pCallback) = 0;
 203
 204   /**
 205    * Unregisters the current audio callback
 206    */
 207   virtual void UnRegisterAudioCallback() = 0;
 208
 209   /**
 210     * Fade the volume level over the specified time
 211     * @param from The volume level to fade from (0.0f-1.0f) - See notes
 212     * @param target The volume level to fade to (0.0f-1.0f)
 213     * @param time The amount of time in milliseconds for the fade to occur
 214     * @note The from parameter does not set the streams volume, it is only used to calculate the fade time properly
 215     */
 216   virtual void FadeVolume(float from, float target, unsigned int time) {} /* FIXME: once all the engines have these new methods */
 217
 218   /**
 219    * Returns if a fade is still running
 220    * @return true if a fade is in progress, otherwise false
 221    */
 222   virtual bool IsFading() { return false; }
 223
 224   /**
 225    * Slave a stream to resume when this stream has drained
 226    */
 227   virtual void RegisterSlave(IAEStream *stream) = 0;
 228 };
 229