From f3924399aa64cd97dffa95ffcf18ee7a1994522c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= Date: Tue, 20 Mar 2018 12:36:29 +0200 Subject: [PATCH] Update docs to 1.14.0 --- docs/gstreamer-app/docs.md | 59 ++- docs/gstreamer-audio/docs.md | 110 ++++ docs/gstreamer-base/docs.md | 36 ++ docs/gstreamer-net/docs.md | 4 + docs/gstreamer-pbutils/docs.md | 49 +- docs/gstreamer-player/docs.md | 32 +- docs/gstreamer-rtsp-server/docs.md | 196 ++++++- docs/gstreamer-rtsp/docs.md | 2 +- docs/gstreamer-video/docs.md | 51 +- docs/gstreamer/docs.md | 818 +++++++++++++++++++++++++++-- 10 files changed, 1258 insertions(+), 99 deletions(-) diff --git a/docs/gstreamer-app/docs.md b/docs/gstreamer-app/docs.md index 1b4c64791..d95949c02 100644 --- a/docs/gstreamer-app/docs.md +++ b/docs/gstreamer-app/docs.md @@ -96,13 +96,15 @@ PLAYING state. `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. +appsink to preroll in the PAUSED state. This function is typically used when dealing with a pipeline in the PAUSED state. Calling this function after doing a seek will give the sample right after the seek position. +Calling this function will clear the internal reference to the preroll +buffer. + Note that the preroll sample will also be returned as the first sample when calling `AppSink::pull_sample`. @@ -186,13 +188,15 @@ Instruct `self` to wait for all buffers to be consumed when an EOS is received. 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. +appsink to preroll in the PAUSED state. This function is typically used when dealing with a pipeline in the PAUSED state. Calling this function after doing a seek will give the sample right after the seek position. +Calling this function will clear the internal reference to the preroll +buffer. + Note that the preroll sample will also be returned as the first sample when calling `AppSink::pull_sample`. @@ -264,13 +268,15 @@ Note that this signal is only emitted when the "emit-signals" property is set to `true`, which it is not by default for performance reasons. Get the last preroll sample in `appsink`. 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. +appsink to preroll in the PAUSED state. This function is typically used when dealing with a pipeline in the PAUSED state. Calling this function after doing a seek will give the sample right after the seek position. +Calling this function will clear the internal reference to the preroll +buffer. + Note that the preroll sample will also be returned as the first sample when calling `AppSink::pull_sample` or the "pull-sample" action signal. @@ -304,13 +310,15 @@ If an EOS event was received before any buffers, this function returns a `gst::Sample` or NULL when the appsink is stopped or EOS. Get the last preroll sample in `appsink`. 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. +appsink to preroll in the PAUSED state. This function is typically used when dealing with a pipeline in the PAUSED state. Calling this function after doing a seek will give the sample right after the seek position. +Calling this function will clear the internal reference to the preroll +buffer. + Note that the preroll sample will also be returned as the first sample when calling `AppSink::pull_sample` or the "pull-sample" action signal. @@ -465,7 +473,7 @@ Retrieve the min and max latencies in `min` and `max` respectively. ## `min` the min latency ## `max` -the min latency +the max latency Get the maximum amount of bytes that can be queued in `self`. @@ -500,6 +508,24 @@ 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. + +Adds a buffer list to the queue of buffers and buffer lists that the +appsrc element will push to its source pad. This function takes ownership +of `buffer_list`. + +When the block property is TRUE, this function can block until free +space becomes available in the queue. + +Feature: `v1_14` + +## `buffer_list` +a `gst::BufferList` to push + +# Returns + +`gst::FlowReturn::Ok` when the buffer list 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 @@ -558,7 +584,7 @@ default latency calculations for pseudo-live sources will be used. ## `min` the min latency ## `max` -the min latency +the max 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 @@ -603,6 +629,19 @@ When the block property is TRUE, this function can block until free space becomes available in the queue. ## `buffer` a buffer to push + +Adds a buffer list to the queue of buffers and buffer lists that the +appsrc element will push to its source pad. This function does not take +ownership of the buffer list so the buffer list needs to be unreffed +after calling this function. + +When the block property is TRUE, this function can block until free space +becomes available in the queue. + +Feature: `v1_14` + +## `buffer_list` +a buffer list to push Extract a buffer from the provided sample and adds the extracted buffer to the queue of buffers that the appsrc element will diff --git a/docs/gstreamer-audio/docs.md b/docs/gstreamer-audio/docs.md index 38f41615e..e08580192 100644 --- a/docs/gstreamer-audio/docs.md +++ b/docs/gstreamer-audio/docs.md @@ -266,6 +266,116 @@ Layout of the audio samples for the different channels. interleaved audio non-interleaved audio + +`AudioStreamAlign` provides a helper object that helps tracking audio +stream alignment and discontinuities, and detects discontinuities if +possible. + +See `AudioStreamAlign::new` for a description of its parameters and +`AudioStreamAlign::process` for the details of the processing. + +Feature: `v1_14` + +Allocate a new `AudioStreamAlign` with the given configuration. All +processing happens according to sample rate `rate`, until +`gst_audio_discont_wait_set_rate` is called with a new `rate`. +A negative rate can be used for reverse playback. + +`alignment_threshold` gives the tolerance in nanoseconds after which a +timestamp difference is considered a discontinuity. Once detected, +`discont_wait` nanoseconds have to pass without going below the threshold +again until the output buffer is marked as a discontinuity. These can later +be re-configured with `AudioStreamAlign::set_alignment_threshold` and +`AudioStreamAlign::set_discont_wait`. + +Feature: `v1_14` + +## `rate` +a sample rate +## `alignment_threshold` +a alignment threshold in nanoseconds +## `discont_wait` +discont wait in nanoseconds + +# Returns + +a new `AudioStreamAlign`. free with `AudioStreamAlign::free`. + +Copy a GstAudioStreamAlign structure. + +Feature: `v1_14` + + +# Returns + +a new `AudioStreamAlign`. free with gst_audio_stream_align_free. + +Free a GstAudioStreamAlign structure previously allocated with `AudioStreamAlign::new` +or `AudioStreamAlign::copy`. + +Feature: `v1_14` + + +Returns the number of samples that were processed since the last +discontinuity was detected. + +Feature: `v1_14` + + +# Returns + +The number of samples processed since the last discontinuity. + +Timestamp that was passed when a discontinuity was detected, i.e. the first +timestamp after the discontinuity. + +Feature: `v1_14` + + +# Returns + +The last timestamp at when a discontinuity was detected + +Marks the next buffer as discontinuous and resets timestamp tracking. + +Feature: `v1_14` + + +Processes data with `timestamp` and `n_samples`, and returns the output +timestamp, duration and sample position together with a boolean to signal +whether a discontinuity was detected or not. All non-discontinuous data +will have perfect timestamps and durations. + +A discontinuity is detected once the difference between the actual +timestamp and the timestamp calculated from the sample count since the last +discontinuity differs by more than the alignment threshold for a duration +longer than discont wait. + +Note: In reverse playback, every buffer is considered discontinuous in the +context of buffer flags because the last sample of the previous buffer is +discontinuous with the first sample of the current one. However for this +function they are only considered discontinuous in reverse playback if the +first sample of the previous buffer is discontinuous with the last sample +of the current one. + +Feature: `v1_14` + +## `discont` +if this data is considered to be discontinuous +## `timestamp` +a `gst::ClockTime` of the start of the data +## `n_samples` +number of samples to process +## `out_timestamp` +output timestamp of the data +## `out_duration` +output duration of the data +## `out_sample_position` +output sample position of the start of the data + +# Returns + +`true` if a discontinuity was detected, `false` otherwise. This interface is implemented by elements that provide a stream volume. Examples for such elements are `volume` and `playbin`. diff --git a/docs/gstreamer-base/docs.md b/docs/gstreamer-base/docs.md index 15753ca05..103c0e3f1 100644 --- a/docs/gstreamer-base/docs.md +++ b/docs/gstreamer-base/docs.md @@ -1281,6 +1281,28 @@ Wait until the start operation completes. # Returns a `gst::FlowReturn`. + +Subclasses can call this from their create virtual method implementation +to submit a buffer list to be pushed out later. This is useful in +cases where the create function wants to produce multiple buffers to be +pushed out in one go in form of a `gst::BufferList`, which can reduce overhead +drastically, especially for packetised inputs (for data streams where +the packetisation/chunking is not important it is usually more efficient +to return larger buffers instead). + +Subclasses that use this function from their create function must return +`gst::FlowReturn::Ok` and no buffer from their create virtual method implementation. +If a buffer is returned after a buffer list has also been submitted via this +function the behaviour is undefined. + +Subclasses must only call this function once per create function call and +subclasses must only call this function when the source operates in push +mode. + +Feature: `v1_14` + +## `buffer_list` +a `gst::BufferList` If the `BaseSrcClass.create`() method performs its own synchronisation against the clock it must unblock when going from PLAYING to the PAUSED state @@ -1583,12 +1605,26 @@ the `gst::Pad` that is being added Removes all pads from a `FlowCombiner` and resets it to its initial state. Frees a `FlowCombiner` struct and all its internal data. + +Increments the reference count on the `FlowCombiner`. + +Feature: `v1_12_1` + + +# Returns + +the `FlowCombiner`. Removes a `gst::Pad` from the `FlowCombiner`. ## `pad` the `gst::Pad` to remove Reset flow combiner and all pads to their initial state without removing pads. + +Decrements the reference count on the `FlowCombiner`. + +Feature: `v1_12_1` + Computes the combined flow return for the pads in it. diff --git a/docs/gstreamer-net/docs.md b/docs/gstreamer-net/docs.md index 14060ce7c..8b87249a1 100644 --- a/docs/gstreamer-net/docs.md +++ b/docs/gstreamer-net/docs.md @@ -134,3 +134,7 @@ check this with `gst::ClockExt::wait_for_sync`, the GstClock::synced signal and Name of the clock ## `domain` PTP domain + +# Returns + +A new `gst::Clock` diff --git a/docs/gstreamer-pbutils/docs.md b/docs/gstreamer-pbutils/docs.md index b573f47af..e3fb09336 100644 --- a/docs/gstreamer-pbutils/docs.md +++ b/docs/gstreamer-pbutils/docs.md @@ -5,13 +5,13 @@ information as possible from one or many URIs. It provides two APIs, allowing usage in blocking or non-blocking mode. -The blocking mode just requires calling `DiscovererExt::discover_uri` +The blocking mode just requires calling `Discoverer::discover_uri` with the URI one wishes to discover. The non-blocking mode requires a running `glib::MainLoop` iterating a `glib::MainContext`, where one connects to the various signals, appends the -URIs to be processed (through `DiscovererExt::discover_uri_async`) and then -asks for the discovery to begin (through `DiscovererExt::start`). +URIs to be processed (through `Discoverer::discover_uri_async`) and then +asks for the discovery to begin (through `Discoverer::start`). By default this will use the GLib default main context unless you have set a custom context using `glib::MainContext::push_thread_default`. @@ -19,13 +19,7 @@ All the information is returned in a `DiscovererInfo` structure. # Implements -[`DiscovererExt`](trait.DiscovererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) - -Trait containing all `Discoverer` methods. - -# Implementors - -[`Discoverer`](struct.Discoverer.html) +[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `Discoverer` with the provided timeout. ## `timeout` @@ -38,7 +32,7 @@ The new `Discoverer`. If an error occurred when creating the discoverer, `err` will be set accordingly and `None` will be returned. If `err` is set, the caller must free it when no longer needed using `glib::Error::free`. - + Synchronously discovers the given `uri`. A copy of `uri` will be made internally, so the caller can safely `g_free` @@ -50,9 +44,9 @@ The URI to run on. the result of the scanning. Can be `None` if an error occurred. - + Appends the given `uri` to the list of URIs to discoverer. The actual -discovery of the `uri` will only take place if `DiscovererExt::start` has +discovery of the `uri` will only take place if `Discoverer::start` has been called. A copy of `uri` will be made internally, so the caller can safely `g_free` @@ -64,11 +58,11 @@ the URI to add. `true` if the `uri` was successfully appended to the list of pending uris, else `false` - + Allow asynchronous discovering of URIs to take place. A `glib::MainLoop` must be available for `Discoverer` to properly work in asynchronous mode. - + Stop the discovery of any pending URIs and clears the list of pending URIS (if any). @@ -80,9 +74,10 @@ depending on the circumstances of the error. ## `info` the results `DiscovererInfo` ## `error` -`glib::Error`, which will be non-NULL if an error - occurred during discovery. You must not - free this `glib::Error`, it will be freed by +`glib::Error`, which will be non-NULL + if an error occurred during + discovery. You must not free + this `glib::Error`, it will be freed by the discoverer. Will be emitted in async mode when all pending URIs have been processed. @@ -121,6 +116,16 @@ set on the result flags. # Returns the average or nominal bitrate of the stream in bits/second. + + +Feature: `v1_14` + + +# Returns + +the channel-mask of the stream, refer to +`gst_audio_channel_positions_from_mask` for more +information. # Returns @@ -206,6 +211,14 @@ matching `DiscovererStreamInfo`. The caller should free it with # Returns the duration of the URI in `gst::ClockTime` (nanoseconds). + + +Feature: `v1_14` + + +# Returns + +whether the URI is live. # Deprecated diff --git a/docs/gstreamer-player/docs.md b/docs/gstreamer-player/docs.md index 678116707..a3d723109 100644 --- a/docs/gstreamer-player/docs.md +++ b/docs/gstreamer-player/docs.md @@ -4,7 +4,7 @@ # Implements -[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `Player` instance that uses `signal_dispatcher` to dispatch signals to some event loop system, or emits signals directly if NULL is @@ -57,6 +57,20 @@ Since 1.10 a `Player` configuration ## `interval` interval in ms + +Enable or disable accurate seeking. When enabled, elements will try harder +to seek as accurately as possible to the requested seek position. Generally +it will be slower especially for formats that don't have any indexes or +timestamp markers in the stream. + +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. +## `config` +a `Player` configuration +## `accurate` +accurate seek or not Set the user agent to pass to the server if `player` needs to connect to a server during playback. This is typically used when playing HTTP @@ -103,18 +117,6 @@ a `None` terminated array of `PlayerVisualization` to free a `None` terminated array containing all available visualizations. Use `Player::visualizations_free` after usage. - -Enable or disable accurate seeking. When enabled, elements will try harder -to seek as accurately as possible to the requested seek position. Generally -it will be slower especially for formats that don't have any indexes or -timestamp markers in the stream. - -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. -## `accurate` -accurate seek or not Retrieve the current value of audio-video-offset property @@ -349,7 +351,9 @@ Enable or disable the current subtitle track. ## `enabled` TRUE or FALSE -Sets the external subtitle URI. +Sets the external subtitle URI. This should be combined with a call to +gst_player_set_subtitle_track_enabled(`self`, TRUE) so the subtitles are actually +rendered. ## `uri` subtitle URI diff --git a/docs/gstreamer-rtsp-server/docs.md b/docs/gstreamer-rtsp-server/docs.md index c43da5ba1..adee7f8c5 100644 --- a/docs/gstreamer-rtsp-server/docs.md +++ b/docs/gstreamer-rtsp-server/docs.md @@ -571,6 +571,21 @@ a `RTSPContext` a `RTSPContext` ## `ctx` +a `RTSPContext` + +Information passed around containing the context of a request. + +Pops `self` off the context stack (verifying that `self` +is on the top of the stack). + +Pushes `self` onto the context stack. The current +context can then be received using `RTSPContext::get_current`. + +Get the current `RTSPContext`. This object is retrieved from the +current thread that is handling the request for a client. + +# Returns + a `RTSPContext` A class that contains the GStreamer element along with a list of @@ -609,6 +624,15 @@ the list of dynamic elements. Find all depayloader elements, they should be named depay\%d in the element of `self`, and create `GstRTSPStreams` for them. + +Add a receiver and sender parts to the pipeline based on the transport from +SETUP. +## `transports` +a list of `gst_rtsp::RTSPTransport` + +# Returns + +`true` if the media pipeline has been sucessfully updated. Create a new stream in `self` that provides RTP data on `pad`. `pad` should be a pad of an element inside `self`->element. @@ -830,6 +854,17 @@ a `gst_rtsp::RTSPTimeRange` # Returns +`true` on success. + +Seek the pipeline of `self` to `range`. `self` must be prepared with +`RTSPMediaExt::prepare`. +## `range` +a `gst_rtsp::RTSPTimeRange` +## `flags` +The minimal set of `gst::SeekFlags` to use + +# Returns + `true` on success. configure `pool` to be used as the address pool of `self`. @@ -992,6 +1027,13 @@ will be created and the role will be added to it. a role ## `fieldname` the first field name + +A convenience wrapper around `RTSPPermissions::add_role_from_structure`. +If `self` had no permissions, new permissions will be created and the +role will be added to it. + +Feature: `v1_14` + Construct the media object and create its streams. Implementations should create the needed gstreamer elements and add them to the result @@ -1107,7 +1149,7 @@ methods. # Returns -The supported transport modes. +The transport mode. Get if media created from this factory will have an EOS event sent to the pipeline before shutdown. @@ -1742,6 +1784,13 @@ the stream index a `RTSPStreamTransport` that is valid until the session of `self` is unreffed. + +Get a list of all available `RTSPStreamTransport` in this session. + +# Returns + +a +list of `RTSPStreamTransport`, g_ptr_array_unref () after usage. Check if the path of `self` matches `path`. It `path` matches, the amount of matched characters is returned in `matched`. @@ -1918,20 +1967,25 @@ a `RTSPStreamTransport` `true` if `trans` was added Allocates RTP and RTCP ports. - -# Deprecated - -This function shouldn't have been made public ## `family` protocol family ## `transport` transport method -## `use_client_setttings` +## `use_client_settings` Whether to use client settings or not # Returns `true` if the RTP and RTCP sockets have been succeccully allocated. + +Add a receiver and sender part to the pipeline based on the transport from +SETUP. +## `transport` +a `gst_rtsp::RTSPTransport` + +# Returns + +`true` if the stream has been sucessfully updated. Get the `RTSPAddressPool` used as the address pool of `self`. @@ -2037,6 +2091,15 @@ Get the amount of time to store retransmission data. # Returns the amount of time to store retransmission data. + +Get the multicast RTCP socket from `self` for a `family`. +## `family` +the socket family + +# Returns + +the multicast RTCP socket or `None` if no +socket could be allocated for `family`. Unref after usage Get the RTCP socket from `self` for a `family`. @@ -2048,6 +2111,15 @@ the socket family the RTCP socket or `None` if no socket could be allocated for `family`. Unref after usage + +Get the multicast RTP socket from `self` for a `family`. +## `family` +the socket family + +# Returns + +the multicast RTP socket or `None` if no +socket could be allocated for `family`. Unref after usage Get the RTP socket from `self` for a `family`. @@ -2130,6 +2202,26 @@ See `RTSPStreamExt::set_client_side` # Returns TRUE if this `RTSPStream` is client-side. + +Checks whether the stream is complete, contains the receiver and the sender +parts. As the stream contains sink(s) element(s), it's possible to perform +seek operations on it. + +# Returns + +`true` if the stream contains at least one sink element. + +Checks whether the stream is a receiver. + +# Returns + +`true` if the stream is a receiver and `false` otherwise. + +Checks whether the stream is a sender. + +# Returns + +`true` if the stream is a sender and `false` otherwise. Check if `transport` can be handled by stream ## `transport` @@ -2241,6 +2333,12 @@ a TTL the `RTSPAddress` of `self` or `None` when the address could be reserved. `RTSPAddress::free` after usage. + +Checks whether the individual `self` is seekable. + +# Returns + +`true` if `self` is seekable, else `false`. configure `pool` to be used as the address pool of `self`. ## `pool` @@ -2537,3 +2635,89 @@ Different thread types a thread to handle the client communication a thread to handle media + +An opaque object used for checking authorisations. +It is generated after successful authentication. + +Create a new Authorization token with the given fieldnames and values. +Arguments are given similar to `gst::Structure::new`. +## `firstfield` +the first fieldname + +# Returns + +a new authorization token. + +Create a new empty Authorization token. + +# Returns + +a new empty authorization token. + +Create a new Authorization token with the given fieldnames and values. +Arguments are given similar to `gst::Structure::new_valist`. +## `firstfield` +the first fieldname +## `var_args` +additional arguments + +# Returns + +a new authorization token. + +Get the string value of `field` in `self`. +## `field` +a field name + +# Returns + +the string value of `field` in +`self` or `None` when `field` is not defined in `self`. The string +becomes invalid when you free `self`. + +Access the structure of the token. + +# Returns + +The structure of the token. The structure is still +owned by the token, which means that you should not free it and that the +pointer becomes invalid when you free the token. + +MT safe. + +Check if `self` has a boolean `field` and if it is set to `true`. +## `field` +a field name + +# Returns + +`true` if `self` has a boolean field named `field` set to `true`. + +Sets a boolean value on `self`. + +Feature: `v1_14` + +## `field` +field to set +## `bool_value` +boolean value to set + +Sets a string value on `self`. + +Feature: `v1_14` + +## `field` +field to set +## `string_value` +string value to set + +Get a writable version of the structure. + +# Returns + +The structure of the token. The structure is still +owned by the token, which means that you should not free it and that the +pointer becomes invalid when you free the token. This function checks if +`self` is writable and will never return `None`. + +MT safe. diff --git a/docs/gstreamer-rtsp/docs.md b/docs/gstreamer-rtsp/docs.md index 4f18e3cc7..a6b222bfc 100644 --- a/docs/gstreamer-rtsp/docs.md +++ b/docs/gstreamer-rtsp/docs.md @@ -63,7 +63,7 @@ function not implemented a system error occured, errno contains more details -a persing error occured +a parsing error occured windows networking could not start diff --git a/docs/gstreamer-video/docs.md b/docs/gstreamer-video/docs.md index 831c02421..c9d9d9c78 100644 --- a/docs/gstreamer-video/docs.md +++ b/docs/gstreamer-video/docs.md @@ -15,7 +15,7 @@ ITU-R BT.601 color matrix SMPTE 240M color matrix -ITU-R BT.2020 color matrix. Since: 1.6. +ITU-R BT.2020 color matrix. Since: 1.6 The color primaries define the how to transform linear RGB values to and from the CIE XYZ colorspace. @@ -34,7 +34,7 @@ SMPTE240M primaries Generic film -BT2020 primaries. Since: 1.6. +BT2020 primaries. Since: 1.6 Adobe RGB primaries. Since: 1.8 @@ -97,6 +97,15 @@ bottom field is first Feature: `v1_12` + +Provides useful functions and a base class for video filters. + +The videofilter will by default enable QoS on the parent GstBaseTransform +to implement frame dropping. + +# Implements + +[`gst_base::BaseTransformExt`](../gst_base/trait.BaseTransformExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Enum value describing the most common video formats. @@ -258,6 +267,12 @@ planar 4:2:2 YUV, 12 bits per channel (Since: 1.12) planar 4:4:4 YUV, 12 bits per channel (Since: 1.12) planar 4:4:4 YUV, 12 bits per channel (Since: 1.12) + +10-bit grayscale, packed into 32bit words (2 bits padding) (Since: 1.14) + +10-bit variant of `VideoFormat::Nv12`, packed into 32bit words (MSB 2 bits padding) (Since: 1.14) + +10-bit variant of `VideoFormat::Nv16`, packed into 32bit words (MSB 2 bits padding) (Since: 1.14) Information for a video format. @@ -833,6 +848,36 @@ Trait containing all `VideoOverlay` methods. # Implementors [`VideoOverlay`](struct.VideoOverlay.html) + +This helper shall be used by classes implementing the `VideoOverlay` +interface that want the render rectangle to be controllable using +properties. This helper will install "render-rectangle" property into the +class. + +Since 1.14 +## `oclass` +The class on which the properties will be installed +## `last_prop_id` +The first free property ID to use + +This helper shall be used by classes implementing the `VideoOverlay` +interface that want the render rectangle to be controllable using +properties. This helper will parse and set the render rectangle calling +`VideoOverlay::set_render_rectangle`. +## `object` +The instance on which the property is set +## `last_prop_id` +The highest property ID. +## `property_id` +The property ID +## `value` +The `gobject::Value` to be set + +# Returns + +`true` if the `property_id` matches the GstVideoOverlay property + +Since 1.14 Tell an overlay that it has been exposed. This will redraw the current frame in the drawable even if the pipeline is PAUSED. @@ -929,6 +974,6 @@ Logarithmic transfer characteristic Gamma 2.2 curve with a linear segment in the lower range. Used for BT.2020 with 12 bits per - component. Since: 1.6. + component. Since: 1.6 Gamma 2.19921875. Since: 1.8 diff --git a/docs/gstreamer/docs.md b/docs/gstreamer/docs.md index 879e0bfc1..258407e06 100644 --- a/docs/gstreamer/docs.md +++ b/docs/gstreamer/docs.md @@ -167,7 +167,8 @@ the `glib::Type` of an interface # Returns -A `Element` inside the bin implementing the interface +A `Element` inside the bin +implementing the interface Gets the element with the given name from a bin. This function recurses into child bins. @@ -587,6 +588,23 @@ a `Structure` holding cryptographic a pointer to the added `ProtectionMeta` if successful; `None` if unsuccessful. + +Add a `ReferenceTimestampMeta` to `self` that holds a `timestamp` and +optionally `duration` based on a specific timestamp `reference`. See the +documentation of `ReferenceTimestampMeta` for details. + +Feature: `v1_14` + +## `reference` +identifier for the timestamp reference. +## `timestamp` +timestamp +## `duration` +duration, or `GST_CLOCK_TIME_NONE` + +# Returns + +The `ReferenceTimestampMeta` that was added to the buffer Append all the memory from `buf2` to `self`. The result buffer will contain a concatenation of the memory of `self` and `buf2`. @@ -692,7 +710,7 @@ the offset to extract the size to extract ## `dest` A pointer where - the destination array will be written. + the destination array will be written. Might be `None` if the size is 0. ## `dest_size` A location where the size of `dest` can be written @@ -801,6 +819,32 @@ the `glib::Type` of an API the metadata for `api` on `self`. + + +Feature: `v1_14` + +## `api_type` +the `glib::Type` of an API + +# Returns + +number of metas of type `api_type` on `self`. + +Find the first `ReferenceTimestampMeta` on `self` that conforms to +`reference`. Conformance is tested by checking if the meta's reference is a +subset of `reference`. + +Buffers can contain multiple `ReferenceTimestampMeta` metadata items. + +Feature: `v1_14` + +## `reference` +a reference `Caps` + +# Returns + +the `ReferenceTimestampMeta` or `None` when there +is no such metadata on `self`. Get the total size of the memory blocks in `self`. @@ -1147,6 +1191,16 @@ an initial reserved size the new `BufferList`. `gst_buffer_list_unref` after usage. + +Calculates the size of the data contained in buffer list by adding the +size of all buffers. + +Feature: `v1_14` + + +# Returns + +the size of the data contained in buffer list in bytes. Create a copy of the given buffer list. This will make a newly allocated copy of the buffer that the source buffer list contains. @@ -1171,6 +1225,9 @@ user data passed to `func` `self` is empty. Get the buffer at `idx`. + +You must make sure that `idx` does not exceed the number of +buffers available. ## `idx` the index @@ -1179,6 +1236,22 @@ the index the buffer at `idx` in `group` or `None` when there is no buffer. The buffer remains valid as long as `self` is valid and buffer is not removed from the list. + +Gets the buffer at `idx`, ensuring it is a writable buffer. + +You must make sure that `idx` does not exceed the number of +buffers available. + +Feature: `v1_14` + +## `idx` +the index + +# Returns + +the buffer at `idx` in `group`. + The returned buffer remains valid as long as `self` is valid and + the buffer is not removed from the list. Insert `buffer` at `idx` in `self`. Other buffers are moved to make room for this new buffer. @@ -1201,6 +1274,282 @@ are moved to close the gap. the index ## `length` the amount to remove + +A `BufferPool` is an object that can be used to pre-allocate and recycle +buffers of the same size and with the same properties. + +A `BufferPool` is created with `BufferPool::new`. + +Once a pool is created, it needs to be configured. A call to +`BufferPool::get_config` returns the current configuration structure from +the pool. With `BufferPool::config_set_params` and +`BufferPool::config_set_allocator` the bufferpool parameters and +allocator can be configured. Other properties can be configured in the pool +depending on the pool implementation. + +A bufferpool can have extra options that can be enabled with +`BufferPool::config_add_option`. The available options can be retrieved +with `BufferPoolExt::get_options`. Some options allow for additional +configuration properties to be set. + +After the configuration structure has been configured, +`BufferPool::set_config` updates the configuration in the pool. This can +fail when the configuration structure is not accepted. + +After the a pool has been configured, it can be activated with +`BufferPoolExt::set_active`. This will preallocate the configured resources +in the pool. + +When the pool is active, `BufferPool::acquire_buffer` can be used to +retrieve a buffer from the pool. + +Buffers allocated from a bufferpool will automatically be returned to the +pool with `BufferPool::release_buffer` when their refcount drops to 0. + +The bufferpool can be deactivated again with `BufferPoolExt::set_active`. +All further `BufferPool::acquire_buffer` calls will return an error. When +all buffers are returned to the pool they will be freed. + +Use `GstObjectExt::unref` to release the reference to a bufferpool. If the +refcount of the pool reaches 0, the pool will be freed. + +# Implements + +[`BufferPoolExt`](trait.BufferPoolExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Trait containing all `BufferPool` methods. + +# Implementors + +[`BufferPool`](struct.BufferPool.html) + +Creates a new `BufferPool` instance. + +# Returns + +a new `BufferPool` instance + +Enabled the option in `config`. This will instruct the `bufferpool` to enable +the specified option on the buffers that it allocates. + +The supported options by `pool` can be retrieved with `BufferPoolExt::get_options`. +## `config` +a `BufferPool` configuration +## `option` +an option to add + +Get the `allocator` and `params` from `config`. +## `config` +a `BufferPool` configuration +## `allocator` +a `Allocator`, or `None` +## `params` +`AllocationParams`, or `None` + +# Returns + +`true`, if the values are set. + +Parse an available `config` and get the option at `index` of the options API +array. +## `config` +a `BufferPool` configuration +## `index` +position in the option array to read + +# Returns + +a `gchar` of the option at `index`. + +Get the configuration values from `config`. +## `config` +a `BufferPool` configuration +## `caps` +the caps of buffers +## `size` +the size of each buffer, not including prefix and padding +## `min_buffers` +the minimum amount of buffers to allocate. +## `max_buffers` +the maximum amount of buffers to allocate or 0 for unlimited. + +# Returns + +`true` if all parameters could be fetched. + +Check if `config` contains `option`. +## `config` +a `BufferPool` configuration +## `option` +an option + +# Returns + +`true` if the options array contains `option`. + +Retrieve the number of values currently stored in the options array of the +`config` structure. +## `config` +a `BufferPool` configuration + +# Returns + +the options array size as a `guint`. + +Set the `allocator` and `params` on `config`. + +One of `allocator` and `params` can be `None`, but not both. When `allocator` +is `None`, the default allocator of the pool will use the values in `param` +to perform its allocation. When `param` is `None`, the pool will use the +provided `allocator` with its default `AllocationParams`. + +A call to `BufferPool::set_config` can update the allocator and params +with the values that it is able to do. Some pools are, for example, not able +to operate with different allocators or cannot allocate with the values +specified in `params`. Use `BufferPool::get_config` to get the currently +used values. +## `config` +a `BufferPool` configuration +## `allocator` +a `Allocator` +## `params` +`AllocationParams` + +Configure `config` with the given parameters. +## `config` +a `BufferPool` configuration +## `caps` +caps for the buffers +## `size` +the size of each buffer, not including prefix and padding +## `min_buffers` +the minimum amount of buffers to allocate. +## `max_buffers` +the maximum amount of buffers to allocate or 0 for unlimited. + +Validate that changes made to `config` are still valid in the context of the +expected parameters. This function is a helper that can be used to validate +changes made by a pool to a config when `BufferPool::set_config` +returns `false`. This expects that `caps` haven't changed and that +`min_buffers` aren't lower then what we initially expected. +This does not check if options or allocator parameters are still valid, +won't check if size have changed, since changing the size is valid to adapt +padding. +## `config` +a `BufferPool` configuration +## `caps` +the excepted caps of buffers +## `size` +the expected size of each buffer, not including prefix and padding +## `min_buffers` +the expected minimum amount of buffers to allocate. +## `max_buffers` +the expect maximum amount of buffers to allocate or 0 for unlimited. + +# Returns + +`true`, if the parameters are valid in this context. + +Acquire a buffer from `self`. `buffer` should point to a memory location that +can hold a pointer to the new buffer. + +`params` can be `None` or contain optional parameters to influence the +allocation. +## `buffer` +a location for a `Buffer` +## `params` +parameters. + +# Returns + +a `FlowReturn` such as `FlowReturn::Flushing` when the pool is +inactive. + +Get a copy of the current configuration of the pool. This configuration +can either be modified and used for the `BufferPool::set_config` call +or it must be freed after usage. + +# Returns + +a copy of the current configuration of `self`. use +`Structure::free` after usage or `BufferPool::set_config`. + +Get a `None` terminated array of string with supported bufferpool options for +`self`. An option would typically be enabled with +`BufferPool::config_add_option`. + +# Returns + +a `None` terminated array + of strings. + +Check if the bufferpool supports `option`. +## `option` +an option + +# Returns + +`true` if the buffer pool contains `option`. + +Check if `self` is active. A pool can be activated with the +`BufferPoolExt::set_active` call. + +# Returns + +`true` when the pool is active. + +Release `buffer` to `self`. `buffer` should have previously been allocated from +`self` with `BufferPool::acquire_buffer`. + +This function is usually called automatically when the last ref on `buffer` +disappears. +## `buffer` +a `Buffer` + +Control the active state of `self`. When the pool is inactive, new calls to +`BufferPool::acquire_buffer` will return with `FlowReturn::Flushing`. + +Activating the bufferpool will preallocate all resources in the pool based on +the configuration of the pool. + +Deactivating will free the resources again when there are no outstanding +buffers. When there are outstanding buffers, they will be freed as soon as +they are all returned to the pool. +## `active` +the new active state + +# Returns + +`false` when the pool was not configured or when preallocation of the +buffers failed. + +Set the configuration of the pool. If the pool is already configured, and +the configuration haven't change, this function will return `true`. If the +pool is active, this method will return `false` and active configuration +will remain. Buffers allocated form this pool must be returned or else this +function will do nothing and return `false`. + +`config` is a `Structure` that contains the configuration parameters for +the pool. A default and mandatory set of parameters can be configured with +`BufferPool::config_set_params`, `BufferPool::config_set_allocator` +and `BufferPool::config_add_option`. + +If the parameters in `config` can not be set exactly, this function returns +`false` and will try to update as much state as possible. The new state can +then be retrieved and refined with `BufferPool::get_config`. + +This function takes ownership of `config`. +## `config` +a `Structure` + +# Returns + +`true` when the configuration could be set. + +Enable or disable the flushing state of a `self` without freeing or +allocating buffers. +## `flushing` +whether to start or stop flushing The different types of buffering methods. @@ -1312,6 +1661,11 @@ The bus watch will only work if a GLib main loop is being run. The watch can be removed using `Bus::remove_watch` or by returning `false` from `func`. If the watch was added to the default main context it is also possible to remove the watch using `glib::Source::remove`. + +The bus watch will take its own reference to the `self`, so it is safe to unref +`self` using `GstObjectExt::unref` after setting the bus watch. + +MT safe. ## `func` A function to call when a message is received. ## `user_data` @@ -1320,8 +1674,6 @@ user data passed to `func`. # Returns The event source id or 0 if `self` already got an event source. - -MT safe. Adds a bus watch to the default main context with the given `priority` (e.g. `G_PRIORITY_DEFAULT`). It is also possible to use a non-default main @@ -1342,6 +1694,9 @@ The watch can be removed using `Bus::remove_watch` or by returning `false` from `func`. If the watch was added to the default main context it is also possible to remove the watch using `glib::Source::remove`. +The bus watch will take its own reference to the `self`, so it is safe to unref +`self` using `GstObjectExt::unref` after setting the bus watch. + MT safe. ## `priority` The priority of the watch. @@ -1404,6 +1759,20 @@ comes from the thread of whatever object posted the message; the "message" signal is marshalled to the main thread via the main loop. MT safe. + +Gets the file descriptor from the bus which can be used to get notified about +messages being available with functions like `g_poll`, and allows integration +into other event loops based on file descriptors. +Whenever a message is available, the POLLIN / `glib::IOCondition::In` event is set. + +Warning: NEVER read or write anything to the returned fd but only use it +for getting notifications via `g_poll` or similar and then use the normal +GstBus API, e.g. `Bus::pop`. + +Feature: `v1_14` + +## `fd` +A GPollFD to fill Check if there are pending messages on the bus that should be handled. @@ -1806,8 +2175,8 @@ the index of the structure # Returns -a pointer to the `CapsFeatures` corresponding - to `index` +a pointer to the `CapsFeatures` + corresponding to `index` Gets the number of structures contained in `self`. @@ -2048,8 +2417,8 @@ Index of the structure to retrieve # Returns -a pointer to the `Structure` corresponding - to `index`. +a pointer to the `Structure` + corresponding to `index`. Subtracts the `subtrahend` from the `self`. > This function does not work reliably if optional properties for caps @@ -3322,7 +3691,8 @@ create a unique name. # Returns -a new `Element` configured to use this device +a new `Element` configured to use +this device Getter for the `Caps` that this device supports. @@ -3579,6 +3949,9 @@ Posts a message on the provider's `Bus` to inform applications that a new device has been added. This is for use by subclasses. + +`device`'s reference count will be incremented, and any floating reference +will be removed (see `Object::ref_sink`). ## `device` a `Device` that has been added @@ -3618,6 +3991,17 @@ are hidden by `self`. a list of hidden providers factory names or `None` when nothing is hidden by `self`. Free with g_strfreev. + +Get metadata with `key` in `self`. + +Feature: `v1_14` + +## `key` +the key to get + +# Returns + +the metadata for `key`. Make `self` hide the devices from the factory with `name`. @@ -3818,7 +4202,8 @@ Name of created element, can be `None`. # Returns -a new element or `None` if none could be created +a new element or `None` if none +could be created Create a new elementfactory capable of instantiating objects of the `type_` and add the factory to `plugin`. @@ -3952,6 +4337,8 @@ the pending state, the next state change is performed. This method is used internally and should normally not be called by plugins or applications. + +This function must be called with STATE_LOCK held. ## `ret` The previous state return value @@ -3964,6 +4351,63 @@ MT safe. Creates a pad for each pad template that is always available. This function is only useful during object initialization of subclasses of `Element`. + +Call `func` with `user_data` for each of `self`'s pads. `func` will be called +exactly once for each pad that exists at the time of this call, unless +one of the calls to `func` returns `false` in which case we will stop +iterating pads and return early. If new pads are added or pads are removed +while pads are being iterated, this will not be taken into account until +next time this function is used. + +Feature: `v1_14` + +## `func` +function to call for each pad +## `user_data` +user data passed to `func` + +# Returns + +`false` if `self` had no pads or if one of the calls to `func` + returned `false`. + +Call `func` with `user_data` for each of `self`'s sink pads. `func` will be +called exactly once for each sink pad that exists at the time of this call, +unless one of the calls to `func` returns `false` in which case we will stop +iterating pads and return early. If new sink pads are added or sink pads +are removed while the sink pads are being iterated, this will not be taken +into account until next time this function is used. + +Feature: `v1_14` + +## `func` +function to call for each sink pad +## `user_data` +user data passed to `func` + +# Returns + +`false` if `self` had no sink pads or if one of the calls to `func` + returned `false`. + +Call `func` with `user_data` for each of `self`'s source pads. `func` will be +called exactly once for each source pad that exists at the time of this call, +unless one of the calls to `func` returns `false` in which case we will stop +iterating pads and return early. If new source pads are added or source pads +are removed while the source pads are being iterated, this will not be taken +into account until next time this function is used. + +Feature: `v1_14` + +## `func` +function to call for each source pad +## `user_data` +user data passed to `func` + +# Returns + +`false` if `self` had no source pads or if one of the calls + to `func` returned `false`. Returns the base time of the element. The base time is the absolute time of the clock when this element was last put to @@ -3981,7 +4425,8 @@ bus for the application. # Returns -the element's `Bus`. unref after usage. +the element's `Bus`. unref after +usage. MT safe. @@ -4058,6 +4503,41 @@ Retrieves the factory that was used to create this element. the `ElementFactory` used for creating this element. no refcounting is needed. + +Get metadata with `key` in `klass`. + +Feature: `v1_14` + +## `key` +the key to get + +# Returns + +the metadata for `key`. + +Retrieves a padtemplate from `self` with the given name. + +Feature: `v1_14` + +## `name` +the name of the `PadTemplate` to get. + +# Returns + +the `PadTemplate` with the + given name, or `None` if none was found. No unreferencing is + necessary. + +Retrieves a list of the pad templates associated with `self`. The +list must not be modified by the calling code. + +Feature: `v1_14` + + +# Returns + +the `glib::List` of + pad templates. Retrieves a pad from the element by name (e.g. "src_\%d"). This version only retrieves request pads. The pad should be released with @@ -5327,7 +5807,9 @@ The select-streams event requests the specified `streams` to be activated. The list of `streams` corresponds to the "Stream ID" of each stream to be activated. Those ID can be obtained via the `Stream` objects present in `EventType::StreamStart`, `EventType::StreamCollection` or -`GST_MESSSAGE_STREAM_COLLECTION`. +`MessageType::StreamCollection`. + +Note: The list of `streams` can not be empty. Feature: `v1_10` @@ -5337,7 +5819,8 @@ activate # Returns -a new select-streams event. +a new select-streams event or `None` in case of +an error (like an empty streams list). Create a new sink-message event. The purpose of the sink-message event is to instruct a sink to post the message contained in the event synchronized @@ -5526,9 +6009,9 @@ Access the structure of the event. # Returns -The structure of the event. The structure is still -owned by the event, which means that you should not free it and -that the pointer becomes invalid when you free the event. +The structure of the event. The +structure is still owned by the event, which means that you should not free +it and that the pointer becomes invalid when you free the event. MT safe. @@ -6825,17 +7308,18 @@ Extracts the object managing the streaming thread from `self`. # Returns -a GValue containing the object that manages the streaming thread. -This object is usually of type GstTask but other types can be added in the -future. The object remains valid as long as `self` is valid. +a GValue containing the object that manages the +streaming thread. This object is usually of type GstTask but other types can +be added in the future. The object remains valid as long as `self` is +valid. Access the structure of the message. # Returns -The structure of the message. The structure is -still owned by the message, which means that you should not free it and -that the pointer becomes invalid when you free the message. +The structure of the message. The +structure is still owned by the message, which means that you should not +free it and that the pointer becomes invalid when you free the message. MT safe. @@ -7013,12 +7497,13 @@ Feature: `v1_10` location where to store a pointer to the object whose property got changed, or `None` ## `property_name` -return location for the name of the - property that got changed, or `None` +return location for + the name of the property that got changed, or `None` ## `property_value` -return location for the new value of - the property that got changed, or `None`. This will only be set if the - property notify watch was told to include the value when it was set up +return location for + the new value of the property that got changed, or `None`. This will + only be set if the property notify watch was told to include the value + when it was set up Extract the timestamps and live status from the QoS message. @@ -7371,6 +7856,21 @@ Index of the stream to retrieve # Returns A `Stream` + +Get a writable version of the structure. + +Feature: `v1_14` + + +# Returns + +The structure of the message. The structure +is still owned by the message, which means that you should not free +it and that the pointer becomes invalid when you free the message. +This function checks if `self` is writable and will never return +`None`. + +MT safe. `Object` provides a root for the object hierarchy tree filed in by the GStreamer library. It is currently a thin wrapper on top of @@ -7430,7 +7930,7 @@ Trait containing all `Object` methods. # Implementors -[`Bus`](struct.Bus.html), [`Clock`](struct.Clock.html), [`DeviceMonitor`](struct.DeviceMonitor.html), [`DeviceProvider`](struct.DeviceProvider.html), [`Device`](struct.Device.html), [`Element`](struct.Element.html), [`Object`](struct.Object.html), [`PadTemplate`](struct.PadTemplate.html), [`Pad`](struct.Pad.html), [`PluginFeature`](struct.PluginFeature.html), [`Plugin`](struct.Plugin.html), [`Registry`](struct.Registry.html), [`StreamCollection`](struct.StreamCollection.html), [`Stream`](struct.Stream.html) +[`BufferPool`](struct.BufferPool.html), [`Bus`](struct.Bus.html), [`Clock`](struct.Clock.html), [`DeviceMonitor`](struct.DeviceMonitor.html), [`DeviceProvider`](struct.DeviceProvider.html), [`Device`](struct.Device.html), [`Element`](struct.Element.html), [`Object`](struct.Object.html), [`PadTemplate`](struct.PadTemplate.html), [`Pad`](struct.Pad.html), [`PluginFeature`](struct.PluginFeature.html), [`Plugin`](struct.Plugin.html), [`Registry`](struct.Registry.html), [`StreamCollection`](struct.StreamCollection.html), [`Stream`](struct.Stream.html) Checks to see if there is any object named `name` in `list`. This function does not do any locking of any kind. You might want to protect the @@ -7476,6 +7976,9 @@ of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one. + +For more background on "floating references" please see the `gobject::Object` +documentation. ## `object` a `Object` to sink @@ -7497,7 +8000,8 @@ a new `Object` Attach the `ControlBinding` to the object. If there already was a `ControlBinding` for this property it will be replaced. -The `self` will take ownership of the `binding`. +The object's reference count will be incremented, and any floating +reference will be removed (see `Object::ref_sink`) ## `binding` the `ControlBinding` that should be used @@ -9164,6 +9668,39 @@ a `Caps` set for the template. # Returns +a new `PadTemplate`. + +Converts a `StaticPadTemplate` into a `PadTemplate` with a type. + +Feature: `v1_14` + +## `pad_template` +the static pad template +## `pad_type` +The `glib::Type` of the pad to create + +# Returns + +a new `PadTemplate`. + +Creates a new pad template with a name according to the given template +and with the given arguments. + +Feature: `v1_14` + +## `name_template` +the name template. +## `direction` +the `PadDirection` of the template. +## `presence` +the `PadPresence` of the pad. +## `caps` +a `Caps` set for the template. +## `pad_type` +The `glib::Type` of the pad to create + +# Returns + a new `PadTemplate`. Gets the capabilities of the pad template. @@ -9188,6 +9725,16 @@ The capabilities of the pad described by the pad template. The direction of the pad described by the pad template. The direction of the pad described by the pad template. + +The type of the pad described by the pad template. + +Feature: `v1_14` + + +The type of the pad described by the pad template. + +Feature: `v1_14` + The name template of the pad template. @@ -9206,8 +9753,8 @@ Free-function: gst_parse_context_free # Returns -a newly-allocated parse context. Free with - `ParseContext::free` when no longer needed. +a newly-allocated parse context. Free + with `ParseContext::free` when no longer needed. Copies the `self`. @@ -9492,7 +10039,8 @@ name of plugin to load # Returns -a reference to a loaded plugin, or `None` on error. +a reference to a loaded plugin, or +`None` on error. Loads the given plugin and refs it. Caller needs to unref after use. ## `filename` @@ -9724,7 +10272,8 @@ plugin = loaded_plugin; # Returns -a reference to a loaded plugin, or `None` on error. +a reference to a loaded plugin, or +`None` on error. Adds plugin specific data to cache. Passes the ownership of the structure to the `self`. @@ -9997,6 +10546,149 @@ A task was canceled. A task caused an error. An error message is also posted on the bus. + +The `Promise` object implements the container for values that may +be available later. i.e. a Future or a Promise in +https://en.wikipedia.org/wiki/Futures_and_promises`` +As with all Future/Promise-like functionality, there is the concept of the +producer of the value and the consumer of the value. + +A `Promise` is created with `Promise::new` by the consumer and passed +to the producer to avoid thread safety issues with the change callback. +A `Promise` can be replied to with a value (or an error) by the producer +with `Promise::reply`. `Promise::interrupt` is for the consumer to +indicate to the producer that the value is not needed anymore and producing +that value can stop. The `PromiseResult::Expired` state set by a call +to `Promise::expire` indicates to the consumer that a value will never +be produced and is intended to be called by a third party that implements +some notion of message handling such as `Bus`. +A callback can also be installed at `Promise` creation for +result changes with `Promise::new_with_change_func`. +The change callback can be used to chain `GstPromises`'s together as in the +following example. + +```C +const GstStructure *reply; +GstPromise *p; +if (gst_promise_wait (promise) != GST_PROMISE_RESULT_REPLIED) + return; // interrupted or expired value +reply = gst_promise_get_reply (promise); +if (error in reply) + return; // propagate error +p = gst_promise_new_with_change_func (another_promise_change_func, user_data, notify); +pass p to promise-using API +``` + +Each `Promise` starts out with a `PromiseResult` of +`PromiseResult::Pending` and only ever transitions once +into one of the other `PromiseResult`'s. + +In order to support multi-threaded code, `Promise::reply`, +`Promise::interrupt` and `Promise::expire` may all be from +different threads with some restrictions and the final result of the promise +is whichever call is made first. There are two restrictions on ordering: + +1. That `Promise::reply` and `Promise::interrupt` cannot be called +after `Promise::expire` +2. That `Promise::reply` and `Promise::interrupt` +cannot be called twice. + +The change function set with `Promise::new_with_change_func` is +called directly from either the `Promise::reply`, +`Promise::interrupt` or `Promise::expire` and can be called +from an arbitrary thread. `Promise` using APIs can restrict this to +a single thread or a subset of threads but that is entirely up to the API +that uses `Promise`. + +Feature: `v1_14` + + +Feature: `v1_14` + + +# Returns + +a new `Promise` + +`func` will be called exactly once when transitioning out of +`PromiseResult::Pending` into any of the other `PromiseResult` +states. + +Feature: `v1_14` + +## `func` +a `GstPromiseChangeFunc` to call +## `user_data` +argument to call `func` with +## `notify` +notification function that `user_data` is no longer needed + +# Returns + +a new `Promise` + +Expire a `self`. This will wake up any waiters with +`PromiseResult::Expired`. Called by a message loop when the parent +message is handled and/or destroyed (possibly unanswered). + +Feature: `v1_14` + + +Retrieve the reply set on `self`. `self` must be in +`PromiseResult::Replied` and the returned structure is owned by `self` + +Feature: `v1_14` + + +# Returns + +The reply set on `self` + +Interrupt waiting for a `self`. This will wake up any waiters with +`PromiseResult::Interrupted`. Called when the consumer does not want +the value produced anymore. + +Feature: `v1_14` + + +Set a reply on `self`. This will wake up any waiters with +`PromiseResult::Replied`. Called by the producer of the value to +indicate success (or failure). + +If `self` has already been interrupted by the consumer, then this reply +is not visible to the consumer. + +Feature: `v1_14` + +## `s` +a `Structure` with the the reply contents + +Wait for `self` to move out of the `PromiseResult::Pending` state. +If `self` is not in `PromiseResult::Pending` then it will return +immediately with the current result. + +Feature: `v1_14` + + +# Returns + +the result of the promise + +The result of a `Promise` + +Initial state. Waiting for transition to any + other state. + +Interrupted by the consumer as it doesn't + want the value anymore. + +A producer marked a reply + +The promise expired (the carrying object + lost all refs) and the promise will never be fulfilled. + +Feature: `v1_14` + @@ -10399,9 +11091,9 @@ Get the structure of a query. # Returns -the `Structure` of the query. The structure is - still owned by the query and will therefore be freed when the query - is unreffed. +the `Structure` of the query. The + structure is still owned by the query and will therefore be freed when the + query is unreffed. Check if `self` has scheduling mode set. @@ -10773,7 +11465,7 @@ index to modify ## `pool` the `BufferPool` ## `size` -the size +the buffer size ## `min_buffers` the min buffers ## `max_buffers` @@ -10953,7 +11645,9 @@ initialized. the `Registry`. Add the feature to the registry. The feature-added signal will be emitted. -This function sinks `feature`. + +`feature`'s reference count will be incremented, and any floating +reference will be removed (see `Object::ref_sink`) ## `feature` the feature to add @@ -10964,7 +11658,9 @@ the feature to add MT safe. Add the plugin to the registry. The plugin-added signal will be emitted. -This function will sink `plugin`. + +`plugin`'s reference count will be incremented, and any floating +reference will be removed (see `Object::ref_sink`) ## `plugin` the plugin to add @@ -11526,6 +12222,10 @@ returned, `running_time` is -1 or not in `self`. Convert `running_time` into a position in the segment so that `Segment::to_running_time` with that position returns `running_time`. + +# Deprecated + +Use `Segment::position_from_running_time` instead. ## `format` the format of the segment. ## `running_time` @@ -11535,8 +12235,6 @@ the running_time in the segment the position in the segment for `running_time`. This function returns -1 when `running_time` is -1 or when it is not inside `self`. - -Deprecated. Use `Segment::position_from_running_time` instead. Translate `position` to the total running time using the currently configured segment. Position is a value between `self` start and stop time. @@ -11708,6 +12406,18 @@ state change from PAUSED to READY. state change from READY to NULL. * Elements close devices * Elements reset any internal state. + +state change from NULL to NULL. (Since 1.14) + +state change from READY to READY, +This might happen when going to PAUSED asynchronously failed, in that case +elements should make sure they are in a proper, coherent READY state. (Since 1.14) + +state change from PAUSED to PAUSED. +This might happen when elements were in PLAYING state and 'lost state', +they should make sure to go back to real 'PAUSED' state (prerolling for example). (Since 1.14) + +state change from PLAYING to PLAYING. (Since 1.14) The possible return values from a state change function such as `ElementExt::set_state`. Only `StateChangeReturn::Failure` is a real failure. @@ -11732,9 +12442,10 @@ Converts a `StaticCaps` to a `Caps`. # Returns -a pointer to the `Caps`. Unref after usage. - Since the core holds an additional ref to the returned caps, - use `gst_caps_make_writable` on the returned caps to modify it. +a pointer to the `Caps`. Unref + after usage. Since the core holds an additional ref to the + returned caps, use `gst_caps_make_writable` on the returned caps + to modify it. Structure describing the `StaticPadTemplate`. @@ -12540,7 +13251,8 @@ the name of the field to get # Returns -the `gobject::Value` corresponding to the field with the given name. +the `gobject::Value` corresponding to the field with the given +name. Check if `self` contains a field named `fieldname`. ## `fieldname` @@ -12610,8 +13322,8 @@ the `glib::Quark` of the field to get # Returns -the `gobject::Value` corresponding to the field with the given name - identifier. +the `gobject::Value` corresponding to the field with the given +name identifier. Check if `self` contains a field named `field`. ## `field` @@ -13133,6 +13845,18 @@ location for the result # Returns +`true`, if a value was copied, `false` if the tag didn't exist in the + given list. + +Copies the contents for the given tag into the value, merging multiple values +into one if multiple values are associated with the tag. +## `tag` +tag to read out +## `value` +location for the result + +# Returns + `true`, if a value was copied, `false` if the tag didn't exist in the given list.