Pepper: add Image Capture interfaces.

ppapi/api/private/ppp_image_capture_private.idl

Index: ppapi/api/private/ppp_image_capture_private.idl
diff --git a/ppapi/api/private/ppp_image_capture_private.idl b/ppapi/api/private/ppp_image_capture_private.idl
new file mode 100644
index 0000000000000000000000000000000000000000..26b790f5321f2a2358504f9a5a60bde1c8dc6233
--- /dev/null
+++ b/ppapi/api/private/ppp_image_capture_private.idl
@@ -0,0 +1,80 @@
+/* Copyright (c) 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.
+ */
+
+/**
+ * This file defines the <code>PPP_ImageCapture_Private</code> interface.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  M39 = 0.1
+};
+
+/**
+ * PPP_ImageCapture_Private structure contains the function pointers that the
+ * plugin MUST implement to provide services needed by the image capture
+ * implementation.

[Justin Chuang, 2014/08/03 10:46:45]

I am not familiar with PPAPI, but I suspect it should be done in a way similar
to ppp_image_capture_private.idl => GetPermissionSettings().

In PPP_Flash_BrowserOperations::GetPermissionSettings(), ppp just provides the
prototype of callback, and provides API to *register* the callback function
pointer implemented elsewhere.

[wuchengli, 2014/08/06 08:14:58]

Good idea. This patchset is similar to PPP_VideoDecoder, which requires the
implementations of all callbacks to work. Image capture callbacks are optional
and should follow your suggestion.

+ *
+ * See PPB_ImageCapture_Private for general usage tips.
+ */
+interface PPP_ImageCapture_Private {
+  /**
+   * Callback function for <code>PPB_ImageCapture_Private.TakePhoto</code>.
+   * Called as near as possible to the moment when a photo is captured from the
+   * sensor. This is a good opportunity to play a shutter sound or give other
+   * feedback of camera operation. This may be some time after the photo was

[Pawel Osciak, 2014/08/03 08:34:38]

s/may be some time/will occur/

[wuchengli, 2014/08/06 08:14:58]

Done.

+   * triggered, but some time before the actual data is available.

[Pawel Osciak, 2014/08/03 08:34:38]

s/some time//

[Pawel Osciak, 2014/08/03 08:34:39]

s/triggered/captured/ I assume?

[wuchengli, 2014/08/06 08:14:58]

Done.

[wuchengli, 2014/08/06 08:14:58]

Done.

+   *
+   * Parameters:
+   *  |instance| the plugin instance to which the callback is responding.
+   *  |image_capture| the PPB_ImageCapture_Private resource.
+   *  |sequence_id| The sequence ID of the image capture, same as the one from
+   *  TakePhoto.
+   */
+  void OnShutter(
+      [in] PP_Instance instance,
+      [in] PP_Resource image_capture,
+      [in] int64_t sequence_id);
+
+  /**
+   * Callback function for <code>PPB_ImageCapture_Private.TakePhoto</code>.
+   * Called for the camera to deliver a postview picture. The client can use
+   * this to show the captured photo. The format and the size are decided
+   * by the associated MediaStream video tracks. Call
+   * <code>PPB_VideoFrame</code> functions to know the exact format and size.
+   *
+   * Parameters:
+   *  |instance| the plugin instance to which the callback is responding.
+   *  |image_capture| the PPB_ImageCapture_Private resource.
+   *  |postview| A <code>PP_Resource</code> corresponding to a VideoFrame
+   *  resource used to store the postview picture.
+   *  |sequence_id| The sequence ID of the image capture, same as the one from
+   *  TakePhoto.
+   */
+  void OnPostviewPicture(
+      [in] PP_Instance instance,
+      [in] PP_Resource image_capture,
+      [in] PP_Resource postview,

[Pawel Osciak, 2014/08/03 08:34:38]

What's the format? How is this returned after use?

[Justin Chuang, 2014/08/03 10:46:45]

The format should be similar to PPB_MediaStreamVideoTrack::GetFrame() to the
associated camera source.

So it probably needs extra comments to describe that the image resolution of
Postview is the same as associated camera_source_id in
PPB_ImageCapture_Private::Create(). 

[wuchengli, 2014/08/06 08:14:58]

Several media stream video tracks can be associated with the same camera. I
added SetPreviewSize, GetPreviewSize, and GetSupportedPreviewSizes. Postview is
renamed to Preview. The format is the original format from the camera. It can be
read from PPB_VideoFrame.GetFormat. If there is a need to specify the format, we
can add it at that time.

Destroying the VideoFrame object will release the buffer. CaptureStillImage is
not called very often like video capture. If the performance is a problem in the
future, we can add something like PPB_MediaStreamVideoTrack.RecycleFrame and
GetFrame.

I added more comments in PPB_ImageCapture_Private.CaptureStillImage.

[Justin Chuang, 2014/08/07 03:34:46]

Can you elaborate the relationship between the *Preview API and the always-on
preview window in camera app (which supposedly is implemented with
MediaStreamVideoTrack)? 

Will the Preview image you get here be grabbed by the live streaming path? Or
will it be obtained by different data path, such as resizing the captured still
image? 

If it's the former case, then there can be only one fixed resolution per device
for the streaming even when multiple Media Stream are attached to one device. I
suppose the master client will be the MediaStreamVideoTrack used by the
always-on camera preview window. Is it correct?

Thanks

+      [in] int64_t sequence_id);
+
+  /**
+   * Callback function for <code>PPB_ImageCapture_Private.TakePhoto</code>.
+   * Called for the camera to deliver a Jpeg picture.
+   *
+   * Parameters:
+   *  |instance| the plugin instance to which the callback is responding.
+   *  |image_capture| the PPB_ImageCapture_Private resource.
+   *  |jpeg| A <code>PP_Resource</code> corresponding to a VideoFrame
+   *  resource used to store the postview picture.
+   *  |sequence_id| The sequence ID of the image capture, same as the one from
+   *  TakePhoto.
+   */
+  void OnJpegPicture(
+      [in] PP_Instance instance,
+      [in] PP_Resource image_capture,
+      [in] PP_Resource jpeg,
+      [in] int64_t sequence_id);
+};