media/base/audio_bus.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_BASE_AUDIO_BUS_H_
   6 #define MEDIA_BASE_AUDIO_BUS_H_
   7
   8 #include <vector>
   9
  10 #include "base/memory/aligned_memory.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "base/memory/scoped_ptr.h"
  13 #include "media/base/media_export.h"
  14
  15 namespace media {
  16 class AudioParameters;
  17
  18 // Scoped container for "busing" audio channel data around.  Each channel is
  19 // stored in planar format and guaranteed to be aligned by kChannelAlignment.
  20 // AudioBus objects can be created normally or via wrapping.  Normally, AudioBus
  21 // will dice up a contiguous memory block for channel data.  When wrapped,
  22 // AudioBus instead routes requests for channel data to the wrapped object.
  23 class MEDIA_EXPORT AudioBus {
  24  public:
  25   // Guaranteed alignment of each channel's data; use 16-byte alignment for easy
  26   // SSE optimizations.
  27   enum { kChannelAlignment = 16 };
  28
  29   // Creates a new AudioBus and allocates |channels| of length |frames|.  Uses
  30   // channels() and frames_per_buffer() from AudioParameters if given.
  31   static scoped_ptr<AudioBus> Create(int channels, int frames);
  32   static scoped_ptr<AudioBus> Create(const AudioParameters& params);
  33
  34   // Creates a new AudioBus with the given number of channels, but zero length.
  35   // It's expected to be used with SetChannelData() and set_frames() to
  36   // wrap externally allocated memory.
  37   static scoped_ptr<AudioBus> CreateWrapper(int channels);
  38
  39   // Creates a new AudioBus from an existing channel vector.  Does not transfer
  40   // ownership of |channel_data| to AudioBus; i.e., |channel_data| must outlive
  41   // the returned AudioBus.  Each channel must be aligned by kChannelAlignment.
  42   static scoped_ptr<AudioBus> WrapVector(
  43       int frames, const std::vector<float*>& channel_data);
  44
  45   // Creates a new AudioBus by wrapping an existing block of memory.  Block must
  46   // be at least CalculateMemorySize() bytes in size.  |data| must outlive the
  47   // returned AudioBus.  |data| must be aligned by kChannelAlignment.
  48   static scoped_ptr<AudioBus> WrapMemory(int channels, int frames, void* data);
  49   static scoped_ptr<AudioBus> WrapMemory(const AudioParameters& params,
  50                                          void* data);
  51   static int CalculateMemorySize(const AudioParameters& params);
  52
  53   // Calculates the required size for an AudioBus given the number of channels
  54   // and frames.
  55   static int CalculateMemorySize(int channels, int frames);
  56
  57   // Helper methods for converting an AudioBus from and to interleaved integer
  58   // data.  Expects interleaving to be [ch0, ch1, ..., chN, ch0, ch1, ...] with
  59   // |bytes_per_sample| per value.  Values are scaled and bias corrected during
  60   // conversion.  ToInterleaved() will also clip values to format range.
  61   // Handles uint8, int16, and int32 currently.  FromInterleaved() will zero out
  62   // any unfilled frames when |frames| is less than frames().
  63   void FromInterleaved(const void* source, int frames, int bytes_per_sample);
  64   void ToInterleaved(int frames, int bytes_per_sample, void* dest) const;
  65   void ToInterleavedPartial(int start_frame, int frames, int bytes_per_sample,
  66                             void* dest) const;
  67
  68   // Similar to FromInterleaved() above, but meant for streaming sources.  Does
  69   // not zero out remaining frames, the caller is responsible for doing so using
  70   // ZeroFramesPartial().  Frames are deinterleaved from the start of |source|
  71   // to channel(x)[start_frame].
  72   void FromInterleavedPartial(const void* source, int start_frame, int frames,
  73                               int bytes_per_sample);
  74
  75   // Helper method for copying channel data from one AudioBus to another.  Both
  76   // AudioBus object must have the same frames() and channels().
  77   void CopyTo(AudioBus* dest) const;
  78
  79   // Helper method to copy frames from one AudioBus to another. Both AudioBus
  80   // objects must have the same number of channels(). |source_start_frame| is
  81   // the starting offset. |dest_start_frame| is the starting offset in |dest|.
  82   // |frame_count| is the number of frames to copy.
  83   void CopyPartialFramesTo(int source_start_frame,
  84                            int frame_count,
  85                            int dest_start_frame,
  86                            AudioBus* dest) const;
  87
  88   // Returns a raw pointer to the requested channel.  Pointer is guaranteed to
  89   // have a 16-byte alignment.  Warning: Do not rely on having sane (i.e. not
  90   // inf, nan, or between [-1.0, 1.0]) values in the channel data.
  91   float* channel(int channel) { return channel_data_[channel]; }
  92   const float* channel(int channel) const { return channel_data_[channel]; }
  93   void SetChannelData(int channel, float* data);
  94
  95   int channels() const { return static_cast<int>(channel_data_.size()); }
  96   int frames() const { return frames_; }
  97   void set_frames(int frames);
  98
  99   // Helper method for zeroing out all channels of audio data.
 100   void Zero();
 101   void ZeroFrames(int frames);
 102   void ZeroFramesPartial(int start_frame, int frames);
 103
 104   // Checks if all frames are zero.
 105   bool AreFramesZero() const;
 106
 107   // Scale internal channel values by |volume| >= 0.  If an invalid value
 108   // is provided, no adjustment is done.
 109   void Scale(float volume);
 110
 111   // Swaps channels identified by |a| and |b|.  The caller needs to make sure
 112   // the channels are valid.
 113   void SwapChannels(int a, int b);
 114
 115   virtual ~AudioBus();
 116
 117  protected:
 118   AudioBus(int channels, int frames);
 119   AudioBus(int channels, int frames, float* data);
 120   AudioBus(int frames, const std::vector<float*>& channel_data);
 121   explicit AudioBus(int channels);
 122
 123  private:
 124   // Helper method for building |channel_data_| from a block of memory.  |data|
 125   // must be at least BlockSize() bytes in size.
 126   void BuildChannelData(int channels, int aligned_frame, float* data);
 127
 128   // Contiguous block of channel memory.
 129   scoped_ptr<float, base::AlignedFreeDeleter> data_;
 130
 131   std::vector<float*> channel_data_;
 132   int frames_;
 133
 134   // Protect SetChannelData() and set_frames() for use by CreateWrapper().
 135   bool can_set_channel_data_;
 136
 137   DISALLOW_COPY_AND_ASSIGN(AudioBus);
 138 };
 139
 140 // RefCounted version of AudioBus. This is not meant for general use. Only use
 141 // this when your lifetime requirements make it impossible to use an
 142 // AudioBus scoped_ptr.
 143 class MEDIA_EXPORT AudioBusRefCounted
 144     : public media::AudioBus,
 145       public base::RefCountedThreadSafe<AudioBusRefCounted> {
 146  public:
 147   static scoped_refptr<AudioBusRefCounted> Create(int channels, int frames);
 148
 149  private:
 150   friend class base::RefCountedThreadSafe<AudioBusRefCounted>;
 151
 152   AudioBusRefCounted(int channels, int frames);
 153   ~AudioBusRefCounted() override;
 154
 155   DISALLOW_COPY_AND_ASSIGN(AudioBusRefCounted);
 156 };
 157
 158 }  // namespace media
 159
 160 #endif  // MEDIA_BASE_AUDIO_BUS_H_