From 398dde60f41837eae16b5a3b0d1dd52f117fe1c1 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Fri, 15 Jun 2001 21:46:57 +0000 Subject: [PATCH] Small updates to the manual. Original commit message from CVS: Small updates to the manual. --- docs/manual/advanced.sgml | 4 +- docs/manual/bins.sgml | 4 +- docs/manual/factories.sgml | 2 +- docs/manual/helloworld.sgml | 89 +++++++++++------------ docs/manual/helloworld2.sgml | 2 +- docs/manual/pads.sgml | 134 ++++++++++++++++++++++++++++++++--- docs/manual/states.sgml | 26 +++---- 7 files changed, 186 insertions(+), 75 deletions(-) diff --git a/docs/manual/advanced.sgml b/docs/manual/advanced.sgml index 1c67a53e60..91d9055108 100644 --- a/docs/manual/advanced.sgml +++ b/docs/manual/advanced.sgml @@ -220,7 +220,7 @@ struct _GstType { 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: @@ -274,7 +274,7 @@ struct _GstType { creating elements with the factory 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: diff --git a/docs/manual/bins.sgml b/docs/manual/bins.sgml index 6befcc36c7..04d46a858d 100644 --- a/docs/manual/bins.sgml +++ b/docs/manual/bins.sgml @@ -28,7 +28,7 @@ A pipeline (GstPipeline). 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. @@ -189,7 +189,7 @@ 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"); diff --git a/docs/manual/factories.sgml b/docs/manual/factories.sgml index b35b11b621..d67146f648 100644 --- a/docs/manual/factories.sgml +++ b/docs/manual/factories.sgml @@ -229,7 +229,7 @@ struct _GstType { 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: diff --git a/docs/manual/helloworld.sgml b/docs/manual/helloworld.sgml index 292234b552..42868dcd6b 100644 --- a/docs/manual/helloworld.sgml +++ b/docs/manual/helloworld.sgml @@ -22,17 +22,17 @@ int main (int argc, char *argv[]) { - GstElement *bin, *disksrc, *parse, *decoder, *audiosink; + GstElement *pipeline, *disksrc, *parse, *decoder, *audiosink; gst_init(&argc, &argv); if (argc != 2) { - g_print ("usage: %s <filename>n", argv[0]); + g_print ("usage: %s <filename>\n", argv[0]); exit (-1); } - /* create a new bin to hold the elements */ - bin = gst_bin_new ("bin"); + /* create a new pipeline to hold the elements */ + pipeline = gst_pipeline_new ("pipeline"); /* create a disk reader */ disksrc = gst_elementfactory_make ("disksrc", "disk_source"); @@ -46,10 +46,10 @@ main (int argc, char *argv[]) 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 (pipeline), disksrc); + gst_bin_add (GST_BIN (pipeline), parse); + gst_bin_add (GST_BIN (pipeline), decoder); + gst_bin_add (GST_BIN (pipeline), audiosink); /* connect src to sink */ gst_pad_connect (gst_element_get_pad (disksrc, "src"), @@ -60,18 +60,19 @@ main (int argc, char *argv[]) gst_element_get_pad (audiosink, "sink")); /* 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 */ - gst_element_set_state (bin, GST_STATE_NULL); + /* stop the pipeline */ + gst_element_set_state (pipeline, 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)); + /* we don't need a reference to these objects anymore */ + gst_object_unref (GST_OBJECT (audiosink)); + gst_object_unref (GST_OBJECT (parse)); + gst_object_unref (GST_OBJECT (decoder)); + gst_object_unref (GST_OBJECT (disksrc)); + gst_object_unref (GST_OBJECT (pipeline)); exit (0); } @@ -102,26 +103,26 @@ main (int argc, char *argv[]) - 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: ... - GstElement *bin, *disksrc, *parse, *decoder, *audiosink; + GstElement *pipeline, *disksrc, *parse, *decoder, *audiosink; ... - Next, we are going to create an empty bin. As you have seen in the basic - introduction, this bin will hold and manage all the elements we are + Next, we are going to create an empty pipeline. As you have seen in the basic + introduction, this pipeline will hold and manage all the elements we are going to stuff into it. - /* create a new bin to hold the elements */ - bin = gst_bin_new ("bin"); + /* create a new pipeline to hold the elements */ + pipeline = gst_pipeline_new ("pipeline"); - We use the standard constructor for a bin: gst_bin_new ("name"). + We use the standard constructor for a pipeline: gst_pipeline_new ("name"). @@ -158,7 +159,7 @@ main (int argc, char *argv[]) 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 choose yourself and might be used to retrieve the element from a - bin. + bin/pipeline. @@ -171,14 +172,14 @@ main (int argc, char *argv[]) - We then add the elements to the bin. + We then add the elements to the pipeline. /* 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 (pipeline), disksrc); + gst_bin_add (GST_BIN (pipeline), parse); + gst_bin_add (GST_BIN (pipeline), decoder); + gst_bin_add (GST_BIN (pipeline), audiosink); @@ -205,46 +206,46 @@ main (int argc, char *argv[]) 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: /* start playing */ - gst_element_set_state (bin, GST_STATE_PLAYING); + gst_element_set_state (pipeline, GST_STATE_PLAYING); - GStreamer will take care of the READY state for you when going from - NULL to PLAYING. + GStreamer will take care of the READY and PAUSED state for y + ou when going from NULL to PLAYING. 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. - while (gst_bin_iterate (GST_BIN (bin))); + while (gst_bin_iterate (GST_BIN (pipeline))); 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. - /* stop the bin */ - gst_element_set_state (bin, GST_STATE_NULL); + /* stop the pipeline */ + gst_element_set_state (pipeline, 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_unref (GST_OBJECT (audiosink)); + gst_object_unref (GST_OBJECT (decoder)); + gst_object_unref (GST_OBJECT (disksrc)); + gst_object_unref (GST_OBJECT (pipeline)); exit (0); - 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. diff --git a/docs/manual/helloworld2.sgml b/docs/manual/helloworld2.sgml index 1a48f7f991..df973472b7 100644 --- a/docs/manual/helloworld2.sgml +++ b/docs/manual/helloworld2.sgml @@ -12,7 +12,7 @@ - Autoplugging helloworld + Autoplugging helloworld (outdated) We will create a second version of the helloworld application using autoplugging. Its source code is considerably easier to write and diff --git a/docs/manual/pads.sgml b/docs/manual/pads.sgml index 4f83e86229..544d0b68c4 100644 --- a/docs/manual/pads.sgml +++ b/docs/manual/pads.sgml @@ -197,10 +197,13 @@ main(int argc, char *argv[]) struct _GstCaps { gchar *name; /* the name of this caps */ - guint16 id; /* type id (major type) */ + guint refcount; /* caps are refcounted */ + GstProps *properties; /* properties for this capability */ + + GstCaps *next; /* caps can be chained together */ }; @@ -317,27 +320,140 @@ Pads: Getting the capabilities of a pad - 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: - GList *caps; + GstCaps *caps; ... - caps = gst_pad_get_caps_list (pad); + caps = gst_pad_get_caps (pad); g_print ("pad name %s\n", gst_pad_get_name (pad)); while (caps) { - GstCaps *cap = (GstCaps *) caps->data; - - g_print (" Capability name %s, MIME type\n", gst_caps_get_name (cap), - gst_caps_get_mime (cap)); + g_print (" Capability name %s, MIME type %s\n", + gst_caps_get_name (cap), + gst_caps_get_mime (cap)); - caps = g_list_next (caps); + caps = caps->next; } ... + + Creating capabilities structures + + 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. + + + As we said, a capability has a name, a mime-type and some properties. The signature of the + function to create a new GstCaps * structure is like: + +GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props); + + + + You can therefore create a new capability with no properties like this: + + GstCaps *newcaps; + + newcaps = gst_caps_new ("my_caps", "audio/wav", NULL); + + + + GstProps basically consist of a set of key-value pairs + and are created with a function with this signature: + +GstProps* gst_props_new (const gchar *firstname, ...); + + + + The keys are given as strings and the values are given with a set of macros: + + + + GST_PROPS_INT(a): An integer value + + + + + GST_PROPS_FLOAT(a): A floating point value + + + + + GST_PROPS_FOURCC(a): A fourcc value + + + + + GST_PROPS_BOOLEAN(a): A boolean value + + + + + GST_PROPS_STRING(a): A string value + + + + The values can also be specified as ranges with: + + + + GST_PROPS_INT_RANGE(a,b): An integer ragne from a to b + + + + + GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b + + + + All of the above values can be given with a list too using: + + + + GST_PROPS_LIST(a,...): A list of property values. + + + + + + A more complex capability with properties is created like this: + + 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 + ); + + Optionally the convenient shortcut macro can be used. The above complex + capability can be created with: + + 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) + ) + ); + + + diff --git a/docs/manual/states.sgml b/docs/manual/states.sgml index e3e0999db4..9027910bf3 100644 --- a/docs/manual/states.sgml +++ b/docs/manual/states.sgml @@ -23,12 +23,12 @@ - PLAYING: The element is doing something. + PAUSED: The element is paused for a period of time. - PAUSED: The element is paused for a period of time. + PLAYING: The element is doing something. @@ -36,10 +36,8 @@ All elements start with the NULL state. The elements will go throught the following state changes: -
- The different states of a <classname>GstElement</classname> and the state transitions - -
+ NULL -> READY -> PAUSED -> PLAYING. Remember when going from PLAYING to READY GStreamer + will internally go throught the intermediate states. The state of an element can be changed with the following code: @@ -61,11 +59,6 @@ - - GST_STATE_NONE_PENDING - The element is in the desired state. - - GST_STATE_NULL Reset the state of an element. @@ -77,13 +70,13 @@ - GST_STATE_PLAYING - means there really is data flowing through the graph. + GST_STATE_PAUSED + temporary stops the data flow. - GST_STATE_PAUSED - temporary stops the data flow. + GST_STATE_PLAYING + means there really is data flowing through the graph. @@ -121,7 +114,8 @@ 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.