blob: 9c46503617ce976bf08127bab2f9202194eb798a [file] [log] [blame]
// Copyright 2015 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_CAPTURE_VIDEO_CAPTURER_SOURCE_H_
#define MEDIA_CAPTURE_VIDEO_CAPTURER_SOURCE_H_
#include <string>
#include <vector>
#include "base/callback.h"
#include "base/memory/ref_counted.h"
#include "base/time/time.h"
#include "media/capture/capture_export.h"
#include "media/capture/video/video_capture_feedback.h"
#include "media/capture/video_capture_types.h"
namespace media {
class VideoFrame;
// VideoCapturerSource is an interface representing the source for captured
// video. An implementation will periodically call the frame callback with new
// video frames.
class CAPTURE_EXPORT VideoCapturerSource {
public:
virtual ~VideoCapturerSource();
// This callback is used to deliver video frames.
//
// |estimated_capture_time| - The capture time of the delivered video
// frame. This field represents the local time at which either: 1) the frame
// was generated, if it was done so locally; or 2) the targeted play-out time
// of the frame, if it was generated from a remote source. Either way, an
// implementation should not present the frame before this point-in-time. This
// value is NOT a high-resolution timestamp, and so it should not be used as a
// presentation time; but, instead, it should be used for buffering playback
// and for A/V synchronization purposes. NOTE: It is possible for this value
// to be null if the current implementation lacks this timing information.
//
// |video_frame->timestamp()| gives the presentation timestamp of the video
// frame relative to the first frame generated by the corresponding source.
// Because a source can start generating frames before a subscriber is added,
// the first video frame delivered may not have timestamp equal to 0.
//
// |scaled_video_frames| are alternative representations of |video_frame|
// where scaling has already been applied. Scaled frames may be produced by
// some capturers that listen to media::VideoCaptureFeedback. However, because
// not all capturers support in-capturer scaling or due to delays in the
// pipeline, listeners have to be prepared for scaled video frames not being
// present or being present with other sizes than most recently requested.
using VideoCaptureDeliverFrameCB = base::RepeatingCallback<void(
scoped_refptr<media::VideoFrame> video_frame,
std::vector<scoped_refptr<media::VideoFrame>> scaled_video_frames,
base::TimeTicks estimated_capture_time)>;
using VideoCaptureDeviceFormatsCB =
base::OnceCallback<void(const media::VideoCaptureFormats&)>;
using RunningCallback = base::RepeatingCallback<void(bool)>;
// Returns formats that are preferred and can currently be used. May be empty
// if no formats are available or known.
virtual VideoCaptureFormats GetPreferredFormats() = 0;
// Starts capturing frames using the capture |params|. |new_frame_callback| is
// triggered when a new video frame is available.
// If capturing is started successfully then |running_callback| will be
// called with a parameter of true. Note that some implementations may
// simply reject StartCapture (by calling running_callback with a false
// argument) if called with the wrong task runner.
// If capturing fails to start or stopped due to an external event then
// |running_callback| will be called with a parameter of false.
// |running_callback| will always be called on the same thread as the
// StartCapture.
virtual void StartCapture(
const media::VideoCaptureParams& params,
const VideoCaptureDeliverFrameCB& new_frame_callback,
const RunningCallback& running_callback) = 0;
// Returns a callback for providing the feedback from the consumer.
// The callback can be called on any thread.
virtual media::VideoCaptureFeedbackCB GetFeedbackCallback() const;
// Asks source to send a refresh frame. In cases where source does not provide
// a continuous rate of new frames (e.g. canvas capture, screen capture where
// the screen's content has not changed in a while), consumers may request a
// "refresh frame" to be delivered. For instance, this would be needed when
// a new sink is added to a MediaStreamTrack.
//
// The default implementation is a no-op and implementations are not required
// to honor this request. If they decide to and capturing is started
// successfully, then |new_frame_callback| should be called with a frame.
//
// Note: This should only be called after StartCapture() and before
// StopCapture(). Otherwise, its behavior is undefined.
virtual void RequestRefreshFrame() {}
// Optionally suspends frame delivery. The source may or may not honor this
// request. Thus, the caller cannot assume frame delivery will actually
// stop. Even if frame delivery is suspended, this might not take effect
// immediately.
//
// The purpose of this is to allow minimizing resource usage while
// there are no frame consumers present.
//
// Note: This should only be called after StartCapture() and before
// StopCapture(). Otherwise, its behavior is undefined.
virtual void MaybeSuspend() {}
// Resumes frame delivery, if it was suspended. If frame delivery was not
// suspended, this is a no-op, and frame delivery will continue.
//
// Note: This should only be called after StartCapture() and before
// StopCapture(). Otherwise, its behavior is undefined.
virtual void Resume() {}
// Stops capturing frames and clears all callbacks including the
// SupportedFormatsCallback callback. Note that queued frame callbacks
// may still occur after this call, so the caller must take care to
// use refcounted or weak references in |new_frame_callback|.
virtual void StopCapture() = 0;
// Indicates to the source that a frame has been dropped.
virtual void OnFrameDropped(media::VideoCaptureFrameDropReason reason) {}
// Hints to the source that if it has an alpha channel, that alpha channel
// will be ignored and can be discarded.
virtual void SetCanDiscardAlpha(bool can_discard_alpha) {}
// Sends a log message to the source.
virtual void OnLog(const std::string& message) {}
};
} // namespace media
#endif // MEDIA_CAPTURE_VIDEO_CAPTURER_SOURCE_H_