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

Updates and additions to the manual

Browse source 
Original commit message from CVS:
Updates and additions to the manual
This commit is contained in:
Wim Taymans 2001-01-04 23:35:50 +00:00
parent df81ae1765
commit ea3715a1b4
13 changed files with 349 additions and 120 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/manual/Makefile.am
View file

@ -6,6 +6,7 @@ sgml_files = gstreamer-manual.sgml \
bins.sgml \
buffers.sgml \
components.sgml \
pads.sgml \
connections.sgml \
cothreads.sgml \
dynamic.sgml \
@ -27,6 +28,7 @@ sgml_files = gstreamer-manual.sgml \
xml.sgml
fig_files = bin-element.fig \
bin-element-ghost.fig \
connected-elements.fig \
filter-element-multi.fig \
filter-element.fig \
@ -39,6 +41,7 @@ fig_files = bin-element.fig \
thread.fig
eps_files = images/bin-element.eps \
images/bin-element-ghost.eps \
images/connected-elements.eps \
images/filter-element-multi.eps \
images/filter-element.eps \
@ -51,6 +54,7 @@ eps_files = images/bin-element.eps \
images/thread.eps
png_files = images/bin-element.png \
images/bin-element-ghost.png \
images/connected-elements.png \
images/filter-element-multi.png \
images/filter-element.png \

47
docs/manual/bin-element-ghost.fig Normal file
View file

@ -0,0 +1,47 @@
#FIG 3.2
Landscape
Center
Inches
Letter
100.00
Single
-2
1200 2
2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5
3975 3600 4725 3600 4725 4125 3975 4125 3975 3600
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
2775 2775 4725 2775 4725 4425 2775 4425 2775 2775
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
5400 2775 7350 2775 7350 4425 5400 4425 5400 2775
2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
8025 2775 9975 2775 9975 4425 8025 4425 8025 2775
2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5
5400 3600 6150 3600 6150 4125 5400 4125 5400 3600
2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5
8025 3600 8775 3600 8775 4125 8025 4125 8025 3600
2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5
6600 3600 7350 3600 7350 4125 6600 4125 6600 3600
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 90.00 120.00
4575 3750 5400 3750
2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
1 1 1.00 90.00 120.00
7200 3750 8025 3750
2 2 0 1 0 7 100 0 -1 0.000 0 0 -1 0 0 5
1950 1950 10575 1950 10575 4800 1950 4800 1950 1950
2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5
1950 4125 2700 4125 2700 4650 1950 4650 1950 4125
2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5
2775 3600 3525 3600 3525 4125 2775 4125 2775 3600
2 1 2 1 0 7 50 0 -1 3.000 0 0 -1 0 0 2
2550 4350 2850 3825
4 0 0 50 0 16 12 0.0000 4 105 255 4200 3975 src\001
4 0 0 50 0 16 12 0.0000 4 135 330 5550 3975 sink\001
4 0 0 50 0 16 12 0.0000 4 135 330 8175 3975 sink\001
4 0 0 50 0 16 12 0.0000 4 105 255 6825 3975 src\001
4 0 0 50 0 16 12 0.0000 4 135 750 5625 3075 element2\001
4 0 0 50 0 16 12 0.0000 4 135 750 8250 3075 element3\001
4 0 0 50 0 16 12 0.0000 4 135 750 3000 3075 element1\001
4 0 0 50 0 16 12 0.0000 4 135 255 2175 2250 bin\001
4 0 0 50 0 16 12 0.0000 4 135 330 2925 3975 sink\001
4 0 0 50 0 16 12 0.0000 4 135 330 2025 4500 sink\001

30
docs/manual/bins.sgml
View file

@ -2,7 +2,7 @@
<title>Bins</title>
<para>
A Bin is a container element. You can add elements to a bin. Since a bin is
an element itself, it can also be added to another bin.
an <classname>GstElement</classname> itself, it can also be added to another bin.
</para>
<para>
Bins allow you to combine connected elements into one logical element. You do
@ -12,7 +12,8 @@
</para>
<para>
The bin will also manage the elements contained in it. It will figure out how
the data will flow in the bin and generate an optimal plan for that data flow.
the data will flow in the bin and generate an optimal plan for that data flow. Plan
generation is one of the most complicated procedures in GStreamer.
</para>
<figure float="1" id="sec-bin-img">
@ -62,5 +63,30 @@
// stop
gst_element_set_state(GST_ELEMENT(mp3player),GST_STATE_NULL);
</programlisting>
Custom bins can be created with a plugin or an XML description.
</para>
<sect1 id="sec-bin-ghostpads">
<title>Ghostpads</title>
<para>
You can see from figure ... how a bin has no pads of its own. This is where Ghostpads
come into play.
</para>
<para>
A ghostpad 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.
</para>
<figure float="1" id="sec-bin-ghost-img">
<title>Visualisation of a <classname>GstBin</classname> element with a ghostpad</title>
<graphic fileref="images/bin-element-ghost" format="png"></graphic>
</figure>
<para>
Above is a representation of a ghostpad. the sinkpad of element one is now also a pad
of the bin.
</para>
</sect1>
</chapter>

29
docs/manual/elements.sgml
View file

@ -13,25 +13,27 @@
This means that a lot of functions you are going to use operate on this object.
</para>
<para>
We will first describe the three most important types of elements that you are
going to use. They are the Source, Filter and Sink elements.
You will see that those elements have pads. These are the elements
connections with the 'outside' world. Depending on the number and direction of
the pads, we can see three types of elements: source, filter and sink element.
</para>
<para>
You will also see that those elements have pads. These are the elements
connections with the 'outside' world.
These three types are all the same GstElement object, they just differ in how
the pads are.
</para>
<sect2 id="sec-elements-src">
<title>GStreamer source elements (<classname>GstSrc</classname>)</title>
<title>GStreamer source elements</title>
<para>
This element will generate data that will be used by the pipeline. It is
typically a file or an audio source.
</para>
<para>
Below you see how we will visualize the <classname>GstSrc</classname> element.
Below you see how we will visualize the element.
We always draw a src pad to the right of the element.
</para>
<figure float="1" id="sec-element-srcimg">
<title>Visualisation of a <classname>GstSrc</classname> element</title>
<title>Visualisation of a source element</title>
<graphic fileref="images/src-element" format="png"></graphic>
</figure>
<para>
@ -39,10 +41,10 @@
this in the figure because it only has a src pad. A src pad can only
generate buffers.
</para>
</sect2>
<sect2 id="sec-elements-filter">
<title>GStreamer filter elements (<classname>GstFilter</classname>)</title>
<title>GStreamer filter elements</title>
<para>
Filter elements both have an input and an output pad. They operate on data
they receive in the sink pad and send the result to the src pad.
@ -56,7 +58,7 @@
streams) and one output pad.
</para>
<figure float="1" id="sec-element-filterimg">
<title>Visualisation of a <classname>GstFilter</classname> element</title>
<title>Visualisation of a filter element</title>
<graphic fileref="images/filter-element" format="png"></graphic>
</figure>
<para>
@ -65,7 +67,7 @@
of the element.
</para>
<figure float="1" id="sec-element-multifilterimg">
<title>Visualisation of a <classname>GstFilter</classname> element with
<title>Visualisation of a filter element with
more than one output pad</title>
<graphic fileref="images/filter-element-multi" format="png"></graphic>
</figure>
@ -79,17 +81,16 @@
</sect2>
<sect2 id="sec-elements-sink">
<title>GStreamer sink elements (<classname>GstSink</classname>)</title>
<title>GStreamer sink elements</title>
<para>
This element accepts data but will not generate any new data. A sink element
is typically a file on disk, a soundcard, a display,... It is presented as
below:
</para>
<figure float="1" id="sec-element-sinkimg">
<title>Visualisation of a <classname>GstSink</classname> element</title>
<title>Visualisation of a sink element</title>
<graphic fileref="images/sink-element" format="png"></graphic>
</figure>
</sect2>
</sect1>
</chapter>

16
docs/manual/factories.sgml
View file

@ -36,8 +36,8 @@
an MP3 decoder element.
</para>
<para>
We have to introduce the concept of MIME types added to the source and
sink pads.
We have to introduce the concept of MIME types and capabilities
added to the source and sink pads.
</para>
</sect1>
@ -51,7 +51,7 @@
</para>
<para>
A MIME (Multipurpose Internet Mail Extension) types are a set of
string that donote a certain type of data. examples include:
string that denote a certain type of data. examples include:
<itemizedlist>
<listitem>
<para>
@ -110,9 +110,8 @@
<sect1>
<title>GStreamer types</title>
<para>
GStreamer assigns a unique number to all registered MIME types. It
also maintains a list of all elements that either uses this type
as a source or as a sink. GStreamer also keeps a reference to
GStreamer assigns a unique number to all registered MIME types.
GStreamer also keeps a reference to
a function that can be used to determine if a given buffer is of
the given MIME type.
</para>
@ -126,7 +125,7 @@
<classname>GstType</classname> is like:
</para>
<programlisting>
typedef gboolean (*GstTypeFindFunc) (GstBuffer *buf,gpointer *priv);
typedef GstCaps (*GstTypeFindFunc) (GstBuffer *buf,gpointer *priv);
typedef struct _GstType GstType;
@ -137,9 +136,6 @@ struct _GstType {
gchar *exts; /* space-delimited list of extensions */
GstTypeFindFunc typefindfunc; /* typefind function */
GList *srcs; /* list of src objects for this type */
GList *sinks; /* list of sink objects for type */
};
</programlisting>
<para>

28
docs/manual/goals.sgml
View file

@ -18,12 +18,18 @@
<itemizedlist>
<listitem>
<para>
The application programmer who wants to build a media pipeline.
The application programmer who wants to build a media pipeline.
The programmer can use an extensive set of powerfull tools to create
media pipelines without writing a single line of code. Performing
complex media manipulations becomes very easy.
</para>
</listitem>
<listitem>
<para>
The plugin programmer.
The plugin programmer. Plugin programmers are provided a clean and
simple API to create self contained plugins. An extensive debugging
and tracing mechanism has been integrated. GStreamer also comes with
an extensive set of real-life plugins that serve as an example too.
</para>
</listitem>
</itemizedlist>
@ -36,7 +42,11 @@
with GTK+ will be confortable with GStreamer.
</para>
<para>
GStreamer uses the mechanisems of signals and object arguments.
GStreamer uses the mechanism of signals and object arguments.
</para>
<para>
All objects can be queried at runtime for their various properties and
capabilities.
</para>
</sect2>
@ -58,6 +68,11 @@
properties of the plugin can be set using the GtkObject arguments, there
is no need to have any header files installed for the plugins.
</para>
<para>
Special care has been taking into making the plugin completely self
contained. This is in the operations, specification of the capabilities
of the plugin and properties.
</para>
</sect2>
<sect2 id="sec-goals-performance">
@ -103,6 +118,13 @@
HW acceleration is possible by writing a specialized plugin.
</para>
</listitem>
<listitem>
<para>
Uses a plugin registry with the specifications of the plugins so
that the plugin loading can be delayed until the plugin is actually
used.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>

3
docs/manual/gstreamer-manual.sgml
View file

@ -4,6 +4,7 @@
<!ENTITY GOALS SYSTEM "goals.sgml">
<!ENTITY ELEMENTS SYSTEM "elements.sgml">
<!ENTITY PADS SYSTEM "pads.sgml">
<!ENTITY CONNECTIONS SYSTEM "connections.sgml">
<!ENTITY BINS SYSTEM "bins.sgml">
<!ENTITY BUFFERS SYSTEM "buffers.sgml">
@ -97,6 +98,8 @@
<!-- ############ Basic concepts - chapter ############# -->
&ELEMENTS;
&PADS;
&CONNECTIONS;
&BINS;

169
docs/manual/helloworld.sgml
View file

@ -1,7 +1,7 @@
<chapter id="cha-hello">
<title>Your first application</title>
<para>
This chapter describes the most rudimentary aspects of a GStreamer application,
This chapter describes the most rudimentary aspects of a <application>GStreamer</application> application,
including initializing the libraries, creating elements, packing them into
a pipeline and playing, pause and stop the pipeline.
</para>
@ -10,7 +10,7 @@
<title>Hello world</title>
<para>
We will create a simple first application. In fact it will be a complete
MP3 player, using standard GStreamer components. The player will read from
MP3 player, using standard <application>GStreamer</application> components. The player will read from
a file that is given as the first argument of the program.
</para>
@ -22,77 +22,75 @@
gboolean playing;
/* eos will be called when the src element has an end of stream */
void eos(GstSrc *src)
void
eos (GstSrc *src)
{
g_print("have eos, quitting\n");
g_print ("have eos, quitting\n");
playing = FALSE;
}
int main(int argc,char *argv[])
int
main (int argc, char *argv[])
{
GstElement *bin, *disksrc, *parse, *decoder, *audiosink;
gst_init(&amp;argc, &amp;argv);
if (argc != 2) {
g_print("usage: %s &lt;filename&gt;n", argv[0]);
exit(-1);
g_print ("usage: %s &lt;filename&gt;n", argv[0]);
exit (-1);
}
gst_init(&amp;argc,&amp;argv);
/* create a new bin to hold the elements */
bin = gst_bin_new("bin");
bin = gst_bin_new ("bin");
/* create a disk reader */
disksrc = gst_elementfactory_make("disksrc", "disk_source");
gtk_object_set(GTK_OBJECT(disksrc),"location", argv[1],NULL);
gtk_signal_connect(GTK_OBJECT(disksrc),"eos",
GTK_SIGNAL_FUNC(eos),NULL);
disksrc = gst_elementfactory_make ("disksrc", "disk_source");
gtk_object_set (GTK_OBJECT (disksrc),"location", argv[1], NULL);
gtk_signal_connect (GTK_OBJECT (disksrc), "eos",
GTK_SIGNAL_FUNC (eos), NULL);
/* now it's time to get the parser */
parse = gst_elementfactory_make("mp3parse","parse");
decoder = gst_elementfactory_make("mpg123","decoder");
parse = gst_elementfactory_make ("mp3parse", "parse");
decoder = gst_elementfactory_make ("mpg123", "decoder");
/* and an audio sink */
audiosink = gst_elementfactory_make("audiosink", "play_audio");
audiosink = gst_elementfactory_make ("audiosink", "play_audio");
/* add objects to the main pipeline */
gst_bin_add(GST_BIN(bin), disksrc);
gst_bin_add(GST_BIN(bin), parse);
gst_bin_add(GST_BIN(bin), decoder);
gst_bin_add(GST_BIN(bin), audiosink);
gst_bin_add (GST_BIN (bin), disksrc);
gst_bin_add (GST_BIN (bin), parse);
gst_bin_add (GST_BIN (bin), decoder);
gst_bin_add (GST_BIN (bin), audiosink);
/* connect src to sink */
gst_pad_connect(gst_element_get_pad(disksrc,"src"),
gst_element_get_pad(parse,"sink"));
gst_pad_connect(gst_element_get_pad(parse,"src"),
gst_element_get_pad(decoder,"sink"));
gst_pad_connect(gst_element_get_pad(decoder,"src"),
gst_element_get_pad(audiosink,"sink"));
gst_pad_connect (gst_element_get_pad (disksrc, "src"),
gst_element_get_pad (parse, "sink"));
gst_pad_connect (gst_element_get_pad (parse, "src"),
gst_element_get_pad (decoder, "sink"));
gst_pad_connect (gst_element_get_pad (decoder, "src"),
gst_element_get_pad (audiosink, "sink"));
/* find out how to handle this bin */
gst_bin_create_plan(GST_BIN(bin));
/* make it ready */
gst_element_set_state(bin, GST_STATE_READY);
/* start playing */
gst_element_set_state(bin, GST_STATE_PLAYING);
gst_element_set_state (bin, GST_STATE_PLAYING);
playing = TRUE;
while (playing) {
gst_bin_iterate(GST_BIN(bin));
gst_bin_iterate (GST_BIN (bin));
}
/* stop the bin */
gst_element_set_state(bin, GST_STATE_NULL);
gst_element_set_state (bin, GST_STATE_NULL);
gst_object_destroy(GST_OBJECT(audiosink));
gst_object_destroy(GST_OBJECT(parse));
gst_object_destroy(GST_OBJECT(decoder));
gst_object_destroy(GST_OBJECT(disksrc));
gst_object_destroy(GST_OBJECT(bin));
gst_object_destroy (GST_OBJECT (audiosink));
gst_object_destroy (GST_OBJECT (parse));
gst_object_destroy (GST_OBJECT (decoder));
gst_object_destroy (GST_OBJECT (disksrc));
gst_object_destroy (GST_OBJECT (bin));
exit(0);
exit (0);
}
</programlisting>
@ -102,7 +100,7 @@ int main(int argc,char *argv[])
</para>
<para>
The first thing you have to do is to include the standard GStreamer headers and
The first thing you have to do is to include the standard <application>GStreamer</application> headers and
initialize the framework.
</para>
<programlisting>
@ -111,10 +109,11 @@ int main(int argc,char *argv[])
...
int main(int argc,char *argv[])
int
main (int argc, char *argv[])
{
...
gst_init(&amp;argc,&amp;argv);
gst_init(&amp;argc, &amp;argv);
...
</programlisting>
@ -136,8 +135,11 @@ int main(int argc,char *argv[])
</para>
<programlisting>
/* create a new bin to hold the elements */
bin = gst_bin_new("bin");
bin = gst_bin_new ("bin");
</programlisting>
<para>
We use the standard constructor for a bin: gst_bin_new ("
</para>
<para>
We then create a disk source element. The disk source element is able to
@ -146,10 +148,10 @@ int main(int argc,char *argv[])
</para>
<programlisting>
/* create a disk reader */
disksrc = gst_elementfactory_make("disksrc", "disk_source");
gtk_object_set(GTK_OBJECT(disksrc),"location", argv[1],NULL);
gtk_signal_connect(GTK_OBJECT(disksrc),"eos",
GTK_SIGNAL_FUNC(eos),NULL);
disksrc = gst_elementfactory_make ("disksrc", "disk_source");
gtk_object_set (GTK_OBJECT (disksrc),"location", argv[1], NULL);
gtk_signal_connect (GTK_OBJECT (disksrc), "eos",
GTK_SIGNAL_FUNC (eos), NULL);
</programlisting>
<para>
We also connected the eos signal to our function. When the
@ -168,16 +170,17 @@ gboolean playing;
...
/* eos will be called when the src element has an end of stream */
void eos(GstSrc *src)
void
eos (GstSrc *src)
{
g_print("have eos, quitting\n");
g_print ("have eos, quitting\n");
playing = FALSE;
}
</programlisting>
<para>
We now create the MP3 decoder element. GStreamer requires you
We now create the MP3 decoder element. <application>GStreamer</application> requires you
to put a parser in front of the decoder. This parser will
cut the raw data from the disk source into MP3 frames
suitable for the decoder. In the advanced concepts chapter we will
@ -185,8 +188,8 @@ void eos(GstSrc *src)
</para>
<programlisting>
/* now it's time to get the parser */
parse = gst_elementfactory_make("mp3parse","parse");
decoder = gst_elementfactory_make("mpg123","decoder");
parse = gst_elementfactory_make ("mp3parse", "parse");
decoder = gst_elementfactory_make ("mpg123", "decoder");
</programlisting>
<para>
gst_elementfactory_make() takes two arguments: a string that will
@ -202,7 +205,7 @@ void eos(GstSrc *src)
</para>
<programlisting>
/* and an audio sink */
audiosink = gst_elementfactory_make("audiosink", "play_audio");
audiosink = gst_elementfactory_make ("audiosink", "play_audio");
</programlisting>
<para>
@ -210,10 +213,10 @@ void eos(GstSrc *src)
</para>
<programlisting>
/* add objects to the main pipeline */
gst_bin_add(GST_BIN(bin), disksrc);
gst_bin_add(GST_BIN(bin), parse);
gst_bin_add(GST_BIN(bin), decoder);
gst_bin_add(GST_BIN(bin), audiosink);
gst_bin_add (GST_BIN (bin), disksrc);
gst_bin_add (GST_BIN (bin), parse);
gst_bin_add (GST_BIN (bin), decoder);
gst_bin_add (GST_BIN (bin), audiosink);
</programlisting>
<para>
@ -221,12 +224,12 @@ void eos(GstSrc *src)
</para>
<programlisting>
/* connect src to sink */
gst_pad_connect(gst_element_get_pad(disksrc,"src"),
gst_element_get_pad(parse,"sink"));
gst_pad_connect(gst_element_get_pad(parse,"src"),
gst_element_get_pad(decoder,"sink"));
gst_pad_connect(gst_element_get_pad(decoder,"src"),
gst_element_get_pad(audiosink,"sink"));
gst_pad_connect (gst_element_get_pad (disksrc, "src"),
gst_element_get_pad (parse, "sink"));
gst_pad_connect (gst_element_get_pad (parse, "src"),
gst_element_get_pad (decoder, "sink"));
gst_pad_connect (gst_element_get_pad (decoder, "src"),
gst_element_get_pad (audiosink, "sink"));
</programlisting>
<para>
@ -238,32 +241,20 @@ void eos(GstSrc *src)
<graphic fileref="images/hello-world" format="png"></graphic>
</figure>
<para>
Before we can run it, we have to instruct the bin to analyse its contents
and come up with a plan to handle the media streams.
</para>
<programlisting>
/* find out how to handle this bin */
gst_bin_create_plan(GST_BIN(bin));
</programlisting>
<para>
Everything is now set up to start the streaming. We use the following
statements to change the state of the bin:
</para>
<programlisting>
/* make it ready */
gst_element_set_state(bin, GST_STATE_READY);
/* start playing */
gst_element_set_state(bin, GST_STATE_PLAYING);
gst_element_set_state (bin, GST_STATE_PLAYING);
playing = TRUE;
</programlisting>
<note>
<para>
Before you set the bin to the PLAYING state, you must go through the
READY state. The READY state will, in this example, open the file, open
the audio device and initialise the MP3 decoder.
<application>GStreamer</application> will take care of the READY state for you when going from
NULL to PLAYING.
</para>
</note>
@ -273,7 +264,7 @@ void eos(GstSrc *src)
</para>
<programlisting>
while (playing) {
gst_bin_iterate(GST_BIN(bin));
gst_bin_iterate (GST_BIN (bin));
}
</programlisting>
<para>
@ -283,14 +274,14 @@ void eos(GstSrc *src)
</para>
<programlisting>
/* stop the bin */
gst_element_set_state(bin, GST_STATE_NULL);
gst_element_set_state (bin, GST_STATE_NULL);
gst_object_destroy(GST_OBJECT(audiosink));
gst_object_destroy(GST_OBJECT(decoder));
gst_object_destroy(GST_OBJECT(disksrc));
gst_object_destroy(GST_OBJECT(bin));
gst_object_destroy (GST_OBJECT (audiosink));
gst_object_destroy (GST_OBJECT (decoder));
gst_object_destroy (GST_OBJECT (disksrc));
gst_object_destroy (GST_OBJECT (bin));
exit(0);
exit (0);
</programlisting>
<note>
<para>
@ -311,8 +302,8 @@ void eos(GstSrc *src)
-o helloworld
</programlisting>
<para>
This uses the program gstreamer-config, which comes with GStreamer. This program "knows"
what compiler switches are needed to compile programs that use GStreamer.
This uses the program gstreamer-config, which comes with <application>GStreamer</application>. This program "knows"
what compiler switches are needed to compile programs that use <application>GStreamer</application>.
gstreamer-config --cflags will output a list of include
directories for the compiler to look in, and gstreamer-config --libs will output the
list of libraries for the compiler to link with and the directories to find them

10
docs/manual/intro.sgml
View file

@ -20,10 +20,18 @@
MPEG1, MPEG2, AVI, MP3, WAV, AU, ...
</para>
<para>
GStreamer, however, is much more than just another media player. Its
main advantages are that the pluggable components also make it possible
to write a full flegded video or audio editing application.
</para>
<para>
The framework is based on plug-ins that will provide the various codec
and other functionality. The plugins can be connected and arranged in
a pipeline. This pipeline defines the flow of the data.
a pipeline. This pipeline defines the flow of the data. Pipelines can
also be edited with a GUI editor and saved as XML so that pipeline
libraries can be made with a minimum of effort.
</para>
<para>

4
docs/manual/motivation.sgml
View file

@ -56,6 +56,10 @@
creation of binary only codecs. No company is willing to port their
code to all the different plugin mechanisms.
</para>
<para>
While GStreamer also uses it own plugin system it offers a very rich
framework for the plugin.
</para>
</sect2>
<sect2 id="sec-motivation-network">

121
docs/manual/pads.sgml Normal file
View file

@ -0,0 +1,121 @@
<chapter id="cha-pads">
<title>GstPad</title>
<para>
As we have seen in the previous chapter (GstElement), the pads are the elements
connections with the outside world.
</para>
<para>
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 (<classname>GstCaps</classname>)
</para>
<sect1 id="sec-pads-description">
<title>Capabilities of a GstPad</title>
<para>
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 pad by using capabilities.
</para>
<para>
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
filter-writer-guide.
</para>
<sect2 id="sec-pads-caps">
<title>What is a capability</title>
<para>
A capability is attached to a pad in order to describe what type of media the pad
can handle.
</para>
<para>
A capability is named and consists of a MIME type and a set of properties. Its data
structure is:
</para>
<programlisting>
struct _GstCaps {
gchar *name; /* the name of this caps */
guint16 id; /* type id (major type) */
GstProps *properties; /* properties for this capability */
};
</programlisting>
<para>
Below is a dump of the capabilities of the element mpg123, as shown by
<command>gstreamer-inspect</command>.
You can see two pads: sink and src. Both pads have capability information attached to them.
</para>
<para>
The sink pad (input pad) is called 'sink' and takes data of MIME type 'audio/mp3'. It also has
three properties: layer, bitrate and framed.
</para>
<para>
The src pad (output pad) is called 'src' and outputs data of MIME type 'audio/raw'. It also has
four properties: format, depth, rate and channels.
</para>
<programlisting>
Pads:
SINK: 'sink'
....
Capabilities:
'mpg123_sink':
MIME type: 'audio/mp3':
layer: Integer range: 1 - 3
bitrate: Integer range: 8 - 320
framed: Boolean: TRUE
SRC: 'src'
....
Capabilities:
'mpg123_src':
MIME type: 'audio/raw':
format: Integer: 16
depth: Integer: 16
rate: Integer range: 11025 - 48000
channels: List:
Integer: 1
Integer: 2
</programlisting>
</sect2>
<sect2 id="sec-pads-props">
<title>What are properties</title>
<para>
Properties are used to describe extra information for the capabilities. The properties
basically exist of a key (a string) and a value. There are different possibile value types
that can be used:
</para>
<itemizedlist>
<listitem>
<para>
An integer value: the property has this exact value.
</para>
</listitem>
<listitem>
<para>
An integer range value. The property denotes a range of possible values. In the case
of the mpg123 element: the src pad has a property rate that can go from 11025 to 48000.
</para>
</listitem>
<listitem>
<para>
A boolean value.
</para>
</listitem>
<listitem>
<para>
a fourcc value: this is a value that is commonly used to describe an encoding for video,
as used be the AVI specification.
</para>
</listitem>
<listitem>
<para>
A list value: the property can take any value from a list.
</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
</chapter>

6
docs/manual/states.sgml
View file

@ -69,6 +69,12 @@
an audio device. Some more complex elements might have a non trivial action to perform in
the READY state such as connecting to a media server using a CORBA connection.
</para>
<note>
<para>
You can also go from the NULL to PLAYING state directly without going through the READY
state. this is a shortcut, the framework will internally go through the READY state for you.
</para>
</note>
</sect1>
<sect1 id="sec-states-playing">

2
docs/manual/threads.sgml
View file

@ -59,7 +59,7 @@
<programlisting>
#include &lt;gst/gst.h&gt;
/* eos will be called when the src element has an end os stream */
/* eos will be called when the src element has an end of stream */
void eos(GstSrc *src, gpointer data)
{
GstThread *thread = GST_THREAD(data);