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 }; 260
