+2004-12-23 Ronald S. Bultje <rbultje@ronald.bitfreak.net>
+
+ * docs/manual/advanced-dataaccess.xml:
+ Add section on how to use fakesrc/fakesink/identity in your
+ application, plus section on how to embed plugins. Also mention
+ probes.
+ * docs/manual/appendix-checklist.xml:
+ * docs/manual/appendix-debugging.xml:
+ * docs/manual/appendix-gnome.xml:
+ * docs/manual/appendix-integration.xml:
+ Debug -> checklist, GNOME -> integration, add sections on Linux,
+ KDE integration and add other things useful for application
+ development.
+ * docs/manual/manual.xml:
+ Remove some fixmes, update some file pointers.
+ * docs/pwg/appendix-checklist.xml:
+ Fix typo.
+ * docs/pwg/building-boiler.xml:
+ Remove ugly header and add commented fixme.
+ * docs/pwg/pwg.xml:
+ Add fixme.
+ * examples/manual/Makefile.am:
+ Add example for added docs.
+
2004-12-23 Thomas Vander Stichele <thomas at apestaart dot org>
* configure.ac:
--- /dev/null
+<chapter id="chapter-dataaccess">
+ <title>Pipeline manipulation</title>
+ <para>
+ This chapter will discuss how you can manipulate your pipeline in several
+ ways from your application on. Parts of this chapter are downright
+ hackish, so be assured that you'll need some programming knowledge
+ before you start reading this.
+ </para>
+ <para>
+ Topics that will be discussed here include how you can insert data into
+ a pipeline from your application, how to read data from a pipeline,
+ how to manipulate the pipeline's speed, length, starting point and how
+ to listen to a pipeline's data processing.
+ </para>
+
+ <sect1 id="section-data-probe">
+ <title>Data probes</title>
+ <para>
+ Probes are best envisioned as pad listeners. They are attached to a
+ pad in a pipeline, and you can add callback functions to this probe.
+ Those callback functions will be called whenever data is being sent
+ over this pad. The callback can then decide whether the data should
+ be discarded or it can replace the piece of data with another piece
+ of data. In this callback, it can also trigger actions in the
+ application itself. For pipeline manipulation, probes are rather
+ limited, but for pipeline tracking, they can be very useful.
+ </para>
+ </sect1>
+
+ <sect1 id="section-data-spoof">
+ <title>Manually adding or removing data from/to a pipeline</title>
+ <para>
+ Many people have expressed the wish to use their own sources to inject
+ data into a pipeline. Some people have also expressed the wish to grab
+ the output in a pipeline and take care of the actual output inside
+ their application. While either of these methods are stongly
+ discouraged, &GStreamer; offers hacks to do this. <emphasis>However,
+ there is no support for those methods.</emphasis> If it doesn't work,
+ you're on your own. Also, synchronization, thread-safety and other
+ things that you've been able to take for granted so far are no longer
+ guanranteed if you use any of those methods. It's always better to
+ simply write a plugin and have the pipeline schedule and manage it.
+ See the Plugin Writer's Guide for more information on this topic. Also
+ see the next section, which will explain how to embed plugins statically
+ in your application.
+ </para>
+ <para>
+ After all those disclaimers, let's start. There's three possible
+ elements that you can use for the above-mentioned purposes. Those are
+ called <quote>fakesrc</quote> (an imaginary source),
+ <quote>fakesink</quote> (an imaginary sink) and <quote>identity</quote>
+ (an imaginary filter). The same method applies to each of those
+ elements. Here, we will discuss how to use those elements to insert
+ (using fakesrc) or grab (using fakesink or identity) data from a
+ pipeline, and how to set negotiation.
+ </para>
+
+ <sect2 id="section-spoof-handoff">
+ <title>Inserting or grabbing data</title>
+ <para>
+ The three before-mentioned elements (fakesrc, fakesink and identity)
+ each have a <quote>handoff</quote> signal that will be called in
+ the <function>_get ()</function>- (fakesrc) or <function>_chain
+ ()</function>-function (identity, fakesink). In the signal handler,
+ you can set (fakesrc) or get (identity, fakesink) data to/from the
+ provided buffer. Note that in the case of fakesrc, you have to set
+ the size of the provided buffer using the <quote>sizemax</quote>
+ property. For both fakesrc and fakesink, you also have to set the
+ <quote>signal-handoffs</quote> property for this method to work.
+ </para>
+ <para>
+ Note that your handoff function should <emphasis>not</emphasis>
+ block, since this will block pipeline iteration. Also, do not try
+ to use all sort of weird hacks in such functions to accomplish
+ something that looks like synchronization or so; it's not the right
+ way and will lead to issues elsewhere. If you're doing any of this,
+ you're basically misunderstanding the &GStreamer; design.
+ </para>
+ </sect2>
+
+ <sect2 id="section-spoof-format">
+ <title>Forcing a format</title>
+ <para>
+ Sometimes, when using fakesrc as a source in your pipeline, you'll
+ want to set a specific format, for example a video size and format
+ or an audio bitsize and number of channels. You can do this by
+ forcing a specific <classname>GstCaps</classname> on the pipeline,
+ which is possible by using <emphasis>filtered caps</emphasis>. You
+ can set a filtered caps on a link by using
+ <function>gst_pad_link_filtered ()</function>, where the third
+ argument is the format to force on the link.
+ </para>
+ </sect2>
+
+ <sect2 id="section-spoof-example">
+ <title>Example application</title>
+ <para>
+ This example application will generate black/white (it switches
+ every second) video to an X-window output by using fakesrc as a
+ source and using filtered caps to force a format. Since the depth
+ of the image depends on your X-server settings, we use a colorspace
+ conversion element to make sure that the output to your X server
+ will have the correct bitdepth. You can also set timestamps on the
+ provided buffers to override the fixed framerate.
+ </para>
+ <programlisting><!-- example-begin fakesrc.c -->
+#include <string.h> /* for memset () */
+#include <gst/gst.h>
+
+static void
+cb_handoff (GstElement *fakesrc,
+ GstBuffer *buffer,
+ GstPad *pad,
+ gpointer user_data)
+{
+ static gboolean white = FALSE;
+
+ /* this makes the image black/white */
+ memset (GST_BUFFER_DATA (buffer), white ? 0xff : 0x0,
+ GST_BUFFER_SIZE (buffer));
+ white = !white;
+}
+
+gint
+main (gint argc,
+ gchar *argv[])
+{
+ GstElement *pipeline, *fakesrc, *conv, *videosink;
+ GstCaps *filter;
+
+ /* init GStreamer */
+ gst_init (&argc, &argv);
+
+ /* setup pipeline */
+ pipeline = gst_pipeline_new ("pipeline");
+ fakesrc = gst_element_factory_make ("fakesrc", "source");
+ conv = gst_element_factory_make ("ffmpegcolorspace", "conv");
+ videosink = gst_element_factory_make ("ximagesink", "videosink");
+
+ /* setup */
+ filter = gst_caps_new_simple ("video/x-raw-rgb",
+ "width", G_TYPE_INT, 384,
+ "height", G_TYPE_INT, 288,
+ "framerate", G_TYPE_DOUBLE, (gdouble) 1.0,
+ "bpp", G_TYPE_INT, 16,
+ "depth", G_TYPE_INT, 16,
+ "endianness", G_TYPE_INT, G_BYTE_ORDER,
+ NULL);
+ gst_element_link_filtered (fakesrc, conv, filter);
+ gst_element_link (conv, videosink);
+ gst_bin_add_many (GST_BIN (pipeline), fakesrc, conv, videosink, NULL);
+
+ /* setup fake source */
+ g_object_set (G_OBJECT (fakesrc),
+ "signal-handoffs", TRUE,
+ "sizemax", 384 * 288 * 2,
+ "sizetype", 2, NULL);
+ g_signal_connect (fakesrc, "handoff", G_CALLBACK (cb_handoff), NULL);
+
+ /* play */
+ gst_element_set_state (pipeline, GST_STATE_PLAYING);
+ while (gst_bin_iterate (GST_BIN (pipeline))) ;
+
+ /* clean up */
+ gst_element_set_state (pipeline, GST_STATE_NULL);
+ gst_object_unref (GST_OBJECT (pipeline));
+
+ return 0;
+}
+ <!-- example-end fakesrc.c --></programlisting>
+ </sect2>
+ </sect1>
+
+ <sect1 id="section-data-manager">
+ <title>Embedding static elements in your application</title>
+ <para>
+ The <ulink type="http"
+ url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
+ Writer's Guide</ulink> describes in great detail how to write elements
+ for the &GStreamer; framework. In this section, we will solely discuss
+ how to embed such elements statically in your application. This can be
+ useful for application-specific elements that have no use elsewhere in
+ &GStreamer;.
+ </para>
+ <para>
+ Dynamically loaded plugins contain a structure that's defined using
+ <function>GST_PLUGIN_DEFINE ()</function>. This structure is loaded
+ when the plugin is loaded by the &GStreamer; core. The structure
+ contains an initialization function (usually called
+ <function>plugin_init</function>) that will be called right after that.
+ It's purpose is to register the elements provided by the plugin with
+ the &GStreamer; framework. If you want to embed elements directly in
+ your application, the only thing you need to do is to manually run
+ this structure using <function>_gst_plugin_register_static
+ ()</function>. The initialization will then be called, and the elements
+ will from then on be available like any other element, without
+ them having to be dynamically loadable libraries. In the example below,
+ you would be able to call <function>gst_element_factory_make
+ ("my-element-name", "some-name")</function> to create an instance
+ of the element.
+ </para>
+ <programlisting>
+/*
+ * Here, you would write the actual plugin code.
+ */
+
+[..]
+
+static gboolean
+register_elements (GstPlugin *plugin)
+{
+ return gst_element_register (plugin, "my-element-name",
+ GST_RANK_NONE, MY_PLUGIN_TYPE);
+}
+
+static GstPluginDesc plugin_desc = {
+ GST_VERSION_MAJOR,
+ GST_VERSION_MINOR,
+ "my-private-plugins",
+ "Private elements of my application",
+ register_elements,
+ NULL,
+ "0.0.1",
+ "LGPL",
+ "my-application",
+ "http://www.my-application.net/",
+ GST_PADDING_INIT
+};
+
+/*
+ * Call this function right after calling gst_init ().
+ */
+
+void
+my_elements_init (void)
+{
+ _gst_plugin_register_static (&plugin_desc);
+}
+ </programlisting>
+ </sect1>
+</chapter>
-<chapter id="chapter-debugging">
- <title>Debugging</title>
- <para>
- GStreamer has an extensive set of debugging tools for
- plugin developers.
+<chapter id="chapter-checklist-element">
+ <title>Things to check when writing an application</title>
+ <para>
+ This chapter contains a fairly random selection of things that can be
+ useful to keep in mind when writing &GStreamer;-based applications. It's
+ up to you how much you're going to use the information provided here.
+ We will shortly discuss how to debug pipeline problems using &GStreamer;
+ applications. Also, we will touch upon how to acquire knowledge about
+ plugins and elements and how to test simple pipelines before building
+ applications around them.
</para>
-
- <sect1 id="section-debugging-command-line">
- <title>Command line options</title>
- <para>
- Applications using the GStreamer libraries accept the following set
- of command line argruments that help in debugging.
+
+ <sect1 id="section-checklist-programming">
+ <title>Good programming habits</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Always connect to the <quote>error</quote> signal of your topmost
+ pipeline to be notified of errors in your pipeline.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Always check return values of &GStreamer; functions. Especially,
+ check return values of <function>gst_element_link ()</function>
+ and <function>gst_element_set_state ()</function>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Always use your pipeline object to keep track of the current state
+ of your pipeline. Don't keep private variables in your application.
+ Also, don't update your user interface if a user presses the
+ <quote>play</quote> button. Instead, connect to the
+ <quote>state-changed</quote> signal of your topmost pipeline and
+ update the user interface whenever this signal is triggered.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="section-checklist-debug">
+ <title>Debugging</title>
+ <para>
+ Applications can make use of the extensive &GStreamer; debugging system
+ to debug pipeline problems. Elements will write output to this system
+ to log what they're doing. It's not used for error reporting, but it
+ is very useful for tracking what an element is doing exactly, which
+ can come in handy when debugging application issues (such as failing
+ seeks, out-of-sync media, etc.).
</para>
-
- <para>
+ <para>
+ Most &GStreamer;-based applications accept the commandline option
+ <option>--gst-debug=LIST</option> and related family members. The
+ list consists of a comma-separated list of category/level pairs,
+ which can set the debugging level for a specific debugging category.
+ For example, <option>--gst-debug=oggdemux:5</option> would turn
+ on debugging for the Ogg demuxer element. You can use wildcards as
+ well. A debugging level of 0 will turn off all debugging, and a level
+ of 5 will turn on all debugging. Intermediate values only turn on
+ some debugging (based on message severity; 2, for example, will only
+ display errors and warnings). Here's a list of all available options:
+ </para>
+ <para>
<itemizedlist>
<listitem>
<para>
- <option>--gst-debug-help</option>
- Print available debug categories and exit
+ <option>--gst-debug-help</option> will print available debug
+ categories and exit.
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug-level=<replaceable>LEVEL</replaceable></option>
- Sets the default debug level from 0 (no output) to 5 (everything)
+ will set the default debug level (which can range from 0 (no
+ output) to 5 (everything)).
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug=<replaceable>LIST</replaceable></option>
- Comma-separated list of category_name:level pairs to set specific
- levels for the individual categories.
- Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3
+ takes a comma-separated list of category_name:level pairs to
+ set specific levels for the individual categories. Example:
+ <option>GST_AUTOPLUG:5,avidemux:3</option>.
</para>
</listitem>
<listitem>
<para>
- <option>--gst-debug-no-color</option>
- Disable color debugging output
+ <option>--gst-debug-no-color</option> will disable color debugging.
</para>
</listitem>
<listitem>
<para>
- <option>--gst-debug-disable</option>
- Disable debugging
+ <option>--gst-debug-disable</option> disables debugging alltogether.
</para>
</listitem>
<listitem>
<para>
- <option>--gst-plugin-spew</option>
- Enable printout of errors while loading GStreamer plugins.
+ <option>--gst-plugin-spew</option> enables printout of errors while
+ loading &GStreamer; plugins.
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
- <sect1 id="section-debugging-adding">
- <title>Adding debugging to a plugin</title>
- <para>
-Plugins can define their own categories for the debugging system.
-Three things need to happen:
- <itemizedlist>
- <listitem>
- <para>
-The debugging variable needs to be defined somewhere.
-If you only have one source file, you can Use GST_DEBUG_CATEGORY_STATIC to
-define a static debug category variable.
- </para>
- <para>
-If you have multiple source files, you should define the variable using
-GST_DEBUG_CATEGORY in the source file where you're initializing the debug
-category. The other source files should use GST_DEBUG_CATEGORY_EXTERN to
-declare the debug category variable, possibly by including a common header
-that has this statement.
- </para>
- </listitem>
- <listitem>
- <para>
-The debugging category needs to be initialized. This is done through
-GST_DEBUG_CATEGORY_INIT.
-If you're using a global debugging category for the complete plugin,
-you can call this in the
-plugin's <function>plugin_init</function>.
-If the debug category is only used for one of the elements, you can call it
-from the element's <function>_class_init</function> function.
- </para>
- </listitem>
- <listitem>
- <para>
-You should also define a default category to be used for debugging. This is
-done by defining GST_CAT_DEFAULT for the source files where you're using
-debug macros.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
-Elements can then log debugging information using the set of macros. There
-are five levels of debugging information:
- <orderedlist>
- <listitem>
-<para>ERROR for fatal errors (for example, internal errors)</para>
- </listitem>
- <listitem>
-<para>WARNING for warnings</para>
- </listitem>
- <listitem>
-<para>INFO for normal information</para>
- </listitem>
- <listitem>
-<para>DEBUG for debug information (for example, device parameters)</para>
- </listitem>
- <listitem>
-<para>LOG for regular operation information (for example, chain handlers)</para>
- </listitem>
- </orderedlist>
- </para>
+ <sect1 id="section-checklist-conversion">
+ <title>Conversion plugins</title>
<para>
-For each of these levels, there are four macros to log debugging information.
-Taking the LOG level as an example, there is
- <itemizedlist>
- <listitem>
- <para>
- GST_CAT_LOG_OBJECT logs debug information in the given GstCategory
- and for the given GstObject
- </para>
- </listitem>
- <listitem>
- <para>
- GST_CAT_LOG logs debug information in the given GstCategory
- but without a GstObject (this is useful for libraries, for example)
- </para>
- </listitem>
- <listitem>
- <para>
- GST_LOG_OBJECT logs debug information in the default GST_CAT_DEFAULT
- category (as defined somewhere in the source), for the given GstObject
- </para>
- </listitem>
- <listitem>
- <para>
- GST_LOG logs debug information in the default GST_CAT_DEFAULT
- category, without a GstObject
- </para>
- </listitem>
- </itemizedlist>
- </para>
+ &GStreamer; contains a bunch of conversion plugins that most
+ applications will find useful. Specifically, those are videoscalers
+ (videoscale), colorspace convertors (ffmpegcolorspace), audio format
+ convertors and channel resamplers (audioconvert) and audio samplerate
+ convertors (audioscale). Those convertors don't do anything when not
+ required, they will act in passthrough mode. They will activate when
+ the hardware doesn't support a specific request, though. All
+ applications are recommended to use those elements.
+ </para>
</sect1>
+ <sect1 id="section-checklist-applications">
+ <title>Utility applications provided with &GStreamer;</title>
+ <para>
+ &GStreamer; comes with a default set of command-line utilities that
+ can help in application development. We will discuss only
+ <command>gst-launch</command> and <command>gst-inspect</command> here.
+ </para>
+
+ <sect2 id="section-applications-launch">
+ <title><command>gst-launch</command></title>
+ <para>
+ <command>gst-launch</command> is a simple script-like commandline
+ application that can be used to test pipelines. For example, the
+ command <command>gst-launch sinesrc ! alsasink</command> will run
+ a pipeline which generates a sine-wave audio stream and plays it
+ to your ALSA audio card. <command>gst-launch</command> also allows
+ the use of threads (using curly brackets, so <quote>{</quote>
+ and <quote>}</quote>) and bins (using brackets, so <quote>(</quote>
+ and <quote>)</quote>). You can use dots to imply padnames on elements,
+ or even omit the padname to automatically select a pad. Using
+ all this, the pipeline <command>gst-launch filesrc location=file.ogg
+ ! oggdemux name=d { d. ! theoradec ! ffmpegcolorspace ! xvimagesink
+ } { d. ! vorbisdec ! alsasink }</command> will play an Ogg file
+ containing a Theora video-stream and a Vorbis audio-stream. You can
+ also use autopluggers such as decodebin on the commandline. See the
+ manual page of <command>gst-launch</command> for more information.
+ </para>
+ </sect2>
+
+ <sect2 id="section-applications-inspect">
+ <title><command>gst-inspect</command></title>
+ <para>
+ <command>gst-inspect</command> can be used to inspect all properties,
+ signals, dynamic parameters and the object hierarchy of an element.
+ This acn be very useful to see which <classname>GObject</classname>
+ properties or which signals (and using what arguments) an element
+ supports. Run <command>gst-inspect fakesrc</command> to get an idea
+ of what it does. See the manual page of <command>gst-inspect</command>
+ for more information.
+ </para>
+ </sect2>
+ </sect1>
</chapter>
+++ /dev/null
-<chapter id="chapter-debugging">
- <title>Debugging</title>
- <para>
- GStreamer has an extensive set of debugging tools for
- plugin developers.
- </para>
-
- <sect1 id="section-debugging-command-line">
- <title>Command line options</title>
- <para>
- Applications using the GStreamer libraries accept the following set
- of command line argruments that help in debugging.
- </para>
-
- <para>
- <itemizedlist>
- <listitem>
- <para>
- <option>--gst-debug-help</option>
- Print available debug categories and exit
- </para>
- </listitem>
- <listitem>
- <para>
- <option>--gst-debug-level=<replaceable>LEVEL</replaceable></option>
- Sets the default debug level from 0 (no output) to 5 (everything)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>--gst-debug=<replaceable>LIST</replaceable></option>
- Comma-separated list of category_name:level pairs to set specific
- levels for the individual categories.
- Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3
- </para>
- </listitem>
- <listitem>
- <para>
- <option>--gst-debug-no-color</option>
- Disable color debugging output
- </para>
- </listitem>
- <listitem>
- <para>
- <option>--gst-debug-disable</option>
- Disable debugging
- </para>
- </listitem>
- <listitem>
- <para>
- <option>--gst-plugin-spew</option>
- Enable printout of errors while loading GStreamer plugins.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect1>
-
- <sect1 id="section-debugging-adding">
- <title>Adding debugging to a plugin</title>
- <para>
-Plugins can define their own categories for the debugging system.
-Three things need to happen:
- <itemizedlist>
- <listitem>
- <para>
-The debugging variable needs to be defined somewhere.
-If you only have one source file, you can Use GST_DEBUG_CATEGORY_STATIC to
-define a static debug category variable.
- </para>
- <para>
-If you have multiple source files, you should define the variable using
-GST_DEBUG_CATEGORY in the source file where you're initializing the debug
-category. The other source files should use GST_DEBUG_CATEGORY_EXTERN to
-declare the debug category variable, possibly by including a common header
-that has this statement.
- </para>
- </listitem>
- <listitem>
- <para>
-The debugging category needs to be initialized. This is done through
-GST_DEBUG_CATEGORY_INIT.
-If you're using a global debugging category for the complete plugin,
-you can call this in the
-plugin's <function>plugin_init</function>.
-If the debug category is only used for one of the elements, you can call it
-from the element's <function>_class_init</function> function.
- </para>
- </listitem>
- <listitem>
- <para>
-You should also define a default category to be used for debugging. This is
-done by defining GST_CAT_DEFAULT for the source files where you're using
-debug macros.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
-Elements can then log debugging information using the set of macros. There
-are five levels of debugging information:
- <orderedlist>
- <listitem>
-<para>ERROR for fatal errors (for example, internal errors)</para>
- </listitem>
- <listitem>
-<para>WARNING for warnings</para>
- </listitem>
- <listitem>
-<para>INFO for normal information</para>
- </listitem>
- <listitem>
-<para>DEBUG for debug information (for example, device parameters)</para>
- </listitem>
- <listitem>
-<para>LOG for regular operation information (for example, chain handlers)</para>
- </listitem>
- </orderedlist>
- </para>
- <para>
-For each of these levels, there are four macros to log debugging information.
-Taking the LOG level as an example, there is
- <itemizedlist>
- <listitem>
- <para>
- GST_CAT_LOG_OBJECT logs debug information in the given GstCategory
- and for the given GstObject
- </para>
- </listitem>
- <listitem>
- <para>
- GST_CAT_LOG logs debug information in the given GstCategory
- but without a GstObject (this is useful for libraries, for example)
- </para>
- </listitem>
- <listitem>
- <para>
- GST_LOG_OBJECT logs debug information in the default GST_CAT_DEFAULT
- category (as defined somewhere in the source), for the given GstObject
- </para>
- </listitem>
- <listitem>
- <para>
- GST_LOG logs debug information in the default GST_CAT_DEFAULT
- category, without a GstObject
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect1>
-
-</chapter>
+++ /dev/null
-<chapter id="chapter-gnome">
- <title>GNOME integration</title>
- <para>
- GStreamer is fairly easy to integrate with GNOME applications.
- GStreamer uses libxml 2.0, GLib 2.0 and popt, as do all other
- GNOME applications.
- There are however some basic issues you need to address in your GNOME
- applications.
- </para>
-
- <sect1>
- <title>Command line options</title>
- <para>
- GNOME applications call gnome_program_init () to parse command-line
- options and initialize the necessary gnome modules.
- GStreamer applications normally call gst_init (&argc, &argv) to
- do the same for GStreamer.
- </para>
- <para>
- Each of these two swallows the program options passed to the program,
- so we need a different way to allow both GNOME and GStreamer to parse
- the command-line options. This is shown in the following example.
- </para>
-
- <programlisting>
-<!-- example-begin gnome.c -->
-#include <gnome.h>
-#include <gst/gst.h>
-
-int
-main (int argc, char **argv)
-{
- GstPoptOption options[] = {
- { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "GStreamer", NULL },
- POPT_TABLEEND
- };
- GnomeProgram *program;
- poptContext context;
- const gchar **argvn;
-
- GstElement *pipeline;
- GstElement *src, *sink;
-
- options[0].arg = (void *) gst_init_get_popt_table ();
- g_print ("Calling gnome_program_init with the GStreamer popt table\n");
- /* gnome_program_init will initialize GStreamer now
- * as a side effect of having the GStreamer popt table passed. */
- if (! (program = gnome_program_init ("my_package", "0.1", LIBGNOMEUI_MODULE,
- argc, argv,
- GNOME_PARAM_POPT_TABLE, options,
- NULL)))
- g_error ("gnome_program_init failed");
-
- g_print ("Getting gnome-program popt context\n");
- g_object_get (program, "popt-context", &context, NULL);
- argvn = poptGetArgs (context);
- if (!argvn) {
- g_print ("Run this example with some arguments to see how it works.\n");
- return 0;
- }
-
- g_print ("Printing rest of arguments\n");
- while (*argvn) {
- g_print ("argument: %s\n", *argvn);
- ++argvn;
- }
-
- /* do some GStreamer things to show everything's initialized properly */
- g_print ("Doing some GStreamer stuff to show that everything works\n");
- pipeline = gst_pipeline_new ("pipeline");
- src = gst_element_factory_make ("fakesrc", "src");
- sink = gst_element_factory_make ("fakesink", "sink");
- gst_bin_add_many (GST_BIN (pipeline), src, sink, NULL);
- gst_element_link (src, sink);
- gst_element_set_state (pipeline, GST_STATE_PLAYING);
- gst_bin_iterate (GST_BIN (pipeline));
- gst_element_set_state (pipeline, GST_STATE_NULL);
-
- return 0;
-}
-<!-- example-end gnome.c -->
- </programlisting>
- <para>
- If you try out this program, you will see that when called with
- --help, it will print out both GStreamer and GNOME help arguments.
- All of the arguments that didn't belong to either end up in the
- argvn pointer array.
- </para>
- <para>
- FIXME: flesh this out more. How do we get the GStreamer arguments
- at the end ?
- FIXME: add a GConf bit.
- </para>
- </sect1>
-</chapter>
-<chapter id="chapter-gnome">
- <title>GNOME integration</title>
- <para>
- GStreamer is fairly easy to integrate with GNOME applications.
- GStreamer uses libxml 2.0, GLib 2.0 and popt, as do all other
- GNOME applications.
- There are however some basic issues you need to address in your GNOME
- applications.
+<chapter id="chapter-intgration">
+ <title>Integration</title>
+ <para>
+ &GStreamer; tries to integrate closely with operating systems (such
+ as Linux and UNIX-like operating systems, OS X or Windows) and desktop
+ environments (such as GNOME or KDE). In this chapter, we'll mention
+ some specific techniques to integrate your application with your
+ operating system or desktop environment of choice.
</para>
- <sect1>
- <title>Command line options</title>
+ <sect1 id="section-integration-nix">
+ <title>Linux and UNIX-like operating systems</title>
<para>
- GNOME applications call gnome_program_init () to parse command-line
- options and initialize the necessary gnome modules.
- GStreamer applications normally call gst_init (&argc, &argv) to
- do the same for GStreamer.
+ &GStreamer; provides a basic set of elements that are useful when
+ integrating with Linux or a UNIX-like operating system.
</para>
- <para>
- Each of these two swallows the program options passed to the program,
- so we need a different way to allow both GNOME and GStreamer to parse
- the command-line options. This is shown in the following example.
- </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ For audio input and output, &GStreamer; provides input and
+ output elements for several audio subsystems. Amongst others,
+ &GStreamer; includes elements for ALSA (alsasrc, alsamixer,
+ alsasink), OSS (osssrc, ossmixer, osssink) and Sun audio
+ (sunaudiosrc, sunaudiomixer, sunaudiosink).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For video input, &GStreamer; contains source elements for
+ Video4linux (v4lsrc, v4lmjpegsrc, v4lelement and v4lmjpegisnk)
+ and Video4linux2 (v4l2src, v4l2element).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For video output, &GStreamer; provides elements for output
+ to X-windows (ximagesink), Xv-windows (xvimagesink; for
+ hardware-accelerated video), direct-framebuffer (dfbimagesink)
+ and openGL image contexts (glsink).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
- <programlisting>
-<!-- example-begin gnome.c -->
+ <sect1 id="section-integration-gnome">
+ <title>GNOME desktop</title>
+ <para>
+ &GStreamer; has been the media backend of the <ulink type="http"
+ url="http://www.gnome.org/">GNOME</ulink> desktop since GNOME-2.2
+ onwards. Nowadays, a whole bunch of GNOME applications make use of
+ &GStreamer; for media-processing, including (but not limited to)
+ <ulink type="http" url="http://www.rhythmbox.org/">Rhythmbox</ulink>,
+ <ulink type="http" url="http://www.hadess.net/totem.php3">Totem</ulink>
+ and <ulink type="http"
+ url="http://www.burtonini.com/blog/computers/sound-juicer">Sound
+ Juicer</ulink>.
+ </para>
+ <para>
+ Most of these GNOME applications make use of some specific techniques
+ to integrate as closely as possible with the GNOME desktop:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ GNOME applications call <function>gnome_program_init ()</function>
+ to parse command-line options and initialize the necessary gnome
+ modules. &GStreamer; applications would normally call
+ <function>gst_init ()</function> to do the same for GStreamer.
+ This would mean that only one of the two can parse command-line
+ options. To work around this issue, &GStreamer; can provide a
+ <classname>poptOption</classname> array which can be passed to
+ <function>gnome_program_init ()</function>.
+ </para>
+ <programlisting><!-- example-begin gnome.c a -->
#include <gnome.h>
#include <gst/gst.h>
-int
-main (int argc, char **argv)
+gint
+main (gint argc,
+ gchar *argv[])
{
- GstPoptOption options[] = {
- { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "GStreamer", NULL },
- POPT_TABLEEND
- };
- GnomeProgram *program;
- poptContext context;
- const gchar **argvn;
-
- GstElement *pipeline;
- GstElement *src, *sink;
+ struct poptOption options[] = {
+ {NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "GStreamer", NULL},
+ POPT_TABLEEND
+ };
+ /* init GStreamer and GNOME using the GStreamer popt tables */
options[0].arg = (void *) gst_init_get_popt_table ();
- g_print ("Calling gnome_program_init with the GStreamer popt table\n");
- /* gnome_program_init will initialize GStreamer now
- * as a side effect of having the GStreamer popt table passed. */
- if (! (program = gnome_program_init ("my_package", "0.1", LIBGNOMEUI_MODULE,
- argc, argv,
- GNOME_PARAM_POPT_TABLE, options,
- NULL)))
- g_error ("gnome_program_init failed");
-
- g_print ("Getting gnome-program popt context\n");
- g_object_get (program, "popt-context", &context, NULL);
- argvn = poptGetArgs (context);
- if (!argvn) {
- g_print ("Run this example with some arguments to see how it works.\n");
- return 0;
- }
-
- g_print ("Printing rest of arguments\n");
- while (*argvn) {
- g_print ("argument: %s\n", *argvn);
- ++argvn;
- }
-
- /* do some GStreamer things to show everything's initialized properly */
- g_print ("Doing some GStreamer stuff to show that everything works\n");
- pipeline = gst_pipeline_new ("pipeline");
- src = gst_element_factory_make ("fakesrc", "src");
- sink = gst_element_factory_make ("fakesink", "sink");
- gst_bin_add_many (GST_BIN (pipeline), src, sink, NULL);
- gst_element_link (src, sink);
- gst_element_set_state (pipeline, GST_STATE_PLAYING);
- gst_bin_iterate (GST_BIN (pipeline));
- gst_element_set_state (pipeline, GST_STATE_NULL);
-
+ gnome_program_init ("my-application", "0.0.1", LIBGNOMEUI_MODULE, argc, argv,
+ GNOME_PARAM_POPT_TABLE, options,
+ NULL);
+<!-- example-end gnome.c a -->
+[..]<!-- example-begin gnome.c b --><!--
return 0;
+--><!-- example-end gnome.c b -->
+<!-- example-begin gnome.c c -->
}
-<!-- example-end gnome.c -->
- </programlisting>
+ <!-- example-end gnome.c c --></programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ GNOME stores the default video and audio sources and sinks in GConf.
+ &GStreamer; provides a small utility library that can be used to
+ get the elements from the registry using functions such as
+ <function>gst_gconf_get_default_video_sink ()</function>. See the
+ header file (<filename>gst/gconf/gconf.h</filename>) for details.
+ All GNOME applications are recommended to use those variables.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ &GStreamer; provides data input/output elements for use with the
+ GNOME-VFS system. These elements are called <quote>gnomevfssrc</quote>
+ and <quote>gnomevfssink</quote>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="section-integration-kde">
+ <title>KDE desktop</title>
+ <para>
+ &GStreamer; has been proposed for inclusion in KDE-4.0. Currently,
+ &GStreamer; is included as an optional component, and it's used by
+ several KDE applications, including <ulink type="http"
+ url="http://amarok.kde.org/">AmaroK</ulink> and <ulink type="http"
+ url="http://developer.kde.org/~wheeler/juk.html">JuK</ulink>. A
+ backend for <ulink type="http"
+ url="http://www.xs4all.nl/~jjvrieze/kmplayer.html">KMPlayer</ulink>
+ is currently under development.
+ </para>
+ <para>
+ Although not yet as complete as the GNOME integration bits, there
+ are already some KDE integration specifics available. This list will
+ probably grow as &GStreamer; starts to be used in KDE-4.0:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ AmaroK contains a kiosrc element, which is a source element that
+ integrates with the KDE VFS subsystem KIO.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="section-integration-osx">
+ <title>OS X</title>
<para>
- If you try out this program, you will see that when called with
- --help, it will print out both GStreamer and GNOME help arguments.
- All of the arguments that didn't belong to either end up in the
- argvn pointer array.
+ &GStreamer; provides native video and audio output elements for OS X.
+ It builds using the standard development tools for OS X.
</para>
+ </sect1>
+
+ <sect1 id="section-integration-win32">
+ <title>Windows</title>
<para>
- FIXME: flesh this out more. How do we get the GStreamer arguments
- at the end ?
- FIXME: add a GConf bit.
+ &GStreamer; builds using Microsoft Visual C .NET 2003 and using Cygwin.
</para>
</sect1>
</chapter>
<!ENTITY COMPONENTS SYSTEM "highlevel-components.xml">
<!-- Appendices -->
-<!ENTITY DEBUGGING SYSTEM "appendix-debugging.xml">
-<!ENTITY PROGRAMS SYSTEM "appendix-programs.xml">
-<!ENTITY GNOME SYSTEM "appendix-gnome.xml">
+<!ENTITY CHECKLIST SYSTEM "appendix-checklist.xml">
+<!ENTITY INTEGRATION SYSTEM "appendix-integration.xml">
<!ENTITY WIN32 SYSTEM "appendix-win32.xml">
<!ENTITY QUOTES SYSTEM "appendix-quotes.xml">
</para>
</partintro>
-<!--
-Idea:
-* Querying and events
- - seeking
- - getting stream length
- - prerolls and why
-* Stream info
- - pads info (see 2.4)
- - tags
- - inserting tags
-* Interfaces
- - each
-* Clocks & Synchronization
- - stress that it's automated
-* Dynamic parameters
- - ..
-* Threading
- - gstthread & queues
- - buffering (network, live network/video/audio source)
- - when 1-to-N, N-to-1 and N-to-N elements need threads
-* Scheduling
- - loop/chain/get etc. (internals)
- - opt
-* Autoplugging principles
- - type detection
- - dynamic element lookup (registry, factories and categories)
- - reference part4!
- - Hello world 2
-* Pipeline manipulation
- - data manipulation (identity, fakesrc, fakesink)
- - probes (both events and data)
- - length manipulation (managers, PWG)
- - explain how to embed elements in applications
- - explain why separate elements are to be preferred
--->
-
&QUERYEVENTS;
&METADATA;
&INTERFACES;
- table please...
-->
- &DEBUGGING;
- &PROGRAMS;
- &GNOME;
+ &CHECKLIST;
+ &INTEGRATION;
&WIN32;
"ES;
()</function> or <function>g_print ()</function>). Instead,
elements should use the logging functions provided by &GStreamer;,
named <function>GST_DEBUG ()</function>,
- <function>GST_INFO ()</function>, <function>GST_INFO ()</function>,
+ <function>GST_LOG ()</function>, <function>GST_INFO ()</function>,
<function>GST_WARNING ()</function> and
<function>GST_ERROR ()</function>. The various logging levels can
be turned on and off at runtime and can thus be used for solving
- issues as they turn up.
+ issues as they turn up. Instead of <function>GST_LOG ()</function>
+ (as an example), you can also use <function>GST_LOG_OBJECT
+ ()</function> to print the object that you're logging output for.
</para>
</listitem>
<listitem>
</programlisting>
<para>
At runtime, you can turn on debugging using the commandline
- <command>--gst-debug=myelement:5</command>.
+ option <command>--gst-debug=myelement:5</command>.
</para>
</listitem>
</itemizedlist>
<!-- ############ sect1 ############# -->
<sect1 id="section-boiler-project-stamp" xreflabel="Using the Project Stamp">
- <title>!!! FIXME !!! Using the Project Stamp</title>
- <para>
- This section needs some fixing from someone that is aware of how this works.
- The only tool that looks like the ones cited there is <filename>gst-plugins/tools/filterstamp.sh</filename>
- </para>
+ <title>Using the Project Stamp</title>
+ <!-- FIXME
+ This section needs some fixing from someone that is aware of how this
+ works. The only tool that looks like the ones cited there is
+ <filename>gst-plugins/tools/filterstamp.sh</filename>
+ -->
<para>
The first thing to do when making a new element is to specify some basic
details about it: what its name is, who wrote it, what version number it
&ADVANCED_INTERFACES;
&ADVANCED_TAGGING;
&ADVANCED_EVENTS;
+
+ <!-- FIXME: add querying, event handling and conversion -->
+
</part>
<!-- ############ part ############# -->
query \
threads \
typefind \
+ fakesrc \
playbin \
decodebin \
$(GST_LOADSAVE_SRC)
$(PERL_PATH) $(srcdir)/extract.pl $@ \
$(top_srcdir)/docs/manual/basics-pads.xml
-gnome.c: $(top_srcdir)/docs/manual/appendix-gnome.xml
+gnome.c: $(top_srcdir)/docs/manual/appendix-integration.xml
$(PERL_PATH) $(srcdir)/extract.pl $@ \
- $(top_srcdir)/docs/manual/appendix-gnome.xml
+ $(top_srcdir)/docs/manual/appendix-integration.xml
helloworld.c: $(top_srcdir)/docs/manual/basics-helloworld.xml
$(PERL_PATH) $(srcdir)/extract.pl $@ \
$(PERL_PATH) $(srcdir)/extract.pl $@ \
$(top_srcdir)/docs/manual/advanced-autoplugging.xml
+fakesrc.c: $(top_srcdir)/docs/manual/advanced-dataaccess.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ \
+ $(top_srcdir)/docs/manual/advanced-dataaccess.xml
+
playbin.c decodebin.c: $(top_srcdir)/docs/manual/highlevel-components.xml
$(PERL_PATH) $(srcdir)/extract.pl $@ \
$(top_srcdir)/docs/manual/highlevel-components.xml
query \
threads \
typefind \
+ fakesrc \
playbin \
decodebin \
$(GST_LOADSAVE_SRC)
$(PERL_PATH) $(srcdir)/extract.pl $@ \
$(top_srcdir)/docs/manual/basics-pads.xml
-gnome.c: $(top_srcdir)/docs/manual/appendix-gnome.xml
+gnome.c: $(top_srcdir)/docs/manual/appendix-integration.xml
$(PERL_PATH) $(srcdir)/extract.pl $@ \
- $(top_srcdir)/docs/manual/appendix-gnome.xml
+ $(top_srcdir)/docs/manual/appendix-integration.xml
helloworld.c: $(top_srcdir)/docs/manual/basics-helloworld.xml
$(PERL_PATH) $(srcdir)/extract.pl $@ \
$(PERL_PATH) $(srcdir)/extract.pl $@ \
$(top_srcdir)/docs/manual/advanced-autoplugging.xml
+fakesrc.c: $(top_srcdir)/docs/manual/advanced-dataaccess.xml
+ $(PERL_PATH) $(srcdir)/extract.pl $@ \
+ $(top_srcdir)/docs/manual/advanced-dataaccess.xml
+
playbin.c decodebin.c: $(top_srcdir)/docs/manual/highlevel-components.xml
$(PERL_PATH) $(srcdir)/extract.pl $@ \
$(top_srcdir)/docs/manual/highlevel-components.xml
projects / platform / upstream / gstreamer.git / commitdiff