gst-libs/gst/interfaces/photography.h

   1 /* GStreamer
   2  *
   3  * Copyright (C) 2008 Nokia Corporation <multimedia@maemo.org>
   4  *
   5  * photography.h: photography interface for digital imaging
   6  *
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #ifndef __GST_PHOTOGRAPHY_H__
  25 #define __GST_PHOTOGRAPHY_H__
  26
  27 #ifndef GST_USE_UNSTABLE_API
  28 #warning "The GstPhotography interface is unstable API and may change in future."
  29 #warning "You can define GST_USE_UNSTABLE_API to avoid this warning."
  30 #endif
  31
  32 #include <gst/gst.h>
  33 #include <gst/interfaces/photography-enumtypes.h>
  34
  35 G_BEGIN_DECLS
  36
  37 #define GST_TYPE_PHOTOGRAPHY \
  38   (gst_photography_get_type ())
  39 #define GST_PHOTOGRAPHY(obj) \
  40   (GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_PHOTOGRAPHY, GstPhotography))
  41 #define GST_IS_PHOTOGRAPHY(obj) \
  42   (GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_PHOTOGRAPHY))
  43 #define GST_PHOTOGRAPHY_GET_IFACE(inst) \
  44   (G_TYPE_INSTANCE_GET_INTERFACE ((inst), GST_TYPE_PHOTOGRAPHY, GstPhotographyInterface))
  45
  46
  47 /* Custom GstMessage name that will be sent to GstBus when autofocusing
  48    is complete */
  49 #define GST_PHOTOGRAPHY_AUTOFOCUS_DONE "autofocus-done"
  50
  51 /* Custom GstMessage name that will be sent to GstBus when shake risk changes */
  52 #define GST_PHOTOGRAPHY_SHAKE_RISK "shake-risk"
  53
  54 /* Interface property names */
  55 #define GST_PHOTOGRAPHY_PROP_WB_MODE      "white-balance-mode"
  56 #define GST_PHOTOGRAPHY_PROP_COLOUR_TONE  "colour-tone-mode"
  57 #define GST_PHOTOGRAPHY_PROP_SCENE_MODE   "scene-mode"
  58 #define GST_PHOTOGRAPHY_PROP_FLASH_MODE   "flash-mode"
  59 #define GST_PHOTOGRAPHY_PROP_NOISE_REDUCTION   "noise-reduction"
  60 #define GST_PHOTOGRAPHY_PROP_FOCUS_STATUS "focus-status"
  61 #define GST_PHOTOGRAPHY_PROP_CAPABILITIES "capabilities"
  62 #define GST_PHOTOGRAPHY_PROP_SHAKE_RISK   "shake-risk"
  63 #define GST_PHOTOGRAPHY_PROP_EV_COMP      "ev-compensation"
  64 #define GST_PHOTOGRAPHY_PROP_ISO_SPEED    "iso-speed"
  65 #define GST_PHOTOGRAPHY_PROP_APERTURE     "aperture"
  66 #define GST_PHOTOGRAPHY_PROP_EXPOSURE     "exposure"
  67 #define GST_PHOTOGRAPHY_PROP_IMAGE_CAPTURE_SUPPORTED_CAPS \
  68     "image-capture-supported-caps"
  69 #define GST_PHOTOGRAPHY_PROP_IMAGE_PREVIEW_SUPPORTED_CAPS \
  70     "image-preview-supported-caps"
  71 #define GST_PHOTOGRAPHY_PROP_FLICKER_MODE "flicker-mode"
  72 #define GST_PHOTOGRAPHY_PROP_FOCUS_MODE   "focus-mode"
  73 #define GST_PHOTOGRAPHY_PROP_ZOOM   "zoom"
  74 #define GST_PHOTOGRAPHY_PROP_AUTOFOCUS    "autofocus"
  75
  76 /**
  77  * GstPhotography:
  78  *
  79  * Opaque #GstPhotography data structure.
  80  */
  81 typedef struct _GstPhotography GstPhotography;
  82
  83 /**
  84  * GstPhotographyNoiseReduction:
  85  * @GST_PHOTOGRAPHY_NOISE_REDUCTION_BAYER: Adaptive noise reduction on Bayer
  86  * format
  87  * @GST_PHOTOGRAPHY_NOISE_REDUCTION_YCC: reduces the noise on Y and 2-chroma
  88  * images.
  89  * @GST_PHOTOGRAPHY_NOISE_REDUCTION_TEMPORAL: Multi-frame adaptive NR,
  90  * provided for the video mode
  91  * @GST_PHOTOGRAPHY_NOISE_REDUCTION_FPN: Fixed Pattern Noise refers to noise
  92  * that does not change between frames. The noise is removed from the sensor
  93  * image, by subtracting a previously-captured black image in memory.
  94  * @GST_PHOTOGRAPHY_NOISE_REDUCTION_EXTRA: Extra Noise Reduction. In the case
  95  * of high-ISO capturing, some noise remains after YCC NR. XNR reduces this
  96  * remaining noise.
  97  *
  98  * Noise Reduction features of a photography capture or filter element.
  99  *
 100  * Since: 0.10.21
 101  */
 102 typedef enum
 103 {
 104   GST_PHOTOGRAPHY_NOISE_REDUCTION_BAYER = ( 1<<0 ),
 105   GST_PHOTOGRAPHY_NOISE_REDUCTION_YCC = ( 1<<1 ),
 106   GST_PHOTOGRAPHY_NOISE_REDUCTION_TEMPORAL= ( 1<< 2),
 107   GST_PHOTOGRAPHY_NOISE_REDUCTION_FIXED = (1 << 3),
 108   GST_PHOTOGRAPHY_NOISE_REDUCTION_EXTRA = (1 << 4)
 109 } GstPhotographyNoiseReduction;
 110
 111 typedef enum
 112 {
 113   GST_PHOTOGRAPHY_WB_MODE_AUTO = 0,
 114   GST_PHOTOGRAPHY_WB_MODE_DAYLIGHT,
 115   GST_PHOTOGRAPHY_WB_MODE_CLOUDY,
 116   GST_PHOTOGRAPHY_WB_MODE_SUNSET,
 117   GST_PHOTOGRAPHY_WB_MODE_TUNGSTEN,
 118   GST_PHOTOGRAPHY_WB_MODE_FLUORESCENT
 119 } GstWhiteBalanceMode;
 120
 121 typedef enum
 122 {
 123   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_NORMAL = 0,
 124   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_SEPIA,
 125   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_NEGATIVE,
 126   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_GRAYSCALE,
 127   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_NATURAL,
 128   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_VIVID,
 129   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_COLORSWAP,
 130   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_SOLARIZE,
 131   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_OUT_OF_FOCUS,
 132   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_SKY_BLUE,
 133   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_GRASS_GREEN,
 134   GST_PHOTOGRAPHY_COLOUR_TONE_MODE_SKIN_WHITEN
 135 } GstColourToneMode;
 136
 137 typedef enum
 138 {
 139   GST_PHOTOGRAPHY_SCENE_MODE_MANUAL = 0,
 140   GST_PHOTOGRAPHY_SCENE_MODE_CLOSEUP,
 141   GST_PHOTOGRAPHY_SCENE_MODE_PORTRAIT,
 142   GST_PHOTOGRAPHY_SCENE_MODE_LANDSCAPE,
 143   GST_PHOTOGRAPHY_SCENE_MODE_SPORT,
 144   GST_PHOTOGRAPHY_SCENE_MODE_NIGHT,
 145   GST_PHOTOGRAPHY_SCENE_MODE_AUTO
 146 } GstSceneMode;
 147
 148 typedef enum
 149 {
 150   GST_PHOTOGRAPHY_FLASH_MODE_AUTO = 0,
 151   GST_PHOTOGRAPHY_FLASH_MODE_OFF,
 152   GST_PHOTOGRAPHY_FLASH_MODE_ON,
 153   GST_PHOTOGRAPHY_FLASH_MODE_FILL_IN,
 154   GST_PHOTOGRAPHY_FLASH_MODE_RED_EYE
 155 } GstFlashMode;
 156
 157 typedef enum
 158 {
 159   GST_PHOTOGRAPHY_FOCUS_STATUS_NONE = 0,
 160   GST_PHOTOGRAPHY_FOCUS_STATUS_RUNNING,
 161   GST_PHOTOGRAPHY_FOCUS_STATUS_FAIL,
 162   GST_PHOTOGRAPHY_FOCUS_STATUS_SUCCESS
 163 } GstFocusStatus;
 164
 165 typedef enum
 166 {
 167   GST_PHOTOGRAPHY_CAPS_NONE = (0 << 0),
 168   GST_PHOTOGRAPHY_CAPS_EV_COMP = (1 << 0),
 169   GST_PHOTOGRAPHY_CAPS_ISO_SPEED = (1 << 1),
 170   GST_PHOTOGRAPHY_CAPS_WB_MODE = (1 << 2),
 171   GST_PHOTOGRAPHY_CAPS_TONE = (1 << 3),
 172   GST_PHOTOGRAPHY_CAPS_SCENE = (1 << 4),
 173   GST_PHOTOGRAPHY_CAPS_FLASH = (1 << 5),
 174   GST_PHOTOGRAPHY_CAPS_ZOOM = (1 << 6),
 175   GST_PHOTOGRAPHY_CAPS_FOCUS = (1 << 7),
 176   GST_PHOTOGRAPHY_CAPS_APERTURE = (1 << 8),
 177   GST_PHOTOGRAPHY_CAPS_EXPOSURE = (1 << 9),
 178   GST_PHOTOGRAPHY_CAPS_SHAKE = (1 << 10),
 179   GST_PHOTOGRAPHY_CAPS_NOISE_REDUCTION = (1 << 11),
 180   GST_PHOTOGRAPHY_CAPS_FLICKER_REDUCTION = (1 << 12),
 181   GST_PHOTOGRAPHY_CAPS_ALL = (~0)
 182 } GstPhotoCaps;
 183
 184 typedef enum
 185 {
 186   GST_PHOTOGRAPHY_SHAKE_RISK_LOW = 0,
 187   GST_PHOTOGRAPHY_SHAKE_RISK_MEDIUM,
 188   GST_PHOTOGRAPHY_SHAKE_RISK_HIGH,
 189 } GstPhotoShakeRisk;
 190
 191 typedef enum
 192 {
 193   GST_PHOTOGRAPHY_FLICKER_REDUCTION_OFF = 0,
 194   GST_PHOTOGRAPHY_FLICKER_REDUCTION_50HZ,
 195   GST_PHOTOGRAPHY_FLICKER_REDUCTION_60HZ,
 196   GST_PHOTOGRAPHY_FLICKER_REDUCTION_AUTO,
 197 } GstFlickerReductionMode;
 198
 199 typedef enum {
 200     GST_PHOTOGRAPHY_FOCUS_MODE_AUTO = 0,
 201     GST_PHOTOGRAPHY_FOCUS_MODE_MACRO,
 202     GST_PHOTOGRAPHY_FOCUS_MODE_PORTRAIT,
 203     GST_PHOTOGRAPHY_FOCUS_MODE_INFINITY,
 204     GST_PHOTOGRAPHY_FOCUS_MODE_HYPERFOCAL,
 205     GST_PHOTOGRAPHY_FOCUS_MODE_EXTENDED,
 206     GST_PHOTOGRAPHY_FOCUS_MODE_CONTINUOUS_NORMAL,
 207     GST_PHOTOGRAPHY_FOCUS_MODE_CONTINUOUS_EXTENDED,
 208     GST_PHOTOGRAPHY_FOCUS_MODE_SPORT
 209 } GstFocusMode;
 210
 211 typedef enum {
 212     GST_PHOTOGRAPHY_OPERATION_MODE_VIEWFINDER = 0,
 213     GST_PHOTOGRAPHY_OPERATION_MODE_IMAGE_CAPTURE,
 214     GST_PHOTOGRAPHY_OPERATION_MODE_PREVIEW,
 215 } GstOperationMode;
 216
 217 typedef struct
 218 {
 219   GstWhiteBalanceMode wb_mode;
 220   GstColourToneMode tone_mode;
 221   GstSceneMode scene_mode;
 222   GstFlashMode flash_mode;
 223   guint32 exposure;
 224   guint aperture;
 225   gfloat ev_compensation;
 226   guint iso_speed;
 227   gfloat zoom;
 228   GstFlickerReductionMode flicker_mode;
 229   GstFocusMode focus_mode;
 230   GstPhotographyNoiseReduction noise_reduction;
 231 } GstPhotoSettings;
 232
 233 /**
 234  * GstPhotoCapturePrepared:
 235  * @data: user data that has been given, when registering the callback
 236  * @configured_caps: #GstCaps defining the configured capture format.
 237  *     Ownership of these caps stays in the element.
 238  *
 239  * This callback will be called when the element has finished preparations
 240  * for photo capture.
 241  */
 242 typedef void (*GstPhotoCapturePrepared) (gpointer data,
 243     const GstCaps *configured_caps);
 244
 245 /**
 246  * GstPhotographyInterface:
 247  * @parent: parent interface type.
 248  * @get_ev_compensation: vmethod to get ev exposure compensation value
 249  * @get_iso_speed: vmethod to get iso speed (light sensitivity) value
 250  * @get_aperture: vmethod to get aperture value
 251  * @get_exposure: vmethod to get exposure time value
 252  * @get_white_balance_mode: vmethod to get white balance mode value
 253  * @get_colour_tone_mode: vmethod to get colour tone mode value
 254  * @get_scene_mode: vmethod to get scene mode value
 255  * @get_flash_mode: vmethod to get flash mode value
 256  * @get_noise_reduction: vmethod to get noise reduction mode value
 257  * @get_zoom: vmethod to get zoom factor value
 258  * @set_ev_compensation: vmethod to set ev exposure compensation value
 259  * @set_iso_speed: vmethod to set iso speed (light sensitivity) value
 260  * @set_aperture: vmethod to set aperture value
 261  * @set_exposure: vmethod to set exposure time value
 262  * @set_white_balance_mode: vmethod to set white balance mode value
 263  * @set_colour_tone_mode: vmethod to set colour tone mode value
 264  * @set_scene_mode: vmethod to set scene mode value
 265  * @set_flash_mode: vmethod to set flash mode value
 266  * @set_noise_reduction: vmethod to set noise reduction mode value
 267  * @set_zoom: vmethod to set zoom factor value
 268  * @get_capabilities: vmethod to get supported capabilities of the interface
 269  * @prepare_for_capture: vmethod to tell the element to prepare for capturing
 270  * @set_autofocus: vmethod to set autofocus on/off
 271  * @set_config: vmethod to set all configuration parameters at once
 272  * @get_config: vmethod to get all configuration parameters at once
 273  * @get_image_capture_supported_caps: vmethod to get caps describing supported image capture formats
 274  * @set_format: vmethod to set caps for given operation mode
 275  * @get_format: vmethod to get current caps for given operation mode
 276  *
 277  * #GstPhotographyInterface interface.
 278  */
 279 typedef struct _GstPhotographyInterface
 280 {
 281   GTypeInterface parent;
 282
 283   /* virtual functions */
 284   gboolean (*get_ev_compensation) (GstPhotography * photo, gfloat * ev_comp);
 285   gboolean (*get_iso_speed) (GstPhotography * photo, guint * iso_speed);
 286   gboolean (*get_aperture) (GstPhotography * photo, guint * aperture);
 287   gboolean (*get_exposure) (GstPhotography * photo, guint32 * exposure);
 288   gboolean (*get_white_balance_mode) (GstPhotography * photo,
 289       GstWhiteBalanceMode * wb_mode);
 290   gboolean (*get_colour_tone_mode) (GstPhotography * photo,
 291       GstColourToneMode * tone_mode);
 292   gboolean (*get_scene_mode) (GstPhotography * photo,
 293       GstSceneMode * scene_mode);
 294   gboolean (*get_flash_mode) (GstPhotography * photo,
 295       GstFlashMode * flash_mode);
 296   gboolean (*get_zoom) (GstPhotography * photo, gfloat * zoom);
 297   gboolean (*get_flicker_mode) (GstPhotography * photo,
 298       GstFlickerReductionMode * flicker_mode);
 299   gboolean (*get_focus_mode) (GstPhotography * photo,
 300       GstFocusMode * focus_mode);
 301
 302   gboolean (*set_ev_compensation) (GstPhotography * photo, gfloat ev_comp);
 303   gboolean (*set_iso_speed) (GstPhotography * photo, guint iso_speed);
 304   gboolean (*set_aperture) (GstPhotography * photo, guint aperture);
 305   gboolean (*set_exposure) (GstPhotography * photo, guint32 exposure);
 306   gboolean (*set_white_balance_mode) (GstPhotography * photo,
 307       GstWhiteBalanceMode wb_mode);
 308   gboolean (*set_colour_tone_mode) (GstPhotography * photo,
 309       GstColourToneMode tone_mode);
 310   gboolean (*set_scene_mode) (GstPhotography * photo,
 311       GstSceneMode scene_mode);
 312   gboolean (*set_flash_mode) (GstPhotography * photo,
 313       GstFlashMode flash_mode);
 314   gboolean (*set_zoom) (GstPhotography * photo, gfloat zoom);
 315   gboolean (*set_flicker_mode) (GstPhotography * photo,
 316       GstFlickerReductionMode flicker_mode);
 317   gboolean (*set_focus_mode) (GstPhotography * photo,
 318       GstFocusMode focus_mode);
 319
 320   GstPhotoCaps (*get_capabilities) (GstPhotography * photo);
 321   gboolean (*prepare_for_capture) (GstPhotography * photo,
 322       GstPhotoCapturePrepared func, GstCaps *capture_caps, gpointer user_data);
 323   void (*set_autofocus) (GstPhotography * photo, gboolean on);
 324   gboolean (*set_config) (GstPhotography * photo, GstPhotoSettings * config);
 325   gboolean (*get_config) (GstPhotography * photo, GstPhotoSettings * config);
 326   gboolean (*get_noise_reduction) (GstPhotography * photo,
 327     GstPhotographyNoiseReduction * noise_reduction);
 328   gboolean (*set_noise_reduction) (GstPhotography * photo,
 329     GstPhotographyNoiseReduction noise_reduction);
 330   gboolean (*set_format) (GstPhotography * photo,
 331       GstOperationMode op_mode, GstCaps * op_mode_caps);
 332   GstCaps * (*get_format) (GstPhotography * photo, GstOperationMode op_mode);
 333
 334   /*< private > */
 335   gpointer _gst_reserved[GST_PADDING];
 336 } GstPhotographyInterface;
 337
 338 GType gst_photography_get_type (void);
 339
 340 /* virtual class function wrappers */
 341 gboolean gst_photography_get_ev_compensation (GstPhotography * photo,
 342     gfloat * ev_comp);
 343 gboolean gst_photography_get_iso_speed (GstPhotography * photo,
 344     guint * iso_speed);
 345 gboolean gst_photography_get_aperture (GstPhotography * photo,
 346     guint * aperture);
 347 gboolean gst_photography_get_exposure (GstPhotography * photo,
 348     guint32 * exposure);
 349 gboolean gst_photography_get_white_balance_mode (GstPhotography * photo,
 350     GstWhiteBalanceMode * wb_mode);
 351 gboolean gst_photography_get_colour_tone_mode (GstPhotography * photo,
 352     GstColourToneMode * tone_mode);
 353 gboolean gst_photography_get_scene_mode (GstPhotography * photo,
 354     GstSceneMode * scene_mode);
 355 gboolean gst_photography_get_flash_mode (GstPhotography * photo,
 356     GstFlashMode * flash_mode);
 357 gboolean gst_photography_get_noise_reduction (GstPhotography * photo,
 358     GstPhotographyNoiseReduction * noise_reduction);
 359 gboolean gst_photography_get_zoom (GstPhotography * photo, gfloat * zoom);
 360 gboolean gst_photography_get_flicker_mode (GstPhotography * photo,
 361     GstFlickerReductionMode *mode);
 362 gboolean gst_photography_get_focus_mode (GstPhotography * photo,
 363     GstFocusMode *mode);
 364
 365 gboolean gst_photography_set_ev_compensation (GstPhotography * photo,
 366     gfloat ev_comp);
 367 gboolean gst_photography_set_iso_speed (GstPhotography * photo,
 368     guint iso_speed);
 369 gboolean gst_photography_set_aperture (GstPhotography * photo, guint aperture);
 370 gboolean gst_photography_set_exposure (GstPhotography * photo, guint exposure);
 371 gboolean gst_photography_set_white_balance_mode (GstPhotography * photo,
 372     GstWhiteBalanceMode wb_mode);
 373 gboolean gst_photography_set_colour_tone_mode (GstPhotography * photo,
 374     GstColourToneMode tone_mode);
 375 gboolean gst_photography_set_scene_mode (GstPhotography * photo,
 376     GstSceneMode scene_mode);
 377 gboolean gst_photography_set_flash_mode (GstPhotography * photo,
 378     GstFlashMode flash_mode);
 379 gboolean gst_photography_set_noise_reduction (GstPhotography * photo,
 380     GstPhotographyNoiseReduction noise_reduction);
 381 gboolean gst_photography_set_zoom (GstPhotography * photo, gfloat zoom);
 382 gboolean gst_photography_set_flicker_mode (GstPhotography * photo,
 383     GstFlickerReductionMode mode);
 384 gboolean gst_photography_set_focus_mode (GstPhotography * photo,
 385     GstFocusMode mode);
 386
 387 GstPhotoCaps gst_photography_get_capabilities (GstPhotography * photo);
 388
 389 gboolean gst_photography_prepare_for_capture (GstPhotography * photo,
 390     GstPhotoCapturePrepared func, GstCaps *capture_caps, gpointer user_data);
 391
 392 void gst_photography_set_autofocus (GstPhotography * photo, gboolean on);
 393
 394 gboolean gst_photography_set_config (GstPhotography * photo,
 395     GstPhotoSettings * config);
 396 gboolean gst_photography_get_config (GstPhotography * photo,
 397     GstPhotoSettings * config);
 398
 399 gboolean gst_photography_set_format (GstPhotography * photo,
 400     GstOperationMode op_mode, GstCaps * op_mode_caps);
 401 GstCaps * gst_photography_get_format (GstPhotography * photo,
 402     GstOperationMode op_mode);
 403
 404 G_END_DECLS
 405
 406 #endif /* __GST_PHOTOGRAPHY_H__ */