From 77db6bf3d6cda87af44300026abd308d662253a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Cr=C3=AAte?= Date: Fri, 20 Jun 2014 16:55:06 -0400 Subject: [PATCH] GstDevice: Document GstDevice and related classes --- docs/gst/gstreamer-sections.txt | 76 ++++++++++++++++++++------------- gst/gstdevice.c | 18 ++++++++ gst/gstdevice.h | 22 ++++++++++ gst/gstdevicemonitor.c | 18 ++++++++ gst/gstdevicemonitor.h | 15 +++++-- gst/gstdevicemonitorfactory.h | 8 ++++ gst/gstglobaldevicemonitor.c | 28 ++++++++++-- gst/gstglobaldevicemonitor.h | 2 + gst/gstmessage.c | 2 + 9 files changed, 151 insertions(+), 38 deletions(-) diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index 72579f56aa..d6e1997d90 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -1580,6 +1580,10 @@ gst_message_parse_context_type gst_message_new_have_context gst_message_parse_have_context +gst_message_new_device_added +gst_message_new_device_removed +gst_message_parse_device_added +gst_message_parse_device_removed GstMessageClass GST_MESSAGE @@ -3324,6 +3328,15 @@ GST_CHECK_VERSION GstDevice GstDeviceClass +gst_device_create_element +gst_device_get_caps +gst_device_get_display_name +gst_device_get_klass +gst_device_has_classes +gst_device_has_classesv +gst_device_reconfigure_element + + GST_DEVICE GST_DEVICE_CAST GST_DEVICE_CLASS @@ -3331,15 +3344,7 @@ GST_DEVICE_GET_CLASS GST_IS_DEVICE GST_IS_DEVICE_CLASS GST_TYPE_DEVICE - -gst_device_create_element -gst_device_get_caps -gst_device_get_display_name -gst_device_get_klass gst_device_get_type -gst_device_has_classes -gst_device_has_classesv -gst_device_reconfigure_element
@@ -3347,13 +3352,6 @@ gst_device_reconfigure_element GstDeviceMonitor GstDeviceMonitor GstDeviceMonitorClass -GST_DEVICE_MONITOR -GST_DEVICE_MONITOR_CAST -GST_DEVICE_MONITOR_CLASS -GST_DEVICE_MONITOR_GET_CLASS -GST_IS_DEVICE_MONITOR -GST_IS_DEVICE_MONITOR_CLASS -GST_TYPE_DEVICE_MONITOR gst_device_monitor_can_monitor gst_device_monitor_class_add_metadata gst_device_monitor_class_add_static_metadata @@ -3365,10 +3363,20 @@ gst_device_monitor_device_remove gst_device_monitor_get_bus gst_device_monitor_get_devices gst_device_monitor_get_factory -gst_device_monitor_get_type gst_device_monitor_register gst_device_monitor_start gst_device_monitor_stop + + +GstDevicePrivate +GST_DEVICE_MONITOR +GST_DEVICE_MONITOR_CAST +GST_DEVICE_MONITOR_CLASS +GST_DEVICE_MONITOR_GET_CLASS +GST_IS_DEVICE_MONITOR +GST_IS_DEVICE_MONITOR_CLASS +GST_TYPE_DEVICE_MONITOR +gst_device_monitor_get_type
@@ -3376,20 +3384,25 @@ gst_device_monitor_stop GstDeviceMonitorFactory GstDeviceMonitorFactory GstDeviceMonitorFactoryClass -GST_DEVICE_MONITOR_FACTORY -GST_DEVICE_MONITOR_FACTORY_CAST -GST_DEVICE_MONITOR_FACTORY_CLASS -GST_TYPE_DEVICE_MONITOR_FACTORY gst_device_monitor_factory_find gst_device_monitor_factory_get gst_device_monitor_factory_get_by_name gst_device_monitor_factory_get_device_monitor_type gst_device_monitor_factory_get_metadata gst_device_monitor_factory_get_metadata_keys -gst_device_monitor_factory_get_type gst_device_monitor_factory_has_classes gst_device_monitor_factory_has_classesv gst_device_monitor_factory_list_get_device_monitors + + +GstDeviceMonitorPrivate +GST_DEVICE_MONITOR_FACTORY +GST_DEVICE_MONITOR_FACTORY_CAST +GST_DEVICE_MONITOR_FACTORY_CLASS +GST_TYPE_DEVICE_MONITOR_FACTORY +GST_IS_DEVICE_MONITOR_FACTORY +GST_IS_DEVICE_MONITOR_FACTORY_CLASS +gst_device_monitor_factory_get_type
@@ -3397,6 +3410,18 @@ gst_device_monitor_factory_list_get_device_monitors GstGlobalDeviceMonitor GstGlobalDeviceMonitor GstGlobalDeviceMonitorClass +gst_global_device_monitor_get_bus +gst_global_device_monitor_get_caps_filter +gst_global_device_monitor_get_classes_filter +gst_global_device_monitor_get_devices +gst_global_device_monitor_new +gst_global_device_monitor_set_caps_filter +gst_global_device_monitor_set_classes_filter +gst_global_device_monitor_start +gst_global_device_monitor_stop + + +GstGlobalDeviceMonitorPrivate GST_GLOBAL_DEVICE_MONITOR GST_GLOBAL_DEVICE_MONITOR_CAST GST_GLOBAL_DEVICE_MONITOR_CLASS @@ -3404,15 +3429,6 @@ GST_GLOBAL_DEVICE_MONITOR_GET_CLASS GST_IS_GLOBAL_DEVICE_MONITOR GST_IS_GLOBAL_DEVICE_MONITOR_CLASS GST_TYPE_GLOBAL_DEVICE_MONITOR -gst_global_device_monitor_get_bus -gst_global_device_monitor_get_caps_filter -gst_global_device_monitor_get_classes_filter -gst_global_device_monitor_get_devices gst_global_device_monitor_get_type -gst_global_device_monitor_new -gst_global_device_monitor_set_caps_filter -gst_global_device_monitor_set_classes_filter -gst_global_device_monitor_start -gst_global_device_monitor_stop
diff --git a/gst/gstdevice.c b/gst/gstdevice.c index 36faf652d6..e67ec2ca4a 100644 --- a/gst/gstdevice.c +++ b/gst/gstdevice.c @@ -19,6 +19,21 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstdevice + * @short_description: Object representing a device + * @see_also: #GstDeviceMonitor + * + * #GstDevice are objects representing a device, they contain + * relevant metadata about the device, such as its class and the #GstCaps + * representing the media types it can produce or handle. + * + * #GstDevice are created by #GstDeviceMonitor objects which can be + * aggregated by #GstGlobalDeviceMonitor objects. + * + * Since: 1.4 + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -163,6 +178,9 @@ gst_device_set_property (GObject * object, guint prop_id, * @name: (allow-none): name of new element, or %NULL to automatically * create a unique name. * + * Creates the element with all of the required paramaters set to use + * this device. + * * Returns: (transfer full): a new #GstElement configured to use this device * * Since: 1.4 diff --git a/gst/gstdevice.h b/gst/gstdevice.h index 9a5d9b3fc0..80da209c23 100644 --- a/gst/gstdevice.h +++ b/gst/gstdevice.h @@ -42,6 +42,14 @@ typedef struct _GstDevicePrivate GstDevicePrivate; #define GST_DEVICE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_DEVICE, GstDeviceClass)) #define GST_DEVICE_CAST(obj) ((GstDevice *)(obj)) +/** + * GstDevice: + * @parent: The parent #GstObject strucuture. + * + * A device object. + * + * Since: 1.4 + */ struct _GstDevice { GstObject parent; @@ -52,6 +60,20 @@ struct _GstDevice { gpointer _gst_reserved[GST_PADDING]; }; +/** + * GstDeviceClass: + * @parent_class: The parent #GstObjectClass strucuture. + * @create_element: Creates the fully configured element to access this device. + * Subclasses need to override this and return a new element. + * @reconfigure_element: This only needs to be implemented by subclasses if the + * element can be reconfigured to use a different device. See the documentation + * for gst_device_reconfigure_element(). + * + * The class structure for a #GstDevice object. + * + * Since: 1.4 + */ + struct _GstDeviceClass { GstObjectClass parent_class; diff --git a/gst/gstdevicemonitor.c b/gst/gstdevicemonitor.c index 82324f2e1c..6fabe11900 100644 --- a/gst/gstdevicemonitor.c +++ b/gst/gstdevicemonitor.c @@ -19,6 +19,24 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstdevicemonitor + * @short_description: A device monitor and prober + * @see_also: #GstDevice, #GstGlobalDeviceMonitor + * + * A #GstDeviceMonitor subclass is provided by a plugin that handles devices + * if there is a way to programatically list connected devices. It can also + * optionally provide updates to the list of connected devices. + * + * Each #GstDeviceMonitor subclass is a singleton, a plugin should + * normally provide a single subclass for all devices. + * + * Applications would normally use a #GstGlobalDeviceMonitor to monitor devices + * from all revelant monitors. + * + * Since: 1.4 + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif diff --git a/gst/gstdevicemonitor.h b/gst/gstdevicemonitor.h index e1677b3663..f5c33073e4 100644 --- a/gst/gstdevicemonitor.h +++ b/gst/gstdevicemonitor.h @@ -44,17 +44,21 @@ typedef struct _GstDeviceMonitorPrivate GstDeviceMonitorPrivate; /** * GstDeviceMonitor: + * @parent: The parent #GstObject + * @devices: a #GList of the #GstDevice objects + * + * The structure of the base #GstDeviceMonitor * * Since: 1.4 */ struct _GstDeviceMonitor { GstObject parent; - /*< private >*/ - /* Protected by the Object lock */ GList *devices; + /*< private >*/ + GstDeviceMonitorPrivate *priv; gpointer _gst_reserved[GST_PADDING]; @@ -62,12 +66,15 @@ struct _GstDeviceMonitor { /** * GstDeviceMonitorClass: + * @parent_class: the parent #GstObjectClass structure * @factory: a pointer to the #GstDeviceMonitorFactory that creates this * monitor * @probe: Returns a list of devices that are currently available. * This should never block. - * @start: Starts monitoring for new devices. - * @stop: Stops monitoring for new devices + * @start: Starts monitoring for new devices. Only subclasses that can know + * that devices have been added or remove need to implement this method. + * @stop: Stops monitoring for new devices. Only subclasses that implement + * the start() method need to implement this method. * * The structure of the base #GstDeviceMonitorClass * diff --git a/gst/gstdevicemonitorfactory.h b/gst/gstdevicemonitorfactory.h index ad4ec0540d..02bf04a8b7 100644 --- a/gst/gstdevicemonitorfactory.h +++ b/gst/gstdevicemonitorfactory.h @@ -33,6 +33,14 @@ * * Since: 1.4 */ + +/** + * GstDeviceMonitorFactoryClass: + * + * The opaque #GstDeviceMonitorFactoryClass data structure. + * + * Since: 1.4 + */ typedef struct _GstDeviceMonitorFactory GstDeviceMonitorFactory; typedef struct _GstDeviceMonitorFactoryClass GstDeviceMonitorFactoryClass; diff --git a/gst/gstglobaldevicemonitor.c b/gst/gstglobaldevicemonitor.c index 58a92b3987..68900efe95 100644 --- a/gst/gstglobaldevicemonitor.c +++ b/gst/gstglobaldevicemonitor.c @@ -18,7 +18,23 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ -/* FIXME: documentation section! */ + +/** + * SECTION:gstglobaldevicemonitor + * @short_description: A global device monitor and prober + * @see_also: #GstDevice, #GstDeviceMonitor + * + * Applications should create a #GstGlobalDeviceMonitor when they want + * to probe, list and monitor devices of a specific type. The + * #GstGlobalDeviceMonitor will create the appropriate + * #GstDeviceMonitor objects and manage them. It will then post + * messages on its #GstBus for devices that have been added and + * removed. + * + * Since: 1.4 + */ + + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -230,8 +246,8 @@ again: * @monitor: A #GstGlobalDeviceMonitor * * Starts monitoring the devices, one this has succeeded, the - * #GstGlobalDeviceMonitor:added and #GstGlobalDeviceMonitor:removed - * signals will be emitted when the list of devices changes. + * %GST_MESSAGE_DEVICE_ADDED and %GST_MESSAGE_DEVICE_REMOVED messages + * will be emitted on the bus when the list of devices changes. * * Returns: %TRUE if the device monitoring could be started * @@ -301,7 +317,7 @@ gst_global_device_monitor_stop (GstGlobalDeviceMonitor * monitor) /** * gst_global_device_monitor_set_classes_filter: - * @self: the global device monitor + * @monitor: the global device monitor * @classes: device classes to use as filter * * Filter devices monitored by device class, e.g. in case you are only @@ -431,6 +447,8 @@ gst_global_device_monitor_set_caps_filter (GstGlobalDeviceMonitor * monitor, * gst_global_device_monitor_get_caps_filter: * @monitor: a global device monitor * + * Get the #GstCaps filter set by gst_global_device_monitor_set_caps_filter(). + * * Returns: (transfer full): the filter caps that are active (or ANY caps) * * Since: 1.4 @@ -452,6 +470,8 @@ gst_global_device_monitor_get_caps_filter (GstGlobalDeviceMonitor * monitor) /** * gst_global_device_monitor_new: * + * Create a new #GstGlobalDeviceMonitor + * * Returns: (transfer full): a new global device monitor. * * Since: 1.4 diff --git a/gst/gstglobaldevicemonitor.h b/gst/gstglobaldevicemonitor.h index 1b05ae1c3f..b92fd4023b 100644 --- a/gst/gstglobaldevicemonitor.h +++ b/gst/gstglobaldevicemonitor.h @@ -44,6 +44,7 @@ typedef struct _GstGlobalDeviceMonitorClass GstGlobalDeviceMonitorClass; /** * GstGlobalDeviceMonitor: + * @parent: the parent #GstObject structure * * Opaque global device monitor object structure. * @@ -61,6 +62,7 @@ struct _GstGlobalDeviceMonitor { /** * GstGlobalDeviceMonitorClass: + * @parent_class: the parent #GstObjectClass structure * * Opaque global device monitor class structure. * diff --git a/gst/gstmessage.c b/gst/gstmessage.c index a0254cc587..5014016fcd 100644 --- a/gst/gstmessage.c +++ b/gst/gstmessage.c @@ -2361,6 +2361,7 @@ gst_message_new_device_added (GstObject * src, GstDevice * device) /** * gst_message_parse_device_added: + * @message: a #GstMessage of type %GST_MESSAGE_DEVICE_ADDED * @device: (out) (allow-none) (transfer none): A location where to store a * pointer to the new #GstDevice, or %NULL * @@ -2412,6 +2413,7 @@ gst_message_new_device_removed (GstObject * src, GstDevice * device) /** * gst_message_parse_device_removed: + * @message: a #GstMessage of type %GST_MESSAGE_DEVICE_REMOVED * @device: (out) (allow-none) (transfer none): A location where to store a * pointer to the removed #GstDevice, or %NULL *