2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the License);
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #ifndef __TIZEN_MEDIA_CAMERA_DOC_H__
19 #define __TIZEN_MEDIA_CAMERA_DOC_H__
24 * @brief This file contains high level documentation for the Camera API.
28 * @ingroup CAPI_MEDIA_FRAMEWORK
29 * @defgroup CAPI_MEDIA_CAMERA_MODULE Camera
30 * @brief The @ref CAPI_MEDIA_CAMERA_MODULE API provides functions for camera preview, capture, and focusing.
32 * @section CAPI_MEDIA_CAMERA_MODULE_HEADER Required Header
33 * \#include <camera.h>
35 * @section CAPI_MEDIA_CAMERA_MODULE_OVERVIEW Overview
36 * The Camera API allows application developers to support using the camera. It includes functions that capture photos and support setting up
37 * notifications for state changes of capturing, previewing, focusing, information about resolution and binary data format, and functions for artistic
38 * picture manipulations like sepia, negative, sketch, and many more.
40 * The Camera API allows creation of components required in taking pictures including:
41 * - selecting proper exposure parameters
42 * - selecting a proper output format
43 * - displaying a photo preview
44 * - triggering the capture phase
45 * - controlling and displaying the camera state
46 * - getting supported formats and picture resolutions
47 * - getting a preview format and a resolution
49 * The Camera API also notifies you (by callback mechanism) when a significant picture parameter changes e.g. focus.
51 * @subsection CAPI_MEDIA_CAMERA_LIFE_CYCLE_STATE_DIAGRAM State Diagram
52 * @image html capi_media_camera_state_diagram.png
54 * @subsection CAPI_MEDIA_CAMERA_LIFE_CYCLE_STATE_TRANSITIONS State Transitions
55 * <div><table class="doxtable" >
57 * <th><b>FUNCTION</b></th>
58 * <th><b>PRE-STATE</b></th>
59 * <th><b>POST-STATE</b></th>
60 * <th><b>SYNC TYPE</b></th>
63 * <td> camera_create() </td>
69 * <td> camera_destroy() </td>
75 * <td> camera_start_preview() </td>
76 * <td> CREATED/CAPTURED </td>
81 * <td> camera_stop_preview() </td>
87 * <td> camera_start_capture() </td>
89 * <td> CAPTURING -> CAPTURED* </td>
94 * (*) The transition from the CAPTURING state to the CAPTURED state will be processed automatically. \n
96 * @subsection CAPI_MEDIA_CAMERA_LIFE_CYCLE_CALLBACK_OPERATIONS Callback(Event) Operations
97 * The callback mechanism is used to notify the application about significant camera events.
98 * <div><table class="doxtable" >
100 * <th><b>REGISTER</b></th>
101 * <th><b>UNREGISTER</b></th>
102 * <th><b>CALLBACK</b></th>
103 * <th><b>DESCRIPTION</b></th>
106 * <td>camera_set_preview_cb()</td>
107 * <td>camera_unset_preview_cb()</td>
108 * <td>camera_preview_cb()</td>
109 * <td>This callback is used to display the preview (it delivers copies of previous frames) </td>
112 * <td>camera_set_state_changed_cb()</td>
113 * <td>camera_unset_state_changed_cb()</td>
114 * <td>camera_state_changed_cb()</td>
115 * <td>This callback is used to notify that the camera state has changed. Not executed in the recorder mode </td>
118 * <td>camera_set_focus_changed_cb()</td>
119 * <td>camera_unset_focus_changed_cb()</td>
120 * <td>camera_focus_changed_cb()</td>
121 * <td>This callback is used to notify that the camera has changed focus (and it is ready to shoot) </td>
124 * <td>camera_set_error_cb()</td>
125 * <td>camera_unset_error_cb()</td>
126 * <td>camera_error_cb()</td>
127 * <td>This callback is used to notify that an error has occurred</td>
131 * @subsection CAPI_MEDIA_CAMERA_FOREACH_OPERATIONS Foreach Operations
132 * <div><table class="doxtable" >
134 * <th><b>FOREACH</b></th>
135 * <th><b>CALLBACK</b></th>
136 * <th><b>DESCRIPTION</b></th>
139 * <td>camera_foreach_supported_preview_resolution()</td>
140 * <td>camera_supported_preview_resolution_cb()</td>
141 * <td>Supported preview resolutions</td>
144 * <td>camera_foreach_supported_capture_resolution()</td>
145 * <td>camera_supported_capture_resolution_cb()</td>
146 * <td>Supported camera capture resolutions</td>
149 * <td>camera_foreach_supported_capture_format()</td>
150 * <td>camera_supported_capture_format_cb()</td>
151 * <td>Supported camera capture formats</td>
154 * <td>camera_foreach_supported_preview_format()</td>
155 * <td>camera_supported_preview_format_cb()</td>
156 * <td>Supported camera preview format</td>
160 * @section CAPI_MEDIA_CAMERA_MODULE_FEATURE Related Features
161 * This API is related with the following features:\n
162 * - http://tizen.org/feature/camera\n
163 * - http://tizen.org/feature/camera.back\n
164 * - http://tizen.org/feature/camera.back.flash\n
165 * - http://tizen.org/feature/camera.front\n
166 * - http://tizen.org/feature/camera.front.flash
168 * It is recommended to design feature related codes in your application for reliability.\n
169 * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
170 * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
171 * More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
177 * @ingroup CAPI_MEDIA_CAMERA_MODULE
178 * @defgroup CAPI_MEDIA_CAMERA_ATTRIBUTES_MODULE Attributes
179 * @brief The @ref CAPI_MEDIA_CAMERA_ATTRIBUTES_MODULE API provides functions to fetch camera attributes.
181 * @section CAPI_MEDIA_CAMERA_ATTRIBUTES_MODULE_HEADER Required Header
182 * \#include <camera.h>
184 * @section CAPI_MEDIA_CAMERA_ATTRIBUTES_MODULE_OVERVIEW Overview
185 * The Camera Attributes API provides functions to get/set basic camera attributes.
187 * With the Camera Attributes API you are able to set and get camera attributes like:
189 * <li>Preview frame rate</li>
190 * <li>Supported FPS</li>
191 * <li>Image quality</li>
192 * <li>Zoom level</li>
193 * <li>Auto focus mode</li>
194 * <li>Supported auto focus mode</li>
195 * <li>Exposure mode</li>
196 * <li>Supported exposure mode</li>
197 * <li>Exposure value</li>
199 * <li>Supported ISO</li>
200 * <li>Brightness level</li>
201 * <li>Contrast level</li>
202 * <li>White balance mode</li>
203 * <li>Supported white balance</li>
204 * <li>Effect mode</li>
205 * <li>Supported effect mode</li>
206 * <li>Scene mode</li>
207 * <li>Supported scene mode</li>
208 * <li>On/off camera information</li>
209 * <li>Image description</li>
210 * <li>Orientation information</li>
211 * <li>Software tag</li>
212 * <li>GPS latitude data</li>
213 * <li>GPS longitude data</li>
214 * <li>GPS altitude data</li>
215 * <li>Flash mode</li>
216 * <li>Supported flash mode</li>
219 * @subsection CAPI_MEDIA_CAMERA_ATTRIBUTES_MODULE_FOREACH_OPERATIONS Foreach Operations
220 * <div><table class="doxtable" >
222 * <th><b>FOREACH</b></th>
223 * <th><b>CALLBACK</b></th>
224 * <th><b>DESCRIPTION</b></th>
227 * <td>camera_attr_foreach_supported_fps()</td>
228 * <td>camera_attr_supported_fps_cb()</td>
229 * <td>Supported FPS</td>
232 * <td>camera_attr_foreach_supported_af_mode()</td>
233 * <td>camera_attr_supported_af_mode_cb()</td>
234 * <td>Supported auto focus mode</td>
237 * <td>camera_attr_foreach_supported_exposure_mode()</td>
238 * <td>camera_attr_supported_exposure_mode_cb()</td>
239 * <td>Supported exposure mode</td>
242 * <td>camera_attr_foreach_supported_iso()</td>
243 * <td>camera_attr_supported_iso_cb()</td>
244 * <td>Supported ISO</td>
247 * <td>camera_attr_foreach_supported_whitebalance()</td>
248 * <td>camera_attr_supported_whitebalance_cb()</td>
249 * <td>Supported whitebalance</td>
252 * <td>camera_attr_foreach_supported_effect()</td>
253 * <td>camera_attr_supported_effect_cb()</td>
254 * <td>Supported effect mode</td>
257 * <td>camera_attr_foreach_supported_scene_mode()</td>
258 * <td>camera_attr_supported_scene_mode_cb()</td>
259 * <td>Supported scene mode</td>
262 * <td>camera_attr_foreach_supported_flash_mode()</td>
263 * <td>camera_attr_supported_flash_mode_cb()</td>
264 * <td>Supported flash mode</td>
268 * @section CAPI_MEDIA_CAMERA_ATTRIBUTES_MODULE_FEATURE Related Features
269 * This API is related with the following features:\n
270 * - http://tizen.org/feature/camera\n
271 * - http://tizen.org/feature/camera.back\n
272 * - http://tizen.org/feature/camera.back.flash\n
273 * - http://tizen.org/feature/camera.front\n
274 * - http://tizen.org/feature/camera.front.flash
276 * It is recommended to design feature related codes in your application for reliability.\n
277 * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
278 * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
279 * More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
284 * @ingroup CAPI_MEDIA_CAMERA_MODULE
285 * @defgroup CAPI_MEDIA_CAMERA_CAPABILITY_MODULE Capability
286 * @brief The @ref CAPI_MEDIA_CAMERA_CAPABILITY_MODULE API provides capability information of the camera.
287 * @section CAPI_MEDIA_CAMERA_CAPABILITY_MODULE_HEADER Required Header
288 * \#include <camera.h>
290 * @section CAPI_MEDIA_CAMERA_CAPABILITY_MODULE_OVERVIEW Overview
291 * The Camera Capability API provides functions to obtain capability information of the camera device.
293 * @section CAPI_MEDIA_CAMERA_CAPABILITY_MODULE_FEATURE Related Features
294 * This API is related with the following features:\n
295 * - http://tizen.org/feature/camera\n
296 * - http://tizen.org/feature/camera.back\n
297 * - http://tizen.org/feature/camera.back.flash\n
298 * - http://tizen.org/feature/camera.front\n
299 * - http://tizen.org/feature/camera.front.flash
301 * It is recommended to design feature related codes in your application for reliability.\n
302 * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
303 * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
304 * More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
309 * @ingroup CAPI_MEDIA_CAMERA_MODULE
310 * @defgroup CAPI_MEDIA_CAMERA_DISPLAY_MODULE Display
311 * @brief The @ref CAPI_MEDIA_CAMERA_DISPLAY_MODULE API provides functions to control display.
312 * @section CAPI_MEDIA_CAMERA_DISPLAY_MODULE_HEADER Required Header
313 * \#include <camera.h>
315 * @section CAPI_MEDIA_CAMERA_DISPLAY_MODULE_OVERVIEW Overview
316 * The Display API allows you to manage display for the camera. This API provides you with
317 * functions that set and get various display properties :
320 * <li>display visibility</li>
321 * <li>display mode</li>
324 * @section CAPI_MEDIA_CAMERA_DISPLAY_MODULE_FEATURE Related Features
325 * This API is related with the following features:\n
326 * - http://tizen.org/feature/camera\n
327 * - http://tizen.org/feature/camera.back\n
328 * - http://tizen.org/feature/camera.back.flash\n
329 * - http://tizen.org/feature/camera.front\n
330 * - http://tizen.org/feature/camera.front.flash
332 * It is recommended to design feature related codes in your application for reliability.\n
333 * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
334 * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n
335 * More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
339 #endif /* __TIZEN_MEDIA_CAMERA_DOC_H__ */