From abe422b1414ded83af172e92810c72cc5ea55181 Mon Sep 17 00:00:00 2001 From: Thomas Vander Stichele Date: Mon, 29 Dec 2003 14:15:02 +0000 Subject: [PATCH] reorganizing manual so that concepts are explained before code is shown. Original commit message from CVS: reorganizing manual so that concepts are explained before code is shown. needs some proofreading, will get to it. --- docs/manual/basics-bins.xml | 199 -------------------- docs/manual/basics-elements.xml | 138 -------------- docs/manual/{init.xml => basics-init.xml} | 0 docs/manual/basics-pads.xml | 299 +---------------------------- docs/manual/basics-plugins.xml | 52 ------ docs/manual/bins-api.xml | 201 ++++++++++++++++++++ docs/manual/bins.xml | 199 -------------------- docs/manual/buffers-api.xml | 6 + docs/manual/elements-api.xml | 141 ++++++++++++++ docs/manual/elements.xml | 138 -------------- docs/manual/init-api.xml | 78 ++++++++ docs/manual/links-api.xml | 79 ++++++++ docs/manual/links.xml | 77 -------- docs/manual/manual.xml | 43 ++++- docs/manual/pads-api.xml | 301 ++++++++++++++++++++++++++++++ docs/manual/pads.xml | 299 +---------------------------- docs/manual/plugins-api.xml | 56 ++++++ docs/manual/plugins.xml | 52 ------ docs/manual/states-api.xml | 48 +++++ docs/manual/states.xml | 11 -- 20 files changed, 957 insertions(+), 1460 deletions(-) rename docs/manual/{init.xml => basics-init.xml} (100%) create mode 100644 docs/manual/bins-api.xml create mode 100644 docs/manual/buffers-api.xml create mode 100644 docs/manual/elements-api.xml create mode 100644 docs/manual/init-api.xml create mode 100644 docs/manual/links-api.xml create mode 100644 docs/manual/pads-api.xml create mode 100644 docs/manual/plugins-api.xml create mode 100644 docs/manual/states-api.xml diff --git a/docs/manual/basics-bins.xml b/docs/manual/basics-bins.xml index 54d018a..9372681 100644 --- a/docs/manual/basics-bins.xml +++ b/docs/manual/basics-bins.xml @@ -46,203 +46,4 @@ - - - Creating a bin - - Bins are created in the same way that other elements are created. ie. - using an element factory, or any of the associated convenience functions: - - - GstElement *bin, *thread, *pipeline; - - /* create a new bin called 'mybin'. this bin will be only for organizational purposes; a normal - GstBin doesn't affect plan generation */ - bin = gst_element_factory_make ("bin", "mybin"); - - /* create a new thread, and give it a unique name */ - thread = gst_element_factory_make ("thread", NULL); - - /* the core bins (GstBin, GstThread, GstPipeline) also have convenience APIs, - gst_<bintype>_new (). these are equivalent to the gst_element_factory_make () syntax. */ - pipeline = gst_pipeline_new ("pipeline_name"); - - - - - Adding elements to a bin - - Elements are added to a bin with the following code sample: - - - GstElement *element; - GstElement *bin; - - bin = gst_bin_new ("mybin"); - - element = gst_element_factory_make ("mpg123", "decoder"); - gst_bin_add (GST_BIN (bin), element); - ... - - - Bins and threads can be added to other bins too. This allows you to create nested bins. Pipelines shouldn't be added to any other element, though. - They are toplevel bins and they are directly linked to the scheduler. - - - To get an element from the bin you can use: - - - GstElement *element; - - element = gst_bin_get_by_name (GST_BIN (bin), "decoder"); - ... - - - You can see that the name of the element becomes very handy - for retrieving the element from a bin by using the element's - name. gst_bin_get_by_name () will recursively search nested bins. - - - To get a list of elements in a bin, use: - - - GList *elements; - - elements = gst_bin_get_list (GST_BIN (bin)); - - while (elements) { - GstElement *element = GST_ELEMENT (elements->data); - - g_print ("element in bin: %s\n", GST_OBJECT_NAME (GST_OBJECT (element))); - - elements = g_list_next (elements); - } - ... - - - To remove an element from a bin, use: - - - GstElement *element; - - gst_bin_remove (GST_BIN (bin), element); - ... - - - To add many elements to a bin at the same time, use the gst_bin_add_many - () function. Remember to pass NULL as the last argument. - - - GstElement *filesrc, *decoder, *audiosink; - GstBin *bin; - - /* instantiate the elements and the bins... */ - - gst_bin_add_many (bin, filesrc, decoder, audiosink, NULL); - - - - - Custom bins - - The application programmer can create custom bins packed with elements - to perform a specific task. This allows you to write an MPEG audio - decoder with just the following lines of code: - - - - /* create the mp3player element */ - GstElement *mp3player = gst_element_factory_make ("mp3player", "mp3player"); - /* set the source mp3 audio file */ - g_object_set (G_OBJECT (mp3player), "location", "helloworld.mp3", NULL); - /* start playback */ - gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PLAYING); - ... - /* pause playback */ - gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PAUSED); - ... - /* stop */ - gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_NULL); - - - Note that the above code assumes that the mp3player bin derives itself - from a GstThread, which begins to play as soon - as its state is set to PLAYING. Other bin types may need explicit - iteration. For more information, see . - - - Custom bins can be created with a plugin or an XML description. You - will find more information about creating custom bin in the Plugin - Writers Guide (FIXME ref). - - - - - Ghost pads - - You can see from how a bin has no pads of its own. - This is where "ghost pads" come into play. - -
- Visualisation of a <classname>GstBin</classname> element without ghost pads - - - - - -
- - A ghost pad is a pad from some element in the bin that has been promoted to the bin. - This way, the bin also has a pad. The bin becomes just another element with a pad and - you can then use the bin just like any other element. This is a very important feature - for creating custom bins. - - -
- Visualisation of a <classname>GstBin</classname> element with a ghost pad - - - - - -
- - - is a representation of a ghost pad. The sink pad of element one is now also a pad - of the bin. - - - Ghost pads can actually be added to all GstElements and not just - GstBins. Use the following code example to add a ghost pad to a bin: - - - GstElement *bin; - GstElement *element; - - element = gst_element_factory_create ("mad", "decoder"); - bin = gst_bin_new ("mybin"); - - gst_bin_add (GST_BIN (bin), element); - - gst_element_add_ghost_pad (bin, gst_element_get_pad (element, "sink"), "sink"); - - - - In the above example, the bin now also has a pad: the pad called 'sink' - of the given element. - - - We can now, for example, link the source pad of a filesrc element - to the bin with: - - - GstElement *filesrc; - - filesrc = gst_element_factory_create ("filesrc", "disk_reader"); - - gst_element_link_pads (filesrc, "src", bin, "sink"); - ... - - - diff --git a/docs/manual/basics-elements.xml b/docs/manual/basics-elements.xml index 9fc8a90..a712e8b 100644 --- a/docs/manual/basics-elements.xml +++ b/docs/manual/basics-elements.xml @@ -115,142 +115,4 @@ - - Creating a GstElement - - A GstElement object is created from - a factory. To create an element, you have to get access to a - GstElementFactory object using a unique - factory name. - - - The following code example is used to get a factory that can be used - to create the 'mad' element, an mp3 decoder. - - - GstElementFactory *factory; - - factory = gst_element_factory_find ("mad"); - - - Once you have the handle to the element factory, you can create a - real element with the following code fragment: - - - GstElement *element; - - element = gst_element_factory_create (factory, "decoder"); - - - gst_element_factory_create will use the element - factory to create an element with the given name. The name of the - element is something you can use later on to look up the element in - a bin, for example. You can pass NULL as the name - argument to get a unique, default name. - - - A simple shortcut exists for creating an element from a factory. The - following example creates an element named "decoder" from the element - factory named "mad". This convenience function is most widely used to - create an element. - - - GstElement *element; - - element = gst_element_factory_make ("mad", "decoder"); - - - When you don't need the element anymore, you need to unref it, as shown in the following - example. - - - GstElement *element; - - ... - gst_element_unref (element); - - - - GstElement properties - - A GstElement can have several properties - which are implemented using standard GObject - properties. The usual GObject methods to query, - set and get property values and GParamSpecs - are therefore supported. - - - Every GstElement inherits at least - one property of its parent GstObject: - the "name" property. This is the name you provide to the - functions gst_element_factory_make or - gst_element_factory_create. You can get and set - this property using the functions - gst_object_set_name - and gst_object_get_name or use the - GObject property mechanism as shown below. - - - GstElement *element; - GValue value = { 0, }; /* initialize the GValue for g_object_get() */ - - element = gst_element_factory_make ("mad", "decoder"); - g_object_set (G_OBJECT (element), "name", "mydecoder", NULL); - ... - - g_value_init (&value, G_TYPE_STRING); - g_object_get_property (G_OBJECT (element), "name", &value); - ... - - - Most plugins provide additional properties to provide more information - about their configuration or to configure the element. - gst-inspect is a useful tool to query the properties - of a particular element, it will also use property introspection to give - a short explanation about the function of the property and about the - parameter types and ranges it supports. - - - For more information about GObject - properties we recommend you read the GObject manual and an introduction to - The Glib Object system. - - - - - GstElement signals - - A GstElement also provides various - GObject signals that can be used as a flexible - callback mechanism. - - - - - More about GstElementFactory - - We talk some more about the GstElementFactory object. - - - - Getting information about an element using the factory details - - - - - - Finding out what pads an element can contain - - - - - - Different ways of querying the factories - - - - diff --git a/docs/manual/init.xml b/docs/manual/basics-init.xml similarity index 100% rename from docs/manual/init.xml rename to docs/manual/basics-init.xml diff --git a/docs/manual/basics-pads.xml b/docs/manual/basics-pads.xml index 391fe1b..47fd004 100644 --- a/docs/manual/basics-pads.xml +++ b/docs/manual/basics-pads.xml @@ -24,57 +24,6 @@ - - Getting pads from an element - - Once you have created an element, you can get one of its pads with: - - - GstPad *srcpad; - ... - srcpad = gst_element_get_pad (element, "src"); - ... - - - This function will get the pad named "src" from the given element. - - - Alternatively, you can request a GList of pads from the element. The - following code example will print the names of all the pads of an - element. - - - GList *pads; - ... - pads = gst_element_get_pad_list (element); - while (pads) { - GstPad *pad = GST_PAD (pads->data); - - g_print ("pad name %s\n", gst_pad_get_name (pad)); - - pads = g_list_next (pads); - } - ... - - - Useful pad functions - - You can get the name of a pad with gst_pad_get_name () and set its name with - get_pad_set_name(). - - - gst_pad_get_direction (GstPad *pad) can be used to query if the pad - is a sink or a source pad. Remember that a source pad is a pad that - can output data and a sink pad is one that accepts data. - - - You can get the parent of the pad, this is the element that this pad belongs to, - with get_pad_get_parent(GstPad *pad). This function will return a pointer to a - GstElement. - - - - Types of pads @@ -97,51 +46,6 @@ will see that this is very important when you are going to create dynamic pipelines later on in this manual. - - You can attach a signal to an element to inform you when the element has created - a new pad from one of its padtemplates. The following piece of code is an example - of how to do this: - - -static void -pad_link_func (GstElement *parser, GstPad *pad, GstElement *pipeline) -{ - g_print("***** a new pad %s was created\n", gst_pad_get_name(pad)); - - gst_element_set_state (pipeline, GST_STATE_PAUSED); - - if (strncmp (gst_pad_get_name (pad), "private_stream_1.0", 18) == 0) { - // set up an AC3 decoder pipeline - ... - // link pad to the AC3 decoder pipeline - ... - } - gst_element_set_state (GST_ELEMENT (audio_thread), GST_STATE_READY); -} - -int -main(int argc, char *argv[]) -{ - GstElement *pipeline; - GstElement *mpeg2parser; - - // create pipeline and do something useful - ... - - mpeg2parser = gst_element_factory_make ("mpegdemux", "mpegdemux"); - g_signal_connect (G_OBJECT (mpeg2parser), "new_pad", pad_link_func, pipeline); - ... - - // start the pipeline - gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING); - ... -} - - - - A pipeline cannot be changed in the PLAYING state. - - Request pads @@ -155,45 +59,6 @@ main(int argc, char *argv[]) output pads. Whenever an element wants to get an output pad from the tee element, it has to request the pad. - - The following piece of code can be used to get a pad from the tee element. After - the pad has been requested, it can be used to link another element to it. - - - ... - GstPad *pad; - ... - element = gst_element_factory_make ("tee", "element"); - - pad = gst_element_get_request_pad (element, "src%d"); - g_print ("new pad %s\n", gst_pad_get_name (pad)); - ... - - - The gst_element_get_request_pad method can be used to get a pad - from the element based on the name_template of the padtemplate. - - - It is also possible to request a pad that is compatible with another - pad template. This is very useful if you want to link an element - to a multiplexer element and you need to request a pad that is - compatible. The gst_element_get_compatible_pad is used to request - a compatible pad, as is shown in the next example. - - - ... - GstPadTemplate *templ; - GstPad *pad; - ... - element = gst_element_factory_make ("tee", "element"); - mad = gst_element_factory_make ("mad", "mad"); - - templ = gst_element_get_pad_template_by_name (mad, "sink"); - - pad = gst_element_get_compatible_pad (element, templ); - g_print ("new pad %s\n", gst_pad_get_name (pad)); - ... - @@ -212,7 +77,7 @@ main(int argc, char *argv[]) - What are capabilities ? + Capabilities Capabilities are attached to a pad in order to describe what type of media the pad can handle. @@ -225,29 +90,16 @@ main(int argc, char *argv[]) The basic entity is a capability, and is defined by a name, a MIME type and a set of properties. A capability can be chained to another capability, which is why we commonly refer to a chain of - capability entities as "capabilities". + capability entities as "capabilities". + It is important to understand that the term "capabilities" refers to a chain of one capability or more. This will be clearer when you see the structure definition of a GstCaps element. - - - - Its structure is: + + - -struct _GstCaps { - gchar *name; /* the name of this caps */ - guint16 id; /* type id (major type) */ - - guint refcount; /* caps are refcounted */ - - GstProps *properties; /* properties for this capability */ - - GstCaps *next; /* caps can be chained together */ -}; - Below is a dump of the capabilities of the element mad, as shown by gst-inspect. @@ -387,146 +239,5 @@ Pads: - - Getting the capabilities of a pad - - A pad can have a chain of capabilities attached to it. You can get the capabilities chain - with: - - - GstCaps *caps; - ... - caps = gst_pad_get_caps (pad); - - g_print ("pad name %s\n", gst_pad_get_name (pad)); - - while (caps) { - g_print (" Capability name %s, MIME type %s\n", - gst_caps_get_name (cap), - gst_caps_get_mime (cap)); - - caps = caps->next; - } - ... - - - - Creating capability structures - - While capabilities are mainly used inside a plugin to describe the - media type of the pads, the application programmer also has to have - basic understanding of capabilities in order to interface with the - plugins, specially when using the autopluggers. - - - As we said, a capability has a name, a mime-type and some - properties. The signature of the function to create a new - GstCaps structure is: - - -GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props); - - - - You can therefore create a new capability with no properties like this: - - GstCaps *newcaps; - - newcaps = gst_caps_new ("my_caps", "audio/wav", NULL); - - - - GstProps basically consist of a set of key-value pairs - and are created with a function with this signature: - -GstProps* gst_props_new (const gchar *firstname, ...); - - - - The keys are given as strings and the values are given with a set of macros: - - - - GST_PROPS_INT(a): An integer value - - - - - GST_PROPS_FLOAT(a): A floating point value - - - - - GST_PROPS_FOURCC(a): A fourcc value - - - - - GST_PROPS_BOOLEAN(a): A boolean value - - - - - GST_PROPS_STRING(a): A string value - - - - The values can also be specified as ranges with: - - - - GST_PROPS_INT_RANGE(a,b): An integer range from a to b - - - - - GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b - - - - All of the above values can be given with a list too, using: - - - - GST_PROPS_LIST(a,...): A list of property values. - - - - - - A more complex capability with properties is created like this: - - GstCaps *newcaps; - - newcaps = gst_caps_new ("my_caps", - "audio/wav", - gst_props_new ( - "bitrate", GST_PROPS_INT_RANGE (11025,22050), - "depth", GST_PROPS_INT (16), - "signed", GST_PROPS_LIST ( - GST_PROPS_BOOLEAN (TRUE), - GST_PROPS_BOOLEAN (FALSE) - ), - NULL - ); - - Optionally, the convenient shortcut macro can be used. The above complex - capability can be created with: - - GstCaps *newcaps; - - newcaps = GST_CAPS_NEW ("my_caps", - "audio/wav", - "bitrate", GST_PROPS_INT_RANGE (11025,22050), - "depth", GST_PROPS_INT (16), - "signed", GST_PROPS_LIST ( - GST_PROPS_BOOLEAN (TRUE), - GST_PROPS_BOOLEAN (FALSE) - ) - ); - - - - diff --git a/docs/manual/basics-plugins.xml b/docs/manual/basics-plugins.xml index 4acbfc6..c8e62ee 100644 --- a/docs/manual/basics-plugins.xml +++ b/docs/manual/basics-plugins.xml @@ -28,56 +28,4 @@ - - All plugins should implement one function, plugin_init, - that creates all the element factories and registers all the type - definitions contained in the plugin. - Without this function, a plugin cannot be registered. - - - The plugins are maintained in the plugin system. Optionally, the - type definitions and the element factories can be saved into an XML - representation so that the plugin system does not have to load all - available plugins in order to know their definition. - - - - The basic plugin structure has the following fields: - - -typedef struct _GstPlugin GstPlugin; - -struct _GstPlugin { - gchar *name; /* name of the plugin */ - gchar *longname; /* long name of plugin */ - gchar *filename; /* filename it came from */ - - GList *types; /* list of types provided */ - gint numtypes; - GList *elements; /* list of elements provided */ - gint numelements; - GList *autopluggers; /* list of autopluggers provided */ - gint numautopluggers; - - gboolean loaded; /* if the plugin is in memory */ -}; - - - - You can query a GList of available plugins with the - function gst_plugin_get_list as this example shows: - - - GList *plugins; - - plugins = gst_plugin_get_list (); - - while (plugins) { - GstPlugin *plugin = (GstPlugin *)plugins->data; - - g_print ("plugin: %s\n", gst_plugin_get_name (plugin)); - - plugins = g_list_next (plugins); - } - diff --git a/docs/manual/bins-api.xml b/docs/manual/bins-api.xml new file mode 100644 index 0000000..89c9f8a --- /dev/null +++ b/docs/manual/bins-api.xml @@ -0,0 +1,201 @@ + + Bins + + Creating a bin + + Bins are created in the same way that other elements are created. ie. + using an element factory, or any of the associated convenience functions: + + + GstElement *bin, *thread, *pipeline; + + /* create a new bin called 'mybin'. this bin will be only for organizational purposes; a normal + GstBin doesn't affect plan generation */ + bin = gst_element_factory_make ("bin", "mybin"); + + /* create a new thread, and give it a unique name */ + thread = gst_element_factory_make ("thread", NULL); + + /* the core bins (GstBin, GstThread, GstPipeline) also have convenience APIs, + gst_<bintype>_new (). these are equivalent to the gst_element_factory_make () syntax. */ + pipeline = gst_pipeline_new ("pipeline_name"); + + + + + Adding elements to a bin + + Elements are added to a bin with the following code sample: + + + GstElement *element; + GstElement *bin; + + bin = gst_bin_new ("mybin"); + + element = gst_element_factory_make ("mpg123", "decoder"); + gst_bin_add (GST_BIN (bin), element); + ... + + + Bins and threads can be added to other bins too. This allows you to create nested bins. Pipelines shouldn't be added to any other element, though. + They are toplevel bins and they are directly linked to the scheduler. + + + To get an element from the bin you can use: + + + GstElement *element; + + element = gst_bin_get_by_name (GST_BIN (bin), "decoder"); + ... + + + You can see that the name of the element becomes very handy + for retrieving the element from a bin by using the element's + name. gst_bin_get_by_name () will recursively search nested bins. + + + To get a list of elements in a bin, use: + + + GList *elements; + + elements = gst_bin_get_list (GST_BIN (bin)); + + while (elements) { + GstElement *element = GST_ELEMENT (elements->data); + + g_print ("element in bin: %s\n", GST_OBJECT_NAME (GST_OBJECT (element))); + + elements = g_list_next (elements); + } + ... + + + To remove an element from a bin, use: + + + GstElement *element; + + gst_bin_remove (GST_BIN (bin), element); + ... + + + To add many elements to a bin at the same time, use the gst_bin_add_many + () function. Remember to pass NULL as the last argument. + + + GstElement *filesrc, *decoder, *audiosink; + GstBin *bin; + + /* instantiate the elements and the bins... */ + + gst_bin_add_many (bin, filesrc, decoder, audiosink, NULL); + + + + + Custom bins + + The application programmer can create custom bins packed with elements + to perform a specific task. This allows you to write an MPEG audio + decoder with just the following lines of code: + + + + /* create the mp3player element */ + GstElement *mp3player = gst_element_factory_make ("mp3player", "mp3player"); + /* set the source mp3 audio file */ + g_object_set (G_OBJECT (mp3player), "location", "helloworld.mp3", NULL); + /* start playback */ + gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PLAYING); + ... + /* pause playback */ + gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PAUSED); + ... + /* stop */ + gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_NULL); + + + Note that the above code assumes that the mp3player bin derives itself + from a GstThread, which begins to play as soon + as its state is set to PLAYING. Other bin types may need explicit + iteration. For more information, see . + + + Custom bins can be created with a plugin or an XML description. You + will find more information about creating custom bin in the Plugin + Writers Guide (FIXME ref). + + + + + Ghost pads + + You can see from how a bin has no pads of its own. + This is where "ghost pads" come into play. + +
+ Visualisation of a <classname>GstBin</classname> element without ghost pads + + + + + +
+ + A ghost pad is a pad from some element in the bin that has been promoted to the bin. + This way, the bin also has a pad. The bin becomes just another element with a pad and + you can then use the bin just like any other element. This is a very important feature + for creating custom bins. + + +
+ Visualisation of a <classname>GstBin</classname> element with a ghost pad + + + + + +
+ + + is a representation of a ghost pad. The sink pad of element one is now also a pad + of the bin. + + + Ghost pads can actually be added to all GstElements and not just + GstBins. Use the following code example to add a ghost pad to a bin: + + + GstElement *bin; + GstElement *element; + + element = gst_element_factory_create ("mad", "decoder"); + bin = gst_bin_new ("mybin"); + + gst_bin_add (GST_BIN (bin), element); + + gst_element_add_ghost_pad (bin, gst_element_get_pad (element, "sink"), "sink"); + + + + In the above example, the bin now also has a pad: the pad called 'sink' + of the given element. + + + We can now, for example, link the source pad of a filesrc element + to the bin with: + + + GstElement *filesrc; + + filesrc = gst_element_factory_create ("filesrc", "disk_reader"); + + gst_element_link_pads (filesrc, "src", bin, "sink"); + ... + + + + diff --git a/docs/manual/bins.xml b/docs/manual/bins.xml index 54d018a..9372681 100644 --- a/docs/manual/bins.xml +++ b/docs/manual/bins.xml @@ -46,203 +46,4 @@ - - - Creating a bin - - Bins are created in the same way that other elements are created. ie. - using an element factory, or any of the associated convenience functions: - - - GstElement *bin, *thread, *pipeline; - - /* create a new bin called 'mybin'. this bin will be only for organizational purposes; a normal - GstBin doesn't affect plan generation */ - bin = gst_element_factory_make ("bin", "mybin"); - - /* create a new thread, and give it a unique name */ - thread = gst_element_factory_make ("thread", NULL); - - /* the core bins (GstBin, GstThread, GstPipeline) also have convenience APIs, - gst_<bintype>_new (). these are equivalent to the gst_element_factory_make () syntax. */ - pipeline = gst_pipeline_new ("pipeline_name"); - - - - - Adding elements to a bin - - Elements are added to a bin with the following code sample: - - - GstElement *element; - GstElement *bin; - - bin = gst_bin_new ("mybin"); - - element = gst_element_factory_make ("mpg123", "decoder"); - gst_bin_add (GST_BIN (bin), element); - ... - - - Bins and threads can be added to other bins too. This allows you to create nested bins. Pipelines shouldn't be added to any other element, though. - They are toplevel bins and they are directly linked to the scheduler. - - - To get an element from the bin you can use: - - - GstElement *element; - - element = gst_bin_get_by_name (GST_BIN (bin), "decoder"); - ... - - - You can see that the name of the element becomes very handy - for retrieving the element from a bin by using the element's - name. gst_bin_get_by_name () will recursively search nested bins. - - - To get a list of elements in a bin, use: - - - GList *elements; - - elements = gst_bin_get_list (GST_BIN (bin)); - - while (elements) { - GstElement *element = GST_ELEMENT (elements->data); - - g_print ("element in bin: %s\n", GST_OBJECT_NAME (GST_OBJECT (element))); - - elements = g_list_next (elements); - } - ... - - - To remove an element from a bin, use: - - - GstElement *element; - - gst_bin_remove (GST_BIN (bin), element); - ... - - - To add many elements to a bin at the same time, use the gst_bin_add_many - () function. Remember to pass NULL as the last argument. - - - GstElement *filesrc, *decoder, *audiosink; - GstBin *bin; - - /* instantiate the elements and the bins... */ - - gst_bin_add_many (bin, filesrc, decoder, audiosink, NULL); - - - - - Custom bins - - The application programmer can create custom bins packed with elements - to perform a specific task. This allows you to write an MPEG audio - decoder with just the following lines of code: - - - - /* create the mp3player element */ - GstElement *mp3player = gst_element_factory_make ("mp3player", "mp3player"); - /* set the source mp3 audio file */ - g_object_set (G_OBJECT (mp3player), "location", "helloworld.mp3", NULL); - /* start playback */ - gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PLAYING); - ... - /* pause playback */ - gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PAUSED); - ... - /* stop */ - gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_NULL); - - - Note that the above code assumes that the mp3player bin derives itself - from a GstThread, which begins to play as soon - as its state is set to PLAYING. Other bin types may need explicit - iteration. For more information, see . - - - Custom bins can be created with a plugin or an XML description. You - will find more information about creating custom bin in the Plugin - Writers Guide (FIXME ref). - - - - - Ghost pads - - You can see from how a bin has no pads of its own. - This is where "ghost pads" come into play. - -
- Visualisation of a <classname>GstBin</classname> element without ghost pads - - - - - -
- - A ghost pad is a pad from some element in the bin that has been promoted to the bin. - This way, the bin also has a pad. The bin becomes just another element with a pad and - you can then use the bin just like any other element. This is a very important feature - for creating custom bins. - - -
- Visualisation of a <classname>GstBin</classname> element with a ghost pad - - - - - -
- - - is a representation of a ghost pad. The sink pad of element one is now also a pad - of the bin. - - - Ghost pads can actually be added to all GstElements and not just - GstBins. Use the following code example to add a ghost pad to a bin: - - - GstElement *bin; - GstElement *element; - - element = gst_element_factory_create ("mad", "decoder"); - bin = gst_bin_new ("mybin"); - - gst_bin_add (GST_BIN (bin), element); - - gst_element_add_ghost_pad (bin, gst_element_get_pad (element, "sink"), "sink"); - - - - In the above example, the bin now also has a pad: the pad called 'sink' - of the given element. - - - We can now, for example, link the source pad of a filesrc element - to the bin with: - - - GstElement *filesrc; - - filesrc = gst_element_factory_create ("filesrc", "disk_reader"); - - gst_element_link_pads (filesrc, "src", bin, "sink"); - ... - - - diff --git a/docs/manual/buffers-api.xml b/docs/manual/buffers-api.xml new file mode 100644 index 0000000..5546c87 --- /dev/null +++ b/docs/manual/buffers-api.xml @@ -0,0 +1,6 @@ + + Buffers + + + + diff --git a/docs/manual/elements-api.xml b/docs/manual/elements-api.xml new file mode 100644 index 0000000..8cb9971 --- /dev/null +++ b/docs/manual/elements-api.xml @@ -0,0 +1,141 @@ + + Elements + + Creating a GstElement + + A GstElement object is created from + a factory. To create an element, you have to get access to a + GstElementFactory object using a unique + factory name. + + + The following code example is used to get a factory that can be used + to create the 'mad' element, an mp3 decoder. + + + GstElementFactory *factory; + + factory = gst_element_factory_find ("mad"); + + + Once you have the handle to the element factory, you can create a + real element with the following code fragment: + + + GstElement *element; + + element = gst_element_factory_create (factory, "decoder"); + + + gst_element_factory_create will use the element + factory to create an element with the given name. The name of the + element is something you can use later on to look up the element in + a bin, for example. You can pass NULL as the name + argument to get a unique, default name. + + + A simple shortcut exists for creating an element from a factory. The + following example creates an element named "decoder" from the element + factory named "mad". This convenience function is most widely used to + create an element. + + + GstElement *element; + + element = gst_element_factory_make ("mad", "decoder"); + + + When you don't need the element anymore, you need to unref it, as shown in the following + example. + + + GstElement *element; + + ... + gst_element_unref (element); + + + + GstElement properties + + A GstElement can have several properties + which are implemented using standard GObject + properties. The usual GObject methods to query, + set and get property values and GParamSpecs + are therefore supported. + + + Every GstElement inherits at least + one property of its parent GstObject: + the "name" property. This is the name you provide to the + functions gst_element_factory_make or + gst_element_factory_create. You can get and set + this property using the functions + gst_object_set_name + and gst_object_get_name or use the + GObject property mechanism as shown below. + + + GstElement *element; + GValue value = { 0, }; /* initialize the GValue for g_object_get() */ + + element = gst_element_factory_make ("mad", "decoder"); + g_object_set (G_OBJECT (element), "name", "mydecoder", NULL); + ... + + g_value_init (&value, G_TYPE_STRING); + g_object_get_property (G_OBJECT (element), "name", &value); + ... + + + Most plugins provide additional properties to provide more information + about their configuration or to configure the element. + gst-inspect is a useful tool to query the properties + of a particular element, it will also use property introspection to give + a short explanation about the function of the property and about the + parameter types and ranges it supports. + + + For more information about GObject + properties we recommend you read the GObject manual and an introduction to + The Glib Object system. + + + + + GstElement signals + + A GstElement also provides various + GObject signals that can be used as a flexible + callback mechanism. + + + + + More about GstElementFactory + + We talk some more about the GstElementFactory object. + + + + Getting information about an element using the factory details + + + + + + Finding out what pads an element can contain + + + + + + Different ways of querying the factories + + + + + diff --git a/docs/manual/elements.xml b/docs/manual/elements.xml index 9fc8a90..a712e8b 100644 --- a/docs/manual/elements.xml +++ b/docs/manual/elements.xml @@ -115,142 +115,4 @@ - - Creating a GstElement - - A GstElement object is created from - a factory. To create an element, you have to get access to a - GstElementFactory object using a unique - factory name. - - - The following code example is used to get a factory that can be used - to create the 'mad' element, an mp3 decoder. - - - GstElementFactory *factory; - - factory = gst_element_factory_find ("mad"); - - - Once you have the handle to the element factory, you can create a - real element with the following code fragment: - - - GstElement *element; - - element = gst_element_factory_create (factory, "decoder"); - - - gst_element_factory_create will use the element - factory to create an element with the given name. The name of the - element is something you can use later on to look up the element in - a bin, for example. You can pass NULL as the name - argument to get a unique, default name. - - - A simple shortcut exists for creating an element from a factory. The - following example creates an element named "decoder" from the element - factory named "mad". This convenience function is most widely used to - create an element. - - - GstElement *element; - - element = gst_element_factory_make ("mad", "decoder"); - - - When you don't need the element anymore, you need to unref it, as shown in the following - example. - - - GstElement *element; - - ... - gst_element_unref (element); - - - - GstElement properties - - A GstElement can have several properties - which are implemented using standard GObject - properties. The usual GObject methods to query, - set and get property values and GParamSpecs - are therefore supported. - - - Every GstElement inherits at least - one property of its parent GstObject: - the "name" property. This is the name you provide to the - functions gst_element_factory_make or - gst_element_factory_create. You can get and set - this property using the functions - gst_object_set_name - and gst_object_get_name or use the - GObject property mechanism as shown below. - - - GstElement *element; - GValue value = { 0, }; /* initialize the GValue for g_object_get() */ - - element = gst_element_factory_make ("mad", "decoder"); - g_object_set (G_OBJECT (element), "name", "mydecoder", NULL); - ... - - g_value_init (&value, G_TYPE_STRING); - g_object_get_property (G_OBJECT (element), "name", &value); - ... - - - Most plugins provide additional properties to provide more information - about their configuration or to configure the element. - gst-inspect is a useful tool to query the properties - of a particular element, it will also use property introspection to give - a short explanation about the function of the property and about the - parameter types and ranges it supports. - - - For more information about GObject - properties we recommend you read the GObject manual and an introduction to - The Glib Object system. - - - - - GstElement signals - - A GstElement also provides various - GObject signals that can be used as a flexible - callback mechanism. - - - - - More about GstElementFactory - - We talk some more about the GstElementFactory object. - - - - Getting information about an element using the factory details - - - - - - Finding out what pads an element can contain - - - - - - Different ways of querying the factories - - - - diff --git a/docs/manual/init-api.xml b/docs/manual/init-api.xml new file mode 100644 index 0000000..7f73fde --- /dev/null +++ b/docs/manual/init-api.xml @@ -0,0 +1,78 @@ + + Initializing <application>GStreamer</application> + + When writing a GStreamer application, you can + simply include gst/gst.h to get + access to the library functions. + + + Before the GStreamer libraries can be used, + gst_init has to be called from the main application. + This call will perform the necessary initialization of the library as + well as parse the GStreamer-specific command line options. + + + A typical program would start like this: + + + +#include <gst/gst.h> + +... + +int +main (int argc, char *argv[]) +{ + ... + gst_init (&argc, &argv); + ... +} + + + Use the GST_VERSION_MAJOR, + GST_VERSION_MINOR and GST_VERSION_MICRO + macros to get the GStreamer version you are + building against, or use the function gst_version + to get the version your application is linked against. + + + + It is also possible to call the gst_init function + with two NULL arguments, in which case no command line + options will parsed by GStreamer. + + + The popt interface + + You can also use a popt table to initialize your own parameters as shown in the next code fragment: + + +int +main(int argc, char *argv[]) +{ + gboolean silent = FALSE; + gchar *savefile = NULL; + struct poptOption options[] = { + {"silent", 's', POPT_ARG_NONE|POPT_ARGFLAG_STRIP, &silent, 0, + "do not output status information", NULL}, + {"output", 'o', POPT_ARG_STRING|POPT_ARGFLAG_STRIP, &savefile, 0, + "save xml representation of pipeline to FILE and exit", "FILE"}, + POPT_TABLEEND + }; + + gst_init_with_popt_table (&argc, &argv, options); + + ... + + + As shown in this fragment, you can use a popt table to define your application-specific + command line options, and pass this table to the + function gst_init_with_popt_table. Your + application options will be parsed in addition to the standard + GStreamer options. + + + + diff --git a/docs/manual/links-api.xml b/docs/manual/links-api.xml new file mode 100644 index 0000000..b4a8f1b --- /dev/null +++ b/docs/manual/links-api.xml @@ -0,0 +1,79 @@ + + Linking elements + + Making simple links + + You can link two pads with: + + + GstPad *srcpad, *sinkpad; + + srcpad = gst_element_get_pad (element1, "src"); + sinpad = gst_element_get_pad (element2, "sink"); + + // link them + gst_pad_link (srcpad, sinkpad); + .... + // and unlink them + gst_pad_unlink (srcpad, sinkpad); + + + + A convenient shortcut for the above code is done with the gst_element_link_pads () + function: + + + + // link them + gst_element_link_pads (element1, "src", element2, "sink"); + .... + // and unlink them + gst_element_unlink_pads (element1, "src", element2, "sink"); + + + + An even more convenient shortcut for single-source, single-sink elements is the + gst_element_link () function: + + + + // link them + gst_element_link (element1, element2); + .... + // and unlink them + gst_element_unlink (element1, element2); + + + + If you have more than one element to link, the gst_element_link_many () function takes + a NULL-terminated list of elements: + + + + // link them + gst_element_link_many (element1, element2, element3, element4, NULL); + .... + // and unlink them + gst_element_unlink_many (element1, element2, element3, element4, NULL); + + + + You can query if a pad is linked with GST_PAD_IS_LINKED (pad). + + + To query for the GstPad a pad is linked to, use + gst_pad_get_peer (pad). + + + + + Making filtered links + + You can also force a specific media type on the link by using gst_pad_link_filtered () + and gst_element_link_filtered () with capabilities. + See for + an explanation of capabilities. + + + + diff --git a/docs/manual/links.xml b/docs/manual/links.xml index c9d1dd2..d313e69 100644 --- a/docs/manual/links.xml +++ b/docs/manual/links.xml @@ -26,81 +26,4 @@ the sink element is your audiocard. We will use this simple graph to construct an MPEG player later in this manual. - - - Making simple links - - You can link two pads with: - - - GstPad *srcpad, *sinkpad; - - srcpad = gst_element_get_pad (element1, "src"); - sinpad = gst_element_get_pad (element2, "sink"); - - // link them - gst_pad_link (srcpad, sinkpad); - .... - // and unlink them - gst_pad_unlink (srcpad, sinkpad); - - - - A convenient shortcut for the above code is done with the gst_element_link_pads () - function: - - - - // link them - gst_element_link_pads (element1, "src", element2, "sink"); - .... - // and unlink them - gst_element_unlink_pads (element1, "src", element2, "sink"); - - - - An even more convenient shortcut for single-source, single-sink elements is the - gst_element_link () function: - - - - // link them - gst_element_link (element1, element2); - .... - // and unlink them - gst_element_unlink (element1, element2); - - - - If you have more than one element to link, the gst_element_link_many () function takes - a NULL-terminated list of elements: - - - - // link them - gst_element_link_many (element1, element2, element3, element4, NULL); - .... - // and unlink them - gst_element_unlink_many (element1, element2, element3, element4, NULL); - - - - You can query if a pad is linked with GST_PAD_IS_LINKED (pad). - - - To query for the GstPad a pad is linked to, use - gst_pad_get_peer (pad). - - - - - Making filtered links - - You can also force a specific media type on the link by using gst_pad_link_filtered () - and gst_element_link_filtered () with capabilities. - See for - an explanation of capabilities. - - - diff --git a/docs/manual/manual.xml b/docs/manual/manual.xml index bf24936..5f08b68 100644 --- a/docs/manual/manual.xml +++ b/docs/manual/manual.xml @@ -6,23 +6,37 @@ %version-entities; + - + + + + + + + + + + + + + + @@ -34,7 +48,6 @@ - @@ -125,7 +138,7 @@ - Basic concepts + Basic Concepts We will first describe the basics of @@ -138,9 +151,6 @@ - - &INIT; - &ELEMENTS; &PADS; @@ -154,8 +164,29 @@ &BUFFERS; &STATES; + + + + Basic API + &INIT-API; + + &ELEMENTS-API; + + &PADS-API; + &PLUGINS-API; + + &LINKS-API; + + &BINS-API; + + &BUFFERS-API; + + &STATES-API; + + + Building an application diff --git a/docs/manual/pads-api.xml b/docs/manual/pads-api.xml new file mode 100644 index 0000000..f7b1c36 --- /dev/null +++ b/docs/manual/pads-api.xml @@ -0,0 +1,301 @@ + + Pads + + As we have seen in , the pads are the element's + interface to the outside world. + + + The specific type of media that the element can handle will be exposed by the pads. + The description of this media type is done with capabilities(see + ) + + + + Pads are either source or sink pads. The terminology is defined from the + view of the element itself: elements accept data on their sink pads, and + send data out on their source pads. Sink pads are drawn on the left, + while source pads are drawn on the right of an element. In general, + data flows from left to right in the graph. + + In reality, there is no objection to data flowing from a + source pad to the sink pad of an element upstream. Data will, however, + always flow from a source pad of one element to the sink pad of + another. + + + + + Types of pads + + + Dynamic pads + + You can attach a signal to an element to inform you when the element has created + a new pad from one of its padtemplates. The following piece of code is an example + of how to do this: + + +static void +pad_link_func (GstElement *parser, GstPad *pad, GstElement *pipeline) +{ + g_print("***** a new pad %s was created\n", gst_pad_get_name(pad)); + + gst_element_set_state (pipeline, GST_STATE_PAUSED); + + if (strncmp (gst_pad_get_name (pad), "private_stream_1.0", 18) == 0) { + // set up an AC3 decoder pipeline + ... + // link pad to the AC3 decoder pipeline + ... + } + gst_element_set_state (GST_ELEMENT (audio_thread), GST_STATE_READY); +} + +int +main(int argc, char *argv[]) +{ + GstElement *pipeline; + GstElement *mpeg2parser; + + // create pipeline and do something useful + ... + + mpeg2parser = gst_element_factory_make ("mpegdemux", "mpegdemux"); + g_signal_connect (G_OBJECT (mpeg2parser), "new_pad", pad_link_func, pipeline); + ... + + // start the pipeline + gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING); + ... +} + + + + A pipeline cannot be changed in the PLAYING state. + + + + + Request pads + + The following piece of code can be used to get a pad from the tee element. After + the pad has been requested, it can be used to link another element to it. + + + ... + GstPad *pad; + ... + element = gst_element_factory_make ("tee", "element"); + + pad = gst_element_get_request_pad (element, "src%d"); + g_print ("new pad %s\n", gst_pad_get_name (pad)); + ... + + + The gst_element_get_request_pad method can be used to get a pad + from the element based on the name_template of the padtemplate. + + + It is also possible to request a pad that is compatible with another + pad template. This is very useful if you want to link an element + to a multiplexer element and you need to request a pad that is + compatible. The gst_element_get_compatible_pad is used to request + a compatible pad, as is shown in the next example. + + + ... + GstPadTemplate *templ; + GstPad *pad; + ... + element = gst_element_factory_make ("tee", "element"); + mad = gst_element_factory_make ("mad", "mad"); + + templ = gst_element_get_pad_template_by_name (mad, "sink"); + + pad = gst_element_get_compatible_pad (element, templ); + g_print ("new pad %s\n", gst_pad_get_name (pad)); + ... + + + + + + + Capabilities of a pad + + Since the pads play a very important role in how the element is viewed by the + outside world, a mechanism is implemented to describe the data that can + flow through the pad by using capabilities. + + + We will briefly describe what capabilities are, enough for you to get a basic understanding + of the concepts. You will find more information on how to create capabilities in the + Plugin Writer's Guide. + + + + Capabilities + + Capabilities are attached to a pad in order to describe + what type of media the pad can handle. + + + Its structure is: + + +struct _GstCaps { + gchar *name; /* the name of this caps */ + guint16 id; /* type id (major type) */ + + guint refcount; /* caps are refcounted */ + + GstProps *properties; /* properties for this capability */ + + GstCaps *next; /* caps can be chained together */ +}; + + + + + Getting the capabilities of a pad + + A pad can have a chain of capabilities attached to it. You can get the capabilities chain + with: + + + GstCaps *caps; + ... + caps = gst_pad_get_caps (pad); + + g_print ("pad name %s\n", gst_pad_get_name (pad)); + + while (caps) { + g_print (" Capability name %s, MIME type %s\n", + gst_caps_get_name (cap), + gst_caps_get_mime (cap)); + + caps = caps->next; + } + ... + + + + Creating capability structures + + While capabilities are mainly used inside a plugin to describe the + media type of the pads, the application programmer also has to have + basic understanding of capabilities in order to interface with the + plugins, specially when using the autopluggers. + + + As we said, a capability has a name, a mime-type and some + properties. The signature of the function to create a new + GstCaps structure is: + + +GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props); + + + + You can therefore create a new capability with no properties like this: + + GstCaps *newcaps; + + newcaps = gst_caps_new ("my_caps", "audio/wav", NULL); + + + + GstProps basically consist of a set of key-value pairs + and are created with a function with this signature: + +GstProps* gst_props_new (const gchar *firstname, ...); + + + + The keys are given as strings and the values are given with a set of macros: + + + + GST_PROPS_INT(a): An integer value + + + + + GST_PROPS_FLOAT(a): A floating point value + + + + + GST_PROPS_FOURCC(a): A fourcc value + + + + + GST_PROPS_BOOLEAN(a): A boolean value + + + + + GST_PROPS_STRING(a): A string value + + + + The values can also be specified as ranges with: + + + + GST_PROPS_INT_RANGE(a,b): An integer range from a to b + + + + + GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b + + + + All of the above values can be given with a list too, using: + + + + GST_PROPS_LIST(a,...): A list of property values. + + + + + + A more complex capability with properties is created like this: + + GstCaps *newcaps; + + newcaps = gst_caps_new ("my_caps", + "audio/wav", + gst_props_new ( + "bitrate", GST_PROPS_INT_RANGE (11025,22050), + "depth", GST_PROPS_INT (16), + "signed", GST_PROPS_LIST ( + GST_PROPS_BOOLEAN (TRUE), + GST_PROPS_BOOLEAN (FALSE) + ), + NULL + ); + + Optionally, the convenient shortcut macro can be used. The above complex + capability can be created with: + + GstCaps *newcaps; + + newcaps = GST_CAPS_NEW ("my_caps", + "audio/wav", + "bitrate", GST_PROPS_INT_RANGE (11025,22050), + "depth", GST_PROPS_INT (16), + "signed", GST_PROPS_LIST ( + GST_PROPS_BOOLEAN (TRUE), + GST_PROPS_BOOLEAN (FALSE) + ) + ); + + + + + + diff --git a/docs/manual/pads.xml b/docs/manual/pads.xml index 391fe1b..47fd004 100644 --- a/docs/manual/pads.xml +++ b/docs/manual/pads.xml @@ -24,57 +24,6 @@ - - Getting pads from an element - - Once you have created an element, you can get one of its pads with: - - - GstPad *srcpad; - ... - srcpad = gst_element_get_pad (element, "src"); - ... - - - This function will get the pad named "src" from the given element. - - - Alternatively, you can request a GList of pads from the element. The - following code example will print the names of all the pads of an - element. - - - GList *pads; - ... - pads = gst_element_get_pad_list (element); - while (pads) { - GstPad *pad = GST_PAD (pads->data); - - g_print ("pad name %s\n", gst_pad_get_name (pad)); - - pads = g_list_next (pads); - } - ... - - - Useful pad functions - - You can get the name of a pad with gst_pad_get_name () and set its name with - get_pad_set_name(). - - - gst_pad_get_direction (GstPad *pad) can be used to query if the pad - is a sink or a source pad. Remember that a source pad is a pad that - can output data and a sink pad is one that accepts data. - - - You can get the parent of the pad, this is the element that this pad belongs to, - with get_pad_get_parent(GstPad *pad). This function will return a pointer to a - GstElement. - - - - Types of pads @@ -97,51 +46,6 @@ will see that this is very important when you are going to create dynamic pipelines later on in this manual. - - You can attach a signal to an element to inform you when the element has created - a new pad from one of its padtemplates. The following piece of code is an example - of how to do this: - - -static void -pad_link_func (GstElement *parser, GstPad *pad, GstElement *pipeline) -{ - g_print("***** a new pad %s was created\n", gst_pad_get_name(pad)); - - gst_element_set_state (pipeline, GST_STATE_PAUSED); - - if (strncmp (gst_pad_get_name (pad), "private_stream_1.0", 18) == 0) { - // set up an AC3 decoder pipeline - ... - // link pad to the AC3 decoder pipeline - ... - } - gst_element_set_state (GST_ELEMENT (audio_thread), GST_STATE_READY); -} - -int -main(int argc, char *argv[]) -{ - GstElement *pipeline; - GstElement *mpeg2parser; - - // create pipeline and do something useful - ... - - mpeg2parser = gst_element_factory_make ("mpegdemux", "mpegdemux"); - g_signal_connect (G_OBJECT (mpeg2parser), "new_pad", pad_link_func, pipeline); - ... - - // start the pipeline - gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING); - ... -} - - - - A pipeline cannot be changed in the PLAYING state. - - Request pads @@ -155,45 +59,6 @@ main(int argc, char *argv[]) output pads. Whenever an element wants to get an output pad from the tee element, it has to request the pad. - - The following piece of code can be used to get a pad from the tee element. After - the pad has been requested, it can be used to link another element to it. - - - ... - GstPad *pad; - ... - element = gst_element_factory_make ("tee", "element"); - - pad = gst_element_get_request_pad (element, "src%d"); - g_print ("new pad %s\n", gst_pad_get_name (pad)); - ... - - - The gst_element_get_request_pad method can be used to get a pad - from the element based on the name_template of the padtemplate. - - - It is also possible to request a pad that is compatible with another - pad template. This is very useful if you want to link an element - to a multiplexer element and you need to request a pad that is - compatible. The gst_element_get_compatible_pad is used to request - a compatible pad, as is shown in the next example. - - - ... - GstPadTemplate *templ; - GstPad *pad; - ... - element = gst_element_factory_make ("tee", "element"); - mad = gst_element_factory_make ("mad", "mad"); - - templ = gst_element_get_pad_template_by_name (mad, "sink"); - - pad = gst_element_get_compatible_pad (element, templ); - g_print ("new pad %s\n", gst_pad_get_name (pad)); - ... - @@ -212,7 +77,7 @@ main(int argc, char *argv[]) - What are capabilities ? + Capabilities Capabilities are attached to a pad in order to describe what type of media the pad can handle. @@ -225,29 +90,16 @@ main(int argc, char *argv[]) The basic entity is a capability, and is defined by a name, a MIME type and a set of properties. A capability can be chained to another capability, which is why we commonly refer to a chain of - capability entities as "capabilities". + capability entities as "capabilities". + It is important to understand that the term "capabilities" refers to a chain of one capability or more. This will be clearer when you see the structure definition of a GstCaps element. - - - - Its structure is: + + - -struct _GstCaps { - gchar *name; /* the name of this caps */ - guint16 id; /* type id (major type) */ - - guint refcount; /* caps are refcounted */ - - GstProps *properties; /* properties for this capability */ - - GstCaps *next; /* caps can be chained together */ -}; - Below is a dump of the capabilities of the element mad, as shown by gst-inspect. @@ -387,146 +239,5 @@ Pads: - - Getting the capabilities of a pad - - A pad can have a chain of capabilities attached to it. You can get the capabilities chain - with: - - - GstCaps *caps; - ... - caps = gst_pad_get_caps (pad); - - g_print ("pad name %s\n", gst_pad_get_name (pad)); - - while (caps) { - g_print (" Capability name %s, MIME type %s\n", - gst_caps_get_name (cap), - gst_caps_get_mime (cap)); - - caps = caps->next; - } - ... - - - - Creating capability structures - - While capabilities are mainly used inside a plugin to describe the - media type of the pads, the application programmer also has to have - basic understanding of capabilities in order to interface with the - plugins, specially when using the autopluggers. - - - As we said, a capability has a name, a mime-type and some - properties. The signature of the function to create a new - GstCaps structure is: - - -GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props); - - - - You can therefore create a new capability with no properties like this: - - GstCaps *newcaps; - - newcaps = gst_caps_new ("my_caps", "audio/wav", NULL); - - - - GstProps basically consist of a set of key-value pairs - and are created with a function with this signature: - -GstProps* gst_props_new (const gchar *firstname, ...); - - - - The keys are given as strings and the values are given with a set of macros: - - - - GST_PROPS_INT(a): An integer value - - - - - GST_PROPS_FLOAT(a): A floating point value - - - - - GST_PROPS_FOURCC(a): A fourcc value - - - - - GST_PROPS_BOOLEAN(a): A boolean value - - - - - GST_PROPS_STRING(a): A string value - - - - The values can also be specified as ranges with: - - - - GST_PROPS_INT_RANGE(a,b): An integer range from a to b - - - - - GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b - - - - All of the above values can be given with a list too, using: - - - - GST_PROPS_LIST(a,...): A list of property values. - - - - - - A more complex capability with properties is created like this: - - GstCaps *newcaps; - - newcaps = gst_caps_new ("my_caps", - "audio/wav", - gst_props_new ( - "bitrate", GST_PROPS_INT_RANGE (11025,22050), - "depth", GST_PROPS_INT (16), - "signed", GST_PROPS_LIST ( - GST_PROPS_BOOLEAN (TRUE), - GST_PROPS_BOOLEAN (FALSE) - ), - NULL - ); - - Optionally, the convenient shortcut macro can be used. The above complex - capability can be created with: - - GstCaps *newcaps; - - newcaps = GST_CAPS_NEW ("my_caps", - "audio/wav", - "bitrate", GST_PROPS_INT_RANGE (11025,22050), - "depth", GST_PROPS_INT (16), - "signed", GST_PROPS_LIST ( - GST_PROPS_BOOLEAN (TRUE), - GST_PROPS_BOOLEAN (FALSE) - ) - ); - - - - diff --git a/docs/manual/plugins-api.xml b/docs/manual/plugins-api.xml new file mode 100644 index 0000000..e7c3d54 --- /dev/null +++ b/docs/manual/plugins-api.xml @@ -0,0 +1,56 @@ + + Plugins + + + All plugins should implement one function, plugin_init, + that creates all the element factories and registers all the type + definitions contained in the plugin. + Without this function, a plugin cannot be registered. + + + The plugins are maintained in the plugin system. Optionally, the + type definitions and the element factories can be saved into an XML + representation so that the plugin system does not have to load all + available plugins in order to know their definition. + + + + The basic plugin structure has the following fields: + + +typedef struct _GstPlugin GstPlugin; + +struct _GstPlugin { + gchar *name; /* name of the plugin */ + gchar *longname; /* long name of plugin */ + gchar *filename; /* filename it came from */ + + GList *types; /* list of types provided */ + gint numtypes; + GList *elements; /* list of elements provided */ + gint numelements; + GList *autopluggers; /* list of autopluggers provided */ + gint numautopluggers; + + gboolean loaded; /* if the plugin is in memory */ +}; + + + + You can query a GList of available plugins with the + function gst_plugin_get_list as this example shows: + + + GList *plugins; + + plugins = gst_plugin_get_list (); + + while (plugins) { + GstPlugin *plugin = (GstPlugin *)plugins->data; + + g_print ("plugin: %s\n", gst_plugin_get_name (plugin)); + + plugins = g_list_next (plugins); + } + + diff --git a/docs/manual/plugins.xml b/docs/manual/plugins.xml index 4acbfc6..c8e62ee 100644 --- a/docs/manual/plugins.xml +++ b/docs/manual/plugins.xml @@ -28,56 +28,4 @@ - - All plugins should implement one function, plugin_init, - that creates all the element factories and registers all the type - definitions contained in the plugin. - Without this function, a plugin cannot be registered. - - - The plugins are maintained in the plugin system. Optionally, the - type definitions and the element factories can be saved into an XML - representation so that the plugin system does not have to load all - available plugins in order to know their definition. - - - - The basic plugin structure has the following fields: - - -typedef struct _GstPlugin GstPlugin; - -struct _GstPlugin { - gchar *name; /* name of the plugin */ - gchar *longname; /* long name of plugin */ - gchar *filename; /* filename it came from */ - - GList *types; /* list of types provided */ - gint numtypes; - GList *elements; /* list of elements provided */ - gint numelements; - GList *autopluggers; /* list of autopluggers provided */ - gint numautopluggers; - - gboolean loaded; /* if the plugin is in memory */ -}; - - - - You can query a GList of available plugins with the - function gst_plugin_get_list as this example shows: - - - GList *plugins; - - plugins = gst_plugin_get_list (); - - while (plugins) { - GstPlugin *plugin = (GstPlugin *)plugins->data; - - g_print ("plugin: %s\n", gst_plugin_get_name (plugin)); - - plugins = g_list_next (plugins); - } - diff --git a/docs/manual/states-api.xml b/docs/manual/states-api.xml new file mode 100644 index 0000000..553a7fd --- /dev/null +++ b/docs/manual/states-api.xml @@ -0,0 +1,48 @@ + + Element states + + Changing element state + + The state of an element can be changed with the following code: + + + GstElement *bin; + + // create a bin, put elements in it and link them + ... + gst_element_set_state (bin, GST_STATE_PLAYING); + ... + + + + You can set the following states on an element: + + + + + + GST_STATE_NULL + Reset the state of an element. + + + + GST_STATE_READY + will make the element ready to start processing data. + + + + GST_STATE_PAUSED + temporary stops the data flow. + + + + GST_STATE_PLAYING + means there really is data flowing through the graph. + + + + + + + + diff --git a/docs/manual/states.xml b/docs/manual/states.xml index 402cde5..fe2b81e 100644 --- a/docs/manual/states.xml +++ b/docs/manual/states.xml @@ -40,17 +40,6 @@ PLAYING. When going from NULL to PLAYING, GStreamer will internally go throught the intermediate states. - - The state of an element can be changed with the following code: - - - GstElement *bin; - - // create a bin, put elements in it and link them - ... - gst_element_set_state (bin, GST_STATE_PLAYING); - ... - You can set the following states on an element: -- 2.7.4