From: Ronald S. Bultje Date: Thu, 23 Dec 2004 14:26:14 +0000 (+0000) Subject: docs/manual/advanced-dataaccess.xml: Add section on how to use fakesrc/fakesink/ident... X-Git-Tag: RELEASE-0_8_9~82 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1fef2701583999c95cc0bece4eb457455edcb6c3;p=platform%2Fupstream%2Fgstreamer.git docs/manual/advanced-dataaccess.xml: Add section on how to use fakesrc/fakesink/identity in your application, plus se... Original commit message from CVS: * 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. --- diff --git a/ChangeLog b/ChangeLog index 9572004..1f767c1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,27 @@ +2004-12-23 Ronald S. Bultje + + * 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 * configure.ac: diff --git a/docs/manual/advanced-dataaccess.xml b/docs/manual/advanced-dataaccess.xml new file mode 100644 index 0000000..2a1f158 --- /dev/null +++ b/docs/manual/advanced-dataaccess.xml @@ -0,0 +1,241 @@ + + Pipeline manipulation + + 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. + + + 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. + + + + Data probes + + 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. + + + + + Manually adding or removing data from/to a pipeline + + 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. However, + there is no support for those methods. 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. + + + After all those disclaimers, let's start. There's three possible + elements that you can use for the above-mentioned purposes. Those are + called fakesrc (an imaginary source), + fakesink (an imaginary sink) and identity + (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. + + + + Inserting or grabbing data + + The three before-mentioned elements (fakesrc, fakesink and identity) + each have a handoff signal that will be called in + the _get ()- (fakesrc) or _chain + ()-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 sizemax + property. For both fakesrc and fakesink, you also have to set the + signal-handoffs property for this method to work. + + + Note that your handoff function should not + 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. + + + + + Forcing a format + + 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 GstCaps on the pipeline, + which is possible by using filtered caps. You + can set a filtered caps on a link by using + gst_pad_link_filtered (), where the third + argument is the format to force on the link. + + + + + Example application + + 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. + + +#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; +} + + + + + + Embedding static elements in your application + + The Plugin + Writer's Guide 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;. + + + Dynamically loaded plugins contain a structure that's defined using + GST_PLUGIN_DEFINE (). This structure is loaded + when the plugin is loaded by the &GStreamer; core. The structure + contains an initialization function (usually called + plugin_init) 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 _gst_plugin_register_static + (). 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 gst_element_factory_make + ("my-element-name", "some-name") to create an instance + of the element. + + +/* + * 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); +} + + + diff --git a/docs/manual/appendix-checklist.xml b/docs/manual/appendix-checklist.xml index 2224241..7df980f 100644 --- a/docs/manual/appendix-checklist.xml +++ b/docs/manual/appendix-checklist.xml @@ -1,152 +1,163 @@ - - Debugging - - GStreamer has an extensive set of debugging tools for - plugin developers. + + Things to check when writing an application + + 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. - - - Command line options - - Applications using the GStreamer libraries accept the following set - of command line argruments that help in debugging. + + + Good programming habits + + + + Always connect to the error signal of your topmost + pipeline to be notified of errors in your pipeline. + + + + + Always check return values of &GStreamer; functions. Especially, + check return values of gst_element_link () + and gst_element_set_state (). + + + + + 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 + play button. Instead, connect to the + state-changed signal of your topmost pipeline and + update the user interface whenever this signal is triggered. + + + + + + + Debugging + + 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.). - - + + Most &GStreamer;-based applications accept the commandline 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, 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: + + - - Print available debug categories and exit + will print available debug + categories and exit. - 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)). - 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: + . - - Disable color debugging output + will disable color debugging. - - Disable debugging + disables debugging alltogether. - - Enable printout of errors while loading GStreamer plugins. + enables printout of errors while + loading &GStreamer; plugins. - - Adding debugging to a plugin - -Plugins can define their own categories for the debugging system. -Three things need to happen: - - - -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. - - -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. - - - - -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 plugin_init. -If the debug category is only used for one of the elements, you can call it -from the element's _class_init function. - - - - -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. - - - - - -Elements can then log debugging information using the set of macros. There -are five levels of debugging information: - - -ERROR for fatal errors (for example, internal errors) - - -WARNING for warnings - - -INFO for normal information - - -DEBUG for debug information (for example, device parameters) - - -LOG for regular operation information (for example, chain handlers) - - - + + Conversion plugins -For each of these levels, there are four macros to log debugging information. -Taking the LOG level as an example, there is - - - - GST_CAT_LOG_OBJECT logs debug information in the given GstCategory - and for the given GstObject - - - - - GST_CAT_LOG logs debug information in the given GstCategory - but without a GstObject (this is useful for libraries, for example) - - - - - GST_LOG_OBJECT logs debug information in the default GST_CAT_DEFAULT - category (as defined somewhere in the source), for the given GstObject - - - - - GST_LOG logs debug information in the default GST_CAT_DEFAULT - category, without a GstObject - - - - + &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. + + + Utility applications provided with &GStreamer; + + &GStreamer; comes with a default set of command-line utilities that + can help in application development. We will discuss only + gst-launch and gst-inspect here. + + + + <command>gst-launch</command> + + gst-launch is a simple script-like commandline + application that can be used to test pipelines. For example, the + command gst-launch sinesrc ! alsasink will run + a pipeline which generates a sine-wave audio stream and plays it + to your ALSA audio card. gst-launch also allows + the use of threads (using curly brackets, so { + and }) and bins (using brackets, so ( + and )). You can use dots to imply padnames on elements, + or even omit the padname to automatically select a pad. Using + all this, the pipeline gst-launch filesrc location=file.ogg + ! oggdemux name=d { d. ! theoradec ! ffmpegcolorspace ! xvimagesink + } { d. ! vorbisdec ! alsasink } 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 gst-launch for more information. + + + + + <command>gst-inspect</command> + + gst-inspect 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 GObject + properties or which signals (and using what arguments) an element + supports. Run gst-inspect fakesrc to get an idea + of what it does. See the manual page of gst-inspect + for more information. + + + diff --git a/docs/manual/appendix-debugging.xml b/docs/manual/appendix-debugging.xml deleted file mode 100644 index 2224241..0000000 --- a/docs/manual/appendix-debugging.xml +++ /dev/null @@ -1,152 +0,0 @@ - - Debugging - - GStreamer has an extensive set of debugging tools for - plugin developers. - - - - Command line options - - Applications using the GStreamer libraries accept the following set - of command line argruments that help in debugging. - - - - - - - - Print available debug categories and exit - - - - - - Sets the default debug level from 0 (no output) to 5 (everything) - - - - - - Comma-separated list of category_name:level pairs to set specific - levels for the individual categories. - Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3 - - - - - - Disable color debugging output - - - - - - Disable debugging - - - - - - Enable printout of errors while loading GStreamer plugins. - - - - - - - - Adding debugging to a plugin - -Plugins can define their own categories for the debugging system. -Three things need to happen: - - - -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. - - -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. - - - - -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 plugin_init. -If the debug category is only used for one of the elements, you can call it -from the element's _class_init function. - - - - -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. - - - - - -Elements can then log debugging information using the set of macros. There -are five levels of debugging information: - - -ERROR for fatal errors (for example, internal errors) - - -WARNING for warnings - - -INFO for normal information - - -DEBUG for debug information (for example, device parameters) - - -LOG for regular operation information (for example, chain handlers) - - - - -For each of these levels, there are four macros to log debugging information. -Taking the LOG level as an example, there is - - - - GST_CAT_LOG_OBJECT logs debug information in the given GstCategory - and for the given GstObject - - - - - GST_CAT_LOG logs debug information in the given GstCategory - but without a GstObject (this is useful for libraries, for example) - - - - - GST_LOG_OBJECT logs debug information in the default GST_CAT_DEFAULT - category (as defined somewhere in the source), for the given GstObject - - - - - GST_LOG logs debug information in the default GST_CAT_DEFAULT - category, without a GstObject - - - - - - - diff --git a/docs/manual/appendix-gnome.xml b/docs/manual/appendix-gnome.xml deleted file mode 100644 index 1438ffa..0000000 --- a/docs/manual/appendix-gnome.xml +++ /dev/null @@ -1,95 +0,0 @@ - - GNOME integration - - 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. - - - - Command line options - - 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. - - - 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. - - - - -#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; -} - - - - 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. - - - FIXME: flesh this out more. How do we get the GStreamer arguments - at the end ? - FIXME: add a GConf bit. - - - diff --git a/docs/manual/appendix-integration.xml b/docs/manual/appendix-integration.xml index 1438ffa..14571ee 100644 --- a/docs/manual/appendix-integration.xml +++ b/docs/manual/appendix-integration.xml @@ -1,95 +1,161 @@ - - GNOME integration - - 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. + + Integration + + &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. - - Command line options + + Linux and UNIX-like operating systems - 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. - - 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. - + + + + 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). + + + + + For video input, &GStreamer; contains source elements for + Video4linux (v4lsrc, v4lmjpegsrc, v4lelement and v4lmjpegisnk) + and Video4linux2 (v4l2src, v4l2element). + + + + + 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). + + + + - - + + GNOME desktop + + &GStreamer; has been the media backend of the GNOME 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) + Rhythmbox, + Totem + and Sound + Juicer. + + + Most of these GNOME applications make use of some specific techniques + to integrate as closely as possible with the GNOME desktop: + + + + + GNOME applications call gnome_program_init () + to parse command-line options and initialize the necessary gnome + modules. &GStreamer; applications would normally call + gst_init () 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 + poptOption array which can be passed to + gnome_program_init (). + + #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); + +[..] + } - - + + + + + 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 + gst_gconf_get_default_video_sink (). See the + header file (gst/gconf/gconf.h) for details. + All GNOME applications are recommended to use those variables. + + + + + &GStreamer; provides data input/output elements for use with the + GNOME-VFS system. These elements are called gnomevfssrc + and gnomevfssink. + + + + + + + KDE desktop + + &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 AmaroK and JuK. A + backend for KMPlayer + is currently under development. + + + 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: + + + + + AmaroK contains a kiosrc element, which is a source element that + integrates with the KDE VFS subsystem KIO. + + + + + + + OS X - 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. + + + + Windows - 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. diff --git a/docs/manual/manual.xml b/docs/manual/manual.xml index 7d4c2ac..fb9021d 100644 --- a/docs/manual/manual.xml +++ b/docs/manual/manual.xml @@ -47,9 +47,8 @@ - - - + + @@ -193,42 +192,6 @@ - - &QUERYEVENTS; &METADATA; &INTERFACES; @@ -313,9 +276,8 @@ Idea: - table please... --> - &DEBUGGING; - &PROGRAMS; - &GNOME; + &CHECKLIST; + &INTEGRATION; &WIN32; "ES; diff --git a/docs/pwg/appendix-checklist.xml b/docs/pwg/appendix-checklist.xml index 79cd4f0..9c1de58 100644 --- a/docs/pwg/appendix-checklist.xml +++ b/docs/pwg/appendix-checklist.xml @@ -59,11 +59,13 @@ () or g_print ()). Instead, elements should use the logging functions provided by &GStreamer;, named GST_DEBUG (), - GST_INFO (), GST_INFO (), + GST_LOG (), GST_INFO (), GST_WARNING () and GST_ERROR (). 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 GST_LOG () + (as an example), you can also use GST_LOG_OBJECT + () to print the object that you're logging output for. @@ -87,7 +89,7 @@ gst_myelement_class_init (GstMyelementClass *klass) At runtime, you can turn on debugging using the commandline - --gst-debug=myelement:5. + option --gst-debug=myelement:5. diff --git a/docs/pwg/building-boiler.xml b/docs/pwg/building-boiler.xml index 3329419..8758c02 100644 --- a/docs/pwg/building-boiler.xml +++ b/docs/pwg/building-boiler.xml @@ -63,11 +63,12 @@ U gst-template/gst-app/src/Makefile.am - !!! FIXME !!! Using the Project Stamp - - 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 gst-plugins/tools/filterstamp.sh - + Using the Project Stamp + 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 diff --git a/docs/pwg/pwg.xml b/docs/pwg/pwg.xml index 2025320..1cd9330 100644 --- a/docs/pwg/pwg.xml +++ b/docs/pwg/pwg.xml @@ -144,6 +144,9 @@ &ADVANCED_INTERFACES; &ADVANCED_TAGGING; &ADVANCED_EVENTS; + + + diff --git a/examples/manual/Makefile.am b/examples/manual/Makefile.am index 79eca40..dd68890 100644 --- a/examples/manual/Makefile.am +++ b/examples/manual/Makefile.am @@ -36,6 +36,7 @@ EXAMPLES = \ query \ threads \ typefind \ + fakesrc \ playbin \ decodebin \ $(GST_LOADSAVE_SRC) @@ -52,9 +53,9 @@ pad.c ghostpad.c: $(top_srcdir)/docs/manual/basics-pads.xml $(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 $@ \ @@ -76,6 +77,10 @@ typefind.c dynamic.c: $(top_srcdir)/docs/manual/advanced-autoplugging.xml $(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 diff --git a/tests/old/examples/manual/Makefile.am b/tests/old/examples/manual/Makefile.am index 79eca40..dd68890 100644 --- a/tests/old/examples/manual/Makefile.am +++ b/tests/old/examples/manual/Makefile.am @@ -36,6 +36,7 @@ EXAMPLES = \ query \ threads \ typefind \ + fakesrc \ playbin \ decodebin \ $(GST_LOADSAVE_SRC) @@ -52,9 +53,9 @@ pad.c ghostpad.c: $(top_srcdir)/docs/manual/basics-pads.xml $(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 $@ \ @@ -76,6 +77,10 @@ typefind.c dynamic.c: $(top_srcdir)/docs/manual/advanced-autoplugging.xml $(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