From ea3715a1b44ea5fff169fcabfe5e8f38776d26ce Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Thu, 4 Jan 2001 23:35:50 +0000 Subject: [PATCH] Updates and additions to the manual Original commit message from CVS: Updates and additions to the manual --- docs/manual/Makefile.am | 4 + docs/manual/bin-element-ghost.fig | 47 +++++++++ docs/manual/bins.sgml | 30 +++++- docs/manual/elements.sgml | 29 ++--- docs/manual/factories.sgml | 16 ++- docs/manual/goals.sgml | 28 ++++- docs/manual/gstreamer-manual.sgml | 3 + docs/manual/helloworld.sgml | 169 ++++++++++++++---------------- docs/manual/intro.sgml | 10 +- docs/manual/motivation.sgml | 4 + docs/manual/pads.sgml | 121 +++++++++++++++++++++ docs/manual/states.sgml | 6 ++ docs/manual/threads.sgml | 2 +- 13 files changed, 349 insertions(+), 120 deletions(-) create mode 100644 docs/manual/bin-element-ghost.fig create mode 100644 docs/manual/pads.sgml diff --git a/docs/manual/Makefile.am b/docs/manual/Makefile.am index c8348e856c..2da008035b 100644 --- a/docs/manual/Makefile.am +++ b/docs/manual/Makefile.am @@ -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 \ diff --git a/docs/manual/bin-element-ghost.fig b/docs/manual/bin-element-ghost.fig new file mode 100644 index 0000000000..34327365f3 --- /dev/null +++ b/docs/manual/bin-element-ghost.fig @@ -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 diff --git a/docs/manual/bins.sgml b/docs/manual/bins.sgml index e959596f84..e9069b326c 100644 --- a/docs/manual/bins.sgml +++ b/docs/manual/bins.sgml @@ -2,7 +2,7 @@ Bins 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 GstElement itself, it can also be added to another bin. Bins allow you to combine connected elements into one logical element. You do @@ -12,7 +12,8 @@ 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.
@@ -62,5 +63,30 @@ // stop gst_element_set_state(GST_ELEMENT(mp3player),GST_STATE_NULL); + + Custom bins can be created with a plugin or an XML description. + + + Ghostpads + + You can see from figure ... how a bin has no pads of its own. This is where Ghostpads + come into play. + + + 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. + + +
+ Visualisation of a <classname>GstBin</classname> element with a ghostpad + +
+ + Above is a representation of a ghostpad. the sinkpad of element one is now also a pad + of the bin. + + + diff --git a/docs/manual/elements.sgml b/docs/manual/elements.sgml index cc35ac47e1..84f8c8e2f1 100644 --- a/docs/manual/elements.sgml +++ b/docs/manual/elements.sgml @@ -13,25 +13,27 @@ This means that a lot of functions you are going to use operate on this object. - 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. - 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. + - GStreamer source elements (<classname>GstSrc</classname>) + GStreamer source elements This element will generate data that will be used by the pipeline. It is typically a file or an audio source. - Below you see how we will visualize the GstSrc element. + Below you see how we will visualize the element. We always draw a src pad to the right of the element.
- Visualisation of a <classname>GstSrc</classname> element + Visualisation of a source element
@@ -39,10 +41,10 @@ this in the figure because it only has a src pad. A src pad can only generate buffers. - + - GStreamer filter elements (<classname>GstFilter</classname>) + GStreamer filter elements 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.
- Visualisation of a <classname>GstFilter</classname> element + Visualisation of a filter element
@@ -65,7 +67,7 @@ of the element.
- Visualisation of a <classname>GstFilter</classname> element with + <title>Visualisation of a filter element with more than one output pad
@@ -79,17 +81,16 @@ - GStreamer sink elements (<classname>GstSink</classname>) + GStreamer sink elements 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:
- Visualisation of a <classname>GstSink</classname> element + Visualisation of a sink element
- diff --git a/docs/manual/factories.sgml b/docs/manual/factories.sgml index 5b156e01fe..810b5ef136 100644 --- a/docs/manual/factories.sgml +++ b/docs/manual/factories.sgml @@ -36,8 +36,8 @@ an MP3 decoder element. - 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. @@ -51,7 +51,7 @@ 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: @@ -110,9 +110,8 @@ GStreamer types - 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. @@ -126,7 +125,7 @@ GstType is like: -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 */ }; diff --git a/docs/manual/goals.sgml b/docs/manual/goals.sgml index cc062165ee..1da2432672 100644 --- a/docs/manual/goals.sgml +++ b/docs/manual/goals.sgml @@ -18,12 +18,18 @@ - 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. - 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. @@ -36,7 +42,11 @@ with GTK+ will be confortable with GStreamer. - GStreamer uses the mechanisems of signals and object arguments. + GStreamer uses the mechanism of signals and object arguments. + + + All objects can be queried at runtime for their various properties and + capabilities. @@ -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. + + 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. + @@ -103,6 +118,13 @@ HW acceleration is possible by writing a specialized plugin. + + + Uses a plugin registry with the specifications of the plugins so + that the plugin loading can be delayed until the plugin is actually + used. + + diff --git a/docs/manual/gstreamer-manual.sgml b/docs/manual/gstreamer-manual.sgml index 560360c9b5..be062eae77 100644 --- a/docs/manual/gstreamer-manual.sgml +++ b/docs/manual/gstreamer-manual.sgml @@ -4,6 +4,7 @@ + @@ -97,6 +98,8 @@ &ELEMENTS; + &PADS; + &CONNECTIONS; &BINS; diff --git a/docs/manual/helloworld.sgml b/docs/manual/helloworld.sgml index 043b21b2cd..ee71f4473f 100644 --- a/docs/manual/helloworld.sgml +++ b/docs/manual/helloworld.sgml @@ -1,7 +1,7 @@ Your first application - This chapter describes the most rudimentary aspects of a GStreamer application, + This chapter describes the most rudimentary aspects of a GStreamer application, including initializing the libraries, creating elements, packing them into a pipeline and playing, pause and stop the pipeline. @@ -10,7 +10,7 @@ Hello world 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 GStreamer components. The player will read from a file that is given as the first argument of the program. @@ -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(&argc, &argv); + if (argc != 2) { - g_print("usage: %s <filename>n", argv[0]); - exit(-1); + g_print ("usage: %s <filename>n", argv[0]); + exit (-1); } - gst_init(&argc,&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); } @@ -102,7 +100,7 @@ int main(int argc,char *argv[]) - 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 GStreamer headers and initialize the framework. @@ -111,10 +109,11 @@ int main(int argc,char *argv[]) ... -int main(int argc,char *argv[]) +int +main (int argc, char *argv[]) { ... - gst_init(&argc,&argv); + gst_init(&argc, &argv); ... @@ -136,8 +135,11 @@ int main(int argc,char *argv[]) /* create a new bin to hold the elements */ - bin = gst_bin_new("bin"); + bin = gst_bin_new ("bin"); + + We use the standard constructor for a bin: gst_bin_new (" + We then create a disk source element. The disk source element is able to @@ -146,10 +148,10 @@ int main(int argc,char *argv[]) /* 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); 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; } - We now create the MP3 decoder element. GStreamer requires you + We now create the MP3 decoder element. GStreamer 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) /* 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"); gst_elementfactory_make() takes two arguments: a string that will @@ -202,7 +205,7 @@ void eos(GstSrc *src) /* and an audio sink */ - audiosink = gst_elementfactory_make("audiosink", "play_audio"); + audiosink = gst_elementfactory_make ("audiosink", "play_audio"); @@ -210,10 +213,10 @@ void eos(GstSrc *src) /* 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); @@ -221,12 +224,12 @@ void eos(GstSrc *src) /* 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")); @@ -238,32 +241,20 @@ void eos(GstSrc *src)
- - 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. - - - /* find out how to handle this bin */ - gst_bin_create_plan(GST_BIN(bin)); - - Everything is now set up to start the streaming. We use the following statements to change the state of the 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; - 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. + GStreamer will take care of the READY state for you when going from + NULL to PLAYING. @@ -273,7 +264,7 @@ void eos(GstSrc *src) while (playing) { - gst_bin_iterate(GST_BIN(bin)); + gst_bin_iterate (GST_BIN (bin)); } @@ -283,14 +274,14 @@ void eos(GstSrc *src) /* 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); @@ -311,8 +302,8 @@ void eos(GstSrc *src) -o helloworld - 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 GStreamer. This program "knows" + what compiler switches are needed to compile programs that use GStreamer. 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 diff --git a/docs/manual/intro.sgml b/docs/manual/intro.sgml index 3d230116ca..2e4f54bebe 100644 --- a/docs/manual/intro.sgml +++ b/docs/manual/intro.sgml @@ -20,10 +20,18 @@ MPEG1, MPEG2, AVI, MP3, WAV, AU, ... + + 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. + + 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. diff --git a/docs/manual/motivation.sgml b/docs/manual/motivation.sgml index 352ee914c8..cde5210b3d 100644 --- a/docs/manual/motivation.sgml +++ b/docs/manual/motivation.sgml @@ -56,6 +56,10 @@ creation of binary only codecs. No company is willing to port their code to all the different plugin mechanisms. + + While GStreamer also uses it own plugin system it offers a very rich + framework for the plugin. + diff --git a/docs/manual/pads.sgml b/docs/manual/pads.sgml new file mode 100644 index 0000000000..b802b6592f --- /dev/null +++ b/docs/manual/pads.sgml @@ -0,0 +1,121 @@ + + GstPad + + As we have seen in the previous chapter (GstElement), the pads are the elements + connections with the outside world. + + + 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 (GstCaps) + + + + Capabilities of a GstPad + + 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. + + + 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. + + + + What is a capability + + A capability is attached to a pad in order to describe what type of media the pad + can handle. + + + A capability is named and consists of a MIME type and a set of properties. Its data + structure is: + + +struct _GstCaps { + gchar *name; /* the name of this caps */ + + guint16 id; /* type id (major type) */ + + GstProps *properties; /* properties for this capability */ +}; + + + Below is a dump of the capabilities of the element mpg123, as shown by + gstreamer-inspect. + You can see two pads: sink and src. Both pads have capability information attached to them. + + + 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. + + + 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. + + +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 + + + + What are properties + + 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: + + + + + + An integer value: the property has this exact value. + + + + + 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. + + + + + A boolean value. + + + + + a fourcc value: this is a value that is commonly used to describe an encoding for video, + as used be the AVI specification. + + + + + A list value: the property can take any value from a list. + + + + + + + + diff --git a/docs/manual/states.sgml b/docs/manual/states.sgml index 9749c8e6e2..1ab5e10047 100644 --- a/docs/manual/states.sgml +++ b/docs/manual/states.sgml @@ -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. + + + 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. + + diff --git a/docs/manual/threads.sgml b/docs/manual/threads.sgml index 9c484e54a2..6de7861af3 100644 --- a/docs/manual/threads.sgml +++ b/docs/manual/threads.sgml @@ -59,7 +59,7 @@ #include <gst/gst.h> -/* 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);