Move audio frame memory handling inside AudioMixer.

webrtc/api/audio/audio_mixer.h

 /*
  *  Copyright (c) 2011 The WebRTC project authors. All Rights Reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
@@ skipping 17 matching lines @@
    public:
     enum class AudioFrameInfo {
       kNormal,  // The samples in audio_frame are valid and should be used.
       kMuted,   // The samples in audio_frame should not be used, but
                 // should be implicitly interpreted as zero. Other
                 // fields in audio_frame may be read and should
                 // contain meaningful values.
       kError,   // The audio_frame will not be used.
     };
 
-    struct AudioFrameWithInfo {
-      AudioFrame* audio_frame;
-      AudioFrameInfo audio_frame_info;
-    };
-
-    // The implementation of GetAudioFrameWithInfo should update
-    // audio_frame with new audio every time it's called. Implementing
-    // classes are allowed to return the same AudioFrame pointer on
-    // different calls. The pointer must stay valid until the next
-    // mixing call or until this audio source is disconnected from the
-    // mixer. The mixer may modify the contents of the passed
-    // AudioFrame pointer at any time until the next call to
-    // GetAudioFrameWithInfo, or until the source is removed from the
-    // mixer.
-    virtual AudioFrameWithInfo GetAudioFrameWithInfo(int sample_rate_hz) = 0;
+    // The AudioFrame pointer should be treated as only valid for the
+    // duration of this call. The passed AudioFrame is strictly an
+    // output parameter and its fields can have any values when being
+    // passed to GetAudioFrameWithInfo. Implementing classes may
+    // return sound with either one or two interleaved
+    // channels. Implementing classes are responsible for filling all
+    // fields of the provided AudioFrame with meaningful values.
+    virtual AudioFrameInfo GetAudioFrameWithInfo(int sample_rate_hz,
+                                                 AudioFrame* audio_frame) = 0;

[kwiberg-webrtc, 2016/10/14 19:59:32]

You never say what the method is supposed to *do*, or what |sample_rate_hz|
means... and I think the rest can be said with less words. Something like this?

  "Overwrites |audio_frame| with new audio (either 1 or 2 interleaved channels)
of the given sample rate."

(Note: I'm just guessing, so you need to fact check in case this suggestion
sounds good.)

Should the comment additionally be explicit about how much new audio we're
talking about? Is it 10 ms?

[aleloi, 2016/10/17 11:06:39]

I've updated the comment. I guess that it's clear and we don't need to add that
implementing classes shouldn't store the audio frame pointer somewhere between
calls?

 
     // A way for a mixer implementation to distinguish participants.
     virtual int Ssrc() = 0;
 
    protected:
     virtual ~Source() {}
   };
 
   // Since the mixer is reference counted, the destructor may be
   // called from any thread.
@@ skipping 10 matching lines @@
   // mixed result is placed in the provided AudioFrame. Will only be
   // called from a single thread. The rate and channels arguments
   // specify the rate and number of channels of the mix result.
   virtual void Mix(int sample_rate_hz,
                    size_t number_of_channels,
                    AudioFrame* audio_frame_for_mixing) = 0;
 };
 }  // namespace webrtc
 
 #endif  // WEBRTC_API_AUDIO_AUDIO_MIXER_H_