Pepper: add Image Capture interfaces.

ppapi/api/ppb_image_capture.idl

Index: ppapi/api/ppb_image_capture.idl
diff --git a/ppapi/api/ppb_image_capture.idl b/ppapi/api/ppb_image_capture.idl
new file mode 100644
index 0000000000000000000000000000000000000000..1adcd2365572bf200782a723d227cc190bc62e38
--- /dev/null
+++ b/ppapi/api/ppb_image_capture.idl
@@ -0,0 +1,120 @@
+/* Copyright 2014 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.
+ */
+
+/**
+ * Defines the <code>PPB_ImageCapture</code> interface. Used for taking
+ * a picture from the source of a MediaStream video track.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  [channel=dev] M38 = 0.1
+};
+
+[version=0.1]
+interface PPB_ImageCapture {
+  /**
+   * Creates a PPB_ImageCapture resource.
+   *
+   * @param[in] resoutce A <code>PP_Resource</code> identifying one
+   * MediaStream video track.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a
+   * PPB_ImageCapture resource if successful, 0 if failed.
+   */
+  PP_Resource Create([in] PP_Resource media_stream_video_track);
+
+  /**
+   * Determines if a resource is an image capture resource.
+   *
+   * @param[in] resource The <code>PP_Resource</code> to test.
+   *
+   * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
+   * resource is an image capture resource or <code>PP_FALSE</code>
+   * otherwise.
+   */
+  PP_Bool IsImageCapture([in] PP_Resource resource);
+
+  /**
+   * Sets the configuration of the photos and the camera device.

[Owen Lin, 2014/07/16 08:20:45]

[optional] "Sets the configuration of the camera device." sounds good enough. 

+   * If <code>SetConfig()</code> is not called, default settings will be used.
+   *
+   * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
+   * image capture resource.
+   * @param[in] config A PP_ImageCaptureConfig object.
+   * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
+   * completion of <code>SetConfig()</code>.
+   *
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   * Returns <code>PP_ERROR_INPROGRESS</code> if there is a pending call of
+   * <code>SetConfig()</code> or <code>TakePhoto()</code>.

[Owen Lin, 2014/07/16 08:20:44]

What's the definition of the pending call to TakePhoto(). Until the
picture_callback is being called?

+   * If an error is returned, all configuration will not be changed.
+   */
+  int32_t SetConfig([in] PP_Resource image_capture,
+                    [in] PP_Resource config,
+                    [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets attribute values for given attribute names.

[Owen Lin, 2014/07/16 08:20:45]

Where are the attribute values and attribute names? Inside the config?
In that case, you should change the type to [inout]. I was assuming it contains
all attributes available. (Not just the given attribute names.)

+   *
+   * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
+   * image capture resource.
+   * @param[out] value A PP_ImageCaptureConfig for storing the current image
+   * capture config on success. Otherwise, the value will not be changed.
+   * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
+   * completion of <code>GetConfig()</code>.
+   *
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   */
+  int32_t GetConfig([in] PP_Resource image_capture,
+                    [out] PP_Resource config,
+                    [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets the capabilities of the capture device.
+   *
+   * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
+   * image capture resource.
+   * @param[out] value A PP_CameraCapabilities for storing the camera
+   * capabilities on success. Otherwise, the value will not be changed.
+   * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
+   * completion of <code>GetConfig()</code>.
+   *
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   */
+  int32_t GetCapabilities([in] PP_Resource image_capture,
+                          [out] PP_Resource capabilities,
+                          [in] PP_CompletionCallback callback);
+
+  /**
+   * Takes a photo from the capture device.
+   *
+   * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
+   * image capture resource.
+   * @param[out] postview A <code>PP_Resource</code> corresponding to a
+   * VideoFrame resource used to store the postview.

[Owen Lin, 2014/07/16 08:20:44]

Did you consider to make it a ImageData? Client can use graphics_2d to render
it. Do we need to duplicate the vidoe frame from the video track ?

+   * @param[out] photo A <code>PP_Resource</code> corresponding to a VideoFrame
+   * resource used to store the encoded picture. The default format is JPEG.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called when

[Owen Lin, 2014/07/16 08:20:44]

s/callback/shutter_callback/

+   * the picture is taken and the camera can be moved without making the picture
+   * blurry. The client can play a shutter sound if needed.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called to

[Owen Lin, 2014/07/16 08:20:44]

s/callback/postview_callback/. Can you move most of your comment to param
postview. Since it is actually a completion callback and returns nothing.

+   * return a postview video frame. The client can use this to show the captured
+   * photo. The format and the size are decided by the MediaStream video track.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon

[Owen Lin, 2014/07/16 08:20:44]

photo_callback

+   * completion of TakePhoto(). <code>photo</code> will contain the encoded
+   * picture.
+   *
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   */
+  int32_t TakePhoto([in] PP_Resource image_capture,
+                    [out] PP_Resource postview,
+                    [out] PP_Resource photo,
+                    [in] PP_CompletionCallback shutter_callback,
+                    [in] PP_CompletionCallback postview_callback,
+                    [in] PP_CompletionCallback picture_callback);

[Owen Lin, 2014/07/16 08:20:45]

why not using the name "photo_callback".

+};
+