From bba6ac4b74ea44b0d39b1f8b6643105e859c8bb7 Mon Sep 17 00:00:00 2001 From: Thomas Vander Stichele Date: Wed, 8 Sep 2004 23:18:55 +0000 Subject: [PATCH] docs/: restructure so that common stuff is shown first Original commit message from CVS: * 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 --- ChangeLog | 18 +++ docs/Makefile.am | 2 +- docs/manual/basics-init.xml | 95 ---------------- docs/manual/elements-api.xml | 155 +++++++++++++++++--------- docs/manual/init-api.xml | 8 +- docs/manual/manual.xml | 33 +++++- docs/manuals.mak | 1 + docs/url.entities | 3 + examples/manual/.gitignore | 15 ++- examples/manual/Makefile.am | 50 +++++++-- examples/manual/extract.pl | 8 ++ tests/old/examples/manual/.gitignore | 15 ++- tests/old/examples/manual/Makefile.am | 50 +++++++-- tests/old/examples/manual/extract.pl | 8 ++ 14 files changed, 271 insertions(+), 190 deletions(-) delete mode 100644 docs/manual/basics-init.xml create mode 100644 docs/url.entities diff --git a/ChangeLog b/ChangeLog index d2ab439f0e..896b944773 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,21 @@ +2004-09-09 Thomas Vander Stichele + + * 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 * docs/gst/tmpl/gstthread.sgml: diff --git a/docs/Makefile.am b/docs/Makefile.am index cf9cfc4aa0..ef24de6b8e 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -18,7 +18,7 @@ DIST_SUBDIRS = gst faq manual pwg libs plugins xsl 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 diff --git a/docs/manual/basics-init.xml b/docs/manual/basics-init.xml deleted file mode 100644 index 0b233fd388..0000000000 --- a/docs/manual/basics-init.xml +++ /dev/null @@ -1,95 +0,0 @@ - - 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 have code to initialize GStreamer that - looks like this: - - - -/* 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 */ - - - 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 be parsed by GStreamer. - - - The popt interface - -You can also use a popt table to initialize your own parameters as shown in the -next example: - - -/* 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 */ - - - 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/elements-api.xml b/docs/manual/elements-api.xml index b51d490fe4..c9c80fe1f3 100644 --- a/docs/manual/elements-api.xml +++ b/docs/manual/elements-api.xml @@ -2,66 +2,106 @@ Elements Creating a GstElement + +The simplest way to create an element is to use + +gst_element_factory_make +. +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 NULL as the name +argument to get a unique, default name. + + +When you don't need the element anymore, you need to unref it using + +gst_object_unref. +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. + + +The following example &EXAFOOT; shows how to create an element named +source from the element factory named +fakesrc. It checks if the creation succeeded. +After checking, it unrefs the element. + + + + +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 */ +]]> + - 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. +gst_element_factory_make is actually a shorthand +for a combination of two functions. +A +GstElement +object is created from a factory. +To create the element, you have to get access to a + +GstElementFactory +object using a unique factory name. +This is done with + +gst_element_factory_find. - 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 fakesrc element, a fake data source. GstElementFactory *factory; - factory = gst_element_factory_find ("mad"); + factory = gst_element_factory_find ("fakesrc"); - 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: GstElement *element; - element = gst_element_factory_create (factory, "decoder"); + element = gst_element_factory_create (factory, "source"); - 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. + +gst_element_factory_create +will use the element factory to create an element with the given 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_object_unref (GST_OBJECT (element)); - GstElement properties - A + A GstElement can have several properties which are implemented using standard GObject properties. The usual GObject methods to query, @@ -69,7 +109,7 @@ are therefore supported. - Every + Every GstElement inherits at least one property of its parent GstObject: the "name" property. This is the name you provide to the @@ -81,16 +121,31 @@ GObject property mechanism as shown below. - GstElement *element; - GValue value = { 0, }; /* initialize the GValue for g_object_get() */ + - g_value_init (&value, G_TYPE_STRING); - g_object_get_property (G_OBJECT (element), "name", &value); - ... +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)); + + return 0; +} + +/* example-end elementget.c */ +]]> Most plugins provide additional properties to provide more information @@ -113,7 +168,7 @@ GstElement signals - A + A GstElement also provides various GObject signals that can be used as a flexible callback mechanism. diff --git a/docs/manual/init-api.xml b/docs/manual/init-api.xml index 0b233fd388..054b7b5198 100644 --- a/docs/manual/init-api.xml +++ b/docs/manual/init-api.xml @@ -12,14 +12,17 @@ well as parse the GStreamer-specific command line options. - A typical program would have code to initialize GStreamer that + A typical program + &EXAFOOT; + would have code to initialize GStreamer that looks like this: + int main (int argc, char *argv[]) @@ -35,6 +38,7 @@ main (int argc, char *argv[]) return 0; } /* example-end init.c */ +]]> Use the GST_VERSION_MAJOR, diff --git a/docs/manual/manual.xml b/docs/manual/manual.xml index a2351956e8..842710842e 100644 --- a/docs/manual/manual.xml +++ b/docs/manual/manual.xml @@ -5,6 +5,18 @@ %image-entities; %version-entities; + +%url-entities; + + + +The code for this example is automatically extracted from +the documentation and built under examples/manual +in the GStreamer tarball. + + +"> @@ -141,7 +153,8 @@ - Basic Concepts + + Basic Concepts We will first describe the basics of @@ -170,7 +183,23 @@ - Basic API + + Basic API + + +This chapter will describe the basics of programming with GStreamer. +Most of the concepts from the previous chapter will be illustrated with code +fragments. + + +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 examples/manual. +Each example has a comment on the first line giving the name of the file +it will be extracted as. + + + &INIT-API; &ELEMENTS-API; diff --git a/docs/manuals.mak b/docs/manuals.mak index dd90317a8d..272debcc58 100644 --- a/docs/manuals.mak +++ b/docs/manuals.mak @@ -85,6 +85,7 @@ $(BUILDDIR)/$(MAIN): $(XML) $(CSS) $(EXTRA_SOURCES) @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 diff --git a/docs/url.entities b/docs/url.entities new file mode 100644 index 0000000000..9bfb50e9e1 --- /dev/null +++ b/docs/url.entities @@ -0,0 +1,3 @@ + + + diff --git a/examples/manual/.gitignore b/examples/manual/.gitignore index 0ebfcdbb44..23514bda5b 100644 --- a/examples/manual/.gitignore +++ b/examples/manual/.gitignore @@ -1,25 +1,24 @@ 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 diff --git a/examples/manual/Makefile.am b/examples/manual/Makefile.am index ffc4f89377..81239ff13e 100644 --- a/examples/manual/Makefile.am +++ b/examples/manual/Makefile.am @@ -10,10 +10,6 @@ else 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) @@ -23,11 +19,41 @@ gnome_CFLAGS = $(GST_OBJ_CFLAGS) $(LIBGNOMEUI_CFLAGS) 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) diff --git a/examples/manual/extract.pl b/examples/manual/extract.pl index 7f6839a42e..578357d28b 100755 --- a/examples/manual/extract.pl +++ b/examples/manual/extract.pl @@ -22,6 +22,8 @@ xml_decode ($) # main my $output = shift @ARGV; +$found = 0; + foreach $file (@ARGV) { open FILE, $file or die "Cannot open file $file"; @@ -31,6 +33,7 @@ foreach $file (@ARGV) if ($line =~ /\/\* example-begin $output \*\//) { print "Extracting $output from $file\n"; + $found = 1; open OUTPUT, ">$output"; print OUTPUT xml_decode ($line); my $example = 1; @@ -50,3 +53,8 @@ foreach $file (@ARGV) } } } +if (!$found) +{ + print "Could not find $output example !\n"; + exit(1); +} diff --git a/tests/old/examples/manual/.gitignore b/tests/old/examples/manual/.gitignore index 0ebfcdbb44..23514bda5b 100644 --- a/tests/old/examples/manual/.gitignore +++ b/tests/old/examples/manual/.gitignore @@ -1,25 +1,24 @@ 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 diff --git a/tests/old/examples/manual/Makefile.am b/tests/old/examples/manual/Makefile.am index ffc4f89377..81239ff13e 100644 --- a/tests/old/examples/manual/Makefile.am +++ b/tests/old/examples/manual/Makefile.am @@ -10,10 +10,6 @@ else 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) @@ -23,11 +19,41 @@ gnome_CFLAGS = $(GST_OBJ_CFLAGS) $(LIBGNOMEUI_CFLAGS) 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) diff --git a/tests/old/examples/manual/extract.pl b/tests/old/examples/manual/extract.pl index 7f6839a42e..578357d28b 100755 --- a/tests/old/examples/manual/extract.pl +++ b/tests/old/examples/manual/extract.pl @@ -22,6 +22,8 @@ xml_decode ($) # main my $output = shift @ARGV; +$found = 0; + foreach $file (@ARGV) { open FILE, $file or die "Cannot open file $file"; @@ -31,6 +33,7 @@ foreach $file (@ARGV) if ($line =~ /\/\* example-begin $output \*\//) { print "Extracting $output from $file\n"; + $found = 1; open OUTPUT, ">$output"; print OUTPUT xml_decode ($line); my $example = 1; @@ -50,3 +53,8 @@ foreach $file (@ARGV) } } } +if (!$found) +{ + print "Could not find $output example !\n"; + exit(1); +}