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 */
49typedef 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 */
66typedef 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 */
83typedef 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 */
98typedef 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 */
121struct 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
276typedef 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