From 7c24fc7450616842cf16dda4cdab9279bd306f7b Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Tue, 25 Sep 2012 14:40:20 +0200 Subject: [PATCH] manual: fix up the manual MIME-type -> media types Fix up the manual in various places with the 1.0 way of doing things such as probes, static elements, scheduling, ... Add porting from 0.10 to 1.0 chapter. Add probe example to build. Remove some docs for remove components such as GstMixer and GstPropertyProbe, XML... --- docs/manual/advanced-autoplugging.xml | 40 ++++---- docs/manual/advanced-dataaccess.xml | 99 +++++++++---------- docs/manual/advanced-interfaces.xml | 110 ++------------------- docs/manual/advanced-threads.xml | 18 ++-- docs/manual/appendix-checklist.xml | 10 +- docs/manual/appendix-integration.xml | 9 +- docs/manual/appendix-porting.xml | 175 ++++++++++++++++++++++++++++++++++ docs/manual/basics-bins.xml | 21 ++-- docs/manual/basics-bus.xml | 4 +- docs/manual/basics-data.xml | 8 +- docs/manual/basics-elements.xml | 9 +- docs/manual/basics-helloworld.xml | 9 +- docs/manual/highlevel-components.xml | 17 +--- docs/manual/intro-basics.xml | 19 ++-- docs/manual/manual.xml | 8 +- docs/random/porting-to-1.0.txt | 4 +- tests/examples/manual/Makefile.am | 5 + 17 files changed, 315 insertions(+), 250 deletions(-) diff --git a/docs/manual/advanced-autoplugging.xml b/docs/manual/advanced-autoplugging.xml index 177e5f8..474a66f 100644 --- a/docs/manual/advanced-autoplugging.xml +++ b/docs/manual/advanced-autoplugging.xml @@ -20,32 +20,32 @@ without needing any adaptations to its autopluggers. - We will first introduce the concept of MIME types as a dynamic and + We will first introduce the concept of Media types as a dynamic and extendible way of identifying media streams. After that, we will introduce the concept of typefinding to find the type of a media stream. Lastly, we will explain how autoplugging and the &GStreamer; registry can be - used to setup a pipeline that will convert media from one mimetype to + used to setup a pipeline that will convert media from one mediatype to another, for example for media decoding. - - MIME-types as a way to identify streams + + Media types as a way to identify streams We have previously introduced the concept of capabilities as a way for elements (or, rather, pads) to agree on a media type when streaming data from one element to the next (see ). We have explained that a capability is - a combination of a mimetype and a set of properties. For most + a combination of a media type and a set of properties. For most container formats (those are the files that you will find on your hard disk; Ogg, for example, is a container format), no properties - are needed to describe the stream. Only a MIME-type is needed. A - full list of MIME-types and accompanying properties can be found + are needed to describe the stream. Only a media type is needed. A + full list of media types and accompanying properties can be found in the Plugin Writer's Guide. - An element must associate a MIME-type to its source and sink pads + An element must associate a media type to its source and sink pads when it is loaded into the system. &GStreamer; knows about the different elements and what type of data they expect and emit through the &GStreamer; registry. This allows for very dynamic and extensible @@ -54,14 +54,14 @@ In , we've learned to build a - music player for Ogg/Vorbis files. Let's look at the MIME-types + music player for Ogg/Vorbis files. Let's look at the media types associated with each pad in this pipeline. shows what MIME-type belongs to each + linkend="section-mime-img"/> shows what media type belongs to each pad in this pipeline.
- The Hello world pipeline with MIME types + The Hello world pipeline with media types @@ -98,11 +98,11 @@ Plugins in &GStreamer; can, as mentioned before, implement typefinder functionality. A plugin implementing this functionality will submit - a mimetype, optionally a set of file extensions commonly used for this + a media type, optionally a set of file extensions commonly used for this media type, and a typefind function. Once this typefind function inside the plugin is called, the plugin will see if the data in this media stream matches a specific pattern that marks the media type identified - by that mimetype. If it does, it will notify the typefind element of + by that media type. If it does, it will notify the typefind element of this fact, telling which mediatype was recognized and how certain we are that this stream is indeed that mediatype. Once this run has been completed for all plugins implementing a typefind functionality, the @@ -257,7 +257,7 @@ GstElement *pipeline; the registry that can decode this streamtype. For this, we will get all element factories (which we've seen before in ) and find the ones with the - given MIME-type and capabilities on their sinkpad. Note that we will + given media type and capabilities on their sinkpad. Note that we will only use parsers, demuxers and decoders. We will not use factories for any other element types, or we might get into a loop of encoders and decoders. For this, we will want to build a list of allowed @@ -416,7 +416,7 @@ try_to_plug (GstPad *pad, GstCaps *caps) { GstObject *parent = GST_OBJECT (GST_OBJECT_PARENT (pad)); - const gchar *mime; + const gchar *media; const GList *item; GstCaps *res, *audiocaps; @@ -428,10 +428,10 @@ try_to_plug (GstPad *pad, } /* as said above, we only try to plug audio... Omit video */ - mime = gst_structure_get_name (gst_caps_get_structure (caps, 0)); - if (g_strrstr (mime, "video")) { - g_print ("Omitting link for pad %s:%s because mimetype %s is non-audio\n", - GST_OBJECT_NAME (parent), GST_OBJECT_NAME (pad), mime); + media = gst_structure_get_name (gst_caps_get_structure (caps, 0)); + if (g_strrstr (media, "video")) { + g_print ("Omitting link for pad %s:%s because media type %s is non-audio\n", + GST_OBJECT_NAME (parent), GST_OBJECT_NAME (pad), media); return; } @@ -489,7 +489,7 @@ try_to_plug (GstPad *pad, /* if we get here, no item was found */ g_print ("No compatible pad found to decode %s on %s:%s\n", - mime, GST_OBJECT_NAME (parent), GST_OBJECT_NAME (pad)); + media, GST_OBJECT_NAME (parent), GST_OBJECT_NAME (pad)); } static void diff --git a/docs/manual/advanced-dataaccess.xml b/docs/manual/advanced-dataaccess.xml index be56564..a0cbf89 100644 --- a/docs/manual/advanced-dataaccess.xml +++ b/docs/manual/advanced-dataaccess.xml @@ -17,18 +17,11 @@ Data probing Probing is best envisioned as a pad listener. Technically, a probe is - nothing more than a signal callback that can be attached to a pad. - Those signals are by default not fired at all (since that may have a - negative impact on performance), but can be enabled by attaching a - probe using gst_pad_add_buffer_probe (), - gst_pad_add_event_probe (), or - gst_pad_add_data_probe (). - Those functions attach the signal handler and - enable the actual signal emission. Similarly, one can use the - gst_pad_remove_buffer_probe (), - gst_pad_remove_event_probe (), or - gst_pad_remove_data_probe () - to remove the signal handlers again. + nothing more than a callback that can be attached to a pad. + You can attach a probe using gst_pad_add_probe (). + Similarly, one can use the + gst_pad_remove_probe () + to remove the callback again. Probes run in pipeline threading context, so callbacks should try to @@ -50,18 +43,21 @@ #include <gst/gst.h> -static gboolean -cb_have_data (GstPad *pad, - GstBuffer *buffer, - gpointer u_data) +static GstPadProbeReturn +cb_have_data (GstPad *pad, + GstPadProbeInfo *info, + gpointer user_data) { gint x, y; - GstMapInfo info; + GstMapInfo map; guint16 *ptr, t; + GstBuffer *buffer; + + buffer = GST_PAD_PROBE_INFO_BUFFER (info); - gst_buffer_map (buffer, &info, GST_MAP_WRITE); + gst_buffer_map (buffer, &map, GST_MAP_WRITE); - ptr = info.data; + ptr = (guint16 *) map.data; /* invert data */ for (y = 0; y < 288; y++) { for (x = 0; x < 384 / 2; x++) { @@ -71,7 +67,7 @@ cb_have_data (GstPad *pad, } ptr += 384; } - gst_buffer_unmap (buffer, &info); + gst_buffer_unmap (buffer, &map); return TRUE; } @@ -120,8 +116,9 @@ main (gint argc, g_object_set (G_OBJECT (filter), "caps", filtercaps, NULL); gst_caps_unref (filtercaps); - pad = gst_element_get_pad (src, "src"); - gst_pad_add_buffer_probe (pad, G_CALLBACK (cb_have_data), NULL); + pad = gst_element_get_static_pad (src, "src"); + gst_pad_add_probe (pad, GST_PAD_PROBE_TYPE_BUFFER, + (GstPadProbeCallback) cb_have_data, NULL, NULL); gst_object_unref (pad); /* run */ @@ -150,17 +147,14 @@ main (gint argc, The above example is not really correct though. Strictly speaking, a pad probe callback is only allowed to modify the buffer content if the - buffer is writable, and it is only allowed to modify buffer metadata like - timestamps, caps, etc. if the buffer metadata is writable. Whether this - is the case or not depends a lot on the pipeline and the elements - involved. Often enough, this is the case, but sometimes it is not, - and if it is not then unexpected modification of the data or metadata - can introduce bugs that are very hard to debug and track down. You can - check if a buffer and its metadata are writable with - gst_buffer_is_writable () and - gst_buffer_is_metadata_writable (). Since you - can't pass back a different buffer than the one passed in, there is no - point of making a buffer writable in the callback function. + buffer is writable. Whether this is the case or not depends a lot on + the pipeline and the elements involved. Often enough, this is the case, + but sometimes it is not, and if it is not then unexpected modification + of the data or metadata can introduce bugs that are very hard to debug + and track down. You can check if a buffer is writable with + gst_buffer_is_writable (). Since you + can pass back a different buffer than the one passed in, it is a good + idea to make the buffer writable in the callback function. Pad probes are suited best for looking at data as it passes through @@ -364,11 +358,12 @@ main (gint argc, 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 + the &GStreamer; framework. + If you want to embed elements directly in your application, the only thing you need to do is to replace - GST_PLUGIN_DEFINE () with - GST_PLUGIN_DEFINE_STATIC (). This will cause the - elements to be registered when your application loads, and the elements + GST_PLUGIN_DEFINE () with a call to + gst_plugin_register_static (). As soon as you + call gst_plugin_register_static (), 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 @@ -390,17 +385,25 @@ register_elements (GstPlugin *plugin) GST_RANK_NONE, MY_PLUGIN_TYPE); } -GST_PLUGIN_DEFINE_STATIC ( - GST_VERSION_MAJOR, - GST_VERSION_MINOR, - "my-private-plugins", - "Private elements of my application", - register_elements, - VERSION, - "LGPL", - "my-application", - "http://www.my-application.net/" -) +static +my_code_init (void) +{ + ... + + gst_plugin_register_static ( + GST_VERSION_MAJOR, + GST_VERSION_MINOR, + "my-private-plugins", + "Private elements of my application", + register_elements, + VERSION, + "LGPL", + "my-application-source", + "my-application", + "http://www.my-application.net/") + + ... +} diff --git a/docs/manual/advanced-interfaces.xml b/docs/manual/advanced-interfaces.xml index 1fa5897..ef41f4c 100644 --- a/docs/manual/advanced-interfaces.xml +++ b/docs/manual/advanced-interfaces.xml @@ -48,78 +48,6 @@ - - The Mixer interface - - - The mixer interface provides a uniform way to control the volume on a - hardware (or software) mixer. The interface is primarily intended to - be implemented by elements for audio inputs and outputs that talk - directly to the hardware (e.g. OSS or ALSA plugins). - - - Using this interface, it is possible to control a list of tracks - (such as Line-in, Microphone, etc.) from a mixer element. They can - be muted, their volume can be changed and, for input tracks, their - record flag can be set as well. - - - Example plugins implementing this interface include the OSS elements - (osssrc, osssink, ossmixer) and the ALSA plugins (alsasrc, alsasink - and alsamixer). - - - You should not use this interface for volume control in a playback - application. Either use a volume element or use - playbin's volume property, or use - the audiosink's volume property (if it has one). - - - - In order for the GstMixer - interface to be - usable, the element implementing it needs to be in the right state, - so that the underlying mixer device is open. This usually means the - element needs to be at least in GST_STATE_READY - before you can use this interface. You will get confusing warnings - if the element is not in the right state when the interface is used. - - - - - - The Tuner interface - - - The tuner interface is a uniform way to control inputs and outputs - on a multi-input selection device. This is primarily used for input - selection on elements for TV- and capture-cards. - - - Using this interface, it is possible to select one track from a list - of tracks supported by that tuner-element. The tuner will then select - that track for media-processing internally. This can, for example, be - used to switch inputs on a TV-card (e.g. from Composite to S-video). - - - This interface is currently only implemented by the Video4linux and - Video4linux2 elements. - - - - In order for the GstTuner - interface to be - usable, the element implementing it needs to be in the right state, - so that the underlying device is open. This usually means the - element needs to be at least in GST_STATE_READY - before you can use this interface. You will get confusing warnings - if the element is not in the right state when the interface is used. - - - - The Color Balance interface @@ -132,45 +60,23 @@ The colorbalance interface is implemented by several plugins, including - xvimagesink and the Video4linux and Video4linux2 elements. - - - - - The Property Probe interface - - - The property probe is a way to autodetect allowed values for a - GObject property. It's primary use is to autodetect - devices in several elements. For example, the OSS elements use this - interface to detect all OSS devices on a system. Applications can then - probe this property and get a list of detected devices. - - - - Given the overlap between HAL and the practical implementations of this - interface, this might in time be deprecated in favour of HAL. - - - - This interface is currently implemented by many elements, including - the ALSA, OSS, XVideo, Video4linux and Video4linux2 elements. + xvimagesink and the Video4linux2 elements. - - The X Overlay interface + + The Video Overlay interface - The X Overlay interface was created to solve the problem of embedding + The Video Overlay interface was created to solve the problem of embedding video streams in an application window. The application provides an - X-window to the element implementing this interface to draw on, and - the element will then use this X-window to draw on rather than creating + window handle to the element implementing this interface to draw on, and + the element will then use this window handle to draw on rather than creating a new toplevel window. This is useful to embed video in video players. - This interface is implemented by, amongst others, the Video4linux and - Video4linux2 elements and by ximagesink, xvimagesink and sdlvideosink. + This interface is implemented by, amongst others, the Video4linux2 + elements and by ximagesink, xvimagesink and sdlvideosink. diff --git a/docs/manual/advanced-threads.xml b/docs/manual/advanced-threads.xml index 218606e..cabdcf5 100644 --- a/docs/manual/advanced-threads.xml +++ b/docs/manual/advanced-threads.xml @@ -80,16 +80,14 @@ Scheduling in &GStreamer; - Scheduling of pipelines in &GStreamer; is done by using a thread for - each group, where a group is a set of elements separated - by queue elements. Within such a group, scheduling is - either push-based or pull-based, depending on which mode is supported - by the particular element. If elements support random access to data, - such as file sources, then elements downstream in the pipeline become - the entry point of this group (i.e. the element controlling the - scheduling of other elements). The entry point pulls data from upstream - and pushes data downstream, thereby calling data handling functions on - either type of element. + Each element in the &GStreamer; pipeline decides how it is going to + be scheduled. Elements can choose to be scheduled push-based or + pull-based. + If elements support random access to data, such as file sources, + then elements downstream in the pipeline can ask to schedule the random + access elements in pull-based mode. Data is pulled from upstream + and pushed downstream. If pull-mode is not supported, the element can + decide to operate in push-mode. In practice, most elements in &GStreamer;, such as decoders, encoders, diff --git a/docs/manual/appendix-checklist.xml b/docs/manual/appendix-checklist.xml index f6e0143..8022a5c 100644 --- a/docs/manual/appendix-checklist.xml +++ b/docs/manual/appendix-checklist.xml @@ -74,7 +74,7 @@ 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 + of 9 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: @@ -187,13 +187,5 @@ - - GstEditor - - GstEditor is a set of widgets to display a graphical representation of a - pipeline. - - - diff --git a/docs/manual/appendix-integration.xml b/docs/manual/appendix-integration.xml index c55edb8..007f614 100644 --- a/docs/manual/appendix-integration.xml +++ b/docs/manual/appendix-integration.xml @@ -23,16 +23,15 @@ 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). + &GStreamer; includes elements for ALSA (alsasrc, + alsasink), OSS (osssrc, osssink) Pulesaudio (pulsesrc, pulsesink) + and Sun audio (sunaudiosrc, sunaudiomixer, sunaudiosink). For video input, &GStreamer; contains source elements for - Video4linux (v4lsrc, v4lmjpegsrc, v4lelement and v4lmjpegisnk) - and Video4linux2 (v4l2src, v4l2element). + Video4linux2 (v4l2src, v4l2element, v4l2sink). diff --git a/docs/manual/appendix-porting.xml b/docs/manual/appendix-porting.xml index fe2c8cb..107db3e 100644 --- a/docs/manual/appendix-porting.xml +++ b/docs/manual/appendix-porting.xml @@ -128,3 +128,178 @@ + + Porting 0.10 applications to 1.0 + + This section of the appendix will discuss shortly what changes to + applications will be needed to quickly and conveniently port most + applications from &GStreamer;-0.10 to &GStreamer;-1.0, with references + to the relevant sections in this Application Development Manual + where needed. With this list, it should be possible to port simple + applications to &GStreamer;-1.0 in less than a day. + + + + List of changes + + + + All deprecated methods were removed. Recompile against 0.10 with + DISABLE_DEPRECATED and fix issues before attempting to port to 1.0. + + + + + "playbin2" has been renamed to "playbin", with similar API + + + + + "decodebin2" has been renamed to "decodebin", with similar API. Note + that there is no longer a "new-decoded-pad" signal, just use GstElement's + "pad-added" signal instead (but don't forget to remove the 'gboolean last' + argument from your old signal callback functino signature). + + + + + the names of some "formatted" pad templates has been changed from e.g. + "src%d" to "src%u" or "src_%u" or similar, since we don't want to see + negative numbers in pad names. This mostly affects applications that + create request pads from elements. + + + + + some elements that used to have a single dynamic source pad have a + source pad now. Example: wavparse, id3demux, iceydemux, apedemux. + (This does not affect applications using decodebin or playbin). + + + + + playbin now proxies the GstVideoOverlay (former GstXOverlay) interface, + so most applications can just remove the sync bus handler where they + would set the window ID, and instead just set the window ID on playbin + from the application thread before starting playback. + + + playbin also proxies the GstColorBalance and GstNavigation interfaces, + so applications that use this don't need to go fishing for elements + that may implement those any more, but can just use them unconditionally. + + + + + multifdsink, tcpclientsink, tcpclientsrc, tcpserversrc the protocol property + is removed, use gdppay and gdpdepay. + + + + + XML serialization was removed. + + + + + Probes and pad blocking was merged into new pad probes. + + + + + Position, duration and convert functions no longer use an inout parameter + for the destination format. + + + + + Video and audio caps were simplified. audio/x-raw-int and audio/x-raw-float + are now all under the audio/x-raw media type. Similarly, video/x-raw-rgb + and video/x-raw-yuv are now video/x-raw. + + + + + ffmpegcolorspace was removed and replaced with videoconvert. + + + + + GstMixerInterface / GstTunerInterface were removed without replacement. + + + + + The GstXOverlay interface was renamed to GstVideoOverlay, and now part + of the video library in gst-plugins-base, as the interfaces library + no longer exists. + + + The name of the GstXOverlay "prepare-xwindow-id" message has changed + to "prepare-window-handle" (and GstXOverlay has been renamed to + GstVideoOverlay). Code that checks for the string directly should be + changed to use gst_is_video_overlay_prepare_window_handle_message(message) + instead. + + + + + The GstPropertyProbe interface was removed. the is no replacement yet, + but a more featureful replacement for device discovery and feature + querying is planned, see https://bugzilla.gnome.org/show_bug.cgi?id=678402 + + + + + gst_uri_handler_get_uri() and the get_uri vfunc now return a copy of + the URI string + + + gst_uri_handler_set_uri() and the set_uri vfunc now take an additional + GError argument so the handler can notify the caller why it didn't + accept a particular URI. + + + gst_uri_handler_set_uri() now checks if the protocol of the URI passed + is one of the protocols advertised by the uri handler, so set_uri vfunc + implementations no longer need to check that as well. + + + + + GstTagList is now an opaque mini object instead of being typedefed to a + GstStructure. While it was previously okay (and in some cases required because of + missing taglist API) to cast a GstTagList to a GstStructure or use + gst_structure_* API on taglists, you can no longer do that. Doing so will + cause crashes. + + + Also, tag lists are refcounted now, and can therefore not be freely + modified any longer. Make sure to call gst_tag_list_make_writable (taglist) + before adding, removing or changing tags in the taglist. + + + GST_TAG_IMAGE, GST_TAG_PREVIEW_IMAGE, GST_TAG_ATTACHMENT: many tags that + used to be of type GstBuffer are now of type GstSample (which is basically + a struct containing a buffer alongside caps and some other info). + + + + + GstController has now been merged into GstObject. It does not exists as an + individual object anymore. In addition core contains a GstControlSource base + class and the GstControlBinding. The actual control sources are in the controller + library as before. The 2nd big change is that control sources generate + a sequence of gdouble values and those are mapped to the property type and + value range by GstControlBindings. + + + The whole gst_controller_* API is gone and now available in simplified form + under gst_object_*. ControlSources are now attached via GstControlBinding + to properties. There are no GValue arguments used anymore when programming + control sources. + + + + + diff --git a/docs/manual/basics-bins.xml b/docs/manual/basics-bins.xml index af736ee..1e3155e 100644 --- a/docs/manual/basics-bins.xml +++ b/docs/manual/basics-bins.xml @@ -19,11 +19,8 @@ The bin will also manage the elements contained in it. It will - figure out how the data will flow in the bin and generate an - optimal plan for that data flow. Plan generation is one of the - most complicated procedures in &GStreamer;. You will learn more - about this process, called scheduling, in . + perform state changes on the elements as well as collect and + forward bus messages.
@@ -42,10 +39,10 @@ - A pipeline: a generic container that allows scheduling of the - containing elements. The toplevel bin has to be a pipeline, - every application thus needs at least one of these. Pipelines will - automatically run themselves in a background thread when started. + A pipeline: a generic container that manages the synchronization + and bus messages of the contained elements. The toplevel bin has + to be a pipeline, every application thus needs at least one of + these. @@ -139,17 +136,17 @@ main (int argc, (This is a silly example of course, there already exists a much more - powerful and versatile custom bin like this: the playbin2 element.) + powerful and versatile custom bin like this: the playbin element.) - Custom bins can be created with a plugin or an XML description. You + Custom bins can be created with a plugin or from the application. You will find more information about creating custom bin in the Plugin Writers Guide. - Examples of such custom bins are the playbin2 and uridecodebin elements from gst-plugins-base. diff --git a/docs/manual/basics-bus.xml b/docs/manual/basics-bus.xml index 867826d..46e037a 100644 --- a/docs/manual/basics-bus.xml +++ b/docs/manual/basics-bus.xml @@ -97,6 +97,7 @@ main (gint argc, { GstElement *pipeline; GstBus *bus; + guint bus_watch_id; /* init */ gst_init (&argc, &argv); @@ -109,7 +110,7 @@ main (gint argc, * GLib main loop is attached to below */ bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); - gst_bus_add_watch (bus, my_bus_callback, NULL); + bus_watch_id = gst_bus_add_watch (bus, my_bus_callback, NULL); gst_object_unref (bus); [..] @@ -127,6 +128,7 @@ main (gint argc, /* clean up */ gst_element_set_state (pipeline, GST_STATE_NULL); gst_object_unref (pipeline); + g_source_remove (bus_watch_id); g_main_loop_unref (loop); return 0; diff --git a/docs/manual/basics-data.xml b/docs/manual/basics-data.xml index bbdb4a6..d8972e0 100644 --- a/docs/manual/basics-data.xml +++ b/docs/manual/basics-data.xml @@ -24,12 +24,8 @@ - A pointer to a piece of memory. - - - - - The size of the memory. + Pointers to memory objects. Memory objects encapsulate a region + in the memory. diff --git a/docs/manual/basics-elements.xml b/docs/manual/basics-elements.xml index f047981..33b805f 100644 --- a/docs/manual/basics-elements.xml +++ b/docs/manual/basics-elements.xml @@ -289,7 +289,7 @@ main (int argc, The Glib Object system. - A + A GstElement also provides various GObject signals that can be used as a flexible callback mechanism. Here, too, you can use gst-inspect @@ -303,17 +303,14 @@ main (int argc, More about element factories In the previous section, we briefly introduced the GstElementFactory + url="&URLAPI;GstElementFactory.html">GstElementFactory object already as a way to create instances of an element. Element factories, however, are much more than just that. Element factories are the basic types retrieved from the &GStreamer; registry, they describe all plugins and elements that &GStreamer; can create. This means that element factories are useful for automated element instancing, such as what autopluggers do, and for creating lists - of available elements, such as what pipeline editing applications - (e.g. &GStreamer; - Editor) do. + of available elements. diff --git a/docs/manual/basics-helloworld.xml b/docs/manual/basics-helloworld.xml index 46360dd..9097b20 100644 --- a/docs/manual/basics-helloworld.xml +++ b/docs/manual/basics-helloworld.xml @@ -44,8 +44,8 @@ The last thing left to do is to add all elements into a container - element, a GstPipeline, and iterate this - pipeline until we've played the whole song. We've previously + element, a GstPipeline, and wait until + we've played the whole song. We've previously learned how to add elements to a container bin in , and we've learned about element states in . We will also attach @@ -125,6 +125,7 @@ main (int argc, GstElement *pipeline, *source, *demuxer, *decoder, *conv, *sink; GstBus *bus; + guint bus_watch_id; /* Initialisation */ gst_init (&argc, &argv); @@ -159,7 +160,7 @@ main (int argc, /* we add a message handler */ bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); - gst_bus_add_watch (bus, bus_call, loop); + bus_watch_id = gst_bus_add_watch (bus, bus_call, loop); gst_object_unref (bus); /* we add all elements into the pipeline */ @@ -197,6 +198,8 @@ main (int argc, g_print ("Deleting pipeline\n"); gst_object_unref (GST_OBJECT (pipeline)); + g_source_remove (bus_watch_id); + g_main_loop_unref (loop); return 0; } diff --git a/docs/manual/highlevel-components.xml b/docs/manual/highlevel-components.xml index 1981ee4..b82c26c 100644 --- a/docs/manual/highlevel-components.xml +++ b/docs/manual/highlevel-components.xml @@ -172,12 +172,9 @@ main (gint argc, For convenience, it is possible to test playbin on - the commandline, using the command gst-launch-0.10 playbin + the commandline, using the command gst-launch-1.0 playbin uri=file:///path/to/file. - - New applications should use playbin2 instead of the old playbin. - @@ -189,7 +186,7 @@ main (gint argc, input from a source that is linked to its sinkpad and will try to detect the media type contained in the stream, and set up decoder routines for each of those. It will automatically select decoders. - For each decoded stream, it will emit the new-decoded-pad + For each decoded stream, it will emit the pad-added signal, to let the client know about the newly found decoded stream. For unknown streams (which might be the whole stream), it will emit the unknown-type signal. The application is then @@ -238,7 +235,6 @@ GstElement *pipeline, *audio; static void cb_newpad (GstElement *decodebin, GstPad *pad, - gboolean last, gpointer data) { GstCaps *caps; @@ -297,7 +293,7 @@ main (gint argc, src = gst_element_factory_make ("filesrc", "source"); g_object_set (G_OBJECT (src), "location", argv[1], NULL); dec = gst_element_factory_make ("decodebin", "decoder"); - g_signal_connect (dec, "new-decoded-pad", G_CALLBACK (cb_newpad), NULL); + g_signal_connect (dec, "pad-added", G_CALLBACK (cb_newpad), NULL); gst_bin_add_many (GST_BIN (pipeline), src, dec, NULL); gst_element_link (src, dec); @@ -367,14 +363,11 @@ main (gint argc, Decodebin can be easily tested on the commandline, e.g. by using the - command gst-launch-0.10 filesrc location=file.ogg ! decodebin + command gst-launch-1.0 filesrc location=file.ogg ! decodebin ! audioconvert ! audioresample ! autoaudiosink. - New applications should use decodebin2 instead of the old decodebin. - - - The uridecodebin element is very similar to decodebin2, only that it + The uridecodebin element is very similar to decodebin, only that it automatically plugs a source plugin based on the protocol of the URI given. diff --git a/docs/manual/intro-basics.xml b/docs/manual/intro-basics.xml index b0c2806..0c385b1 100644 --- a/docs/manual/intro-basics.xml +++ b/docs/manual/intro-basics.xml @@ -59,10 +59,10 @@ through one or more sink pads. Source and sink elements have only source and sink pads, respectively. Data usually means buffers (described by the GstBuffer - object) and events (described by the - GstEvent object). + url="&URLAPI;gstreamer-GstBuffer.html"> + GstBuffer object) and events (described + by the + GstEvent object). @@ -71,8 +71,7 @@ A bin is a container for a collection of elements. - A pipeline is a special subtype of a bin that allows execution of all - of its contained child elements. Since bins are subclasses of 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 @@ -80,9 +79,11 @@ contained children (such as error messages, tag messages or EOS messages). - A pipeline 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 + A pipeline is a top-level bin. It provides a bus for + the application and manages the synchronization for its children. + 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. diff --git a/docs/manual/manual.xml b/docs/manual/manual.xml index af6466e..0f147b9 100644 --- a/docs/manual/manual.xml +++ b/docs/manual/manual.xml @@ -47,7 +47,6 @@ - @@ -191,8 +190,8 @@ much control (and as much code), but will prefer to use a standard playback interface that does most of the difficult internals for them. In this chapter, we will introduce you into the concept of - autopluggers, playback managing elements, XML-based pipelines and - other such things. Those higher-level interfaces are intended to + autopluggers, playback managing elements and other such things. + Those higher-level interfaces are intended to simplify &GStreamer;-based application programming. They do, however, also reduce the flexibility. It is up to the application developer to choose which interface he will want to use. @@ -200,7 +199,6 @@ &COMPONENTS; - &XML; @@ -221,7 +219,7 @@ In addition, we also provide a porting guide which will explain - easily how to port &GStreamer;-0.8 applications to &GStreamer;-0.10. + easily how to port &GStreamer;-0.10 applications to &GStreamer;-1.0. diff --git a/docs/random/porting-to-1.0.txt b/docs/random/porting-to-1.0.txt index 5143c95..070ad29 100644 --- a/docs/random/porting-to-1.0.txt +++ b/docs/random/porting-to-1.0.txt @@ -207,8 +207,8 @@ GStreamer 0.10 to 1.0 porting guide The GST_MINI_OBJECT_READONLY flag was removed as it used to mark the memory in buffers as READONLY. Marking memory READONLY can now be done - with the GstMemory API. Writability of miniobjects is now only done by using - the refcount. + with the GstMemory API. Writability of miniobjects is now either done + by using the refcount or by using exclusive locking. * GstBuffer A GstBuffer is now a simple boxed type this means that subclassing is not diff --git a/tests/examples/manual/Makefile.am b/tests/examples/manual/Makefile.am index 7d87111..65d997c 100644 --- a/tests/examples/manual/Makefile.am +++ b/tests/examples/manual/Makefile.am @@ -35,6 +35,7 @@ EXAMPLES = \ init \ query \ typefind \ + probe \ fakesrc \ playbin \ decodebin @@ -48,6 +49,7 @@ BUILT_SOURCES = \ init.c \ query.c \ typefind.c dynamic.c \ + probe.c \ fakesrc.c \ playbin.c decodebin.c @@ -81,6 +83,9 @@ query.c: $(top_srcdir)/docs/manual/advanced-position.xml typefind.c dynamic.c: $(top_srcdir)/docs/manual/advanced-autoplugging.xml $(PERL_PATH) $(srcdir)/extract.pl $@ $< +probe.c: $(top_srcdir)/docs/manual/advanced-dataaccess.xml + $(PERL_PATH) $(srcdir)/extract.pl $@ $< + fakesrc.c: $(top_srcdir)/docs/manual/advanced-dataaccess.xml $(PERL_PATH) $(srcdir)/extract.pl $@ $< -- 2.7.4