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.
7 * Defines the <code>PPB_ImageCapture_Private</code> interface. Used for
8 * acquiring a single still image from a camera source.
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.
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
30 typedef void PPB_ImageCapture_Private_ShutterCallback
(
31 [inout
] mem_t user_data
,
32 [in] int64_t sequence_id
);
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.
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
45 * |preview| A <code>PP_Resource</code> corresponding to a VideoFrame
46 * resource used to store the preview image.
48 typedef void PPB_ImageCapture_Private_PreviewCallback
(
49 [inout
] mem_t user_data
,
50 [in] int64_t sequence_id
,
51 [in] PP_Resource preview
);
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.
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
63 * |jpeg| A <code>PP_Resource</code> corresponding to a VideoFrame
64 * resource used to store the JPEG image.
66 typedef void PPB_ImageCapture_Private_JpegCallback
(
67 [inout
] mem_t user_data
,
68 [in] int64_t sequence_id
,
69 [in] PP_Resource jpeg
);
72 * Callback function for <code>PPB_ImageCapture_Private.CaptureStillImage
73 * </code> to indicate the image capture has failed.
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
80 * |int32_t| An error code from <code>pp_errors.h</code>.
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
);
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
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.
99 interface PPB_ImageCapture_Private
{
101 * Creates a PPB_ImageCapture_Private resource.
103 * @param[in] instance A <code>PP_Instance</code> identifying one instance
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.
115 * @return A <code>PP_Resource</code> corresponding to a
116 * PPB_ImageCapture_Private resource if successful, 0 if failed.
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
);
124 * Determines if a resource is an image capture resource.
126 * @param[in] resource The <code>PP_Resource</code> to test.
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>
132 PP_Bool IsImageCapture
([in] PP_Resource resource
);
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
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>.
146 * @return An int32_t containing a result code from <code>pp_errors.h</code>.
148 int32_t Close
([in] PP_Resource resource
,
149 [in] PP_CompletionCallback
callback);
152 * Sets the configuration of the image capture.
153 * If <code>SetConfig()</code> is not called, default settings will be used.
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>.
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.
166 int32_t SetConfig
([in] PP_Resource image_capture
,
167 [in] PP_Resource config
,
168 [in] PP_CompletionCallback
callback);
171 * Gets the configuration of the image capture.
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
178 * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
179 * completion of <code>GetConfig()</code>.
181 * @return An int32_t containing a result code from <code>pp_errors.h</code>.
183 int32_t GetConfig
([in] PP_Resource image_capture
,
184 [out] PP_Resource config
,
185 [in] PP_CompletionCallback
callback);
188 * Gets the camera capabilities.
190 * The camera capabilities do not change for a given camera source.
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>.
200 * @return An int32_t containing a result code from <code>pp_errors.h</code>.
202 int32_t GetCameraCapabilities
([in] PP_Resource image_capture
,
203 [out] PP_Resource capabilities
,
204 [in] PP_CompletionCallback
callback);
207 * Captures a still JPEG image from the camera.
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.
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>.
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
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
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.
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.
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
);