From 93ea284fe4d231fb665911c89bda9a25e9a183e0 Mon Sep 17 00:00:00 2001 From: "Ronald S. Bultje" Date: Tue, 27 Jan 2004 14:58:21 +0000 Subject: [PATCH] docs/pwg/: Add as a placeholder for future filling-in. Original commit message from CVS: 2004-01-27 Ronald Bultje * docs/pwg/advanced_interfaces.xml: * docs/pwg/pwg.xml: Add as a placeholder for future filling-in. * docs/pwg/basics_autoplugging.xml: * docs/pwg/basics_buffers.xml: * docs/pwg/basics_elements.xml: * docs/pwg/basics_events.xml: * docs/pwg/basics_plugins.xml: * docs/pwg/basics_types.xml: Remove, because unused (this is all in intro_basics.xml). * docs/pwg/building_signals.xml: Short intro to signals + reference to GObject docs - we really shouldn't go into these sort of things to deply because we don't use them that extensively anyway. * docs/pwg/building_state.xml: Explanation of states. Benjamin, please check. * docs/pwg/building_testapp.xml: Put everything in one page - putting only a few lines of content per page doesn't really make sense. Time to get into the advanced topics. ;). --- ChangeLog | 24 +++++++++++ docs/pwg/advanced-interfaces.xml | 6 +++ docs/pwg/basics-autoplugging.xml | 18 -------- docs/pwg/basics-buffers.xml | 32 --------------- docs/pwg/basics-elements.xml | 39 ------------------ docs/pwg/basics-events.xml | 8 ---- docs/pwg/basics-plugins.xml | 30 -------------- docs/pwg/basics-types.xml | 15 ------- docs/pwg/building-signals.xml | 7 +++- docs/pwg/building-state.xml | 88 ++++++++++++++++++++++++++++++++++++++++ docs/pwg/building-testapp.xml | 18 -------- docs/pwg/pwg.xml | 2 + 12 files changed, 126 insertions(+), 161 deletions(-) create mode 100644 docs/pwg/advanced-interfaces.xml delete mode 100644 docs/pwg/basics-autoplugging.xml delete mode 100644 docs/pwg/basics-buffers.xml delete mode 100644 docs/pwg/basics-elements.xml delete mode 100644 docs/pwg/basics-events.xml delete mode 100644 docs/pwg/basics-plugins.xml delete mode 100644 docs/pwg/basics-types.xml diff --git a/ChangeLog b/ChangeLog index 45edb20..3528a65 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,29 @@ 2004-01-27 Ronald Bultje + * docs/pwg/advanced_interfaces.xml: + * docs/pwg/pwg.xml: + Add as a placeholder for future filling-in. + * docs/pwg/basics_autoplugging.xml: + * docs/pwg/basics_buffers.xml: + * docs/pwg/basics_elements.xml: + * docs/pwg/basics_events.xml: + * docs/pwg/basics_plugins.xml: + * docs/pwg/basics_types.xml: + Remove, because unused (this is all in intro_basics.xml). + * docs/pwg/building_signals.xml: + Short intro to signals + reference to GObject docs - we really + shouldn't go into these sort of things to deply because we don't + use them that extensively anyway. + * docs/pwg/building_state.xml: + Explanation of states. Benjamin, please check. + * docs/pwg/building_testapp.xml: + Put everything in one page - putting only a few lines of content + per page doesn't really make sense. + + Time to get into the advanced topics. ;). + +2004-01-27 Ronald Bultje + * docs/pwg/advanced_types.xml: Finish documenting the current state of mimetypes. * docs/pwg/building_boiler.xml: diff --git a/docs/pwg/advanced-interfaces.xml b/docs/pwg/advanced-interfaces.xml new file mode 100644 index 0000000..7643740 --- /dev/null +++ b/docs/pwg/advanced-interfaces.xml @@ -0,0 +1,6 @@ + + Interfaces + + WRITEME + + diff --git a/docs/pwg/basics-autoplugging.xml b/docs/pwg/basics-autoplugging.xml deleted file mode 100644 index f6a927d..0000000 --- a/docs/pwg/basics-autoplugging.xml +++ /dev/null @@ -1,18 +0,0 @@ - - - - - Autopluggers - - &GStreamer; has an autoplugging mechanism, which enables application writers - to simply specify start and end elements for a path, and the system will - then create a path which links these elements, in accordance with the type - information provided by the elements. - - - It is possible to devise many different schemes for generating such - pathways, perhaps to optimise based on special criteria, or with some - specific constraints. It is thus possible to define new autoplugging - systems, using the plugin system. - - diff --git a/docs/pwg/basics-buffers.xml b/docs/pwg/basics-buffers.xml deleted file mode 100644 index 28267d4..0000000 --- a/docs/pwg/basics-buffers.xml +++ /dev/null @@ -1,32 +0,0 @@ - - - - - Buffers - - Buffers are structures used to pass data between elements. All streams of - data are chopped up into chunks which are stored in buffers. Buffers can be - of any size, and also contain metadata indicating the type of data contained - in them. Buffers can be allocated by various different schemes, and may - either be passed on by elements or unreferenced (and the memory used by the - buffer freed). - - - - Anatomy of a buffer - - - - - - Refcounts and mutability - - - - - - Metadata - - - - diff --git a/docs/pwg/basics-elements.xml b/docs/pwg/basics-elements.xml deleted file mode 100644 index df33648..0000000 --- a/docs/pwg/basics-elements.xml +++ /dev/null @@ -1,39 +0,0 @@ - - - - - Elements, Plugins, and Filters - - In the &GStreamer; framework, a plugin is a specific - sort of code module that gets loaded when a program requests the - functionality that the plugin provides. A plugin is essentially a shared - code library. -Filters are an - important subset of plugins that process data, as opposed to producing or - consuming data. (Producers and consumers of data are called - source and sink plugins, - respectively.) - - - Elements are at the core of &GStreamer;. Without elements, &GStreamer; is - just a bunch of pipe fittings with nothing to link. A large number of - elements (filters, sources, and sinks) ship with &GStreamer;, but extra - elements can also be written. The purpose of this guide is to help you - learn to create new elements. - - - An element may be constructed in several different ways, but all must - conform to the same basic rules. This guide presents one basic way to build - a filter elementA simple filter may be built with the - FilterFactory, where the only code that need be written is the actual filter - code. A more complex filter, or a source or sink, will need to be written - out fully for complete access to the features and performance possible with - &GStreamer;. - - - The implementation of a new element will be contained in a plugin: a single - plugin may contain the implementation of several elements, or just a single - one. - - - diff --git a/docs/pwg/basics-events.xml b/docs/pwg/basics-events.xml deleted file mode 100644 index ac84310..0000000 --- a/docs/pwg/basics-events.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - - Events - - - diff --git a/docs/pwg/basics-plugins.xml b/docs/pwg/basics-plugins.xml deleted file mode 100644 index 051f99b..0000000 --- a/docs/pwg/basics-plugins.xml +++ /dev/null @@ -1,30 +0,0 @@ - - - - - Plugins - - Extensions to &GStreamer; can be made using a plugin mechanism. This is used - extensively in &GStreamer; even if only the standard package is being used: - a few very basic functions reside in the core library, and all others are - implemented in plugins. - - - Plugins are only loaded when needed: a plugin registry is used to store the - details of the plugins so that it is not neccessary to load all plugins to - determine which are needed. This registry needs to be updated whenever a new - plugin is added to the system: see the gst-register - utility and the documentation in the &GstAppDevMan; for more details. - - - User extensions to &GStreamer; can be installed in the main plugin - directory, and will immediately be available for use in applications. - gst-register should be run to update the repository: - but the system should work correctly even if it hasn't been - it will just - take longer to load the correct plugin. - - - User specific plugin directories and registries will be available in future - versions of &GStreamer;. - - diff --git a/docs/pwg/basics-types.xml b/docs/pwg/basics-types.xml deleted file mode 100644 index e28ec40..0000000 --- a/docs/pwg/basics-types.xml +++ /dev/null @@ -1,15 +0,0 @@ - - - - - Typing and Properties - - A type system is used to ensure that the data passed between elements is in - a recognised format, and that the various parameters required to fully - specify that format match up correctly. Each link that is made between - elements has a specified type. This is related, but different, to the - metadata in buffers which describes the type of data in that particular - buffer. See the next chapter of this document for details of the available - types. - - diff --git a/docs/pwg/building-signals.xml b/docs/pwg/building-signals.xml index 8299104..81b6c23 100644 --- a/docs/pwg/building-signals.xml +++ b/docs/pwg/building-signals.xml @@ -4,6 +4,11 @@ Signals - Define signals in enum. + Signals can be used to notify applications of events specific to this + object. Note, however, that the application needs to be aware of signals + and their meaning, so if you're looking for a generic way for application- + element interaction, signals are probably not what you're looking for. In + many cases, however, signals can be very useful. See the GObject + documentation for all internals about signals. diff --git a/docs/pwg/building-state.xml b/docs/pwg/building-state.xml index 4d8a1e1..1d1e71e 100644 --- a/docs/pwg/building-state.xml +++ b/docs/pwg/building-state.xml @@ -3,6 +3,55 @@ What are states? + A state describes whether the element instance is initialized, whether it + is ready to transfer data and whether it is currently handling data. There + are four states defined in &GStreamer;: GST_STATE_NULL, + GST_STATE_READY, GST_STATE_PAUSED + and GST_STATE_PLAYING. + + + GST_STATE_NULL (from now on referred to as + NULL) is the default state of an element. In this state, it + has not allocated any runtime resources, it has not loaded any runtime + libraries and it can obviously not handle data. + + + GST_STATE_READY (from now on referred to as + READY) is the next state that an element can be in. In the + READY state, an element has all default resources (runtime-libraries, + runtime-memory) allocated. However, it has not yet allocated or defined + anything that is stream-specific. When going from NULL to READY state + (GST_STATE_NULL_TO_READY), an element should + allocate any non-stream-specific resources and should load runtime-loadable + libraries (if any). When going the other way around (from READY to NULL, + GST_STATE_READY_TO_NULL), an element should unload + these libraries and free all allocated resources. Examples of such + resources are hardware devices. Note that files are generally streams, + and these should thus be considered as stream-specific resources; therefore, + they should not be allocated in this state. + + + GST_STATE_PAUSED (from now on referred to as + PAUSED) is a state in which an element is by all means able + to handle data; the only 'but' here is that it doesn't actually handle + any data. When going from the READY state into the PAUSED state + (GST_STATE_READY_TO_PAUSED), the element will + usually not do anything at all: all stream-specific info is generally + handled in the _link (), which is called during caps + negotiation. Exceptions to this rule are, for example, files: these are + considered stream-specific data (since one file is one stream), and should + thus be opened in this state change. When going from the PAUSED back to + READY (GST_STATE_PAUSED_TO_READY), all + stream-specific data should be discarded. + + + GST_STATE_PLAYING (from now on referred to as + PLAYING) is the highest state that an element can be in. It + is similar to PAUSED, except that now, data is actually passing over the + pipeline. The transition from PAUSED to PLAYING + (GST_STATE_PAUSED_TO_PLAYING) should be as small + as possible and would ideally cause no delay at all. The same goes for the + reverse transition (GST_STATE_PLAYING_TO_PAUSED). @@ -10,5 +59,44 @@ Mangaging filter state + An element can be notified of state changes through a virtual function + pointer. Inside this function, the element can initialize any sort of + specific data needed by the element, and it can optionally fail to + go from one state to another. + +static GstElementStateReturn + gst_my_filter_change_state (GstElement *element); + +static void +gst_my_filter_class_init (GstMyFilterClass *klass) +{ + GstElementClass *element_class = GST_ELEMENT_CLASS (klass); + + element_class->change_state = gst_my_filter_change_state; +} + +static GstElementStateReturn +gst_my_filter_change_state (GstElement *element) +{ + GstMyFilter *filter = GST_MY_FILTER (element); + + switch (GST_STATE_TRANSITION (element)) { + case GST_STATE_NULL_TO_READY: + if (!gst_my_filter_allocate_memory (filter)) + return GST_STATE_FAILURE; + break; + case GST_STATE_READY_TO_NULL: + gst_my_filter_free_memory (filter); + break; + default: + break; + } + + if (GST_ELEMENT_CLASS (parent_class)->change_state) + return GST_ELEMENT_CLASS (parent_class)->change_state (element); + + return GST_STATE_SUCCESS; +} + diff --git a/docs/pwg/building-testapp.xml b/docs/pwg/building-testapp.xml index 29fdc32..8f7a4ba 100644 --- a/docs/pwg/building-testapp.xml +++ b/docs/pwg/building-testapp.xml @@ -14,8 +14,6 @@ Manual. - - Initialization At the start, you need to initialize the &GStreamer; core library by calling gst_init (). You can alternatively call @@ -23,10 +21,7 @@ a pointer to popt tables. You can then use libpopt to handle the given argument table, and this will finish the &GStreamer; intialization. - - - Instantiating the plugins You can create elements using gst_element_factory_make (), where the first argument is the element type that you want to create, @@ -43,20 +38,14 @@ (indeed, an eletric fence memory debugger wrapper element) to check for memory errors. - - - Linking the plugins During linking, your test application can use fixation or filtered caps as a way to drive a specific type of data to or from your element. This is a very simple and effective way of checking multiple types of input and output in your element. - - - Running the pipeline Running the pipeline happens through the gst_bin_iterate () function. Note that during running, you should connect to at least the @@ -65,10 +54,7 @@ you should add events into the pipeline and make sure your plugin handles these correctly (with respect to clocking, internal caching, etc.). - - - Cleaning up the memory Never forget to clean up memory in your plugin or your test application. When going to the NULL state, your element should clean up allocated @@ -76,10 +62,7 @@ possible support libraries. Your application should unref () the pipeline and make sure it doesn't crash. - - - Summary #include <gst/gst.h> @@ -117,5 +100,4 @@ main (gint arcg, return 0; } - diff --git a/docs/pwg/pwg.xml b/docs/pwg/pwg.xml index 6cf0f98..d4b23cd 100644 --- a/docs/pwg/pwg.xml +++ b/docs/pwg/pwg.xml @@ -24,6 +24,7 @@ + @@ -124,6 +125,7 @@ &ADVANCED_CLOCK; &ADVANCED_DPARAMS; &ADVANCED_MIDI; + &ADVANCED_INTERFACES; -- 2.7.4