ppapi/c/private/ppb_image_capture_private.h

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