Pepper: add Image Capture interfaces.

API proposal:
https://docs.google.com/a/chromium.org/document/d/1deeCrsvT9xA77UP4yWMhqbHgS3FvYCTF_8meIMQRrDo/edit#

BUG=387547
TEST=Build chrome, run PPAPITest, and run an app that uses ppapi.

Review URL: https://codereview.chromium.org/391323002

Cr-Commit-Position: refs/heads/master@{#290186}
git-svn-id: svn://svn.chromium.org/chrome/trunk/src@290186 0039d316-1c4b-4281-b951-d872f2087c98

3 files changed, 503 insertions, 0 deletions

diff --git a/ppapi/c/private/ppb_camera_capabilities_private.h b/ppapi/c/private/ppb_camera_capabilities_private.h
new file mode 100644
index 0000000..542c69e
--- /dev/null
+++ b/ppapi/c/private/ppb_camera_capabilities_private.h
@@ -0,0 +1,106 @@
+/* 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.
+ */
+
+/* From private/ppb_camera_capabilities_private.idl,
+ *   modified Thu Aug 14 11:40:27 2014.
+ */
+
+#ifndef PPAPI_C_PRIVATE_PPB_CAMERA_CAPABILITIES_PRIVATE_H_
+#define PPAPI_C_PRIVATE_PPB_CAMERA_CAPABILITIES_PRIVATE_H_
+
+#include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_instance.h"
+#include "ppapi/c/pp_macros.h"
+#include "ppapi/c/pp_resource.h"
+#include "ppapi/c/pp_size.h"
+#include "ppapi/c/pp_stdint.h"
+
+#define PPB_CAMERACAPABILITIES_PRIVATE_INTERFACE_0_1 \
+    "PPB_CameraCapabilities_Private;0.1"
+#define PPB_CAMERACAPABILITIES_PRIVATE_INTERFACE \
+    PPB_CAMERACAPABILITIES_PRIVATE_INTERFACE_0_1
+
+/**
+ * @file
+ * This file defines the PPB_CameraCapabilities_Private interface for
+ * establishing an image capture configuration resource within the browser.
+ */
+
+
+/**
+ * @addtogroup Interfaces
+ * @{
+ */
+/**
+ * The <code>PPB_CameraCapabilities_Private</code> interface contains pointers
+ * to several functions for getting the image capture capabilities within the
+ * browser.
+ */
+struct PPB_CameraCapabilities_Private_0_1 {
+  /**
+   * Creates a PPB_CameraCapabilities_Private resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a
+   * PPB_CameraCapabilities_Private resource if successful, 0 if failed.
+   */
+  PP_Resource (*Create)(PP_Instance instance);
+  /**
+   * IsCameraCapabilities() determines if the given resource is a
+   * <code>PPB_CameraCapabilities_Private</code>.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to an image
+   * capture capabilities resource.
+   *
+   * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
+   * resource is an <code>PP_CameraCapabilities_Private</code> resource,
+   * otherwise <code>PP_FALSE</code>.
+   */
+  PP_Bool (*IsCameraCapabilities)(PP_Resource resource);
+  /**
+   * GetSupportedPreviewSizes() returns the supported preview sizes for the
+   * given <code>PPB_CameraCapabilities_Private</code>.
+   *
+   * @param[in] capabilities A <code>PP_Resource</code> corresponding to an
+   * image capture capabilities resource.
+   * @param[out] array_size The size of preview size array.
+   * @param[out] An array of <code>PP_Size</code> corresponding to the
+   * supported preview sizes in pixels. The ownership of the array belongs to
+   * <code>PPB_CameraCapabilities_Private</code> and the caller should not
+   * free it. When a PPB_CameraCapabilities_Private is deleted, the array
+   * returning from this is no longer valid.
+   */
+  void (*GetSupportedPreviewSizes)(PP_Resource capabilities,
+                                   int32_t* array_size,
+                                   struct PP_Size* preview_sizes[]);
+  /**
+   * GetSupportedJpegSize() returns the supported JPEG sizes for the given
+   * <code>PPB_CameraCapabilities_Private</code>.
+   *
+   * @param[in] capabilities A <code>PP_Resource</code> corresponding to an
+   * image capture capabilities resource.
+   * @param[out] array_size The size of JPEG size array. If the output of this
+   * is 0, the camera has no support for generating JPEG images.
+   * @param[out] An array of <code>PP_Size</code> corresponding to the
+   * supported JPEG image sizes in pixels. The ownership of the array belongs
+   * to <code>PPB_CameraCapabilities_Private</code> and the caller should not
+   * free it. When a PPB_CameraCapabilities_Private is deleted, the array
+   * returning from this is no longer valid.
+   */
+  void (*GetSupportedJpegSizes)(PP_Resource capabilities,
+                                int32_t* array_size,
+                                struct PP_Size* jpeg_sizes[]);
+};
+
+typedef struct PPB_CameraCapabilities_Private_0_1
+    PPB_CameraCapabilities_Private;
+/**
+ * @}
+ */
+
+#endif  /* PPAPI_C_PRIVATE_PPB_CAMERA_CAPABILITIES_PRIVATE_H_ */
+
diff --git a/ppapi/c/private/ppb_image_capture_config_private.h b/ppapi/c/private/ppb_image_capture_config_private.h
new file mode 100644
index 0000000..3788b67
--- /dev/null
+++ b/ppapi/c/private/ppb_image_capture_config_private.h
@@ -0,0 +1,115 @@
+/* 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.
+ */
+
+/* From private/ppb_image_capture_config_private.idl,
+ *   modified Wed Aug 13 17:43:55 2014.
+ */
+
+#ifndef PPAPI_C_PRIVATE_PPB_IMAGE_CAPTURE_CONFIG_PRIVATE_H_
+#define PPAPI_C_PRIVATE_PPB_IMAGE_CAPTURE_CONFIG_PRIVATE_H_
+
+#include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_instance.h"
+#include "ppapi/c/pp_macros.h"
+#include "ppapi/c/pp_resource.h"
+#include "ppapi/c/pp_size.h"
+#include "ppapi/c/pp_stdint.h"
+
+#define PPB_IMAGECAPTURECONFIG_PRIVATE_INTERFACE_0_1 \
+    "PPB_ImageCaptureConfig_Private;0.1"
+#define PPB_IMAGECAPTURECONFIG_PRIVATE_INTERFACE \
+    PPB_IMAGECAPTURECONFIG_PRIVATE_INTERFACE_0_1
+
+/**
+ * @file
+ * This file defines the PPB_ImageCaptureConfig_Private interface for
+ * establishing an image capture configuration resource within the browser.
+ */
+
+
+/**
+ * @addtogroup Interfaces
+ * @{
+ */
+/**
+ * The <code>PPB_ImageCaptureConfig_Private</code> interface contains pointers
+ * to several functions for establishing image capture configuration within the
+ * browser. The new configuration will take effect after <code>
+ * PPB_ImageCapture_Private.SetConfig</code> is called.
+ */
+struct PPB_ImageCaptureConfig_Private_0_1 {
+  /**
+   * Creates a PPB_ImageCaptureConfig_Private resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a
+   * PPB_ImageCaptureConfig_Private resource if successful, 0 if failed.
+   */
+  PP_Resource (*Create)(PP_Instance instance);
+  /**
+   * IsImageCaptureConfig() determines if the given resource is a
+   * <code>PPB_ImageCaptureConfig_Private</code>.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to an image
+   * capture config resource.
+   *
+   * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
+   * resource is an <code>ImageCaptureConfig_Private</code> resource, otherwise
+   * <code>PP_FALSE</code>.
+   */
+  PP_Bool (*IsImageCaptureConfig)(PP_Resource resource);
+  /**
+   * GetPreviewSize() returns the preview image size in pixels for the given
+   * <code>PPB_ImageCaptureConfig_Private</code>.
+   *
+   * @param[in] config A <code>PP_Resource</code> corresponding to an image
+   * capture config resource.
+   * @param[out] preview_size A <code>PP_Size</code> that indicates the
+   * requested preview image size.
+   */
+  void (*GetPreviewSize)(PP_Resource config, struct PP_Size* preview_size);
+  /**
+   * SetPreviewSize() sets the preview image size for the given <code>
+   * PPB_ImageCaptureConfig_Private</code>.
+   *
+   * @param[in] config A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_ImageCaptureConfig_Private</code>.
+   * @param[in] preview_size A <code>PP_Size</code> that indicates the requested
+   * preview image size.
+   */
+  void (*SetPreviewSize)(PP_Resource config,
+                         const struct PP_Size* preview_size);
+  /**
+   * GetJpegSize() returns the JPEG image size in pixels for the given
+   * <code>PPB_ImageCaptureConfig_Private</code>.
+   *
+   * @param[in] config A <code>PP_Resource</code> corresponding to an image
+   * capture config resource.
+   * @param[out] jpeg_size A <code>PP_Size</code> that indicates the current
+   * JPEG image size.
+   */
+  void (*GetJpegSize)(PP_Resource config, struct PP_Size* jpeg_size);
+  /**
+   * SetJpegSize() sets the JPEG image size for the given
+   * <code>PPB_ImageCaptureConfig_Private</code>.
+   *
+   * @param[in] config A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_ImageCaptureConfig_Private</code>.
+   * @param[in] jpeg_size A <code>PP_Size</code> that indicates the requested
+   * JPEG image size.
+   */
+  void (*SetJpegSize)(PP_Resource config, const struct PP_Size* jpeg_size);
+};
+
+typedef struct PPB_ImageCaptureConfig_Private_0_1
+    PPB_ImageCaptureConfig_Private;
+/**
+ * @}
+ */
+
+#endif  /* PPAPI_C_PRIVATE_PPB_IMAGE_CAPTURE_CONFIG_PRIVATE_H_ */
+
diff --git a/ppapi/c/private/ppb_image_capture_private.h b/ppapi/c/private/ppb_image_capture_private.h
new file mode 100644
index 0000000..190c9a6
--- /dev/null
+++ b/ppapi/c/private/ppb_image_capture_private.h
@@ -0,0 +1,282 @@
+/* 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.
+ */
+
+/* From private/ppb_image_capture_private.idl,
+ *   modified Wed Aug 13 17:26:13 2014.
+ */
+
+#ifndef PPAPI_C_PRIVATE_PPB_IMAGE_CAPTURE_PRIVATE_H_
+#define PPAPI_C_PRIVATE_PPB_IMAGE_CAPTURE_PRIVATE_H_
+
+#include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_completion_callback.h"
+#include "ppapi/c/pp_instance.h"
+#include "ppapi/c/pp_macros.h"
+#include "ppapi/c/pp_resource.h"
+#include "ppapi/c/pp_stdint.h"
+#include "ppapi/c/pp_var.h"
+
+#define PPB_IMAGECAPTURE_PRIVATE_INTERFACE_0_1 "PPB_ImageCapture_Private;0.1"
+#define PPB_IMAGECAPTURE_PRIVATE_INTERFACE \
+    PPB_IMAGECAPTURE_PRIVATE_INTERFACE_0_1
+
+/**
+ * @file
+ * Defines the <code>PPB_ImageCapture_Private</code> interface. Used for
+ * acquiring a single still image from a camera source.
+ */
+
+
+/**
+ * @addtogroup Typedefs
+ * @{
+ */
+/**
+ * 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:
+ *  |user_data| The same pointer that was passed into <code>
+ *  PPB_ImageCapture_Private.Create()</code>.
+ *  |sequence_id| The sequence ID of the image capture, same as the one from
+ *  CaptureStillImage.
+ */
+typedef void (*PPB_ImageCapture_Private_ShutterCallback)(void* user_data,
+                                                         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:
+ *  |user_data| The same pointer that was passed into <code>
+ *  PPB_ImageCapture_Private.Create()</code>.
+ *  |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)(void* user_data,
+                                                         int64_t sequence_id,
+                                                         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:
+ *  |user_data| The same pointer that was passed into <code>
+ *  PPB_ImageCapture_Private.Create()</code>.
+ *  |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)(void* user_data,
+                                                      int64_t sequence_id,
+                                                      PP_Resource jpeg);
+
+/**
+ * Callback function for <code>PPB_ImageCapture_Private.CaptureStillImage
+ * </code> to indicate the image capture has failed.
+ *
+ * Parameters:
+ *  |user_data| The same pointer that was passed into <code>
+ *  PPB_ImageCapture_Private.Create()</code>.
+ *  |sequence_id| The sequence ID of the image capture, same as the one from
+ *  CaptureStillImage.
+ *  |int32_t| An error code from <code>pp_errors.h</code>.
+ */
+typedef void (*PPB_ImageCapture_Private_ErrorCallback)(void* user_data,
+                                                       int64_t sequence_id,
+                                                       int32_t pp_error);
+/**
+ * @}
+ */
+
+/**
+ * @addtogroup Interfaces
+ * @{
+ */
+/**
+ * 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.
+ */
+struct PPB_ImageCapture_Private_0_1 {
+  /**
+   * 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.
+   * @param[in] error_callback A <code>PPB_ImageCapture_Private_ErrorCallback
+   * </code> callback to indicate the image capture has failed.
+   * @param[inout] user_data An opaque pointer that will be passed to the
+   * callbacks of PPB_ImageCapture_Private.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a
+   * PPB_ImageCapture_Private resource if successful, 0 if failed.
+   */
+  PP_Resource (*Create)(PP_Instance instance,
+                        struct PP_Var camera_source_id,
+                        PPB_ImageCapture_Private_ErrorCallback error_callback,
+                        void* user_data);
+  /**
+   * 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)(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.
+   * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
+   * completion of <code>Close()</code>.
+   *
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   */
+  int32_t (*Close)(PP_Resource resource, struct PP_CompletionCallback callback);
+  /**
+   * 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)(PP_Resource image_capture,
+                       PP_Resource config,
+                       struct 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)(PP_Resource image_capture,
+                       PP_Resource* config,
+                       struct 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>GetCameraCapabilities()</code>.
+   *
+   * @return An int32_t containing a result code from <code>pp_errors.h</code>.
+   */
+  int32_t (*GetCameraCapabilities)(PP_Resource image_capture,
+                                   PP_Resource* capabilities,
+                                   struct 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. If there is an error after the capture is in
+   * progress, the error callback passed to <code>
+   * PPB_ImageCapture_Private.Create()</code> will be invoked. All the callbacks
+   * are invoked by the thread that calls this function.
+   *
+   * 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)(
+      PP_Resource image_capture,
+      PPB_ImageCapture_Private_ShutterCallback shutter_callback,
+      PPB_ImageCapture_Private_PreviewCallback preview_callback,
+      PPB_ImageCapture_Private_JpegCallback jpeg_callback,
+      int64_t* sequence_id);
+};
+
+typedef struct PPB_ImageCapture_Private_0_1 PPB_ImageCapture_Private;
+/**
+ * @}
+ */
+
+#endif  /* PPAPI_C_PRIVATE_PPB_IMAGE_CAPTURE_PRIVATE_H_ */
+