doc/camera_doc.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17
  18 #ifndef __TIZEN_MEDIA_CAMERA_DOC_H__
  19 #define __TIZEN_MEDIA_CAMERA_DOC_H__
  20
  21
  22 /**
  23  * @file camera_doc.h
  24  * @brief This file contains high level documentation for the Camera API.
  25  */
  26
  27 /**
  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.
  31  *
  32  * @section CAPI_MEDIA_CAMERA_MODULE_HEADER Required Header
  33  *   \#include <camera.h>
  34  *
  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.
  39  *
  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
  48  *
  49  * The Camera API also notifies you (by callback mechanism) when a significant picture parameter changes e.g. focus.
  50  *
  51  * @subsection CAPI_MEDIA_CAMERA_LIFE_CYCLE_STATE_DIAGRAM State Diagram
  52  * @image html capi_media_camera_state_diagram.png
  53  *
  54  * @subsection CAPI_MEDIA_CAMERA_LIFE_CYCLE_STATE_TRANSITIONS State Transitions
  55  * <div><table class="doxtable" >
  56  * <tr>
  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>
  61  * </tr>
  62  * <tr>
  63  *    <td> camera_create() </td>
  64  *    <td> NONE </td>
  65  *    <td> CREATED </td>
  66  *    <td> SYNC </td>
  67  * </tr>
  68  * <tr>
  69  *    <td> camera_destroy() </td>
  70  *    <td> CREATED </td>
  71  *    <td> NONE </td>
  72  *    <td> SYNC </td>
  73  * </tr>
  74  * <tr>
  75  *    <td> camera_start_preview() </td>
  76  *    <td> CREATED/CAPTURED </td>
  77  *    <td> PREVIEW </td>
  78  *    <td> SYNC </td>
  79  * </tr>
  80  * <tr>
  81  *    <td> camera_stop_preview() </td>
  82  *    <td> PREVIEW </td>
  83  *    <td> CREATED </td>
  84  *    <td> SYNC </td>
  85  * </tr>
  86  * <tr>
  87  *    <td> camera_start_capture() </td>
  88  *    <td> PREVIEW </td>
  89  *    <td> CAPTURING -> CAPTURED* </td>
  90  *    <td> SYNC </td>
  91  * </tr>
  92  * </table></div>
  93  *
  94  * (*) The transition from the CAPTURING state to the CAPTURED state will be processed automatically. \n
  95  *
  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" >
  99  *     <tr>
 100  *        <th><b>REGISTER</b></th>
 101  *        <th><b>UNREGISTER</b></th>
 102  *        <th><b>CALLBACK</b></th>
 103  *        <th><b>DESCRIPTION</b></th>
 104  *     </tr>
 105  *     <tr>
 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>
 110  *     </tr>
 111  *               <tr>
 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>
 116  *     </tr>
 117  *               <tr>
 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>
 122  *     </tr>
 123  *               <tr>
 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>
 128  *     </tr>
 129  *</table></div>
 130  *
 131  * @subsection CAPI_MEDIA_CAMERA_FOREACH_OPERATIONS Foreach Operations
 132  * <div><table class="doxtable" >
 133  *     <tr>
 134  *        <th><b>FOREACH</b></th>
 135  *        <th><b>CALLBACK</b></th>
 136  *        <th><b>DESCRIPTION</b></th>
 137  *     </tr>
 138  *     <tr>
 139  *        <td>camera_foreach_supported_preview_resolution()</td>
 140  *        <td>camera_supported_preview_resolution_cb()</td>
 141  *        <td>Supported preview resolutions</td>
 142  *     </tr>
 143  *     <tr>
 144  *        <td>camera_foreach_supported_capture_resolution()</td>
 145  *        <td>camera_supported_capture_resolution_cb()</td>
 146  *        <td>Supported camera capture resolutions</td>
 147  *     </tr>
 148  *     <tr>
 149  *        <td>camera_foreach_supported_capture_format()</td>
 150  *        <td>camera_supported_capture_format_cb()</td>
 151  *        <td>Supported camera capture formats</td>
 152  *     </tr>
 153  *     <tr>
 154  *        <td>camera_foreach_supported_preview_format()</td>
 155  *        <td>camera_supported_preview_format_cb()</td>
 156  *        <td>Supported camera preview format</td>
 157  *     </tr>
 158  *</table></div>
 159  *
 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
 167  *
 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>
 172  *
 173  */
 174
 175
 176 /**
 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.
 180  *
 181  * @section CAPI_MEDIA_CAMERA_ATTRIBUTES_MODULE_HEADER Required Header
 182  *   \#include <camera.h>
 183  *
 184  * @section CAPI_MEDIA_CAMERA_ATTRIBUTES_MODULE_OVERVIEW Overview
 185  * The Camera Attributes API provides functions to get/set basic camera attributes.
 186  *
 187  * With the Camera Attributes API you are able to set and get camera attributes like:
 188  * <ul>
 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>
 198  *  <li>ISO level</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>
 217  * </ul>
 218  *
 219  * @subsection CAPI_MEDIA_CAMERA_ATTRIBUTES_MODULE_FOREACH_OPERATIONS Foreach Operations
 220  * <div><table class="doxtable" >
 221  *     <tr>
 222  *        <th><b>FOREACH</b></th>
 223  *        <th><b>CALLBACK</b></th>
 224  *        <th><b>DESCRIPTION</b></th>
 225  *     </tr>
 226  *     <tr>
 227  *        <td>camera_attr_foreach_supported_fps()</td>
 228  *        <td>camera_attr_supported_fps_cb()</td>
 229  *        <td>Supported FPS</td>
 230  *     </tr>
 231  *     <tr>
 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>
 235  *     </tr>
 236  *     <tr>
 237  *        <td>camera_attr_foreach_supported_exposure_mode()</td>
 238  *        <td>camera_attr_supported_exposure_mode_cb()</td>
 239  *        <td>Supported exposure mode</td>
 240  *     </tr>
 241  *     <tr>
 242  *        <td>camera_attr_foreach_supported_iso()</td>
 243  *        <td>camera_attr_supported_iso_cb()</td>
 244  *        <td>Supported ISO</td>
 245  *     </tr>
 246  *     <tr>
 247  *        <td>camera_attr_foreach_supported_whitebalance()</td>
 248  *        <td>camera_attr_supported_whitebalance_cb()</td>
 249  *        <td>Supported whitebalance</td>
 250  *     </tr>
 251  *     <tr>
 252  *        <td>camera_attr_foreach_supported_effect()</td>
 253  *        <td>camera_attr_supported_effect_cb()</td>
 254  *        <td>Supported effect mode</td>
 255  *     </tr>
 256  *     <tr>
 257  *        <td>camera_attr_foreach_supported_scene_mode()</td>
 258  *        <td>camera_attr_supported_scene_mode_cb()</td>
 259  *        <td>Supported scene mode</td>
 260  *     </tr>
 261  *     <tr>
 262  *        <td>camera_attr_foreach_supported_flash_mode()</td>
 263  *        <td>camera_attr_supported_flash_mode_cb()</td>
 264  *        <td>Supported flash mode</td>
 265  *     </tr>
 266  *</table></div>
 267  *
 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
 275  *
 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>
 280  *
 281  */
 282
 283 /**
 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>
 289  *
 290  * @section CAPI_MEDIA_CAMERA_CAPABILITY_MODULE_OVERVIEW Overview
 291  * The Camera Capability API provides functions to obtain capability information of the camera device.
 292  *
 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
 300  *
 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>
 305  *
 306  */
 307
 308 /**
 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>
 314  *
 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 :
 318  * <ul>
 319  *   <li>rotation</li>
 320  *   <li>display visibility</li>
 321  *   <li>display mode</li>
 322  * </ul>
 323  *
 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
 331  *
 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>
 336  *
 337  */
 338
 339 #endif /* __TIZEN_MEDIA_CAMERA_DOC_H__ */
 340
 341