[Cast] Size-Adaptable platform video encoders.

media/cast/cast_sender.h

 // Copyright 2013 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.
 //
 // This is the main interface for the cast sender.
 //
 // The AudioFrameInput, VideoFrameInput and PacketReciever interfaces should
 // be accessed from the main thread.
 
 #ifndef MEDIA_CAST_CAST_SENDER_H_
 #define MEDIA_CAST_CAST_SENDER_H_
 
 #include "base/basictypes.h"
 #include "base/callback.h"
 #include "base/memory/ref_counted.h"
 #include "base/memory/scoped_ptr.h"
 #include "base/time/tick_clock.h"
 #include "base/time/time.h"
 #include "media/base/audio_bus.h"
 #include "media/cast/cast_config.h"
 #include "media/cast/cast_environment.h"
 #include "media/cast/net/cast_transport_sender.h"
 
+namespace gfx {
+class Size;
+}
+
 namespace media {
 class VideoFrame;
 
 namespace cast {
 class AudioSender;
 class VideoSender;
 
 class VideoFrameInput : public base::RefCountedThreadSafe<VideoFrameInput> {
  public:
   // Insert video frames into Cast sender. Frames will be encoded, packetized
   // and sent to the network.
   virtual void InsertRawVideoFrame(
       const scoped_refptr<media::VideoFrame>& video_frame,
       const base::TimeTicks& capture_time) = 0;
 
   // Creates a |VideoFrame| optimized for the encoder. When available, these
   // frames offer performance benefits, such as memory copy elimination. The
   // format is guaranteed to be I420 or NV12.
   //
-  // Not every encoder supports this method. Use |ShouldCreateOptimizedFrame|
-  // to determine if you can and should use this method. Calling
-  // this method when |ShouldCreateOptimizedFrame| is false will CHECK.
-  virtual scoped_refptr<VideoFrame> CreateOptimizedFrame(
-      base::TimeDelta timestamp) = 0;
+  // Not every encoder supports this method. Use |CanCreateOptimizedFrames| to
+  // determine if you can and should use this method.
+  //
+  // Even if |CanCreateOptimizedFrames| indicates support, there are transient
+  // conditions during a session where optimized frames cannot be provided.  In
+  // this case, the caller must be able to handle a nullptr return value.

[hubbe, 2015/02/11 00:47:53]

And do what?
Should the caller create an un-optimized frame, or should they wait?

[miu, 2015/02/11 02:14:23]

Done.

+  virtual scoped_refptr<VideoFrame> MaybeCreateOptimizedFrame(

[hubbe, 2015/02/11 00:47:54]

I think the "Maybe" is redundant.

[miu, 2015/02/11 02:14:23]

I put it in there for two reasons: 1) The naming strongly implies a nullptr can
be returned.  2) I want to break compilation on code outside of the Chromium
project that calls this method since its behavior has changed (as discussed w/
jfroy@).

+      const gfx::Size& frame_size, base::TimeDelta timestamp) = 0;
 
   // Returns true if the encoder supports creating optimized frames.
-  virtual bool SupportsCreateOptimizedFrame() const = 0;
+  virtual bool CanCreateOptimizedFrames() const = 0;
 
  protected:
   virtual ~VideoFrameInput() {}
 
  private:
   friend class base::RefCountedThreadSafe<VideoFrameInput>;
 };
 
 class AudioFrameInput : public base::RefCountedThreadSafe<AudioFrameInput> {
  public:
@@ skipping 44 matching lines @@
   // Change the target delay. This is only valid if the receiver
   // supports the "adaptive_target_delay" rtp extension.
   virtual void SetTargetPlayoutDelay(
       base::TimeDelta new_target_playout_delay) = 0;
 };
 
 }  // namespace cast
 }  // namespace media
 
 #endif  // MEDIA_CAST_CAST_SENDER_H_