From 018a6f381b72bceffccc422f25d1a4a20fa274c6 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Wed, 16 Aug 2000 21:38:57 +0000 Subject: [PATCH] First draft of Chapter 1 (introduction) and Chapter 2 (basic concepts) of the GStreamer manual. Original commit message from CVS: First draft of Chapter 1 (introduction) and Chapter 2 (basic concepts) of the GStreamer manual. --- docs/manual/.gitignore | 4 + docs/manual/BUILD | 19 +++ docs/manual/README | 19 +++ docs/manual/bins.sgml | 66 +++++++++ docs/manual/buffers.sgml | 77 ++++++++++ docs/manual/connections.sgml | 24 ++++ docs/manual/elements.sgml | 95 +++++++++++++ docs/manual/fig/.gitignore | 2 + docs/manual/fig/bin-element.fig | 39 +++++ docs/manual/fig/connected-elements.fig | 36 +++++ docs/manual/fig/filter-element-multi.fig | 21 +++ docs/manual/fig/filter-element.fig | 18 +++ docs/manual/fig/sink-element.fig | 15 ++ docs/manual/fig/src-element.fig | 15 ++ docs/manual/fig/state-diagram.fig | 46 ++++++ docs/manual/goals.sgml | 109 ++++++++++++++ docs/manual/gstreamer-manual.sgml | 173 +++++++++++++++++++++++ docs/manual/intro.sgml | 35 +++++ docs/manual/motivation.sgml | 86 +++++++++++ docs/manual/outline.txt | 81 +++++++++++ docs/manual/states.sgml | 104 ++++++++++++++ 21 files changed, 1084 insertions(+) create mode 100644 docs/manual/.gitignore create mode 100644 docs/manual/BUILD create mode 100644 docs/manual/README create mode 100644 docs/manual/bins.sgml create mode 100644 docs/manual/buffers.sgml create mode 100644 docs/manual/connections.sgml create mode 100644 docs/manual/elements.sgml create mode 100644 docs/manual/fig/.gitignore create mode 100644 docs/manual/fig/bin-element.fig create mode 100644 docs/manual/fig/connected-elements.fig create mode 100644 docs/manual/fig/filter-element-multi.fig create mode 100644 docs/manual/fig/filter-element.fig create mode 100644 docs/manual/fig/sink-element.fig create mode 100644 docs/manual/fig/src-element.fig create mode 100644 docs/manual/fig/state-diagram.fig create mode 100644 docs/manual/goals.sgml create mode 100644 docs/manual/gstreamer-manual.sgml create mode 100644 docs/manual/intro.sgml create mode 100644 docs/manual/motivation.sgml create mode 100644 docs/manual/outline.txt create mode 100644 docs/manual/states.sgml diff --git a/docs/manual/.gitignore b/docs/manual/.gitignore new file mode 100644 index 0000000000..ec60ea3e11 --- /dev/null +++ b/docs/manual/.gitignore @@ -0,0 +1,4 @@ +Makefile +Makefile.in +*.bak +.deps diff --git a/docs/manual/BUILD b/docs/manual/BUILD new file mode 100644 index 0000000000..9a874920bc --- /dev/null +++ b/docs/manual/BUILD @@ -0,0 +1,19 @@ +For now use: + + db2html gstreamer-manual + +You will need the png support for docbook (see GNOME documentation project) + +convert the fig images to png with: + + fig2dev -L png -s 16 fig/.fig images/.png + +Put a link in the gstreamer-manual directory with + + ln -s ../images gstreamer-manual/images + +point your browser to gstreamer-manual/gstreamer.html + +Fix typing errors and correct bad english. +Let me know about the stuff that needs some more explanation. +Let me know about the structure of the document. diff --git a/docs/manual/README b/docs/manual/README new file mode 100644 index 0000000000..9a874920bc --- /dev/null +++ b/docs/manual/README @@ -0,0 +1,19 @@ +For now use: + + db2html gstreamer-manual + +You will need the png support for docbook (see GNOME documentation project) + +convert the fig images to png with: + + fig2dev -L png -s 16 fig/.fig images/.png + +Put a link in the gstreamer-manual directory with + + ln -s ../images gstreamer-manual/images + +point your browser to gstreamer-manual/gstreamer.html + +Fix typing errors and correct bad english. +Let me know about the stuff that needs some more explanation. +Let me know about the structure of the document. diff --git a/docs/manual/bins.sgml b/docs/manual/bins.sgml new file mode 100644 index 0000000000..e959596f84 --- /dev/null +++ b/docs/manual/bins.sgml @@ -0,0 +1,66 @@ + + 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. + + + Bins allow you to combine connected elements into one logical element. You do + not deal with the individual elements anymore but with just one element, the bin. + We will see that this is extremely powerfull when you are going to construct + complex pipelines since it allows you to break up the pipeline in smaller chunks. + + + 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. + + +
+ Visualisation of a <classname>GstBin</classname> element with some elements in it + +
+ + + There are two standard bins available to the GStreamer programmer: + + + + + A pipeline (GstPipeline). Which is a generic container you will + use most of the time. + + + + + A thread (GstThread). All the elements in the thread bin will + run in a separate thread. You will haver to use this bin if you carfully have to + synchronize audio and video for example. You will learn more about threads in.. + + + + + + + The application programmer can create custom bins packed with elements to perform a + specific task. This allow you to write an MPEG audio decoder with just the follwing lines + of code: + + + + // create the mp3player element + GstElement *mp3player = gst_elementfactory_make("mp3player","mp3player"); + // set the source mp3 audio file + gtk_object_set(GTK_OBJECT(mp3player), "location", "helloworld.mp3", NULL); + // tell the mp3player to prepare itself + gst_element_set_state(GST_ELEMENT(mp3player),GST_STATE_READY); + // start playback + gst_element_set_state(GST_ELEMENT(mp3player),GST_STATE_PLAYING); + ... + // pause playback + gst_element_set_state(GST_ELEMENT(mp3player),GST_STATE_PAUSED); + ... + // stop + gst_element_set_state(GST_ELEMENT(mp3player),GST_STATE_NULL); + + + diff --git a/docs/manual/buffers.sgml b/docs/manual/buffers.sgml new file mode 100644 index 0000000000..2af5ce8cbf --- /dev/null +++ b/docs/manual/buffers.sgml @@ -0,0 +1,77 @@ + + 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 the 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. + + + The most important information in the buffer is: + + + + + A pointer to a piece of memory. + + + + + The size of the memory. + + + + + A refcount that indicates how many elements are using this buffer. This refcount + will be used to destroy the buffer when no element is having a reference to it. + + + + + A list of metadata that describes the context of the buffers memory. In the case + of audio data, for example, it would provide the samplerate, depth and channel + count. + + + GStreamer provides a registry where different metadata types can be registered + so that everybody is talking about the same data. + + + + + + + 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 filter. That filter 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 carefull when + the buffer is used in more than one element; a copy on write has to made in this + situation. + + + + Before an element can operate on the buffers memory, is has to check the metadata + attached to it (if any). An MPEG audio decoder has to ignore a buffer with video + metadata (in which case the pipeline is probably constructed by connecting the + wrong elements, anyway). + + + diff --git a/docs/manual/connections.sgml b/docs/manual/connections.sgml new file mode 100644 index 0000000000..814aaf1065 --- /dev/null +++ b/docs/manual/connections.sgml @@ -0,0 +1,24 @@ + + Connecting elements + + You can connect the different pads of elements together so that the elements + form a chain. + + +
+ Visualisation of three connected elements + +
+ + By connecting these three elements, we have created a very simple pipeline. The effect + of this will be that the output of the source element (element1) will be used as input + for the filter element (element2). The filter element will do something with the data and + send the result to the final sink element (element3). + + + Imagine the above graph as a simple mpeg audio decoder. The source element is a + disk source, the filter element is the mpeg decoder and the sink element is your + audiocard. We will use this simple graph to construct an mpeg player later + in this manual. + + diff --git a/docs/manual/elements.sgml b/docs/manual/elements.sgml new file mode 100644 index 0000000000..cc35ac47e1 --- /dev/null +++ b/docs/manual/elements.sgml @@ -0,0 +1,95 @@ + + GstElement + + The most important object in GStreamer for the application programmer is + the GstElement object. + + + + What is a GstElement + + The GstElement is the basic building block for the media pipeline. All the + different components you are going to use are derived from this GstElement. + 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 also see that those elements have pads. These are the elements + connections with the 'outside' world. + + + GStreamer source elements (<classname>GstSrc</classname>) + + 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. + We always draw a src pad to the right of the element. + +
+ Visualisation of a <classname>GstSrc</classname> element + +
+ + Source elements do not accept data, they only generate data. You can see + this in the figure because it only has a src pad. A src pad can only + generate buffers. + + + + + GStreamer filter elements (<classname>GstFilter</classname>) + + 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. + + + Examples of a filter element might include: an MPEG decoder, volume filter,... + + + Filters may also contain any number of input pads and output pads. For example, + a video mixer might have to input pads (the images of the two different video + streams) and one output pad. + +
+ Visualisation of a <classname>GstFilter</classname> element + +
+ + The above figure shows the visualisation of a filter element. This element has + one sink pad (input) and one src (output) pad. Sink pads are drawn on the left + of the element. + +
+ Visualisation of a <classname>GstFilter</classname> element with + more than one output pad + +
+ + The above figure shows the visualisation of a filter element with more than one + output pad. An example of such a filter is the AVI splitter. This element will + parse the input data and extracts 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 connect an arbitrary element to the newly created pad. + + + + + GStreamer sink elements (<classname>GstSink</classname>) + + 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 + +
+ + + + diff --git a/docs/manual/fig/.gitignore b/docs/manual/fig/.gitignore new file mode 100644 index 0000000000..194bbf2c29 --- /dev/null +++ b/docs/manual/fig/.gitignore @@ -0,0 +1,2 @@ +*.bak +.deps diff --git a/docs/manual/fig/bin-element.fig b/docs/manual/fig/bin-element.fig new file mode 100644 index 0000000000..a4259a6ef9 --- /dev/null +++ b/docs/manual/fig/bin-element.fig @@ -0,0 +1,39 @@ +#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 +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 diff --git a/docs/manual/fig/connected-elements.fig b/docs/manual/fig/connected-elements.fig new file mode 100644 index 0000000000..0aff06c9f4 --- /dev/null +++ b/docs/manual/fig/connected-elements.fig @@ -0,0 +1,36 @@ +#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 +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 diff --git a/docs/manual/fig/filter-element-multi.fig b/docs/manual/fig/filter-element-multi.fig new file mode 100644 index 0000000000..9cd2a3e624 --- /dev/null +++ b/docs/manual/fig/filter-element-multi.fig @@ -0,0 +1,21 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 5625 2775 7575 2775 7575 4425 5625 4425 5625 2775 +2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 + 5625 3600 6375 3600 6375 4125 5625 4125 5625 3600 +2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 + 6825 3225 7575 3225 7575 3750 6825 3750 6825 3225 +2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 + 6825 3825 7575 3825 7575 4350 6825 4350 6825 3825 +4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 element_name\001 +4 0 0 50 0 16 12 0.0000 4 135 330 5850 3975 sink\001 +4 0 0 50 0 16 12 0.0000 4 135 465 6975 3600 video\001 +4 0 0 50 0 16 12 0.0000 4 135 465 6975 4200 audio\001 diff --git a/docs/manual/fig/filter-element.fig b/docs/manual/fig/filter-element.fig new file mode 100644 index 0000000000..335a54c3b6 --- /dev/null +++ b/docs/manual/fig/filter-element.fig @@ -0,0 +1,18 @@ +#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 + 6825 3600 7575 3600 7575 4125 6825 4125 6825 3600 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 5625 2775 7575 2775 7575 4425 5625 4425 5625 2775 +2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 + 5625 3600 6375 3600 6375 4125 5625 4125 5625 3600 +4 0 0 50 0 16 12 0.0000 4 105 255 7050 3975 src\001 +4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 element_name\001 +4 0 0 50 0 16 12 0.0000 4 135 330 5850 3975 sink\001 diff --git a/docs/manual/fig/sink-element.fig b/docs/manual/fig/sink-element.fig new file mode 100644 index 0000000000..0a52a1b504 --- /dev/null +++ b/docs/manual/fig/sink-element.fig @@ -0,0 +1,15 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 5625 2775 7575 2775 7575 4425 5625 4425 5625 2775 +2 2 0 1 0 6 50 0 20 0.000 0 0 -1 0 0 5 + 5625 3600 6375 3600 6375 4125 5625 4125 5625 3600 +4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 element_name\001 +4 0 0 50 0 16 12 0.0000 4 135 330 5850 3975 sink\001 diff --git a/docs/manual/fig/src-element.fig b/docs/manual/fig/src-element.fig new file mode 100644 index 0000000000..82264aa705 --- /dev/null +++ b/docs/manual/fig/src-element.fig @@ -0,0 +1,15 @@ +#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 + 6825 3600 7575 3600 7575 4125 6825 4125 6825 3600 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 5625 2775 7575 2775 7575 4425 5625 4425 5625 2775 +4 0 0 50 0 16 12 0.0000 4 105 255 7050 3975 src\001 +4 0 0 50 0 16 12 0.0000 4 165 1200 5775 3150 element_name\001 diff --git a/docs/manual/fig/state-diagram.fig b/docs/manual/fig/state-diagram.fig new file mode 100644 index 0000000000..1b10e5db13 --- /dev/null +++ b/docs/manual/fig/state-diagram.fig @@ -0,0 +1,46 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 3600 1950 480 480 3600 1950 3975 2250 +1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 3600 3150 480 480 3600 3150 3975 3450 +1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 3600 4350 480 480 3600 4350 3975 4650 +1 3 0 1 0 7 50 0 -1 0.000 1 0.0000 4875 4350 480 480 4875 4350 5250 4650 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3600 900 3600 1500 +2 2 0 1 7 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1350 750 5550 750 5550 5100 1350 5100 1350 750 +3 2 0 1 0 7 50 0 -1 0.000 0 1 0 3 + 1 1 1.00 60.00 120.00 + 3150 1875 2700 2400 3150 2925 + 0.000 -1.000 0.000 +3 2 0 1 0 7 50 0 -1 0.000 0 1 0 3 + 1 1 1.00 60.00 120.00 + 3150 3150 2700 3675 3150 4200 + 0.000 -1.000 0.000 +3 2 0 1 0 7 50 0 -1 0.000 0 1 0 3 + 1 1 1.00 60.00 120.00 + 3750 3900 4275 3675 4800 3900 + 0.000 -1.000 0.000 +3 2 0 1 0 7 50 0 -1 0.000 0 1 0 3 + 1 1 1.00 60.00 120.00 + 4800 4800 4275 5025 3750 4800 + 0.000 -1.000 0.000 +3 2 0 1 0 7 50 0 -1 0.000 0 1 0 3 + 1 1 1.00 60.00 120.00 + 5175 3975 5175 2475 4050 1725 + 0.000 -1.000 0.000 +3 2 0 1 0 7 50 0 -1 0.000 0 1 0 3 + 1 1 1.00 60.00 120.00 + 3225 4650 1575 3300 3150 1725 + 0.000 -1.000 0.000 +4 0 0 50 0 0 12 0.0000 4 135 480 3375 2025 NULL\001 +4 0 0 50 0 0 12 0.0000 4 135 645 3300 3225 READY\001 +4 0 0 50 0 0 12 0.0000 4 135 810 3225 4425 PLAYING\001 +4 0 0 50 0 0 12 0.0000 4 135 735 4500 4425 PAUSED\001 diff --git a/docs/manual/goals.sgml b/docs/manual/goals.sgml new file mode 100644 index 0000000000..cc062165ee --- /dev/null +++ b/docs/manual/goals.sgml @@ -0,0 +1,109 @@ + + Goals + + GStreamer was designed to provide a solution to the current Linux media + problems. + + + + The design goals + + We descibe what we try to achieve with GStreamer. + + + Clean and powerfull + + GStreamer wants to provide a clean interface to: + + + + + The application programmer who wants to build a media pipeline. + + + + + The plugin programmer. + + + + + + + Object oriented + + Adhere as much as possible to the GTK+ object model. A programmer familiar + with GTK+ will be confortable with GStreamer. + + + GStreamer uses the mechanisems of signals and object arguments. + + + + + Extensible + + All GStreamer Objects can be extended using the GTK+ inheritance methods. + + + All plugins are loaded dynamically and can be extended and upgraded + independently. + + + + + Allow binary only plugins + + plugins are shared libraries that are loaded at runtime. since all the + properties of the plugin can be set using the GtkObject arguments, there + is no need to have any header files installed for the plugins. + + + + + High performance + + High performance is obtained by: + + + + + Using glib g_mem_chunk where possible to minimize dynamic memory + allocation. + + + + + Connections between plugins are extremely light-weight. Data can travel + the pipeline with minimal overhead. + + + + + Provide a mechanism to directly work on the target memory. A + plugin can for example directly write to the X servers shared mem. + Buffers can also point to arbitrary memory like kernel memory. + + + + + Refcounting and copy on write to minimize the amount of memcpy. + Subbufers to efficiently split the data in a buffer. + + + + + Pipelines can be constructed using cothreads to minimize the + threading overhead. Cothreads are a simple user-space method for + switching between subtasks. + + + + + HW acceleration is possible by writing a specialized plugin. + + + + + + diff --git a/docs/manual/gstreamer-manual.sgml b/docs/manual/gstreamer-manual.sgml new file mode 100644 index 0000000000..c6f06593a4 --- /dev/null +++ b/docs/manual/gstreamer-manual.sgml @@ -0,0 +1,173 @@ + + + + + + + + + +]> + + + + + + + + Wim + Taymans + + + wim.taymans@chello.be + + + + + + First Release + 2000 + + 2000 + New Riders Publishing + + + + + This material may be distributed only subject to the terms and + conditions set forth in the Open Publication License, v1.0 or later (the + latest version is presently available at http://www.opencontent.org/openpub/ ) + + + + GStreamer Application Development Manual + + + + + + Overview + + + The first chapter of the book gives you an overview of GStreamer + design goals. Chapter 2 rapidly covers the basics of GStreamer + programming. In chapter 3 we will move on to the examples. + Since GStreamer adheres to the GTK+ programming model, the reader is + assumed to understand the basics of GTK+. + For a gentle introduction to GTK+, you may wish to read the GTK+ + Tutorial or Eric Harlow's book Developing Linux + Applications with GTK+ and GDK. + + + + + &INTRO; + + &MOTIVATION; + + &GOALS; + + + + + Basic concepts + + + We will first describe the basics of the GStreamer programming by + introducing the different objects needed to create a media pipeline. + + + We will use a visual representation of these objects so that we can + visualize the more complex pipelines you will learn to build later on. + + + + + &ELEMENTS; + + &CONNECTIONS; + + &BINS; + + &BUFFERS; + + &STATES; + + + + Building an application + + + + With the basic concepts out of the way, you're ready to start building a + full-scale GStreamer application. This part of the book walks you through the + creation of a generic application skeleton: a source tree using + automake and + autoconf, argument parsing, session + management, internationalization, the main window, dialogs, toolbars, and + menubars. Many examples in Part 2 come from a simple application called + "GnomeHello"; the source code for this application is included in the + back of the book. Of course the "meat" of the application + is up to you; but in Part 3 of the book we'll cover a range of library + features you can use to develop it. + + + + + + + + Advanced GStreamer concepts + + + + Wanna know more? + + + + + + + + XML in GStreamer + + + + Just say how we use it... + + + + + + + + plugin development in GStreamer + + + + A lot of text will follow... + + + + + + + + + Appendices + + + + + + + + + + + + + diff --git a/docs/manual/intro.sgml b/docs/manual/intro.sgml new file mode 100644 index 0000000000..3d230116ca --- /dev/null +++ b/docs/manual/intro.sgml @@ -0,0 +1,35 @@ + + Introduction + + This chapter gives you an overview of the technologies described in this + book. + + + + What is GStreamer? + + GStreamer is a framework for creating streaming media applications. + The fundamental design comes from the video pipeline at Oregon Graduate + Institute, as well as some ideas from DirectShow. + + + + GStreamer's development framework makes it possible to write any + streaming multimedia application. The framework includes several + components to build a full featured media player capable of playing + MPEG1, MPEG2, AVI, MP3, WAV, AU, ... + + + + 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. + + + + This book is about GStreamer from a developer's point of view; it describes + how to write a GStreamer application using the GStreamer libraries and tools. + + + + diff --git a/docs/manual/motivation.sgml b/docs/manual/motivation.sgml new file mode 100644 index 0000000000..352ee914c8 --- /dev/null +++ b/docs/manual/motivation.sgml @@ -0,0 +1,86 @@ + + Motivation + + Linux has historically lagged behind other operating systems in the multimedia + arena. Microsoft's Windows[tm] and Apple's MacOS[tm] both have strong support + for multimedia devices, multimedia content creation, + playback, and realtime processing. Linux, on the other hand, has a poorly integrated + collection of multimedia utilities and applications available, which can hardly compete + with the professional level of software available for MS Windows and MacOS. + + + + Current problems + + We descibe the typical problems in todays media handling on Linux. + + + Multitude of duplicate code + + The Linux user who wishes to hear a sound file must hunt through their collection of + sound file players in order to play the tens of sound file formats in wide use today. + Most of these players basically reimplement the same code over and over again. + + + The Linux developer who wishes to embed a video clip in their application must use + crude hacks to run an external video player. There is no library available that a + developer can use to create a custom media player. + + + + + 'One goal' media players + + Your typical MPEG player was designed to play MPEG video and audio. Most of + these players have implemented a complete infrastructure focused on + achieving their only goal: playback. No provisions were made to add + filters or special effects to the video or audio data. + + + If I wanted to convert an MPEG2 video stream into an AVI file, my best + option would be to take all of the MPEG2 decoding algorithms out + of the player and duplicate them into my own AVI encoder. These + algorithms cannot easily be shared accross applications. + + + + + Non unified plugin mechanisms + + Your typical media player might have a plugin for different media + types. Two media players will typically implement their own plugin + mechanism so that the codecs cannot be easily exchanged. + + + The lack of a unified plugin mechanism also seriously hinders the + creation of binary only codecs. No company is willing to port their + code to all the different plugin mechanisms. + + + + + Provision for network transparency + + No infrastructure is present to allow network transparent media + handling. A distributed MPEG encoder will typically duplicate the + same encoder algorithms found in a non-distributed encoder. + + + No provisions have been made for emerging technologies such as + the GNOME object embedding using BONOBO. + + + + + Catch up with the Windows(tm) world + + We need solid media handling if we want to see Linux succeed on + the desktop. + + + We must clear the road for commercially backed codecs and multimedia + applications so that Linux can become an option for doing multimedia. + + + + diff --git a/docs/manual/outline.txt b/docs/manual/outline.txt new file mode 100644 index 0000000000..092c19a89f --- /dev/null +++ b/docs/manual/outline.txt @@ -0,0 +1,81 @@ +Overview + Introduction + (creating multimedia apps) + (pipeline/plugin based) + + Motivation + (multitude of duplicate code) + (mostly focused on one goal) + (reinvent plugin mechanisms) + (network transparency?) + (catch up with Windows(tm) world) + + Goals + (clean and powerfull) + (building graphs) + (building plugins) + (object oriented) + (using GTK+ object model) + (extensible) + (alow binary only plugins) + (alow high performance) + (HW acceleration) + (efficient memory use) + (kernel buffers etc..) + +Basic concepts + elements + (what is it) + (types) sink, src, filter + (have pads) + connecting elements + bin + (can contain elements) + pipeline + (a complete graph) + buffers + (pass between elements) + (contains data) + (can cary metadata) + (use refcounting) + element states + (null) + (ready) + (paused) + (playing) + +Building apps + helloworld + (fdsrc->mp3decoder->audiosink) + (step by step explanation) + +advanced concepts + threads + queues + cothreads + dynamic pipeline construction + ghost pads + types + type detection + plugin registry + bufferpools + Quality of service + utility functions + + +XML in GStreamer + (saving) + (loading a pipeline) + +Plugin development + buffers + metadata + subbufers + adding pads + libraries + +GStreamer programs + editor + gstplay + + diff --git a/docs/manual/states.sgml b/docs/manual/states.sgml new file mode 100644 index 0000000000..9749c8e6e2 --- /dev/null +++ b/docs/manual/states.sgml @@ -0,0 +1,104 @@ + + Element states + + One you have created a pipeline packed with elements, nothing will happen yet. + This is where the different states come into play. + + + + The different element states + + All elements can be in one of the following four states: + + + + NULL: this is the default state all elements are in when they are created + and are doing nothing. + + + + + READY: An element is ready to start doing something. + + + + + PLAYING: The element is doing something. + + + + + PAUSED: The element is paused for a period of time. + + + + + + + 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 + +
+ + + + + The NULL state + + When you created the pipeline all of the elements will be in the NULL state. There is + nothing spectacular about the NULL state. + + + + Don't forget to reset the pipeline to the NULL state when you are not going to use it + anymore. This will allow the elements to free the resources they might use. + + + + + + The READY state + + You will start the pipeline by first setting it to the READY state. This will allow the + pipeline and all the elements contained in it to prepare themselves for the actions + they are about to perform. + + + The typical actions that an element will perform in the READY state might be to open a file or + 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. + + + + + The PLAYING state + + A Pipeline that is in the READY state can be started by setting it to the PLAYING state. At + that time data will start to flow all the way through the pipeline. + + + + + The PAUSED state + + A pipeline that is playing can be set to the PAUSED state. This will temporarily stop all + data flowing through the pipeline. + + + You can resume the data flow by setting the pipeline back to the PLAYING state. + + + + The PAUSED state is build for temporarily freezing the pipeline. Elements will typically + do not free their resources in the PAUSED state. Use the NULL state if you want to stop + the data flow permanantly. + + + + The pipeline has to be in the PAUSED or NULL state if you want to insert or modify an element + in the pipeline. We will cover dynamic pipeline behaviour in ... + + + +