Pepper: add Image Capture interfaces.

ppapi/api/private/ppb_image_capture_private.idl

Index: ppapi/api/private/ppb_image_capture_private.idl
diff --git a/ppapi/api/private/ppb_image_capture_private.idl b/ppapi/api/private/ppb_image_capture_private.idl
new file mode 100644
index 0000000000000000000000000000000000000000..af3a571cc0e8a3cdb125b1426d0b5c084e5a6141
--- /dev/null
+++ b/ppapi/api/private/ppb_image_capture_private.idl
@@ -0,0 +1,226 @@
+/* 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_Private</code> interface. Used for
+ * acquiring a single still image from a camera source.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  M39 = 0.1
+};
+
+/**
+ * Callback function for <code>PPB_ImageCapture_Private.CaptureStillImage
+ * </code> to indicate the image has been captured from the sensor. This is a
+ * good opportunity to play a shutter sound or give other feedback of camera
+ * operation. This will occur after the image was captured, but before the
+ * actual data is available.
+ *
+ * Parameters:
+ *  |image_capture| the PPB_ImageCapture_Private resource.
+ *  |sequence_id| The sequence ID of the image capture, same as the one from
+ *  CaptureStillImage.
+ */
+typedef void PPB_ImageCapture_Private_ShutterCallback(
+    [in] PP_Resource image_capture,
+    [in] int64_t sequence_id);
+
+/**
+ * Callback function for <code>PPB_ImageCapture_Private.CaptureStillImage
+ * </code> to deliver a preview image. The client can use this to show the
+ * captured image. See <code>PPB_ImageCapture_Private.CaptureStillImage
+ * </code> for more information.
+ *
+ * Parameters:
+ *  |image_capture| the PPB_ImageCapture_Private resource.
+ *  |sequence_id| The sequence ID of the image capture, same as the one from
+ *  CaptureStillImage.
+ *  |preview| A <code>PP_Resource</code> corresponding to a VideoFrame
+ *  resource used to store the preview image.
+ */
+typedef void PPB_ImageCapture_Private_PreviewCallback(
+    [in] PP_Resource image_capture,
+    [in] int64_t sequence_id,
+    [in] PP_Resource preview);
+
+/**
+ * Callback function for <code>PPB_ImageCapture_Private.CaptureStillImage
+ * </code> to deliver a still JPEG image. See <code>
+ * PPB_ImageCapture_Private.CaptureStillImage</code> for more information.
+ *
+ * Parameters:
+ *  |image_capture| the PPB_ImageCapture_Private resource.
+ *  |sequence_id| The sequence ID of the image capture, same as the one from
+ *  CaptureStillImage.
+ *  |jpeg| A <code>PP_Resource</code> corresponding to a VideoFrame
+ *  resource used to store the JPEG image.
+ */
+typedef void PPB_ImageCapture_Private_JpegCallback(
+    [in] PP_Resource image_capture,
+    [in] int64_t sequence_id,
+    [in] PP_Resource jpeg);
+

[Justin Chuang, 2014/08/11 08:32:35]

We do not have *_ErrorCallback when HW is broken or other unexpected case (like
OOM). 
The API may not know the error immediately when CaptureStillImage returns. 

Do we need the error callback? Can we merge it with one of the existing 3
callbacks? 

[wuchengli, 2014/08/12 07:27:02]

I added an error callback to Create for image capture. For the error callback
notifying camera is disconnected or disabled, I'll add it in the future
patchset.

+/**
+ * To capture a still image with this class, use the following steps.
+ * 1. Get a PPB_ImageCapture_Private object by Create().
+ * 2. Call GetCameraCapabilities to get the supported preview sizes.
+ * 3. For optimal performance, set one of the supported preview size as the
+ *    constraints of getUserMedia. Use the created MediaStreamVideoTrack for
+ *    camera previews.
+ * 4. Set the same preview size and other settings by SetConfig.
+ * 5. Call CaptureStillImage to capture a still image. Play the shutter sound in
+ *    the shutter callback. The image from the preview callback can be used for
+ *    display. JPEG image will be returned to the JPEG callback.
+ */
+interface PPB_ImageCapture_Private {
+  /**
+   * Creates a PPB_ImageCapture_Private resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   * @param[in] camera_source_id A <code>PP_Var</code> identifying a camera
+   * source. The type is string. The ID can be obtained from
+   * MediaStreamTrack.getSources() or MediaStreamVideoTrack.id. If a
+   * MediaStreamVideoTrack is associated with the same source and the track
+   * is closed, this PPB_ImageCapture_Private object can still do image capture.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a
+   * PPB_ImageCapture_Private resource if successful, 0 if failed.
+   */
+  PP_Resource Create([in] PP_Instance instance,
+                     [in] PP_Var camera_source_id);
+
+  /**
+   * 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);
+
+  /**
+   * Disconnects from the camera and cancels all pending capture requests.
+   * After this returns, no callbacks will be called. If <code>
+   * PPB_ImageCapture_Private</code> is destroyed and is not closed yet, this
+   * function will be automatically called. Calling this more than once has no
+   * effect.
+   *
+   * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
+   * image capture resource.
+   */
+  void Close([in] PP_Resource resource);
+
+  /**
+   * Sets the configuration of the image capture.
+   * 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 <code>PP_ImageCaptureConfig_Private</code> 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>CaptureStillImage()</code>.
+   * If an error is returned, the configuration will not be changed.
+   */
+  int32_t SetConfig([in] PP_Resource image_capture,
+                    [in] PP_Resource config,
+                    [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets the configuration of the image capture.
+   *
+   * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
+   * image capture resource.
+   * @param[out] config A <code>PP_ImageCaptureConfig_Private</code> for storing
+   * the current image capture config on success. Otherwise, the values 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 camera capabilities.
+   *
+   * The camera capabilities do not change for a given camera source.
+   *
+   * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
+   * image capture resource.
+   * @param[out] capabilities A <code>PPB_CameraCapabilities_Private</code> for
+   * storing the image capture capabilities on success. Otherwise, the value
+   * will not be changed.
+   * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
+   * completion of <code>GetCapabilities()</code>.
+   *
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   */
+  int32_t GetCameraCapabilities([in] PP_Resource image_capture,
+                                [out] PP_Resource capabilities,
+                                [in] PP_CompletionCallback callback);
+
+  /**
+   * Captures a still JPEG image from the camera.
+   *
+   * Triggers an asynchronous image capture. The camera will initiate a series
+   * of callbacks to the application as the image capture progresses. The
+   * callbacks will be invoked in the order of shutter callback, preview
+   * callback, and JPEG callback. The shutter callback occurs after the image is
+   * captured. This can be used to trigger a sound to let the user know that
+   * image has been captured. The preview callback occurs when a scaled, fully
+   * processed preview image is available. The JPEG callback occurs when the
+   * compressed image is available.
+   *
+   * The size of the preview image in preview callback is determined by
+   * <code>PPB_ImageCaptureConfig_Private.SetPreviewSize</code>. The format is
+   * decided by the camera and can be got from <code>PPB_VideoFrame.GetFormat
+   * </code>. The size of the JPEG image is determined by <code>
+   * PPB_ImageCaptureConfig_Private.SetJpegSize</code>.
+   *
+   * The camera may need to stop and re-start streaming during image capture. If
+   * some MediaStreamVideoTrack are associated with the camera source, they will
+   * receive mute and unmute events. The mute event will be received before all
+   * the callbacks. The unmute event will be received after all the callbacks.
+   * The preview image will not be sent to the video tracks associated with the
+   * camera.
+   *
+   * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
+   * image capture resource.
+   * @param[in] shutter_callback A <code>
+   * PPB_ImageCapture_Private_ShutterCallback</code> callback to indicate the
+   * image has been taken.
+   * @param[in] preview_callback A <code>
+   * PPB_ImageCapture_Private_PreviewCallback</code> callback to return a
+   * preview of the captured image.
+   * @param[in] jpeg_callback A <code>
+   * PPB_ImageCapture_Private_JpegCallback</code> callback to return captured
+   * JPEG image.
+   * @param[out] sequence_id The sequence ID is a unique monotonically
+   * increasing value starting from 0, incremented every time a new request like
+   * image capture is submitted.
+   *
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   * PP_OK means the callbacks will be triggered. Other values mean the
+   * callbacks will not be triggered.
+   */
+  int32_t CaptureStillImage(
+      [in] PP_Resource image_capture,
+      [in] PPB_ImageCapture_Private_ShutterCallback shutter_callback,
+      [in] PPB_ImageCapture_Private_PreviewCallback preview_callback,
+      [in] PPB_ImageCapture_Private_JpegCallback jpeg_callback,

[dmichael (off chromium), 2014/08/08 21:13:05]

You might want to consider modeling this after
PPB_Messaging::RegisterMessageHandler and PPP_MessageHandler...
https://code.google.com/p/chromium/codesearch#chromium/src/ppapi/api/ppb_mess...
https://code.google.com/p/chromium/codesearch#chromium/src/ppapi/api/ppp_mess...
...the main advantage being consistency. That also makes it easy to specify a
different thread to receive events, but you probably don't care about that. I
also think it's helpful that it has a void* user_data pointer passed in and out,
to make it easy for the plugin to have something like an object that handles the
callbacks without needing to map from PP_Resource.

But what you have may be good enough for a Private API.

Speaking of threads...  I'm guessing your intent is that these callbacks are
invoked on the same thread that CaptureStillImage is called on? It would be good
to document that.

[wuchengli, 2014/08/12 07:27:02]

Do you mean something like my patchset #3?
https://codereview.chromium.org/391323002/diff/140001/ppapi/api/private/ppp_i...
Or do you mean I should have a single HandleMessage to handle all different
kinds of callbacks? I assume you meant the former. I changed to the current code
so the plugin can just implement the callbacks they need. Also, several other
classes use the pattern like this. Ex: PPB_Audio_Callback. I'll submit this
first and discuss with you after you are back from OOO. 
All good points. I added user_data and message_loop. CaptureStillImage callbacks
will be called on the thread of message_loop. I also added comments about
threading.

+      [out] int64_t sequence_id);
+};