Add still image capture interface for VideoCaptureDevice.

media/video/capture/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 198 matching lines @@
         const VideoCaptureFormat& buffer_format,
         const scoped_refptr<media::VideoFrame>& frame,
         base::TimeTicks timestamp) = 0;
 
     // An error has occurred that cannot be handled and VideoCaptureDevice must
     // be StopAndDeAllocate()-ed. |reason| is a text description of the error.
     virtual void OnError(const std::string& reason) = 0;
 
     // VideoCaptureDevice requests the |message| to be logged.
     virtual void OnLog(const std::string& message) {}
+
+    // The video stream has been muted. After this callback, no more
+    // OnIncomingCapturedData() will be called. This may happen when
+    // CaptureImage() is being called. After the still image has been

[wuchengli, 2014/09/11 08:50:05]

s/is being/has/

80 char alignment. Run git cl format

[Owen Lin, 2014/09/12 09:07:55]

I think git cl won't help us on comment.

+    // captured,  the video stream will be resumed and the client would be

[wuchengli, 2014/09/11 08:50:05]

Remove the extra space. I think the order should be switched. That is, the
client will be notified by OnUnmute() and the video stream will be resumed.

[Owen Lin, 2014/09/12 09:07:55]

Done. Thanks.

+    // notified by OnUnmute().
+    virtual void OnMute() {}
+
+    // The video stream has resumed.
+    virtual void OnUnmute() {}
+  };
+
+  class MEDIA_EXPORT ImageClient {
+   public:
+    virtual ~ImageClient() {}
+
+    // Callback function to notify the client the caputred image is available.
+    virtual void OnIncomingCapturedData(const uint8* data,
+                                        int length,
+                                        const ImageCaptureFormat& format,
+                                        int rotation,
+                                        base::TimeTicks timestamp) = 0;
+
+    // Callback function to notify client the failure of the image capturing.
+    // The VideoCaptureDevice must be StopAndDeAllocate()-ed. |reason| is a
+    // text description of the error.
+    virtual void OnError(const std::string& reason) = 0;
   };
 
   // Creates a VideoCaptureDevice object.
   // Return NULL if the hardware is not available.
   static VideoCaptureDevice* Create(
       scoped_refptr<base::SingleThreadTaskRunner> ui_task_runner,
       const Name& device_name);
   virtual ~VideoCaptureDevice();
 
   // Gets the names of all video capture devices connected to this computer.
   static void GetDeviceNames(Names* device_names);
 
   // Gets the supported formats of a particular device attached to the system.
   // This method should be called before allocating or starting a device. In
   // case format enumeration is not supported, or there was a problem, the
   // formats array will be empty.
   static void GetDeviceSupportedFormats(const Name& device,
                                         VideoCaptureFormats* supported_formats);
 
+  // Gets the supported formats for still image of a particular device attached
+  // to the system.
+  static void GetDeviceSupportedImageFormats(

[wuchengli, 2014/09/11 08:50:05]

Does this compile? You need to implement it somewhere.

[Owen Lin, 2014/09/12 09:07:55]

Yes. It compiles. I don't need if no one use it.

+      const Name& device,
+      ImageCaptureFormats* supported_formats);
+
   // Prepares the camera for use. After this function has been called no other
   // applications can use the camera. StopAndDeAllocate() must be called before
   // the object is deleted.
   virtual void AllocateAndStart(const VideoCaptureParams& params,
                                 scoped_ptr<Client> client) = 0;
 
   // Deallocates the camera, possibly asynchronously.
   //
   // This call requires the device to do the following things, eventually: put
   // camera 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
   // happens first.
   virtual void StopAndDeAllocate() = 0;
 
   // Gets the power line frequency from the current system time zone if this is
   // defined, otherwise returns 0.
   int GetPowerLineFrequencyForLocation() const;
 
+  // Initializes the device for still image capture for the given image format.
+  // This function must be called between AllocateAndStart() and
+  // StopAndDeAllocate().
+  virtual void InitializeImageCapture(const ImageCaptureFormat& image_format,
+                                      scoped_ptr<ImageClient> client) {}
+
+  // Releases resources for image capture. The ImageClient passed from
+  // InitializeImageCapture would be freed. This method must be called between
+  // InitializeImageCapture() and StopAndDeAllocate().
+  virtual void CloseImageCapture() {}

[wuchengli, 2014/09/11 08:50:05]

s/CloseImageCapture/ReleaseImageCapture/. Close should be opposite to Open. I
think Release is better.

[Owen Lin, 2014/09/12 09:07:55]

Sure. However, I remember this is the name you suggest. :D

+
+  // Gets one image from the device asynchronously. It will return the image

[wuchengli, 2014/09/11 08:50:05]

More readable to put a blank line after "asynchronously" like StopAndDeAllocate.

+  // by the ImageClient::OnIncomingCapturedData() callback.
+  // If the video stream has to be stopped to capture the still image, the
+  // Client::OnMute() and Client::OnUnmute() will be called.

[wuchengli, 2014/09/11 08:50:05]

s/Client/ImageClient/

[Owen Lin, 2014/09/12 09:07:55]

It's Client. The callback is go to the client of the video stream.

+  //
+  // This function must be called between InitializeImageCapture() and
+  // CloseImageCapture().
+  virtual void CaptureImage() {}
+
  protected:
   static const int kPowerLine50Hz = 50;
   static const int kPowerLine60Hz = 60;
 };
 
 }  // namespace media
 
 #endif  // MEDIA_VIDEO_CAPTURE_VIDEO_CAPTURE_DEVICE_H_