From 41e812d075da360470f408bfe120fbb83dd91575 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= Date: Thu, 17 Aug 2017 13:10:30 +0300 Subject: [PATCH] Update docs --- docs/gstreamer-app/docs.md | 110 +++++++------- docs/gstreamer-audio/docs.md | 70 +++++++++ docs/gstreamer-player/docs.md | 15 -- docs/gstreamer/docs.md | 265 +++++++++++++++++++++++++++++++++- 4 files changed, 382 insertions(+), 78 deletions(-) diff --git a/docs/gstreamer-app/docs.md b/docs/gstreamer-app/docs.md index 7ccd313da..c89f56259 100644 --- a/docs/gstreamer-app/docs.md +++ b/docs/gstreamer-app/docs.md @@ -8,10 +8,10 @@ appsink can be used by linking to the gstappsink.h header file to access the methods or by using the appsink action signals and properties. The normal way of retrieving samples from appsink is by using the -`AppSinkExt::pull_sample` and `AppSinkExt::pull_preroll` methods. +`AppSink::pull_sample` and `AppSink::pull_preroll` methods. These methods block until a sample becomes available in the sink or when the sink is shut down or reaches EOS. There are also timed variants of these -methods, `AppSinkExt::try_pull_sample` and `AppSinkExt::try_pull_preroll`, +methods, `AppSink::try_pull_sample` and `AppSink::try_pull_preroll`, which accept a timeout parameter to limit the amount of time to wait. Appsink will internally use a queue to collect buffers from the streaming @@ -32,21 +32,15 @@ the pulled samples can be obtained by getting the sample caps. If one of the pull-preroll or pull-sample methods return `None`, the appsink is stopped or in the EOS state. You can check for the EOS state with the -"eos" property or with the `AppSinkExt::is_eos` method. +"eos" property or with the `AppSink::is_eos` method. The eos signal can also be used to be informed when the EOS state is reached to avoid polling. # Implements -[`AppSinkExt`](trait.AppSinkExt.html), [`ObjectExt`](trait.ObjectExt.html) - -Trait containing all `AppSink` methods. - -# Implementors - -[`AppSink`](struct.AppSink.html) - +[`ElementExt`](trait.ElementExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ObjectExt`](trait.ObjectExt.html) + Check if `self` supports buffer lists. Feature: `v1_12` @@ -55,13 +49,13 @@ Feature: `v1_12` # Returns `true` if `self` supports buffer lists. - + Get the configured caps on `self`. # Returns the `gst::Caps` accepted by the sink. `gst_caps_unref` after usage. - + Check if `self` will drop old buffers when the maximum amount of queued buffers is reached. @@ -69,20 +63,20 @@ buffers is reached. `true` if `self` is dropping old buffers when the queue is filled. - + Check if appsink will emit the "new-preroll" and "new-sample" signals. # Returns `true` if `self` is emiting the "new-preroll" and "new-sample" signals. - + Get the maximum amount of buffers that can be queued in `self`. # Returns The maximum amount of buffers that can be queued. - + Check if `self` will wait for all buffers to be consumed when an EOS is received. @@ -90,7 +84,7 @@ received. `true` if `self` will wait for all buffers to be consumed when an EOS is received. - + Check if `self` is EOS, which is when no more samples can be pulled because an EOS event was received. @@ -100,7 +94,7 @@ PLAYING state. # Returns `true` if no more samples can be pulled and the appsink is EOS. - + Get the last preroll sample in `self`. This was the sample that caused the appsink to preroll in the PAUSED state. This sample can be pulled many times and remains available to the application even after EOS. @@ -110,7 +104,7 @@ state. Calling this function after doing a seek will give the sample right after the seek position. Note that the preroll sample will also be returned as the first sample -when calling `AppSinkExt::pull_sample`. +when calling `AppSink::pull_sample`. If an EOS event was received before any buffers, this function returns `None`. Use gst_app_sink_is_eos () to check for the EOS condition. @@ -122,7 +116,7 @@ element is set to the READY/NULL state. a `gst::Sample` or NULL when the appsink is stopped or EOS. Call `gst_sample_unref` after usage. - + This function blocks until a sample or EOS becomes available or the appsink element is set to the READY/NULL state. @@ -139,7 +133,7 @@ If an EOS event was received before any buffers, this function returns a `gst::Sample` or NULL when the appsink is stopped or EOS. Call `gst_sample_unref` after usage. - + Instruct `self` to enable or disable buffer list support. For backwards-compatibility reasons applications need to opt in @@ -149,7 +143,7 @@ Feature: `v1_12` ## `enable_lists` enable or disable buffer list support - + Set callbacks which will be executed for each new preroll, new sample and eos. This is an alternative to using the signals, it has lower overhead and is thus less expensive, but also less flexible. @@ -162,35 +156,35 @@ the callbacks a user_data argument for the callbacks ## `notify` a destroy notify function - + Set the capabilities on the appsink element. This function takes a copy of the caps structure. After calling this method, the sink will only accept caps that match `caps`. If `caps` is non-fixed, or incomplete, you must check the caps on the samples to get the actual used caps. ## `caps` caps to set - + Instruct `self` to drop old buffers when the maximum amount of queued buffers is reached. ## `drop` the new state - + Make appsink emit the "new-preroll" and "new-sample" signals. This option is by default disabled because signal emission is expensive and unneeded when the application prefers to operate in pull mode. ## `emit` the new state - + Set the maximum amount of buffers that can be queued in `self`. After this amount of buffers are queued in appsink, any more buffers will block upstream elements until a sample is pulled from `self`. ## `max` the maximum number of buffers to queue - + Instruct `self` to wait for all buffers to be consumed when an EOS is received. ## `wait` the new state - + Get the last preroll sample in `self`. This was the sample that caused the appsink to preroll in the PAUSED state. This sample can be pulled many times and remains available to the application even after EOS. @@ -200,7 +194,7 @@ state. Calling this function after doing a seek will give the sample right after the seek position. Note that the preroll sample will also be returned as the first sample -when calling `AppSinkExt::pull_sample`. +when calling `AppSink::pull_sample`. If an EOS event was received before any buffers or the timeout expires, this function returns `None`. Use gst_app_sink_is_eos () to check for the EOS @@ -218,7 +212,7 @@ the maximum amount of time to wait for the preroll sample a `gst::Sample` or NULL when the appsink is stopped or EOS or the timeout expires. Call `gst_sample_unref` after usage. - + This function blocks until a sample or EOS becomes available or the appsink element is set to the READY/NULL state or the timeout expires. @@ -259,7 +253,7 @@ sample and sets them on the appsrc replacing any previously set caps (if different from sample's caps). The main way of handing data to the appsrc element is by calling the -`AppSrcExt::push_buffer` method or by emitting the push-buffer action signal. +`AppSrc::push_buffer` method or by emitting the push-buffer action signal. This will put the buffer onto a queue from which appsrc will read from in its streaming thread. It is important to note that data transport will not happen from the thread that performed the push-buffer call. @@ -303,20 +297,14 @@ For the stream and seekable modes, setting this property is optional but recommended. When the application has finished pushing data into appsrc, it should call -`AppSrcExt::end_of_stream` or emit the end-of-stream action signal. After +`AppSrc::end_of_stream` or emit the end-of-stream action signal. After this call, no more buffers can be pushed into appsrc until a flushing seek occurs or the state of the appsrc has gone through READY. # Implements -[`AppSrcExt`](trait.AppSrcExt.html), [`ObjectExt`](trait.ObjectExt.html) - -Trait containing all `AppSrc` methods. - -# Implementors - -[`AppSrc`](struct.AppSrc.html) - +[`ElementExt`](trait.ElementExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ObjectExt`](trait.ObjectExt.html) + Indicates to the appsrc element that the last buffer queued in the element is the last buffer of the stream. @@ -324,19 +312,19 @@ element is the last buffer of the stream. `gst::FlowReturn::Ok` when the EOS was successfuly queued. `gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING. - + Get the configured caps on `self`. # Returns the `gst::Caps` produced by the source. `gst_caps_unref` after usage. - + Get the number of currently queued bytes inside `self`. # Returns The number of currently queued bytes. - + Get the duration of the stream in nanoseconds. A value of GST_CLOCK_TIME_NONE means that the duration is not known. @@ -345,41 +333,41 @@ Feature: `v1_10` # Returns -the duration of the stream previously set with `AppSrcExt::set_duration`; - +the duration of the stream previously set with `AppSrc::set_duration`; + Check if appsrc will emit the "new-preroll" and "new-buffer" signals. # Returns `true` if `self` is emitting the "new-preroll" and "new-buffer" signals. - + Retrieve the min and max latencies in `min` and `max` respectively. ## `min` the min latency ## `max` the min latency - + Get the maximum amount of bytes that can be queued in `self`. # Returns The maximum amount of bytes that can be queued. - + Get the size of the stream in bytes. A value of -1 means that the size is not known. # Returns -the size of the stream previously set with `AppSrcExt::set_size`; - +the size of the stream previously set with `AppSrc::set_size`; + Get the stream type. Control the stream type of `self` -with `AppSrcExt::set_stream_type`. +with `AppSrc::set_stream_type`. # Returns the stream type. - + Adds a buffer to the queue of buffers that the appsrc element will push to its source pad. This function takes ownership of the buffer. @@ -393,7 +381,7 @@ a `gst::Buffer` to push `gst::FlowReturn::Ok` when the buffer was successfuly queued. `gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING. `gst::FlowReturn::Eos` when EOS occured. - + Extract a buffer from the provided sample and adds it to the queue of buffers that the appsrc element will push to its source pad. Any previous caps that were set on appsrc will be replaced by the caps @@ -410,7 +398,7 @@ extracted `gst::FlowReturn::Ok` when the buffer was successfuly queued. `gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING. `gst::FlowReturn::Eos` when EOS occured. - + Set callbacks which will be executed when data is needed, enough data has been collected or when a seek should be performed. This is an alternative to using the signals, it has lower overhead and is thus @@ -424,14 +412,14 @@ the callbacks a user_data argument for the callbacks ## `notify` a destroy notify function - + Set the capabilities on the appsrc element. This function takes a copy of the caps structure. After calling this method, the source will only produce caps that match `caps`. `caps` must be fixed and the caps on the buffers must match the caps or left NULL. ## `caps` caps to set - + Set the duration of the stream in nanoseconds. A value of GST_CLOCK_TIME_NONE means that the duration is not known. @@ -439,31 +427,31 @@ Feature: `v1_10` ## `duration` the duration to set - + Make appsrc emit the "new-preroll" and "new-buffer" signals. This option is by default disabled because signal emission is expensive and unneeded when the application prefers to operate in pull mode. ## `emit` the new state - + Configure the `min` and `max` latency in `src`. If `min` is set to -1, the default latency calculations for pseudo-live sources will be used. ## `min` the min latency ## `max` the min latency - + Set the maximum amount of bytes that can be queued in `self`. After the maximum amount of bytes are queued, `self` will emit the "enough-data" signal. ## `max` the maximum number of bytes to queue - + Set the size of the stream in bytes. A value of -1 means that the size is not known. ## `size` the size to set - + Set the stream type on `self`. For seekable streams, the "seek" signal must be connected to. diff --git a/docs/gstreamer-audio/docs.md b/docs/gstreamer-audio/docs.md index db14eae55..38f41615e 100644 --- a/docs/gstreamer-audio/docs.md +++ b/docs/gstreamer-audio/docs.md @@ -266,3 +266,73 @@ Layout of the audio samples for the different channels. interleaved audio non-interleaved audio + +This interface is implemented by elements that provide a stream volume. Examples for +such elements are `volume` and `playbin`. + +Applications can use this interface to get or set the current stream volume. For this +the "volume" `gobject::Object` property can be used or the helper functions `StreamVolume::set_volume` +and `StreamVolume::get_volume`. This volume is always a linear factor, i.e. 0.0 is muted +1.0 is 100%. For showing the volume in a GUI it might make sense to convert it to +a different format by using `StreamVolume::convert_volume`. Volume sliders should usually +use a cubic volume. + +Separate from the volume the stream can also be muted by the "mute" `gobject::Object` property or +`StreamVolume::set_mute` and `StreamVolume::get_mute`. + +Elements that provide some kind of stream volume should implement the "volume" and +"mute" `gobject::Object` properties and handle setting and getting of them properly. +The volume property is defined to be a linear volume factor. + +# Implements + +[`StreamVolumeExt`](trait.StreamVolumeExt.html) + +Trait containing all `StreamVolume` methods. + +# Implementors + +[`StreamVolume`](struct.StreamVolume.html) + +## `from` +`StreamVolumeFormat` to convert from +## `to` +`StreamVolumeFormat` to convert to +## `val` +Volume in `from` format that should be converted + +# Returns + +the converted volume + + +# Returns + +Returns `true` if the stream is muted + +## `format` +`StreamVolumeFormat` which should be returned + +# Returns + +The current stream volume as linear factor + +## `mute` +Mute state that should be set + +## `format` +`StreamVolumeFormat` of `val` +## `val` +Linear volume factor that should be set + +Different representations of a stream volume. `StreamVolume::convert_volume` +allows to convert between the different representations. + +Formulas to convert from a linear to a cubic or dB volume are +cbrt(val) and 20 * log10 (val). + +Linear scale factor, 1.0 = 100% + +Cubic volume scale + +Logarithmic volume scale (dB, amplitude not power) diff --git a/docs/gstreamer-player/docs.md b/docs/gstreamer-player/docs.md index 2ca88519b..07c679558 100644 --- a/docs/gstreamer-player/docs.md +++ b/docs/gstreamer-player/docs.md @@ -113,9 +113,6 @@ If accurate seeking is disabled, elements will seek as close as the request position without slowing down seeking too much. Accurate seeking is disabled by default. - -Feature: `v1_12` - ## `accurate` accurate seek or not @@ -500,33 +497,21 @@ Application can use gst_sample_*`_` API's to get caps, buffer etc. GstSample or NULL. -Feature: `v1_12` - - # Returns number of audio streams. -Feature: `v1_12` - - # Returns number of total streams. -Feature: `v1_12` - - # Returns number of subtitle streams. -Feature: `v1_12` - - # Returns number of video streams. diff --git a/docs/gstreamer/docs.md b/docs/gstreamer/docs.md index d4fec404d..8bf90e364 100644 --- a/docs/gstreamer/docs.md +++ b/docs/gstreamer/docs.md @@ -2163,7 +2163,7 @@ Trait containing all `Clock` methods. # Implementors -[`Clock`](struct.Clock.html) +[`Clock`](struct.Clock.html), [`SystemClock`](struct.SystemClock.html) Compares the two `ClockID` instances. This function can be used as a GCompareFunc when sorting ids. @@ -2605,6 +2605,33 @@ timeout for waiting or `GST_CLOCK_TIME_NONE` # Returns `true` if waiting was successful, or `false` on timeout + +The return value of a clock operation. + +The operation succeeded. + +The operation was scheduled too late. + +The clockID was unscheduled + +The ClockID is busy + +A bad time was provided to a function. + +An error occurred + +Operation is not supported + +The ClockID is done waiting + +The different kind of clocks. + +time since Epoch + +monotonic time since some unspecified starting + point + +some other time source is used (Since 1.0.5) `Context` is a container object used to store contexts like a device context, a display server connection and similar concepts that should @@ -3550,7 +3577,7 @@ Trait containing all `Element` methods. # Implementors -[`Bin`](struct.Bin.html), [`Element`](struct.Element.html), [`TagSetter`](struct.TagSetter.html) +[`Bin`](struct.Bin.html), [`Element`](struct.Element.html), [`TagSetter`](struct.TagSetter.html), [`TocSetter`](struct.TocSetter.html) Creates an element for handling the given URI. ## `type_` @@ -10637,6 +10664,22 @@ Get the structure of a query. This method should be called with a writable the `Structure` of the query. The structure is still owned by the query and will therefore be freed when the query is unreffed. + +Element priority ranks. Defines the order in which the autoplugger (or +similar rank-picking mechanisms, such as e.g. `Element::make_from_uri`) +will choose this element over an alternative one with the same function. + +These constants serve as a rough guidance for defining the rank of a +`PluginFeature`. Any value is valid, including values bigger than +`Rank::Primary`. + +will be chosen last or not at all + +unlikely to be chosen + +likely to be chosen + +will be chosen first Resource errors are for any resource used by an element: memory, files, network connections, process space, ... @@ -12236,6 +12279,47 @@ The type of a `MessageType::StructureChange`. Pad linking is starting or done. Pad unlinking is starting or done. + +The GStreamer core provides a GstSystemClock based on the system time. +Asynchronous callbacks are scheduled from an internal thread. + +Clock implementors are encouraged to subclass this systemclock as it +implements the async notification. + +Subclasses can however override all of the important methods for sync and +async notifications to implement their own callback methods or blocking +wait operations. + +# Implements + +[`SystemClockExt`](trait.SystemClockExt.html), [`ClockExt`](trait.ClockExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `SystemClock` methods. + +# Implementors + +[`SystemClock`](struct.SystemClock.html) + +Get a handle to the default system clock. The refcount of the +clock will be increased so you need to unref the clock after +usage. + +# Returns + +the default clock. + +MT safe. + +Sets the default system clock that can be obtained with +`SystemClock::obtain`. + +This is mostly used for testing and debugging purposes when you +want to have control over the time reported by the default system +clock. + +MT safe. +## `new_clock` +a `Clock` List of tags and values used to describe media metadata. @@ -13007,6 +13091,183 @@ specified by this interface. The default is `TagMergeMode::Keep`, which keeps the tags set with this interface and discards tags from events. ## `mode` The mode with which tags are added + +`Toc` functions are used to create/free `Toc` and `TocEntry` structures. +Also they are used to convert `Toc` into `Structure` and vice versa. + +`Toc` lets you to inform other elements in pipeline or application that playing +source has some kind of table of contents (TOC). These may be chapters, editions, +angles or other types. For example: DVD chapters, Matroska chapters or cue sheet +TOC. Such TOC will be useful for applications to display instead of just a +playlist. + +Using TOC is very easy. Firstly, create `Toc` structure which represents root +contents of the source. You can also attach TOC-specific tags to it. Then fill +it with `TocEntry` entries by appending them to the `Toc` using +`Toc::append_entry`, and appending subentries to a `TocEntry` using +`TocEntry::append_sub_entry`. + +Note that root level of the TOC can contain only either editions or chapters. You +should not mix them together at the same level. Otherwise you will get serialization +/deserialization errors. Make sure that no one of the entries has negative start and + stop values. + +Use `Event::new_toc` to create a new TOC `Event`, and `Event::parse_toc` to +parse received TOC event. Use `Event::new_toc_select` to create a new TOC select `Event`, +and `Event::parse_toc_select` to parse received TOC select event. The same rule for +the `Message`: `Message::new_toc` to create new TOC `Message`, and +`Message::parse_toc` to parse received TOC message. + +TOCs can have global scope or current scope. Global scope TOCs contain +all entries that can possibly be selected using a toc select event, and +are what an application is usually interested in. TOCs with current scope +only contain the parts of the TOC relevant to the currently selected/playing +stream; the current scope TOC is used by downstream elements such as muxers +to write correct TOC entries when transcoding files, for example. When +playing a DVD, the global TOC would contain a hierarchy of all titles, +chapters and angles, for example, while the current TOC would only contain +the chapters for the currently playing title if playback of a specific +title was requested. + +Applications and plugins should not rely on TOCs having a certain kind of +structure, but should allow for different alternatives. For example, a +simple CUE sheet embedded in a file may be presented as a flat list of +track entries, or could have a top-level edition node (or some other +alternative type entry) with track entries underneath that node; or even +multiple top-level edition nodes (or some other alternative type entries) +each with track entries underneath, in case the source file has extracted +a track listing from different sources). + +Create a new `Toc` structure. +## `scope` +scope of this TOC + +# Returns + +newly allocated `Toc` structure, free it + with `gst_toc_unref`. + +Appends the `TocEntry` `entry` to `self`. +## `entry` +A `TocEntry` + +Find `TocEntry` with given `uid` in the `self`. +## `uid` +UID to find `TocEntry` with. + +# Returns + +`TocEntry` with specified +`uid` from the `self`, or `None` if not found. + +Gets the list of `TocEntry` of `self`. + +# Returns + +A `glib::List` of `TocEntry` for `entry` + + +# Returns + +scope of `self` + +Gets the tags for `self`. + +# Returns + +A `TagList` for `entry` + +Merge `tags` into the existing tags of `self` using `mode`. +## `tags` +A `TagList` or `None` +## `mode` +A `TagMergeMode` + +Set a `TagList` with tags for the complete `self`. +## `tags` +A `TagList` or `None` + +The different types of TOC entries (see `TocEntry`). + +There are two types of TOC entries: alternatives or parts in a sequence. + +entry is an angle (i.e. an alternative) + +entry is a version (i.e. alternative) + +entry is an edition (i.e. alternative) + +invalid entry type value + +entry is a title (i.e. a part of a sequence) + +entry is a track (i.e. a part of a sequence) + +entry is a chapter (i.e. a part of a sequence) + +How a `TocEntry` should be repeated. By default, entries are played a +single time. + +single forward playback + +repeat forward + +repeat backward + +repeat forward and backward + +The scope of a TOC. + +global TOC representing all selectable options + (this is what applications are usually interested in) + +TOC for the currently active/selected stream + (this is a TOC representing the current stream from start to EOS, + and is what a TOC writer / muxer is usually interested in; it will + usually be a subset of the global TOC, e.g. just the chapters of + the current title, or the chapters selected for playback from the + current title) + +Element interface that allows setting of the TOC. + +Elements that support some kind of chapters or editions (or tracks like in +the FLAC cue sheet) will implement this interface. + +If you just want to retrieve the TOC in your application then all you +need to do is watch for TOC messages on your pipeline's bus (or you can +perform TOC query). This interface is only for setting TOC data, not for +extracting it. To set TOC from the application, find proper tocsetter element +and set TOC using `TocSetter::set_toc`. + +Elements implementing the `TocSetter` interface can extend existing TOC +by getting extend UID for that (you can use `Toc::find_entry` to retrieve it) +with any TOC entries received from downstream. + +# Implements + +[`TocSetterExt`](trait.TocSetterExt.html), [`ElementExt`](trait.ElementExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ObjectExt`](trait.ObjectExt.html) + +Trait containing all `TocSetter` methods. + +# Implementors + +[`TocSetter`](struct.TocSetter.html) + +Return current TOC the setter uses. The TOC should not be +modified without making it writable first. + +# Returns + +TOC set, or `None`. Unref with + `gst_toc_unref` when no longer needed + +Reset the internal TOC. Elements should call this from within the +state-change handler. + +Set the given TOC on the setter. Previously set TOC will be +unreffed before setting a new one. +## `toc` +a `Toc` to set. Different URI-related errors that can occur.