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 283
