From 626cbdc8b28c91d628c671dbbf3355c55c2358a9 Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Tue, 27 Jul 2004 15:01:10 +0000 Subject: [PATCH] cleanup of unused and forgoten sections fixed links from the manual and the pwg to the API docs added more notes to R... Original commit message from CVS: cleanup of unused and forgoten sections fixed links from the manual and the pwg to the API docs added more notes to README --- docs/README | 3 +- docs/gst/gstreamer-docs.sgml | 43 +- docs/gst/gstreamer-sections.txt | 6 +- docs/gst/tmpl/gstcompat.sgml | 4 +- docs/gst/tmpl/gstmacros.sgml | 4 +- docs/gst/tmpl/gststructure.sgml | 7 + docs/gst/tmpl/gstsystemclock.sgml | 7 + docs/gst/tmpl/gsttaglist.sgml | 863 ++++++++++++++++++++++++++++++++++++++ docs/gst/tmpl/gsttypes.sgml | 4 +- docs/gst/tmpl/gsturihandler.sgml | 141 +++++++ docs/gst/tmpl/gsturitype.sgml | 2 +- docs/gst/tmpl/gstutils.sgml | 2 +- docs/gst/tmpl/gstversion.sgml | 2 +- docs/manual/advanced-threads.xml | 166 -------- docs/manual/autoplugging.xml | 1 + docs/manual/basics-data.xml | 65 --- docs/manual/basics-elements.xml | 118 ------ docs/manual/basics-helloworld.xml | 279 ------------ docs/manual/basics-pads.xml | 243 ----------- docs/manual/bins-api.xml | 14 +- docs/manual/buffers.xml | 3 +- docs/manual/cothreads.xml | 11 +- docs/manual/elements-api.xml | 18 +- docs/manual/elements.xml | 12 +- docs/manual/helloworld.xml | 3 +- docs/manual/links-api.xml | 13 +- docs/manual/manual.xml | 8 +- docs/manual/pads-api.xml | 5 +- docs/manual/pads.xml | 5 +- docs/manual/threads.xml | 6 +- docs/pwg/advanced-events.xml | 16 +- docs/pwg/advanced-interfaces.xml | 35 +- docs/pwg/advanced-tagging.xml | 31 +- docs/pwg/building-pads.xml | 18 +- docs/pwg/building-state.xml | 26 +- docs/pwg/intro-basics.xml | 15 +- docs/pwg/intro-preface.xml | 5 +- 37 files changed, 1222 insertions(+), 982 deletions(-) create mode 100644 docs/gst/tmpl/gsttaglist.sgml create mode 100644 docs/gst/tmpl/gsturihandler.sgml delete mode 100644 docs/manual/advanced-threads.xml delete mode 100644 docs/manual/basics-data.xml delete mode 100644 docs/manual/basics-elements.xml delete mode 100644 docs/manual/basics-helloworld.xml delete mode 100644 docs/manual/basics-pads.xml diff --git a/docs/README b/docs/README index 2983a4f..c5254aa 100644 --- a/docs/README +++ b/docs/README @@ -143,7 +143,8 @@ GTK-DOC NOTES $(MODULE)-sections.txt is created if it doesn't exist yet (it should), as well as $(MODULE)-decl.txt and $(MODULE)-decl-list.txt and .args, .hierarchy and .signals files are created - gtkdoc-scan is called + gtkdoc-scan is called + - if it not works, try e.g. 'rm docs/gst/*.stamp' * Possible errors and how to fix them - Warning: multiple "IDs" for constraint linkend: gst-tag-register. diff --git a/docs/gst/gstreamer-docs.sgml b/docs/gst/gstreamer-docs.sgml index b7b4828..d6bbc4a 100644 --- a/docs/gst/gstreamer-docs.sgml +++ b/docs/gst/gstreamer-docs.sgml @@ -9,21 +9,24 @@ + + + + - - + @@ -34,6 +37,7 @@ + @@ -45,14 +49,18 @@ + - + + + + - + @@ -89,22 +97,24 @@ &Gst; &GstBin; &GstBuffer; - &GstConfig; &GstCaps; &GstClock; + &GstConfig; &GstCpu; &GstData; &GstElement; &GstElementDetails; &GstElementFactory; + &GstEnumTypes; &GstError; &GstEvent; + &GstFilter; &GstFormat; &GstGhostPad; + &GstImplementsInterface; &GstIndex; &GstIndexFactory; &GstInfo; - &GstImplementsInterface; &GstObject; &GstPad; &GstPadTemplate; @@ -127,9 +137,12 @@ &GstThread; &GstTypeFind; &GstTypeFindFactory; + &GstTypes; &GstUriHandler; + &GstUriType; &GstUtils; &GstValue; + &GstVersion; &GstXML; @@ -141,12 +154,24 @@ &GstAtomic; + &GstMacros; &GstMemChunk; - -gstcompat +GstCompat - +Deprecated API entries diff --git a/docs/gst/tmpl/gstmacros.sgml b/docs/gst/tmpl/gstmacros.sgml index 6617bc2..ced3888 100644 --- a/docs/gst/tmpl/gstmacros.sgml +++ b/docs/gst/tmpl/gstmacros.sgml @@ -1,8 +1,8 @@ -gstmacros +GstMacros - +various portabillity helper macros diff --git a/docs/gst/tmpl/gststructure.sgml b/docs/gst/tmpl/gststructure.sgml index a0b2b7e..122fb20 100644 --- a/docs/gst/tmpl/gststructure.sgml +++ b/docs/gst/tmpl/gststructure.sgml @@ -14,6 +14,13 @@ Generic structure containing fields of names and values + + + + + + + diff --git a/docs/gst/tmpl/gstsystemclock.sgml b/docs/gst/tmpl/gstsystemclock.sgml index 1f5f6eb..c8afc01 100644 --- a/docs/gst/tmpl/gstsystemclock.sgml +++ b/docs/gst/tmpl/gstsystemclock.sgml @@ -25,6 +25,13 @@ system time. @cond: @_gst_reserved: + + + + + + + diff --git a/docs/gst/tmpl/gsttaglist.sgml b/docs/gst/tmpl/gsttaglist.sgml new file mode 100644 index 0000000..d0c5164 --- /dev/null +++ b/docs/gst/tmpl/gsttaglist.sgml @@ -0,0 +1,863 @@ + +GstTagList + + +List of tags and values used to describe media metadata + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@GST_TAG_MERGE_UNDEFINED: +@GST_TAG_MERGE_REPLACE_ALL: +@GST_TAG_MERGE_REPLACE: +@GST_TAG_MERGE_APPEND: +@GST_TAG_MERGE_PREPEND: +@GST_TAG_MERGE_KEEP: +@GST_TAG_MERGE_KEEP_ALL: +@GST_TAG_MERGE_COUNT: + + + + + + +@GST_TAG_FLAG_UNDEFINED: +@GST_TAG_FLAG_META: +@GST_TAG_FLAG_ENCODED: +@GST_TAG_FLAG_DECODED: +@GST_TAG_FLAG_COUNT: + + + + + + +@list: +@tag: +@user_data: + + + + + + + +@dest: +@src: + + + + + + + +@name: +@flag: +@type: +@nick: +@blurb: +@func: + + + + + + + +@dest: +@src: + + + + + + + +@dest: +@src: + + + + + + + +@tag: +@Returns: + + + + + + + +@tag: +@Returns: + + + + + + + +@tag: +@Returns: + + + + + + + +@tag: +@Returns: + + + + + + + +@tag: +@Returns: + + + + + + + +@tag: +@Returns: + + + + + + + +@Returns: + + + + + + + +@p: +@Returns: + + + + + + + +@list: +@Returns: + + + + + + + +@into: +@from: +@mode: + + + + + + + +@list1: +@list2: +@mode: +@Returns: + + + + + + + +@list: + + + + + + + +@list: +@tag: +@Returns: + + + + + + + +@list: +@mode: +@tag: +@Varargs: + + + + + + + +@list: +@mode: +@tag: +@Varargs: + + + + + + + +@list: +@mode: +@tag: +@var_args: + + + + + + + +@list: +@mode: +@tag: +@var_args: + + + + + + + +@list: +@tag: + + + + + + + +@list: +@func: +@user_data: + + + + + + + +@list: +@tag: +@index: +@Returns: + + + + + + + +@dest: +@list: +@tag: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@tag: +@value: +@Returns: + + + + + + + +@list: +@tag: +@index: +@value: +@Returns: + + + + + + + +@list: +@Returns: + + + + + + + +@tag_event: +@Returns: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/gst/tmpl/gsttypes.sgml b/docs/gst/tmpl/gsttypes.sgml index dbf8240..b56d58a 100644 --- a/docs/gst/tmpl/gsttypes.sgml +++ b/docs/gst/tmpl/gsttypes.sgml @@ -1,8 +1,8 @@ -gsttypes +GstTypes - +various global enums and constants diff --git a/docs/gst/tmpl/gsturihandler.sgml b/docs/gst/tmpl/gsturihandler.sgml new file mode 100644 index 0000000..29fa2d6 --- /dev/null +++ b/docs/gst/tmpl/gsturihandler.sgml @@ -0,0 +1,141 @@ + +GstUriHandler + + +Plugin feature that handles URI types + + + +The URIHandler is a pluginfeature that can be used to locate element +and the element property that can handle a given URI. + + + + + + + + + + + + + + + + + + + + + + + + + +@type: + + + + + + + +@protocol: +@Returns: + + + + + + + +@uri: +@Returns: + + + + + + + +@uri: +@Returns: + + + + + + + +@uri: +@Returns: + + + + + + + +@protocol: +@location: +@Returns: + + + + + + + +@type: +@uri: +@elementname: +@Returns: + + + + + + + +@handler: +@Returns: + + + + + + + +@handler: +@Returns: + + + + + + + +@handler: +@Returns: + + + + + + + +@handler: +@uri: +@Returns: + + + + + + + +@handler: +@uri: + + diff --git a/docs/gst/tmpl/gsturitype.sgml b/docs/gst/tmpl/gsturitype.sgml index 8e7bcfd..77aec06 100644 --- a/docs/gst/tmpl/gsturitype.sgml +++ b/docs/gst/tmpl/gsturitype.sgml @@ -2,7 +2,7 @@ GstURIType - +describes URI types diff --git a/docs/gst/tmpl/gstutils.sgml b/docs/gst/tmpl/gstutils.sgml index b05d1aa..980fc8a 100644 --- a/docs/gst/tmpl/gstutils.sgml +++ b/docs/gst/tmpl/gstutils.sgml @@ -1,5 +1,5 @@ -gstutils +GstUtils various utility functions diff --git a/docs/gst/tmpl/gstversion.sgml b/docs/gst/tmpl/gstversion.sgml index 004a212..28b6880 100644 --- a/docs/gst/tmpl/gstversion.sgml +++ b/docs/gst/tmpl/gstversion.sgml @@ -2,7 +2,7 @@ gstversion - +GStreamer version macros diff --git a/docs/manual/advanced-threads.xml b/docs/manual/advanced-threads.xml deleted file mode 100644 index 3877366..0000000 --- a/docs/manual/advanced-threads.xml +++ /dev/null @@ -1,166 +0,0 @@ - - Threads - - GStreamer has support for multithreading through the use of - the GstThread object. This object is in fact - a special GstBin that will become a thread when started. - - - - To construct a new thread you will perform something like: - - - - - GstElement *my_thread; - - /* create the thread object */ - my_thread = gst_thread_new ("my_thread"); - /* you could have used gst_element_factory_make ("thread", "my_thread"); */ - g_return_if_fail (my_thread != NULL); - - /* add some plugins */ - gst_bin_add (GST_BIN (my_thread), GST_ELEMENT (funky_src)); - gst_bin_add (GST_BIN (my_thread), GST_ELEMENT (cool_effect)); - - /* link the elements here... */ - ... - - /* start playing */ - gst_element_set_state (GST_ELEMENT (my_thread), GST_STATE_PLAYING); - - - - - The above program will create a thread with two elements in it. As soon - as it is set to the PLAYING state, the thread will start to iterate - itself. You never need to explicitly iterate a thread. - - - - Constraints placed on the pipeline by the GstThread - - Within the pipeline, everything is the same as in any other bin. The - difference lies at the thread boundary, at the link between the - thread and the outside world (containing bin). Since GStreamer is - fundamentally buffer-oriented rather than byte-oriented, the natural - solution to this problem is an element that can "buffer" the buffers - between the threads, in a thread-safe fashion. This element is the - queue, described more fully in . It doesn't - matter if the queue is placed in the containing bin or in the thread - itself, but it needs to be present on one side or the other to enable - inter-thread communication. - - - - When would you want to use a thread? - - If you are writing a GUI application, making the top-level bin a thread will make your GUI - more responsive. If it were a pipeline instead, it would have to be iterated by your - application's event loop, which increases the latency between events (say, keyboard presses) - and responses from the GUI. In addition, any slight hang in the GUI would delay iteration of - the pipeline, which (for example) could cause pops in the output of the sound card, if it is - an audio pipeline. - - - shows how a thread can be visualised. - -
- A thread - - - - - -
- - - As an example we show the helloworld program using a thread. - - - - -/* example-begin threads.c */ -#include <gst/gst.h> - -/* we set this to TRUE right before gst_main (), but there could still - be a race condition between setting it and entering the function */ -gboolean can_quit = FALSE; - -/* eos will be called when the src element has an end of stream */ -void -eos (GstElement *src, gpointer data) -{ - GstThread *thread = GST_THREAD (data); - g_print ("have eos, quitting\n"); - - /* stop the bin */ - gst_element_set_state (GST_ELEMENT (thread), GST_STATE_NULL); - - while (!can_quit) /* waste cycles */ ; - gst_main_quit (); -} - -int -main (int argc, char *argv[]) -{ - GstElement *filesrc, *demuxer, *decoder, *converter, *audiosink; - GstElement *thread; - - if (argc < 2) { - g_print ("usage: %s <Ogg/Vorbis filename>\n", argv[0]); - exit (-1); - } - - gst_init (&argc, &argv); - - /* create a new thread to hold the elements */ - thread = gst_thread_new ("thread"); - g_assert (thread != NULL); - - /* create a disk reader */ - filesrc = gst_element_factory_make ("filesrc", "disk_source"); - g_assert (filesrc != NULL); - g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL); - g_signal_connect (G_OBJECT (filesrc), "eos", - G_CALLBACK (eos), thread); - - /* create an ogg demuxer */ - demuxer = gst_element_factory_make ("oggdemux", "demuxer"); - g_assert (demuxer != NULL); - - /* create a vorbis decoder */ - decoder = gst_element_factory_make ("vorbisdec", "decoder"); - g_assert (decoder != NULL); - - /* create an audio converter */ - converter = gst_element_factory_make ("audioconvert", "converter"); - g_assert (decoder != NULL); - - /* and an audio sink */ - audiosink = gst_element_factory_make ("osssink", "play_audio"); - g_assert (audiosink != NULL); - - /* add objects to the thread */ - gst_bin_add_many (GST_BIN (thread), filesrc, demuxer, decoder, converter, audiosink, NULL); - /* link them in the logical order */ - gst_element_link_many (filesrc, demuxer, decoder, converter, audiosink, NULL); - - /* start playing */ - gst_element_set_state (thread, GST_STATE_PLAYING); - - /* do whatever you want here, the thread will be playing */ - g_print ("thread is playing\n"); - - can_quit = TRUE; - gst_main (); - - gst_object_unref (GST_OBJECT (thread)); - - exit (0); -} -/* example-end threads.c */ - - - - diff --git a/docs/manual/autoplugging.xml b/docs/manual/autoplugging.xml index ab417ee..3369f64 100644 --- a/docs/manual/autoplugging.xml +++ b/docs/manual/autoplugging.xml @@ -92,6 +92,7 @@ + Using the <classname>GstAutoplugCache</classname> element The GstAutoplugCache element is used to cache the diff --git a/docs/manual/basics-data.xml b/docs/manual/basics-data.xml deleted file mode 100644 index 026830a..0000000 --- a/docs/manual/basics-data.xml +++ /dev/null @@ -1,65 +0,0 @@ - - Buffers - - Buffers contain the data that will flow through the pipeline you have - created. A source element will typically create a new buffer and pass - it through a pad to the next element in the chain. When using the - GStreamer infrastructure to create a media pipeline you will not have - to deal with buffers yourself; the elements will do that for you. - - - A buffer consists of: - - - - - a pointer to a piece of memory. - - - - - the size of the memory. - - - - - a timestamp for the buffer. - - - - - A refcount that indicates how many elements are using this - buffer. This refcount will be used to destroy the buffer when no - element has a reference to it. - - - - - - - GStreamer provides functions to create custom buffer create/destroy algorithms, called - a GstBufferPool. This makes it possible to efficiently - allocate and destroy buffer memory. It also makes it possible to exchange memory between - elements by passing the GstBufferPool. A video element can, - for example, create a custom buffer allocation algorithm that creates buffers with XSHM - as the buffer memory. An element can use this algorithm to create and fill the buffer - with data. - - - - The simple case is that a buffer is created, memory allocated, data put - in it, and passed to the next element. That element reads the data, does - something (like creating a new buffer and decoding into it), and - unreferences the buffer. This causes the data to be freed and the buffer - to be destroyed. A typical MPEG audio decoder works like this. - - - - A more complex case is when the filter modifies the data in place. It - does so and simply passes on the buffer to the next element. This is just - as easy to deal with. An element that works in place has to be careful when - the buffer is used in more than one element; a copy on write has to made in this - situation. - - - diff --git a/docs/manual/basics-elements.xml b/docs/manual/basics-elements.xml deleted file mode 100644 index 3bd4ff9..0000000 --- a/docs/manual/basics-elements.xml +++ /dev/null @@ -1,118 +0,0 @@ - - Elements - - The most important object in GStreamer for the - application programmer is the GstElement object. - - - - What is an element ? - - An element is the basic building block for the media pipeline. - All the different high-level components you are going to use are - derived from GstElement. This means that a - lot of functions you are going to use operate on objects of this class. - - - Elements, from the perspective of GStreamer, are viewed as "black boxes" - with a number of different aspects. One of these aspects is the presence - of "pads" (see ), or link points. This terminology arises from soldering; - pads are where wires can be attached. - - - - - Types of elements - - - Source elements - - Source elements generate data for use by a pipeline, for example - reading from disk or from a sound card. - - - shows how we will visualise - a source element. - We always draw a source pad to the right of the element. - -
- Visualisation of a source element - - - - - -
- - Source elements do not accept data, they only generate data. You can - see this in the figure because it only has a source pad. A source - pad can only generate data. - - - - - Filters and codecs - - Filter elements have both input and output pads. They operate on - data they receive in their sink pads and produce data on their source - pads. For example, MPEG decoders and volume filters would fall into - this category. - - - Elements are not constrained as to the number of pads they might have; - for example, a video mixer might have two input pads (the images of - the two different video streams) and one output pad. - -
- Visualisation of a filter element - - - - - -
- - shows how we will visualise - a filter element. - This element has one sink (input) pad and one source (output) pad. - Sink pads are drawn on the left of the element. - -
- Visualisation of a filter element with - more than one output pad - - - - - -
- - shows the visualisation of a filter element with - more than one output pad. An example of such a filter is the AVI - demultiplexer. This element will parse the input data and - extract the audio and video data. Most of these filters dynamically - send out a signal when a new pad is created so that the application - programmer can link an arbitrary element to the newly created pad. - - - - - Sink elements - - Sink elements are end points in a media pipeline. They accept - data but do not produce anything. Disk writing, soundcard playback, - and video output would all be implemented by sink elements. - shows a sink element. - -
- Visualisation of a sink element - - - - - -
- - - diff --git a/docs/manual/basics-helloworld.xml b/docs/manual/basics-helloworld.xml deleted file mode 100644 index 4910bc1..0000000 --- a/docs/manual/basics-helloworld.xml +++ /dev/null @@ -1,279 +0,0 @@ - - Your first 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, - pausing and stopping the pipeline. - - - - Hello world - - We will create a simple first application, a complete MP3 player, using - standard GStreamer components. The player - will read from a file that is given as the first argument to the program. - - - -/* example-begin helloworld.c */ -#include <gst/gst.h> - -int -main (int argc, char *argv[]) -{ - GstElement *pipeline, *filesrc, *decoder, *audiosink; - - gst_init(&argc, &argv); - - if (argc != 2) { - g_print ("usage: %s <mp3 filename>\n", argv[0]); - exit (-1); - } - - /* create a new pipeline to hold the elements */ - pipeline = gst_pipeline_new ("pipeline"); - - /* create a disk reader */ - filesrc = gst_element_factory_make ("filesrc", "disk_source"); - g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL); - - /* now it's time to get the decoder */ - decoder = gst_element_factory_make ("mad", "decoder"); - - /* and an audio sink */ - audiosink = gst_element_factory_make ("osssink", "play_audio"); - - /* add objects to the main pipeline */ - gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL); - - /* link src to sink */ - gst_element_link_many (filesrc, decoder, audiosink, NULL); - - /* start playing */ - gst_element_set_state (pipeline, GST_STATE_PLAYING); - - while (gst_bin_iterate (GST_BIN (pipeline))); - - /* stop the pipeline */ - gst_element_set_state (pipeline, GST_STATE_NULL); - - /* we don't need a reference to these objects anymore */ - gst_object_unref (GST_OBJECT (pipeline)); - /* unreffing the pipeline unrefs the contained elements as well */ - - exit (0); -} -/* example-end helloworld.c */ - - - - Let's go through this example step by step. - - - - The first thing you have to do is to include the standard - GStreamer headers and - initialize the framework. - - - -#include <gst/gst.h> - - ... - -int -main (int argc, char *argv[]) -{ - ... - gst_init(&argc, &argv); - ... - - - - - We are going to create three elements and one pipeline. Since all - elements share the same base type, GstElement, - we can define them as: - - - ... - GstElement *pipeline, *filesrc, *decoder, *audiosink; - ... - - - - 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 pack into it. - - - /* create a new pipeline to hold the elements */ - pipeline = gst_pipeline_new ("pipeline"); - - - We use the standard constructor for a pipeline: gst_pipeline_new (). - - - - We then create a disk source element. The disk source element is able to - read from a file. We use the standard GObject property mechanism to set - a property of the element: the file to read from. - - - /* create a disk reader */ - filesrc = gst_element_factory_make ("filesrc", "disk_source"); - g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL); - - - - You can check if the filesrc != NULL to verify the creation of the - disk source element. - - - - - We now create the MP3 decoder element. This assumes that the 'mad' plugin - is installed on the system where this application is executed. - - - /* now it's time to get the decoder */ - decoder = gst_element_factory_make ("mad", "decoder"); - - - gst_element_factory_make() takes two arguments: a string that will - 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/pipeline. - - - - Finally we create our audio sink element. This element will be able - to play back the audio using OSS. - - - /* and an audio sink */ - audiosink = gst_element_factory_make ("osssink", "play_audio"); - - - - We then add the elements to the pipeline. - - - /* add objects to the main pipeline */ - gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL); - - - - We link the different pads of the elements together like this: - - - /* link src to sink */ - gst_element_link_many (filesrc, decoder, audiosink, NULL); - - - - We now have created a complete pipeline. We can visualise the - pipeline as follows: - -
- The "hello world" pipeline - - - - - - -
- - - Everything is now set up to start streaming. We use the following - statements to change the state of the pipeline: - - - /* start playing */ - gst_element_set_state (pipeline, GST_STATE_PLAYING); - - - - - GStreamer will take care of the READY and PAUSED state for - you when going from NULL to PLAYING. - - - - - Since we do not use threads, nothing will happen yet. We have to - call gst_bin_iterate() to execute one iteration of the pipeline. - - - while (gst_bin_iterate (GST_BIN (pipeline))); - - - The gst_bin_iterate() function will return TRUE as long as something - interesting happened 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 pipeline */ - gst_element_set_state (pipeline, GST_STATE_NULL); - - gst_object_unref (GST_OBJECT (pipeline)); - - exit (0); - - - - Don't forget to set the state of the pipeline to NULL. This will free - all of the resources held by the elements. - - - - - - - Compiling helloworld.c - - To compile the helloworld example, use: - - - gcc -Wall `pkg-config gstreamer-&GST_MAJORMINOR; --cflags --libs` helloworld.c \ - -o helloworld - - - We use pkg-config to get the compiler flags needed to compile - this application. Make sure to have your PKG_CONFIG_PATH environment - variable set to the correct location if you are building this - application against the uninstalled location. - - - You can run the example with - (substitute helloworld.mp3 with you favorite MP3 file): - - - ./helloworld helloworld.mp3 - - - - - Conclusion - - This concludes our first example. As you see, setting up a pipeline - is very low-level but powerful. You will see later in this manual how - you can create a custom MP3 element with a higher-level API. - - - It should be clear from the example that we can very easily replace the - filesrc element with the gnomevfssrc element, giving you instant streaming - from any gnomevfs URL. - - - We can also choose to use another type of sink instead of the audiosink. - We could use a filesink to write the raw samples to a file, for example. - It should also be clear that inserting filters, like a stereo effect, - into the pipeline is not that hard to do. The most important thing is - that you can reuse already existing elements. - - - diff --git a/docs/manual/basics-pads.xml b/docs/manual/basics-pads.xml deleted file mode 100644 index c668843..0000000 --- a/docs/manual/basics-pads.xml +++ /dev/null @@ -1,243 +0,0 @@ - - Pads - - As we have seen in , the pads are the element's - interface to 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(see - ) - - - - Pads are either source or sink pads. The terminology is defined from the - view of the element itself: elements accept data on their sink pads, and - send data out on their source pads. Sink pads are drawn on the left, - while source pads are drawn on the right of an element. In general, - data flows from left to right in the graph. - - In reality, there is no objection to data flowing from a - source pad to the sink pad of an element upstream. Data will, however, - always flow from a source pad of one element to the sink pad of - another. - - - - - Types of pad - - - Dynamic pads - - Some elements might not have all of their pads when the element is - created. This - can happen, for example, with an MPEG system demultiplexer. The - demultiplexer will create its pads at runtime when it detects the - different elementary streams in the MPEG system stream. - - - Running gst-inspect mpegdemux will show that - the element has only one pad: a sink pad called 'sink'. The other pads are - "dormant". You can see this in the pad template because there is - an 'Exists: Sometimes' - property. Depending on the type of MPEG file you play, the pads will - be created. We - will see that this is very important when you are going to create dynamic - pipelines later on in this manual. - - - - Request pads - - An element can also have request pads. These pads are not created - automatically but are only created on demand. This is very useful - for multiplexers, aggregators and tee elements. - - - The tee element, for example, has one input pad and a request padtemplate for the - output pads. Whenever an element wants to get an output pad from the tee element, it - has to request the pad. - - - - - - - Capabilities of a pad - - 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 data that can - flow through 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 - Plugin Writer's Guide. - - - - Capabilities - - Capabilities are attached to a pad in order to describe - what type of media the pad can handle. - - - Capabilities is shorthand for "capability chain". A capability chain - is a chain of one capability or more. - - - The basic entity is a capability, and is defined by a name, a MIME - type and a set of properties. A capability can be chained to - another capability, which is why we commonly refer to a chain of - capability entities as "capabilities". - - - It is important to understand that the term "capabilities" refers - to a chain of one capability or more. This will be clearer when - you see the structure definition of a GstCaps - element. - - - - - Below is a dump of the capabilities of the element mad, as shown by - gst-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 source 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 template: 'sink' - Availability: Always - Capabilities: - 'mad_sink': - MIME type: 'audio/mp3': - - SRC template: 'src' - Availability: Always - Capabilities: - 'mad_src': - MIME type: 'audio/raw': - format: String: int - endianness: Integer: 1234 - width: Integer: 16 - depth: Integer: 16 - channels: Integer range: 1 - 2 - law: Integer: 0 - signed: Boolean: TRUE - rate: Integer range: 11025 - 48000 - - - - What are properties ? - - Properties are used to describe extra information for - capabilities. A property consists of a key (a string) and - a value. There are different possible value types that can be used: - - - - - - basic types: - - - - - an integer value: the property has this exact value. - - - - - a boolean value: the property is either TRUE or FALSE. - - - - - a fourcc value: this is a value that is commonly used to - describe an encoding for video, - as used for example by the AVI specification. - - fourcc values consist of four bytes. - The FOURCC - Definition List is the most complete resource - on the allowed fourcc values. - - - - - - a float value: the property has this exact floating point value. - - - - - a string value. - - - - - - - - range types: - - - - - an integer range value: the property denotes a range of - possible integers. For example, the wavparse element has - a source pad where the "rate" property can go from 8000 to - 48000. - - - - - a float range value: the property denotes a range of possible - floating point values. - - - - - - - a list value: the property can take any value from a list of - basic value types or range types. - - - - - - - What capabilities are used for - - Capabilities describe in great detail the type of media that is handled by the pads. - They are mostly used for: - - - - - Autoplugging: automatically finding plugins for a set of capabilities - - - - - Compatibility detection: when two pads are linked, GStreamer - can verify if the two pads are talking about the same media types. - The process of linking two pads and checking if they are compatible - is called "caps negotiation". - - - - - - diff --git a/docs/manual/bins-api.xml b/docs/manual/bins-api.xml index 95a3edf..7b6dd9a 100644 --- a/docs/manual/bins-api.xml +++ b/docs/manual/bins-api.xml @@ -119,7 +119,8 @@ Note that the above code assumes that the mp3player bin derives itself - from a GstThread, which begins to play as soon + from a GstThread, which begins to play as soon as its state is set to PLAYING. Other bin types may need explicit iteration. For more information, see . @@ -137,7 +138,8 @@ This is where "ghost pads" come into play.
- Visualisation of a <classname>GstBin</classname> element without ghost pads + Visualisation of a <ulink type="http" + url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink> element without ghost pads @@ -152,7 +154,8 @@
- Visualisation of a <classname>GstBin</classname> element with a ghost pad + Visualisation of a <ulink type="http" + url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink> element with a ghost pad @@ -165,8 +168,9 @@ of the bin. - Ghost pads can actually be added to all GstElements and not just - GstBins. Use the following code example to add a ghost pad to a bin: + Ghost pads can actually be added to all GstElements and not just + GstBins. Use the following code example to add a ghost pad to a bin: GstElement *bin; diff --git a/docs/manual/buffers.xml b/docs/manual/buffers.xml index 026830a..2fef01a 100644 --- a/docs/manual/buffers.xml +++ b/docs/manual/buffers.xml @@ -36,7 +36,8 @@ - + + GStreamer provides functions to create custom buffer create/destroy algorithms, called a GstBufferPool. This makes it possible to efficiently allocate and destroy buffer memory. It also makes it possible to exchange memory between diff --git a/docs/manual/cothreads.xml b/docs/manual/cothreads.xml index 450a26f..20f141a 100644 --- a/docs/manual/cothreads.xml +++ b/docs/manual/cothreads.xml @@ -6,7 +6,9 @@ from other user-space threading libraries in that they are scheduled explictly by GStreamer. - A cothread is created by a GstBin whenever an element is found + A cothread is created by a GstBin + whenever an element is found inside the bin that has one or more of the following properties: @@ -25,7 +27,8 @@ - The GstBin will create a cothread context for all the elements + The GstBin + will create a cothread context for all the elements in the bin so that the elements will interact in cooperative multithreading. @@ -117,7 +120,9 @@ chain_function (GstPad *pad, GstBuffer *buffer) bytestream library will need to be loop-based. - There is no problem in putting cothreaded elements into a GstThread to + There is no problem in putting cothreaded elements into a GstThread + to create even more complex pipelines with both user and kernel space threads. diff --git a/docs/manual/elements-api.xml b/docs/manual/elements-api.xml index 79daf5b..b51d490 100644 --- a/docs/manual/elements-api.xml +++ b/docs/manual/elements-api.xml @@ -3,9 +3,12 @@ Creating a GstElement - A GstElement object is created from - a factory. To create an element, you have to get access to a - GstElementFactory object using a unique + A GstElement + object is created from a factory. + To create an element, you have to get access to a + + GstElementFactory object using a unique factory name. @@ -58,14 +61,16 @@ GstElement properties - A GstElement can have several properties + A + GstElement can have several properties which are implemented using standard GObject properties. The usual GObject methods to query, set and get property values and GParamSpecs are therefore supported. - Every GstElement inherits at least + Every + GstElement inherits at least one property of its parent GstObject: the "name" property. This is the name you provide to the functions gst_element_factory_make or @@ -108,7 +113,8 @@ GstElement signals - A GstElement also provides various + A + GstElement also provides various GObject signals that can be used as a flexible callback mechanism. diff --git a/docs/manual/elements.xml b/docs/manual/elements.xml index 3bd4ff9..0ce686c 100644 --- a/docs/manual/elements.xml +++ b/docs/manual/elements.xml @@ -2,7 +2,9 @@ Elements The most important object in GStreamer for the - application programmer is the GstElement object. + application programmer is the GstElement + object. @@ -10,14 +12,16 @@ An element is the basic building block for the media pipeline. All the different high-level components you are going to use are - derived from GstElement. This means that a + derived from + GstElement. This means that a lot of functions you are going to use operate on objects of this class. Elements, from the perspective of GStreamer, are viewed as "black boxes" with a number of different aspects. One of these aspects is the presence - of "pads" (see ), or link points. This terminology arises from soldering; - pads are where wires can be attached. + of "pads" (see ), or link points. + This terminology arises from soldering; pads are where wires can be + attached. diff --git a/docs/manual/helloworld.xml b/docs/manual/helloworld.xml index 4910bc1..68611b4 100644 --- a/docs/manual/helloworld.xml +++ b/docs/manual/helloworld.xml @@ -93,7 +93,8 @@ main (int argc, char *argv[]) We are going to create three elements and one pipeline. Since all - elements share the same base type, GstElement, + elements share the same base type, GstElement, we can define them as: diff --git a/docs/manual/links-api.xml b/docs/manual/links-api.xml index aae23e3..ac0d4bd 100644 --- a/docs/manual/links-api.xml +++ b/docs/manual/links-api.xml @@ -59,19 +59,22 @@ - You can query if a pad is linked with GST_PAD_IS_LINKED (pad). + You can query if a pad is linked with + GST_PAD_IS_LINKED (pad). - To query for the GstPad a pad is linked to, use - gst_pad_get_peer (pad). + To query for the GstPad + a pad is linked to, use gst_pad_get_peer (pad). Making filtered links - You can also force a specific media type on the link by using gst_pad_link_filtered () - and gst_element_link_filtered () with capabilities. + You can also force a specific media type on the link by using + gst_pad_link_filtered () + and gst_element_link_filtered () with capabilities. See for an explanation of capabilities. diff --git a/docs/manual/manual.xml b/docs/manual/manual.xml index 07f6321..a235195 100644 --- a/docs/manual/manual.xml +++ b/docs/manual/manual.xml @@ -123,9 +123,11 @@ For a gentle introduction to this system, you may wish to read the GTK+ - Tutorial or Eric Harlow's book Developing - Linux Applications with GTK+ and GDK. - + Tutorial, Eric Harlow's book Developing + Linux Applications with GTK+ and GDK and the + Glib Object + system. diff --git a/docs/manual/pads-api.xml b/docs/manual/pads-api.xml index 5256c97..e92b423 100644 --- a/docs/manual/pads-api.xml +++ b/docs/manual/pads-api.xml @@ -190,8 +190,9 @@ struct _GstCaps { 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: - + + GstCaps structure is: + GstCaps* gst_caps_new (const gchar *name, const gchar *mime, GstProps *props); diff --git a/docs/manual/pads.xml b/docs/manual/pads.xml index c668843..e7a44f6 100644 --- a/docs/manual/pads.xml +++ b/docs/manual/pads.xml @@ -95,8 +95,9 @@ It is important to understand that the term "capabilities" refers to a chain of one capability or more. This will be clearer when - you see the structure definition of a GstCaps - element. + you see the structure definition of a GstCaps + element. diff --git a/docs/manual/threads.xml b/docs/manual/threads.xml index 3877366..05ea3cd 100644 --- a/docs/manual/threads.xml +++ b/docs/manual/threads.xml @@ -2,8 +2,10 @@ Threads GStreamer has support for multithreading through the use of - the GstThread object. This object is in fact - a special GstBin that will become a thread when started. + the + GstThread object. This object is in fact + a special + GstBin that will become a thread when started. diff --git a/docs/pwg/advanced-events.xml b/docs/pwg/advanced-events.xml index 5c51e66..5517ec9 100644 --- a/docs/pwg/advanced-events.xml +++ b/docs/pwg/advanced-events.xml @@ -158,9 +158,13 @@ gst_my_filter_handle_src_event (GstPad *pad, In this chapter follows a list of all defined events that are currently being used, plus how they should be used/interpreted. Events are stored - in a GstEvent structure, which is simply a big - C union with the types for each event in it. For the next development - cycle, we intend to switch events over to GstStructure, + in a GstEvent + structure, which is simply a big C union with the + types for each event in it. For the next development cycle, we intend to + switch events over to GstStructure + , but you don't need to worry about that too much for now. @@ -194,7 +198,7 @@ gst_my_filter_handle_src_event (GstPad *pad, . - The EOS event (GST_EVENT_EOS) has no properties, + The EOS event (GST_EVENT_EOS) has no properties, and that makes it one of the simplest events in &GStreamer;. It is created using gst_event_new (GST_EVENT_EOS);. @@ -246,12 +250,12 @@ gst_my_filter_handle_src_event (GstPad *pad, and a modified event should be sent on. The last is true for demuxers, which generally have a byte-to-time conversion concept. Their input is usually byte-based, so the incoming event will have an offset in - byte units (GST_FORMAT_BYTES), too. Elements + byte units (GST_FORMAT_BYTES), too. Elements downstream, however, expect discontinuity events in time units, so that it can be used to update the pipeline clock. Therefore, demuxers and similar elements should not forward the event, but parse it, free it and send a new discontinuity event (in time units, - GST_FORMAT_TIME) further downstream. + GST_FORMAT_TIME) further downstream. The discontinuity event is created using the function diff --git a/docs/pwg/advanced-interfaces.xml b/docs/pwg/advanced-interfaces.xml index dc66a51..4e810535 100644 --- a/docs/pwg/advanced-interfaces.xml +++ b/docs/pwg/advanced-interfaces.xml @@ -37,7 +37,9 @@ at their own will. We've also created a small extension to GTypeInterface (which is static itself, too) which allows us to query for interface availability based on runtime properties. - This extension is called GstImplementsInterface. + This extension is called + GstImplementsInterface. One important note: interfaces do not replace @@ -57,13 +59,16 @@ will be notified of doing that wrongly when using the element: it will quit with failed assertions, which will explain what went wrong. In the case of GStreamer, the only dependency that some - interfaces have is GstImplementsInterface. Per + interfaces have is + GstImplementsInterface. Per interface, we will indicate clearly when it depends on this extension. If it does, you need to register support for that interface before registering support for the interface that you're wanting to support. The example below explains how to add support for a simple interface with no further dependencies. For a small explanation - on GstImplementsInterface, see the next section + on + GstImplementsInterface, see the next section about the mixer interface: . @@ -127,13 +132,16 @@ gst_my_filter_some_interface_init (GstSomeInterface *iface) and input/output settings. - The mixer interface requires the GstImplementsInterface + The mixer interface requires the + GstImplementsInterface interface to be implemented by the element. The example below will - feature both, so it serves as an example for the - GstImplementsInterface, too. In the - GstImplementsInterface, it is required to set a - function pointer for the supported () function. If - you don't, this function will always return FALSE (default + feature both, so it serves as an example for the + GstImplementsInterface, too. In this + interface, it is required to set a function pointer for the + supported () function. + If you don't, this function will always return FALSE (default implementation) and the mixer interface implementation will not work. For the mixer interface, the only required function is list_tracks (). All other function pointers in the @@ -307,7 +315,9 @@ gst_my_filter_mixer_interface_init (GstMixerClass *iface) highly analog-video-centric. - This interface requires the GstImplemensInterface + This interface requires the + GstImplemensInterface interface to work correctly. @@ -454,7 +464,7 @@ gst_my_filter_tuner_interface_init (GstTunerClass *iface) Property probing stores the list of allowed (or recommended) values in a GValueArray and returns that to the user. - NULL is a valid return value, too. The process of + NULL is a valid return value, too. The process of property probing is separated over two virtual functions: one for probing the property to create a GValueArray, and one to retrieve the current GValueArray. Those two are @@ -462,12 +472,13 @@ gst_my_filter_tuner_interface_init (GstTunerClass *iface) this simpliies interface implementation in elements. For the application, there are functions that wrap those two. For more information on this, have a look at the API reference for the + GstPropertyProbe interface. Below is a example of property probing for the audio filter element; it will probe for allowed values for the silent property. - Indeed, this value is a gboolean so it doesn't + Indeed, this value is a gboolean so it doesn't make much sense. Then again, it's only an example. diff --git a/docs/pwg/advanced-tagging.xml b/docs/pwg/advanced-tagging.xml index 677ce64..de260af 100644 --- a/docs/pwg/advanced-tagging.xml +++ b/docs/pwg/advanced-tagging.xml @@ -32,21 +32,32 @@ once as streaminfo. + A tag reading element is called TagGetter in - &GStreamer;. A tag writer is called TagSetter. An - element supporting both can be used in a tag editor for quick tag changing. + &GStreamer;. + A tag writer is called TagSetter. + An element supporting both can be used in a tag editor for quick tag + changing. Reading Tags from Streams - The basic object for tags is a GstTagList. An - element that is reading tags from a stream should create an empty taglist - and fill this with individual tags. Empty tag lists can be created with - gst_tag_list_new (). Then, the element can fill the - list using gst_tag_list_add_values (). Note that - an element probably reads metadata as strings, but values might not - necessarily be strings. Be sure to use gst_value_transform () + The basic object for tags is a GstTagList + . An element that is reading tags from a stream should + create an empty taglist and fill this with individual tags. Empty tag + lists can be created with gst_tag_list_new (). Then, + the element can fill the list using gst_tag_list_add_values () + . Note that an element probably reads metadata as strings, but + values might not necessarily be strings. Be sure to use + gst_value_transform () to make sure that your data is of the right type. After data reading, the application can be notified of the new taglist by calling gst_element_found_tags (). The tags should also be @@ -160,7 +171,7 @@ gst_my_filter_class_init (GstMyFilterClass *klass) reader, too. Application tags are tags provided to the element via the TagSetter interface (which is just a layer). Pipeline tags are tags provided to the element from within the pipeline. The element receives - such tags via the GST_EVENT_TAG event, which means + such tags via the GST_EVENT_TAG event, which means that tags writers should automatically be event aware. The tag writer is responsible for combining all these three into one list and writing them to the output stream. diff --git a/docs/pwg/building-pads.xml b/docs/pwg/building-pads.xml index d7fd79a..35c4b89 100644 --- a/docs/pwg/building-pads.xml +++ b/docs/pwg/building-pads.xml @@ -63,11 +63,12 @@ gst_my_filter_init (GstMyFilter *filter) is the process where the linked pads decide on the streamtype that will transfer between them. A full list of type-definitions can be found in . A _link () - receives a pointer to a GstCaps struct that - defines the proposed streamtype, and can respond with either - yes (GST_PAD_LINK_OK), - no (GST_PAD_LINK_REFUSED) or - don't know yet (GST_PAD_LINK_DELAYED). + receives a pointer to a GstCaps + struct that defines the proposed streamtype, and can respond with + either yes (GST_PAD_LINK_OK), + no (GST_PAD_LINK_REFUSED) or + don't know yet (GST_PAD_LINK_DELAYED). If the element responds positively towards the streamtype, that type will be used on the pad. An example: @@ -115,8 +116,11 @@ gst_my_filter_link (GstPad *pad, In here, we check the mimetype of the provided caps. Normally, you don't need to do that in your own plugin/element, because the core does that for you. We simply use it to show how to retrieve the mimetype from a - provided set of caps. Types are stored in GstStructure - internally. A GstCaps is nothing more than a small + provided set of caps. Types are stored in GstStructure + internally. A GstCaps + is nothing more than a small wrapper for 0 or more structures/types. From the structure, you can also retrieve properties, as is shown above with the function gst_structure_get_int (). diff --git a/docs/pwg/building-state.xml b/docs/pwg/building-state.xml index 4815015..67831e9 100644 --- a/docs/pwg/building-state.xml +++ b/docs/pwg/building-state.xml @@ -5,53 +5,53 @@ A state describes whether the element instance is initialized, whether it is ready to transfer data and whether it is currently handling data. There - are four states defined in &GStreamer;: GST_STATE_NULL, - GST_STATE_READY, GST_STATE_PAUSED - and GST_STATE_PLAYING. + are four states defined in &GStreamer;: GST_STATE_NULL, + GST_STATE_READY, GST_STATE_PAUSED + and GST_STATE_PLAYING. - GST_STATE_NULL (from now on referred to as + GST_STATE_NULL (from now on referred to as NULL) is the default state of an element. In this state, it has not allocated any runtime resources, it has not loaded any runtime libraries and it can obviously not handle data. - GST_STATE_READY (from now on referred to as + GST_STATE_READY (from now on referred to as READY) is the next state that an element can be in. In the READY state, an element has all default resources (runtime-libraries, runtime-memory) allocated. However, it has not yet allocated or defined anything that is stream-specific. When going from NULL to READY state - (GST_STATE_NULL_TO_READY), an element should + (GST_STATE_NULL_TO_READY), an element should allocate any non-stream-specific resources and should load runtime-loadable libraries (if any). When going the other way around (from READY to NULL, - GST_STATE_READY_TO_NULL), an element should unload + GST_STATE_READY_TO_NULL), an element should unload these libraries and free all allocated resources. Examples of such resources are hardware devices. Note that files are generally streams, and these should thus be considered as stream-specific resources; therefore, they should not be allocated in this state. - GST_STATE_PAUSED (from now on referred to as + GST_STATE_PAUSED (from now on referred to as PAUSED) is a state in which an element is by all means able to handle data; the only 'but' here is that it doesn't actually handle any data. When going from the READY state into the PAUSED state - (GST_STATE_READY_TO_PAUSED), the element will + (GST_STATE_READY_TO_PAUSED), the element will usually not do anything at all: all stream-specific info is generally handled in the _link (), which is called during caps negotiation. Exceptions to this rule are, for example, files: these are considered stream-specific data (since one file is one stream), and should thus be opened in this state change. When going from the PAUSED back to - READY (GST_STATE_PAUSED_TO_READY), all + READY (GST_STATE_PAUSED_TO_READY), all stream-specific data should be discarded. - GST_STATE_PLAYING (from now on referred to as + GST_STATE_PLAYING (from now on referred to as PLAYING) is the highest state that an element can be in. It is similar to PAUSED, except that now, data is actually passing over the pipeline. The transition from PAUSED to PLAYING - (GST_STATE_PAUSED_TO_PLAYING) should be as small + (GST_STATE_PAUSED_TO_PLAYING) should be as small as possible and would ideally cause no delay at all. The same goes for the - reverse transition (GST_STATE_PLAYING_TO_PAUSED). + reverse transition (GST_STATE_PLAYING_TO_PAUSED). diff --git a/docs/pwg/intro-basics.xml b/docs/pwg/intro-basics.xml index 4b03cae..eecbd15 100644 --- a/docs/pwg/intro-basics.xml +++ b/docs/pwg/intro-basics.xml @@ -17,7 +17,8 @@ Elements are at the core of &GStreamer;. In the context of plugin development, an element is an object derived from the - GstElement class. Elements provide some sort of + + GstElement class. Elements provide some sort of functionality when linked with other elements: For example, a source element provides data to a stream, and a filter element acts on the data in a stream. Without elements, &GStreamer; is just a bunch of conceptual @@ -56,9 +57,9 @@ See the &GstLibRef; for the current implementation details of GstElement + url="../../gstreamer/html/GstElement.html">GstElement and GstPlugin. + url="../../gstreamer/html/gstreamer-GstPlugin.html">GstPlugin. @@ -97,7 +98,7 @@ See the &GstLibRef; for the current implementation details of a GstPad. + url="../../gstreamer/html/GstPad.html">GstPad. @@ -192,9 +193,9 @@ See the &GstLibRef; for the current implementation details of a GstData, GstBuffer and GstEvent. + url="../../gstreamer/html/gstreamer-GstData.html">GstData, GstBuffer and GstEvent. diff --git a/docs/pwg/intro-preface.xml b/docs/pwg/intro-preface.xml index fc47f1e..adc0838 100644 --- a/docs/pwg/intro-preface.xml +++ b/docs/pwg/intro-preface.xml @@ -67,7 +67,10 @@ url="http://developer.gnome.org/doc/API/2.0/gobject/index.html">GObject programming. There are several good introductions to the GObject library, including the GTK+ Tutorial. + url="http://www.gtk.org/tutorial/">GTK+ Tutorial and + the Glib Object + system. -- 2.7.4