From 26c9fb0d1063a7c12c07707de96c3bc48de79d5b Mon Sep 17 00:00:00 2001 From: "Ronald S. Bultje" Date: Wed, 28 Jan 2004 14:16:59 +0000 Subject: [PATCH] docs/pwg/advanced_interfaces.xml: Add documentation on propertyprobing. Original commit message from CVS: 2004-01-28 Ronald Bultje * docs/pwg/advanced_interfaces.xml: Add documentation on propertyprobing. * docs/pwg/advanced_events.xml: * docs/pwg/advanced_tagging.xml: * docs/pwg/building_boiler.xml: * docs/pwg/building_filterfactory.xml: * docs/pwg/pwg.xml: Move filterfactory and tagging into their own chapter, add a chapter on events. all these are empty placeholders that will be filled in some day. --- ChangeLog | 13 +++ docs/pwg/advanced-events.xml | 6 ++ docs/pwg/advanced-interfaces.xml | 175 ++++++++++++++++++++++++++++++++++-- docs/pwg/advanced-tagging.xml | 6 ++ docs/pwg/building-boiler.xml | 28 ------ docs/pwg/building-filterfactory.xml | 24 +++++ docs/pwg/pwg.xml | 6 ++ 7 files changed, 222 insertions(+), 36 deletions(-) create mode 100644 docs/pwg/advanced-events.xml create mode 100644 docs/pwg/advanced-tagging.xml create mode 100644 docs/pwg/building-filterfactory.xml diff --git a/ChangeLog b/ChangeLog index cb3b68a..e2fc021 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,19 @@ 2004-01-28 Ronald Bultje * docs/pwg/advanced_interfaces.xml: + Add documentation on propertyprobing. + * docs/pwg/advanced_events.xml: + * docs/pwg/advanced_tagging.xml: + * docs/pwg/building_boiler.xml: + * docs/pwg/building_filterfactory.xml: + * docs/pwg/pwg.xml: + Move filterfactory and tagging into their own chapter, add a chapter + on events. all these are empty placeholders that will be filled in + some day. + +2004-01-28 Ronald Bultje + + * docs/pwg/advanced_interfaces.xml: Docs for mixer interface. Also a check for website uploading. 2004-01-28 Thomas Vander Stichele diff --git a/docs/pwg/advanced-events.xml b/docs/pwg/advanced-events.xml new file mode 100644 index 0000000..cd0dfbb --- /dev/null +++ b/docs/pwg/advanced-events.xml @@ -0,0 +1,6 @@ + + Events: Seeking, Navigation and More + + WRITEME + + diff --git a/docs/pwg/advanced-interfaces.xml b/docs/pwg/advanced-interfaces.xml index df5c0ea..5801545 100644 --- a/docs/pwg/advanced-interfaces.xml +++ b/docs/pwg/advanced-interfaces.xml @@ -39,6 +39,13 @@ allows us to query for interface availability based on runtime properties. This extension is called GstImplementsInterface. + + One important note: interfaces do not replace + properties. Rather, interfaces should be built next to + properties. There are two important reasons for this. Firstly, properties + can be saved in XML files. Secondly, properties can be specified on the + commandline (gst-launch). + How to Implement Interfaces @@ -137,6 +144,8 @@ gst_my_filter_some_interface_init (GstSomeInterface *iface) to the implementation here. +#include <gst/mixer/mixer.h> + typedef struct _GstMyFilter { [..] gint volume; @@ -277,7 +286,164 @@ gst_my_filter_mixer_interface_init (GstMixerClass *iface) Property Probe Interface - WRITEME + Property probing is a generic solution to the problem that properties' + value lists in an enumeration are static. We've shown enumerations in + . Property probing tries to accomplish + a goal similar to enumeration lists: to have a limited, explicit list of + allowed values for a property. There are two differences between + enumeration lists and probing. Firstly, enumerations only allow strings + as values; property probing works for any value type. Secondly, the + contents of a probed list of allowed values may change during the life + of an element. The contents of a enumeraiton list are static. Crrently, + property probing is being used for detection of devices (e.g. for OSS + elements, Video4linux elements, etc.). It could - in theory - be used + for any property, though. + + + Property probing stores the list of allowed (or recommended) values in a + GValueArray and returns that to the user. + NULL is a valid return value, too. The process of + property probing is separated over two virtual functions: one for probing + the property to create a GValueArray, and one to + retrieve the current GValueArray. Those two are + separated because probing might take a long time (several seconds). Also, + this simpliies interface implementation in elements. For the application, + there are functions that wrap those two. For more information on this, + have a look at the API reference for the + GstPropertyProbe interface. + + + Below is a example of property probing for the audio filter element; it + will probe for allowed values for the silent property. + Indeed, this value is a gboolean so it doesn't + make much sense. Then again, it's only an example. + + +#include <gst/propertyprobe/propertyprobe.h> + +static void gst_my_filter_probe_interface_init (GstPropertyProbeInterface *iface); + +GType +gst_my_filter_get_type (void) +{ +[..] + static const GInterfaceInfo probe_interface_info = { + (GInterfaceInitFunc) gst_my_filter_probe_interface_init, + NULL, + NULL + }; +[..] + g_type_add_interface_static (my_filter_type, + GST_TYPE_PROPERTY_PROBE, + &probe_interface_info); +[..] +} + +static const GList * +gst_my_filter_probe_get_properties (GstPropertyProbe *probe) +{ + GObjectClass *klass = G_OBJECT_GET_CLASS (probe); + static GList *props = NULL; + + if (!props) { + GParamSpec *pspec; + + pspec = g_object_class_find_property (klass, "silent"); + props = g_list_append (props, pspec); + } + + return props; +} + +static gboolean +gst_my_filter_probe_needs_probe (GstPropertyProbe *probe, + guint prop_id, + const GParamSpec *pspec) +{ + gboolean res = FALSE; + + switch (prop_id) { + case ARG_SILENT: + res = FALSE; + break; + default: + G_OBJECT_WARN_INVALID_PROPERTY_ID (probe, prop_id, pspec); + break; + } + + return res; +} + +static void +gst_my_filter_probe_probe_property (GstPropertyProbe *probe, + guint prop_id, + const GParamSpec *pspec) +{ + switch (prop_id) { + case ARG_SILENT: + /* don't need to do much here... */ + break; + default: + G_OBJECT_WARN_INVALID_PROPERTY_ID (probe, prop_id, pspec); + break; + } +} + +static GValueArray * +gst_my_filter_get_silent_values (GstMyFilter *filter) +{ + GValueArray *array = g_value_array_new (2); + GValue value = { 0 }; + + g_value_init (&value, G_TYPE_BOOLEAN); + + /* add TRUE */ + g_value_set_boolean (&value, TRUE); + g_value_array_append (array, &value); + + /* add FALSE */ + g_value_set_boolean (&value, FALSE); + g_value_array_append (array, &value); + + g_value_unset (&value); + + return array; +} + +static GValueArray * +gst_my_filter_probe_get_values (GstPropertyProbe *probe, + guint prop_id, + const GParamSpec *pspec) +{ + GstMyFilter *filter = GST_MY_FILTER (probe); + GValueArray *array = NULL; + + switch (prop_id) { + case ARG_SILENT: + array = gst_my_filter_get_silent_values (filter); + break; + default: + G_OBJECT_WARN_INVALID_PROPERTY_ID (probe, prop_id, pspec); + break; + } + + return array; +} + +static void +gst_my_filter_probe_interface_init (GstPropertyProbeInterface *iface) +{ + iface->get_properties = gst_my_filter_probe_get_properties; + iface->needs_probe = gst_my_filter_probe_needs_probe; + iface->probe_property = gst_my_filter_probe_probe_property; + iface->get_values = gst_my_filter_probe_get_values; +} + + + You don't need to support any functions for getting or setting values. + All that is handled via the standard GObject + _set_property () and _get_property () + functions. @@ -301,11 +467,4 @@ gst_my_filter_mixer_interface_init (GstMixerClass *iface) WRITEME - - - Tagging Interface - - WRITEME - - diff --git a/docs/pwg/advanced-tagging.xml b/docs/pwg/advanced-tagging.xml new file mode 100644 index 0000000..4b239f9 --- /dev/null +++ b/docs/pwg/advanced-tagging.xml @@ -0,0 +1,6 @@ + + Tagging (Metadata and Streaminfo) + + WRITEME + + diff --git a/docs/pwg/building-boiler.xml b/docs/pwg/building-boiler.xml index 5248045..5392df4 100644 --- a/docs/pwg/building-boiler.xml +++ b/docs/pwg/building-boiler.xml @@ -167,34 +167,6 @@ U gst-template/gst-app/src/Makefile.am - - Creating a Filter With FilterFactory (Future) - - A plan for the future is to create a FilterFactory, to make the process of - making a new filter a simple process of specifying a few details, and - writing a small amount of code to perform the actual data processing. - Ideally, a FilterFactory would perform the tasks of boilerplate creation, - code functionality implementation, and filter registration. - - - Unfortunately, this has not yet been implemented. Even when someone - eventually does write a FilterFactory, this element will not be able to - cover all the possibilities available for filter writing. Thus, some - plugins will always need to be manually coded and registered. - - - Here is a rough outline of what is planned: You run the FilterFactory and - give the factory a list of appropriate function pointers and data - structures to define a filter. With a reasonable measure of preprocessor - magic, you just need to provide a name for the filter and definitions of - the functions and data structures desired. Then you call a macro from - within plugin_init() that registers the new filter. All the fluff that - goes into the definition of a filter is thus be hidden from view. - - - - - GstElementDetails diff --git a/docs/pwg/building-filterfactory.xml b/docs/pwg/building-filterfactory.xml new file mode 100644 index 0000000..4d2e4e8 --- /dev/null +++ b/docs/pwg/building-filterfactory.xml @@ -0,0 +1,24 @@ + + Creating a Filter with a Filter Factory + + A plan for the future is to create a FilterFactory, to make the process of making a new filter a simple process of specifying a few details, and + writing a small amount of code to perform the actual data processing. + Ideally, a FilterFactory would perform the tasks of boilerplate creation, + code functionality implementation, and filter registration. + + + Unfortunately, this has not yet been implemented. Even when someone + eventually does write a FilterFactory, this element will not be able to + cover all the possibilities available for filter writing. Thus, some + plugins will always need to be manually coded and registered. + + + Here is a rough outline of what is planned: You run the FilterFactory and + give the factory a list of appropriate function pointers and data + structures to define a filter. With a reasonable measure of preprocessor + magic, you just need to provide a name for the filter and definitions of + the functions and data structures desired. Then you call a macro from + within plugin_init() that registers the new filter. All the fluff that + goes into the definition of a filter is thus be hidden from view. + + diff --git a/docs/pwg/pwg.xml b/docs/pwg/pwg.xml index d4b23cd..8ff9e08 100644 --- a/docs/pwg/pwg.xml +++ b/docs/pwg/pwg.xml @@ -17,6 +17,7 @@ + @@ -25,6 +26,8 @@ + + @@ -108,6 +111,7 @@ &BUILDING_PROPS; &BUILDING_SIGNALS; &BUILDING_TESTAPP; + &BUILDING_FILTERFACT; @@ -126,6 +130,8 @@ &ADVANCED_DPARAMS; &ADVANCED_MIDI; &ADVANCED_INTERFACES; + &ADVANCED_TAGGING; + &ADVANCED_EVENTS; -- 2.7.4