[cheese] Add basic documentation for remaining public API
- From: David King <davidk src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [cheese] Add basic documentation for remaining public API
- Date: Sat, 29 Oct 2011 16:42:21 +0000 (UTC)
commit 0692d3ef28c0a4fd5107c6e42de1f9ca77d119d4
Author: David King <amigadave amigadave com>
Date: Sat Oct 29 18:24:53 2011 +0200
Add basic documentation for remaining public API
Add cheese-widget-private.h back to files ignored by gtk-doc. Add basic
documentation for the remainder of the public API. Use UUID instead of
ID or UDI. Add blurb and nick to all documented properties. Add
CheeseVideoFormat documentation. Use unsigned integers where the values
are always positive. Sprinkle some const qualifiers. Add some filename
GObject Introspection annotations.
docs/reference/Makefile.am | 1 +
docs/reference/cheese-sections.txt | 35 +++++++++--
libcheese/cheese-camera-device.c | 92 ++++++++++++++-------------
libcheese/cheese-camera-device.h | 23 +++++--
libcheese/cheese-camera.c | 123 +++++++++++++++++++++++++-----------
libcheese/cheese-camera.h | 14 ++--
libcheese/cheese-effect.c | 12 ++--
libcheese/cheese-fileutil.c | 15 +++--
libcheese/cheese-fileutil.h | 8 +-
libcheese/cheese-flash.c | 4 +-
libcheese/cheese-widget.c | 14 ++--
src/vapi/cheese-common.vapi | 10 +--
tests/cheese-test-monitor.c | 14 ++--
13 files changed, 228 insertions(+), 137 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index d5eefda..6dd82c6 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -53,6 +53,7 @@ CFILE_GLOB=$(top_srcdir)/libcheese/*.c
IGNORE_HFILES= \
cheese-aspect-frame.h \
cheese-enums.h \
+ cheese-widget-private.h \
um-crop-area.h
# Images to copy into HTML directory.
diff --git a/docs/reference/cheese-sections.txt b/docs/reference/cheese-sections.txt
index dc93148..8537670 100644
--- a/docs/reference/cheese-sections.txt
+++ b/docs/reference/cheese-sections.txt
@@ -21,8 +21,26 @@ CHEESE_AVATAR_CHOOSER_GET_CLASS
CheeseCameraClass
CheeseCamera
cheese_camera_new
-cheese_camera_setup
+cheese_camera_get_camera_devices
+cheese_camera_get_current_video_format
+cheese_camera_get_video_formats
+cheese_camera_set_video_format
+cheese_camera_get_selected_device
+cheese_camera_set_device_by_dev_file
+cheese_camera_set_effect
+cheese_camera_get_balance_property_range
+cheese_camera_set_balance_property
+cheese_camera_connect_effect_texture
+cheese_camera_play
+cheese_camera_stop
+cheese_camera_start_video_recording
+cheese_camera_stop_video_recording
+cheese_camera_switch_camera_device
+cheese_camera_take_photo
+cheese_camera_take_photo_pixbuf
+cheese_camera_toggle_effects_pipeline
CheeseCameraError
+cheese_camera_setup
<SUBSECTION Standard>
CHEESE_CAMERA
CHEESE_IS_CAMERA
@@ -38,10 +56,15 @@ CHEESE_CAMERA_GET_CLASS
<TITLE>CheeseCameraDevice</TITLE>
CheeseCameraDeviceClass
CheeseCameraDevice
+CheeseVideoFormat
cheese_camera_device_new
cheese_camera_device_get_name
-cheese_camera_device_get_id
+cheese_camera_device_get_uuid
cheese_camera_device_get_device_file
+cheese_camera_device_get_best_format
+cheese_camera_device_get_caps_for_format
+cheese_camera_device_get_format_list
+cheese_camera_device_get_src
<SUBSECTION Standard>
CHEESE_CAMERA_DEVICE
CHEESE_IS_CAMERA_DEVICE
@@ -50,6 +73,8 @@ cheese_camera_device_get_type
CHEESE_CAMERA_DEVICE_CLASS
CHEESE_IS_CAMERA_DEVICE_CLASS
CHEESE_CAMERA_DEVICE_GET_CLASS
+CHEESE_TYPE_VIDEO_FORMAT
+cheese_video_format_get_type
</SECTION>
<SECTION>
@@ -77,6 +102,9 @@ CheeseEffect
cheese_effect_new
cheese_effect_enable_preview
cheese_effect_disable_preview
+cheese_effect_is_preview_connected
+cheese_effect_load_effects
+cheese_effect_load_from_file
<SUBSECTION Standard>
CHEESE_EFFECT
CHEESE_IS_EFFECT
@@ -97,7 +125,6 @@ CHEESE_PHOTO_NAME_SUFFIX
CHEESE_VIDEO_NAME_SUFFIX
CheeseMediaMode
cheese_fileutil_get_new_media_filename
-cheese_fileutil_get_path_before_224
cheese_fileutil_get_photo_path
cheese_fileutil_get_video_path
cheese_fileutil_reset_burst
@@ -134,9 +161,7 @@ CHEESE_FLASH_GET_CLASS
CheeseWidgetClass
CheeseWidget
cheese_widget_new
-cheese_widget_get_camera
cheese_widget_get_error
-cheese_widget_get_video_area
CheeseWidgetState
<SUBSECTION Standard>
CHEESE_WIDGET
diff --git a/libcheese/cheese-camera-device.c b/libcheese/cheese-camera-device.c
index 99f85e7..94e3c83 100644
--- a/libcheese/cheese-camera-device.c
+++ b/libcheese/cheese-camera-device.c
@@ -78,17 +78,17 @@ enum
PROP_0,
PROP_NAME,
PROP_FILE,
- PROP_ID,
- PROP_API
+ PROP_UUID,
+ PROP_V4LAPI
};
typedef struct
{
gchar *device;
- gchar *id;
+ gchar *uuid;
const gchar *src;
gchar *name;
- gint api;
+ guint v4lapi;
GstCaps *caps;
GList *formats;
@@ -387,7 +387,7 @@ cheese_camera_device_constructed (GObject *object)
CheeseCameraDevicePrivate *priv =
CHEESE_CAMERA_DEVICE_GET_PRIVATE (device);
- priv->src = (priv->api == 2) ? "v4l2src" : "v4lsrc";
+ priv->src = (priv->v4lapi == 2) ? "v4l2src" : "v4lsrc";
cheese_camera_device_get_caps (device);
@@ -410,11 +410,11 @@ cheese_camera_device_get_property (GObject *object, guint prop_id, GValue *value
case PROP_FILE:
g_value_set_string (value, priv->device);
break;
- case PROP_ID:
- g_value_set_string (value, priv->id);
+ case PROP_UUID:
+ g_value_set_string (value, priv->uuid);
break;
- case PROP_API:
- g_value_set_int (value, priv->api);
+ case PROP_V4LAPI:
+ g_value_set_uint (value, priv->v4lapi);
break;
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
@@ -436,18 +436,18 @@ cheese_camera_device_set_property (GObject *object, guint prop_id, const GValue
g_free (priv->name);
priv->name = g_value_dup_string (value);
break;
- case PROP_ID:
- if (priv->id)
- g_free (priv->id);
- priv->id = g_value_dup_string (value);
+ case PROP_UUID:
+ if (priv->uuid)
+ g_free (priv->uuid);
+ priv->uuid = g_value_dup_string (value);
break;
case PROP_FILE:
if (priv->device)
g_free (priv->device);
priv->device = g_value_dup_string (value);
break;
- case PROP_API:
- priv->api = g_value_get_int (value);
+ case PROP_V4LAPI:
+ priv->v4lapi = g_value_get_uint (value);
break;
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
@@ -463,7 +463,7 @@ cheese_camera_device_finalize (GObject *object)
CHEESE_CAMERA_DEVICE_GET_PRIVATE (device);
g_free (priv->device);
- g_free (priv->id);
+ g_free (priv->uuid);
g_free (priv->name);
gst_caps_unref (priv->caps);
@@ -494,7 +494,9 @@ cheese_camera_device_class_init (CheeseCameraDeviceClass *klass)
*/
g_object_class_install_property (object_class, PROP_NAME,
g_param_spec_string ("name",
- NULL, NULL, NULL,
+ "Device name",
+ "Human-readable name of the video capture device",
+ NULL,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
/**
@@ -504,29 +506,35 @@ cheese_camera_device_class_init (CheeseCameraDeviceClass *klass)
*/
g_object_class_install_property (object_class, PROP_FILE,
g_param_spec_string ("device-file",
- NULL, NULL, NULL,
+ "Device file",
+ "Path to the device node of the video capture device",
+ NULL,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
/**
- * CheeseCameraDevice:device-id:
+ * CheeseCameraDevice:uuid:
*
* UUID of the video capture device.
*/
- g_object_class_install_property (object_class, PROP_ID,
- g_param_spec_string ("device-id",
- NULL, NULL, NULL,
+ g_object_class_install_property (object_class, PROP_UUID,
+ g_param_spec_string ("uuid",
+ "Device UUID",
+ "UUID of the video capture device",
+ NULL,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
/**
- * CheeseCameraDevice:api:
+ * CheeseCameraDevice:v4l-api:
*
* Version of the Video4Linux API that the device supports. Currently, either
* 1 or 2 are supported.
*/
- g_object_class_install_property (object_class, PROP_API,
- g_param_spec_int ("api", NULL, NULL,
- 1, 2, 2,
- G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+ g_object_class_install_property (object_class, PROP_V4LAPI,
+ g_param_spec_uint ("v4l-api",
+ "Video4Linux API",
+ "Version of the Video4Linux API that the device supports",
+ 1, 2, 2,
+ G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
g_type_class_add_private (klass, sizeof (CheeseCameraDevicePrivate));
}
@@ -544,7 +552,7 @@ cheese_camera_device_init (CheeseCameraDevice *device)
CHEESE_CAMERA_DEVICE_GET_PRIVATE (device);
priv->device = NULL;
- priv->id = NULL;
+ priv->uuid = NULL;
priv->src = NULL;
priv->name = g_strdup (_("Unknown device"));
priv->caps = gst_caps_new_empty ();
@@ -589,7 +597,8 @@ cheese_camera_device_initable_init (GInitable *initable,
/**
* cheese_camera_device_new:
* @device_id: UUID of the device, as supplied by udev
- * @device_file: path to the device node of the video capture device
+ * @device_file: (type filename): path to the device node of the video capture
+ * device
* @product_name: human-readable name of the device, as supplied by udev
* @api_version: version of the Video4Linux API that the device uses. Currently
* either 1 or 2
@@ -605,15 +614,15 @@ CheeseCameraDevice *
cheese_camera_device_new (const gchar *device_id,
const gchar *device_file,
const gchar *product_name,
- gint api_version,
+ guint api_version,
GError **error)
{
return CHEESE_CAMERA_DEVICE (g_initable_new (CHEESE_TYPE_CAMERA_DEVICE,
NULL, error,
- "device-id", device_id,
+ "uuid", device_id,
"device-file", device_file,
"name", product_name,
- "api", api_version,
+ "v4l-api", api_version,
NULL));
}
@@ -622,9 +631,8 @@ cheese_camera_device_new (const gchar *device_id,
* @device: a #CheeseCameraDevice
*
* Returns: (element-type Cheese.VideoFormat) (transfer container): List of
- * #CheeseVideoFormat
+ * #CheeseVideoFormat that the device supports
*/
-
GList *
cheese_camera_device_get_format_list (CheeseCameraDevice *device)
{
@@ -640,7 +648,6 @@ cheese_camera_device_get_format_list (CheeseCameraDevice *device)
*
* Returns: (transfer none): the human-readable name of the video capture device
*/
-
const gchar *
cheese_camera_device_get_name (CheeseCameraDevice *device)
{
@@ -651,19 +658,18 @@ cheese_camera_device_get_name (CheeseCameraDevice *device)
}
/**
- * cheese_camera_device_get_id:
+ * cheese_camera_device_get_uuid:
* @device: a #CheeseCameraDevice
*
* Returns: (transfer none): the UUID of the video capture device
*/
-
const gchar *
-cheese_camera_device_get_id (CheeseCameraDevice *device)
+cheese_camera_device_get_uuid (CheeseCameraDevice *device)
{
CheeseCameraDevicePrivate *priv =
CHEESE_CAMERA_DEVICE_GET_PRIVATE (device);
- return priv->id;
+ return priv->uuid;
}
/**
@@ -672,7 +678,6 @@ cheese_camera_device_get_id (CheeseCameraDevice *device)
*
* Returns: (transfer none)
*/
-
const gchar *
cheese_camera_device_get_src (CheeseCameraDevice *device)
{
@@ -689,7 +694,6 @@ cheese_camera_device_get_src (CheeseCameraDevice *device)
* Returns: (transfer none): the path to the device node of the video capture
* device
*/
-
const gchar *
cheese_camera_device_get_device_file (CheeseCameraDevice *device)
{
@@ -703,7 +707,8 @@ cheese_camera_device_get_device_file (CheeseCameraDevice *device)
* cheese_camera_device_get_best_format:
* @device: a #CheeseCameraDevice
*
- * Returns: (transfer full): a #CheeseVideoFormat
+ * Returns: (transfer full): the highest-resolution #CheeseVideoFormat
+ * supported be the @device
*/
CheeseVideoFormat *
@@ -721,9 +726,8 @@ cheese_camera_device_get_best_format (CheeseCameraDevice *device)
* @device: a #CheeseCameraDevice
* @format: a #CheeseVideoFormat
*
- * Returns: (transfer full)
+ * Returns: (transfer full): the #GstCaps for the given @format on the @device
*/
-
GstCaps *
cheese_camera_device_get_caps_for_format (CheeseCameraDevice *device,
CheeseVideoFormat *format)
diff --git a/libcheese/cheese-camera-device.h b/libcheese/cheese-camera-device.h
index 6874b93..f3ad52e 100644
--- a/libcheese/cheese-camera-device.h
+++ b/libcheese/cheese-camera-device.h
@@ -65,11 +65,22 @@ struct _CheeseCameraDevice
#define CHEESE_TYPE_VIDEO_FORMAT (cheese_video_format_get_type ())
-typedef struct
+typedef struct _CheeseVideoFormat CheeseVideoFormat;
+
+/**
+ * CheeseVideoFormat:
+ * @width: the width of of the video, in pixels
+ * @height: the height of the video, in pixels
+ *
+ * A description of the resolution, in pixels, of the format to capture with a
+ * #CheeseCameraDevice.
+ */
+struct _CheeseVideoFormat
{
- int width;
- int height;
-} CheeseVideoFormat;
+ /*< public >*/
+ gint width;
+ gint height;
+};
GType cheese_video_format_get_type (void) G_GNUC_CONST;
@@ -78,7 +89,7 @@ GType cheese_camera_device_get_type (void) G_GNUC_CONST;
CheeseCameraDevice *cheese_camera_device_new (const gchar *device_id,
const gchar *device_file,
const gchar *product_name,
- gint api_version,
+ guint api_version,
GError **error);
GstCaps *cheese_camera_device_get_caps_for_format (CheeseCameraDevice *device,
@@ -88,7 +99,7 @@ GList * cheese_camera_device_get_format_list (CheeseCameraDevice *dev
const gchar *cheese_camera_device_get_name (CheeseCameraDevice *device);
const gchar *cheese_camera_device_get_src (CheeseCameraDevice *device);
-const gchar *cheese_camera_device_get_id (CheeseCameraDevice *device);
+const gchar *cheese_camera_device_get_uuid (CheeseCameraDevice *device);
const gchar *cheese_camera_device_get_device_file (CheeseCameraDevice *device);
diff --git a/libcheese/cheese-camera.c b/libcheese/cheese-camera.c
index ea1c387..6ad2571 100644
--- a/libcheese/cheese-camera.c
+++ b/libcheese/cheese-camera.c
@@ -99,16 +99,16 @@ typedef struct
gboolean is_recording;
gboolean pipeline_is_playing;
- char *photo_filename;
+ gchar *photo_filename;
- int num_camera_devices;
- char *device_name;
+ gint num_camera_devices;
+ gchar *device_name;
/* an array of CheeseCameraDevices */
GPtrArray *camera_devices;
- int x_resolution;
- int y_resolution;
- int selected_device;
+ gint x_resolution;
+ gint y_resolution;
+ gint selected_device;
CheeseVideoFormat *current_format;
guint eos_timeout_id;
@@ -289,7 +289,7 @@ cheese_camera_add_device (CheeseCameraDeviceMonitor *monitor,
*/
static void
cheese_camera_remove_device (CheeseCameraDeviceMonitor *monitor,
- gchar *uuid,
+ const gchar *uuid,
CheeseCamera *camera)
{
int i;
@@ -299,7 +299,7 @@ cheese_camera_remove_device (CheeseCameraDeviceMonitor *monitor,
for (i = 0; i < priv->num_camera_devices; i++)
{
CheeseCameraDevice *indexDevice = (CheeseCameraDevice *) g_ptr_array_index (priv->camera_devices, i);
- const gchar *indexDeviceId = cheese_camera_device_get_id (indexDevice);
+ const gchar *indexDeviceId = cheese_camera_device_get_uuid (indexDevice);
if (strcmp (indexDeviceId, uuid) == 0)
{
@@ -334,6 +334,15 @@ cheese_camera_detect_camera_devices (CheeseCamera *camera)
cheese_camera_device_monitor_coldplug (priv->monitor);
}
+/*
+ * cheese_camera_set_camera_source:
+ * @camera: a #CheeseCamera
+ *
+ * Set the currently-selected video capture device as the source for a video
+ * steam.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise
+ */
static gboolean
cheese_camera_set_camera_source (CheeseCamera *camera)
{
@@ -554,6 +563,12 @@ cheese_camera_create_video_filter_bin (CheeseCamera *camera, GError **error)
return TRUE;
}
+/*
+ * cheese_camera_get_num_camera_devices:
+ * @camera: a #CheeseCamera
+ *
+ * Returns: the number of #CheeseCameraDevice objects on the system
+ */
static int
cheese_camera_get_num_camera_devices (CheeseCamera *camera)
{
@@ -566,7 +581,8 @@ cheese_camera_get_num_camera_devices (CheeseCamera *camera)
* cheese_camera_get_selected_device:
* @camera: a #CheeseCamera
*
- * Returns: (transfer none): a #CheeseCameraDevice or %NULL
+ * Returns: (transfer none): a #CheeseCameraDevice, or %NULL if there is no
+ * selected device
*/
CheeseCameraDevice *
cheese_camera_get_selected_device (CheeseCamera *camera)
@@ -841,7 +857,8 @@ cheese_camera_connect_effect_texture (CheeseCamera *camera, CheeseEffect *effect
/**
* cheese_camera_start_video_recording:
* @camera: a #CheeseCamera
- * @filename: the name of the video file that should be recorded
+ * @filename: (type filename): the name of the video file to where the
+ * recording will be saved
*
* Start a video recording with the @camera and save it to @filename.
*/
@@ -858,6 +875,12 @@ cheese_camera_start_video_recording (CheeseCamera *camera, const char *filename)
priv->is_recording = TRUE;
}
+/*
+ * cheese_camera_force_stop_video_recording:
+ * @data: a #CheeseCamera on which to forcibly stop video recording
+ *
+ * Returns: %FALSE
+ */
static gboolean
cheese_camera_force_stop_video_recording (gpointer data)
{
@@ -905,8 +928,16 @@ cheese_camera_stop_video_recording (CheeseCamera *camera)
}
}
+/*
+ * cheese_camera_image_done_cb:
+ * @camerabin: a CameraBin #GstElement
+ * @filename: (type filename): path to where the photo was saved
+ * @camera: a #CheeseCamera
+ *
+ * Emits the ::photo-saved signal, if a filename was provided.
+ */
static void
-cheese_camera_image_done_cb (GstElement *camerabin, gchar *filename,
+cheese_camera_image_done_cb (GstElement *camerabin, const gchar *filename,
CheeseCamera *camera)
{
CheeseCameraPrivate *priv = CHEESE_CAMERA_GET_PRIVATE (camera);
@@ -920,7 +951,7 @@ cheese_camera_image_done_cb (GstElement *camerabin, gchar *filename,
/**
* cheese_camera_take_photo:
* @camera: a #CheeseCamera
- * @filename: name of the file to save a photo to
+ * @filename: (type filename): name of the file to save a photo to
*
* Save a photo taken with the @camera to a new file at @filename.
*
@@ -1163,8 +1194,8 @@ cheese_camera_class_init (CheeseCameraClass *klass)
*/
g_object_class_install_property (object_class, PROP_VIDEO_TEXTURE,
g_param_spec_pointer ("video-texture",
- NULL,
- NULL,
+ "Video texture",
+ "The video texture for the CheeseCamera to render into",
G_PARAM_READWRITE));
/**
@@ -1174,8 +1205,8 @@ cheese_camera_class_init (CheeseCameraClass *klass)
*/
g_object_class_install_property (object_class, PROP_DEVICE_NAME,
g_param_spec_string ("device-name",
- NULL,
- NULL,
+ "Device name",
+ "The path to the device node for the video capture device.",
"",
G_PARAM_READWRITE));
@@ -1186,8 +1217,8 @@ cheese_camera_class_init (CheeseCameraClass *klass)
*/
g_object_class_install_property (object_class, PROP_FORMAT,
g_param_spec_boxed ("format",
- NULL,
- NULL,
+ "Video format",
+ "The format of the video capture device",
CHEESE_TYPE_VIDEO_FORMAT,
G_PARAM_READWRITE));
@@ -1212,13 +1243,15 @@ cheese_camera_init (CheeseCamera *camera)
/**
* cheese_camera_new:
* @video_texture: a #ClutterTexture
- * @camera_device_name: (allow-none): the device name
+ * @camera_device_name: (allow-none): the device node path
* @x_resolution: the resolution width
* @y_resolution: the resolution height
+ *
+ * Returns: a new #CheeseCamera
*/
CheeseCamera *
-cheese_camera_new (ClutterTexture *video_texture, char *camera_device_name,
- int x_resolution, int y_resolution)
+cheese_camera_new (ClutterTexture *video_texture, const gchar *camera_device_name,
+ gint x_resolution, gint y_resolution)
{
CheeseCamera *camera;
CheeseVideoFormat *format = g_slice_new (CheeseVideoFormat);
@@ -1229,7 +1262,7 @@ cheese_camera_new (ClutterTexture *video_texture, char *camera_device_name,
if (camera_device_name)
{
camera = g_object_new (CHEESE_TYPE_CAMERA, "video-texture", video_texture,
- "device_name", camera_device_name,
+ "device-name", camera_device_name,
"format", format, NULL);
}
else
@@ -1242,21 +1275,29 @@ cheese_camera_new (ClutterTexture *video_texture, char *camera_device_name,
}
/**
- * cheese_camera_set_device_by_dev_file:
+ * cheese_camera_set_device_by_device_node:
* @camera: a #CheeseCamera
- * @file: the filename
+ * @file: the device node path
*
- * Set the active video capture device with the device node path.
+ * Set the active video capture device of the @camera, matching by device node
+ * path.
*/
void
cheese_camera_set_device_by_dev_file (CheeseCamera *camera, const gchar *file)
{
g_return_if_fail (CHEESE_IS_CAMERA (camera));
- g_object_set (camera, "device_name", file, NULL);
+ g_object_set (camera, "device-name", file, NULL);
}
+/*
+ * cheese_camera_set_device_by_uuid:
+ * @camera: a #CheeseCamera
+ * @uuid: UUID of a #CheeseCameraDevice
+ *
+ * Set the active video capture device of the @camera, matching by UUID.
+ */
static void
-cheese_camera_set_device_by_dev_udi (CheeseCamera *camera, const gchar *udi)
+cheese_camera_set_device_by_dev_uuid (CheeseCamera *camera, const gchar *uuid)
{
CheeseCameraPrivate *priv = CHEESE_CAMERA_GET_PRIVATE (camera);
int i;
@@ -1267,10 +1308,10 @@ cheese_camera_set_device_by_dev_udi (CheeseCamera *camera, const gchar *udi)
for (i = 0; i < priv->num_camera_devices; i++)
{
CheeseCameraDevice *device = g_ptr_array_index (priv->camera_devices, i);
- if (strcmp (cheese_camera_device_get_id (device), udi) == 0)
+ if (strcmp (cheese_camera_device_get_uuid (device), uuid) == 0)
{
g_object_set (camera,
- "device_name", cheese_camera_device_get_id (device),
+ "device-name", cheese_camera_device_get_uuid (device),
NULL);
break;
}
@@ -1280,13 +1321,13 @@ cheese_camera_set_device_by_dev_udi (CheeseCamera *camera, const gchar *udi)
/**
* cheese_camera_setup:
* @camera: a #CheeseCamera
- * @id: (allow-none): the device id
- * @error: return location for a #GError or %NULL
+ * @uuid: (allow-none): UUID of the video capture device, or %NULL
+ * @error: return location for a #GError, or %NULL
*
* Setup a video capture device.
*/
void
-cheese_camera_setup (CheeseCamera *camera, const char *id, GError **error)
+cheese_camera_setup (CheeseCamera *camera, const gchar *uuid, GError **error)
{
CheeseCameraPrivate *priv = CHEESE_CAMERA_GET_PRIVATE (camera);
@@ -1302,9 +1343,9 @@ cheese_camera_setup (CheeseCamera *camera, const char *id, GError **error)
return;
}
- if (id != NULL)
+ if (uuid != NULL)
{
- cheese_camera_set_device_by_dev_udi (camera, id);
+ cheese_camera_set_device_by_dev_uuid (camera, uuid);
}
@@ -1365,6 +1406,9 @@ cheese_camera_setup (CheeseCamera *camera, const char *id, GError **error)
* cheese_camera_get_camera_devices:
* @camera: a #CheeseCamera
*
+ * Get the list of #CheeseCameraDevice objects, representing active video
+ * capture devices on the system.
+ *
* Returns: (element-type Cheese.CameraDevice) (transfer container): an array
* of #CheeseCameraDevice
*/
@@ -1384,8 +1428,11 @@ cheese_camera_get_camera_devices (CheeseCamera *camera)
* cheese_camera_get_video_formats:
* @camera: a #CheeseCamera
*
+ * Gets the list of #CheeseVideoFormat supported by the selected
+ * #CheeseCameraDevice on the @camera.
+ *
* Returns: (element-type Cheese.VideoFormat) (transfer container): a #GList of
- * #CheeseVideoFormat
+ * #CheeseVideoFormat, or %NULL if there was no device selected
*/
GList *
cheese_camera_get_video_formats (CheeseCamera *camera)
@@ -1406,7 +1453,8 @@ cheese_camera_get_video_formats (CheeseCamera *camera)
* cheese_camera_is_playing:
* @camera: a #CheeseCamera
*
- * Returns: whether the #CheeseCamera is in the playing state
+ * Returns: %TRUE if the #CheeseCamera is in the playing state, %FALSE
+ * otherwise
*/
static gboolean
cheese_camera_is_playing (CheeseCamera *camera)
@@ -1425,7 +1473,8 @@ cheese_camera_is_playing (CheeseCamera *camera)
* @camera: a #CheeseCamera
* @format: a #CheeseVideoFormat
*
- * Sets a #CheeseVideoFormat on a #CheeseCamera.
+ * Sets a #CheeseVideoFormat on a #CheeseCamera, restarting the video stream if
+ * necessary.
*/
void
cheese_camera_set_video_format (CheeseCamera *camera, CheeseVideoFormat *format)
diff --git a/libcheese/cheese-camera.h b/libcheese/cheese-camera.h
index d55eb3f..b03c234 100644
--- a/libcheese/cheese-camera.h
+++ b/libcheese/cheese-camera.h
@@ -93,25 +93,25 @@ typedef enum
GType cheese_camera_get_type (void);
CheeseCamera *cheese_camera_new (ClutterTexture *video_texture,
- char *camera_device_name,
- int x_resolution,
- int y_resolution);
+ const gchar *camera_device_name,
+ gint x_resolution,
+ gint y_resolution);
const CheeseVideoFormat *cheese_camera_get_current_video_format (CheeseCamera *camera);
-void cheese_camera_setup (CheeseCamera *camera, const char *id, GError **error);
+void cheese_camera_setup (CheeseCamera *camera, const gchar *uuid, GError **error);
void cheese_camera_play (CheeseCamera *camera);
void cheese_camera_stop (CheeseCamera *camera);
void cheese_camera_set_effect (CheeseCamera *camera, CheeseEffect *effect);
void cheese_camera_connect_effect_texture (CheeseCamera *camera,
CheeseEffect *effect,
ClutterTexture *texture);
-void cheese_camera_start_video_recording (CheeseCamera *camera, const char *filename);
+void cheese_camera_start_video_recording (CheeseCamera *camera, const gchar *filename);
void cheese_camera_stop_video_recording (CheeseCamera *camera);
-gboolean cheese_camera_take_photo (CheeseCamera *camera, const char *filename);
+gboolean cheese_camera_take_photo (CheeseCamera *camera, const gchar *filename);
gboolean cheese_camera_take_photo_pixbuf (CheeseCamera *camera);
CheeseCameraDevice *cheese_camera_get_selected_device (CheeseCamera *camera);
GPtrArray * cheese_camera_get_camera_devices (CheeseCamera *camera);
-void cheese_camera_set_device_by_dev_file (CheeseCamera *camera, const char *file);
+void cheese_camera_set_device_by_dev_file (CheeseCamera *camera, const gchar *file);
void cheese_camera_switch_camera_device (CheeseCamera *camera);
GList * cheese_camera_get_video_formats (CheeseCamera *camera);
void cheese_camera_set_video_format (CheeseCamera *camera,
diff --git a/libcheese/cheese-effect.c b/libcheese/cheese-effect.c
index 467f2cb..2ca2fa0 100644
--- a/libcheese/cheese-effect.c
+++ b/libcheese/cheese-effect.c
@@ -119,8 +119,8 @@ cheese_effect_class_init (CheeseEffectClass *klass)
*/
g_object_class_install_property (object_class, PROP_NAME,
g_param_spec_string ("name",
- NULL,
- NULL,
+ "Name",
+ "Name of the effect",
"",
G_PARAM_READWRITE));
@@ -131,8 +131,8 @@ cheese_effect_class_init (CheeseEffectClass *klass)
*/
g_object_class_install_property (object_class, PROP_PIPELINE_DESC,
g_param_spec_string ("pipeline_desc",
- NULL,
- NULL,
+ "Pipeline description",
+ "Description of the GStreamer pipeline associated with the effect",
"",
G_PARAM_READWRITE));
@@ -143,8 +143,8 @@ cheese_effect_class_init (CheeseEffectClass *klass)
*/
g_object_class_install_property (object_class, PROP_CONTROL_VALVE,
g_param_spec_object ("control_valve",
- NULL,
- NULL,
+ "Control valve",
+ "TODO",
GST_TYPE_ELEMENT,
G_PARAM_READWRITE));
}
diff --git a/libcheese/cheese-fileutil.c b/libcheese/cheese-fileutil.c
index d2b06e7..5bb86f7 100644
--- a/libcheese/cheese-fileutil.c
+++ b/libcheese/cheese-fileutil.c
@@ -52,11 +52,14 @@ typedef struct
gchar *burst_raw_name;
} CheeseFileUtilPrivate;
+static gchar *
+cheese_fileutil_get_path_before_224 (CheeseFileUtil *fileutil);
+
/**
* cheese_fileutil_get_video_path:
* @fileutil: a #CheeseFileUtil
*
- * Returns: (transfer none): the Cheese video path
+ * Returns: (transfer none) (type filename): the Cheese video path
*/
const gchar *
cheese_fileutil_get_video_path (CheeseFileUtil *fileutil)
@@ -70,7 +73,7 @@ cheese_fileutil_get_video_path (CheeseFileUtil *fileutil)
* cheese_fileutil_get_photo_path:
* @fileutil: a #CheeseFileUtil
*
- * Returns: (transfer none): the Cheese photo path
+ * Returns: (transfer none) (type filename): the Cheese photo path
*/
const gchar *
cheese_fileutil_get_photo_path (CheeseFileUtil *fileutil)
@@ -80,13 +83,13 @@ cheese_fileutil_get_photo_path (CheeseFileUtil *fileutil)
return priv->photo_path;
}
-/**
+/*
* cheese_fileutil_get_path_before_224:
* @fileutil: a #CheeseFileUtil
*
- * Returns: (transfer full): the photo path for Cheese versions before 2.24
+ * Returns: (transfer full) (type filename): the photo path for Cheese versions before 2.24
*/
-gchar *
+static gchar *
cheese_fileutil_get_path_before_224 (CheeseFileUtil *fileutil)
{
return g_strjoin (G_DIR_SEPARATOR_S, g_get_home_dir (), ".gnome2", "cheese", "media", NULL);
@@ -102,7 +105,7 @@ cheese_fileutil_get_path_before_224 (CheeseFileUtil *fileutil)
* function increments the burst count automatically. To start a new burst,
* first call cheese_fileutil_reset_burst().
*
- * Returns: (transfer full): a new filename
+ * Returns: (transfer full) (type filename): a new filename
*/
gchar *
cheese_fileutil_get_new_media_filename (CheeseFileUtil *fileutil, CheeseMediaMode mode)
diff --git a/libcheese/cheese-fileutil.h b/libcheese/cheese-fileutil.h
index 2bea0c5..60d1a78 100644
--- a/libcheese/cheese-fileutil.h
+++ b/libcheese/cheese-fileutil.h
@@ -32,9 +32,9 @@
#define CHEESE_PHOTO_NAME_SUFFIX ".jpg"
/**
- * CHEESE_PHOTO_VIDEO_NAME_SUFFIX:
+ * CHEESE_VIDEO_NAME_SUFFIX:
*
- * the filename suffix for videos saved by Cheese.
+ * The filename suffix for videos saved by Cheese.
*/
#define CHEESE_VIDEO_NAME_SUFFIX ".ogv"
@@ -78,7 +78,8 @@ struct _CheeseFileUtil
* @CHEESE_MEDIA_MODE_VIDEO: video
* @CHEESE_MEDIA_MODE_BURST: a burst of photos
*
- * The media type.
+ * The media type, used for generating filenames with
+ * cheese_fileutil_get_new_media_filename().
*/
typedef enum
{
@@ -93,7 +94,6 @@ CheeseFileUtil *cheese_fileutil_new (void);
const gchar *cheese_fileutil_get_video_path (CheeseFileUtil *fileutil);
const gchar *cheese_fileutil_get_photo_path (CheeseFileUtil *fileutil);
-gchar *cheese_fileutil_get_path_before_224 (CheeseFileUtil *fileutil);
gchar *cheese_fileutil_get_new_media_filename (CheeseFileUtil *fileutil, CheeseMediaMode mode);
void cheese_fileutil_reset_burst (CheeseFileUtil *fileutil);
diff --git a/libcheese/cheese-flash.c b/libcheese/cheese-flash.c
index e14e300..cd90d83 100644
--- a/libcheese/cheese-flash.c
+++ b/libcheese/cheese-flash.c
@@ -286,8 +286,8 @@ cheese_flash_class_init (CheeseFlashClass *klass)
*/
g_object_class_install_property (object_class, PROP_PARENT,
g_param_spec_object ("parent",
- NULL,
- NULL,
+ "Parent widget",
+ "The flash will be fired on the screen where the parent widget is shown",
GTK_TYPE_WIDGET,
G_PARAM_WRITABLE));
}
diff --git a/libcheese/cheese-widget.c b/libcheese/cheese-widget.c
index 3dc93b9..82ba66d 100644
--- a/libcheese/cheese-widget.c
+++ b/libcheese/cheese-widget.c
@@ -403,14 +403,14 @@ cheese_widget_class_init (CheeseWidgetClass *klass)
*
* Current state of the widget.
*
- * Connect to notify::state signal to get notified about state
- * changes. Useful to update other widgets sensitiveness when the
- * camera is ready or to handle errors if camera setup fails.
+ * Connect to notify::state signal to get notified about state changes.
+ * Useful to update other widgets sensitivities when the camera is ready or
+ * to handle errors if camera setup fails.
*/
g_object_class_install_property (object_class, PROP_STATE,
g_param_spec_enum ("state",
- NULL,
- NULL,
+ "State",
+ "The current state of the widget",
CHEESE_TYPE_WIDGET_STATE,
CHEESE_WIDGET_STATE_NONE,
G_PARAM_READABLE));
@@ -445,7 +445,7 @@ cheese_widget_get_settings (CheeseWidget *widget)
return priv->settings;
}
-/**
+/*
* cheese_widget_get_camera:
* @widget: a #CheeseWidget
*
@@ -463,7 +463,7 @@ cheese_widget_get_camera (CheeseWidget *widget)
return G_OBJECT (priv->webcam);
}
-/**
+/*
* cheese_widget_get_video_area:
* @widget: a #CheeseWidget
*
diff --git a/src/vapi/cheese-common.vapi b/src/vapi/cheese-common.vapi
index be6c51b..a65f3d2 100644
--- a/src/vapi/cheese-common.vapi
+++ b/src/vapi/cheese-common.vapi
@@ -65,16 +65,16 @@ namespace Cheese
public class CameraDevice : GLib.Object, GLib.Initable
{
[CCode (has_construct_function = false)]
- public CameraDevice (string device_id, string device_file, string product_name, int api_version) throws GLib.Error;
+ public CameraDevice (string uuid, string device_file, string product_name, int api_version) throws GLib.Error;
public unowned Cheese.VideoFormat get_best_format ();
public unowned Gst.Caps get_caps_for_format (Cheese.VideoFormat format);
public unowned string get_device_file ();
public unowned GLib.List get_format_list ();
- public unowned string get_id ();
+ public unowned string get_uuid ();
public unowned string get_name ();
public unowned string get_src ();
[NoAccessorMethod]
- public int api {get; construct;}
+ public uint v4l_api {get; construct;}
public string device_file {get; construct;}
[NoAccessorMethod]
public string device_id {owned get; construct;}
@@ -87,7 +87,7 @@ namespace Cheese
[CCode (has_construct_function = false)]
public CameraDeviceMonitor ();
public void coldplug ();
- public virtual signal void added (string id, string device_file, string product_name, int api_version);
+ public virtual signal void added (string uuid, string device_file, string product_name, uint api_version);
public virtual signal void removed (string id);
}
@@ -99,8 +99,6 @@ namespace Cheese
public FileUtil ();
[CCode (cname = "cheese_fileutil_get_new_media_filename")]
public unowned string get_new_media_filename (Cheese.MediaMode mode);
- [CCode (cname = "cheese_fileutil_get_path_before_224")]
- public unowned string get_path_before_224 ();
[CCode (cname = "cheese_fileutil_get_photo_path")]
public unowned string get_photo_path ();
[CCode (cname = "cheese_fileutil_get_video_path")]
diff --git a/tests/cheese-test-monitor.c b/tests/cheese-test-monitor.c
index aed85e9..7153d51 100644
--- a/tests/cheese-test-monitor.c
+++ b/tests/cheese-test-monitor.c
@@ -5,19 +5,19 @@
static void
added_cb (CheeseCameraDeviceMonitor *monitor,
- const char *id,
- const char *device_file,
- const char *product_name,
- gint api_version)
+ CheeseCameraDevice *device,
+ gpointer user_data)
{
- g_message ("Added new device with ID '%s'", id);
+ g_message ("Added new device with ID '%s'", cheese_camera_device_get_uuid (device));
+ g_object_unref (device);
}
static void
removed_cb (CheeseCameraDeviceMonitor *monitor,
- const char *id)
+ const gchar *uuid,
+ gpointer user_data)
{
- g_message ("Removed device with ID '%s'", id);
+ g_message ("Removed device with ID '%s'", uuid);
}
int
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
