Prime the landing pad for the new video rendering pipeline.

media/base/video_renderer_sink.h

Index: media/base/video_renderer_sink.h
diff --git a/media/base/video_renderer_sink.h b/media/base/video_renderer_sink.h
new file mode 100644
index 0000000000000000000000000000000000000000..25159430dda7cdbfc9b2edbed43f5b9c0325ccdc
--- /dev/null
+++ b/media/base/video_renderer_sink.h
@@ -0,0 +1,65 @@
+// Copyright 2014 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_VIDEO_RENDERER_SINK_H_
+#define MEDIA_BASE_VIDEO_RENDERER_SINK_H_
+
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/logging.h"
+#include "media/base/media_export.h"
+#include "media/base/video_frame.h"
+
+namespace media {
+
+// VideoRendererSink is an interface representing the end-point for rendered
+// video frames.  An implementation is expected to periodically call Render() on
+// a callback object.
+class MEDIA_EXPORT VideoRendererSink {
+ public:
+  class RenderCallback {
+   public:
+    // Returns a VideoFrame for rendering which should be displayed within the
+    // presentation interval [|deadline_min|, |deadline_max|].  Returns NULL if

[xhwang, 2015/04/03 07:00:13]

ditto: What if there are multiple frames in that interval? Shall the newest
frame be returned?

Also, will the interval be contiguous (no overlapping and no gap)?

[DaleCurtis, 2015/04/03 17:14:52]

It's expected to be contiguous and monotonically increasing. The current
algorithm increasing the display count of the last rendered frame for missed
intervals.

[xhwang, 2015/04/03 19:18:27]

Yeah, that makes sense. Let's update the comment to be clear about this.

[DaleCurtis, 2015/04/07 00:40:51]

Done.

+    // no frame or no new frame (since the last Render() call) is available for
+    // rendering within the requested interval.
+    //
+    // If |is_visible| is false, the returned frame may not be rendered; clients
+    // may use this information to stop counting dropped frames (as the deadline
+    // interval may be extend while render frequency is reduced to conserve on
+    // power consumption).
+    virtual scoped_refptr<VideoFrame> Render(base::TimeTicks deadline_min,
+                                             base::TimeTicks deadline_max,
+                                             bool is_visible) = 0;

[xhwang, 2015/04/03 07:00:13]

VideoFrameProvider has a separate SetVisible(bool visible) method. Is there any
reason for this difference?

[DaleCurtis, 2015/04/03 17:14:52]

I was hoping to avoid having to have the VideoRendererImpl pump callbacks to its
own Render() method, but now I'm not sure. Let me explain my thought process and
hopefully you can help reach the best decision :)

Visibility seems a blink/cc level concept, so I'm still not 100% happy with this
flag as it almost feels like a layer violation... but we need some way to not
count drop frames when render intervals expand to say 100ms vs the typical 16ms
vsync interval. If we can find another way to ignore dropped frames for
invisibility, we can drop this (which would be the best solution I think). Today
Pipeline owns the pipeline statistics, which makes it tricky to deal with the
incorrect reporting.

It also seems cleanest to have VideoFrameCompositor own a FakeVideoRendererSink
which it uses as a proxy to pump Render() callbacks to the VideoRendererImpl
when visibility is lost; even though VideoFrameCompositor or VideoRendererImpl
could own a FakeVideoRendererSink which it would use to pump callbacks to.

All this lead me to having VFC pump Render() callbacks with visibility=false
such that frame rendering is done correctly (i.e. frames dropped and requested
as normal), but dropped frames just aren't counted. Since VRI doesn't seem to
need this value outside of during Render() I put it on that method.

[xhwang, 2015/04/03 19:18:27]

Agreed "visibility" should be a cc layer concept. If "visibility" is false, can
the cc code keep calling GetCurrentFrame() and drop the frame onto the floor
immediately, and then call PutCurrentFrame() to pretend it's rendered? One issue
from this model is that we still need the cc layer to issue Render() calls
periodically even when the tab is in background. Is that a performance concern
you try to solve?
Not sure about the details of this plan. But if someone must issue Render()
anyways, why can't we just let the cc code to do it. (See comment above.)

One thing to note is that when the Render() interval is large (e.g. 200ms),
VideoRenderImpl should drop decoded frame immediately if it's behind the last
Render() call interval. Otherwise, since we only buffer 4 frames and stop
buffering more, we could always lag behind (e.g. drop 4 frames for every
Render() call).

[DaleCurtis, 2015/04/03 19:59:16]

Yes, it's power concern; which is why the cc/ time seems to be actively working
to remove background callbacks like this. The cc/ code couldn't skew the render
interval for power savings without letting VRI know somehow, otherwise we'd
count the frames which weren't picked for the longer interval as dropped; which
doesn't seem correct (and surely our friends who care about dropped frames a lot
won't like this :)
Correct. It was my intent that larger render intervals would cause multiple
frames to drop and then requeue new frames as they exceed their potential
display range; this is why we need the visibility signal to count these
appropriately.

[DaleCurtis, 2015/04/07 00:40:51]

As discussed via chat, these have been replaced with OnRenderResumed() and
OnRenderSuspended(). We'll have the VideoRendererImpl itself pump the fake
callbacks based on knowledge of the frame durations.

+
+    // Called by the sink when a VideoFrame previously returned via Render() was
+    // not actually rendered.  Must be called before the next Render() call.
+    // Must not be called if |is_visible| was false when Render() was called.
+    virtual void OnFrameDropped() = 0;
+
+    virtual ~RenderCallback() {}
+  };
+
+  // Starts video rendering.  See RenderCallback for more details.
+  virtual void Start(RenderCallback* callback) = 0;
+
+  // Stops video rendering, waits for any outstanding calls to |callback| to
+  // complete before returning.  No new calls to |callback| will be issued after
+  // this method returns.
+  virtual void Stop() = 0;
+
+  // Instead of using a callback driven rendering path, allow clients to paint
+  // frames as they see fit without regard for the compositor.
+  // TODO(dalecurtis): This should be nuked once experiments show the new path
+  // is amazing and the old path is not! http://crbug.com/439548
+  virtual void PaintFrameUsingOldRenderingPath(
+      const scoped_refptr<VideoFrame>& frame) = 0;
+
+  virtual ~VideoRendererSink() {}
+};
+
+}  // namespace media
+
+#endif  // MEDIA_BASE_VIDEO_RENDERER_SINK_H_