mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-06-17 05:20:37 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs/: restructure so that common stuff is shown first

Browse source 
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
This commit is contained in:
Thomas Vander Stichele 2004-09-08 23:18:55 +00:00
parent 00ec0495e1
commit bba6ac4b74
14 changed files with 271 additions and 190 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
ChangeLog
View file

@ -1,3 +1,21 @@
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:

2
docs/Makefile.am
View file

@ -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

95
docs/manual/basics-init.xml
View file

@ -1,95 +0,0 @@
<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 &lt;gst/gst.h&gt;
int
main (int argc, char *argv[])
{
guint major, minor, micro;
gst_init (&amp;argc, &amp;argv);
gst_version (&amp;major, &amp;minor, &amp;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 &lt;gst/gst.h&gt;
int
main(int argc, char *argv[])
{
gboolean silent = FALSE;
gchar *savefile = NULL;
struct poptOption options[] = {
{"silent", 's', POPT_ARG_NONE|POPT_ARGFLAG_STRIP, &amp;silent, 0,
"do not output status information", NULL},
{"output", 'o', POPT_ARG_STRING|POPT_ARGFLAG_STRIP, &amp;savefile, 0,
"save xml representation of pipeline to FILE and exit", "FILE"},
POPT_TABLEEND
};
gst_init_with_popt_table (&amp;argc, &amp;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>

155
docs/manual/elements-api.xml
View file

@ -2,66 +2,106 @@
<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.
<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>
<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.
</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,
@ -69,7 +109,7 @@
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
@ -81,16 +121,31 @@
<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 */
element = gst_element_factory_make ("mad", "decoder");
g_object_set (G_OBJECT (element), "name", "mydecoder", NULL);
...
#include <gst/gst.h>
g_value_init (&amp;value, G_TYPE_STRING);
g_object_get_property (G_OBJECT (element), "name", &amp;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 */
]]>
</programlisting>
<para>
Most plugins provide additional properties to provide more information
@ -113,7 +168,7 @@
<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.

8
docs/manual/init-api.xml
View file

@ -12,14 +12,17 @@
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 &lt;gst/gst.h&gt;
#include <gst/gst.h>
int
main (int argc, char *argv[])
@ -35,6 +38,7 @@ main (int argc, char *argv[])
return 0;
}
/* example-end init.c */
]]>
</programlisting>
<para>
Use the <symbol>GST_VERSION_MAJOR</symbol>,

33
docs/manual/manual.xml
View file

@ -5,6 +5,18 @@
%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">
@ -141,7 +153,8 @@
<!-- ############ 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
@ -170,7 +183,23 @@
</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;

1
docs/manuals.mak
View file

@ -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

3
docs/url.entities Normal file
View file

@ -0,0 +1,3 @@
<!-- These entities could be overridden for installed docs -->
<!ENTITY URLAPI "http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/">

15
examples/manual/.gitignore vendored
View file

@ -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

50
examples/manual/Makefile.am
View file

@ -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)

8
examples/manual/extract.pl
View file

@ -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);
}

15
tests/old/examples/manual/.gitignore vendored
View file

@ -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

50
tests/old/examples/manual/Makefile.am
View file

@ -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)

8
tests/old/examples/manual/extract.pl
View file

@ -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);
}