Video Capture: Allow suspension of individual devices.

media/capture/video/video_capture_device.h

 // Copyright (c) 2012 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.
 //
 // VideoCaptureDevice is the abstract base class for realizing video capture
 // device support in Chromium. It provides the interface for OS dependent
 // implementations.
 // The class is created and functions are invoked on a thread owned by
 // VideoCaptureManager. Capturing is done on other threads, depending on the OS
 // specific implementation.
@@ skipping 147 matching lines @@
   //      amount of time).
   //   2. A few repeats of the same frame would allow a lossy video encoder to
   //      improve the video quality of unchanging content.
   //
   // The default implementation is a no-op. VideoCaptureDevice implementations
   // are not required to honor this request, especially if they do not
   // self-pause and/or if honoring the request would cause them to exceed their
   // configured maximum frame rate. Any VideoCaptureDevice that does self-pause,
   // however, should provide an implementation of this method that makes
   // reasonable attempts to honor these requests.
+  //
+  // Note: This should only be called after AllocateAndStart() and before
+  // StopAndDeAllocate(). Otherwise, its behavior is undefined.
   virtual void RequestRefreshFrame() {}
 
+  // Optionally suspends frame delivery. The VideoCaptureDevice 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 quickly place the device into a state where it's
+  // resource utilization is minimized while there are no frame consumers; and
+  // then quickly resume once a frame consumer is present.
+  //
+  // Note: This should only be called after AllocateAndStart() and before
+  // StopAndDeAllocate(). 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 AllocateAndStart() and before
+  // StopAndDeAllocate(). Otherwise, its behavior is undefined.
+  virtual void Resume() {}
+
   // Deallocates the video capturer, possibly asynchronously.
   //
   // This call requires the device to do the following things, eventually: put
   // hardware into a state where other applications could use it, free the
   // memory associated with capture, and delete the |client| pointer passed into
   // AllocateAndStart.
   //
   // If deallocation is done asynchronously, then the device implementation must
   // ensure that a subsequent AllocateAndStart() operation targeting the same ID
   // would be sequenced through the same task runner, so that deallocation
@@ skipping 24 matching lines @@
 
  private:
   // Gets the power line frequency from the current system time zone if this is
   // defined, otherwise returns 0.
   PowerLineFrequency GetPowerLineFrequencyForLocation() const;
 };
 
 }  // namespace media
 
 #endif  // MEDIA_CAPTURE_VIDEO_VIDEO_CAPTURE_DEVICE_H_