media/base/video_capturer_source.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_BASE_VIDEO_CAPTURER_SOURCE_H_
   6 #define MEDIA_BASE_VIDEO_CAPTURER_SOURCE_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/callback.h"
  12 #include "base/memory/ref_counted.h"
  13 #include "base/time/time.h"
  14 #include "media/base/media_export.h"
  15 #include "media/base/video_capture_types.h"
  16
  17 namespace media {
  18
  19 class VideoFrame;
  20
  21 // VideoCapturerSource is an interface representing the source for captured
  22 // video.  An implementation will periodically call the frame callback with new
  23 // video frames.
  24 class MEDIA_EXPORT VideoCapturerSource {
  25  public:
  26   virtual ~VideoCapturerSource();
  27
  28   // This callback is used to deliver video frames.
  29   //
  30   // |estimated_capture_time| - The capture time of the delivered video
  31   // frame. This field represents the local time at which either: 1) the frame
  32   // was generated, if it was done so locally; or 2) the targeted play-out time
  33   // of the frame, if it was generated from a remote source. Either way, an
  34   // implementation should not present the frame before this point-in-time. This
  35   // value is NOT a high-resolution timestamp, and so it should not be used as a
  36   // presentation time; but, instead, it should be used for buffering playback
  37   // and for A/V synchronization purposes. NOTE: It is possible for this value
  38   // to be null if the current implementation lacks this timing information.
  39   //
  40   // |video_frame->timestamp()| gives the presentation timestamp of the video
  41   // frame relative to the first frame generated by the corresponding source.
  42   // Because a source can start generating frames before a subscriber is added,
  43   // the first video frame delivered may not have timestamp equal to 0.
  44   using VideoCaptureDeliverFrameCB =
  45       base::Callback<void(const scoped_refptr<media::VideoFrame>& video_frame,
  46                           base::TimeTicks estimated_capture_time)>;
  47
  48   using VideoCaptureDeviceFormatsCB =
  49       base::Callback<void(const media::VideoCaptureFormats&)>;
  50
  51   using RunningCallback = base::Callback<void(bool)>;
  52
  53   // Collects the formats that can currently be used.
  54   // |max_requested_height|, |max_requested_width|, and
  55   // |max_requested_frame_rate| is used by Tab and Screen capture to decide what
  56   // resolution/framerate to generate. |callback| is triggered when the formats
  57   // have been collected.
  58   virtual void GetCurrentSupportedFormats(
  59       int max_requested_width,
  60       int max_requested_height,
  61       double max_requested_frame_rate,
  62       const VideoCaptureDeviceFormatsCB& callback) = 0;
  63
  64   // Starts capturing frames using the capture |params|. |new_frame_callback| is
  65   // triggered when a new video frame is available.
  66   // If capturing is started successfully then |running_callback| will be
  67   // called with a parameter of true. Note that some implementations may
  68   // simply reject StartCapture (by calling running_callback with a false
  69   // argument) if called with the wrong task runner.
  70   // If capturing fails to start or stopped due to an external event then
  71   // |running_callback| will be called with a parameter of false.
  72   // |running_callback| will always be called on the same thread as the
  73   // StartCapture.
  74   virtual void StartCapture(
  75       const media::VideoCaptureParams& params,
  76       const VideoCaptureDeliverFrameCB& new_frame_callback,
  77       const RunningCallback& running_callback) = 0;
  78
  79   // Stops capturing frames and clears all callbacks including the
  80   // SupportedFormatsCallback callback. Note that queued frame callbacks
  81   // may still occur after this call, so the caller must take care to
  82   // use refcounted or weak references in |new_frame_callback|.
  83   virtual void StopCapture() = 0;
  84 };
  85
  86 }  // namespace media
  87
  88 #endif  // MEDIA_BASE_VIDEO_CAPTURER_SOURCE_H_