Commit 77db6bf3 authored by Olivier Crête's avatar Olivier Crête 👻

GstDevice: Document GstDevice and related classes

parent 5b3ee70e
...@@ -1580,6 +1580,10 @@ gst_message_parse_context_type ...@@ -1580,6 +1580,10 @@ gst_message_parse_context_type
gst_message_new_have_context gst_message_new_have_context
gst_message_parse_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
<SUBSECTION Standard> <SUBSECTION Standard>
GstMessageClass GstMessageClass
GST_MESSAGE GST_MESSAGE
...@@ -3324,6 +3328,15 @@ GST_CHECK_VERSION ...@@ -3324,6 +3328,15 @@ GST_CHECK_VERSION
GstDevice GstDevice
GstDeviceClass 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
<SUBSECTION Standard>
GST_DEVICE GST_DEVICE
GST_DEVICE_CAST GST_DEVICE_CAST
GST_DEVICE_CLASS GST_DEVICE_CLASS
...@@ -3331,15 +3344,7 @@ GST_DEVICE_GET_CLASS ...@@ -3331,15 +3344,7 @@ GST_DEVICE_GET_CLASS
GST_IS_DEVICE GST_IS_DEVICE
GST_IS_DEVICE_CLASS GST_IS_DEVICE_CLASS
GST_TYPE_DEVICE 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_get_type
gst_device_has_classes
gst_device_has_classesv
gst_device_reconfigure_element
</SECTION> </SECTION>
<SECTION> <SECTION>
...@@ -3347,13 +3352,6 @@ gst_device_reconfigure_element ...@@ -3347,13 +3352,6 @@ gst_device_reconfigure_element
<TITLE>GstDeviceMonitor</TITLE> <TITLE>GstDeviceMonitor</TITLE>
GstDeviceMonitor GstDeviceMonitor
GstDeviceMonitorClass 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_can_monitor
gst_device_monitor_class_add_metadata gst_device_monitor_class_add_metadata
gst_device_monitor_class_add_static_metadata gst_device_monitor_class_add_static_metadata
...@@ -3365,10 +3363,20 @@ gst_device_monitor_device_remove ...@@ -3365,10 +3363,20 @@ gst_device_monitor_device_remove
gst_device_monitor_get_bus gst_device_monitor_get_bus
gst_device_monitor_get_devices gst_device_monitor_get_devices
gst_device_monitor_get_factory gst_device_monitor_get_factory
gst_device_monitor_get_type
gst_device_monitor_register gst_device_monitor_register
gst_device_monitor_start gst_device_monitor_start
gst_device_monitor_stop gst_device_monitor_stop
<SUBSECTION Standard>
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
</SECTION> </SECTION>
<SECTION> <SECTION>
...@@ -3376,20 +3384,25 @@ gst_device_monitor_stop ...@@ -3376,20 +3384,25 @@ gst_device_monitor_stop
<TITLE>GstDeviceMonitorFactory</TITLE> <TITLE>GstDeviceMonitorFactory</TITLE>
GstDeviceMonitorFactory GstDeviceMonitorFactory
GstDeviceMonitorFactoryClass 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_find
gst_device_monitor_factory_get gst_device_monitor_factory_get
gst_device_monitor_factory_get_by_name gst_device_monitor_factory_get_by_name
gst_device_monitor_factory_get_device_monitor_type gst_device_monitor_factory_get_device_monitor_type
gst_device_monitor_factory_get_metadata gst_device_monitor_factory_get_metadata
gst_device_monitor_factory_get_metadata_keys gst_device_monitor_factory_get_metadata_keys
gst_device_monitor_factory_get_type
gst_device_monitor_factory_has_classes gst_device_monitor_factory_has_classes
gst_device_monitor_factory_has_classesv gst_device_monitor_factory_has_classesv
gst_device_monitor_factory_list_get_device_monitors gst_device_monitor_factory_list_get_device_monitors
<SUBSECTION Standard>
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
</SECTION> </SECTION>
<SECTION> <SECTION>
...@@ -3397,22 +3410,25 @@ gst_device_monitor_factory_list_get_device_monitors ...@@ -3397,22 +3410,25 @@ gst_device_monitor_factory_list_get_device_monitors
<TITLE>GstGlobalDeviceMonitor</TITLE> <TITLE>GstGlobalDeviceMonitor</TITLE>
GstGlobalDeviceMonitor GstGlobalDeviceMonitor
GstGlobalDeviceMonitorClass GstGlobalDeviceMonitorClass
GST_GLOBAL_DEVICE_MONITOR
GST_GLOBAL_DEVICE_MONITOR_CAST
GST_GLOBAL_DEVICE_MONITOR_CLASS
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_bus
gst_global_device_monitor_get_caps_filter gst_global_device_monitor_get_caps_filter
gst_global_device_monitor_get_classes_filter gst_global_device_monitor_get_classes_filter
gst_global_device_monitor_get_devices gst_global_device_monitor_get_devices
gst_global_device_monitor_get_type
gst_global_device_monitor_new gst_global_device_monitor_new
gst_global_device_monitor_set_caps_filter gst_global_device_monitor_set_caps_filter
gst_global_device_monitor_set_classes_filter gst_global_device_monitor_set_classes_filter
gst_global_device_monitor_start gst_global_device_monitor_start
gst_global_device_monitor_stop gst_global_device_monitor_stop
<SUBSECTION Standard>
GstGlobalDeviceMonitorPrivate
GST_GLOBAL_DEVICE_MONITOR
GST_GLOBAL_DEVICE_MONITOR_CAST
GST_GLOBAL_DEVICE_MONITOR_CLASS
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_type
</SECTION> </SECTION>
...@@ -19,6 +19,21 @@ ...@@ -19,6 +19,21 @@
* Boston, MA 02111-1307, USA. * 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 #ifdef HAVE_CONFIG_H
#include "config.h" #include "config.h"
#endif #endif
...@@ -163,6 +178,9 @@ gst_device_set_property (GObject * object, guint prop_id, ...@@ -163,6 +178,9 @@ gst_device_set_property (GObject * object, guint prop_id,
* @name: (allow-none): name of new element, or %NULL to automatically * @name: (allow-none): name of new element, or %NULL to automatically
* create a unique name. * 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 * Returns: (transfer full): a new #GstElement configured to use this device
* *
* Since: 1.4 * Since: 1.4
......
...@@ -42,6 +42,14 @@ typedef struct _GstDevicePrivate GstDevicePrivate; ...@@ -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_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_DEVICE, GstDeviceClass))
#define GST_DEVICE_CAST(obj) ((GstDevice *)(obj)) #define GST_DEVICE_CAST(obj) ((GstDevice *)(obj))
/**
* GstDevice:
* @parent: The parent #GstObject strucuture.
*
* A device object.
*
* Since: 1.4
*/
struct _GstDevice { struct _GstDevice {
GstObject parent; GstObject parent;
...@@ -52,6 +60,20 @@ struct _GstDevice { ...@@ -52,6 +60,20 @@ struct _GstDevice {
gpointer _gst_reserved[GST_PADDING]; 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 { struct _GstDeviceClass {
GstObjectClass parent_class; GstObjectClass parent_class;
......
...@@ -19,6 +19,24 @@ ...@@ -19,6 +19,24 @@
* Boston, MA 02111-1307, USA. * 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 #ifdef HAVE_CONFIG_H
#include "config.h" #include "config.h"
#endif #endif
......
...@@ -44,17 +44,21 @@ typedef struct _GstDeviceMonitorPrivate GstDeviceMonitorPrivate; ...@@ -44,17 +44,21 @@ typedef struct _GstDeviceMonitorPrivate GstDeviceMonitorPrivate;
/** /**
* GstDeviceMonitor: * GstDeviceMonitor:
* @parent: The parent #GstObject
* @devices: a #GList of the #GstDevice objects
*
* The structure of the base #GstDeviceMonitor
* *
* Since: 1.4 * Since: 1.4
*/ */
struct _GstDeviceMonitor { struct _GstDeviceMonitor {
GstObject parent; GstObject parent;
/*< private >*/
/* Protected by the Object lock */ /* Protected by the Object lock */
GList *devices; GList *devices;
/*< private >*/
GstDeviceMonitorPrivate *priv; GstDeviceMonitorPrivate *priv;
gpointer _gst_reserved[GST_PADDING]; gpointer _gst_reserved[GST_PADDING];
...@@ -62,12 +66,15 @@ struct _GstDeviceMonitor { ...@@ -62,12 +66,15 @@ struct _GstDeviceMonitor {
/** /**
* GstDeviceMonitorClass: * GstDeviceMonitorClass:
* @parent_class: the parent #GstObjectClass structure
* @factory: a pointer to the #GstDeviceMonitorFactory that creates this * @factory: a pointer to the #GstDeviceMonitorFactory that creates this
* monitor * monitor
* @probe: Returns a list of devices that are currently available. * @probe: Returns a list of devices that are currently available.
* This should never block. * This should never block.
* @start: Starts monitoring for new devices. * @start: Starts monitoring for new devices. Only subclasses that can know
* @stop: Stops monitoring for new devices * 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 * The structure of the base #GstDeviceMonitorClass
* *
......
...@@ -33,6 +33,14 @@ ...@@ -33,6 +33,14 @@
* *
* Since: 1.4 * Since: 1.4
*/ */
/**
* GstDeviceMonitorFactoryClass:
*
* The opaque #GstDeviceMonitorFactoryClass data structure.
*
* Since: 1.4
*/
typedef struct _GstDeviceMonitorFactory GstDeviceMonitorFactory; typedef struct _GstDeviceMonitorFactory GstDeviceMonitorFactory;
typedef struct _GstDeviceMonitorFactoryClass GstDeviceMonitorFactoryClass; typedef struct _GstDeviceMonitorFactoryClass GstDeviceMonitorFactoryClass;
......
...@@ -18,7 +18,23 @@ ...@@ -18,7 +18,23 @@
* Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA. * 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 #ifdef HAVE_CONFIG_H
#include "config.h" #include "config.h"
#endif #endif
...@@ -230,8 +246,8 @@ again: ...@@ -230,8 +246,8 @@ again:
* @monitor: A #GstGlobalDeviceMonitor * @monitor: A #GstGlobalDeviceMonitor
* *
* Starts monitoring the devices, one this has succeeded, the * Starts monitoring the devices, one this has succeeded, the
* #GstGlobalDeviceMonitor:added and #GstGlobalDeviceMonitor:removed * %GST_MESSAGE_DEVICE_ADDED and %GST_MESSAGE_DEVICE_REMOVED messages
* signals will be emitted when the list of devices changes. * will be emitted on the bus when the list of devices changes.
* *
* Returns: %TRUE if the device monitoring could be started * Returns: %TRUE if the device monitoring could be started
* *
...@@ -301,7 +317,7 @@ gst_global_device_monitor_stop (GstGlobalDeviceMonitor * monitor) ...@@ -301,7 +317,7 @@ gst_global_device_monitor_stop (GstGlobalDeviceMonitor * monitor)
/** /**
* gst_global_device_monitor_set_classes_filter: * gst_global_device_monitor_set_classes_filter:
* @self: the global device monitor * @monitor: the global device monitor
* @classes: device classes to use as filter * @classes: device classes to use as filter
* *
* Filter devices monitored by device class, e.g. in case you are only * 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, ...@@ -431,6 +447,8 @@ gst_global_device_monitor_set_caps_filter (GstGlobalDeviceMonitor * monitor,
* gst_global_device_monitor_get_caps_filter: * gst_global_device_monitor_get_caps_filter:
* @monitor: a global device monitor * @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) * Returns: (transfer full): the filter caps that are active (or ANY caps)
* *
* Since: 1.4 * Since: 1.4
...@@ -452,6 +470,8 @@ gst_global_device_monitor_get_caps_filter (GstGlobalDeviceMonitor * monitor) ...@@ -452,6 +470,8 @@ gst_global_device_monitor_get_caps_filter (GstGlobalDeviceMonitor * monitor)
/** /**
* gst_global_device_monitor_new: * gst_global_device_monitor_new:
* *
* Create a new #GstGlobalDeviceMonitor
*
* Returns: (transfer full): a new global device monitor. * Returns: (transfer full): a new global device monitor.
* *
* Since: 1.4 * Since: 1.4
......
...@@ -44,6 +44,7 @@ typedef struct _GstGlobalDeviceMonitorClass GstGlobalDeviceMonitorClass; ...@@ -44,6 +44,7 @@ typedef struct _GstGlobalDeviceMonitorClass GstGlobalDeviceMonitorClass;
/** /**
* GstGlobalDeviceMonitor: * GstGlobalDeviceMonitor:
* @parent: the parent #GstObject structure
* *
* Opaque global device monitor object structure. * Opaque global device monitor object structure.
* *
...@@ -61,6 +62,7 @@ struct _GstGlobalDeviceMonitor { ...@@ -61,6 +62,7 @@ struct _GstGlobalDeviceMonitor {
/** /**
* GstGlobalDeviceMonitorClass: * GstGlobalDeviceMonitorClass:
* @parent_class: the parent #GstObjectClass structure
* *
* Opaque global device monitor class structure. * Opaque global device monitor class structure.
* *
......
...@@ -2361,6 +2361,7 @@ gst_message_new_device_added (GstObject * src, GstDevice * device) ...@@ -2361,6 +2361,7 @@ gst_message_new_device_added (GstObject * src, GstDevice * device)
/** /**
* gst_message_parse_device_added: * 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 * @device: (out) (allow-none) (transfer none): A location where to store a
* pointer to the new #GstDevice, or %NULL * pointer to the new #GstDevice, or %NULL
* *
...@@ -2412,6 +2413,7 @@ gst_message_new_device_removed (GstObject * src, GstDevice * device) ...@@ -2412,6 +2413,7 @@ gst_message_new_device_removed (GstObject * src, GstDevice * device)
/** /**
* gst_message_parse_device_removed: * 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 * @device: (out) (allow-none) (transfer none): A location where to store a
* pointer to the removed #GstDevice, or %NULL * pointer to the removed #GstDevice, or %NULL
* *
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment