audio_bus.h revision 5821806d5e7f356e8fa4b058a389a808ea183019 
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/scoped_ptr.h"
12#include "media/base/media_export.h"
13
14namespace media {
15class AudioParameters;
16
17// Scoped container for "busing" audio channel data around.  Each channel is
18// stored in planar format and guaranteed to be aligned by kChannelAlignment.
19// AudioBus objects can be created normally or via wrapping.  Normally, AudioBus
20// will dice up a contiguous memory block for channel data.  When wrapped,
21// AudioBus instead routes requests for channel data to the wrapped object.
22class MEDIA_EXPORT AudioBus {
23 public:
24  // Guaranteed alignment of each channel's data; use 16-byte alignment for easy
25  // SSE optimizations.
26  enum { kChannelAlignment = 16 };
27
28  // Creates a new AudioBus and allocates |channels| of length |frames|.  Uses
29  // channels() and frames_per_buffer() from AudioParameters if given.
30  static scoped_ptr<AudioBus> Create(int channels, int frames);
31  static scoped_ptr<AudioBus> Create(const AudioParameters& params);
32
33  // Creates a new AudioBus with the given number of channels, but zero length.
34  // It's expected to be used with SetChannelData() and set_frames() to
35  // wrap externally allocated memory.
36  static scoped_ptr<AudioBus> CreateWrapper(int channels);
37
38  // Creates a new AudioBus from an existing channel vector.  Does not transfer
39  // ownership of |channel_data| to AudioBus; i.e., |channel_data| must outlive
40  // the returned AudioBus.  Each channel must be aligned by kChannelAlignment.
41  static scoped_ptr<AudioBus> WrapVector(
42      int frames, const std::vector<float*>& channel_data);
43
44  // Creates a new AudioBus by wrapping an existing block of memory.  Block must
45  // be at least CalculateMemorySize() bytes in size.  |data| must outlive the
46  // returned AudioBus.  |data| must be aligned by kChannelAlignment.
47  static scoped_ptr<AudioBus> WrapMemory(int channels, int frames, void* data);
48  static scoped_ptr<AudioBus> WrapMemory(const AudioParameters& params,
49                                         void* data);
50  // Returns the required memory size to use the WrapMemory() method.
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
66  // Similar to FromInterleaved() above, but meant for streaming sources.  Does
67  // not zero out remaining frames, the caller is responsible for doing so using
68  // ZeroFramesPartial().  Frames are deinterleaved from the start of |source|
69  // to channel(x)[start_frame].
70  void FromInterleavedPartial(const void* source, int start_frame, int frames,
71                              int bytes_per_sample);
72
73  // Helper method for copying channel data from one AudioBus to another.  Both
74  // AudioBus object must have the same frames() and channels().
75  void CopyTo(AudioBus* dest) const;
76
77  // Returns a raw pointer to the requested channel.  Pointer is guaranteed to
78  // have a 16-byte alignment.  Warning: Do not rely on having sane (i.e. not
79  // inf, nan, or between [-1.0, 1.0]) values in the channel data.
80  float* channel(int channel) { return channel_data_[channel]; }
81  const float* channel(int channel) const { return channel_data_[channel]; }
82  void SetChannelData(int channel, float* data);
83
84  int channels() const { return channel_data_.size(); }
85  int frames() const { return frames_; }
86  void set_frames(int frames);
87
88  // Helper method for zeroing out all channels of audio data.
89  void Zero();
90  void ZeroFrames(int frames);
91  void ZeroFramesPartial(int start_frame, int frames);
92
93 private:
94  friend class scoped_ptr<AudioBus>;
95  ~AudioBus();
96
97  AudioBus(int channels, int frames);
98  AudioBus(int channels, int frames, float* data);
99  AudioBus(int frames, const std::vector<float*>& channel_data);
100  explicit AudioBus(int channels);
101
102  // Helper method for building |channel_data_| from a block of memory.  |data|
103  // must be at least BlockSize() bytes in size.
104  void BuildChannelData(int channels, int aligned_frame, float* data);
105
106  // Contiguous block of channel memory.
107  scoped_ptr_malloc<float, base::ScopedPtrAlignedFree> data_;
108
109  std::vector<float*> channel_data_;
110  int frames_;
111
112  // Protect SetChannelData() and set_frames() for use by CreateWrapper().
113  bool can_set_channel_data_;
114
115  DISALLOW_COPY_AND_ASSIGN(AudioBus);
116};
117
118}  // namespace media
119
120#endif  // MEDIA_BASE_AUDIO_BUS_H_
121