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
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
<SUBSECTION Standard>
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
<SUBSECTION Standard>
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
</SECTION>
<SECTION>
......@@ -3347,13 +3352,6 @@ gst_device_reconfigure_element
<TITLE>GstDeviceMonitor</TITLE>
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
<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>
......@@ -3376,20 +3384,25 @@ gst_device_monitor_stop
<TITLE>GstDeviceMonitorFactory</TITLE>
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
<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>
......@@ -3397,22 +3410,25 @@ gst_device_monitor_factory_list_get_device_monitors
<TITLE>GstGlobalDeviceMonitor</TITLE>
GstGlobalDeviceMonitor
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_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
<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>
......@@ -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
......
......@@ -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;
......
......@@ -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
......
......@@ -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
*
......
......@@ -33,6 +33,14 @@
*
* Since: 1.4
*/
/**
* GstDeviceMonitorFactoryClass:
*
* The opaque #GstDeviceMonitorFactoryClass data structure.
*
* Since: 1.4
*/
typedef struct _GstDeviceMonitorFactory GstDeviceMonitorFactory;
typedef struct _GstDeviceMonitorFactoryClass GstDeviceMonitorFactoryClass;
......
......@@ -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
......
......@@ -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.
*
......
......@@ -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
*
......
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