+2004-09-09 Thomas Vander Stichele <thomas at apestaart dot org>
+
+ * docs/Makefile.am:
+ * docs/manual/elements-api.xml:
+ restructure so that common stuff is shown first
+ * docs/manual/init-api.xml:
+ convert to examples
+ * docs/manual/manual.xml:
+ * docs/manuals.mak:
+ * docs/url.entities:
+ link to API on the website, possibly override later in build
+ * examples/manual/.cvsignore:
+ ignore more
+ * examples/manual/Makefile.am:
+ add more examples
+ * examples/manual/extract.pl:
+ error out on failure
+
2004-09-08 Thomas Vander Stichele <thomas at apestaart dot org>
* docs/gst/tmpl/gstthread.sgml:
EXTRA_DIST = \
slides manuals.mak htmlinstall.mak upload.mak \
- image-png image-pdf image-eps version.entities.in
+ image-png image-pdf image-eps url.entities version.entities.in
upload:
@if test "x$(SUBDIRS_DOCS)" != x; then for a in $(SUBDIRS_DOCS); do cd $$a; make upload; cd ..; done; fi
+++ /dev/null
-<chapter id="chapter-initialisation">
- <title>Initializing <application>GStreamer</application></title>
- <para>
- When writing a <application>GStreamer</application> application, you can
- simply include <filename class='headerfile'>gst/gst.h</filename> to get
- access to the library functions.
- </para>
- <para>
- Before the <application>GStreamer</application> libraries can be used,
- <function>gst_init</function> 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.
- </para>
- <para>
- A typical program would have code to initialize GStreamer that
- looks like this:
- </para>
-
- <programlisting>
-/* example-begin init.c */
-
-#include <gst/gst.h>
-
-int
-main (int argc, char *argv[])
-{
- guint major, minor, micro;
-
- gst_init (&argc, &argv);
-
- gst_version (&major, &minor, &micro);
- printf ("This program is linked against GStreamer %d.%d.%d\n",
- major, minor, micro);
-
- return 0;
-}
-/* example-end init.c */
- </programlisting>
- <para>
- Use the <symbol>GST_VERSION_MAJOR</symbol>,
- <symbol>GST_VERSION_MINOR</symbol> and <symbol>GST_VERSION_MICRO</symbol>
- macros to get the <application>GStreamer</application> version you are
- building against, or use the function <function>gst_version</function>
- to get the version your application is linked against.
-<!-- FIXME: include an automatically generated list of these options. -->
- </para>
- <para>
- It is also possible to call the <function>gst_init</function> function
- with two <symbol>NULL</symbol> arguments, in which case no command line
- options will be parsed by <application>GStreamer</application>.
- </para>
- <sect1>
- <title>The popt interface</title>
- <para>
-You can also use a popt table to initialize your own parameters as shown in the
-next example:
- </para>
- <programlisting>
-/* example-begin popt.c */
-
-#include <gst/gst.h>
-
-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);
-
- printf ("Run me with --help to see the Application options appended.\n");
-
- return 0;
-}
-/* example-end popt.c */
- </programlisting>
- <para>
- As shown in this fragment, you can use a <ulink
- url="http://developer.gnome.org/doc/guides/popt/"
- type="http">popt</ulink> table to define your application-specific
- command line options, and pass this table to the
- function <function>gst_init_with_popt_table</function>. Your
- application options will be parsed in addition to the standard
- <application>GStreamer</application> options.
- </para>
- </sect1>
-
-</chapter>
<title>Elements</title>
<sect1 id="section-elements-create">
<title>Creating a GstElement</title>
+ <para>
+The simplest way to create an element is to use
+<ulink type="http"
+ url="&URLAPI;GstElementFactory.html#gst-element-factory-make">
+<function>gst_element_factory_make</function>
+</ulink>.
+This function takes a factory name and an element name for the newly created
+element.
+ 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 <symbol>NULL</symbol> as the name
+argument to get a unique, default name.
+ </para>
+ <para>
+When you don't need the element anymore, you need to unref it using
+<ulink type="http"
+ url="&URLAPI;GstObject.html#gst-object-unref">
+<function>gst_object_unref</function></ulink>.
+This decreases the reference count for the element by 1. An element has a
+refcount of 1 when it gets created. An element gets destroyed completely
+when the refcount is decreased to 0.
+ </para>
+ <para>
+The following example &EXAFOOT; shows how to create an element named
+<emphasis>source</emphasis> from the element factory named
+<emphasis>fakesrc</emphasis>. It checks if the creation succeeded.
+After checking, it unrefs the element.
+ </para>
+ <programlisting>
+<![CDATA[
+/* example-begin elementmake.c */
+
+#include <gst/gst.h>
+
+int
+main (int argc, char *argv[])
+{
+ GstElement *element;
+
+ gst_init (&argc, &argv);
+
+ element = gst_element_factory_make ("fakesrc", "source");
+
+ if (!element) {
+ g_error ("Could not create an element from 'fakesrc' factory.\n");
+ }
+
+ gst_object_unref (GST_OBJECT (element));
+
+ return 0;
+}
+
+/* example-end elementmake.c */
+]]>
+ </programlisting>
<para>
- A <ulink type="http"
- url="../../gstreamer/html/GstElement.html"><classname>GstElement</classname></ulink>
- object is created from a factory.
- To create an element, you have to get access to a
- <ulink type="http" url="../../gstreamer/html/GstElementFactory.html">
- <classname>GstElementFactory</classname></ulink> object using a unique
- factory name.
+<function>gst_element_factory_make</function> is actually a shorthand
+for a combination of two functions.
+A
+<ulink type="http"
+ url="&URLAPI;GstElement.html"><classname>GstElement</classname></ulink>
+object is created from a factory.
+To create the element, you have to get access to a
+<ulink type="http" url="&URLAPI;GstElementFactory.html">
+<classname>GstElementFactory</classname></ulink>
+object using a unique factory name.
+This is done with
+<ulink type="http"
+ url="&URLAPI;GstElementFactory.html#gst-element-factory-find">
+<function>gst_element_factory_find</function></ulink>.
</para>
<para>
- The following code example is used to get a factory that can be used
- to create the 'mad' element, an mp3 decoder.
+The following code fragment is used to get a factory that can be used
+to create the <emphasis>fakesrc</emphasis> element, a fake data source.
</para>
<programlisting>
GstElementFactory *factory;
- factory = gst_element_factory_find ("mad");
+ factory = gst_element_factory_find ("fakesrc");
</programlisting>
<para>
- Once you have the handle to the element factory, you can create a
- real element with the following code fragment:
+Once you have the handle to the element factory, you can create a
+real element with the following code fragment:
</para>
<programlisting>
GstElement *element;
- element = gst_element_factory_create (factory, "decoder");
+ element = gst_element_factory_create (factory, "source");
</programlisting>
<para>
- <function>gst_element_factory_create</function> 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 <symbol>NULL</symbol> as the name
- argument to get a unique, default name.
- </para>
- <para>
- 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.
+<ulink type="http"
+ url="&URLAPI;GstElementFactory.html#gst-element-factory-create">
+<function>gst_element_factory_create</function></ulink>
+will use the element factory to create an element with the given name.
</para>
- <programlisting>
- GstElement *element;
-
- element = gst_element_factory_make ("mad", "decoder");
- </programlisting>
- <para>
- When you don't need the element anymore, you need to unref it, as shown in the following
- example.
- </para>
- <programlisting>
- GstElement *element;
-
- ...
- gst_object_unref (GST_OBJECT (element));
- </programlisting>
</sect1>
<sect1 id="section-elements-properties">
<title>GstElement properties</title>
<para>
- A <ulink type="http" url="../../gstreamer/html/GstElement.html">
+ A <ulink type="http" url="&URLAPI;GstElement.html">
<classname>GstElement</classname></ulink> can have several properties
which are implemented using standard <classname>GObject</classname>
properties. The usual <classname>GObject</classname> methods to query,
are therefore supported.
</para>
<para>
- Every <ulink type="http" url="../../gstreamer/html/GstElementFactory.html">
+ Every <ulink type="http" url="&URLAPI;GstElementFactory.html">
<classname>GstElement</classname></ulink> inherits at least
one property of its parent <classname>GstObject</classname>:
the "name" property. This is the name you provide to the
<classname>GObject</classname> property mechanism as shown below.
</para>
<programlisting>
- GstElement *element;
- GValue value = { 0, }; /* initialize the GValue for g_object_get() */
+<![CDATA[
+/* example-begin elementget.c */
+
+#include <gst/gst.h>
+
+int
+main (int argc, char *argv[])
+{
+ GstElement *element;
+ GValue value = { 0, }; /* initialize the GValue for g_object_get() */
+
+ gst_init (&argc, &argv);
+ element = gst_element_factory_make ("fakesrc", "source");
+ g_object_set (G_OBJECT (element), "name", "mysource", NULL);
+
+ g_value_init (&value, G_TYPE_STRING);
+ g_object_get_property (G_OBJECT (element), "name", &value);
+
+ g_print ("The name of the source is '%s'.\n", g_value_get_string (&value));
- element = gst_element_factory_make ("mad", "decoder");
- g_object_set (G_OBJECT (element), "name", "mydecoder", NULL);
- ...
+ return 0;
+}
- g_value_init (&value, G_TYPE_STRING);
- g_object_get_property (G_OBJECT (element), "name", &value);
- ...
+/* example-end elementget.c */
+]]>
</programlisting>
<para>
Most plugins provide additional properties to provide more information
<sect1 id="section-elements-signals">
<title>GstElement signals</title>
<para>
- A <ulink type="http" url="../../gstreamer/html/GstElementFactory.html">
+ A <ulink type="http" url="&URLAPI;gstreamer/html/GstElementFactory.html">
<classname>GstElement</classname></ulink> also provides various
<classname>GObject</classname> signals that can be used as a flexible
callback mechanism.
well as parse the GStreamer-specific command line options.
</para>
<para>
- A typical program would have code to initialize GStreamer that
+ A typical program
+ &EXAFOOT;
+ would have code to initialize GStreamer that
looks like this:
</para>
<programlisting>
+<![CDATA[
/* example-begin init.c */
-#include <gst/gst.h>
+#include <gst/gst.h>
int
main (int argc, char *argv[])
return 0;
}
/* example-end init.c */
+]]>
</programlisting>
<para>
Use the <symbol>GST_VERSION_MAJOR</symbol>,
%image-entities;
<!ENTITY % version-entities SYSTEM "version.entities">
%version-entities;
+<!ENTITY % url-entities SYSTEM "url.entities">
+%url-entities;
+
+<!ENTITY EXAFOOT "
+<footnote>
+<para>
+The code for this example is automatically extracted from
+the documentation and built under <filename>examples/manual</filename>
+in the GStreamer tarball.
+</para>
+</footnote>
+">
<!-- Part 1: Overview -->
<!ENTITY INTRO SYSTEM "intro.xml">
<!-- ############ Basic concepts - part ############# -->
- <part id="part-basic-concepts"><title>Basic Concepts</title>
+ <part id="part-basic-concepts">
+ <title>Basic Concepts</title>
<partintro>
<para>
We will first describe the basics of
</part>
<!-- ############ Basic API - part ############# -->
- <part id="part-basic-api"><title>Basic API</title>
+ <part id="part-basic-api">
+ <title>Basic API</title>
+ <partintro>
+ <para>
+This chapter will describe the basics of programming with GStreamer.
+Most of the concepts from the previous chapter will be illustrated with code
+fragments.
+ </para>
+ <para>
+Most of the code examples in this manual are automatically extracted as part
+of the build process of the GStreamer tarball. After building GStreamer from
+source, you will find the examples in <filename>examples/manual</filename>.
+Each example has a comment on the first line giving the name of the file
+it will be extracted as.
+ </para>
+ </partintro>
+
&INIT-API;
&ELEMENTS-API;
@for a in $(XML); do cp $(srcdir)/$$a $(BUILDDIR); done
@for a in $(CSS); do cp $(srcdir)/$$a $(BUILDDIR); done
@cp ../version.entities $(BUILDDIR)
+ @cp ../url.entities $(BUILDDIR)
html/index.html: $(BUILDDIR)/$(MAIN) $(PNG_BUILT) $(FIG_SRC)
@make check-local
--- /dev/null
+<!-- These entities could be overridden for installed docs -->
+<!ENTITY URLAPI "http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/">
+
Makefile
Makefile.in
+*.c
*.o
*.lo
*.la
.deps
.libs
+
dynamic
-dynamic.c
+elementget
+elementmake
gnome
-gnome.c
helloworld
-helloworld.c
helloworld2
-helloworld2.c
+init
+popt
queue
-queue.c
threads
-threads.c
+
xml-mp3
-xml-mp3.c
-xml.c
xml
xmlTest.gst
README
GST_LOADSAVE_SRC = xml-mp3
endif
-EXAMPLES = dynamic $(GNOME) helloworld init popt queue threads $(GST_LOADSAVE_SRC)
-noinst_PROGRAMS = $(EXAMPLES)
-
-LDADD = $(GST_OBJ_LIBS)
INCLUDES = $(GST_OBJ_CFLAGS)
#dynamic_LDADD = $(GST_OBJ_LIBS) $(LIBGNOMEUI_LIBS)
EXTRA_DIST = extract.pl
-# for some reason specifying %.c runs us into trouble when running make
-# clean, it starts looking for things like mostlyclean-am.c, please
-# help me fix that so we don't need to specify all sources here
-# also, it's a bit irritating that right now a change in any xml file
-# triggers a rebuild of all examples
-#%.c:
-dynamic.c gnome.c helloworld.c init.c popt.c queue.c threads.c xml-mp3.c: $(top_srcdir)/docs/manual/*.xml
- $(PERL_PATH) $(srcdir)/extract.pl $@ $(top_srcdir)/docs/manual/*.xml
+EXAMPLES = \
+ dynamic $(GNOME) factorymake helloworld \
+ init popt queue threads $(GST_LOADSAVE_SRC)
+
+dynamic.c: $(top_srcdir)/docs/manual/dynamic.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+elementmake.c elementget.c: $(top_srcdir)/docs/manual/elements-api.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+gnome.c: $(top_srcdir)/docs/manual/gnome.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+helloworld.c: $(top_srcdir)/docs/manual/helloworld.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+init.c popt.c: $(top_srcdir)/docs/manual/init-api.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+queue.c: $(top_srcdir)/docs/manual/queues.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+threads.c: $(top_srcdir)/docs/manual/threads.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+xml-mp3.c: $(top_srcdir)/docs/manual/xml.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+# we use some of the examples as testsuite apps, to verify that
+# they actually run
+include $(top_srcdir)/testsuite/Rules
+
+tests_pass = elementmake elementget init popt $(GNOME)
+tests_fail =
+tests_ignore =
+
+noinst_PROGRAMS = $(EXAMPLES)
+LDADD = $(GST_OBJ_LIBS)
# main
my $output = shift @ARGV;
+$found = 0;
+
foreach $file (@ARGV)
{
open FILE, $file or die "Cannot open file $file";
if ($line =~ /\/\* example-begin $output \*\//)
{
print "Extracting $output from $file\n";
+ $found = 1;
open OUTPUT, ">$output";
print OUTPUT xml_decode ($line);
my $example = 1;
}
}
}
+if (!$found)
+{
+ print "Could not find $output example !\n";
+ exit(1);
+}
Makefile
Makefile.in
+*.c
*.o
*.lo
*.la
.deps
.libs
+
dynamic
-dynamic.c
+elementget
+elementmake
gnome
-gnome.c
helloworld
-helloworld.c
helloworld2
-helloworld2.c
+init
+popt
queue
-queue.c
threads
-threads.c
+
xml-mp3
-xml-mp3.c
-xml.c
xml
xmlTest.gst
README
GST_LOADSAVE_SRC = xml-mp3
endif
-EXAMPLES = dynamic $(GNOME) helloworld init popt queue threads $(GST_LOADSAVE_SRC)
-noinst_PROGRAMS = $(EXAMPLES)
-
-LDADD = $(GST_OBJ_LIBS)
INCLUDES = $(GST_OBJ_CFLAGS)
#dynamic_LDADD = $(GST_OBJ_LIBS) $(LIBGNOMEUI_LIBS)
EXTRA_DIST = extract.pl
-# for some reason specifying %.c runs us into trouble when running make
-# clean, it starts looking for things like mostlyclean-am.c, please
-# help me fix that so we don't need to specify all sources here
-# also, it's a bit irritating that right now a change in any xml file
-# triggers a rebuild of all examples
-#%.c:
-dynamic.c gnome.c helloworld.c init.c popt.c queue.c threads.c xml-mp3.c: $(top_srcdir)/docs/manual/*.xml
- $(PERL_PATH) $(srcdir)/extract.pl $@ $(top_srcdir)/docs/manual/*.xml
+EXAMPLES = \
+ dynamic $(GNOME) factorymake helloworld \
+ init popt queue threads $(GST_LOADSAVE_SRC)
+
+dynamic.c: $(top_srcdir)/docs/manual/dynamic.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+elementmake.c elementget.c: $(top_srcdir)/docs/manual/elements-api.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+gnome.c: $(top_srcdir)/docs/manual/gnome.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+helloworld.c: $(top_srcdir)/docs/manual/helloworld.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+init.c popt.c: $(top_srcdir)/docs/manual/init-api.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+queue.c: $(top_srcdir)/docs/manual/queues.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+threads.c: $(top_srcdir)/docs/manual/threads.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+xml-mp3.c: $(top_srcdir)/docs/manual/xml.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ $<
+
+# we use some of the examples as testsuite apps, to verify that
+# they actually run
+include $(top_srcdir)/testsuite/Rules
+
+tests_pass = elementmake elementget init popt $(GNOME)
+tests_fail =
+tests_ignore =
+
+noinst_PROGRAMS = $(EXAMPLES)
+LDADD = $(GST_OBJ_LIBS)
# main
my $output = shift @ARGV;
+$found = 0;
+
foreach $file (@ARGV)
{
open FILE, $file or die "Cannot open file $file";
if ($line =~ /\/\* example-begin $output \*\//)
{
print "Extracting $output from $file\n";
+ $found = 1;
open OUTPUT, ">$output";
print OUTPUT xml_decode ($line);
my $example = 1;
}
}
}
+if (!$found)
+{
+ print "Could not find $output example !\n";
+ exit(1);
+}
projects / platform / upstream / gstreamer.git / commitdiff