Upgrade AudioBus to support wrapping, interleaving.

media/base/audio_bus.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef MEDIA_BASE_AUDIO_BUS_H_
 #define MEDIA_BASE_AUDIO_BUS_H_
 
 #include <vector>
 
 #include "base/memory/aligned_memory.h"
 #include "base/memory/scoped_ptr.h"
 #include "media/base/media_export.h"
 
 namespace media {
 class AudioParameters;
 
 // Scoped container for "busing" audio channel data around.  Each channel is
 // stored in planar format and guaranteed to have a 16-byte alignment.  AudioBus
 // objects can be created normally or via wrapping.  Normally, AudioBus will
 // dice up a contiguous memory block for channel data.  When wrapped, AudioBus
 // instead routes requests for channel data to the wrapped object.
 class MEDIA_EXPORT AudioBus {
  public:
   // Creates a new AudioBus and allocates |channels| of length |frames|.  Uses
   // channels() and frames_per_buffer() if given an AudioParameters object.

[henrika (OOO until Aug 14), 2012/08/15 09:59:37]

nit, channels() and frames_per_buffer() can also mean your private methods with
the same names. Should we add AudioParameters::channels() to be more clear?

Also, the sample rate is now used as well.

[DaleCurtis, 2012/08/16 01:54:14]

Reworded, sample rate dropped.

   static scoped_ptr<AudioBus> Create(int channels, int frames);
   static scoped_ptr<AudioBus> Create(const AudioParameters& params);
 
   // Creates a new AudioBus from an existing channel vector.  Does not transfer
   // ownership of |channel_data| to AudioBus; i.e., |channel_data| must outlive
   // the returned AudioBus.  Each channel pointer must be 16-byte aligned.
   static scoped_ptr<AudioBus> WrapVector(
       int frames, const std::vector<float*>& channel_data);
 
+  // Creates a new AudioBus by wrapping an existing block of memory.  Block must
+  // be large enough to hold ExpectedDataSize() bytes of memory.  |data| must
+  // outlive the returned AudioBus.
+  static scoped_ptr<AudioBus> WrapBlock(int channels, int frames, void* data);

[henrika (OOO until Aug 14), 2012/08/15 09:59:37]

I have actually never really understood why we need the Wrap methods and I can't
see that they are used today in Chrome either. Care to add some info? I
understand what they do; just don't know where they will be used.

[DaleCurtis, 2012/08/15 19:16:47]

These are necessary to save a memcpy between the AudioBus and the shared memory.
The next patch set will show this done for AudioOutputDevice.

Without these methods PPAPI would require both an AudioBus::FromInterleaved()
and a memcpy to transfer data across the shared memory.

+  static scoped_ptr<AudioBus> WrapBlock(const AudioParameters& params,
+                                        void* data);
+
+  // Returns the data_size() of an AudioBus created with the given parameters.
+  static int ExpectedDataSize(int channels, int frames);

[henrika (OOO until Aug 14), 2012/08/15 09:59:37]

Hope this is not a stupid comment but, "expected" means "will most likely get
but we are not sure if we get exactly this size". I mean, we *will* get this
size, right? I am unable to come up with a better name ;-)

[DaleCurtis, 2012/08/15 19:16:47]

Agreed, I don't like it either :) Will keep thinking on it!

[Chris Rogers, 2012/08/15 19:39:31]

How about CalculateSize() or CalculateDataSize() or CalculateStorageSize()

[DaleCurtis, 2012/08/16 01:54:14]

Since this method is intended to be used with WrapBlock I went with BlockSize().

+  static int ExpectedDataSize(const AudioParameters& params);
+
   // Returns a raw pointer to internal channel data.  Useful for copying state
   // between two AudioBus objects created with the same parameters.  data_size()
   // is in bytes.  Can not be used with an AudioBus constructed via wrapping.
   void* data();
   int data_size() const;
 
+  // Helper methods for working with interleaved data.  Expects interleaving to
+  // be [ch0, ch1, ..., chN, ch0, ch1, ...] with |bytes_per_channel| per value.
+  void FromInterleaved(const void* source, int frames, int bytes_per_channel);

[henrika (OOO until Aug 14), 2012/08/15 09:59:37]

Signature is not inline with the function definition where |bytes_per_sample| is
used. bytes_per_channel does not feel correct and it might look odd to mix
frames with samples.

Also, you do more stuff here right? Like converting to float and scaling. Would
be nice with some more comments.

[DaleCurtis, 2012/08/16 01:54:14]

Done.

+  void ToInterleaved(void* dest, int frames, int bytes_per_channel);
+
   // Returns a raw pointer to the requested channel.  Pointer is guaranteed to
   // have a 16-byte alignment.
   float* channel(int channel) { return channel_data_[channel]; }
   const float* channel(int channel) const { return channel_data_[channel]; }
 
   int channels() const { return channel_data_.size(); }
   int frames() const { return frames_; }
 
+  // Output sample rate for the frames in this buffer.  Can only be used with

[DaleCurtis, 2012/08/15 05:18:44]

I actually don't like this and pending discussion from our ongoing emails,
hopefully we can remove it in favor of having AudioOutputController retrieve the
information from AudioManager.

[henrika (OOO until Aug 14), 2012/08/15 09:59:37]

"Output sample rate": not sure if it is a good idea to use output here. Isn't
the intention that we shall use the AudioBus on the input/capture side as well?

[DaleCurtis, 2012/08/15 19:16:47]

I'm pretty confident this can be removed now. I'll drop it in the next patch
set.

+  // an AudioBus created via AudioParameters.
+  int sample_rate() const;
+
   // Helper method for zeroing out all channels of audio data.
   void Zero();
   void ZeroFrames(int frames);
 
  private:
   friend class scoped_ptr<AudioBus>;
   ~AudioBus();
 
-  AudioBus(int channels, int frames);
+  AudioBus(int channels, int frames, int sample_rate);
+  AudioBus(int channels, int frames, int sample_rate, float* data);
   AudioBus(int frames, const std::vector<float*>& channel_data);
 
+  // Helper method for building |channel_data_| from a block of memory.  |data|
+  // must be at least ExpectedDataSize() bytes in size.
+  void BuildChannelData(int channels, int aligned_frame, float* data);
+
+  // Helper method for validating construction parameters.
+  void ValidateConfig(int channels, int frames, int sample_rate);
+
   // Contiguous block of channel memory.
   scoped_ptr_malloc<float, base::ScopedPtrAlignedFree> data_;
   int data_size_;
 
   std::vector<float*> channel_data_;
   int frames_;
 
+  // Output sample rate of the data contained in the bus.

[henrika (OOO until Aug 14), 2012/08/15 09:59:37]

ditto

[DaleCurtis, 2012/08/16 01:54:14]

Removed.

+  int sample_rate_;
+
   DISALLOW_COPY_AND_ASSIGN(AudioBus);
 };
 
 }  // namespace media
 
 #endif  // MEDIA_BASE_AUDIO_BUS_H_