gstreamer/docs/manual/intro-basics.xml

159 lines
7.2 KiB
XML
Raw Normal View History

docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
<chapter id="chapter-intro-basics">
<title>Foundations</title>
<para><!-- synchronize with PWG -->
docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
This chapter of the guide introduces the basic concepts of &GStreamer;.
Understanding these concepts will be important in reading any of the
rest of this guide, all of them assume understanding of these basic
concepts.
</para>
<sect1 id="section-intro-basics-elements">
<title>Elements</title>
<para>
An <emphasis>element</emphasis> is the most important class of objects
in &GStreamer;. You will usually create a chain of elements linked
together and let data flow through this chain of elements. An element
has one specific function, which can be the reading of data from a
file, decoding of this data or outputting this data to your sound
card (or anything else). By chaining together several such elements,
you create a <emphasis>pipeline</emphasis> that can do a specific task,
for example media playback or capture. &GStreamer; ships with a large
collection of elements by default, making the development of a large
variety of media applications possible. If needed, you can also write
new elements. That topic is explained in great deal in the &GstPWG;.
docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
</para>
</sect1>
<sect1 id="section-intro-basics-pads">
<title>Pads</title>
<para>
docs/manual/: Add scale factor for pdf output. Original commit message from CVS: patch by: Luc Pionchon <luc.pionchon@nokia.com> * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-threads.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-pads.xml: Add scale factor for pdf output. * docs/manual/intro-basics.xml: Switched sections "pads" and "bins" and added a pipeline diagram. * docs/manual/intro-gstreamer.xml: Added more info on gstreamer. * docs/manual/intro-motivation.xml: Commented out the whole section "current problem", which sounds historical and somehow osolete; it could be turned in a positive way and reused to improve the design principles. * docs/manual/intro-preface.xml: - Update URLs to library.gnome.org. - Do not mention GTK+ in preliminary reading (irrelevant). - Mention Plugin Writer's Manual and further reading only in the previous section. - Added a list of most relevant GObject/glib topics. * docs/manual/Makefile.am: * docs/manual/bin-element-ghost.fig: * docs/manual/bin-element-ghost.png: * docs/manual/bin-element-noghost.fig: * docs/manual/bin-element-noghost.png: * docs/manual/bin-element.fig: * docs/manual/bin-element.png: * docs/manual/filter-element-multi.fig: * docs/manual/filter-element-multi.png: * docs/manual/filter-element.fig: * docs/manual/filter-element.png: * docs/manual/gstreamer-overview.png: * docs/manual/hello-world.fig: * docs/manual/hello-world.png: * docs/manual/linked-elements.fig: * docs/manual/linked-elements.png: * docs/manual/mime-world.fig: * docs/manual/mime-world.png: * docs/manual/queue.fig: * docs/manual/queue.png: * docs/manual/simple-player.png: * docs/manual/sink-element.fig: * docs/manual/sink-element.png: * docs/manual/src-element.fig: * docs/manual/src-element.png: * docs/manual/diagrams-general.svg: * docs/manual/diagrams-pipelines.svg: Removed .fig, added .png counterpart. Fixes: #539137
2008-06-27 07:03:05 +00:00
<emphasis>Pads</emphasis> are element's input and output, where
2009-11-28 14:40:30 +00:00
you can connect other elements. They are used to negotiate links and
docs/manual/: Add scale factor for pdf output. Original commit message from CVS: patch by: Luc Pionchon <luc.pionchon@nokia.com> * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-threads.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-pads.xml: Add scale factor for pdf output. * docs/manual/intro-basics.xml: Switched sections "pads" and "bins" and added a pipeline diagram. * docs/manual/intro-gstreamer.xml: Added more info on gstreamer. * docs/manual/intro-motivation.xml: Commented out the whole section "current problem", which sounds historical and somehow osolete; it could be turned in a positive way and reused to improve the design principles. * docs/manual/intro-preface.xml: - Update URLs to library.gnome.org. - Do not mention GTK+ in preliminary reading (irrelevant). - Mention Plugin Writer's Manual and further reading only in the previous section. - Added a list of most relevant GObject/glib topics. * docs/manual/Makefile.am: * docs/manual/bin-element-ghost.fig: * docs/manual/bin-element-ghost.png: * docs/manual/bin-element-noghost.fig: * docs/manual/bin-element-noghost.png: * docs/manual/bin-element.fig: * docs/manual/bin-element.png: * docs/manual/filter-element-multi.fig: * docs/manual/filter-element-multi.png: * docs/manual/filter-element.fig: * docs/manual/filter-element.png: * docs/manual/gstreamer-overview.png: * docs/manual/hello-world.fig: * docs/manual/hello-world.png: * docs/manual/linked-elements.fig: * docs/manual/linked-elements.png: * docs/manual/mime-world.fig: * docs/manual/mime-world.png: * docs/manual/queue.fig: * docs/manual/queue.png: * docs/manual/simple-player.png: * docs/manual/sink-element.fig: * docs/manual/sink-element.png: * docs/manual/src-element.fig: * docs/manual/src-element.png: * docs/manual/diagrams-general.svg: * docs/manual/diagrams-pipelines.svg: Removed .fig, added .png counterpart. Fixes: #539137
2008-06-27 07:03:05 +00:00
data flow
docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
between elements in &GStreamer;. A pad can be viewed as a
<quote>plug</quote> or <quote>port</quote> on an element where
links may be made with other elements, and through which data can
flow to or from those elements. Pads have specific data handling
2010-06-17 07:05:58 +00:00
capabilities: a pad can restrict the type of data that flows
docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
through it. Links are only allowed between two pads when the
allowed data types of the two pads are compatible. Data types are
negotiated between pads using a process called <emphasis>caps
negotiation</emphasis>. Data types are described as a
<classname>GstCaps</classname>.
</para>
<para>
An analogy may be helpful here. A pad is similar to a plug or jack on a
physical device. Consider, for example, a home theater system consisting
of an amplifier, a DVD player, and a (silent) video projector. Linking
the DVD player to the amplifier is allowed because both devices have audio
jacks, and linking the projector to the DVD player is allowed because
both devices have compatible video jacks. Links between the
projector and the amplifier may not be made because the projector and
amplifier have different types of jacks. Pads in &GStreamer; serve the
same purpose as the jacks in the home theater system.
</para>
<para>
For the most part, all data in &GStreamer; flows one way through a link
between elements. Data flows out of one element through one or more
<emphasis>source pads</emphasis>, and elements accept incoming data
through one or more <emphasis>sink pads</emphasis>. Source and sink
elements have only source and sink pads, respectively. Data usually
means buffers (described by the <ulink type="http"
url="&URLAPI;gstreamer-GstBuffer.html"><classname>GstBuffer
</classname></ulink> object) and events (described by the <ulink
type="http" url="&URLAPI;gstreamer-GstEvent.html"><classname>
GstEvent</classname></ulink> object).
docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
</para>
</sect1>
docs/manual/: Add scale factor for pdf output. Original commit message from CVS: patch by: Luc Pionchon <luc.pionchon@nokia.com> * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-threads.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-pads.xml: Add scale factor for pdf output. * docs/manual/intro-basics.xml: Switched sections "pads" and "bins" and added a pipeline diagram. * docs/manual/intro-gstreamer.xml: Added more info on gstreamer. * docs/manual/intro-motivation.xml: Commented out the whole section "current problem", which sounds historical and somehow osolete; it could be turned in a positive way and reused to improve the design principles. * docs/manual/intro-preface.xml: - Update URLs to library.gnome.org. - Do not mention GTK+ in preliminary reading (irrelevant). - Mention Plugin Writer's Manual and further reading only in the previous section. - Added a list of most relevant GObject/glib topics. * docs/manual/Makefile.am: * docs/manual/bin-element-ghost.fig: * docs/manual/bin-element-ghost.png: * docs/manual/bin-element-noghost.fig: * docs/manual/bin-element-noghost.png: * docs/manual/bin-element.fig: * docs/manual/bin-element.png: * docs/manual/filter-element-multi.fig: * docs/manual/filter-element-multi.png: * docs/manual/filter-element.fig: * docs/manual/filter-element.png: * docs/manual/gstreamer-overview.png: * docs/manual/hello-world.fig: * docs/manual/hello-world.png: * docs/manual/linked-elements.fig: * docs/manual/linked-elements.png: * docs/manual/mime-world.fig: * docs/manual/mime-world.png: * docs/manual/queue.fig: * docs/manual/queue.png: * docs/manual/simple-player.png: * docs/manual/sink-element.fig: * docs/manual/sink-element.png: * docs/manual/src-element.fig: * docs/manual/src-element.png: * docs/manual/diagrams-general.svg: * docs/manual/diagrams-pipelines.svg: Removed .fig, added .png counterpart. Fixes: #539137
2008-06-27 07:03:05 +00:00
<sect1 id="section-intro-basics-bins">
<title>Bins and pipelines</title>
<para>
A <emphasis>bin</emphasis> is a container for a collection of elements.
A <emphasis>pipeline</emphasis> is a special subtype of a bin that allows execution of all
of its contained child elements. Since bins are subclasses of elements
themselves, you can mostly control a bin as if it were an element,
thereby abstracting away a lot of complexity for your application. You
can, for example change state on all elements in a bin by changing the
state of that bin itself. Bins also forward bus messages from their
contained children (such as error messages, tag messages or EOS messages).
</para>
<para>
A <emphasis>pipeline</emphasis> is a top-level bin. As you set it to PAUSED or PLAYING state,
data flow will start and media processing will take place. Once started,
pipelines will run in a separate thread until you stop them or the end
of the data stream is reached.
</para>
<figure float="1" id="section-pipeline-img">
<title>&GStreamer; pipeline for a simple ogg player</title>
<mediaobject>
<imageobject>
<imagedata scale="75" fileref="images/simple-player.&image;" format="&IMAGE;" />
</imageobject>
</mediaobject>
</figure>
</sect1>
<sect1 id="section-intro-basics-communication">
<title>Communication</title>
<para>
&GStreamer; provides several mechanisms for communication and data exchange
between the <emphasis>application</emphasis> and the <emphasis>pipeline</emphasis>.
</para>
<itemizedlist>
<listitem>
<para>
<emphasis>buffers</emphasis> are objects for passing streaming data
between elements in the pipeline. Buffers always travel from sources
to sinks (downstream).
</para>
</listitem>
<listitem>
<para>
<emphasis>events</emphasis> are objects sent between elements or from
the application to elements. Events can travel upstream and downstream.
Downstream events can be synchronised to the data flow.
</para>
</listitem>
<listitem>
<para>
<emphasis>messages</emphasis> are objects posted by elements on
the pipeline's message bus, where they will be held for collection
by the application. Messages can be intercepted synchronously from
the streaming thread context of the element posting the message, but
are usually handled asynchronously by the application from the
application's main thread. Messages are used to transmit information
such as errors, tags, state changes, buffering state, redirects etc.
from elements to the application in a thread-safe way.
</para>
</listitem>
<listitem>
<para>
<emphasis>queries</emphasis> allow applications to request information
such as duration or current playback position from the pipeline.
Queries are always answered synchronously. Elements can also use
queries to request information from their peer elements (such as the
file size or duration). They can be used both ways within a pipeline,
but upstream queries are more common.
</para>
</listitem>
</itemizedlist>
<figure float="1" id="section-communication-img">
<title>&GStreamer; pipeline with different communication flows</title>
<mediaobject>
<imageobject>
<imagedata scale="75" fileref="images/communication.&image;" format="&IMAGE;" />
</imageobject>
</mediaobject>
</figure>
</sect1>
docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
</chapter>