content/common/gpu/surface_capturer.h

   1 // Copyright 2013 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 CONTENT_COMMON_GPU_SURFACE_CAPTURER_H_
   6 #define CONTENT_COMMON_GPU_SURFACE_CAPTURER_H_
   7
   8 #include "content/common/content_export.h"
   9 #include "media/base/video_frame.h"
  10
  11 namespace gfx {
  12
  13 class Size;
  14 class Rect;
  15
  16 }  // namespace ui
  17
  18 namespace content {
  19
  20 // Surface capturer interface.  This interface is implemented by classes
  21 // that perform image capturing from the backbuffer.
  22 class CONTENT_EXPORT SurfaceCapturer {
  23  public:
  24   enum Error {
  25     // Invalid argument was passed to an API method.
  26     kInvalidArgumentError,
  27     // A failure occurred at the GPU process or one of its dependencies.
  28     // Examples of such failures include GPU hardware failures, GPU driver
  29     // failures, GPU library failures, GPU process programming errors, and so
  30     // on.
  31     kPlatformFailureError,
  32   };
  33
  34   class CONTENT_EXPORT Client {
  35    public:
  36     // Callback to notify client of parameters of the backbuffer capture.  Every
  37     // time the Client receives this callback, subsequent media::VideoFrames
  38     // passed to CopyCaptureToVideoFrame() should mind the new parameters.
  39     // Parameters:
  40     //  |buffer_size| is the required logical size (in pixels) of the buffer
  41     //  to capture to (corresponds to |frame->coded_size()| in
  42     //  CopyCaptureToVideoFrame().
  43     //  |visible_rect| is the visible subrect of the actual screen capture
  44     //  contents in the buffer to capture to (corresponds to
  45     //  |frame->visible_rect()| in CopyCaptureToVideoFrame().
  46     virtual void NotifyCaptureParameters(const gfx::Size& buffer_size,
  47                                          const gfx::Rect& visible_rect) = 0;
  48
  49     // Callback to notify client that CopyCaptureToVideoFrame() has been
  50     // completed for |frame|.  After this call, the capturer will drop all its
  51     // outstanding references to |frame|.
  52     // Parameters:
  53     //  |frame| is the completed copied captured frame.
  54     virtual void NotifyCopyCaptureDone(
  55         const scoped_refptr<media::VideoFrame>& frame) = 0;
  56
  57     // Error notification callback.
  58     // Parameters:
  59     //  |error| is the error to report.
  60     virtual void NotifyError(Error error) = 0;
  61
  62    protected:
  63     // Clients are not owned by Capturer instances and should not be deleted
  64     // through these pointers.
  65     virtual ~Client() {}
  66   };
  67
  68   // Initialize the capturer to a specific configuration.
  69   // Parameters:
  70   //  |format| is the format to capture to (corresponds to |frame->format()| in
  71   //  CopyCaptureToVideoFrame()).  The NotifyCaptureParameters() callback is
  72   //  made to the Client on success; on failure, a NotifyError() callback is
  73   //  performed.
  74   virtual void Initialize(media::VideoFrame::Format format) = 0;
  75
  76   // Attempt to capture a single frame.  This call is advisory to note to the
  77   // SurfaceCapturer that capture should be attempted at this time; success is
  78   // not guaranteed.  The most recent captured frame is cached internally, and
  79   // its contents returned every time CopyCaptureToVideoFrame() is called.
  80   virtual void TryCapture() = 0;
  81
  82   // Copy the most recent captured contents to |frame|.
  83   // Parameters:
  84   //  |frame| is the media::VideoFrame to fill with captured contents.
  85   virtual void CopyCaptureToVideoFrame(
  86       const scoped_refptr<media::VideoFrame>& frame) = 0;
  87
  88   // Destroys the capturer; all pending inputs and outputs are dropped
  89   // immediately and the component is freed.  This call may asynchronously free
  90   // system resources, but its client-visible effects are synchronous.  After
  91   // this method returns no more callbacks will be made on the client.  Deletes
  92   // |this| unconditionally, so make sure to drop all pointers to it!
  93   virtual void Destroy() = 0;
  94
  95   virtual ~SurfaceCapturer();
  96 };
  97
  98 }  // namespace content
  99
 100 #endif  // CONTENT_COMMON_GPU_SURFACE_CAPTURER_H_