1/*
2 *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11#ifndef WEBRTC_MODULES_AUDIO_CODING_NETEQ_AUDIO_MULTI_VECTOR_H_
12#define WEBRTC_MODULES_AUDIO_CODING_NETEQ_AUDIO_MULTI_VECTOR_H_
13
14#include <string.h>  // Access to size_t.
15
16#include <vector>
17
18#include "webrtc/base/constructormagic.h"
19#include "webrtc/modules/audio_coding/neteq/audio_vector.h"
20#include "webrtc/typedefs.h"
21
22namespace webrtc {
23
24class AudioMultiVector {
25 public:
26  // Creates an empty AudioMultiVector with |N| audio channels. |N| must be
27  // larger than 0.
28  explicit AudioMultiVector(size_t N);
29
30  // Creates an AudioMultiVector with |N| audio channels, each channel having
31  // an initial size. |N| must be larger than 0.
32  AudioMultiVector(size_t N, size_t initial_size);
33
34  virtual ~AudioMultiVector();
35
36  // Deletes all values and make the vector empty.
37  virtual void Clear();
38
39  // Clears the vector and inserts |length| zeros into each channel.
40  virtual void Zeros(size_t length);
41
42  // Copies all values from this vector to |copy_to|. Any contents in |copy_to|
43  // are deleted. After the operation is done, |copy_to| will be an exact
44  // replica of this object. The source and the destination must have the same
45  // number of channels.
46  virtual void CopyTo(AudioMultiVector* copy_to) const;
47
48  // Appends the contents of array |append_this| to the end of this
49  // object. The array is assumed to be channel-interleaved. |length| must be
50  // an even multiple of this object's number of channels.
51  // The length of this object is increased with the |length| divided by the
52  // number of channels.
53  virtual void PushBackInterleaved(const int16_t* append_this, size_t length);
54
55  // Appends the contents of AudioMultiVector |append_this| to this object. The
56  // length of this object is increased with the length of |append_this|.
57  virtual void PushBack(const AudioMultiVector& append_this);
58
59  // Appends the contents of AudioMultiVector |append_this| to this object,
60  // taken from |index| up until the end of |append_this|. The length of this
61  // object is increased.
62  virtual void PushBackFromIndex(const AudioMultiVector& append_this,
63                                 size_t index);
64
65  // Removes |length| elements from the beginning of this object, from each
66  // channel.
67  virtual void PopFront(size_t length);
68
69  // Removes |length| elements from the end of this object, from each
70  // channel.
71  virtual void PopBack(size_t length);
72
73  // Reads |length| samples from each channel and writes them interleaved to
74  // |destination|. The total number of elements written to |destination| is
75  // returned, i.e., |length| * number of channels. If the AudioMultiVector
76  // contains less than |length| samples per channel, this is reflected in the
77  // return value.
78  virtual size_t ReadInterleaved(size_t length, int16_t* destination) const;
79
80  // Like ReadInterleaved() above, but reads from |start_index| instead of from
81  // the beginning.
82  virtual size_t ReadInterleavedFromIndex(size_t start_index,
83                                          size_t length,
84                                          int16_t* destination) const;
85
86  // Like ReadInterleaved() above, but reads from the end instead of from
87  // the beginning.
88  virtual size_t ReadInterleavedFromEnd(size_t length,
89                                        int16_t* destination) const;
90
91  // Overwrites each channel in this AudioMultiVector with values taken from
92  // |insert_this|. The values are taken from the beginning of |insert_this| and
93  // are inserted starting at |position|. |length| values are written into each
94  // channel. If |length| and |position| are selected such that the new data
95  // extends beyond the end of the current AudioVector, the vector is extended
96  // to accommodate the new data. |length| is limited to the length of
97  // |insert_this|.
98  virtual void OverwriteAt(const AudioMultiVector& insert_this,
99                           size_t length,
100                           size_t position);
101
102  // Appends |append_this| to the end of the current vector. Lets the two
103  // vectors overlap by |fade_length| samples (per channel), and cross-fade
104  // linearly in this region.
105  virtual void CrossFade(const AudioMultiVector& append_this,
106                         size_t fade_length);
107
108  // Returns the number of channels.
109  virtual size_t Channels() const { return num_channels_; }
110
111  // Returns the number of elements per channel in this AudioMultiVector.
112  virtual size_t Size() const;
113
114  // Verify that each channel can hold at least |required_size| elements. If
115  // not, extend accordingly.
116  virtual void AssertSize(size_t required_size);
117
118  virtual bool Empty() const;
119
120  // Copies the data between two channels in the AudioMultiVector. The method
121  // does not add any new channel. Thus, |from_channel| and |to_channel| must
122  // both be valid channel numbers.
123  virtual void CopyChannel(size_t from_channel, size_t to_channel);
124
125  // Accesses and modifies a channel (i.e., an AudioVector object) of this
126  // AudioMultiVector.
127  const AudioVector& operator[](size_t index) const;
128  AudioVector& operator[](size_t index);
129
130 protected:
131  std::vector<AudioVector*> channels_;
132  size_t num_channels_;
133
134 private:
135  DISALLOW_COPY_AND_ASSIGN(AudioMultiVector);
136};
137
138}  // namespace webrtc
139#endif  // WEBRTC_MODULES_AUDIO_CODING_NETEQ_AUDIO_MULTI_VECTOR_H_
140