src/ppapi/api/private/ppb_image_capture_private.idl

   1 /* Copyright 2014 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * Defines the <code>PPB_ImageCapture_Private</code> interface. Used for
   8  * acquiring a single still image from a camera source.
   9  */
  10
  11 [generate_thunk]
  12
  13 label Chrome {
  14   M39 = 0.1
  15 };
  16
  17 /**
  18  * Callback function for <code>PPB_ImageCapture_Private.CaptureStillImage
  19  * </code> to indicate the image has been captured from the sensor. This is a
  20  * good opportunity to play a shutter sound or give other feedback of camera
  21  * operation. This will occur after the image was captured, but before the
  22  * actual data is available.
  23  *
  24  * Parameters:
  25  *  |user_data| The same pointer that was passed into <code>
  26  *  PPB_ImageCapture_Private.Create()</code>.
  27  *  |sequence_id| The sequence ID of the image capture, same as the one from
  28  *  CaptureStillImage.
  29  */
  30 typedef void PPB_ImageCapture_Private_ShutterCallback(
  31     [inout] mem_t user_data,
  32     [in] int64_t sequence_id);
  33
  34 /**
  35  * Callback function for <code>PPB_ImageCapture_Private.CaptureStillImage
  36  * </code> to deliver a preview image. The client can use this to show the
  37  * captured image. See <code>PPB_ImageCapture_Private.CaptureStillImage
  38  * </code> for more information.
  39  *
  40  * Parameters:
  41  *  |user_data| The same pointer that was passed into <code>
  42  *  PPB_ImageCapture_Private.Create()</code>.
  43  *  |sequence_id| The sequence ID of the image capture, same as the one from
  44  *  CaptureStillImage.
  45  *  |preview| A <code>PP_Resource</code> corresponding to a VideoFrame
  46  *  resource used to store the preview image.
  47  */
  48 typedef void PPB_ImageCapture_Private_PreviewCallback(
  49     [inout] mem_t user_data,
  50     [in] int64_t sequence_id,
  51     [in] PP_Resource preview);
  52
  53 /**
  54  * Callback function for <code>PPB_ImageCapture_Private.CaptureStillImage
  55  * </code> to deliver a still JPEG image. See <code>
  56  * PPB_ImageCapture_Private.CaptureStillImage</code> for more information.
  57  *
  58  * Parameters:
  59  *  |user_data| The same pointer that was passed into <code>
  60  *  PPB_ImageCapture_Private.Create()</code>.
  61  *  |sequence_id| The sequence ID of the image capture, same as the one from
  62  *  CaptureStillImage.
  63  *  |jpeg| A <code>PP_Resource</code> corresponding to a VideoFrame
  64  *  resource used to store the JPEG image.
  65  */
  66 typedef void PPB_ImageCapture_Private_JpegCallback(
  67     [inout] mem_t user_data,
  68     [in] int64_t sequence_id,
  69     [in] PP_Resource jpeg);
  70
  71 /**
  72  * Callback function for <code>PPB_ImageCapture_Private.CaptureStillImage
  73  * </code> to indicate the image capture has failed.
  74  *
  75  * Parameters:
  76  *  |user_data| The same pointer that was passed into <code>
  77  *  PPB_ImageCapture_Private.Create()</code>.
  78  *  |sequence_id| The sequence ID of the image capture, same as the one from
  79  *  CaptureStillImage.
  80  *  |int32_t| An error code from <code>pp_errors.h</code>.
  81  */
  82 typedef void PPB_ImageCapture_Private_ErrorCallback(
  83     [inout] mem_t user_data,
  84     [in] int64_t sequence_id,
  85     [in] int32_t pp_error);
  86
  87 /**
  88  * To capture a still image with this class, use the following steps.
  89  * 1. Get a PPB_ImageCapture_Private object by Create().
  90  * 2. Call GetCameraCapabilities to get the supported preview sizes.
  91  * 3. For optimal performance, set one of the supported preview size as the
  92  *    constraints of getUserMedia. Use the created MediaStreamVideoTrack for
  93  *    camera previews.
  94  * 4. Set the same preview size and other settings by SetConfig.
  95  * 5. Call CaptureStillImage to capture a still image. Play the shutter sound in
  96  *    the shutter callback. The image from the preview callback can be used for
  97  *    display. JPEG image will be returned to the JPEG callback.
  98  */
  99 interface PPB_ImageCapture_Private {
 100   /**
 101    * Creates a PPB_ImageCapture_Private resource.
 102    *
 103    * @param[in] instance A <code>PP_Instance</code> identifying one instance
 104    * of a module.
 105    * @param[in] camera_source_id A <code>PP_Var</code> identifying a camera
 106    * source. The type is string. The ID can be obtained from
 107    * MediaStreamTrack.getSources() or MediaStreamVideoTrack.id. If a
 108    * MediaStreamVideoTrack is associated with the same source and the track
 109    * is closed, this PPB_ImageCapture_Private object can still do image capture.
 110    * @param[in] error_callback A <code>PPB_ImageCapture_Private_ErrorCallback
 111    * </code> callback to indicate the image capture has failed.
 112    * @param[inout] user_data An opaque pointer that will be passed to the
 113    * callbacks of PPB_ImageCapture_Private.
 114    *
 115    * @return A <code>PP_Resource</code> corresponding to a
 116    * PPB_ImageCapture_Private resource if successful, 0 if failed.
 117    */
 118   PP_Resource Create([in] PP_Instance instance,
 119                      [in] PP_Var camera_source_id,
 120                      [in] PPB_ImageCapture_Private_ErrorCallback error_callback,
 121                      [inout] mem_t user_data);
 122
 123   /**
 124    * Determines if a resource is an image capture resource.
 125    *
 126    * @param[in] resource The <code>PP_Resource</code> to test.
 127    *
 128    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
 129    * resource is an image capture resource or <code>PP_FALSE</code>
 130    * otherwise.
 131    */
 132   PP_Bool IsImageCapture([in] PP_Resource resource);
 133
 134   /**
 135    * Disconnects from the camera and cancels all pending capture requests.
 136    * After this returns, no callbacks will be called. If <code>
 137    * PPB_ImageCapture_Private</code> is destroyed and is not closed yet, this
 138    * function will be automatically called. Calling this more than once has no
 139    * effect.
 140    *
 141    * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
 142    * image capture resource.
 143    * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
 144    * completion of <code>Close()</code>.
 145    *
 146    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
 147    */
 148   int32_t Close([in] PP_Resource resource,
 149                 [in] PP_CompletionCallback callback);
 150
 151   /**
 152    * Sets the configuration of the image capture.
 153    * If <code>SetConfig()</code> is not called, default settings will be used.
 154    *
 155    * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
 156    * image capture resource.
 157    * @param[in] config A <code>PP_ImageCaptureConfig_Private</code> object.
 158    * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
 159    * completion of <code>SetConfig()</code>.
 160    *
 161    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
 162    * Returns <code>PP_ERROR_INPROGRESS</code> if there is a pending call of
 163    * <code>SetConfig()</code> or <code>CaptureStillImage()</code>.
 164    * If an error is returned, the configuration will not be changed.
 165    */
 166   int32_t SetConfig([in] PP_Resource image_capture,
 167                     [in] PP_Resource config,
 168                     [in] PP_CompletionCallback callback);
 169
 170   /**
 171    * Gets the configuration of the image capture.
 172    *
 173    * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
 174    * image capture resource.
 175    * @param[out] config A <code>PP_ImageCaptureConfig_Private</code> for storing
 176    * the current image capture config on success. Otherwise, the values will not
 177    * be changed.
 178    * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
 179    * completion of <code>GetConfig()</code>.
 180    *
 181    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
 182    */
 183   int32_t GetConfig([in] PP_Resource image_capture,
 184                     [out] PP_Resource config,
 185                     [in] PP_CompletionCallback callback);
 186
 187   /**
 188    * Gets the camera capabilities.
 189    *
 190    * The camera capabilities do not change for a given camera source.
 191    *
 192    * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
 193    * image capture resource.
 194    * @param[out] capabilities A <code>PPB_CameraCapabilities_Private</code> for
 195    * storing the image capture capabilities on success. Otherwise, the value
 196    * will not be changed.
 197    * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
 198    * completion of <code>GetCameraCapabilities()</code>.
 199    *
 200    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
 201    */
 202   int32_t GetCameraCapabilities([in] PP_Resource image_capture,
 203                                 [out] PP_Resource capabilities,
 204                                 [in] PP_CompletionCallback callback);
 205
 206   /**
 207    * Captures a still JPEG image from the camera.
 208    *
 209    * Triggers an asynchronous image capture. The camera will initiate a series
 210    * of callbacks to the application as the image capture progresses. The
 211    * callbacks will be invoked in the order of shutter callback, preview
 212    * callback, and JPEG callback. The shutter callback occurs after the image is
 213    * captured. This can be used to trigger a sound to let the user know that
 214    * image has been captured. The preview callback occurs when a scaled, fully
 215    * processed preview image is available. The JPEG callback occurs when the
 216    * compressed image is available. If there is an error after the capture is in
 217    * progress, the error callback passed to <code>
 218    * PPB_ImageCapture_Private.Create()</code> will be invoked. All the callbacks
 219    * are invoked by the thread that calls this function.
 220    *
 221    * The size of the preview image in preview callback is determined by
 222    * <code>PPB_ImageCaptureConfig_Private.SetPreviewSize</code>. The format is
 223    * decided by the camera and can be got from <code>PPB_VideoFrame.GetFormat
 224    * </code>. The size of the JPEG image is determined by <code>
 225    * PPB_ImageCaptureConfig_Private.SetJpegSize</code>.
 226    *
 227    * The camera may need to stop and re-start streaming during image capture. If
 228    * some MediaStreamVideoTrack are associated with the camera source, they will
 229    * receive mute and unmute events. The mute event will be received before all
 230    * the callbacks. The unmute event will be received after all the callbacks.
 231    * The preview image will not be sent to the video tracks associated with the
 232    * camera.
 233    *
 234    * @param[in] image_capture A <code>PP_Resource</code> corresponding to an
 235    * image capture resource.
 236    * @param[in] shutter_callback A <code>
 237    * PPB_ImageCapture_Private_ShutterCallback</code> callback to indicate the
 238    * image has been taken.
 239    * @param[in] preview_callback A <code>
 240    * PPB_ImageCapture_Private_PreviewCallback</code> callback to return a
 241    * preview of the captured image.
 242    * @param[in] jpeg_callback A <code>
 243    * PPB_ImageCapture_Private_JpegCallback</code> callback to return captured
 244    * JPEG image.
 245    * @param[out] sequence_id The sequence ID is a unique monotonically
 246    * increasing value starting from 0, incremented every time a new request like
 247    * image capture is submitted.
 248    *
 249    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
 250    * PP_OK means the callbacks will be triggered. Other values mean the
 251    * callbacks will not be triggered.
 252    */
 253   int32_t CaptureStillImage(
 254       [in] PP_Resource image_capture,
 255       [in] PPB_ImageCapture_Private_ShutterCallback shutter_callback,
 256       [in] PPB_ImageCapture_Private_PreviewCallback preview_callback,
 257       [in] PPB_ImageCapture_Private_JpegCallback jpeg_callback,
 258       [out] int64_t sequence_id);
 259 };