summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTim-Philipp Müller <tim.muller@collabora.co.uk>2010-06-30 12:16:35 (GMT)
committerTim-Philipp Müller <tim.muller@collabora.co.uk>2010-06-30 12:16:35 (GMT)
commitcda5a353d27326c0272a79c92c11c221a4092da4 (patch)
tree6264852e8110f4d176710512fdccac557d327fb0
parentdbaae8f2442c44710242e58e6f85348faba0ca85 (diff)
docs: update 'XML in GStreamer' section in application developer's manual
-rw-r--r--docs/manual/highlevel-xml.xml265
1 files changed, 9 insertions, 256 deletions
diff --git a/docs/manual/highlevel-xml.xml b/docs/manual/highlevel-xml.xml
index 04cf7f9..e330616 100644
--- a/docs/manual/highlevel-xml.xml
+++ b/docs/manual/highlevel-xml.xml
@@ -1,264 +1,17 @@
<chapter id="chapter-xml">
- <title>XML in <application>GStreamer</application></title>
+ <title>XML in <application>GStreamer</application> (deprecated)</title>
<para>
- <application>GStreamer</application> can use XML to store and load
- its pipeline definitions.
+ <application>GStreamer</application> used to provide functions to
+ save pipeline definitions into XML format and later restore them
+ again from XML.
</para>
<para>
- We will show you how you can save a pipeline to XML and how you can reload that
- XML file again for later use.
+ This never really worked properly for all but the most simple use cases
+ though, and is also pretty much impossible to make work correctly in a
+ useful way due to the dynamic nature of almost all non-trivial GStreamer
+ pipelines. Consequently, this API has been deprecated and will be
+ removed at some point. Don't use it.
</para>
-
- <sect1 id="section-xml-write">
- <title>Turning GstElements into XML</title>
-
- <para>
- We create a simple pipeline and write it to stdout with
- gst_xml_write_file (). The following code constructs an MP3 player
- pipeline and then writes out the XML both to stdout
- and to a file. Use this program with one argument: the MP3 file on disk.
- </para>
-
- <programlisting>
-<!-- example-begin xml-mp3.c -->
-#include &lt;stdlib.h&gt;
-#include &lt;gst/gst.h&gt;
-
-gboolean playing;
-
-int
-main (int argc, char *argv[])
-{
- GstElement *filesrc, *osssink, *decode;
- GstElement *pipeline;
-
- gst_init (&amp;argc,&amp;argv);
-
- if (argc != 2) {
- g_print ("usage: %s &lt;mp3 filename&gt;\n", argv[0]);
- exit (-1);
- }
-
- /* create a new pipeline to hold the elements */
- pipeline = gst_element_factory_make ("pipeline", "pipeline");
- g_assert (pipeline != NULL);
-
- /* create a disk reader */
- filesrc = gst_element_factory_make ("filesrc", "disk_source");
- g_assert (filesrc != NULL);
- g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
-
- /* and an audio sink */
- osssink = gst_element_factory_make ("osssink", "play_audio");
- g_assert (osssink != NULL);
-
- decode = gst_element_factory_make ("mad", "decode");
- g_assert (decode != NULL);
-
- /* add objects to the main pipeline */
- gst_bin_add_many (GST_BIN (pipeline), filesrc, decode, osssink, NULL);
-
- gst_element_link_many (filesrc, decode, osssink, NULL);
-
- /* write the pipeline to stdout */
- gst_xml_write_file (GST_ELEMENT (pipeline), stdout);
-
- /* write the bin to a file */
- gst_xml_write_file (GST_ELEMENT (pipeline), fopen ("xmlTest.gst", "w"));
-
- exit (0);
-}
-<!-- example-end xml-mp3.c -->
- </programlisting>
- <para>
- The most important line is:
- </para>
- <programlisting>
- gst_xml_write_file (GST_ELEMENT (pipeline), stdout);
- </programlisting>
- <para>
- gst_xml_write_file () will turn the given element into an xmlDocPtr that
- is then formatted and saved to a file. To save to disk, pass the result
- of a fopen(2) as the second argument.
- </para>
- <para>
- The complete element hierarchy will be saved along with the inter element
- pad links and the element parameters. Future <application>GStreamer</application>
- versions will also allow you to store the signals in the XML file.
- </para>
- </sect1>
-
- <sect1 id="section-xml-load">
- <title>Loading a GstElement from an XML file</title>
- <para>
- Before an XML file can be loaded, you must create a GstXML object.
- A saved XML file can then be loaded with the
- gst_xml_parse_file (xml, filename, rootelement) method.
- The root element can optionally left NULL. The following code example loads
- the previously created XML file and runs it.
- </para>
- <programlisting>
-#include &lt;stdlib.h&gt;
-#include &lt;gst/gst.h&gt;
-
-int
-main(int argc, char *argv[])
-{
- GstXML *xml;
- GstElement *pipeline;
- gboolean ret;
-
- gst_init (&amp;argc, &amp;argv);
-
- xml = gst_xml_new ();
-
- ret = gst_xml_parse_file(xml, "xmlTest.gst", NULL);
- g_assert (ret == TRUE);
-
- pipeline = gst_xml_get_element (xml, "pipeline");
- g_assert (pipeline != NULL);
-
- gst_element_set_state (pipeline, GST_STATE_PLAYING);
-
- g_sleep (4);
-
- gst_element_set_state (pipeline, GST_STATE_NULL);
-
- exit (0);
-}
- </programlisting>
- <para>
- gst_xml_get_element (xml, "name") can be used to get a specific element
- from the XML file.
- </para>
- <para>
- gst_xml_get_topelements (xml) can be used to get a list of all toplevel elements
- in the XML file.
- </para>
- <para>
- In addition to loading a file, you can also load from a xmlDocPtr and
- an in-memory buffer using gst_xml_parse_doc and gst_xml_parse_memory
- respectively. Both of these methods return a gboolean indicating
- success or failure of the requested action.
- </para>
- </sect1>
- <sect1 id="section-xml-custom">
- <title>Adding custom XML tags into the core XML data</title>
-
- <para>
- It is possible to add custom XML tags to the core XML created with
- gst_xml_write. This feature can be used by an application to add more
- information to the save plugins. The editor will for example insert
- the position of the elements on the screen using the custom XML tags.
- </para>
- <para>
- It is strongly suggested to save and load the custom XML tags using
- a namespace. This will solve the problem of having your XML tags
- interfere with the core XML tags.
- </para>
- <para>
- To insert a hook into the element saving procedure you can link
- a signal to the GstElement using the following piece of code:
- </para>
- <programlisting>
-xmlNsPtr ns;
-
- ...
- ns = xmlNewNs (NULL, "http://gstreamer.net/gst-test/1.0/", "test");
- ...
- pipeline = gst_element_factory_make ("pipeline", "pipeline");
- g_signal_connect (G_OBJECT (pipeline), "object_saved",
- G_CALLBACK (object_saved), g_strdup ("decoder pipeline"));
- ...
- </programlisting>
- <para>
- When the thread is saved, the object_save method will be called. Our example
- will insert a comment tag:
- </para>
- <programlisting>
-static void
-object_saved (GstObject *object, xmlNodePtr parent, gpointer data)
-{
- xmlNodePtr child;
-
- child = xmlNewChild (parent, ns, "comment", NULL);
- xmlNewChild (child, ns, "text", (gchar *)data);
-}
- </programlisting>
- <para>
- Adding the custom tag code to the above example you will get an XML file
- with the custom tags in it. Here's an excerpt:
- </para>
- <programlisting>
- ...
- &lt;gst:element&gt;
- &lt;gst:name&gt;pipeline&lt;/gst:name&gt;
- &lt;gst:type&gt;pipeline&lt;/gst:type&gt;
- &lt;gst:version&gt;0.1.0&lt;/gst:version&gt;
- ...
- &lt;/gst:children&gt;
- &lt;test:comment&gt;
- &lt;test:text&gt;decoder pipeline&lt;/test:text&gt;
- &lt;/test:comment&gt;
- &lt;/gst:element&gt;
- ...
- </programlisting>
- <para>
- To retrieve the custom XML again, you need to attach a signal to
- the GstXML object used to load the XML data. You can then parse your
- custom XML from the XML tree whenever an object is loaded.
- </para>
-
- <para>
- We can extend our previous example with the following piece of
- code.
- </para>
-
- <programlisting>
- xml = gst_xml_new ();
-
- g_signal_connect (G_OBJECT (xml), "object_loaded",
- G_CALLBACK (xml_loaded), xml);
-
- ret = gst_xml_parse_file (xml, "xmlTest.gst", NULL);
- g_assert (ret == TRUE);
- </programlisting>
-
- <para>
- Whenever a new object has been loaded, the xml_loaded function will
- be called. This function looks like:
- </para>
- <programlisting>
-static void
-xml_loaded (GstXML *xml, GstObject *object, xmlNodePtr self, gpointer data)
-{
- xmlNodePtr children = self-&gt;xmlChildrenNode;
-
- while (children) {
- if (!strcmp (children-&gt;name, "comment")) {
- xmlNodePtr nodes = children-&gt;xmlChildrenNode;
-
- while (nodes) {
- if (!strcmp (nodes-&gt;name, "text")) {
- gchar *name = g_strdup (xmlNodeGetContent (nodes));
- g_print ("object %s loaded with comment '%s'\n",
- gst_object_get_name (object), name);
- }
- nodes = nodes-&gt;next;
- }
- }
- children = children-&gt;next;
- }
-}
- </programlisting>
- <para>
- As you can see, you'll get a handle to the GstXML object, the
- newly loaded GstObject and the xmlNodePtr that was used to create
- this object. In the above example we look for our special tag inside
- the XML tree that was used to load the object and we print our
- comment to the console.
- </para>
- </sect1>
</chapter>