## CheeseCamera CheeseCamera — A representation of the video capture device inside CheeseWidget |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <cheese/cheese-camera.h>

    struct              CheeseCameraClass;
    struct              CheeseCamera;
    CheeseCamera *      cheese_camera_new                   (ClutterTexture *video_texture,
                                                             const gchar *camera_device_node,
                                                             gint x_resolution,
                                                             gint y_resolution);
    GPtrArray *         cheese_camera_get_camera_devices    (CheeseCamera *camera);
    const CheeseVideoFormat * cheese_camera_get_current_video_format
                                                            (CheeseCamera *camera);
    GList *             cheese_camera_get_video_formats     (CheeseCamera *camera);
    void                cheese_camera_set_video_format      (CheeseCamera *camera,
                                                             CheeseVideoFormat *format);
    CheeseCameraDevice * cheese_camera_get_selected_device  (CheeseCamera *camera);
    void                cheese_camera_set_device_by_device_node
                                                            (CheeseCamera *camera,
                                                             const gchar *file);
    void                cheese_camera_set_effect            (CheeseCamera *camera,
                                                             CheeseEffect *effect);
    gboolean            cheese_camera_get_balance_property_range
                                                            (CheeseCamera *camera,
                                                             const gchar *property,
                                                             gdouble *min,
                                                             gdouble *max,
                                                             gdouble *def);
    void                cheese_camera_set_balance_property  (CheeseCamera *camera,
                                                             const gchar *property,
                                                             gdouble value);
    gchar *             cheese_camera_get_recorded_time     (CheeseCamera *camera);
    void                cheese_camera_connect_effect_texture
                                                            (CheeseCamera *camera,
                                                             CheeseEffect *effect,
                                                             ClutterTexture *texture);
    void                cheese_camera_play                  (CheeseCamera *camera);
    void                cheese_camera_stop                  (CheeseCamera *camera);
    void                cheese_camera_start_video_recording (CheeseCamera *camera,
                                                             const gchar *filename);
    void                cheese_camera_stop_video_recording  (CheeseCamera *camera);
    void                cheese_camera_switch_camera_device  (CheeseCamera *camera);
    gboolean            cheese_camera_take_photo            (CheeseCamera *camera,
                                                             const gchar *filename);
    gboolean            cheese_camera_take_photo_pixbuf     (CheeseCamera *camera);
    void                cheese_camera_toggle_effects_pipeline
                                                            (CheeseCamera *camera,
                                                             gboolean active);
    enum                CheeseCameraError;
    void                cheese_camera_setup                 (CheeseCamera *camera,
                                                             const gchar *uuid,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----CheeseCamera

## Properties

      "device-node"              gchar*                : Read / Write
      "format"                   CheeseVideoFormat*    : Read / Write
      "num-camera-devices"       guint                 : Read
      "video-texture"            gpointer              : Read / Write

## Signals

      "photo-saved"                                    : Action
      "photo-taken"                                    : Action
      "state-flags-changed"                            : Action
      "video-saved"                                    : Action

## Description

CheeseCamera represents the video capture device used to drive a CheeseWidget.

## Details

### struct CheeseCameraClass

    struct CheeseCameraClass {
      void (*photo_saved)(CheeseCamera *camera);
      void (*photo_taken)(CheeseCamera *camera, GdkPixbuf *pixbuf);
      void (*video_saved)(CheeseCamera *camera);
      void (*state_flags_changed)(CheeseCamera *camera, GstState new_state);
    };

Class for CheeseCamera.

`photo_saved` () | invoked when a photo was saved to disk
`photo_taken` () | invoked when a photo was taken
`video_saved` () | invoked when a video was saved to disk
`state_flags_changed` () | invoked when the state of the camera GstElement changed

### struct CheeseCamera

    struct CheeseCamera;

Use the accessor functions below.

### cheese_camera_new ()

    CheeseCamera *      cheese_camera_new                   (ClutterTexture *video_texture,
                                                             const gchar *camera_device_node,
                                                             gint x_resolution,
                                                             gint y_resolution);

Create a new CheeseCamera object.

`video_texture` : | a ClutterTexture
`camera_device_node` : | the device node path. [allow-none]
`x_resolution` : | the resolution width
`y_resolution` : | the resolution height
Returns : | a new CheeseCamera

### cheese_camera_get_camera_devices ()

    GPtrArray *         cheese_camera_get_camera_devices    (CheeseCamera *camera);

Get the list of CheeseCameraDevice objects, representing active video capture devices on the system.

`camera` : | a CheeseCamera
Returns : | an array of CheeseCameraDevice. [element-type Cheese.CameraDevice][transfer container]

### cheese_camera_get_current_video_format ()

    const CheeseVideoFormat * cheese_camera_get_current_video_format
                                                            (CheeseCamera *camera);

Get the CheeseVideoFormat that is currently set on the `camera`.

`camera` : | a CheeseCamera
Returns : | the CheeseVideoFormat set on the CheeseCamera. [transfer none]

### cheese_camera_get_video_formats ()

    GList *             cheese_camera_get_video_formats     (CheeseCamera *camera);

Gets the list of CheeseVideoFormat supported by the selected CheeseCameraDevice on the `camera`.

`camera` : | a CheeseCamera
Returns : | a GList of CheeseVideoFormat, or `NULL` if there was no device selected. [element-type Cheese.VideoFormat][transfer container]

### cheese_camera_set_video_format ()

    void                cheese_camera_set_video_format      (CheeseCamera *camera,
                                                             CheeseVideoFormat *format);

Sets a CheeseVideoFormat on a CheeseCamera, restarting the video stream if necessary.

`camera` : | a CheeseCamera
`format` : | a CheeseVideoFormat

### cheese_camera_get_selected_device ()

    CheeseCameraDevice * cheese_camera_get_selected_device  (CheeseCamera *camera);

Get the currently-selected CheeseCameraDevice of the `camera`.

`camera` : | a CheeseCamera
Returns : | a CheeseCameraDevice, or `NULL` if there is no selected device. [transfer none]

### cheese_camera_set_device_by_device_node ()

    void                cheese_camera_set_device_by_device_node
                                                            (CheeseCamera *camera,
                                                             const gchar *file);

Set the active video capture device of the `camera`, matching by device node path.

`camera` : | a CheeseCamera
`file` : | the device node path. [type filename]

### cheese_camera_set_effect ()

    void                cheese_camera_set_effect            (CheeseCamera *camera,
                                                             CheeseEffect *effect);

Set the `effect` on the `camera`.

`camera` : | a CheeseCamera
`effect` : | a CheeseEffect

### cheese_camera_get_balance_property_range ()

    gboolean            cheese_camera_get_balance_property_range
                                                            (CheeseCamera *camera,
                                                             const gchar *property,
                                                             gdouble *min,
                                                             gdouble *max,
                                                             gdouble *def);

Get the minimum, maximum and default values for the requested `property` of the `camera`.

`camera` : | a CheeseCamera
`property` : | name of the balance property
`min` : | minimum value. [out]
`max` : | maximum value. [out]
`def` : | default value. [out]
Returns : | `TRUE` if the operation was successful, `FALSE` otherwise

### cheese_camera_set_balance_property ()

    void                cheese_camera_set_balance_property  (CheeseCamera *camera,
                                                             const gchar *property,
                                                             gdouble value);

Set the requested `property` on the `camera` to `value`.

`camera` : | A CheeseCamera
`property` : | name of the balance property
`value` : | value to be set

### cheese_camera_get_recorded_time ()

    gchar *             cheese_camera_get_recorded_time     (CheeseCamera *camera);

Get a string representation of the playing time of the current video recording

`camera` : | A CheeseCamera
Returns : | A string with the time representation.

### cheese_camera_connect_effect_texture ()

    void                cheese_camera_connect_effect_texture
                                                            (CheeseCamera *camera,
                                                             CheeseEffect *effect,
                                                             ClutterTexture *texture);

Connect the supplied `texture` to the `camera`, using `effect`.

`camera` : | a CheeseCamera
`effect` : | a CheeseEffect
`texture` : | a ClutterTexture

### cheese_camera_play ()

    void                cheese_camera_play                  (CheeseCamera *camera);

Set the state of the GStreamer pipeline associated with the CheeseCamera to playing.

`camera` : | a CheeseCamera

### cheese_camera_stop ()

    void                cheese_camera_stop                  (CheeseCamera *camera);

Set the state of the GStreamer pipeline associated with the CheeseCamera to NULL.

`camera` : | a CheeseCamera

### cheese_camera_start_video_recording ()

    void                cheese_camera_start_video_recording (CheeseCamera *camera,
                                                             const gchar *filename);

Start a video recording with the `camera` and save it to `filename`.

`camera` : | a CheeseCamera
`filename` : | the name of the video file to where the recording will be saved. [type filename]

### cheese_camera_stop_video_recording ()

    void                cheese_camera_stop_video_recording  (CheeseCamera *camera);

Stop recording video on the `camera`.

`camera` : | a CheeseCamera

### cheese_camera_switch_camera_device ()

    void                cheese_camera_switch_camera_device  (CheeseCamera *camera);

Toggle the playing/recording state of the `camera`.

`camera` : | a CheeseCamera

### cheese_camera_take_photo ()

    gboolean            cheese_camera_take_photo            (CheeseCamera *camera,
                                                             const gchar *filename);

Save a photo taken with the `camera` to a new file at `filename`.

`camera` : | a CheeseCamera
`filename` : | name of the file to save a photo to. [type filename]
Returns : | `TRUE` on success, `FALSE` if an error occurred

### cheese_camera_take_photo_pixbuf ()

    gboolean            cheese_camera_take_photo_pixbuf     (CheeseCamera *camera);

Take a photo with the `camera` and emit it in the ::capture-start signal as a GdkPixbuf.

`camera` : | a CheeseCamera
Returns : | `TRUE` if the photo was successfully captured, `FALSE` otherwise

### cheese_camera_toggle_effects_pipeline ()

    void                cheese_camera_toggle_effects_pipeline
                                                            (CheeseCamera *camera,
                                                             gboolean active);

Control whether the effects pipeline is enabled for `camera`.

`camera` : | a CheeseCamera
`active` : | `TRUE` if effects pipeline is active, `FALSE` otherwise

### enum CheeseCameraError

    typedef enum {
      CHEESE_CAMERA_ERROR_UNKNOWN,
      CHEESE_CAMERA_ERROR_ELEMENT_NOT_FOUND,
      CHEESE_CAMERA_ERROR_NO_DEVICE
    } CheeseCameraError;

Errors that can occur during camera setup, when calling `cheese_camera_setup()`.

`CHEESE_CAMERA_ERROR_UNKNOWN` | unknown error
`CHEESE_CAMERA_ERROR_ELEMENT_NOT_FOUND` | a required GStreamer element was not found
`CHEESE_CAMERA_ERROR_NO_DEVICE` | a CheeseCameraDevice was not found

### cheese_camera_setup ()

    void                cheese_camera_setup                 (CheeseCamera *camera,
                                                             const gchar *uuid,
                                                             GError **error);

Setup a video capture device.

`camera` : | a CheeseCamera
`uuid` : | UUID of the video capture device, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`

## Property Details

### The `"device-node"` property

      "device-node"              gchar*                : Read / Write

The path to the device node for the video capture device.

Default value: ""

### The `"format"` property

      "format"                   CheeseVideoFormat*    : Read / Write

The format of the video capture device.

### The `"num-camera-devices"` property

      "num-camera-devices"       guint                 : Read

The currently number of camera devices available for being used.

Allowed values: <= 255

Default value: 0

### The `"video-texture"` property

      "video-texture"            gpointer              : Read / Write

The video texture for the CheeseCamera to render into.

## Signal Details

### The `"photo-saved"` signal

    void                user_function                      (CheeseCamera *camera,
                                                            gpointer      user_data)      : Action

Emitted when a photo was saved to disk.

`camera` : | a CheeseCamera
`user_data` : | user data set when the signal handler was connected.

### The `"photo-taken"` signal

    void                user_function                      (CheeseCamera *camera,
                                                            GdkPixbuf    *pixbuf,
                                                            gpointer      user_data)      : Action

Emitted when a photo was taken.

`camera` : | a CheeseCamera
`pixbuf` : | a GdkPixbuf of the photo which was taken
`user_data` : | user data set when the signal handler was connected.

### The `"state-flags-changed"` signal

    void                user_function                      (CheeseCamera *camera,
                                                            gint          state,
                                                            gpointer      user_data)      : Action

Emitted when the state of the `camera` GstElement changed.

`camera` : | a CheeseCamera
`state` : | the GstState which `camera` changed to
`user_data` : | user data set when the signal handler was connected.

### The `"video-saved"` signal

    void                user_function                      (CheeseCamera *camera,
                                                            gpointer      user_data)      : Action

Emitted when a video was saved to disk.

`camera` : | a CheeseCamera
`user_data` : | user data set when the signal handler was connected.