mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-23 00:36:51 +00:00
Code Issues 1 Projects Releases Wiki Activity

Small updates to the manual.

Browse source 
Original commit message from CVS:
Small updates to the manual.
This commit is contained in:
Wim Taymans 2001-06-15 21:46:57 +00:00
parent 07b3816510
commit 398dde60f4
7 changed files with 186 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/manual/advanced.sgml
View file

@ -220,7 +220,7 @@ struct _GstType {
<note> <note>
<para> <para>
As you can see, there might be a multitude of elements that As you can see, there might be a multitude of elements that
are able to operate on video/raw types. some might include: are able to operate on audio/raw types. some might include:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
@ -274,7 +274,7 @@ struct _GstType {
<title>creating elements with the factory</title> <title>creating elements with the factory</title>
<para> <para>
In the previous section we described how you could obtain In the previous section we described how you could obtain
an element factory using MIME types. One the factory has been an element factory using MIME types. Once the factory has been
obtained, you can create an element using: obtained, you can create an element using:
</para> </para>
<programlisting> <programlisting>

4
docs/manual/bins.sgml
View file

@ -28,7 +28,7 @@
<listitem> <listitem>
<para> <para>
A pipeline (<classname>GstPipeline</classname>). Which is a generic container you will A pipeline (<classname>GstPipeline</classname>). Which is a generic container you will
use most of the time. use most of the time. The toplevel bin has to be a pipeline.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -189,7 +189,7 @@
gst_bin_add (GST_BIN (bin), element); gst_bin_add (GST_BIN (bin), element);
gst_element_add_ghost_pad (bin, gst_element_get_pad (element, "sink")); gst_element_add_ghost_pad (bin, gst_element_get_pad (element, "sink"), "sink");
</programlisting> </programlisting>
<para> <para>

2
docs/manual/factories.sgml
View file

@ -229,7 +229,7 @@ struct _GstType {
<note> <note>
<para> <para>
As you can see, there might be a multitude of elements that As you can see, there might be a multitude of elements that
are able to operate on video/raw types. some might include: are able to operate on audio/raw types. some might include:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>

89
docs/manual/helloworld.sgml
View file

@ -22,17 +22,17 @@
int int
main (int argc, char *argv[]) main (int argc, char *argv[])
{ {
GstElement *bin, *disksrc, *parse, *decoder, *audiosink; GstElement *pipeline, *disksrc, *parse, *decoder, *audiosink;
gst_init(&amp;argc, &amp;argv); gst_init(&amp;argc, &amp;argv);
if (argc != 2) { if (argc != 2) {
g_print ("usage: &percnt;s &lt;filename&gt;n", argv[0]); g_print ("usage: &percnt;s &lt;filename&gt;\n", argv[0]);
exit (-1); exit (-1);
} }
/* create a new bin to hold the elements */ /* create a new pipeline to hold the elements */
bin = gst_bin_new ("bin"); pipeline = gst_pipeline_new ("pipeline");
/* create a disk reader */ /* create a disk reader */
disksrc = gst_elementfactory_make ("disksrc", "disk_source"); disksrc = gst_elementfactory_make ("disksrc", "disk_source");
@ -46,10 +46,10 @@ main (int argc, char *argv[])
audiosink = gst_elementfactory_make ("audiosink", "play_audio"); audiosink = gst_elementfactory_make ("audiosink", "play_audio");
/* add objects to the main pipeline */ /* add objects to the main pipeline */
gst_bin_add (GST_BIN (bin), disksrc); gst_bin_add (GST_BIN (pipeline), disksrc);
gst_bin_add (GST_BIN (bin), parse); gst_bin_add (GST_BIN (pipeline), parse);
gst_bin_add (GST_BIN (bin), decoder); gst_bin_add (GST_BIN (pipeline), decoder);
gst_bin_add (GST_BIN (bin), audiosink); gst_bin_add (GST_BIN (pipeline), audiosink);
/* connect src to sink */ /* connect src to sink */
gst_pad_connect (gst_element_get_pad (disksrc, "src"), gst_pad_connect (gst_element_get_pad (disksrc, "src"),
@ -60,18 +60,19 @@ main (int argc, char *argv[])
gst_element_get_pad (audiosink, "sink")); gst_element_get_pad (audiosink, "sink"));
/* start playing */ /* start playing */
gst_element_set_state (bin, GST_STATE_PLAYING); gst_element_set_state (pipeline, GST_STATE_PLAYING);
while (gst_bin_iterate (GST_BIN (bin))); while (gst_bin_iterate (GST_BIN (pipeline)));
/* stop the bin */ /* stop the pipeline */
gst_element_set_state (bin, GST_STATE_NULL); gst_element_set_state (pipeline, GST_STATE_NULL);
gst_object_destroy (GST_OBJECT (audiosink)); /* we don't need a reference to these objects anymore */
gst_object_destroy (GST_OBJECT (parse)); gst_object_unref (GST_OBJECT (audiosink));
gst_object_destroy (GST_OBJECT (decoder)); gst_object_unref (GST_OBJECT (parse));
gst_object_destroy (GST_OBJECT (disksrc)); gst_object_unref (GST_OBJECT (decoder));
gst_object_destroy (GST_OBJECT (bin)); gst_object_unref (GST_OBJECT (disksrc));
gst_object_unref (GST_OBJECT (pipeline));
exit (0); exit (0);
} }
@ -102,26 +103,26 @@ main (int argc, char *argv[])
</programlisting> </programlisting>
<para> <para>
We are going to create 4 elements and one bin. Since all objects are We are going to create 4 elements and one pipeline. Since all objects are
in fact elements, we can define them as: in fact elements, we can define them as:
</para> </para>
<programlisting> <programlisting>
... ...
GstElement *bin, *disksrc, *parse, *decoder, *audiosink; GstElement *pipeline, *disksrc, *parse, *decoder, *audiosink;
... ...
</programlisting> </programlisting>
<para> <para>
Next, we are going to create an empty bin. As you have seen in the basic Next, we are going to create an empty pipeline. As you have seen in the basic
introduction, this bin will hold and manage all the elements we are introduction, this pipeline will hold and manage all the elements we are
going to stuff into it. going to stuff into it.
</para> </para>
<programlisting> <programlisting>
/* create a new bin to hold the elements */ /* create a new pipeline to hold the elements */
bin = gst_bin_new ("bin"); pipeline = gst_pipeline_new ("pipeline");
</programlisting> </programlisting>
<para> <para>
We use the standard constructor for a bin: gst_bin_new ("name"). We use the standard constructor for a pipeline: gst_pipeline_new ("name").
</para> </para>
<para> <para>
@ -158,7 +159,7 @@ main (int argc, char *argv[])
identify the element you need and a second argument: how you want identify the element you need and a second argument: how you want
to name the element. The name of the element is something you can to name the element. The name of the element is something you can
choose yourself and might be used to retrieve the element from a choose yourself and might be used to retrieve the element from a
bin. bin/pipeline.
</para> </para>
<para> <para>
@ -171,14 +172,14 @@ main (int argc, char *argv[])
</programlisting> </programlisting>
<para> <para>
We then add the elements to the bin. We then add the elements to the pipeline.
</para> </para>
<programlisting> <programlisting>
/* add objects to the main pipeline */ /* add objects to the main pipeline */
gst_bin_add (GST_BIN (bin), disksrc); gst_bin_add (GST_BIN (pipeline), disksrc);
gst_bin_add (GST_BIN (bin), parse); gst_bin_add (GST_BIN (pipeline), parse);
gst_bin_add (GST_BIN (bin), decoder); gst_bin_add (GST_BIN (pipeline), decoder);
gst_bin_add (GST_BIN (bin), audiosink); gst_bin_add (GST_BIN (pipeline), audiosink);
</programlisting> </programlisting>
<para> <para>
@ -205,46 +206,46 @@ main (int argc, char *argv[])
<para> <para>
Everything is now set up to start the streaming. We use the following Everything is now set up to start the streaming. We use the following
statements to change the state of the bin: statements to change the state of the pipeline:
</para> </para>
<programlisting> <programlisting>
/* start playing */ /* start playing */
gst_element_set_state (bin, GST_STATE_PLAYING); gst_element_set_state (pipeline, GST_STATE_PLAYING);
</programlisting> </programlisting>
<note> <note>
<para> <para>
<application>GStreamer</application> will take care of the READY state for you when going from <application>GStreamer</application> will take care of the READY and PAUSED state for y
NULL to PLAYING. ou when going from NULL to PLAYING.
</para> </para>
</note> </note>
<para> <para>
Since we do not use threads, nothing will happen yet. We manually have to Since we do not use threads, nothing will happen yet. We manually have to
call gst_bin_iterate() to execute one iteration of the bin. call gst_bin_iterate() to execute one iteration of the pipeline.
</para> </para>
<programlisting> <programlisting>
while (gst_bin_iterate (GST_BIN (bin))); while (gst_bin_iterate (GST_BIN (pipeline)));
</programlisting> </programlisting>
<para> <para>
The gst_bin_iterate() function will return TRUE as long as something interesting The gst_bin_iterate() function will return TRUE as long as something interesting
happended inside the bin. When the end-of-file has been reached the _iterate happended inside the pipeline. When the end-of-file has been reached the _iterate
function will return FALSE and we can end the loop. function will return FALSE and we can end the loop.
</para> </para>
<programlisting> <programlisting>
/* stop the bin */ /* stop the pipeline */
gst_element_set_state (bin, GST_STATE_NULL); gst_element_set_state (pipeline, GST_STATE_NULL);
gst_object_destroy (GST_OBJECT (audiosink)); gst_object_unref (GST_OBJECT (audiosink));
gst_object_destroy (GST_OBJECT (decoder)); gst_object_unref (GST_OBJECT (decoder));
gst_object_destroy (GST_OBJECT (disksrc)); gst_object_unref (GST_OBJECT (disksrc));
gst_object_destroy (GST_OBJECT (bin)); gst_object_unref (GST_OBJECT (pipeline));
exit (0); exit (0);
</programlisting> </programlisting>
<note> <note>
<para> <para>
don't forget to set the state of the bin to NULL. This will free don't forget to set the state of the pipeline to NULL. This will free
all of the resources held by the elements. all of the resources held by the elements.
</para> </para>
</note> </note>

2
docs/manual/helloworld2.sgml
View file

@ -12,7 +12,7 @@
</para> </para>
<sect1> <sect1>
<title>Autoplugging helloworld</title> <title>Autoplugging helloworld (outdated) </title>
<para> <para>
We will create a second version of the helloworld application using We will create a second version of the helloworld application using
autoplugging. Its source code is considerably easier to write and autoplugging. Its source code is considerably easier to write and

132
docs/manual/pads.sgml
View file

@ -197,10 +197,13 @@ main(int argc, char *argv[])
<programlisting> <programlisting>
struct _GstCaps { struct _GstCaps {
gchar *name; /* the name of this caps */ gchar *name; /* the name of this caps */
guint16 id; /* type id (major type) */ guint16 id; /* type id (major type) */
guint refcount; /* caps are refcounted */
GstProps *properties; /* properties for this capability */ GstProps *properties; /* properties for this capability */
GstCaps *next; /* caps can be chained together */
}; };
</programlisting> </programlisting>
<para> <para>
@ -317,27 +320,140 @@ Pads:
<sect2 id="sec-pads-caps-get"> <sect2 id="sec-pads-caps-get">
<title>Getting the capabilities of a pad</title> <title>Getting the capabilities of a pad</title>
<para> <para>
A pad can have a GList of capabilities attached to it. You can get the capabilities list A pad can have a chain of capabilities attached to it. You can get the capabilities chain
with: with:
</para> </para>
<programlisting> <programlisting>
GList *caps; GstCaps *caps;
... ...
caps = gst_pad_get_caps_list (pad); caps = gst_pad_get_caps (pad);
g_print ("pad name &percnt;s\n", gst_pad_get_name (pad)); g_print ("pad name &percnt;s\n", gst_pad_get_name (pad));
while (caps) { while (caps) {
GstCaps *cap = (GstCaps *) caps-&gt;data; g_print (" Capability name &percnt;s, MIME type &percnt;s\n",
gst_caps_get_name (cap),
g_print (" Capability name &percnt;s, MIME type\n", gst_caps_get_name (cap),
gst_caps_get_mime (cap)); gst_caps_get_mime (cap));
caps = g_list_next (caps); caps = caps-&gt;next;
} }
... ...
</programlisting> </programlisting>
</sect2> </sect2>
<sect2 id="sec-pads-caps-create">
<title>Creating capabilities structures</title>
<para>
While the capabilities are mainly used inside the plugin to describe the media type of the
pads, the application programmer also has to have basic understanding of caps in order to
interface with the plugins, specially when using the autopluggers.
</para>
<para>
As we said, a capability has a name, a mime-type and some properties. The signature of the
function to create a new <classname>GstCaps *</classname> structure is like:
<programlisting>
GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props);
</programlisting>
</para>
<para>
You can therefore create a new capability with no properties like this:
<programlisting>
GstCaps *newcaps;
newcaps = gst_caps_new ("my_caps", "audio/wav", NULL);
</programlisting>
</para>
<para>
<classname>GstProps</classname> basically consist of a set of key-value pairs
and are created with a function with this signature:
<programlisting>
GstProps* gst_props_new (const gchar *firstname, ...);
</programlisting>
</para>
<para>
The keys are given as strings and the values are given with a set of macros:
<itemizedlist>
<listitem>
<para>
GST_PROPS_INT(a): An integer value
</para>
</listitem>
<listitem>
<para>
GST_PROPS_FLOAT(a): A floating point value
</para>
</listitem>
<listitem>
<para>
GST_PROPS_FOURCC(a): A fourcc value
</para>
</listitem>
<listitem>
<para>
GST_PROPS_BOOLEAN(a): A boolean value
</para>
</listitem>
<listitem>
<para>
GST_PROPS_STRING(a): A string value
</para>
</listitem>
</itemizedlist>
The values can also be specified as ranges with:
<itemizedlist>
<listitem>
<para>
GST_PROPS_INT_RANGE(a,b): An integer ragne from a to b
</para>
</listitem>
<listitem>
<para>
GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b
</para>
</listitem>
</itemizedlist>
All of the above values can be given with a list too using:
<itemizedlist>
<listitem>
<para>
GST_PROPS_LIST(a,...): A list of property values.
</para>
</listitem>
</itemizedlist>
</para>
<para>
A more complex capability with properties is created like this:
<programlisting>
GstCaps *newcaps;
newcaps = gst_caps_new ("my_caps",
"audio/wav",
gst_props_new (
"bitrate", GST_PROPS_INT_RANGE (11025,22050),
"depth", GST_PROPS_INT (16),
"signed", GST_PROPS_LIST (
GST_PROPS_BOOLEAN (TRUE),
GST_PROPS_BOOLEAN (FALSE)
),
NULL
);
</programlisting>
Optionally the convenient shortcut macro can be used. The above complex
capability can be created with:
<programlisting>
GstCaps *newcaps;
newcaps = GST_CAPS_NEW ("my_caps",
"audio/wav",
"bitrate", GST_PROPS_INT_RANGE (11025,22050),
"depth", GST_PROPS_INT (16),
"signed", GST_PROPS_LIST (
GST_PROPS_BOOLEAN (TRUE),
GST_PROPS_BOOLEAN (FALSE)
)
);
</programlisting>
</para>
</sect2>
</sect1> </sect1>
</chapter> </chapter>

26
docs/manual/states.sgml
View file

@ -23,12 +23,12 @@
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
PLAYING: The element is doing something. PAUSED: The element is paused for a period of time.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
PAUSED: The element is paused for a period of time. PLAYING: The element is doing something.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -36,10 +36,8 @@
<para> <para>
All elements start with the NULL state. The elements will go throught the following state changes: All elements start with the NULL state. The elements will go throught the following state changes:
<figure float="1" id="sec-state-img"> NULL -&gt; READY -&gt; PAUSED -&gt; PLAYING. Remember when going from PLAYING to READY GStreamer
<title>The different states of a <classname>GstElement</classname> and the state transitions</title> will internally go throught the intermediate states.
<graphic fileref="images/state-diagram" format="png"></graphic>
</figure>
</para> </para>
<para> <para>
The state of an element can be changed with the following code: The state of an element can be changed with the following code:
@ -61,11 +59,6 @@
<colspec colwidth="2*"> <colspec colwidth="2*">
<colspec colwidth="8*"> <colspec colwidth="8*">
<tbody> <tbody>
<row>
<entry><literal>GST_STATE_NONE_PENDING</literal></entry>
<entry>The element is in the desired state.
</entry>
</row>
<row> <row>
<entry><literal>GST_STATE_NULL</literal></entry> <entry><literal>GST_STATE_NULL</literal></entry>
<entry>Reset the state of an element. <entry>Reset the state of an element.
@ -77,13 +70,13 @@
</entry> </entry>
</row> </row>
<row> <row>
<entry><literal>GST_STATE_PLAYING</literal></entry> <entry><literal>GST_STATE_PAUSED</literal></entry>
<entry>means there really is data flowing through the graph. <entry>temporary stops the data flow.
</entry> </entry>
</row> </row>
<row> <row>
<entry><literal>GST_STATE_PAUSED</literal></entry> <entry><literal>GST_STATE_PLAYING</literal></entry>
<entry>temporary stops the data flow. <entry>means there really is data flowing through the graph.
</entry> </entry>
</row> </row>
</tbody> </tbody>
@ -121,7 +114,8 @@
<note> <note>
<para> <para>
You can also go from the NULL to PLAYING state directly without going through the READY 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. state. this is a shortcut, the framework will internally go through the READY and the
PAUSED state for you.
</para> </para>
</note> </note>
</sect1> </sect1>