Rename all FillThisBuffer and EmptyThisBuffer to something more meaningful

The FillThisBuffer and EmptyThisBuffer names are very confusing. Anyone
new working on the code probably won't understand the code at all. I'm changing
the names to something more meaningful, which state the actual action taken by
the methods. It is also easier to tell whether the method is for input pin or
for output pin by their names.

Review URL: http://codereview.chromium.org/3201013

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@58604 0039d316-1c4b-4281-b951-d872f2087c98

6 files changed, 82 insertions, 48 deletions

diff --git a/media/video/ffmpeg_video_decode_engine.cc b/media/video/ffmpeg_video_decode_engine.cc
index e1908b6..2d35fdc 100644
--- a/media/video/ffmpeg_video_decode_engine.cc
+++ b/media/video/ffmpeg_video_decode_engine.cc
@@ -151,7 +151,7 @@ static void CopyPlane(size_t plane,
   }
 }
 
-void FFmpegVideoDecodeEngine::EmptyThisBuffer(
+void FFmpegVideoDecodeEngine::ConsumeVideoSample(
     scoped_refptr<Buffer> buffer) {
   pending_input_buffers_--;
   if (flush_pending_) {
@@ -162,7 +162,8 @@ void FFmpegVideoDecodeEngine::EmptyThisBuffer(
   }
 }
 
-void FFmpegVideoDecodeEngine::FillThisBuffer(scoped_refptr<VideoFrame> frame) {
+void FFmpegVideoDecodeEngine::ProduceVideoFrame(
+    scoped_refptr<VideoFrame> frame) {
   // We should never receive NULL frame or EOS frame.
   DCHECK(frame.get() && !frame->IsEndOfStream());
 
@@ -216,7 +217,7 @@ void FFmpegVideoDecodeEngine::DecodeFrame(scoped_refptr<Buffer> buffer) {
               << " , packet size: "
               << buffer->GetDataSize() << " bytes";
     // TODO(jiesun): call event_handler_->OnError() instead.
-    event_handler_->OnFillBufferCallback(video_frame);
+    event_handler_->ConsumeVideoFrame(video_frame);
     return;
   }
 
@@ -227,7 +228,7 @@ void FFmpegVideoDecodeEngine::DecodeFrame(scoped_refptr<Buffer> buffer) {
   // drained, we mark the flag. Otherwise we read from demuxer again.
   if (frame_decoded == 0) {
     if (buffer->IsEndOfStream()) {  // We had started flushing.
-      event_handler_->OnFillBufferCallback(video_frame);
+      event_handler_->ConsumeVideoFrame(video_frame);
       output_eos_reached_ = true;
     } else {
       ReadInput();
@@ -242,7 +243,7 @@ void FFmpegVideoDecodeEngine::DecodeFrame(scoped_refptr<Buffer> buffer) {
       !av_frame_->data[VideoFrame::kUPlane] ||
       !av_frame_->data[VideoFrame::kVPlane]) {
     // TODO(jiesun): call event_handler_->OnError() instead.
-    event_handler_->OnFillBufferCallback(video_frame);
+    event_handler_->ConsumeVideoFrame(video_frame);
     return;
   }
 
@@ -290,7 +291,7 @@ void FFmpegVideoDecodeEngine::DecodeFrame(scoped_refptr<Buffer> buffer) {
   video_frame->SetDuration(duration);
 
   pending_output_buffers_--;
-  event_handler_->OnFillBufferCallback(video_frame);
+  event_handler_->ConsumeVideoFrame(video_frame);
 }
 
 void FFmpegVideoDecodeEngine::Uninitialize() {
@@ -334,7 +335,7 @@ void FFmpegVideoDecodeEngine::Seek() {
 void FFmpegVideoDecodeEngine::ReadInput() {
   DCHECK_EQ(output_eos_reached_, false);
   pending_input_buffers_++;
-  event_handler_->OnEmptyBufferCallback(NULL);
+  event_handler_->ProduceVideoSample(NULL);
 }
 
 VideoFrame::Format FFmpegVideoDecodeEngine::GetSurfaceFormat() const {
diff --git a/media/video/ffmpeg_video_decode_engine.h b/media/video/ffmpeg_video_decode_engine.h
index 3e030db..bc1e033 100644
--- a/media/video/ffmpeg_video_decode_engine.h
+++ b/media/video/ffmpeg_video_decode_engine.h
@@ -29,8 +29,8 @@ class FFmpegVideoDecodeEngine : public VideoDecodeEngine {
   virtual void Initialize(MessageLoop* message_loop,
                           VideoDecodeEngine::EventHandler* event_handler,
                           const VideoCodecConfig& config);
-  virtual void EmptyThisBuffer(scoped_refptr<Buffer> buffer);
-  virtual void FillThisBuffer(scoped_refptr<VideoFrame> frame);
+  virtual void ConsumeVideoSample(scoped_refptr<Buffer> buffer);
+  virtual void ProduceVideoFrame(scoped_refptr<VideoFrame> frame);
   virtual void Uninitialize();
   virtual void Flush();
   virtual void Seek();
diff --git a/media/video/ffmpeg_video_decode_engine_unittest.cc b/media/video/ffmpeg_video_decode_engine_unittest.cc
index b7856d8..704b251 100644
--- a/media/video/ffmpeg_video_decode_engine_unittest.cc
+++ b/media/video/ffmpeg_video_decode_engine_unittest.cc
@@ -96,9 +96,9 @@ class FFmpegVideoDecodeEngineTest : public testing::Test,
   }
 
  public:
-  MOCK_METHOD1(OnFillBufferCallback,
+  MOCK_METHOD1(ConsumeVideoFrame,
                void(scoped_refptr<VideoFrame> video_frame));
-  MOCK_METHOD1(OnEmptyBufferCallback,
+  MOCK_METHOD1(ProduceVideoSample,
                void(scoped_refptr<Buffer> buffer));
   MOCK_METHOD1(OnInitializeComplete,
                void(const VideoCodecInfo& info));
@@ -193,7 +193,7 @@ TEST_F(FFmpegVideoDecodeEngineTest, Initialize_OpenDecoderFails) {
 }
 
 ACTION_P2(DemuxComplete, engine, buffer) {
-  engine->EmptyThisBuffer(buffer);
+  engine->ConsumeVideoSample(buffer);
 }
 
 ACTION_P(DecodeComplete, decoder) {
@@ -217,11 +217,11 @@ TEST_F(FFmpegVideoDecodeEngineTest, DecodeFrame_Normal) {
       .WillOnce(DoAll(SetArgumentPointee<2>(1),  // Simulate 1 byte frame.
                       Return(0)));
 
-  EXPECT_CALL(*this, OnEmptyBufferCallback(_))
+  EXPECT_CALL(*this, ProduceVideoSample(_))
       .WillOnce(DemuxComplete(test_engine_.get(), buffer_));
-  EXPECT_CALL(*this, OnFillBufferCallback(_))
+  EXPECT_CALL(*this, ConsumeVideoFrame(_))
       .WillOnce(DecodeComplete(this));
-  test_engine_->FillThisBuffer(video_frame_);
+  test_engine_->ProduceVideoFrame(video_frame_);
 
   // |video_frame_| timestamp is 0 because we set the timestamp based off
   // the buffer timestamp.
@@ -243,12 +243,12 @@ TEST_F(FFmpegVideoDecodeEngineTest, DecodeFrame_0ByteFrame) {
       .WillOnce(DoAll(SetArgumentPointee<2>(1),  // Simulate 1 byte frame.
                       Return(0)));
 
-  EXPECT_CALL(*this, OnEmptyBufferCallback(_))
+  EXPECT_CALL(*this, ProduceVideoSample(_))
       .WillOnce(DemuxComplete(test_engine_.get(), buffer_))
       .WillOnce(DemuxComplete(test_engine_.get(), buffer_));
-  EXPECT_CALL(*this, OnFillBufferCallback(_))
+  EXPECT_CALL(*this, ConsumeVideoFrame(_))
       .WillOnce(DecodeComplete(this));
-  test_engine_->FillThisBuffer(video_frame_);
+  test_engine_->ProduceVideoFrame(video_frame_);
 
   EXPECT_TRUE(video_frame_.get());
 }
@@ -262,11 +262,11 @@ TEST_F(FFmpegVideoDecodeEngineTest, DecodeFrame_DecodeError) {
               AVCodecDecodeVideo2(&codec_context_, &yuv_frame_, _, _))
       .WillOnce(Return(-1));
 
-  EXPECT_CALL(*this, OnEmptyBufferCallback(_))
+  EXPECT_CALL(*this, ProduceVideoSample(_))
       .WillOnce(DemuxComplete(test_engine_.get(), buffer_));
-  EXPECT_CALL(*this, OnFillBufferCallback(_))
+  EXPECT_CALL(*this, ConsumeVideoFrame(_))
       .WillOnce(DecodeComplete(this));
-  test_engine_->FillThisBuffer(video_frame_);
+  test_engine_->ProduceVideoFrame(video_frame_);
 
   EXPECT_FALSE(video_frame_.get());
 }
diff --git a/media/video/omx_video_decode_engine.cc b/media/video/omx_video_decode_engine.cc
index c893d7d..3aa8101 100644
--- a/media/video/omx_video_decode_engine.cc
+++ b/media/video/omx_video_decode_engine.cc
@@ -119,7 +119,7 @@ void OmxVideoDecodeEngine::Initialize(
 }
 
 // This method handles only input buffer, without coupling with output
-void OmxVideoDecodeEngine::EmptyThisBuffer(scoped_refptr<Buffer> buffer) {
+void OmxVideoDecodeEngine::ConsumeVideoSample(scoped_refptr<Buffer> buffer) {
   DCHECK_EQ(message_loop_, MessageLoop::current());
   DCHECK(!free_input_buffers_.empty());
   DCHECK_GT(input_pending_request_, 0);
@@ -304,7 +304,7 @@ void OmxVideoDecodeEngine::FinishEmptyBuffer(scoped_refptr<Buffer> buffer) {
   DCHECK_EQ(message_loop_, MessageLoop::current());
 
   if (!input_queue_has_eos_) {
-    event_handler_->OnEmptyBufferCallback(buffer);
+    event_handler_->ProduceVideoSample(buffer);
     ++input_pending_request_;
   }
 }
@@ -323,7 +323,7 @@ void OmxVideoDecodeEngine::FinishFillBuffer(OMX_BUFFERHEADERTYPE* buffer) {
   frame->SetTimestamp(base::TimeDelta::FromMicroseconds(buffer->nTimeStamp));
   frame->SetDuration(frame->GetTimestamp() - last_pts_);
   last_pts_ = frame->GetTimestamp();
-  event_handler_->OnFillBufferCallback(frame);
+  event_handler_->ConsumeVideoFrame(frame);
   output_pending_request_--;
 }
 
@@ -597,7 +597,7 @@ void OmxVideoDecodeEngine::DoneSetStateExecuting(OMX_STATETYPE state) {
 
 // Function for receiving output buffers. Hookup for buffer recycling
 // and outside allocator.
-void OmxVideoDecodeEngine::FillThisBuffer(
+void OmxVideoDecodeEngine::ProduceVideoFrame(
     scoped_refptr<VideoFrame> video_frame) {
   DCHECK(video_frame.get() && !video_frame->IsEndOfStream());
   output_pending_request_++;
@@ -605,7 +605,7 @@ void OmxVideoDecodeEngine::FillThisBuffer(
   if (!CanAcceptOutput()) {
     if (uses_egl_image_) {  // return it to owner.
       output_pending_request_--;
-      event_handler_->OnFillBufferCallback(video_frame);
+      event_handler_->ConsumeVideoFrame(video_frame);
     }
     return;
   }
@@ -617,7 +617,7 @@ void OmxVideoDecodeEngine::FillThisBuffer(
     } else if (kClientFlushing == client_state_) {
       if (uses_egl_image_) {  // return it to owner.
         output_pending_request_--;
-        event_handler_->OnFillBufferCallback(video_frame);
+        event_handler_->ConsumeVideoFrame(video_frame);
       }
       if (InputPortFlushed() && OutputPortFlushed())
         ComponentFlushDone();
@@ -1220,7 +1220,7 @@ void OmxVideoDecodeEngine::FillBufferDoneTask(OMX_BUFFERHEADERTYPE* buffer) {
     if (uses_egl_image_) {
       scoped_refptr<VideoFrame> frame;
       frame = static_cast<VideoFrame*>(buffer->pAppPrivate);
-      event_handler_->OnFillBufferCallback(frame);
+      event_handler_->ConsumeVideoFrame(frame);
       output_pending_request_--;
     }
     return;
@@ -1240,7 +1240,7 @@ void OmxVideoDecodeEngine::FillBufferDoneTask(OMX_BUFFERHEADERTYPE* buffer) {
     // Singal end of stream.
     scoped_refptr<VideoFrame> frame;
     VideoFrame::CreateEmptyFrame(&frame);
-    event_handler_->OnFillBufferCallback(frame);
+    event_handler_->ConsumeVideoFrame(frame);
   }
 
   if (client_state_ == kClientFlushing &&
diff --git a/media/video/omx_video_decode_engine.h b/media/video/omx_video_decode_engine.h
index 9e8bcf3..8347eed 100644
--- a/media/video/omx_video_decode_engine.h
+++ b/media/video/omx_video_decode_engine.h
@@ -29,8 +29,8 @@ class OmxVideoDecodeEngine : public VideoDecodeEngine {
   virtual void Initialize(MessageLoop* message_loop,
                           VideoDecodeEngine::EventHandler* event_handler,
                           const VideoCodecConfig& config);
-  virtual void EmptyThisBuffer(scoped_refptr<Buffer> buffer);
-  virtual void FillThisBuffer(scoped_refptr<VideoFrame> frame);
+  virtual void ConsumeVideoSample(scoped_refptr<Buffer> buffer);
+  virtual void ProduceVideoFrame(scoped_refptr<VideoFrame> frame);
   virtual void Uninitialize();
   virtual void Flush();
   virtual void Seek();
diff --git a/media/video/video_decode_engine.h b/media/video/video_decode_engine.h
index 9c84f11..df14522 100644
--- a/media/video/video_decode_engine.h
+++ b/media/video/video_decode_engine.h
@@ -79,8 +79,35 @@ class VideoDecodeEngine {
     virtual void OnSeekComplete() = 0;
     virtual void OnError() = 0;
     virtual void OnFormatChange(VideoStreamInfo stream_info) = 0;
-    virtual void OnEmptyBufferCallback(scoped_refptr<Buffer> buffer) = 0;
-    virtual void OnFillBufferCallback(scoped_refptr<VideoFrame> frame) = 0;
+
+    // TODO(hclam): The following two methods shouldn't belong to this class
+    // because they are not video decode events but used to send decoded
+    // video frames and request video packets.
+    //
+    // Signal the user of VideoDecodeEngine to provide a video sample.
+    //
+    // In the normal running state, this method is called by the video decode
+    // engine to request video samples used for decoding.
+    //
+    // In the case when the video decode engine is flushing, this method is
+    // called to return video samples acquired by the video decode engine.
+    //
+    // |buffer| can be NULL in which case this method call is purely for
+    // requesting new video samples. If |buffer| is non-NULL, the buffer is
+    // returned to the owner at the sample time as a request for video sample
+    // is made.
+    virtual void ProduceVideoSample(scoped_refptr<Buffer> buffer) = 0;
+
+    // Signal the user of VideoDecodeEngine that a video frame is ready to
+    // be consumed or a video frame is returned to the owner.
+    //
+    // In the normal running state, this method is called to signal that
+    // |frame| contains a decoded video frame and is ready to be used.
+    //
+    // In the case of flushing and video frame is provided externally, this
+    // method is called to return the video frame object to the owner.
+    // The content of the video frame may be invalid.
+    virtual void ConsumeVideoFrame(scoped_refptr<VideoFrame> frame) = 0;
   };
 
   virtual ~VideoDecodeEngine() {}
@@ -106,21 +133,27 @@ class VideoDecodeEngine {
   // issue read requests after Flush() us made.
   virtual void Seek() = 0;
 
-  // Buffer exchange method for input and output stream.
-  // These functions and callbacks could be used in two scenarios for both
-  // input and output streams:
-  // 1. Engine provide buffers.
-  // 2. Outside party provide buffers.
-  // The currently planned engine implementation:
-  // 1. provides the input buffer request inside engine through
-  // |EmptyThisBufferCallback|. The engine implementation has better knowledge
-  // of the decoder reordering delay and jittery removal requirements. Input
-  // buffers are returned into engine through |EmptyThisBuffer|.
-  // 2. Output buffers are provided from outside the engine, and feed into
-  // engine through |FillThisBuffer|. Output buffers are returned to outside
-  // by |FillThisBufferCallback|.
-  virtual void EmptyThisBuffer(scoped_refptr<Buffer> buffer) = 0;
-  virtual void FillThisBuffer(scoped_refptr<VideoFrame> frame) = 0;
+  // Provide a video sample to be used by the video decode engine.
+  //
+  // This method is called in response to ProvideVideoSample() called to the
+  // user.
+  virtual void ConsumeVideoSample(scoped_refptr<Buffer> buffer) = 0;
+
+  // Signal the video decode engine to produce a video frame or return the
+  // video frame object to the video decode engine.
+  //
+  // In the normal running state, this method is called by the user of the
+  // video decode engine to request a decoded video frame. If |frame| is
+  // NULL the video decode engine should allocate a video frame object.
+  // Otherwise video decode engine should try to use the video frame object
+  // provided as output.
+  //
+  // In flushing state and video frames are allocated internally this method
+  // is called by the user to return the video frame object.
+  //
+  // In response to this method call, ConsumeVideoFrame() is called with a
+  // video frame object containing decoded video content.
+  virtual void ProduceVideoFrame(scoped_refptr<VideoFrame> frame) = 0;
 };
 
 }  // namespace media