diff --git a/docs/gstreamer-app/docs.md b/docs/gstreamer-app/docs.md index ccf7aa2e6..b423b2055 100644 --- a/docs/gstreamer-app/docs.md +++ b/docs/gstreamer-app/docs.md @@ -54,7 +54,7 @@ Get the configured caps on `self`. # Returns -the `gst::Caps` accepted by the sink. `gst_caps_unref` after usage. +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. @@ -68,7 +68,7 @@ Check if appsink will emit the "new-preroll" and "new-sample" signals. # Returns -`true` if `self` is emiting the "new-preroll" and "new-sample" +`true` if `self` is emitting the "new-preroll" and "new-sample" signals. Get the maximum amount of buffers that can be queued in `self`. @@ -117,7 +117,7 @@ element is set to the READY/NULL state. # Returns a `gst::Sample` or NULL when the appsink is stopped or EOS. - Call `gst_sample_unref` after usage. + 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. @@ -134,7 +134,7 @@ If an EOS event was received before any buffers, this function returns # Returns a `gst::Sample` or NULL when the appsink is stopped or EOS. - Call `gst_sample_unref` after usage. + Call `gst::Sample::unref` after usage. Instruct `self` to enable or disable buffer list support. @@ -152,6 +152,9 @@ less expensive, but also less flexible. If callbacks are installed, no signals will be emitted for performance reasons. + +Before 1.16.3 it was not possible to change the callbacks in a thread-safe +way. ## `callbacks` the callbacks ## `user_data` @@ -215,7 +218,7 @@ the maximum amount of time to wait for the preroll sample # Returns a `gst::Sample` or NULL when the appsink is stopped or EOS or the timeout expires. - Call `gst_sample_unref` after usage. + 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. @@ -238,7 +241,7 @@ the maximum amount of time to wait for a sample # Returns a `gst::Sample` or NULL when the appsink is stopped or EOS or the timeout expires. -Call `gst_sample_unref` after usage. +Call `gst::Sample::unref` after usage. Signal that the end-of-stream has been reached. This signal is emitted from the streaming thread. @@ -414,7 +417,7 @@ mode when implementing various network protocols or hardware devices. The pull mode, in which the need-data signal triggers the next push-buffer call. This mode is typically used in the "random-access" stream-type. Use this -mode for file access or other randomly accessable sources. In this mode, a +mode for file access or other randomly accessible sources. In this mode, a buffer of exactly the amount of bytes given by the need-data signal should be pushed into appsrc. @@ -437,14 +440,14 @@ element is the last buffer of the stream. # Returns -`gst::FlowReturn::Ok` when the EOS was successfuly queued. +`gst::FlowReturn::Ok` when the EOS was successfully 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. +the `gst::Caps` produced by the source. `gst::Caps::unref` after usage. Get the number of currently queued bytes inside `self`. @@ -505,9 +508,9 @@ a `gst::Buffer` to push # Returns -`gst::FlowReturn::Ok` when the buffer was successfuly queued. +`gst::FlowReturn::Ok` when the buffer was successfully queued. `gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING. -`gst::FlowReturn::Eos` when EOS occured. +`gst::FlowReturn::Eos` when EOS occurred. 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 @@ -523,9 +526,9 @@ a `gst::BufferList` to push # Returns -`gst::FlowReturn::Ok` when the buffer list was successfuly queued. +`gst::FlowReturn::Ok` when the buffer list was successfully queued. `gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING. -`gst::FlowReturn::Eos` when EOS occured. +`gst::FlowReturn::Eos` when EOS occurred. 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 @@ -543,9 +546,9 @@ extracted # Returns -`gst::FlowReturn::Ok` when the buffer was successfuly queued. +`gst::FlowReturn::Ok` when the buffer was successfully queued. `gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING. -`gst::FlowReturn::Eos` when EOS occured. +`gst::FlowReturn::Eos` when EOS occurred. Set callbacks which will be executed when data is needed, enough data has been collected or when a seek should be performed. @@ -554,6 +557,9 @@ less expensive, but also less flexible. If callbacks are installed, no signals will be emitted for performance reasons. + +Before 1.16.3 it was not possible to change the callbacks in a thread-safe +way. ## `callbacks` the callbacks ## `user_data` diff --git a/docs/gstreamer-audio/docs.md b/docs/gstreamer-audio/docs.md index 99a5307de..729776fb6 100644 --- a/docs/gstreamer-audio/docs.md +++ b/docs/gstreamer-audio/docs.md @@ -180,7 +180,7 @@ This is expressed in caps by having a single channel and no channel mask. This is expressed in caps by having a channel mask with no bits set. As another special case it is allowed to have two channels without a channel mask. -This implicitely means that this is a stereo stream with a front left and front right +This implicitly means that this is a stereo stream with a front left and front right channel. used for position-less channels, e.g. @@ -340,7 +340,7 @@ Things that subclass need to take care of: # Implements -[`AudioDecoderExt`](trait.AudioDecoderExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`AudioDecoderExt`](trait.AudioDecoderExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`AudioDecoderExtManual`](prelude/trait.AudioDecoderExtManual.html) Trait containing all `AudioDecoder` methods. @@ -715,7 +715,7 @@ Things that subclass need to take care of: # Implements -[`AudioEncoderExt`](trait.AudioEncoderExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`AudioEncoderExt`](trait.AudioEncoderExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`AudioEncoderExtManual`](prelude/trait.AudioEncoderExtManual.html) Trait containing all `AudioEncoder` methods. @@ -1063,8 +1063,6 @@ encoded audio format 32-bit floating point samples, native endianness 64-bit floating point samples, native endianness - -Information for an audio format. Information describing audio properties. This information can be filled in from GstCaps with `AudioInfo::from_caps`. @@ -1376,7 +1374,7 @@ Feature: `v1_14` a new discont wait Sets `rate` as new sample rate for the following processing. If the sample -rate differs this implicitely marks the next data as discontinuous. +rate differs this implicitly marks the next data as discontinuous. Feature: `v1_14` diff --git a/docs/gstreamer-base/docs.md b/docs/gstreamer-base/docs.md index 4e0b612ab..c09374d12 100644 --- a/docs/gstreamer-base/docs.md +++ b/docs/gstreamer-base/docs.md @@ -84,8 +84,8 @@ at the last discontinuity, which can be retrieved with since then can be queried with `Adapter::distance_from_discont`. A last thing to note is that while `Adapter` is pretty optimized, -merging buffers still might be an operation that requires a `malloc` and -`memcpy` operation, and these operations are not the fastest. Because of +merging buffers still might be an operation that requires a `malloc()` and +`memcpy()` operation, and these operations are not the fastest. Because of this, some functions like `Adapter::available_fast` are provided to help speed up such cases should you want to. To avoid repeated memory allocations, `Adapter::copy` can be used to copy data into a (statically allocated) @@ -97,7 +97,7 @@ of `Adapter` is inside one pad's chain function, in which case access is serialized via the pad's STREAM_LOCK. Note that `Adapter::push` takes ownership of the buffer passed. Use -`gst_buffer_ref` before pushing it into the adapter if you still want to +`gst::Buffer::ref` before pushing it into the adapter if you still want to access the buffer later. The adapter will never modify the data in the buffer pushed in it. @@ -178,7 +178,7 @@ Returns a `gst::Buffer` containing the first `nbytes` of the `self`, but does not flush them from the adapter. See `Adapter::take_buffer` for details. -Caller owns a reference to the returned buffer. `gst_buffer_unref` after +Caller owns a reference to the returned buffer. `gst::Buffer::unref` after usage. Free-function: gst_buffer_unref @@ -189,13 +189,13 @@ the number of bytes to get a `gst::Buffer` containing the first `nbytes` of the adapter, or `None` if `nbytes` bytes are not available. - `gst_buffer_unref` when no longer needed. + `gst::Buffer::unref` when no longer needed. Returns a `gst::Buffer` containing the first `nbytes` of the `self`, but does not flush them from the adapter. See `Adapter::take_buffer_fast` for details. -Caller owns a reference to the returned buffer. `gst_buffer_unref` after +Caller owns a reference to the returned buffer. `gst::Buffer::unref` after usage. Free-function: gst_buffer_unref @@ -206,13 +206,13 @@ the number of bytes to get a `gst::Buffer` containing the first `nbytes` of the adapter, or `None` if `nbytes` bytes are not available. - `gst_buffer_unref` when no longer needed. + `gst::Buffer::unref` when no longer needed. Returns a `gst::BufferList` of buffers containing the first `nbytes` bytes of the `self` but does not flush them from the adapter. See `Adapter::take_buffer_list` for details. -Caller owns the returned list. Call `gst_buffer_list_unref` to free +Caller owns the returned list. Call `gst::BufferList::unref` to free the list after usage. ## `nbytes` the number of bytes to get @@ -227,7 +227,7 @@ Returns a `glib::List` of buffers containing the first `nbytes` bytes of the `self`, but does not flush them from the adapter. See `Adapter::take_list` for details. -Caller owns returned list and contained buffers. `gst_buffer_unref` each +Caller owns returned list and contained buffers. `gst::Buffer::unref` each buffer in the list before freeing the list after usage. ## `nbytes` the number of bytes to get @@ -468,7 +468,7 @@ unset. Since 1.6 this will also copy over all GstMeta of the input buffers except for meta with the `gst::MetaFlags::Pooled` flag or with the "memory" tag. -Caller owns a reference to the returned buffer. `gst_buffer_unref` after +Caller owns a reference to the returned buffer. `gst::Buffer::unref` after usage. Free-function: gst_buffer_unref @@ -479,7 +479,7 @@ the number of bytes to take a `gst::Buffer` containing the first `nbytes` of the adapter, or `None` if `nbytes` bytes are not available. - `gst_buffer_unref` when no longer needed. + `gst::Buffer::unref` when no longer needed. Returns a `gst::Buffer` containing the first `nbytes` of the `self`. The returned bytes will be flushed from the adapter. This function @@ -500,7 +500,7 @@ for meta with the `gst::MetaFlags::Pooled` flag or with the "memory" tag. This function can return buffer up to the return value of `Adapter::available` without making copies if possible. -Caller owns a reference to the returned buffer. `gst_buffer_unref` after +Caller owns a reference to the returned buffer. `gst::Buffer::unref` after usage. Free-function: gst_buffer_unref @@ -511,14 +511,14 @@ the number of bytes to take a `gst::Buffer` containing the first `nbytes` of the adapter, or `None` if `nbytes` bytes are not available. - `gst_buffer_unref` when no longer needed. + `gst::Buffer::unref` when no longer needed. Returns a `gst::BufferList` of buffers containing the first `nbytes` bytes of the `self`. The returned bytes will be flushed from the adapter. When the caller can deal with individual buffers, this function is more performant because no memory should be copied. -Caller owns the returned list. Call `gst_buffer_list_unref` to free +Caller owns the returned list. Call `gst::BufferList::unref` to free the list after usage. ## `nbytes` the number of bytes to take @@ -534,7 +534,7 @@ Returns a `glib::List` of buffers containing the first `nbytes` bytes of the When the caller can deal with individual buffers, this function is more performant because no memory should be copied. -Caller owns returned list and contained buffers. `gst_buffer_unref` each +Caller owns returned list and contained buffers. `gst::Buffer::unref` each buffer in the list before freeing the list after usage. ## `nbytes` the number of bytes to take @@ -592,7 +592,7 @@ Feature: `v1_14` # Implements -[`AggregatorExt`](trait.AggregatorExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`AggregatorExt`](trait.AggregatorExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`AggregatorExtManual`](prelude/trait.AggregatorExtManual.html) Trait containing all `Aggregator` methods. @@ -646,6 +646,17 @@ Feature: `v1_14` # Returns The latency or `GST_CLOCK_TIME_NONE` if the element does not sync + +Negotiates src pad caps with downstream elements. +Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again +if `AggregatorClass.negotiate`() fails. + +Feature: `v1_18` + + +# Returns + +`true` if the negotiation succeeded, else `false`. Lets `Aggregator` sub-classes tell the baseclass what their internal latency is. Will also post a LATENCY message on the bus so the pipeline @@ -665,7 +676,7 @@ Feature: `v1_14` ## `caps` The `gst::Caps` to set on the src pad. -This is a simple `Aggregator::get_next_time` implementation that +This is a simple `AggregatorClass.get_next_time`() implementation that just looks at the `gst::Segment` on the srcpad of the aggregator and bases the next time on the running time there. @@ -678,6 +689,13 @@ Feature: `v1_16` # Returns The running time based on the position + +Subclasses should use this to update the segment on their +source pad, instead of directly pushing new segment events +downstream. + +Feature: `v1_18` + Force minimum upstream latency (in nanoseconds). When sources with a higher latency are expected to be plugged in dynamically after the @@ -697,7 +715,7 @@ account when larger than the actually reported minimum latency. Feature: `v1_16` -Pads managed by a `GstAggregor` subclass. +Pads managed by a `Aggregator` subclass. This class used to live in gst-plugins-bad and was moved to core. @@ -705,7 +723,7 @@ Feature: `v1_14` # Implements -[`AggregatorPadExt`](trait.AggregatorPadExt.html), [`gst::PadExt`](../gst/trait.PadExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`AggregatorPadExt`](trait.AggregatorPadExt.html), [`gst::PadExt`](../gst/trait.PadExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`AggregatorPadExtManual`](prelude/trait.AggregatorPadExtManual.html) Trait containing all `AggregatorPad` methods. @@ -857,7 +875,7 @@ a parser and share a lot of rather complex code. * During the parsing process `BaseParseClass` will handle both srcpad and sinkpad events. They will be passed to subclass if - `BaseParseClass.event`() or `BaseParseClass.src_event`() + `BaseParseClass.sink_event`() or `BaseParseClass.src_event`() implementations have been provided. ## Shutdown phase @@ -911,7 +929,7 @@ Things that subclass need to take care of: # Implements -[`BaseParseExt`](trait.BaseParseExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`BaseParseExt`](trait.BaseParseExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BaseParseExtManual`](prelude/trait.BaseParseExtManual.html) Trait containing all `BaseParse` methods. @@ -1268,7 +1286,7 @@ with non-synchronized streams or sparse streams. # Implements -[`BaseSinkExt`](trait.BaseSinkExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`BaseSinkExt`](trait.BaseSinkExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BaseSinkExtManual`](prelude/trait.BaseSinkExtManual.html) Trait containing all `BaseSink` methods. @@ -1317,7 +1335,7 @@ Free-function: gst_sample_unref # Returns -a `gst::Sample`. `gst_sample_unref` after +a `gst::Sample`. `gst::Sample::unref` after usage. This function returns `None` when no buffer has arrived in the sink yet or when the sink is not in PAUSED or PLAYING. @@ -1359,6 +1377,20 @@ information about the render delay. # Returns the render delay of `self`. + +Return various `BaseSink` statistics. This function returns a `gst::Structure` +with name `application/x-gst-base-sink-stats` with the following fields: + +- "average-rate" G_TYPE_DOUBLE average frame rate +- "dropped" G_TYPE_UINT64 Number of dropped frames +- "rendered" G_TYPE_UINT64 Number of rendered frames + +Feature: `v1_18` + + +# Returns + +pointer to `gst::Structure` Checks if `self` is currently configured to synchronize against the clock. @@ -1633,6 +1665,16 @@ make other sinks compensate for the delay. The additional delay between synchronisation and actual rendering of the media. This property will add additional latency to the device in order to make other sinks compensate for the delay. + +Various `BaseSink` statistics. This property returns a `gst::Structure` +with name `application/x-gst-base-sink-stats` with the following fields: + +- "average-rate" G_TYPE_DOUBLE average frame rate +- "dropped" G_TYPE_UINT64 Number of dropped frames +- "rendered" G_TYPE_UINT64 Number of rendered frames + +Feature: `v1_18` + The time to insert between buffers. This property can be used to control the maximum amount of buffers per second to render. Setting this property @@ -1766,7 +1808,7 @@ received, it may safely shut down the entire pipeline. # Implements -[`BaseSrcExt`](trait.BaseSrcExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`BaseSrcExt`](trait.BaseSrcExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BaseSrcExtManual`](prelude/trait.BaseSrcExtManual.html) Trait containing all `BaseSrc` methods. @@ -1814,9 +1856,24 @@ Check if an element is in live mode. # Returns `true` if element is in live mode. + +Negotiates src pad caps with downstream elements. +Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again +if `BaseSrcClass.negotiate`() fails. + +Do not call this in the `BaseSrcClass.fill`() vmethod. Call this in +`BaseSrcClass.create`() or in `BaseSrcClass.alloc`(), _before_ any +buffer is allocated. + +Feature: `v1_18` + + +# Returns + +`true` if the negotiation succeeded, else `false`. Prepare a new seamless segment for emission downstream. This function must -only be called by derived sub-classes, and only from the `create` function, +only be called by derived sub-classes, and only from the `BaseSrcClass::create` function, as the stream-lock needs to be held. The format for the new segment will be the current format of the source, as @@ -1864,7 +1921,7 @@ when trying to read more should set this to `false`. When `self` operates in `gst::Format::Time`, `BaseSrc` will send an EOS when a buffer outside of the currently configured segment is pushed if `automatic_eos` is `true`. Since 1.16, if `automatic_eos` is `false` an -EOS will be pushed only when the `BaseSrc.create` implementation +EOS will be pushed only when the `BaseSrcClass.create`() implementation returns `gst::FlowReturn::Eos`. ## `automatic_eos` automatic eos @@ -2071,7 +2128,7 @@ It provides for: # Implements -[`BaseTransformExt`](trait.BaseTransformExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`BaseTransformExt`](trait.BaseTransformExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BaseTransformExtManual`](prelude/trait.BaseTransformExtManual.html) Trait containing all `BaseTransform` methods. @@ -2079,10 +2136,10 @@ Trait containing all `BaseTransform` methods. [`BaseTransform`](struct.BaseTransform.html) -Lets `BaseTransform` sub-classes to know the memory `allocator` +Lets `BaseTransform` sub-classes know the memory `allocator` used by the base class and its `params`. -Unref the `allocator` after use it. +Unref the `allocator` after use. ## `allocator` the `gst::Allocator` used @@ -2094,13 +2151,13 @@ the # Returns the instance of the `gst::BufferPool` used -by `self`; free it after use it +by `self`; free it after use See if `self` is configured as a in_place transform. # Returns -`true` is the transform is configured in in_place mode. +`true` if the transform is configured in in_place mode. MT safe. @@ -2108,7 +2165,7 @@ See if `self` is configured as a passthrough transform. # Returns -`true` is the transform is configured in passthrough mode. +`true` if the transform is configured in passthrough mode. MT safe. @@ -2119,6 +2176,28 @@ Queries if the transform will handle QoS. `true` if QoS is enabled. MT safe. + +Negotiates src pad caps with downstream elements if the source pad is +marked as needing reconfiguring. Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in +any case. But marks it again if negotiation fails. + +Do not call this in the `BaseTransformClass.transform`() or +`BaseTransformClass.transform_ip`() vmethod. Call this in +`BaseTransformClass.submit_input_buffer`(), +`BaseTransformClass.prepare_output_buffer`() or in +`BaseTransformClass.generate_output`() _before_ any output buffer is +allocated. + +It will be default be called when handling an ALLOCATION query or at the +very beginning of the default `BaseTransformClass.submit_input_buffer`() +implementation. + +Feature: `v1_18` + + +# Returns + +`true` if the negotiation succeeded, else `false`. Instructs `self` to request renegotiation upstream. This function is typically called after properties on the transform were set that @@ -2154,7 +2233,7 @@ Set passthrough mode for this filter by default. This is mostly useful for filters that do not care about negotiation. Always `true` for filters which don't implement either a transform -or transform_ip method. +or transform_ip or generate_output method. MT safe. ## `passthrough` @@ -2193,7 +2272,7 @@ the diff against the clock the timestamp of the buffer generating the QoS expressed in running_time. -Updates the srcpad caps and send the caps downstream. This function +Updates the srcpad caps and sends the caps downstream. This function can be used by subclasses when they have already negotiated their caps but found a change in them (or computed new information). This way, they can notify downstream about that change without losing any @@ -2204,7 +2283,7 @@ downstream # Returns -`true` if the caps could be send downstream `false` otherwise +`true` if the caps could be sent downstream `false` otherwise Utility struct to help handling `gst::FlowReturn` combination. Useful for `gst::Element`s that have multiple source pads and need to combine @@ -2323,4 +2402,4 @@ base class. # Implements -[`BaseSrcExt`](trait.BaseSrcExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`BaseSrcExt`](trait.BaseSrcExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BaseSrcExtManual`](prelude/trait.BaseSrcExtManual.html) diff --git a/docs/gstreamer-check/docs.md b/docs/gstreamer-check/docs.md index 11f512829..c0d5532e2 100644 --- a/docs/gstreamer-check/docs.md +++ b/docs/gstreamer-check/docs.md @@ -1,1007 +1,4 @@ - -`Harness` is meant to make writing unit test for GStreamer much easier. -It can be thought of as a way of treating a `gst::Element` as a black box, -deterministically feeding it data, and controlling what data it outputs. - -The basic structure of `Harness` is two "floating" `GstPads` that connect -to the harnessed `gst::Element` src and sink `GstPads` like so: - - -```C - #include - #include - GstHarness *h; - GstBuffer *in_buf; - GstBuffer *out_buf; - - // attach the harness to the src and sink pad of GstQueue - h = gst_harness_new ("queue"); - - // we must specify a caps before pushing buffers - gst_harness_set_src_caps_str (h, "mycaps"); - - // create a buffer of size 42 - in_buf = gst_harness_create_buffer (h, 42); - - // push the buffer into the queue - gst_harness_push (h, in_buf); - - // pull the buffer from the queue - out_buf = gst_harness_pull (h); - - // validate the buffer in is the same as buffer out - fail_unless (in_buf == out_buf); - - // cleanup - gst_buffer_unref (out_buf); - gst_harness_teardown (h); - - ]| - -Another main feature of the #GstHarness is its integration with the -#GstTestClock. Operating the #GstTestClock can be very challenging, but -#GstHarness simplifies some of the most desired actions a lot, like wanting -to manually advance the clock while at the same time releasing a #GstClockID -that is waiting, with functions like gst_harness_crank_single_clock_wait(). - -#GstHarness also supports sub-harnesses, as a way of generating and -validating data. A sub-harness is another #GstHarness that is managed by -the "parent" harness, and can either be created by using the standard -gst_harness_new type functions directly on the (GstHarness *)->src_harness, -or using the much more convenient gst_harness_add_src() or -gst_harness_add_sink_parse(). If you have a decoder-element you want to test, -(like vp8dec) it can be very useful to add a src-harness with both a -src-element (videotestsrc) and an encoder (vp8enc) to feed the decoder data -with different configurations, by simply doing: - -|[ - GstHarness * h = gst_harness_new (h, "vp8dec"); - gst_harness_add_src_parse (h, "videotestsrc is-live=1 ! vp8enc", TRUE); -``` - -and then feeding it data with: - - -```C -gst_harness_push_from_src (h); -``` - -Adds a `gst::Element` to an empty `Harness` - -MT safe. -## `element` -a `gst::Element` to add to the harness (transfer none) -## `hsrc` -a `gst::StaticPadTemplate` describing the harness srcpad. -`None` will not create a harness srcpad. -## `element_sinkpad_name` -a `gchar` with the name of the element -sinkpad that is then linked to the harness srcpad. Can be a static or request -or a sometimes pad that has been added. `None` will not get/request a sinkpad -from the element. (Like if the element is a src.) -## `hsink` -a `gst::StaticPadTemplate` describing the harness sinkpad. -`None` will not create a harness sinkpad. -## `element_srcpad_name` -a `gchar` with the name of the element -srcpad that is then linked to the harness sinkpad, similar to the -`element_sinkpad_name`. - -Links the specified `gst::Pad` the `Harness` srcpad. - -MT safe. -## `sinkpad` -a `gst::Pad` to link to the harness srcpad - -Links the specified `gst::Pad` the `Harness` sinkpad. This can be useful if -perhaps the srcpad did not exist at the time of creating the harness, -like a demuxer that provides a sometimes-pad after receiving data. - -MT safe. -## `srcpad` -a `gst::Pad` to link to the harness sinkpad - -Parses the `launchline` and puts that in a `gst::Bin`, -and then attches the supplied `Harness` to the bin. - -MT safe. -## `launchline` -a `gchar` describing a gst-launch type line - -A convenience function to allows you to call gst_pad_add_probe on a -`gst::Pad` of a `gst::Element` that are residing inside the `Harness`, -by using normal gst_pad_add_probe syntax - -MT safe. -## `element_name` -a `gchar` with a `gst::ElementFactory` name -## `pad_name` -a `gchar` with the name of the pad to attach the probe to -## `mask` -a `gst::PadProbeType` (see gst_pad_add_probe) -## `callback` -a `GstPadProbeCallback` (see gst_pad_add_probe) -## `user_data` -a `gpointer` (see gst_pad_add_probe) -## `destroy_data` -a `GDestroyNotify` (see gst_pad_add_probe) - -Add api with params as one of the supported metadata API to propose when -receiving an allocation query. - -MT safe. - -Feature: `v1_16` - -## `api` -a metadata API -## `params` -API specific parameters - -Similar to gst_harness_add_sink_harness, this is a convenience to -directly create a sink-harness using the `sink_element_name` name specified. - -MT safe. -## `sink_element_name` -a `gchar` with the name of a `gst::Element` - -Similar to gst_harness_add_src, this allows you to send the data coming out -of your harnessed `gst::Element` to a sink-element, allowing to test different -responses the element output might create in sink elements. An example might -be an existing sink providing some analytical data on the input it receives that -can be useful to your testing. If the goal is to test a sink-element itself, -this is better achieved using gst_harness_new directly on the sink. - -If a sink-harness already exists it will be replaced. - -MT safe. -## `sink_harness` -a `Harness` to be added as a sink-harness. - -Similar to gst_harness_add_sink, this allows you to specify a launch-line -instead of just an element name. See gst_harness_add_src_parse for details. - -MT safe. -## `launchline` -a `gchar` with the name of a `gst::Element` - -Similar to gst_harness_add_src_harness, this is a convenience to -directly create a src-harness using the `src_element_name` name specified. - -MT safe. -## `src_element_name` -a `gchar` with the name of a `gst::Element` -## `has_clock_wait` -a `gboolean` specifying if the `gst::Element` uses -gst_clock_wait_id internally. - -A src-harness is a great way of providing the `Harness` with data. -By adding a src-type `gst::Element`, it is then easy to use functions like -gst_harness_push_from_src or gst_harness_src_crank_and_push_many -to provide your harnessed element with input. The `has_clock_wait` variable -is a great way to control you src-element with, in that you can have it -produce a buffer for you by simply cranking the clock, and not have it -spin out of control producing buffers as fast as possible. - -If a src-harness already exists it will be replaced. - -MT safe. -## `src_harness` -a `Harness` to be added as a src-harness. -## `has_clock_wait` -a `gboolean` specifying if the `gst::Element` uses -gst_clock_wait_id internally. - -Similar to gst_harness_add_src, this allows you to specify a launch-line, -which can be useful for both having more then one `gst::Element` acting as your -src (Like a src producing raw buffers, and then an encoder, providing encoded -data), but also by allowing you to set properties like "is-live" directly on -the elements. - -MT safe. -## `launchline` -a `gchar` describing a gst-launch type line -## `has_clock_wait` -a `gboolean` specifying if the `gst::Element` uses -gst_clock_wait_id internally. - -The number of `GstBuffers` currently in the `Harness` sinkpad `glib::AsyncQueue` - -MT safe. - -# Returns - -a `guint` number of buffers in the queue - -The total number of `GstBuffers` that has arrived on the `Harness` sinkpad. -This number includes buffers that have been dropped as well as buffers -that have already been pulled out. - -MT safe. - -# Returns - -a `guint` number of buffers received - -Similar to `Harness::crank_single_clock_wait`, this is the function to use -if your harnessed element(s) are using more then one gst_clock_id_wait. -Failing to do so can (and will) make it racy which `gst::ClockID` you actually -are releasing, where as this function will process all the waits at the -same time, ensuring that one thread can't register another wait before -both are released. - -MT safe. -## `waits` -a `guint` describing the number of `GstClockIDs` to crank - -# Returns - -a `gboolean` `true` if the "crank" was successful, `false` if not. - -A "crank" consists of three steps: -1: Wait for a `gst::ClockID` to be registered with the `TestClock`. -2: Advance the `TestClock` to the time the `gst::ClockID` is waiting for. -3: Release the `gst::ClockID` wait. -Together, this provides an easy way to not have to think about the details -around clocks and time, but still being able to write deterministic tests -that are dependent on this. A "crank" can be though of as the notion of -manually driving the clock forward to its next logical step. - -MT safe. - -# Returns - -a `gboolean` `true` if the "crank" was successful, `false` if not. - -Allocates a buffer using a `gst::BufferPool` if present, or else using the -configured `gst::Allocator` and `gst::AllocationParams` - -MT safe. -## `size` -a `gsize` specifying the size of the buffer - -# Returns - -a `gst::Buffer` of size `size` - -Allows you to dump the `GstBuffers` the `Harness` sinkpad `glib::AsyncQueue` -to a file. - -MT safe. -## `filename` -a `gchar` with a the name of a file - -The number of `GstEvents` currently in the `Harness` sinkpad `glib::AsyncQueue` - -MT safe. - -# Returns - -a `guint` number of events in the queue - -The total number of `GstEvents` that has arrived on the `Harness` sinkpad -This number includes events handled by the harness as well as events -that have already been pulled out. - -MT safe. - -# Returns - -a `guint` number of events received - -Most useful in conjunction with gst_harness_new_parse, this will scan the -`GstElements` inside the `Harness`, and check if any of them matches -`element_name`. Typical usecase being that you need to access one of the -harnessed elements for properties and/or signals. - -MT safe. -## `element_name` -a `gchar` with a `gst::ElementFactory` name - -# Returns - -a `gst::Element` or `None` if not found - -A convenience function to allows you to call g_object_get on a `gst::Element` -that are residing inside the `Harness`, by using normal g_object_get -syntax. - -MT safe. -## `element_name` -a `gchar` with a `gst::ElementFactory` name -## `first_property_name` -a `gchar` with the first property name - -Gets the `allocator` and its `params` that has been decided to use after an -allocation query. - -MT safe. -## `allocator` -the `gst::Allocator` used -## `params` -the `gst::AllocationParams` of - `allocator` - -Get the timestamp of the last `gst::Buffer` pushed on the `Harness` srcpad, -typically with gst_harness_push or gst_harness_push_from_src. - -MT safe. - -# Returns - -a `gst::ClockTime` with the timestamp or `GST_CLOCK_TIME_NONE` if no -`gst::Buffer` has been pushed on the `Harness` srcpad - -Get the `TestClock`. Useful if specific operations on the testclock is -needed. - -MT safe. - -# Returns - -a `TestClock`, or `None` if the testclock is not -present. - -This will set the harnessed `gst::Element` to `gst::State::Playing`. -`GstElements` without a sink-`gst::Pad` and with the `gst::ElementFlags::Source` -flag set is considered a src `gst::Element` -Non-src `GstElements` (like sinks and filters) are automatically set to -playing by the `Harness`, but src `GstElements` are not to avoid them -starting to produce buffers. -Hence, for src `gst::Element` you must call `Harness::play` explicitly. - -MT safe. - -Pulls a `gst::Buffer` from the `glib::AsyncQueue` on the `Harness` sinkpad. The pull -will timeout in 60 seconds. This is the standard way of getting a buffer -from a harnessed `gst::Element`. - -MT safe. - -# Returns - -a `gst::Buffer` or `None` if timed out. - -Pulls an `gst::Event` from the `glib::AsyncQueue` on the `Harness` sinkpad. -Timeouts after 60 seconds similar to gst_harness_pull. - -MT safe. - -# Returns - -a `gst::Event` or `None` if timed out. - -Pulls an `gst::Event` from the `glib::AsyncQueue` on the `Harness` srcpad. -Timeouts after 60 seconds similar to gst_harness_pull. - -MT safe. - -# Returns - -a `gst::Event` or `None` if timed out. - -Pushes a `gst::Buffer` on the `Harness` srcpad. The standard way of -interacting with an harnessed element. - -MT safe. -## `buffer` -a `gst::Buffer` to push - -# Returns - -a `gst::FlowReturn` with the result from the push - -Basically a gst_harness_push and a gst_harness_pull in one line. Reflects -the fact that you often want to do exactly this in your test: Push one buffer -in, and inspect the outcome. - -MT safe. -## `buffer` -a `gst::Buffer` to push - -# Returns - -a `gst::Buffer` or `None` if timed out. - -Pushes an `gst::Event` on the `Harness` srcpad. - -MT safe. -## `event` -a `gst::Event` to push - -# Returns - -a `gboolean` with the result from the push - -Transfer data from the src-`Harness` to the main-`Harness`. It consists -of 4 steps: -1: Make sure the src is started. (see: gst_harness_play) -2: Crank the clock (see: gst_harness_crank_single_clock_wait) -3: Pull a `gst::Buffer` from the src-`Harness` (see: gst_harness_pull) -4: Push the same `gst::Buffer` into the main-`Harness` (see: gst_harness_push) - -MT safe. - -# Returns - -a `gst::FlowReturn` with the result of the push - -Transfer one `gst::Buffer` from the main-`Harness` to the sink-`Harness`. -See gst_harness_push_from_src for details. - -MT safe. - -# Returns - -a `gst::FlowReturn` with the result of the push - -Pushes an `gst::Event` on the `Harness` sinkpad. - -MT safe. -## `event` -a `gst::Event` to push - -# Returns - -a `gboolean` with the result from the push - -Get the min latency reported by any harnessed `gst::Element`. - -MT safe. - -# Returns - -a `gst::ClockTime` with min latency - -A convenience function to allows you to call g_object_set on a `gst::Element` -that are residing inside the `Harness`, by using normal g_object_set -syntax. - -MT safe. -## `element_name` -a `gchar` with a `gst::ElementFactory` name -## `first_property_name` -a `gchar` with the first property name - -Setting this will make the harness block in the chain-function, and -then release when `Harness::pull` or `Harness::try_pull` is called. -Can be useful when wanting to control a src-element that is not implementing -`gst::Clock::id_wait` so it can't be controlled by the `TestClock`, since -it otherwise would produce buffers as fast as possible. - -MT safe. - -Sets the `Harness` srcpad and sinkpad caps. - -MT safe. -## `in_` -a `gst::Caps` to set on the harness srcpad -## `out` -a `gst::Caps` to set on the harness sinkpad - -Sets the `Harness` srcpad and sinkpad caps using strings. - -MT safe. -## `in_` -a `gchar` describing a `gst::Caps` to set on the harness srcpad -## `out` -a `gchar` describing a `gst::Caps` to set on the harness sinkpad - -When set to `true`, instead of placing the buffers arriving from the harnessed -`gst::Element` inside the sinkpads `glib::AsyncQueue`, they are instead unreffed. - -MT safe. -## `drop_buffers` -a `gboolean` specifying to drop outgoing buffers or not - -As a convenience, a src-harness will forward `gst::EventType::StreamStart`, -`gst::EventType::Caps` and `gst::EventType::Segment` to the main-harness if forwarding -is enabled, and forward any sticky-events from the main-harness to -the sink-harness. It will also forward the `gst::QueryType::Allocation`. - -If forwarding is disabled, the user will have to either manually push -these events from the src-harness using `Harness::src_push_event`, or -create and push them manually. While this will allow full control and -inspection of these events, for the most cases having forwarding enabled -will be sufficient when writing a test where the src-harness' main function -is providing data for the main-harness. - -Forwarding is enabled by default. - -MT safe. -## `forwarding` -a `gboolean` to enable/disable forwarding - -Sets the `allocator` and `params` to propose when receiving an allocation -query. - -MT safe. -## `allocator` -a `gst::Allocator` -## `params` -a `gst::AllocationParams` - -Sets the `Harness` sinkpad caps. - -MT safe. -## `caps` -a `gst::Caps` to set on the harness sinkpad - -Sets the `Harness` sinkpad caps using a string. - -MT safe. -## `str` -a `gchar` describing a `gst::Caps` to set on the harness sinkpad - -Sets the `Harness` srcpad caps. This must be done before any buffers -can legally be pushed from the harness to the element. - -MT safe. -## `caps` -a `gst::Caps` to set on the harness srcpad - -Sets the `Harness` srcpad caps using a string. This must be done before -any buffers can legally be pushed from the harness to the element. - -MT safe. -## `str` -a `gchar` describing a `gst::Caps` to set on the harness srcpad - -Advance the `TestClock` to a specific time. - -MT safe. -## `time` -a `gst::ClockTime` to advance the clock to - -# Returns - -a `gboolean` `true` if the time could be set. `false` if not. - -Sets the min latency reported by `Harness` when receiving a latency-query -## `latency` -a `gst::ClockTime` specifying the latency - -Convenience that calls gst_harness_push_to_sink `pushes` number of times. -Will abort the pushing if any one push fails. - -MT safe. -## `pushes` -a `gint` with the number of calls to gst_harness_push_to_sink - -# Returns - -a `gst::FlowReturn` with the result of the push - -Transfer data from the src-`Harness` to the main-`Harness`. Similar to -gst_harness_push_from_src, this variant allows you to specify how many cranks -and how many pushes to perform. This can be useful for both moving a lot -of data at the same time, as well as cases when one crank does not equal one -buffer to push and v.v. - -MT safe. -## `cranks` -a `gint` with the number of calls to gst_harness_crank_single_clock_wait -## `pushes` -a `gint` with the number of calls to gst_harness_push - -# Returns - -a `gst::FlowReturn` with the result of the push - -Similar to what gst_harness_src_push does with `GstBuffers`, this transfers -a `gst::Event` from the src-`Harness` to the main-`Harness`. Note that -some `GstEvents` are being transferred automagically. Look at sink_forward_pad -for details. - -MT safe. - -# Returns - -a `gboolean` with the result of the push - -Start a custom stress-thread that will call your `callback` for every -iteration allowing you to do something nasty. - -MT safe. -## `init` -a `GFunc` that is called initially and only once -## `callback` -a `GFunc` that is called as often as possible -## `data` -a `gpointer` with custom data to pass to the `callback` function -## `sleep` -a `gulong` specifying how long to sleep in (microseconds) for -each call to the `callback` - -# Returns - -a `HarnessThread` - -Call g_object_set with `name` and `value` in intervals of `sleep` microseconds - -MT safe. -## `name` -a `gchar` specifying a property name -## `value` -a `gobject::Value` to set the property to -## `sleep` -a `gulong` specifying how long to sleep in (microseconds) for -each g_object_set with `name` and `value` - -# Returns - -a `HarnessThread` - -Push a `gst::Buffer` in intervals of `sleep` microseconds. - -MT safe. -## `caps` -a `gst::Caps` for the `gst::Buffer` -## `segment` -a `gst::Segment` -## `buf` -a `gst::Buffer` to push -## `sleep` -a `gulong` specifying how long to sleep in (microseconds) for -each call to gst_pad_push - -# Returns - -a `HarnessThread` - -Push a `gst::Buffer` returned by `func` in intervals of `sleep` microseconds. - -MT safe. -## `caps` -a `gst::Caps` for the `gst::Buffer` -## `segment` -a `gst::Segment` -## `func` -a `GstHarnessPrepareBufferFunc` function called before every iteration -to prepare / create a `gst::Buffer` for pushing -## `data` -a `gpointer` with data to the `GstHarnessPrepareBufferFunc` function -## `notify` -a `GDestroyNotify` that is called when thread is stopped -## `sleep` -a `gulong` specifying how long to sleep in (microseconds) for -each call to gst_pad_push - -# Returns - -a `HarnessThread` - -Push the `event` onto the harnessed `gst::Element` sinkpad in intervals of -`sleep` microseconds - -MT safe. -## `event` -a `gst::Event` to push -## `sleep` -a `gulong` specifying how long to sleep in (microseconds) for -each gst_event_push with `event` - -# Returns - -a `HarnessThread` - -Push a `gst::Event` returned by `func` onto the harnessed `gst::Element` sinkpad -in intervals of `sleep` microseconds. - -MT safe. -## `func` -a `GstHarnessPrepareEventFunc` function called before every iteration -to prepare / create a `gst::Event` for pushing -## `data` -a `gpointer` with data to the `GstHarnessPrepareEventFunc` function -## `notify` -a `GDestroyNotify` that is called when thread is stopped -## `sleep` -a `gulong` specifying how long to sleep in (microseconds) for -each call to gst_pad_push - -# Returns - -a `HarnessThread` - -Push the `event` onto the harnessed `gst::Element` srcpad in intervals of -`sleep` microseconds. - -MT safe. -## `event` -a `gst::Event` to push -## `sleep` -a `gulong` specifying how long to sleep in (microseconds) for -each gst_event_push with `event` - -# Returns - -a `HarnessThread` - -Push a `gst::Event` returned by `func` onto the harnessed `gst::Element` srcpad -in intervals of `sleep` microseconds. - -MT safe. -## `func` -a `GstHarnessPrepareEventFunc` function called before every iteration -to prepare / create a `gst::Event` for pushing -## `data` -a `gpointer` with data to the `GstHarnessPrepareEventFunc` function -## `notify` -a `GDestroyNotify` that is called when thread is stopped -## `sleep` -a `gulong` specifying how long to sleep in (microseconds) for -each call to gst_pad_push - -# Returns - -a `HarnessThread` - -Call gst_element_request_pad in intervals of `sleep` microseconds - -MT safe. -## `templ` -a `gst::PadTemplate` -## `name` -a `gchar` -## `caps` -a `gst::Caps` -## `release` -a `gboolean` -## `sleep` -a `gulong` specifying how long to sleep in (microseconds) for -each gst_element_request_pad - -# Returns - -a `HarnessThread` - -Change the state of your harnessed `gst::Element` from NULL to PLAYING and -back again, only pausing for `sleep` microseconds every time. - -MT safe. -## `sleep` -a `gulong` specifying how long to sleep in (microseconds) for -each state-change - -# Returns - -a `HarnessThread` - -Pulls all pending data from the harness and returns it as a single -data slice. - -Feature: `v1_14` - -## `size` -the size of the data in bytes - -# Returns - -a pointer to the data, newly allocated. Free - with `g_free` when no longer needed. Will return `None` if there is no - data. - -Pulls all pending data from the harness and returns it as a single buffer. - -Feature: `v1_14` - - -# Returns - -the data as a buffer. Unref with `gst_buffer_unref` - when no longer needed. - -Pulls all pending data from the harness and returns it as a single `glib::Bytes`. - -Feature: `v1_14` - - -# Returns - -a pointer to the data, newly allocated. Free - with `g_free` when no longer needed. - -Tears down a `Harness`, freeing all resources allocated using it. - -MT safe. - -Pulls a `gst::Buffer` from the `glib::AsyncQueue` on the `Harness` sinkpad. Unlike -gst_harness_pull this will not wait for any buffers if not any are present, -and return `None` straight away. - -MT safe. - -# Returns - -a `gst::Buffer` or `None` if no buffers are present in the `glib::AsyncQueue` - -Pulls an `gst::Event` from the `glib::AsyncQueue` on the `Harness` sinkpad. -See gst_harness_try_pull for details. - -MT safe. - -# Returns - -a `gst::Event` or `None` if no buffers are present in the `glib::AsyncQueue` - -Pulls an `gst::Event` from the `glib::AsyncQueue` on the `Harness` srcpad. -See gst_harness_try_pull for details. - -MT safe. - -# Returns - -a `gst::Event` or `None` if no buffers are present in the `glib::AsyncQueue` - -The number of `GstEvents` currently in the `Harness` srcpad `glib::AsyncQueue` - -MT safe. - -# Returns - -a `guint` number of events in the queue - -The total number of `GstEvents` that has arrived on the `Harness` srcpad -This number includes events handled by the harness as well as events -that have already been pulled out. - -MT safe. - -# Returns - -a `guint` number of events received - -Sets the system `gst::Clock` on the `Harness` `gst::Element` - -MT safe. - -Sets the `TestClock` on the `Harness` `gst::Element` - -MT safe. - -Waits for `timeout` seconds until `waits` number of `gst::ClockID` waits is -registered with the `TestClock`. Useful for writing deterministic tests, -where you want to make sure that an expected number of waits have been -reached. - -MT safe. -## `waits` -a `guint` describing the numbers of `gst::ClockID` registered with -the `TestClock` -## `timeout` -a `guint` describing how many seconds to wait for `waits` to be true - -# Returns - -a `gboolean` `true` if the waits have been registered, `false` if not. -(Could be that it timed out waiting or that more waits than waits was found) - -Creates a new harness. Works like `Harness::new_with_padnames`, except it -assumes the `gst::Element` sinkpad is named "sink" and srcpad is named "src" - -MT safe. -## `element_name` -a `gchar` describing the `gst::Element` name - -# Returns - -a `Harness`, or `None` if the harness could -not be created - -Creates a new empty harness. Use `Harness::add_element_full` to add -an `gst::Element` to it. - -MT safe. - -# Returns - -a `Harness`, or `None` if the harness could -not be created - -Creates a new harness. - -MT safe. -## `element` -a `gst::Element` to attach the harness to (transfer none) -## `hsrc` -a `gst::StaticPadTemplate` describing the harness srcpad. -`None` will not create a harness srcpad. -## `element_sinkpad_name` -a `gchar` with the name of the element -sinkpad that is then linked to the harness srcpad. Can be a static or request -or a sometimes pad that has been added. `None` will not get/request a sinkpad -from the element. (Like if the element is a src.) -## `hsink` -a `gst::StaticPadTemplate` describing the harness sinkpad. -`None` will not create a harness sinkpad. -## `element_srcpad_name` -a `gchar` with the name of the element -srcpad that is then linked to the harness sinkpad, similar to the -`element_sinkpad_name`. - -# Returns - -a `Harness`, or `None` if the harness could -not be created - -Creates a new harness, parsing the `launchline` and putting that in a `gst::Bin`, -and then attches the harness to the bin. - -MT safe. -## `launchline` -a `gchar` describing a gst-launch type line - -# Returns - -a `Harness`, or `None` if the harness could -not be created - -Creates a new harness. Works in the same way as `Harness::new_full`, only -that generic padtemplates are used for the harness src and sinkpads, which -will be sufficient in most usecases. - -MT safe. -## `element` -a `gst::Element` to attach the harness to (transfer none) -## `element_sinkpad_name` -a `gchar` with the name of the element -sinkpad that is then linked to the harness srcpad. `None` does not attach a -sinkpad -## `element_srcpad_name` -a `gchar` with the name of the element -srcpad that is then linked to the harness sinkpad. `None` does not attach a -srcpad - -# Returns - -a `Harness`, or `None` if the harness could -not be created - -Creates a new harness. Works like `Harness::new_with_element`, -except you specify the factoryname of the `gst::Element` - -MT safe. -## `element_name` -a `gchar` describing the `gst::Element` name -## `element_sinkpad_name` -a `gchar` with the name of the element -sinkpad that is then linked to the harness srcpad. `None` does not attach a -sinkpad -## `element_srcpad_name` -a `gchar` with the name of the element -srcpad that is then linked to the harness sinkpad. `None` does not attach a -srcpad - -# Returns - -a `Harness`, or `None` if the harness could -not be created - -Creates a new harness, like `Harness::new_full`, except it -assumes the `gst::Element` sinkpad is named "sink" and srcpad is named "src" - -MT safe. -## `element_name` -a `gchar` describing the `gst::Element` name -## `hsrc` -a `gst::StaticPadTemplate` describing the harness srcpad. -`None` will not create a harness srcpad. -## `hsink` -a `gst::StaticPadTemplate` describing the harness sinkpad. -`None` will not create a harness sinkpad. - -# Returns - -a `Harness`, or `None` if the harness could -not be created - -Stop the running `HarnessThread` - -MT safe. -## `t` -a `HarnessThread` GstTestClock is an implementation of `gst::Clock` which has different behaviour compared to `gst::SystemClock`. Time for `gst::SystemClock` advances @@ -1189,7 +186,8 @@ a positive `gst::ClockTimeDiff` to be added to the time of the clock A "crank" consists of three steps: 1: Wait for a `gst::ClockID` to be registered with the `TestClock`. -2: Advance the `TestClock` to the time the `gst::ClockID` is waiting for. +2: Advance the `TestClock` to the time the `gst::ClockID` is waiting, unless + the clock time is already passed the clock id (Since: 1.18). 3: Release the `gst::ClockID` wait. A "crank" can be though of as the notion of manually driving the clock forward to its next logical step. @@ -1243,6 +241,15 @@ notification to look for `true` if `pending_id` is the next clock notification to be triggered, `false` otherwise. + +Processes and releases the pending ID. + +MT safe. + +Feature: `v1_18` + +## `pending_id` +`gst::ClockID` Processes and releases the pending IDs in the list. diff --git a/docs/gstreamer-editing-services/docs.md b/docs/gstreamer-editing-services/docs.md index 31cfe046a..e8ffdc968 100644 --- a/docs/gstreamer-editing-services/docs.md +++ b/docs/gstreamer-editing-services/docs.md @@ -1,14 +1,18 @@ -The Assets in the GStreamer Editing Services represent the resources -that can be used. You can create assets for any type that implements the `Extractable` -interface, for example `GESClips`, `Formatter`, and `TrackElement` do implement it. -This means that assets will represent for example a `GESUriClips`, `BaseEffect` etc, -and then you can extract objects of those types with the appropriate parameters from the asset -using the `AssetExt::extract` method: +A `Asset` in the GStreamer Editing Services represents a resources +that can be used. In particular, any class that implements the +`Extractable` interface may have some associated assets with a +corresponding `Asset:extractable-type`, from which its objects can be +extracted using `AssetExt::extract`. Some examples would be +`Clip`, `Formatter` and `TrackElement`. +All assets that are created within GES are stored in a cache; one per +each `Asset:id` and `Asset:extractable-type` pair. These assets can +be fetched, and initialized if they do not yet exist in the cache, +using `Asset::request`. -```text +``` c GESAsset *effect_asset; GESEffect *effect; @@ -20,25 +24,20 @@ effect = GES_EFFECT (ges_asset_extract (effect_asset)); ``` -In that example, the advantages of having a `Asset` are that you can know what effects -you are working with and let your user know about the avalaible ones, you can add metadata -to the `Asset` through the `MetaContainer` interface and you have a model for your -custom effects. Note that `Asset` management is making easier thanks to the `Project` class. +The advantage of using assets, rather than simply creating the object +directly, is that the currently loaded resources can be listed with +`ges_list_assets` and displayed to an end user. For example, to show +which media files have been loaded, and a standard list of effects. In +fact, the GES library already creates assets for `TransitionClip` and +`Formatter`, which you can use to list all the available transition +types and supported formats. -Each asset is represented by a pair of `extractable_type` and `id` (string). Actually the `extractable_type` -is the type that implements the `Extractable` interface, that means that for example for a `UriClip`, -the type that implements the `Extractable` interface is `Clip`. -The identifier represents different things depending on the `extractable_type` and you should check -the documentation of each type to know what the ID of `Asset` actually represents for that type. By default, -we only have one `Asset` per type, and the `id` is the name of the type, but this behaviour is overriden -to be more useful. For example, for GESTransitionClips, the ID is the vtype of the transition -you will extract from it (ie crossfade, box-wipe-rc etc..) For `Effect` the ID is the -`bin`-description property of the extracted objects (ie the gst-launch style description of the bin that -will be used). +The other advantage is that `Asset` implements `MetaContainer`, so +metadata can be set on the asset, with some subclasses automatically +creating this metadata on initiation. -Each and every `Asset` is cached into GES, and you can query those with the `ges_list_assets` function. -Also the system will automatically register `GESAssets` for `GESFormatters` and `GESTransitionClips` -and standard effects (actually not implemented yet) and you can simply query those calling: +For example, to display information about the supported formats, you +could do the following: ```text GList *formatter_assets, *tmp; @@ -49,17 +48,52 @@ and standard effects (actually not implemented yet) and you can simply query tho // Print some infos about the formatter GESAsset for (tmp = formatter_assets; tmp; tmp = tmp->next) { g_print ("Name of the formatter: %s, file extension it produces: %s", - ges_meta_container_get_string (GES_META_CONTAINER (tmp->data), GES_META_FORMATTER_NAME), - ges_meta_container_get_string (GES_META_CONTAINER (tmp->data), GES_META_FORMATTER_EXTENSION)); + ges_meta_container_get_string ( + GES_META_CONTAINER (tmp->data), GES_META_FORMATTER_NAME), + ges_meta_container_get_string ( + GES_META_CONTAINER (tmp->data), GES_META_FORMATTER_EXTENSION)); } g_list_free (transition_assets); ``` -You can request the creation of `GESAssets` using either `Asset::request` or -`Asset::request_async`. All the `GESAssets` are cached and thus any asset that has already -been created can be requested again without overhead. +## ID + +Each asset is uniquely defined in the cache by its +`Asset:extractable-type` and `Asset:id`. Depending on the +`Asset:extractable-type`, the `Asset:id` can be used to parametrise +the creation of the object upon extraction. By default, a class that +implements `Extractable` will only have a single associated asset, +with an `Asset:id` set to the type name of its objects. However, this +is overwritten by some implementations, which allow a class to have +multiple associated assets. For example, for `TransitionClip` the +`Asset:id` will be a nickname of the `TransitionClip:vtype`. You +should check the documentation for each extractable type to see if they +differ from the default. + +Moreover, each `Asset:extractable-type` may also associate itself +with a specific asset subclass. In such cases, when their asset is +requested, an asset of this subclass will be returned instead. + +## Managing + +You can use a `Project` to easily manage the assets of a +`Timeline`. + +## Proxies + +Some assets can (temporarily) act as the `Asset:proxy` of another +asset. When the original asset is requested from the cache, the proxy +will be returned in its place. This can be useful if, say, you want +to substitute a `UriClipAsset` corresponding to a high resolution +media file with the asset of a lower resolution stand in. + +An asset may even have several proxies, the first of which will act as +its default and be returned on requests, but the others will be ordered +to take its place once it is removed. You can add a proxy to an asset, +or set its default, using `AssetExt::set_proxy`, and you can remove +them with `AssetExt::unproxy`. # Implements @@ -71,52 +105,88 @@ Trait containing all `Asset` methods. [`Asset`](struct.Asset.html), [`Project`](struct.Project.html) -Sets an asset from the internal cache as needing reload. An asset needs reload -in the case where, for example, we were missing a GstPlugin to use it and that -plugin has been installed, or, that particular asset content as changed -meanwhile (in the case of the usage of proxies). +Indicate that an existing `Asset` in the cache should be reloaded +upon the next request. This can be used when some condition has +changed, which may require that an existing asset should be updated. +For example, if an external resource has changed or now become +available. -Once an asset has been set as "needs reload", requesting that asset again -will lead to it being re discovered, and reloaded as if it was not in the -cache before. +Note, the asset is not immediately changed, but will only actually +reload on the next call to `Asset::request` or +`Asset::request_async`. ## `extractable_type` -The `glib::Type` of the object that can be extracted from the - asset to be reloaded. +The `Asset:extractable-type` of the asset that +needs reloading ## `id` -The identifier of the asset to mark as needing reload +The `Asset:id` of the asset asset that needs +reloading # Returns -`true` if the asset was in the cache and could be set as needing reload, -`false` otherwise. +`true` if the specified asset exists in the cache and could be +marked for reloading. -Create a `Asset` in the most simple cases, you should look at the `extractable_type` -documentation to see if that constructor can be called for this particular type +Returns an asset with the given properties. If such an asset already +exists in the cache (it has been previously created in GES), then a +reference to the existing asset is returned. Otherwise, a newly created +asset is returned, and also added to the cache. -As it is recommanded not to instanciate assets for GESUriClip synchronously, -it will not work with this method, but you can instead use the specific -`UriClipAsset::request_sync` method if you really want to. +If the requested asset has been loaded with an error, then `error` is +set, if given, and `None` will be returned instead. + +Note that the given `id` may not be exactly the `Asset:id` that is +set on the returned asset. For instance, it may be adjusted into a +standard format. Or, if a `Extractable` type does not have its +extraction parametrised, as is the case by default, then the given `id` +may be ignored entirely and the `Asset:id` set to some standard, in +which case a `None` `id` can be given. + +Similarly, the given `extractable_type` may not be exactly the +`Asset:extractable-type` that is set on the returned asset. Instead, +the actual extractable type may correspond to a subclass of the given +`extractable_type`, depending on the given `id`. + +Moreover, depending on the given `extractable_type`, the returned asset +may belong to a subclass of `Asset`. + +Finally, if the requested asset has a `Asset:proxy`, then the proxy +that is found at the end of the chain of proxies is returned (a proxy's +proxy will take its place, and so on, unless it has no proxy). + +Some asset subclasses only support asynchronous construction of its +assets, such as `UriClip`. For such assets this method will fail, and +you should use `Asset::request_async` instead. In the case of +`UriClip`, you can use `UriClipAsset::request_sync` if you only +want to wait for the request to finish. ## `extractable_type` -The `glib::Type` of the object that can be extracted from the new asset. +The `Asset:extractable-type` of the asset ## `id` -The Identifier or `None` +The `Asset:id` of the asset # Returns -A reference to the wanted `Asset` or `None` +A reference to the requested +asset, or `None` if an error occurred. -The `callback` will be called from a running `glib::MainLoop` which is iterating a `glib::MainContext`. -Note that, users should ensure the `glib::MainContext`, since this method will notify -`callback` from the thread which was associated with a thread default -`glib::MainContext` at calling `ges_init`. -For example, if a user wants non-default `glib::MainContext` to be associated -with `callback`, `ges_init` must be called after g_main_context_push_thread_default () -with custom `glib::MainContext`. +Requests an asset with the given properties asynchronously (see +`Asset::request`). When the asset has been initialized or fetched +from the cache, the given callback function will be called. The +asset can then be retrieved in the callback using the +`Asset::request_finish` method on the given `gio::AsyncResult`. -Request a new `Asset` asyncronously, `callback` will be called when the materail is -ready to be used or if an error occured. +Note that the source object passed to the callback will be the +`Asset` corresponding to the request, but it may not have loaded +correctly and therefore can not be used as is. Instead, +`Asset::request_finish` should be used to fetch a usable asset, or +indicate that an error occurred in the asset's creation. -Example of request of a GESAsset async: +Note that the callback will be called in the `glib::MainLoop` running under +the same `glib::MainContext` that `ges_init` was called in. So, if you wish +the callback to be invoked outside the default `glib::MainContext`, you can +call `glib::MainContext::push_thread_default` in a new thread before +calling `ges_init`. + +Example of an asynchronous asset request: ```text // The request callback @@ -143,112 +213,479 @@ ges_asset_request_async (GES_TYPE_URI_CLIP, some_uri, NULL, (GAsyncReadyCallback) asset_loaded_cb, user_data); ``` ## `extractable_type` -The `glib::Type` of the object that can be extracted from the - new asset. The class must implement the `Extractable` interface. +The `Asset:extractable-type` of the asset ## `id` -The Identifier of the asset we want to create. This identifier depends of the extractable, -type you want. By default it is the name of the class itself (or `None`), but for example for a -GESEffect, it will be the pipeline description, for a GESUriClip it -will be the name of the file, etc... You should refer to the documentation of the `Extractable` -type you want to create a `Asset` for. +The `Asset:id` of the asset ## `cancellable` -optional `gio::Cancellable` object, `None` to ignore. +An object to allow cancellation of the +asset request, or `None` to ignore ## `callback` -a `GAsyncReadyCallback` to call when the initialization is finished, -Note that the `source` of the callback will be the `Asset`, but you need to -make sure that the asset is properly loaded using the `Asset::request_finish` -method. This asset can not be used as is. +A function to call when the initialization is finished ## `user_data` -The user data to pass when `callback` is called +Data to be passed to `callback` -Finalize the request of an async `Asset` +Fetches an asset requested by `Asset::request_async`, which +finalises the request. ## `res` -The `gio::AsyncResult` from which to get the newly created `Asset` +The task result to fetch the asset from # Returns -The `Asset` previously requested +The requested asset, or `None` if an error +occurred. -Extracts a new `gobject::Object` from `asset`. The type of the object is -defined by the extractable-type of `asset`, you can check what -type will be extracted from `asset` using -`AssetExt::get_extractable_type` +Extracts a new `Asset:extractable-type` object from the asset. The +`Asset:id` of the asset may determine the properties and state of the +newly created object. # Returns -A newly created `Extractable` +A newly created object, or `None` if an +error occurred. +Retrieve the error that was set on the asset when it was loaded. # Returns -The `glib::Error` of the asset or `None` if -the asset was loaded without issue +The error set on `asset`, or +`None` if no error occurred when `asset` was loaded. -Gets the type of object that can be extracted from `self` +Gets the `Asset:extractable-type` of the asset. # Returns -the type of object that can be extracted from `self` +The extractable type of `self`. -Gets the ID of a `Asset` +Gets the `Asset:id` of the asset. # Returns -The ID of `self` +The ID of `self`. +Gets the default `Asset:proxy` of the asset. # Returns -The proxy in use for `self` +The default proxy of `self`. +Gets the `Asset:proxy-target` of the asset. + +Note that the proxy target may have loaded with an error, so you should +call `AssetExt::get_error` on the returned target. # Returns -The `Asset` that is proxied by `self` +The asset that `self` is a proxy +of. +Get all the proxies that the asset has. The first item of the list will +be the default `Asset:proxy`. The second will be the proxy that is +'next in line' to be default, and so on. # Returns -The list of proxies `self` has. Note that the default asset to be -used is always the first in that list. +The list of proxies +that `self` has. -A proxying asset is an asset that can substitue the real `self`. For example if you -have a full HD `UriClipAsset` you might want to set a lower resolution (HD version -of the same file) as proxy. Note that when an asset is proxied, calling -`Asset::request` will actually return the proxy asset. +Sets the `Asset:proxy` for the asset. + +If `proxy` is among the existing proxies of the asset (see +`AssetExt::list_proxies`) it will be moved to become the default +proxy. Otherwise, if `proxy` is not `None`, it will be added to the list +of proxies, as the new default. The previous default proxy will become +'next in line' for if the new one is removed, and so on. As such, this +will **not** actually remove the previous default proxy (use +`AssetExt::unproxy` for that). + +Note that an asset can only act as a proxy for one other asset. + +As a special case, if `proxy` is `None`, then this method will actually +remove **all** proxies from the asset. ## `proxy` -The `Asset` that should be used as default proxy for `self` or -`None` if you want to use the currently set proxy. Note that an asset can proxy one and only -one other asset. +A new default proxy for `self` # Returns -`true` if `proxy` has been set on `self`, `false` otherwise. +`true` if `proxy` was successfully set as the default for +`self`. -Removes `proxy` from the list of known proxies for `self`. -If `proxy` was the current proxy for `self`, stop using it. +Removes the proxy from the available list of proxies for the asset. If +the given proxy is the default proxy of the list, then the next proxy +in the available list (see `AssetExt::list_proxies`) will become the +default. If there are no other proxies, then the asset will no longer +have a default `Asset:proxy`. ## `proxy` -The `Asset` to stop considering as a proxy for `self` +An existing proxy of `self` # Returns -`true` if `proxy` was a known proxy for `self`, `false` otherwise. +`true` if `proxy` was successfully removed from `self`'s proxy +list. + +The `Extractable` object type that can be extracted from the asset. + +The `Extractable` object type that can be extracted from the asset. + +The ID of the asset. This should be unique amongst all assets with +the same `Asset:extractable-type`. Depending on the associated +`Extractable` implementation, this id may convey some information +about the `gobject::Object` that should be extracted. Note that, as such, the +ID will have an expected format, and you can not choose this value +arbitrarily. By default, this will be set to the type name of the +`Asset:extractable-type`, but you should check the documentation +of the extractable type to see whether they differ from the +default behaviour. + +The ID of the asset. This should be unique amongst all assets with +the same `Asset:extractable-type`. Depending on the associated +`Extractable` implementation, this id may convey some information +about the `gobject::Object` that should be extracted. Note that, as such, the +ID will have an expected format, and you can not choose this value +arbitrarily. By default, this will be set to the type name of the +`Asset:extractable-type`, but you should check the documentation +of the extractable type to see whether they differ from the +default behaviour. + +The default proxy for this asset, or `None` if it has no proxy. A +proxy will act as a substitute for the original asset when the +original is requested (see `Asset::request`). + +Setting this property will not usually remove the existing proxy, but +will replace it as the default (see `AssetExt::set_proxy`). + +The default proxy for this asset, or `None` if it has no proxy. A +proxy will act as a substitute for the original asset when the +original is requested (see `Asset::request`). + +Setting this property will not usually remove the existing proxy, but +will replace it as the default (see `AssetExt::set_proxy`). + +The asset that this asset is a proxy for, or `None` if it is not a +proxy for another asset. + +Note that even if this asset is acting as a proxy for another asset, +but this asset is not the default `Asset:proxy`, then `proxy`-target +will *still* point to this other asset. So you should check the +`Asset:proxy` property of `target`-proxy before assuming it is the +current default proxy for the target. + +Note that the `gobject::Object::notify` for this property is emitted after +the `Asset:proxy` `gobject::Object::notify` for the corresponding (if any) +asset it is now the proxy of/no longer the proxy of. +A `BaseEffect` is some operation that applies an effect to the data +it receives. +## Time Effects + +Some operations will change the timing of the stream data they receive +in some way. In particular, the `gst::Element` that they wrap could alter +the times of the segment they receive in a `gst::EventType::Segment` event, +or the times of a seek they receive in a `gst::EventType::Seek` event. Such +operations would be considered time effects since they translate the +times they receive on their source to different times at their sink, +and vis versa. This introduces two sets of time coordinates for the +event: (internal) sink coordinates and (internal) source coordinates, +where segment times are translated from the sink coordinates to the +source coordinates, and seek times are translated from the source +coordinates to the sink coordinates. + +If you use such an effect in GES, you will need to inform GES of the +properties that control the timing with +`BaseEffectExt::register_time_property`, and the effect's timing +behaviour using `BaseEffectExt::set_time_translation_funcs`. + +Note that a time effect should not have its +`TrackElement:has-internal-source` set to `true`. + +In addition, note that GES only *fully* supports time effects whose +mapping from the source to sink coordinates (those applied to seeks) +obeys: + ++ Maps the time `0` to `0`. So initial time-shifting effects are + excluded. ++ Is monotonically increasing. So reversing effects, and effects that + jump backwards in the stream are excluded. ++ Can handle a reasonable `gst::ClockTime`, relative to the project. So + this would exclude a time effect with an extremely large speed-up + that would cause the converted `gst::ClockTime` seeks to overflow. ++ Is 'continuously reversible'. This essentially means that for every + time in the sink coordinates, we can, to 'good enough' accuracy, + calculate the corresponding time in the source coordinates. Moreover, + this should correspond to how segment times are translated from + sink to source. ++ Only depends on the registered time properties, rather than the + state of the `gst::Element` or the data it receives. This would exclude, + say, an effect that would speedup if there is more red in the image + it receives. + +Note that a constant-rate-change effect that is not extremely fast or +slow would satisfy these conditions. For such effects, you may wish to +use `EffectClass::register_rate_property`. # Implements -[`TrackElementExt`](trait.TrackElementExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html) +[`BaseEffectExt`](trait.BaseEffectExt.html), [`TrackElementExt`](trait.TrackElementExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html), [`TimelineElementExtManual`](prelude/trait.TimelineElementExtManual.html) + +Trait containing all `BaseEffect` methods. + +# Implementors + +[`BaseEffect`](struct.BaseEffect.html), [`Effect`](struct.Effect.html) + +Get whether the effect is considered a time effect or not. An effect +with registered time properties or set translation functions is +considered a time effect. + +Feature: `v1_18` + + +# Returns + +`true` if `self` is considered a time effect. + +Register a child property of the effect as a property that, when set, +can change the timing of its input data. The child property should be +specified as in `TimelineElementExt::lookup_child`. + +You should also set the corresponding time translation using +`BaseEffectExt::set_time_translation_funcs`. + +Note that `self` must not be part of a clip, nor can it have +`TrackElement:has-internal-source` set to `true`. + +Feature: `v1_18` + +## `child_property_name` +The name of the child property to register as +a time property + +# Returns + +`true` if the child property was found and newly registered. + +Set the time translation query functions for the time effect. If an +effect is a time effect, it will have two sets of coordinates: one +at its sink and one at its source. The given functions should be able +to translate between these two sets of coordinates. More specifically, +`source_to_sink_func` should *emulate* how the corresponding `gst::Element` +would translate the `gst::Segment` `time` field, and `sink_to_source_func` +should emulate how the corresponding `gst::Element` would translate the +seek query `start` and `stop` values, as used in `gst::ElementExt::seek`. As +such, `sink_to_source_func` should act as an approximate reverse of +`source_to_sink_func`. + +Note, these functions will be passed a table of time properties, as +registered in `BaseEffectExt::register_time_property`, and their +values. The functions should emulate what the translation *would* be +*if* the time properties were set to the given values. They should not +use the currently set values. + +Note that `self` must not be part of a clip, nor can it have +`TrackElement:has-internal-source` set to `true`. + +Feature: `v1_18` + +## `source_to_sink_func` +The function to use +for querying how a time is translated from the source coordinates to +the sink coordinates of `self` +## `sink_to_source_func` +The function to use +for querying how a time is translated from the sink coordinates to the +source coordinates of `self` +## `user_data` +Data to pass to both `source_to_sink_func` and +`sink_to_source_func` +## `destroy` +Method to call to destroy +`user_data`, or `None` + +# Returns + +`true` if the translation functions were set. -A `Clip` is a 'natural' object which controls one or more -`TrackElement`(s) in one or more `Track`(s). +`Clip`-s are the core objects of a `Layer`. Each clip may exist in +a single layer but may control several `TrackElement`-s that span +several `Track`-s. A clip will ensure that all its children share the +same `TimelineElement:start` and `TimelineElement:duration` in +their tracks, which will match the `TimelineElement:start` and +`TimelineElement:duration` of the clip itself. Therefore, changing +the timing of the clip will change the timing of the children, and a +change in the timing of a child will change the timing of the clip and +subsequently all its siblings. As such, a clip can be treated as a +singular object in its layer. -Keeps a reference to the `TrackElement`(s) it created and -sets/updates their properties. +For most uses of a `Timeline`, it is often sufficient to only +interact with `Clip`-s directly, which will take care of creating and +organising the elements of the timeline's tracks. + +## Core Children + +In more detail, clips will usually have some *core* `TrackElement` +children, which are created by the clip when it is added to a layer in +a timeline. The type and form of these core children will depend on the +clip's subclass. You can use `TrackElementExt::is_core` to determine +whether a track element is considered such a core track element. Note, +if a core track element is part of a clip, it will always be treated as +a core *child* of the clip. You can connect to the +`Container::child-added` signal to be notified of their creation. + +When a child is added to a clip, the timeline will select its tracks +using `Timeline::select-tracks-for-object`. Note that it may be the +case that the child will still have no set `TrackElement:track` +after this process. For example, if the timeline does not have a track +of the corresponding `Track:track-type`. A clip can safely contain +such children, which may have their track set later, although they will +play no functioning role in the timeline in the meantime. + +If a clip may create track elements with various +`TrackElement:track-type`(s), such as a `UriClip`, but you only +want it to create a subset of these types, you should set the +`Clip:supported-formats` of the clip to the subset of types. This +should be done *before* adding the clip to a layer. + +If a clip will produce several core elements of the same +`TrackElement:track-type`, you should connect to the timeline's +`Timeline::select-tracks-for-object` signal to coordinate which +tracks each element should land in. Note, no two core children within a +clip can share the same `Track`, so you should not select the same +track for two separate core children. Provided you stick to this rule, +it is still safe to select several tracks for the same core child, the +core child will be copied into the additional tracks. You can manually +add the child to more tracks later using `ClipExt::add_child_to_track`. +If you do not wish to use a core child, you can always select no track. + +The `TimelineElement:in-point` of the clip will control the +`TimelineElement:in-point` of its core children to be the same +value if their `TrackElement:has-internal-source` is set to `true`. + +The `TimelineElement:max-duration` of the clip is the minimum +`TimelineElement:max-duration` of its core children. If you set its +value to anything other than its current value, this will also set the +`TimelineElement:max-duration` of all its core children to the same +value if their `TrackElement:has-internal-source` is set to `true`. +As a special case, whilst a clip does not yet have any core children, +its `TimelineElement:max-duration` may be set to indicate what its +value will be once they are created. + +## Effects + +Some subclasses (`SourceClip` and `BaseEffectClip`) may also allow +their objects to have additional non-core `BaseEffect`-s elements as +children. These are additional effects that are applied to the output +data of the core elements. They can be added to the clip using +`ClipExt::add_top_effect`, which will take care of adding the effect to +the timeline's tracks. The new effect will be placed between the clip's +core track elements and its other effects. As such, the newly added +effect will be applied to any source data **before** the other existing +effects. You can change the ordering of effects using +`ClipExt::set_top_effect_index`. + +Tracks are selected for top effects in the same way as core children. +If you add a top effect to a clip before it is part of a timeline, and +later add the clip to a timeline, the track selection for the top +effects will occur just after the track selection for the core +children. If you add a top effect to a clip that is already part of a +timeline, the track selection will occur immediately. Since a top +effect must be applied on top of a core child, if you use +`Timeline::select-tracks-for-object`, you should ensure that the +added effects are destined for a `Track` that already contains a core +child. + +In addition, if the core child in the track is not +`TrackElement:active`, then neither can any of its effects be +`TrackElement:active`. Therefore, if a core child is made in-active, +all of the additional effects in the same track will also become +in-active. Similarly, if an effect is set to be active, then the core +child will also become active, but other effects will be left alone. +Finally, if an active effect is added to the track of an in-active core +child, it will become in-active as well. Note, in contrast, setting a +core child to be active, or an effect to be in-active will *not* change +the other children in the same track. + +### Time Effects + +Some effects also change the timing of their data (see `BaseEffect` +for what counts as a time effect). Note that a `BaseEffectClip` will +refuse time effects, but a `Source` will allow them. + +When added to a clip, time effects may adjust the timing of other +children in the same track. Similarly, when changing the order of +effects, making them (in)-active, setting their time property values +or removing time effects. These can cause the `Clip:duration-limit` +to change in value. However, if such an operation would ever cause the +`TimelineElement:duration` to shrink such that a clip's `Source` is +totally overlapped in the timeline, the operation would be prevented. +Note that the same can happen when adding non-time effects with a +finite `TimelineElement:max-duration`. + +Therefore, when working with time effects, you should -- more so than +usual -- not assume that setting the properties of the clip's children +will succeed. In particular, you should use +`TimelineElementExt::set_child_property_full` when setting the time +properties. + +If you wish to preserve the *internal* duration of a source in a clip +during these time effect operations, you can do something like the +following. + +```c +void +do_time_effect_change (GESClip * clip) +{ + GList *tmp, *children; + GESTrackElement *source; + GstClockTime source_outpoint; + GstClockTime new_end; + GError *error = NULL; + + // choose some active source in a track to preserve the internal + // duration of + source = ges_clip_get_track_element (clip, NULL, GES_TYPE_SOURCE); + + // note its current internal end time + source_outpoint = ges_clip_get_internal_time_from_timeline_time ( + clip, source, GES_TIMELINE_ELEMENT_END (clip), NULL); + + // handle invalid out-point + + // stop the children's control sources from clamping when their + // out-point changes with a change in the time effects + children = ges_container_get_children (GES_CONTAINER (clip), FALSE); + + for (tmp = children; tmp; tmp = tmp->next) + ges_track_element_set_auto_clamp_control_source (tmp->data, FALSE); + + // add time effect, or set their children properties, or move them around + ... + // user can make sure that if a time effect changes one source, we should + // also change the time effect for another source. E.g. if + // "GstVideorate::rate" is set to 2.0, we also set "GstPitch::rate" to + // 2.0 + + // Note the duration of the clip may have already changed if the + // duration-limit of the clip dropped below its current value + + new_end = ges_clip_get_timeline_time_from_internal_time ( + clip, source, source_outpoint, &error); + // handle error + + if (!ges_timeline_elemnet_edit_full (GES_TIMELINE_ELEMENT (clip), + -1, GES_EDIT_MODE_TRIM, GES_EDGE_END, new_end, &error)) + // handle error + + for (tmp = children; tmp; tmp = tmp->next) + ges_track_element_set_auto_clamp_control_source (tmp->data, TRUE); + + g_list_free_full (children, gst_object_unref); + gst_object_unref (source); +} +``` # Implements -[`ClipExt`](trait.ClipExt.html), [`GESContainerExt`](trait.GESContainerExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html) +[`ClipExt`](trait.ClipExt.html), [`GESContainerExt`](trait.GESContainerExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html), [`TimelineElementExtManual`](prelude/trait.TimelineElementExtManual.html) Trait containing all `Clip` methods. @@ -256,146 +693,464 @@ Trait containing all `Clip` methods. [`Clip`](struct.Clip.html) -Extracts a `TrackElement` from `asset` and adds it to the `self`. -Should only be called in order to add operations to a `Clip`, -ni other cases TrackElement are added automatically when adding the -`Clip`/`Asset` to a layer. - -Takes a reference on `track_element`. +Extracts a `TrackElement` from an asset and adds it to the clip. +This can be used to add effects that derive from the asset to the +clip, but this method is not intended to be used to create the core +elements of the clip. ## `asset` -a `Asset` with `GES_TYPE_TRACK_ELEMENT` as extractable_type +An asset with `GES_TYPE_TRACK_ELEMENT` as its +`Asset:extractable-type` # Returns -Created `TrackElement` or NULL -if an error happened +The newly created element, or +`None` if an error occurred. + +Adds the track element child of the clip to a specific track. + +If the given child is already in another track, this will create a copy +of the child, add it to the clip, and add this copy to the track. + +You should only call this whilst a clip is part of a `Timeline`, and +for tracks that are in the same timeline. + +This method is an alternative to using the +`Timeline::select-tracks-for-object` signal, but can be used to +complement it when, say, you wish to copy a clip's children from one +track into a new one. + +When the child is a core child, it must be added to a track that does +not already contain another core child of the same clip. If it is not a +core child (an additional effect), then it must be added to a track +that already contains one of the core children of the same clip. + +This method can also fail if the adding the track element to the track +would break a configuration rule of the corresponding `Timeline`, +such as causing three sources to overlap at a single time, or causing +a source to completely overlap another in the same track. +## `child` +A child of `self` +## `track` +The track to add `child` to + +# Returns + +The element that was added to `track`, either +`child` or a copy of child, or `None` if the element could not be added. + +Add a top effect to a clip at the given index. + +Unlike using `GESContainerExt::add`, this allows you to set the index +in advance. It will also check that no error occurred during the track +selection for the effect. + +Note, only subclasses of `ClipClass` that have +`GES_CLIP_CLASS_CAN_ADD_EFFECTS` set to `true` (such as `SourceClip` +and `BaseEffectClip`) can have additional top effects added. + +Note, if the effect is a time effect, this may be refused if the clip +would not be able to adapt itself once the effect is added. + +Feature: `v1_18` + +## `effect` +A top effect to add +## `index` +The index to add `effect` at, or -1 to add at the highest + +# Returns + +`true` if `effect` was successfully added to `self` at `index`. -Finds the `TrackElement` controlled by `self` that is used in `track`. You -may optionally specify a GType to further narrow search criteria. +Finds an element controlled by the clip. If `track` is given, +then only the track elements in `track` are searched for. If `type_` is +given, then this function searches for a track element of the given +`type_`. -Note: If many objects match, then the one with the highest priority will be -returned. +Note, if multiple track elements in the clip match the given criteria, +this will return the element amongst them with the highest +`TimelineElement:priority` (numerically, the smallest). See +`ClipExt::find_track_elements` if you wish to find all such elements. ## `track` -a `Track` or NULL +The track to search in, or `None` to search in +all tracks ## `type_` -a `glib::Type` indicating the type of track element you are looking -for or `G_TYPE_NONE` if you do not care about the track type. +The type of track element to search for, or `G_TYPE_NONE` to +match any type # Returns -The `TrackElement` used by `track`, -else `None`. Unref after usage +The element controlled by +`self`, in `track`, and of the given `type_`, or `None` if no such element +could be found. -Finds all the `TrackElement` controlled by `self` that is used in `track`. You -may optionally specify a GType to further narrow search criteria. +Finds the `TrackElement`-s controlled by the clip that match the +given criteria. If `track` is given as `None` and `track_type` is given as +`TrackType::Unknown`, then the search will match all elements in any +track, including those with no track, and of any +`TrackElement:track-type`. Otherwise, if `track` is not `None`, but +`track_type` is `TrackType::Unknown`, then only the track elements in +`track` are searched for. Otherwise, if `track_type` is not +`TrackType::Unknown`, but `track` is `None`, then only the track +elements whose `TrackElement:track-type` matches `track_type` are +searched for. Otherwise, when both are given, the track elements that +match **either** criteria are searched for. Therefore, if you wish to +only find elements in a specific track, you should give the track as +`track`, but you should not give the track's `Track:track-type` as +`track_type` because this would also select elements from other tracks +of the same type. + +You may also give `type_` to _further_ restrict the search to track +elements of the given `type_`. ## `track` -a `Track` or NULL +The track to search in, or `None` to search in +all tracks ## `track_type` -a `TrackType` indicating the type of tracks in which elements -should be searched. +The track-type of the track element to search for, or +`TrackType::Unknown` to match any track type ## `type_` -a `glib::Type` indicating the type of track element you are looking -for or `G_TYPE_NONE` if you do not care about the track type. +The type of track element to search for, or `G_TYPE_NONE` to +match any type # Returns -a `glib::List` of the -`TrackElement` contained in `self`. -The refcount of the objects will be increased. The user will have to -unref each `TrackElement` and free the `glib::List`. +A list of all +the `TrackElement`-s controlled by `self`, in `track` or of the given +`track_type`, and of the given `type_`. + +Gets the `Clip:duration-limit` of the clip. + +Feature: `v1_18` + + +# Returns + +The duration-limit of `self`. + +Convert the timeline time to an internal source time of the child. +This will take any time effects placed on the clip into account (see +`BaseEffect` for what time effects are supported, and how to +declare them in GES). + +When `timeline_time` is above the `TimelineElement:start` of `self`, +this will return the internal time at which the content that appears at +`timeline_time` in the output of the timeline is created in `child`. For +example, if `timeline_time` corresponds to the current seek position, +this would let you know which part of a media file is being read. + +This will be done assuming the clip has an indefinite end, so the +internal time may be beyond the current out-point of the child, or even +its `TimelineElement:max-duration`. + +If, instead, `timeline_time` is below the current +`TimelineElement:start` of `self`, this will return what you would +need to set the `TimelineElement:in-point` of `child` to if you set +the `TimelineElement:start` of `self` to `timeline_time` and wanted +to keep the content of `child` currently found at the current +`TimelineElement:start` of `self` at the same timeline position. If +this would be negative, the conversion fails. This is useful for +determining what `TimelineElement:in-point` would result from a +`EditMode::Trim` to `timeline_time`. + +Note that whilst a clip has no time effects, this second return is +equivalent to finding the internal time at which the content that +appears at `timeline_time` in the timeline can be found in `child` if it +had indefinite extent in both directions. However, with non-linear time +effects this second return will be more distinct. + +In either case, the returned time would be appropriate to use for the +`TimelineElement:in-point` or `TimelineElement:max-duration` of the +child. + +See `ClipExt::get_timeline_time_from_internal_time`, which performs the +reverse. + +Feature: `v1_18` + +## `child` +An `TrackElement:active` child of `self` with a +`TrackElement:track` +## `timeline_time` +A time in the timeline time coordinates + +# Returns + +The time in the internal coordinates of `child` corresponding +to `timeline_time`, or `GST_CLOCK_TIME_NONE` if the conversion could not +be performed. -Get the `Layer` to which this clip belongs. +Gets the `Clip:layer` of the clip. # Returns -The `Layer` where this `self` is being -used, or `None` if it is not used on any layer. The caller should unref it -usage. +The layer `self` is in, or `None` if +`self` is not in any layer. -Get the formats supported by `self`. +Gets the `Clip:supported-formats` of the clip. # Returns -The formats supported by `self`. +The `TrackType`-s supported by `self`. + +Convert the internal source time from the child to a timeline time. +This will take any time effects placed on the clip into account (see +`BaseEffect` for what time effects are supported, and how to +declare them in GES). + +When `internal_time` is above the `TimelineElement:in-point` of +`child`, this will return the timeline time at which the internal +content found at `internal_time` appears in the output of the timeline's +track. For example, this would let you know where in the timeline a +particular scene in a media file would appear. + +This will be done assuming the clip has an indefinite end, so the +timeline time may be beyond the end of the clip, or even breaking its +`Clip:duration-limit`. + +If, instead, `internal_time` is below the current +`TimelineElement:in-point` of `child`, this will return what you would +need to set the `TimelineElement:start` of `self` to if you set the +`TimelineElement:in-point` of `child` to `internal_time` and wanted to +keep the content of `child` currently found at the current +`TimelineElement:start` of `self` at the same timeline position. If +this would be negative, the conversion fails. This is useful for +determining what position to use in a `EditMode::Trim` if you wish +to trim to a specific point in the internal content, such as a +particular scene in a media file. + +Note that whilst a clip has no time effects, this second return is +equivalent to finding the timeline time at which the content of `child` +at `internal_time` would be found in the timeline if it had indefinite +extent in both directions. However, with non-linear time effects this +second return will be more distinct. + +In either case, the returned time would be appropriate to use in +`TimelineElementExt::edit` for `EditMode::Trim`, and similar, if +you wish to use a particular internal point as a reference. For +example, you could choose to end a clip at a certain internal +'out-point', similar to the `TimelineElement:in-point`, by +translating the desired end time into the timeline coordinates, and +using this position to trim the end of a clip. + +See `ClipExt::get_internal_time_from_timeline_time`, which performs the +reverse, or `ClipExt::get_timeline_time_from_source_frame` which does +the same conversion, but using frame numbers. +## `child` +An `TrackElement:active` child of `self` with a +`TrackElement:track` +## `internal_time` +A time in the internal time coordinates of `child` + +# Returns + +The time in the timeline coordinates corresponding to +`internal_time`, or `GST_CLOCK_TIME_NONE` if the conversion could not be +performed. + +Convert the source frame number to a timeline time. This acts the same +as `ClipExt::get_timeline_time_from_internal_time` using the core +children of the clip and using the frame number to specify the internal +position, rather than a timestamp. + +The returned timeline time can be used to seek or edit to a specific +frame. + +Note that you can get the frame timestamp of a particular clip asset +with `ClipAsset::get_frame_time`. + +Feature: `v1_18` + +## `frame_number` +The frame number to get the corresponding timestamp of +in the timeline coordinates + +# Returns + +The timestamp corresponding to `frame_number` in the core +children of `self`, in the timeline coordinates, or `GST_CLOCK_TIME_NONE` +if the conversion could not be performed. -Gets the index position of an effect. +Gets the internal index of an effect in the clip. The index of effects +in a clip will run from 0 to n-1, where n is the total number of +effects. If two effects share the same `TrackElement:track`, the +effect with the numerically lower index will be applied to the source +data **after** the other effect, i.e. output data will always flow from +a higher index effect to a lower index effect. ## `effect` -The `BaseEffect` we want to get the top index from +The effect we want to get the index of # Returns -The top index of the effect, -1 if something went wrong. +The index of `effect` in `self`, or -1 if something went wrong. -Get effects applied on `self` +Gets the `BaseEffect`-s that have been added to the clip. The +returned list is ordered by their internal index in the clip. See +`ClipExt::get_top_effect_index`. # Returns -a `glib::List` of the -`BaseEffect` that are applied on `self` order by ascendant priorities. -The refcount of the objects will be increased. The user will have to -unref each `BaseEffect` and free the `glib::List`. +A list of all +`BaseEffect`-s that have been added to `self`. -Moves `self` to `layer`. If `self` is not in any layer, it adds it to -`layer`, else, it removes it from its current layer, and adds it to `layer`. +See `ClipExt::move_to_layer_full`, which also gives an error. ## `layer` -the new `Layer` +The new layer # Returns -`true` if `self` could be moved `false` otherwize - -Sets the formats supported by the file. -## `supportedformats` -the `TrackType` defining formats supported by `self` - -This is a convenience method that lets you set the index of a top effect. +`true` if `self` was successfully moved to `layer`. + +Moves a clip to a new layer. If the clip already exists in a layer, it +is first removed from its current layer before being added to the new +layer. + +Feature: `v1_18` + +## `layer` +The new layer + +# Returns + +`true` if `self` was successfully moved to `layer`. + +Remove a top effect from the clip. + +Note, if the effect is a time effect, this may be refused if the clip +would not be able to adapt itself once the effect is removed. + +Feature: `v1_18` + ## `effect` -The `BaseEffect` to move +The top effect to remove + +# Returns + +`true` if `effect` was successfully added to `self` at `index`. + +Sets the `Clip:supported-formats` of the clip. This should normally +only be called by subclasses, which should be responsible for updating +its value, rather than the user. +## `supportedformats` +The `TrackType`-s supported by `self` + +See `ClipExt::set_top_effect_index_full`, which also gives an error. +## `effect` +An effect within `self` to move ## `newindex` -the new index at which to move the `effect` inside this -`Clip` +The index for `effect` in `self` # Returns -`true` if `effect` was successfuly moved, `false` otherwise. +`true` if `effect` was successfully moved to `newindex`. + +Set the index of an effect within the clip. See +`ClipExt::get_top_effect_index`. The new index must be an existing +index of the clip. The effect is moved to the new index, and the other +effects may be shifted in index accordingly to otherwise maintain the +ordering. + +Feature: `v1_18` + +## `effect` +An effect within `self` to move +## `newindex` +The index for `effect` in `self` + +# Returns + +`true` if `effect` was successfully moved to `newindex`. -The function modifies `self`, and creates another `Clip` so we have two -clips at the end, splitted at the time specified by `position`, as a position -in the timeline (not in the clip to be split). For example, if -ges_clip_split is called on a 4-second clip playing from 0:01.00 until -0:05.00, with a split position of 0:02.00, this will result in one clip of 1 -second and one clip of 3 seconds, not in two clips of 2 seconds. - -The newly created clip will be added to the same layer as `self` is in. This -implies that `self` must be in a `Layer` for the operation to be possible. - -This method supports clips playing at a different tempo than one second per -second. For example, splitting a clip with a `Effect` 'pitch tempo=1.5' -four seconds after it starts, will set the inpoint of the new clip to six -seconds after that of the clip to split. For this, the rate-changing -property must be registered using `EffectClass::register_rate_property`; -for the 'pitch' plugin, this is already done. +See `ClipExt::split_full`, which also gives an error. ## `position` -a `gst::ClockTime` representing the timeline position at which to split +The timeline position at which to perform the split # Returns -The newly created `Clip` resulting -from the splitting or `None` if the clip can't be split. +The newly created clip resulting +from the splitting `self`, or `None` if `self` can't be split. + +Splits a clip at the given timeline position into two clips. The clip +must already have a `Clip:layer`. + +The original clip's `TimelineElement:duration` is reduced such that +its end point matches the split position. Then a new clip is created in +the same layer, whose `TimelineElement:start` matches the split +position and `TimelineElement:duration` will be set such that its end +point matches the old end point of the original clip. Thus, the two +clips together will occupy the same positions in the timeline as the +original clip did. + +The children of the new clip will be new copies of the original clip's +children, so it will share the same sources and use the same +operations. + +The new clip will also have its `TimelineElement:in-point` set so +that any internal data will appear in the timeline at the same time. +Thus, when the timeline is played, the playback of data should +appear the same. This may be complicated by any additional +`Effect`-s that have been placed on the original clip that depend on +the playback time or change the data consumption rate of sources. This +method will attempt to translate these effects such that the playback +appears the same. In such complex situations, you may get a better +result if you place the clip in a separate sub `Project`, which only +contains this clip (and its effects), and in the original layer +create two neighbouring `UriClip`-s that reference this sub-project, +but at a different `TimelineElement:in-point`. + +Feature: `v1_18` + +## `position` +The timeline position at which to perform the split, between +the start and end of the clip + +# Returns + +The newly created clip resulting +from the splitting `self`, or `None` if `self` can't be split. + +The maximum `TimelineElement:duration` that can be *currently* set +for the clip, taking into account the `TimelineElement:in-point`, +`TimelineElement:max-duration`, `TrackElement:active`, and +`TrackElement:track` properties of its children, as well as any +time effects. If there is no limit, this will be set to +`GST_CLOCK_TIME_NONE`. + +Note that whilst a clip has no children in any tracks, the limit will +be unknown, and similarly set to `GST_CLOCK_TIME_NONE`. + +If the duration-limit would ever go below the current +`TimelineElement:duration` of the clip due to a change in the above +variables, its `TimelineElement:duration` will be set to the new +limit. -The GESLayer where this clip is being used. If you want to connect to its -notify signal you should connect to it with g_signal_connect_after as the -signal emission can be stop in the first fase. +The layer this clip lies in. + +If you want to connect to this property's `gobject::Object::notify` signal, +you should connect to it with `g_signal_connect_after` since the +signal emission may be stopped internally. -The formats supported by the clip. +The `TrackType`-s that the clip supports, which it can create +`TrackElement`-s for. Note that this can be a combination of +`TrackType` flags to indicate support for several +`TrackElement:track-type` elements. -The formats supported by the clip. +The `TrackType`-s that the clip supports, which it can create +`TrackElement`-s for. Note that this can be a combination of +`TrackType` flags to indicate support for several +`TrackElement:track-type` elements. -The `Container` base class. +A `Container` is a timeline element that controls other +`TimelineElement`-s, which are its children. In particular, it is +responsible for maintaining the relative `TimelineElement:start` and +`TimelineElement:duration` times of its children. Therefore, if a +container is temporally adjusted or moved to a new layer, it may +accordingly adjust and move its children. Similarly, a change in one of +its children may prompt the parent to correspondingly change its +siblings. # Implements -[`GESContainerExt`](trait.GESContainerExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html) +[`GESContainerExt`](trait.GESContainerExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html), [`TimelineElementExtManual`](prelude/trait.TimelineElementExtManual.html) Trait containing all `Container` methods. @@ -403,140 +1158,292 @@ Trait containing all `Container` methods. [`Clip`](struct.Clip.html), [`Container`](struct.Container.html), [`Group`](struct.Group.html) -Groups the `Container`-s provided in `containers`. It creates a subclass -of `Container`, depending on the containers provided in `containers`. -Basically, if all the containers in `containers` should be contained in a same -clip (all the `TrackElement` they contain have the exact same -start/inpoint/duration and are in the same layer), it will create a `Clip` -otherwise a `Group` will be created +Groups the containers into a single container by merging them. The +containers must all belong to the same `TimelineElement:timeline`. + +If the elements are all `Clip`-s then this method will attempt to +combine them all into a single `Clip`. This should succeed if they: +share the same `TimelineElement:start`, `TimelineElement:duration` +and `TimelineElement:in-point`; exist in the same layer; and all of +the sources share the same `Asset`. If this fails, or one of the +elements is not a `Clip`, this method will try to create a `Group` +instead. ## `containers` -The -`Container` to group, they must all be in a same `Timeline` + +The `Container`-s to group # Returns -The `Container` (subclass) resulting of the -grouping +The container created by merging +`containers`, or `None` if they could not be merged into a single +container. -Add the `TimelineElement` to the container. +Adds a timeline element to the container. The element will now be a +child of the container (and the container will be the +`TimelineElement:parent` of the added element), which means that it +is now controlled by the container. This may change the properties of +the child or the container, depending on the subclass. + +Additionally, the children properties of the newly added element will +be shared with the container, meaning they can also be read and set +using `TimelineElementExt::get_child_property` and +`TimelineElementExt::set_child_property` on the container. ## `child` -the `TimelineElement` +The element to add as a child # Returns -`true` on success, `false` on failure. +`true` if `child` was successfully added to `self`. -Edit `self` in the different exisiting `EditMode` modes. In the case of -slide, and roll, you need to specify a `Edge` +Edits the container within its timeline. + +# Deprecated since 1.18 + +use `TimelineElementExt::edit` instead. ## `layers` -The layers you want the edit to - happen in, `None` means that the edition is done in all the - `GESLayers` contained in the current timeline. +A whitelist of layers +where the edit can be performed, `None` allows all layers in the +timeline ## `new_layer_priority` -The priority of the layer `self` should land in. - If the layer you're trying to move the container to doesn't exist, it will - be created automatically. -1 means no move. +The priority/index of the layer `self` should +be moved to. -1 means no move ## `mode` -The `EditMode` in which the editition will happen. +The edit mode ## `edge` -The `Edge` the edit should happen on. +The edge of `self` where the edit should occur ## `position` -The position at which to edit `self` (in nanosecond) +The edit position: a new location for the edge of `self` +(in nanoseconds) # Returns -`true` if the container as been edited properly, `false` if an error -occured +`true` if the edit of `self` completed, `false` on failure. -Get the list of `TimelineElement` contained in `self` -The user is responsible for unreffing the contained objects -and freeing the list. +Get the list of timeline elements contained in the container. If +`recursive` is `true`, and the container contains other containers as +children, then their children will be added to the list, in addition to +themselves, and so on. ## `recursive` Whether to recursively get children in `self` # Returns The list of -timeline element contained in `self`. +`TimelineElement`-s contained in `self`. -Release the `child` from the control of `self`. +Removes a timeline element from the container. The element will no +longer be controlled by the container. ## `child` -the `TimelineElement` to release +The child to remove # Returns -`true` if the `child` was properly released, else `false`. +`true` if `child` was successfully removed from `self`. -Ungroups the `TimelineElement` contained in this GESContainer, -creating new `Container` containing those `TimelineElement` -apropriately. +Ungroups the container by splitting it into several containers +containing various children of the original. The rules for how the +container splits depends on the subclass. A `Group` will simply split +into its children. A `Clip` will split into one `Clip` per +`TrackType` it overlaps with (so an audio-video clip will split into +an audio clip and a video clip), where each clip contains all the +`TrackElement`-s from the original clip with a matching +`TrackElement:track-type`. + +If `recursive` is `true`, and the container contains other containers as +children, then they will also be ungrouped, and so on. ## `recursive` -Wether to recursively ungroup `self` +Whether to recursively ungroup `self` # Returns The list of -`Container` resulting from the ungrouping operation -The user is responsible for unreffing the contained objects -and freeing the list. +new `Container`-s created from the splitting of `self`. -Will be emitted after a child was added to `container`. -Usually you should connect with `g_signal_connect_after` -as in the first emission stage, the signal emission might -get stopped internally. +Will be emitted after a child is added to the container. Usually, +you should connect with `g_signal_connect_after` since the signal +may be stopped internally. ## `element` -the `TimelineElement` that was added. +The child that was added -Will be emitted after a child was removed from `container`. +Will be emitted after a child is removed from the container. ## `element` -the `TimelineElement` that was removed. +The child that was removed -The span of priorities which this container occupies. +The span of the container's children's `TimelineElement:priority` +values, which is the number of integers that lie between (inclusive) +the minimum and maximum priorities found amongst the container's +children (maximum - minimum + 1). The edges of an object contain in a `Timeline` or `Track` - + Represents the start of an object. - + Represents the end of an object. - -Represent the fact we are not workin with any edge of an + +Represent the fact we are not working with any edge of an object. -You can also find more explanation about the behaviour of those modes at: - trim, ripple and roll`` -and clip management``. - -The object is edited the normal way (default). - -The objects are edited in ripple mode. - The Ripple mode allows you to modify the beginning/end of a clip - and move the neighbours accordingly. This will change the overall - timeline duration. In the case of ripple end, the duration of the - clip being rippled can't be superior to its max_duration - inpoint - otherwise the action won't be executed. - -The object is edited in roll mode. - The Roll mode allows you to modify the position of an editing point - between two clips without modifying the inpoint of the first clip - nor the out-point of the second clip. This will not change the - overall timeline duration. - -The object is edited in trim mode. - The Trim mode allows you to modify the in-point/duration of a clip - without modifying its position in the timeline. - -The object is edited in slide mode. - The Slide mode allows you to modify the position of a clip in a - timeline without modifying its duration or its in-point, but will - modify the duration of the previous clip and in-point of the - following clip so does not modify the overall timeline duration. - (not implemented yet) - +When a single timeline element is edited within its timeline at some +position, using `TimelineElementExt::edit`, depending on the edit +mode, its `TimelineElement:start`, `TimelineElement:duration` or +`TimelineElement:in-point` will be adjusted accordingly. In addition, +any clips may change `Clip:layer`. +Each edit can be broken down into a combination of three basic edits: + ++ MOVE: This moves the start of the element to the edit position. ++ START-TRIM: This cuts or grows the start of the element, whilst + maintaining the time at which its internal content appears in the + timeline data output. If the element is made shorter, the data that + appeared at the edit position will still appear in the timeline at + the same time. If the element is made longer, the data that appeared + at the previous start of the element will still appear in the + timeline at the same time. ++ END-TRIM: Similar to START-TRIM, but the end of the element is cut or + grown. + +In particular, when editing a `Clip`: + ++ MOVE: This will set the `TimelineElement:start` of the clip to the + edit position. ++ START-TRIM: This will set the `TimelineElement:start` of the clip + to the edit position. To keep the end time the same, the + `TimelineElement:duration` of the clip will be adjusted in the + opposite direction. In addition, the `TimelineElement:in-point` of + the clip will be shifted such that the content that appeared at the + new or previous start time, whichever is latest, still appears at the + same timeline time. For example, if a frame appeared at the start of + the clip, and the start of the clip is reduced, the in-point of the + clip will also reduce such that the frame will appear later within + the clip, but at the same timeline position. ++ END-TRIM: This will set the `TimelineElement:duration` of the clip + such that its end time will match the edit position. + +When editing a `Group`: + ++ MOVE: This will set the `Group:start` of the clip to the edit + position by shifting all of its children by the same amount. So each + child will maintain their relative positions. ++ START-TRIM: If the group is made shorter, this will START-TRIM any + clips under the group that start after the edit position to the same + edit position. If the group is made longer, this will START-TRIM any + clip under the group whose start matches the start of the group to + the same edit position. ++ END-TRIM: If the group is made shorter, this will END-TRIM any clips + under the group that end after the edit position to the same edit + position. If the group is made longer, this will END-TRIM any clip + under the group whose end matches the end of the group to the same + edit position. + +When editing a `TrackElement`, if it has a `Clip` parent, this +will be edited instead. Otherwise it is edited in the same way as a +`Clip`. + +The layer priority of a `Group` is the lowest layer priority of any +`Clip` underneath it. When a group is edited to a new layer +priority, it will shift all clips underneath it by the same amount, +such that their relative layers stay the same. + +If the `Timeline` has a `Timeline:snapping-distance`, then snapping +may occur for some of the edges of the **main** edited element: + ++ MOVE: The start or end edge of *any* `Source` under the element may + be snapped. ++ START-TRIM: The start edge of a `Source` whose start edge touches + the start edge of the element may snap. ++ END-TRIM: The end edge of a `Source` whose end edge touches the end + edge of the element may snap. + +These edges may snap with either the start or end edge of *any* other +`Source` in the timeline that is not also being moved by the element, +including those in different layers, if they are within the +`Timeline:snapping-distance`. During an edit, only up to one snap can +occur. This will shift the edit position such that the snapped edges +will touch once the edit has completed. + +Note that snapping can cause an edit to fail where it would have +otherwise succeeded because it may push the edit position such that the +edit would result in an unsupported timeline configuration. Similarly, +snapping can cause an edit to succeed where it would have otherwise +failed. + +For example, in `EditMode::Ripple` acting on `Edge::None`, the +main element is the MOVED toplevel of the edited element. Any source +under the main MOVED toplevel may have its start or end edge snapped. +Note, these sources cannot snap with each other. The edit may also +push other elements, but any sources under these elements cannot snap, +nor can they be snapped with. If a snap does occur, the MOVE of the +toplevel *and* all other elements pushed by the ripple will be shifted +by the same amount such that the snapped edges will touch. + +You can also find more explanation about the behaviour of those modes at: +[trim, ripple and roll](http://pitivi.org/manual/trimming.html) +and [clip management](http://pitivi.org/manual/usingclips.html). + +The element is edited the normal way (default). + If acting on the element as a whole (`Edge::None`), this will MOVE + the element by MOVING its toplevel. When acting on the start of the + element (`Edge::Start`), this will only MOVE the element, but not + its toplevel parent. This can allow you to move a `Clip` or + `Group` to a new start time or layer within its container group, + without effecting other members of the group. When acting on the end + of the element (`Edge::End`), this will END-TRIM the element, + leaving its toplevel unchanged. + +The element is edited in ripple mode: moving + itself as well as later elements, keeping their relative times. This + edits the element the same as `EditMode::Normal`. In addition, if + acting on the element as a whole, or the start of the element, any + toplevel element in the same timeline (including different layers) + whose start time is later than the *current* start time of the MOVED + element will also be MOVED by the same shift as the edited element. + If acting on the end of the element, any toplevel element whose start + time is later than the *current* end time of the edited element will + also be MOVED by the same shift as the change in the end of the + edited element. These additional elements will also be shifted by + the same shift in layers as the edited element. + +The element is edited in roll mode: swapping its + content for its neighbour's, or vis versa, in the timeline output. + This edits the element the same as `EditMode::Trim`. In addition, + any neighbours are also TRIMMED at their opposite edge to the same + timeline position. When acting on the start of the element, a + neighbour is any earlier element in the timeline whose end time + matches the *current* start time of the edited element. When acting on + the end of the element, a neighbour is any later element in the + timeline whose start time matches the *current* start time of the + edited element. In addition, a neighbour have a `Source` at its + end/start edge that shares a track with a `Source` at the start/end + edge of the edited element. Basically, a neighbour is an element that + can be extended, or cut, to have its content replace, or be replaced + by, the content of the edited element. Acting on the element as a + whole (`Edge::None`) is not defined. The element can not shift + layers under this mode. + +The element is edited in trim mode. When acting + on the start of the element, this will START-TRIM it. When acting on + the end of the element, this will END-TRIM it. Acting on the element + as a whole (`Edge::None`) is not defined. + +The element is edited in slide mode (not yet + implemented): moving the element replacing or consuming content on + each end. When acting on the element as a whole, this will MOVE the + element, and TRIM any neighbours on either side. A neighbour is + defined in the same way as in `EditMode::Roll`, but they may be on + either side of the edited elements. Elements at the end with be + START-TRIMMED to the new end position of the edited element. Elements + at the start will be END-TRIMMED to the new start position of the + edited element. Acting on the start or end of the element + (`Edge::Start` and `Edge::End`) is not defined. The element can + not shift layers under this mode. + +Currently we only support effects with 1 sinkpad and 1 sourcepad +with the exception of `gesaudiomixer` and `gescompositor` which +can be used as effects. # Implements -[`EffectExt`](trait.EffectExt.html), [`BaseEffectExt`](trait.BaseEffectExt.html), [`TrackElementExt`](trait.TrackElementExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html) +[`EffectExt`](trait.EffectExt.html), [`BaseEffectExt`](trait.BaseEffectExt.html), [`TrackElementExt`](trait.TrackElementExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html), [`TimelineElementExtManual`](prelude/trait.TimelineElementExtManual.html) Trait containing all `Effect` methods. @@ -568,7 +1475,22 @@ pipeline description. Example: "videobalance saturation=1.5 hue=+0.5" -FIXME: Long description needed +A `gobject::Object` that implements the `Extractable` interface can be +extracted from a `Asset` using `AssetExt::extract`. + +Each extractable type will have its own way of interpreting the +`Asset:id` of an asset (or, if it is associated with a specific +subclass of `Asset`, the asset subclass may handle the +interpretation of the `Asset:id`). By default, the requested asset +`Asset:id` will be ignored by a `Extractable` and will be set to +the type name of the extractable instead. Also by default, when the +requested asset is extracted, the returned object will simply be a +newly created default object of that extractable type. You should check +the documentation for each extractable type to see if they differ from +the default. + +After the object is extracted, it will have a reference to the asset it +came from, which you can retrieve using `Extractable::get_asset`. # Implements @@ -580,37 +1502,82 @@ Trait containing all `Extractable` methods. [`BaseEffect`](struct.BaseEffect.html), [`Clip`](struct.Clip.html), [`Container`](struct.Container.html), [`Effect`](struct.Effect.html), [`Extractable`](struct.Extractable.html), [`Group`](struct.Group.html), [`Layer`](struct.Layer.html), [`TimelineElement`](struct.TimelineElement.html), [`Timeline`](struct.Timeline.html), [`TrackElement`](struct.TrackElement.html), [`UriClip`](struct.UriClip.html) -Method for getting an asset from a `Extractable` +Get the asset that has been set on the extractable object. # Returns -The `Asset` or `None` if none has -been set +The asset set on `self`, or `None` +if no asset has been set. +Gets the `Asset:id` of some associated asset. It may be the case +that the object has no set asset, or even that such an asset does not +yet exist in the GES cache. Instead, this will return the asset +`Asset:id` that is _compatible_ with the current state of the object, +as determined by the `Extractable` implementer. If it was indeed +extracted from an asset, this should return the same as its +corresponding asset `Asset:id`. # Returns -The `id` of the associated `Asset`, free with `g_free` +The `Asset:id` of some associated `Asset` +that is compatible with `self`'s current state. -Method to set the asset which instantiated the specified object +Sets the asset for this extractable object. + +When an object is extracted from an asset using `AssetExt::extract` its +asset will be automatically set. Note that many classes that implement +`Extractable` will automatically create their objects using assets +when you call their `new` methods. However, you can use this method to +associate an object with a compatible asset if it was created by other +means and does not yet have an asset. Or, for some implementations of +`Extractable`, you can use this to change the asset of the given +extractable object, which will lead to a change in its state to +match the new asset `Asset:id`. ## `asset` -The `Asset` to set +The asset to set # Returns -`true` if `asset` could be set `false` otherwize +`true` if `asset` could be successfully set on `self`. -A `Group` is an object which controls one or more -`GESClips` in one or more `Layer`(s). +A `Group` controls one or more `Container`-s (usually `Clip`-s, +but it can also control other `Group`-s). Its children must share +the same `Timeline`, but can otherwise lie in separate `Layer`-s +and have different timings. -To instanciate a group, you should use the ges_container_group method, -this will be responsible for deciding what subclass of `Container` -should be instaciated to group the various `TimelineElement` passed -in parametter. +To initialise a group, you may want to use `Container::group`, +and similarly use `GESContainerExt::ungroup` to dispose of it. + +A group will maintain the relative `TimelineElement:start` times of +its children, as well as their relative layer `Layer:priority`. +Therefore, if one of its children has its `TimelineElement:start` +set, all other children will have their `TimelineElement:start` +shifted by the same amount. Similarly, if one of its children moves to +a new layer, the other children will also change layers to maintain the +difference in their layer priorities. For example, if a child moves +from a layer with `Layer:priority` 1 to a layer with priority 3, then +another child that was in a layer with priority 0 will move to the +layer with priority 2. + +The `Group:start` of a group refers to the earliest start +time of its children. If the group's `Group:start` is set, all the +children will be shifted equally such that the earliest start time +will match the set value. The `Group:duration` of a group is the +difference between the earliest start time and latest end time of its +children. If the group's `Group:duration` is increased, the children +whose end time matches the end of the group will be extended +accordingly. If it is decreased, then any child whose end time exceeds +the new end time will also have their duration decreased accordingly. + +A group may span several layers, but for methods such as +`TimelineElementExt::get_layer_priority` and +`TimelineElementExt::edit` a group is considered to have a layer +priority that is the highest `Layer:priority` (numerically, the +smallest) of all the layers it spans. # Implements -[`GroupExt`](trait.GroupExt.html), [`GESContainerExt`](trait.GESContainerExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html) +[`GroupExt`](trait.GroupExt.html), [`GESContainerExt`](trait.GESContainerExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html), [`TimelineElementExtManual`](prelude/trait.TimelineElementExtManual.html) Trait containing all `Group` methods. @@ -618,42 +1585,72 @@ Trait containing all `Group` methods. [`Group`](struct.Group.html) -Created a new empty `Group`, if you want to group several container -together, it is recommanded to use the `Container::group` method so the -proper subclass is selected. +Created a new empty group. You may wish to use +`Container::group` instead, which can return a different +`Container` subclass if possible. # Returns The new empty group. -The duration (in nanoseconds) which will be used in the container +An overwrite of the `TimelineElement:duration` property. For a +`Group`, this is the difference between the earliest +`TimelineElement:start` time and the latest end time (given by +`TimelineElement:start` + `TimelineElement:duration`) amongst +its children. -The duration (in nanoseconds) which will be used in the container +An overwrite of the `TimelineElement:duration` property. For a +`Group`, this is the difference between the earliest +`TimelineElement:start` time and the latest end time (given by +`TimelineElement:start` + `TimelineElement:duration`) amongst +its children. -The in-point at which this `Group` will start outputting data -from its contents (in nanoseconds). - -Ex : an in-point of 5 seconds means that the first outputted buffer will -be the one located 5 seconds in the controlled resource. +An overwrite of the `TimelineElement:in-point` property. This has +no meaning for a group and should not be set. -The in-point at which this `Group` will start outputting data -from its contents (in nanoseconds). - -Ex : an in-point of 5 seconds means that the first outputted buffer will -be the one located 5 seconds in the controlled resource. +An overwrite of the `TimelineElement:in-point` property. This has +no meaning for a group and should not be set. -The maximum duration (in nanoseconds) of the `Group`. +An overwrite of the `TimelineElement:max-duration` property. This +has no meaning for a group and should not be set. -The maximum duration (in nanoseconds) of the `Group`. +An overwrite of the `TimelineElement:max-duration` property. This +has no meaning for a group and should not be set. + +An overwrite of the `TimelineElement:priority` property. +Setting `TimelineElement` priorities is deprecated as all priority +management is now done by GES itself. + +An overwrite of the `TimelineElement:priority` property. +Setting `TimelineElement` priorities is deprecated as all priority +management is now done by GES itself. -The position of the object in its container (in nanoseconds). +An overwrite of the `TimelineElement:start` property. For a +`Group`, this is the earliest `TimelineElement:start` time +amongst its children. -The position of the object in its container (in nanoseconds). +An overwrite of the `TimelineElement:start` property. For a +`Group`, this is the earliest `TimelineElement:start` time +amongst its children. -Responsible for the ordering of the various contained Clip(s). A -timeline layer has a "priority" property, which is used to manage the -priorities of individual Clips. Two layers should not have the -same priority within a given timeline. +`Layer`-s are responsible for collecting and ordering `Clip`-s. + +A layer within a timeline will have an associated priority, +corresponding to their index within the timeline. A layer with the +index/priority 0 will have the highest priority and the layer with the +largest index will have the lowest priority (the order of priorities, +in this sense, is the _reverse_ of the numerical ordering of the +indices). `TimelineExt::move_layer` should be used if you wish to +change how layers are prioritised in a timeline. + +Layers with higher priorities will have their content priorities +over content from lower priority layers, similar to how layers are +used in image editing. For example, if two separate layers both +display video content, then the layer with the higher priority will +have its images shown first. The other layer will only have its image +shown if the higher priority layer has no content at the given +playtime, or is transparent in some way. Audio content in separate +layers will simply play in addition. # Implements @@ -665,120 +1662,189 @@ Trait containing all `Layer` methods. [`Layer`](struct.Layer.html) -Creates a new `Layer`. +Creates a new layer. # Returns -A new `Layer` +A new layer. -Creates Clip from asset, adds it to layer and -returns a reference to it. +See `LayerExt::add_asset_full`, which also gives an error. ## `asset` -The asset to add to +The asset to extract the new clip from ## `start` -The start value to set on the new `Clip`, -if `start` == GST_CLOCK_TIME_NONE, it will be set to -the current duration of `self` +The `TimelineElement:start` value to set on the new clip +If `start == #GST_CLOCK_TIME_NONE`, it will be added to the end +of `self`, i.e. it will be set to `self`'s duration ## `inpoint` -The inpoint value to set on the new `Clip` +The `TimelineElement:in-point` value to set on the new +clip ## `duration` -The duration value to set on the new `Clip` +The `TimelineElement:duration` value to set on the new +clip ## `track_types` -The `TrackType` to set on the the new `Clip` +The `Clip:supported-formats` to set on the the new +clip, or `TrackType::Unknown` to use the default # Returns -Created `Clip` - -Adds the given clip to the layer. Sets the clip's parent, and thus -takes ownership of the clip. +The newly created clip. + +Extracts a new clip from an asset and adds it to the layer with +the given properties. -An clip can only be added to one layer. +Feature: `v1_18` -Calling this method will construct and properly set all the media related -elements on `clip`. If you need to know when those objects (actually `TrackElement`) -are constructed, you should connect to the container::child-added signal which -is emited right after those elements are ready to be used. -## `clip` -the `Clip` to add. - -# Returns - -`true` if the clip was properly added to the layer, or `false` -if the `self` refuses to add the clip. - -Gets whether transitions are automatically added when objects -overlap or not. - -# Returns - -`true` if transitions are automatically added, else `false`. - -Get the clips this layer contains. - -# Returns - -a `glib::List` of -clips. The user is responsible for -unreffing the contained objects and freeing the list. - -Gets the clips which appear between `start` and `end` on `self`. +## `asset` +The asset to extract the new clip from ## `start` -start of the interval -## `end` -end of the interval +The `TimelineElement:start` value to set on the new clip +If `start == #GST_CLOCK_TIME_NONE`, it will be added to the end +of `self`, i.e. it will be set to `self`'s duration +## `inpoint` +The `TimelineElement:in-point` value to set on the new +clip +## `duration` +The `TimelineElement:duration` value to set on the new +clip +## `track_types` +The `Clip:supported-formats` to set on the the new +clip, or `TrackType::Unknown` to use the default # Returns -a `glib::List` of clips intersecting [`start`, `end`) interval on `self`. - -Lets you retrieve the duration of the layer, which means -the end time of the last clip inside it - -# Returns - -The duration of a layer - -Get the priority of `self` within the timeline. - -# Returns - -The priority of the `self` within the timeline. - -Get the `Timeline` in which `Layer` currently is. - -# Returns - -the `Timeline` in which `Layer` -currently is or `None` if not in any timeline yet. - -Convenience method to check if `self` is empty (doesn't contain any clip), -or not. - -# Returns - -`true` if `self` is empty, `false` if it already contains at least -one `Clip` - -Removes the given `clip` from the `self` and unparents it. -Unparenting it means the reference owned by `self` on the `clip` will be -removed. If you wish to use the `clip` after this function, make sure you -call `gst::ObjectExt::ref` before removing it from the `self`. +The newly created clip. + +See `LayerExt::add_clip_full`, which also gives an error. ## `clip` -the `Clip` to remove +The clip to add # Returns -`true` if the clip could be removed, `false` if the layer does -not want to remove the clip. +`true` if `clip` was properly added to `self`, or `false` +if `self` refused to add `clip`. + +Adds the given clip to the layer. If the method succeeds, the layer +will take ownership of the clip. + +This method will fail and return `false` if `clip` already resides in +some layer. It can also fail if the additional clip breaks some +compositional rules (see `TimelineElement`). + +Feature: `v1_18` + +## `clip` +The clip to add + +# Returns + +`true` if `clip` was properly added to `self`, or `false` +if `self` refused to add `clip`. + +Gets whether the layer is active for the given track. See +`LayerExt::set_active_for_tracks`. +## `track` +The `Track` to check if `self` is currently active for + +# Returns + +`true` if `self` is active for `track`, or `false` otherwise. + +Gets the `Layer:auto-transition` of the layer. + +# Returns + +`true` if transitions are automatically added to `self`. + +Get the `Clip`-s contained in this layer. + +# Returns + +A list of clips in +`self`. + +Gets the clips within the layer that appear between `start` and `end`. +## `start` +Start of the interval +## `end` +End of the interval + +# Returns + +A list of `Clip`-s +that intersect the interval `[start, end)` in `self`. + +Retrieves the duration of the layer, which is the difference +between the start of the layer (always time 0) and the end (which will +be the end time of the final clip). + +# Returns + +The duration of `self`. + +Get the priority of the layer. When inside a timeline, this is its +index in the timeline. See `TimelineExt::move_layer`. + +# Returns + +The priority of `self` within its timeline. + +Gets the timeline that the layer is a part of. + +# Returns + +The timeline that `self` +is currently part of, or `None` if it is not associated with any +timeline. + +Convenience method to check if the layer is empty (doesn't contain +any `Clip`), or not. + +# Returns + +`true` if `self` is empty, `false` if it contains at least +one clip. + +Removes the given clip from the layer. +## `clip` +The clip to remove + +# Returns + +`true` if `clip` was removed from `self`, or `false` if the +operation failed. + +Activate or deactivate track elements in `tracks` (or in all tracks if `tracks` +is `None`). + +When a layer is deactivated for a track, all the `TrackElement`-s in +the track that belong to a `Clip` in the layer will no longer be +active in the track, regardless of their individual +`TrackElement:active` value. + +Note that by default a layer will be active for all of its +timeline's tracks. +## `active` +Whether elements in `tracks` should be active or not +## `tracks` +The list of +tracks `self` should be (de-)active in, or `None` to include all the tracks +in the `self`'s timeline + +# Returns + +`true` if the operation worked `false` otherwise. -Sets the layer to the given `auto_transition`. See the documentation of the -property auto_transition for more information. +Sets `Layer:auto-transition` for the layer. Use +`TimelineExt::set_auto_transition` if you want all layers within a +`Timeline` to have `Layer:auto-transition` set to `true`. Use this +method if you want different values for different layers (and make sure +to keep `Timeline:auto-transition` as `false` for the corresponding +timeline). ## `auto_transition` -whether the auto_transition is active +Whether transitions should be automatically added to +the layer -Sets the layer to the given `priority`. See the documentation of the -priority property for more information. +Sets the layer to the given priority. See `Layer:priority`. # Deprecated since 1.16 @@ -786,26 +1852,46 @@ use `TimelineExt::move_layer` instead. This deprecation means that you will not need to handle layer priorities at all yourself, GES will make sure there is never 'gaps' between layer priorities. ## `priority` -the priority to set +The priority to set + +Will be emitted whenever the layer is activated or deactivated +for some `Track`. See `LayerExt::set_active_for_tracks`. +## `active` +Whether `layer` has been made active or de-active in the `tracks` +## `tracks` +A list of `Track` +which have been activated or deactivated -Will be emitted after the clip was added to the layer. +Will be emitted after the clip is added to the layer. ## `clip` -the `Clip` that was added. +The clip that was added -Will be emitted after the clip was removed from the layer. +Will be emitted after the clip is removed from the layer. ## `clip` -the `Clip` that was removed +The clip that was removed -Sets whether transitions are added automagically when clips overlap. +Whether to automatically create a `TransitionClip` whenever two +`Source`-s that both belong to a `Clip` in the layer overlap. +See `Timeline` for what counts as an overlap. + +When a layer is added to a `Timeline`, if this property is left as +`false`, but the timeline's `Timeline:auto-transition` is `true`, it +will be set to `true` as well. -Sets whether transitions are added automagically when clips overlap. +Whether to automatically create a `TransitionClip` whenever two +`Source`-s that both belong to a `Clip` in the layer overlap. +See `Timeline` for what counts as an overlap. + +When a layer is added to a `Timeline`, if this property is left as +`false`, but the timeline's `Timeline:auto-transition` is `true`, it +will be set to `true` as well. The priority of the layer in the `Timeline`. 0 is the highest -priority. Conceptually, a `Timeline` is a stack of GESLayers, +priority. Conceptually, a timeline is a stack of layers, and the priority of the layer represents its position in the stack. Two layers should not have the same priority within a given GESTimeline. -Note that the timeline needs to be commited (with `TimelineExt::commit`) +Note that the timeline needs to be committed (with `TimelineExt::commit`) for the change to be taken into account. # Deprecated since 1.16 @@ -815,11 +1901,11 @@ that you will not need to handle layer priorities at all yourself, GES will make sure there is never 'gaps' between layer priorities. The priority of the layer in the `Timeline`. 0 is the highest -priority. Conceptually, a `Timeline` is a stack of GESLayers, +priority. Conceptually, a timeline is a stack of layers, and the priority of the layer represents its position in the stack. Two layers should not have the same priority within a given GESTimeline. -Note that the timeline needs to be commited (with `TimelineExt::commit`) +Note that the timeline needs to be committed (with `TimelineExt::commit`) for the change to be taken into account. # Deprecated since 1.16 @@ -828,9 +1914,17 @@ use `TimelineExt::move_layer` instead. This deprecation means that you will not need to handle layer priorities at all yourself, GES will make sure there is never 'gaps' between layer priorities. -`Pipeline` allows developers to view and render `Timeline` -in a simple fashion. -Its usage is inspired by the 'playbin' element from gst-plugins-base. +A `Pipeline` can take an audio-video `Timeline` and conveniently +link its `Track`-s to an internal `playsink` element, for +preview/playback, and an internal `encodebin` element, for rendering. +You can switch between these modes using `GESPipelineExt::set_mode`. + +You can choose the specific audio and video sinks used for previewing +the timeline by setting the `Pipeline:audio-sink` and +`Pipeline:video-sink` properties. + +You can set the encoding and save location used in rendering by calling +`GESPipelineExt::set_render_settings`. # Implements @@ -842,151 +1936,179 @@ Trait containing all `Pipeline` methods. [`Pipeline`](struct.Pipeline.html) -Creates a new conveninence `Pipeline`. +Creates a new pipeline. # Returns -the new `Pipeline`. +The newly created pipeline. +Gets the `Pipeline:mode` of the pipeline. # Returns -the `PipelineFlags` currently in use. +The current mode of `self`. -Returns a `gst::Sample` with the currently playing image in the format specified by -caps. The caller should free the sample with `gst_sample_unref` when finished. If ANY -caps are specified, the information will be returned in the whatever format -is currently used by the sink. This information can be retrieve from caps -associated with the buffer. +Gets a sample from the pipeline of the currently displayed image in +preview, in the specified format. + +Note that if you use "ANY" caps for `caps`, then the current format of +the image is used. You can retrieve these caps from the returned sample +with `gst::Sample::get_caps`. ## `caps` -caps specifying current format. Use `GST_CAPS_ANY` -for native size. +Some caps to specifying the desired format, or +`GST_CAPS_ANY` to use the native format # Returns -a `gst::Sample` or `None` +A sample of `self`'s current image preview in +the format given by `caps`, or `None` if an error prevented fetching the +sample. -A convenience method for `GESPipelineExt::get_thumbnail` which -returns a buffer in 24-bit RGB, optionally scaled to the specified width -and height. If -1 is specified for either dimension, it will be left at -native size. You can retreive this information from the caps associated -with the buffer. +Gets a sample from the pipeline of the currently displayed image in +preview, in the 24-bit "RGB" format and of the desired width and +height. -The caller is responsible for unreffing the returned sample with -`gst_sample_unref`. +See `GESPipelineExt::get_thumbnail`. ## `width` -the requested width or -1 for native size +The requested pixel width of the image, or -1 to use the native +size ## `height` -the requested height or -1 for native size +The requested pixel height of the image, or -1 to use the +native size # Returns -a `gst::Sample` or `None` +A sample of `self`'s current image preview in +the "RGB" format, scaled to `width` and `height`, or `None` if an error +prevented fetching the sample. -Obtains a pointer to playsink's audio sink element that is used for -displaying audio when the `Pipeline` is in `PipelineFlags::FullPreview` - -The caller is responsible for unreffing the returned element with -`gst::ObjectExt::unref`. +Gets the `Pipeline:audio-sink` of the pipeline. # Returns -a pointer to the playsink audio sink `gst::Element` +The audio sink used by `self` for preview. -Obtains a pointer to playsink's video sink element that is used for -displaying video when the `Pipeline` is in `PipelineFlags::FullPreview` - -The caller is responsible for unreffing the returned element with -`gst::ObjectExt::unref`. +Gets the `Pipeline:video-sink` of the pipeline. # Returns -a pointer to the playsink video sink `gst::Element` +The video sink used by `self` for preview. -Sets playsink's audio sink element that is used for displaying audio when -the `Pipeline` is in `PipelineFlags::FullPreview` +Sets the `Pipeline:audio-sink` of the pipeline. ## `sink` -a audio sink `gst::Element` +A audio sink for `self` to use for preview -Sets playsink's video sink element that is used for displaying video when -the `Pipeline` is in `PipelineFlags::FullPreview` +Sets the `Pipeline:video-sink` of the pipeline. ## `sink` -a video sink `gst::Element` +A video sink for `self` to use for preview -Saves the current frame to the specified `location`. +Saves the currently displayed image of the pipeline in preview to the +given location, in the specified dimensions and format. ## `width` -the requested width or -1 for native size +The requested pixel width of the image, or -1 to use the native +size ## `height` -the requested height or -1 for native size +The requested pixel height of the image, or -1 to use the +native size ## `format` -a string specifying the desired mime type (for example, -image/jpeg) +The desired mime type (for example, "image/jpeg") ## `location` -the path to save the thumbnail +The path to save the thumbnail to # Returns -`true` if the thumbnail was properly save, else `false`. +`true` if `self`'s current image preview was successfully saved +to `location` using the given `format`, `height` and `width`. -switches the `self` to the specified `mode`. The default mode when -creating a `Pipeline` is `PipelineFlags::FullPreview`. +Sets the `Pipeline:mode` of the pipeline. -Note: The `self` will be set to `gst::State::Null` during this call due to -the internal changes that happen. The caller will therefore have to -set the `self` to the requested state after calling this method. +Note that the pipeline will be set to `gst::State::Null` during this call +to perform the necessary changes. You will need to set the state again +yourself after calling this. ## `mode` -the `PipelineFlags` to use +The mode to set for `self` # Returns -`true` if the mode was properly set, else `false`. +`true` if the mode of `self` was successfully set to `mode`. -Specify where the pipeline shall be rendered and with what settings. +Specifies the encoding to be used by the pipeline to render its +`Pipeline:timeline`, and where the result should be written to. -A copy of `profile` and `output_uri` will be done internally, the caller can -safely free those values afterwards. - -This method must be called before setting the pipeline mode to -`PipelineFlags::Render` +This method **must** be called before setting the pipeline mode to +`PipelineFlags::Render`. ## `output_uri` -the URI to which the timeline will be rendered +The URI to save the `Pipeline:timeline` rendering +result to ## `profile` -the `gst_pbutils::EncodingProfile` to use to render the timeline. +The encoding to use for rendering the `Pipeline:timeline` # Returns -`true` if the settings were aknowledged properly, else `false` +`true` if the settings were successfully set on `self`. -Sets the timeline to use in this pipeline. +Takes the given timeline and sets it as the `Pipeline:timeline` for +the pipeline. -The reference to the `timeline` will be stolen by the `self`. +Note that you should only call this method once on a given pipeline +because a pipeline can not have its `Pipeline:timeline` changed after +it has been set. ## `timeline` -the `Timeline` to set on the `self`. +The timeline to set for `self` # Returns -`true` if the `timeline` could be successfully set on the `self`, -else `false`. +`true` if `timeline` was successfully given to `self`. + +The audio filter(s) to apply during playback in preview mode, +immediately before the `Pipeline:audio-sink`. This exposes the +`playsink:audio-filter` property of the internal `playsink`. + +The audio filter(s) to apply during playback in preview mode, +immediately before the `Pipeline:audio-sink`. This exposes the +`playsink:audio-filter` property of the internal `playsink`. -Audio sink for the preview. +The audio sink used for preview. This exposes the +`playsink:audio-sink` property of the internal `playsink`. -Audio sink for the preview. +The audio sink used for preview. This exposes the +`playsink:audio-sink` property of the internal `playsink`. -Pipeline mode. See `GESPipelineExt::set_mode` for more -info. +The pipeline's mode. In preview mode (for audio or video, or both) +the pipeline can display the timeline's content to an end user. In +rendering mode the pipeline can encode the timeline's content and +save it to a file. -Pipeline mode. See `GESPipelineExt::set_mode` for more -info. +The pipeline's mode. In preview mode (for audio or video, or both) +the pipeline can display the timeline's content to an end user. In +rendering mode the pipeline can encode the timeline's content and +save it to a file. -Timeline to use in this pipeline. See also -`GESPipelineExt::set_timeline` for more info. +The timeline used by this pipeline, whose content it will play and +render, or `None` if the pipeline does not yet have a timeline. + +Note that after you set the timeline for the first time, subsequent +calls to change the timeline will fail. -Timeline to use in this pipeline. See also -`GESPipelineExt::set_timeline` for more info. +The timeline used by this pipeline, whose content it will play and +render, or `None` if the pipeline does not yet have a timeline. + +Note that after you set the timeline for the first time, subsequent +calls to change the timeline will fail. + +The video filter(s) to apply during playback in preview mode, +immediately before the `Pipeline:video-sink`. This exposes the +`playsink:video-filter` property of the internal `playsink`. + +The video filter(s) to apply during playback in preview mode, +immediately before the `Pipeline:video-sink`. This exposes the +`playsink:video-filter` property of the internal `playsink`. -Video sink for the preview. +The video sink used for preview. This exposes the +`playsink:video-sink` property of the internal `playsink`. -Video sink for the preview. +The video sink used for preview. This exposes the +`playsink:video-sink` property of the internal `playsink`. The `Project` is used to control a set of `Asset` and is a `Asset` with `GES_TYPE_TIMELINE` as `extractable_type` itself. That @@ -1011,6 +2133,24 @@ It lets you request new asset, and it informs you about new assets through a set of signals. Also it handles problem such as missing files/missing `gst::Element` and lets you try to recover from those. +## Subprojects + +In order to add a subproject, the only thing to do is to add the subproject +to the main project: + +``` c +ges_project_add_asset (project, GES_ASSET (subproject)); +``` +then the subproject will be serialized in the project files. To use +the subproject in a timeline, you should use a `UriClip` with the +same subproject URI. + +When loading a project with subproject, subprojects URIs will be temporary +writable local files. If you want to edit the subproject timeline, +you should retrieve the subproject from the parent project asset list and +extract the timeline with `AssetExt::extract` and save it at +the same temporary location. + # Implements [`ProjectExt`](trait.ProjectExt.html), [`AssetExt`](trait.AssetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) @@ -1053,6 +2193,13 @@ the same name already exists, it will be replaced # Returns `true` if `profile` could be added, `false` otherwize + +Adds a formatter as used to load `self` + +Feature: `v1_18` + +## `formatter` +A formatter used by `self` Create and add a `Asset` to `self`. You should connect to the "asset-added" signal to get the asset when it finally gets added to @@ -1148,9 +2295,10 @@ The `Timeline` to save, it must have been extracted from `self` ## `uri` The uri where to save `self` and `timeline` ## `formatter_asset` -The formatter asset to use or `None`. If `None`, -will try to save in the same format as the one from which the timeline as been loaded -or default to the formatter with highest rank +The formatter asset to +use or `None`. If `None`, will try to save in the same format as the one +from which the timeline as been loaded or default to the best formatter +as defined in `ges_find_formatter_for_uri` ## `overwrite` `true` to overwrite file if it exists @@ -1166,6 +2314,14 @@ The `Asset` that started loading ## `asset` The `Asset` that has been removed from `project` + + +Feature: `v1_18` + +## `timeline` +The timeline that failed loading +## `error` +The `glib::Error` defining the error that occured Informs you that a `Asset` could not be created. In case of missing GStreamer plugins, the error will be set to `GST_CORE_ERROR` @@ -1179,7 +2335,13 @@ The `extractable_type` of the asset that failed loading ## `timeline` -The `Timeline` that complete loading +The `Timeline` that completed loading + + +Feature: `v1_18` + +## `timeline` +The `Timeline` that started loading ```text @@ -1211,17 +2373,105 @@ The new URI of `wrong_asset` `Timeline` is the central object for any multimedia timeline. -Contains a list of `Layer` which users should use to arrange the -various clips through time. +A timeline is composed of a set of `Track`-s and a set of +`Layer`-s, which are added to the timeline using +`TimelineExt::add_track` and `TimelineExt::append_layer`, respectively. -The output type is determined by the `Track` that are set on -the `Timeline`. +The contained tracks define the supported types of the timeline +and provide the media output. Essentially, each track provides an +additional source `gst::Pad`. -To save/load a timeline, you can use the `TimelineExt::load_from_uri` and -`TimelineExt::save_to_uri` methods to use the default format. If you wish +Most usage of a timeline will likely only need a single `AudioTrack` +and/or a single `VideoTrack`. You can create such a timeline with +`Timeline::new_audio_video`. After this, you are unlikely to need to +work with the tracks directly. -Note that any change you make in the timeline will not actually be taken -into account until you call the `TimelineExt::commit` method. +A timeline's layers contain `Clip`-s, which in turn control the +creation of `TrackElement`-s, which are added to the timeline's +tracks. See `Timeline::select-tracks-for-object` if you wish to have +more control over which track a clip's elements are added to. + +The layers are ordered, with higher priority layers having their +content prioritised in the tracks. This ordering can be changed using +`TimelineExt::move_layer`. + +## Editing + +See `TimelineElement` for the various ways the elements of a timeline +can be edited. + +If you change the timing or ordering of a timeline's +`TimelineElement`-s, then these changes will not actually be taken +into account in the output of the timeline's tracks until the +`TimelineExt::commit` method is called. This allows you to move its +elements around, say, in response to an end user's mouse dragging, with +little expense before finalising their effect on the produced data. + +## Overlaps and Auto-Transitions + +There are certain restrictions placed on how `Source`-s may overlap +in a `Track` that belongs to a timeline. These will be enforced by +GES, so the user will not need to keep track of them, but they should +be aware that certain edits will be refused as a result if the overlap +rules would be broken. + +Consider two `Source`-s, `A` and `B`, with start times `startA` and +`startB`, and end times `endA` and `endB`, respectively. The start +time refers to their `TimelineElement:start`, and the end time is +their `TimelineElement:start` + `TimelineElement:duration`. These +two sources *overlap* if: + ++ they share the same `TrackElement:track` (non `None`), which belongs + to the timeline; ++ they share the same `GES_TIMELINE_ELEMENT_LAYER_PRIORITY`; and ++ `startA < endB` and `startB < endA `. + +Note that when `startA = endB` or `startB = endA` then the two sources +will *touch* at their edges, but are not considered overlapping. + +If, in addition, `startA < startB < endA`, then we can say that the +end of `A` overlaps the start of `B`. + +If, instead, `startA <= startB` and `endA >= endB`, then we can say +that `A` fully overlaps `B`. + +The overlap rules for a timeline are that: + +1. One source cannot fully overlap another source. +2. A source can only overlap the end of up to one other source at its + start. +3. A source can only overlap the start of up to one other source at its + end. + +The last two rules combined essentially mean that at any given timeline +position, only up to two `Source`-s may overlap at that position. So +triple or more overlaps are not allowed. + +If you switch on `Timeline:auto-transition`, then at any moment when +the end of one source (the first source) overlaps the start of another +(the second source), a `TransitionClip` will be automatically created +for the pair in the same layer and it will cover their overlap. If the +two elements are edited in a way such that the end of the first source +no longer overlaps the start of the second, the transition will be +automatically removed from the timeline. However, if the two sources +still overlap at the same edges after the edit, then the same +transition object will be kept, but with its timing and layer adjusted +accordingly. + +## Saving + +To save/load a timeline, you can use the `TimelineExt::load_from_uri` +and `TimelineExt::save_to_uri` methods that use the default format. + +## Playing + +A timeline is a `gst::Bin` with a source `gst::Pad` for each of its +tracks, which you can fetch with `TimelineExt::get_pad_for_track`. You +will likely want to link these to some compatible sink `gst::Element`-s to +be able to play or capture the content of the timeline. + +You can use a `Pipeline` to easily preview/play the timeline's +content, or render it to a file. # Implements @@ -1233,746 +2483,1301 @@ Trait containing all `Timeline` methods. [`Timeline`](struct.Timeline.html) -Creates a new empty `Timeline`. +Creates a new empty timeline. # Returns The new timeline. -Creates a new `Timeline` containing a raw audio and a -raw video track. +Creates a new timeline containing a single `AudioTrack` and a +single `VideoTrack`. # Returns -The newly created `Timeline`. +The new timeline, or `None` if the tracks +could not be created and added. Creates a timeline from the given URI. ## `uri` -the URI to load from +The URI to load from # Returns A new timeline if the uri was loaded successfully, or `None` if the uri could not be loaded. -Add the layer to the timeline. The reference to the `layer` will be stolen -by the `self`. +Add a layer to the timeline. + +If the layer contains `Clip`-s, then this may trigger the creation of +their core track element children for the timeline's tracks, and the +placement of the clip's children in the tracks of the timeline using +`Timeline::select-tracks-for-object`. Some errors may occur if this +would break one of the configuration rules of the timeline in one of +its tracks. In such cases, some track elements would fail to be added +to their tracks, but this method would still return `true`. As such, it +is advised that you only add clips to layers that already part of a +timeline. In such situations, `LayerExt::add_clip` is able to fail if +adding the clip would cause such an error. + +# Deprecated since 1.18 + +This method requires you to ensure the layer's +`Layer:priority` will be unique to the timeline. Use +`TimelineExt::append_layer` and `TimelineExt::move_layer` instead. ## `layer` -the `Layer` to add +The layer to add # Returns -`true` if the layer was properly added, else `false`. +`true` if `layer` was properly added. -Add a track to the timeline. The reference to the track will be stolen by the -pipeline. +Add a track to the timeline. + +If the timeline already contains clips, then this may trigger the +creation of their core track element children for the track, and the +placement of the clip's children in the track of the timeline using +`Timeline::select-tracks-for-object`. Some errors may occur if this +would break one of the configuration rules for the timeline in the +track. In such cases, some track elements would fail to be added to the +track, but this method would still return `true`. As such, it is advised +that you avoid adding tracks to timelines that already contain clips. ## `track` -the `Track` to add +The track to add # Returns -`true` if the track was properly added, else `false`. +`true` if `track` was properly added. -Append a newly created `Layer` to `self` -Note that you do not own any reference to the returned layer. +Append a newly created layer to the timeline. The layer will +be added at the lowest `Layer:priority` (numerically, the highest). # Returns -The newly created `Layer`, or the last (empty) -`Layer` of `self`. +The newly created layer. Commit all the pending changes of the clips contained in the -`self`. +timeline. -When changes happen in a timeline, they are not -directly executed in the non-linear engine. Call this method once you are -done with a set of changes and want it to be executed. - -The `Timeline::commited` signal will be emitted when the (possibly updated) -`gst::Pipeline` is ready to output data again, except if the state of the -timeline was `gst::State::Ready` or `gst::State::Null`. - -Note that all the pending changes will automatically be executed when the -timeline goes from `gst::State::Ready` to `gst::State::Paused`, which usually is -triggered by corresponding state changes in a containing `Pipeline`. +When changes happen in a timeline, they are not immediately executed +internally, in a way that effects the output data of the timeline. You +should call this method when you are done with a set of changes and you +want them to be executed. +Any pending changes will be executed in the backend. The +`Timeline::commited` signal will be emitted once this has completed. You should not try to change the state of the timeline, seek it or add -tracks to it during a commit operation, that is between a call to this -function and after receiving the `Timeline::commited` signal. +tracks to it before receiving this signal. You can use +`TimelineExt::commit_sync` if you do not want to perform other tasks in +the mean time. -See `TimelineExt::commit_sync` if you don't want to bother with waiting -for the signal. +Note that all the pending changes will automatically be executed when +the timeline goes from `gst::State::Ready` to `gst::State::Paused`, which is +usually triggered by a corresponding state changes in a containing +`Pipeline`. # Returns -`true` if pending changes were commited or `false` if nothing needed -to be commited +`true` if pending changes were committed, or `false` if nothing +needed to be committed. -Commit all the pending changes of the `GESClips` contained in the -`self`. +Commit all the pending changes of the clips contained in the +timeline and wait for the changes to complete. -Will return once the update is complete, that is when the -(possibly updated) `gst::Pipeline` is ready to output data again, or if the -state of the timeline was `gst::State::Ready` or `gst::State::Null`. - -This function will wait for any pending state change of the timeline by -calling `gst::ElementExt::get_state` with a `GST_CLOCK_TIME_NONE` timeout, you -should not try to change the state from another thread before this function -has returned. - -See `TimelineExt::commit` for more information. +See `TimelineExt::commit`. # Returns -`true` if pending changes were commited or `false` if nothing needed -to be commited +`true` if pending changes were committed, or `false` if nothing +needed to be committed. -Gets whether transitions are automatically added when objects -overlap or not. +Gets `Timeline:auto-transition` for the timeline. # Returns -`true` if transitions are automatically added, else `false`. +The auto-transition of `self_`. -Get the current duration of `self` +Get the current `Timeline:duration` of the timeline # Returns -The current duration of `self` +The current duration of `self`. -Gets a `TimelineElement` contained in the timeline +Gets the element contained in the timeline with the given name. +## `name` +The name of the element to find # Returns -The `TimelineElement` or `None` if -not found. +The timeline element in `self` +with the given `name`, or `None` if it was not found. + +This method allows you to convert a timeline `gst::ClockTime` into its +corresponding `FrameNumber` in the timeline's output. +## `timestamp` +The timestamp to get the corresponding frame number of + +# Returns + +The frame number `timestamp` corresponds to. + +This method allows you to convert a timeline output frame number into a +timeline `gst::ClockTime`. For example, this time could be used to seek to a +particular frame in the timeline's output, or as the edit position for +an element within the timeline. +## `frame_number` +The frame number to get the corresponding timestamp of in the + timeline coordinates + +# Returns + +The timestamp corresponding to `frame_number` in the output of `self`. -Get the list of `Group` present in the Timeline. +Get the list of `Group`-s present in the timeline. # Returns -the list of -`Group` that contain clips present in the timeline's layers. +The list of +groups that contain clips present in `self`'s layers. Must not be changed. -Retrieve the layer with `priority` as a priority +Retrieve the layer whose index in the timeline matches the given +priority. ## `priority` -The priority of the layer to find +The priority/index of the layer to find # Returns -A `Layer` or `None` if no layer with -`priority` was found +The layer with the given +`priority`, or `None` if none was found. Since 1.6 -Get the list of `Layer` present in the Timeline. +Get the list of `Layer`-s present in the timeline. # Returns -the list of -`Layer` present in the Timeline sorted by priority. -The caller should unref each Layer once he is done with them. +The list of +layers present in `self` sorted by priority. -Search the `gst::Pad` corresponding to the given `self`'s `track`. +Search for the `gst::Pad` corresponding to the given timeline's track. +You can link to this pad to receive the output data of the given track. ## `track` -The `Track` +A track # Returns -The corresponding `gst::Pad` if it is -found, or `None` if there is an error. +The pad corresponding to `track`, +or `None` if there is an error. -Gets the configured snapping distance of the timeline. See -the documentation of the property snapping_distance for more -information. +Gets the `Timeline:snapping-distance` for the timeline. # Returns -The `snapping_distance` property of the timeline +The snapping distance (in nanoseconds) of `self`. -Search the `Track` corresponding to the given `self`'s `pad`. +Search for the `Track` corresponding to the given timeline's pad. ## `pad` -The `gst::Pad` +A pad # Returns -The corresponding `Track` if it is -found, or `None` if there is an error. +The track corresponding to `pad`, +or `None` if there is an error. -Returns the list of `Track` used by the Timeline. +Get the list of `Track`-s used by the timeline. # Returns -A list of `Track`. -The caller should unref each track once he is done with them. +The list of tracks +used by `self`. -Check whether a `Timeline` is empty or not +Check whether the timeline is empty or not. # Returns -`true` if the timeline is empty `false` otherwize +`true` if `self` is empty. -Loads the contents of URI into the given timeline. +Loads the contents of URI into the timeline. ## `uri` The URI to load from # Returns -`true` if the timeline was loaded successfully, or `false` if the uri -could not be loaded. +`true` if the timeline was loaded successfully from `uri`. -Moves `layer` at `new_layer_priority` meaning that `layer` -we land at that position in the stack of layers inside -the timeline. If `new_layer_priority` is superior than the number -of layers present in the time, it will move to the end of the -stack of layers. +Moves a layer within the timeline to the index given by +`new_layer_priority`. +An index of 0 corresponds to the layer with the highest priority in a +timeline. If `new_layer_priority` is greater than the number of layers +present in the timeline, it will become the lowest priority layer. Feature: `v1_16` ## `layer` -The layer to move at `new_layer_priority` +A layer within `self`, whose priority should be changed ## `new_layer_priority` -The index at which `layer` should land +The new index for `layer` -Paste `element` inside the timeline. `element` must have been -created using ges_timeline_element_copy with deep=TRUE set, -i.e. it must be a deep copy, otherwise it will fail. +Paste an element inside the timeline. `element` **must** be the return of +`TimelineElementExt::copy` with `deep=TRUE`, +and it should not be changed before pasting. `element` itself is not +placed in the timeline, instead a new element is created, alike to the +originally copied element. Note that the originally copied element must +also lie within `self`, at both the point of copying and pasting. + +Pasting may fail if it would place the timeline in an unsupported +configuration. + +After calling this function `element` should not be used. In particular, +`element` can **not** be pasted again. Instead, you can copy the +returned element and paste that copy (although, this is only possible +if the paste was successful). + +See also `TimelineElementExt::paste`. ## `element` -The `TimelineElement` to paste +The element to paste ## `position` -The position in the timeline the element should -be pasted to, meaning it will become the start of `element` +The position in the timeline `element` should be pasted to, +i.e. the `TimelineElement:start` value for the pasted element. ## `layer_priority` -The `Layer` to which the element should be pasted to. --1 means paste to the same layer from which the `element` has been copied from. +The layer into which the element should be pasted. +-1 means paste to the same layer from which `element` has been copied from # Returns -Shallow copy of the `element` pasted +The newly created element, or +`None` if pasting fails. -Removes the layer from the timeline. The reference that the `self` holds on -the layer will be dropped. If you wish to use the `layer` after calling this -method, you need to take a reference before calling. +Removes a layer from the timeline. ## `layer` -the `Layer` to remove +The layer to remove # Returns -`true` if the layer was properly removed, else `false`. +`true` if `layer` was properly removed. -Remove the `track` from the `self`. The reference stolen when adding the -`track` will be removed. If you wish to use the `track` after calling this -function you must ensure that you have a reference to it. +Remove a track from the timeline. ## `track` -the `Track` to remove +The track to remove # Returns -`true` if the `track` was properly removed, else `false`. +`true` if `track` was properly removed. -Saves the timeline to the given location +Saves the timeline to the given location. If `formatter_asset` is `None`, +the method will attempt to save in the same format the timeline was +loaded from, before defaulting to the formatter with highest rank. ## `uri` The location to save to ## `formatter_asset` -The formatter asset to use or `None`. If `None`, -will try to save in the same format as the one from which the timeline as been loaded -or default to the formatter with highest rank +The formatter asset to use, or `None` ## `overwrite` `true` to overwrite file if it exists # Returns -`true` if the timeline was successfully saved to the given location, -else `false`. +`true` if `self` was successfully saved to `uri`. -Sets the layer to the given `auto_transition`. See the documentation of the -property auto_transition for more information. +Sets `Timeline:auto-transition` for the timeline. This will also set +the corresponding `Layer:auto-transition` for all of the timeline's +layers to the same value. See `LayerExt::set_auto_transition` if you +wish to set the layer's `Layer:auto-transition` individually. ## `auto_transition` -whether the auto_transition is active +Whether transitions should be automatically added +to `self`'s layers -Sets the `snapping_distance` of the timeline. See the documentation of the -property snapping_distance for more information. +Sets `Timeline:snapping-distance` for the timeline. This new value +will only effect future snappings and will not be used to snap the +current element positions within the timeline. ## `snapping_distance` -whether the snapping_distance is active +The snapping distance to use (in nanoseconds) -This signal will be emitted once the changes initiated by `TimelineExt::commit` -have been executed in the backend. Use `TimelineExt::commit_sync` if you -don't need to do anything in the meantime. +This signal will be emitted once the changes initiated by +`TimelineExt::commit` have been executed in the backend. Use +`TimelineExt::commit_sync` if you do not want to have to connect +to this signal. -Will be emitted after a new group is added to to the timeline. +Will be emitted after the group is added to to the timeline. This can +happen when grouping with `ges_container_group`, or by adding +containers to a newly created group. + +Note that this should not be emitted whilst a timeline is being +loaded from its `Project` asset. You should connect to the +project's `Project::loaded` signal if you want to know which groups +were created for the timeline. ## `group` -the `Group` +The group that was added to `timeline` -Will be emitted after a group has been removed from the timeline. +Will be emitted after the group is removed from the timeline through +`ges_container_ungroup`. Note that `group` will no longer contain its +former children, these are held in `children`. + +Note that if a group is emptied, then it will no longer belong to the +timeline, but this signal will **not** be emitted in such a case. ## `group` -the `Group` +The group that was removed from `timeline` ## `children` -a list of `Container` +A list +of `Container`-s that _were_ the children of the removed `group` -Will be emitted after a new layer is added to the timeline. +Will be emitted after the layer is added to the timeline. + +Note that this should not be emitted whilst a timeline is being +loaded from its `Project` asset. You should connect to the +project's `Project::loaded` signal if you want to know which +layers were created for the timeline. ## `layer` -the `Layer` that was added to the timeline +The layer that was added to `timeline` -Will be emitted after the layer was removed from the timeline. +Will be emitted after the layer is removed from the timeline. ## `layer` -the `Layer` that was removed from the timeline +The layer that was removed from `timeline` +This will be emitted whenever the timeline needs to determine which +tracks a clip's children should be added to. The track element will +be added to each of the tracks given in the return. If a track +element is selected to go into multiple tracks, it will be copied +into the additional tracks, under the same clip. Note that the copy +will *not* keep its properties or state in sync with the original. + +Connect to this signal once if you wish to control which element +should be added to which track. Doing so will overwrite the default +behaviour, which adds `track_element` to all tracks whose +`Track:track-type` includes the `track_element`'s +`TrackElement:track-type`. + +Note that under the default track selection, if a clip would produce +multiple core children of the same `TrackType`, it will choose +one of the core children arbitrarily to place in the corresponding +tracks, with a warning for the other core children that are not +placed in the track. For example, this would happen for a `UriClip` +that points to a file that contains multiple audio streams. If you +wish to choose the stream, you could connect to this signal, and use, +say, `UriSourceAssetExt::get_stream_info` to choose which core +source to add. + +When a clip is first added to a timeline, its core elements will +be created for the current tracks in the timeline if they have not +already been created. Then this will be emitted for each of these +core children to select which tracks, if any, they should be added +to. It will then be called for any non-core children in the clip. + +In addition, if a new track element is ever added to a clip in a +timeline (and it is not already part of a track) this will be emitted +to select which tracks the element should be added to. + +Finally, as a special case, if a track is added to the timeline +*after* it already contains clips, then it will request the creation +of the clips' core elements of the corresponding type, if they have +not already been created, and this signal will be emitted for each of +these newly created elements. In addition, this will also be released +for all other track elements in the timeline's clips that have not +yet been assigned a track. However, in this final case, the timeline +will only check whether the newly added track appears in the track +list. If it does appear, the track element will be added to the newly +added track. All other tracks in the returned track list are ignored. + +In this latter case, track elements that are already part of a track +will not be asked if they want to be copied into the new track. If +you wish to do this, you can use `ClipExt::add_child_to_track`. + +Note that the returned `glib::PtrArray` should own a new reference to each +of its contained `Track`. The timeline will set the `GDestroyNotify` +free function on the `glib::PtrArray` to dereference the elements. ## `clip` -The `Clip` on which `track_element` will land +The clip that `track_element` is being added to ## `track_element` -The `TrackElement` for which to choose the tracks it should land into +The element being added # Returns -a `glib::PtrArray` of `Track`-s where that object should be added +An array of +`Track`-s that `track_element` should be added to, or `None` to +not add the element to any track. -Will be emitted when the 2 `TrackElement` ended to snap +Will be emitted whenever a snapping event ends. After a snap event +has started (see `Timeline::snapping-started`), it can later end +because either another timeline edit has occurred (which may or may +not have created a new snapping event), or because the timeline has +been committed. ## `obj1` -the first `TrackElement` that was snapping. +The first element that was snapping ## `obj2` -the second `TrackElement` that was snapping. +The second element that was snapping ## `position` -the position where the two objects finally snapping. +The position where the two objects were to be snapped to -Will be emitted when the 2 `TrackElement` first snapped +Will be emitted whenever an element's movement invokes a snapping +event during an edit (usually of one of its ancestors) because its +start or end point lies within the `Timeline:snapping-distance` of +another element's start or end point. + +See `EditMode` to see what can snap during an edit. + +Note that only up to one snapping-started signal will be emitted per +element edit within a timeline. ## `obj1` -the first `TrackElement` that was snapping. +The first element that is snapping ## `obj2` -the second `TrackElement` that was snapping. +The second element that is snapping ## `position` -the position where the two objects finally snapping. +The position where the two objects will snap to -Will be emitted after the track was added to the timeline. +Will be emitted after the track is added to the timeline. + +Note that this should not be emitted whilst a timeline is being +loaded from its `Project` asset. You should connect to the +project's `Project::loaded` signal if you want to know which +tracks were created for the timeline. ## `track` -the `Track` that was added to the timeline +The track that was added to `timeline` -Will be emitted after the track was removed from the timeline. +Will be emitted after the track is removed from the timeline. ## `track` -the `Track` that was removed from the timeline +The track that was removed from `timeline` -Sets whether transitions are added automagically when clips overlap. +Whether to automatically create a transition whenever two +`Source`-s overlap in a track of the timeline. See +`Layer:auto-transition` if you want this to only happen in some +layers. -Sets whether transitions are added automagically when clips overlap. +Whether to automatically create a transition whenever two +`Source`-s overlap in a track of the timeline. See +`Layer:auto-transition` if you want this to only happen in some +layers. -Current duration (in nanoseconds) of the `Timeline` +The current duration (in nanoseconds) of the timeline. A timeline +'starts' at time 0, so this is the maximum end time of all of its +`TimelineElement`-s. -Distance (in nanoseconds) from which a moving object will snap -with it neighboors. 0 means no snapping. +The distance (in nanoseconds) at which a `TimelineElement` being +moved within the timeline should snap one of its `Source`-s with +another `Source`-s edge. See `EditMode` for which edges can +snap during an edit. 0 means no snapping. -Distance (in nanoseconds) from which a moving object will snap -with it neighboors. 0 means no snapping. +The distance (in nanoseconds) at which a `TimelineElement` being +moved within the timeline should snap one of its `Source`-s with +another `Source`-s edge. See `EditMode` for which edges can +snap during an edit. 0 means no snapping. -The GESTimelineElement base class implements the notion of timing as well -as priority. A GESTimelineElement can have a parent object which will be -responsible for controlling its timing properties. +A `TimelineElement` will have some temporal extent in its +corresponding `TimelineElement:timeline`, controlled by its +`TimelineElement:start` and `TimelineElement:duration`. This +determines when its content will be displayed, or its effect applied, +in the timeline. Several objects may overlap within a given +`Timeline`, in which case their `TimelineElement:priority` is used +to determine their ordering in the timeline. Priority is mostly handled +internally by `Layer`-s and `Clip`-s. + +A timeline element can have a `TimelineElement:parent`, +such as a `Clip`, which is responsible for controlling its timing. + +## Editing + +Elements can be moved around in their `TimelineElement:timeline` by +setting their `TimelineElement:start` and +`TimelineElement:duration` using `TimelineElementExt::set_start` +and `TimelineElementExt::set_duration`. Additionally, which parts of +the underlying content are played in the timeline can be adjusted by +setting the `TimelineElement:in-point` using +`TimelineElementExt::set_inpoint`. The library also provides +`TimelineElementExt::edit`, with various `EditMode`-s, which can +adjust these properties in a convenient way, as well as introduce +similar changes in neighbouring or later elements in the timeline. + +However, a timeline may refuse a change in these properties if they +would place the timeline in an unsupported configuration. See +`Timeline` for its overlap rules. + +Additionally, an edit may be refused if it would place one of the +timing properties out of bounds (such as a negative time value for +`TimelineElement:start`, or having insufficient internal +content to last for the desired `TimelineElement:duration`). + +## Time Coordinates + +There are three main sets of time coordinates to consider when using +timeline elements: + ++ Timeline coordinates: these are the time coordinates used in the + output of the timeline in its `Track`-s. Each track share the same + coordinates, so there is only one set of coordinates for the + timeline. These extend indefinitely from 0. The times used for + editing (including setting `TimelineElement:start` and + `TimelineElement:duration`) use these coordinates, since these + define when an element is present and for how long the element lasts + for in the timeline. ++ Internal source coordinates: these are the time coordinates used + internally at the element's output. This is only really defined for + `TrackElement`-s, where it refers to time coordinates used at the + final source pad of the wrapped `gst::Element`-s. However, these + coordinates may also be used in a `Clip` in reference to its + children. In particular, these are the coordinates used for + `TimelineElement:in-point` and `TimelineElement:max-duration`. ++ Internal sink coordinates: these are the time coordinates used + internally at the element's input. A `Source` has no input, so + these would be undefined. Otherwise, for most `TrackElement`-s + these will be the same set of coordinates as the internal source + coordinates because the element does not change the timing + internally. Only `BaseEffect` can support elements where these + are different. See `BaseEffect` for more information. + +You can determine the timeline time for a given internal source time +in a `Track` in a `Clip` using +`ClipExt::get_timeline_time_from_internal_time`, and vice versa using +`ClipExt::get_internal_time_from_timeline_time`, for the purposes of +editing and setting timings properties. + +## Children Properties + +If a timeline element owns another `gst::Object` and wishes to expose +some of its properties, it can do so by registering the property as one +of the timeline element's children properties using +`TimelineElementExt::add_child_property`. The registered property of +the child can then be read and set using the +`TimelineElementExt::get_child_property` and +`TimelineElementExt::set_child_property` methods, respectively. Some +sub-classed objects will be created with pre-registered children +properties; for example, to expose part of an underlying `gst::Element` +that is used internally. The registered properties can be listed with +`TimelineElementExt::list_children_properties`. # Implements -[`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html) +[`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html), [`TimelineElementExtManual`](prelude/trait.TimelineElementExtManual.html) Trait containing all `TimelineElement` methods. # Implementors [`Container`](struct.Container.html), [`TimelineElement`](struct.TimelineElement.html), [`TrackElement`](struct.TrackElement.html) - -Copies `self` -## `deep` -whether we want to create the elements `self` contains or not + +Register a property of a child of the element to allow it to be +written with `TimelineElementExt::set_child_property` and read with +`TimelineElementExt::get_child_property`. A change in the property +will also appear in the `TimelineElement::deep-notify` signal. -# Returns - -The newly create `TimelineElement`, copied from `self` - -Gets properties of a child of `self`. -## `first_property_name` -The name of the first property to get - -In general, a copy is made of the property contents and -the caller is responsible for freeing the memory by calling -`gobject::Value::unset`. - -Gets a property of a GstElement contained in `object`. - -Note that `TimelineElementExt::get_child_property` is really -intended for language bindings, `TimelineElementExt::get_child_properties` -is much more convenient for C programming. -## `property_name` -The name of the property -## `value` -return location for the property value, it will -be initialized if it is initialized with 0 - -# Returns - -`true` if the property was found, `false` otherwize - -Gets a property of a child of `self`. +`pspec` should be unique from other children properties that have been +registered on `self`. ## `pspec` -The `gobject::ParamSpec` that specifies the property you want to get -## `value` -return location for the value - -Gets a property of a child of `self`. If there are various child elements -that have the same property name, you can distinguish them using the following -syntax: 'ClasseName::property_name' as property name. If you don't, the -corresponding property of the first element found will be set. +The specification for the property to add +## `child` +The `gst::Object` who the property belongs to + +# Returns + +`true` if the property was successfully registered. + +Create a copy of `self`. All the properties of `self` are copied into +a new element, with the exception of `TimelineElement:parent`, +`TimelineElement:timeline` and `TimelineElement:name`. Other data, +such the list of a `Container`'s children, is **not** copied. + +If `deep` is `true`, then the new element is prepared so that it can be +used in `TimelineElementExt::paste` or `TimelineExt::paste_element`. +In the case of copying a `Container`, this ensures that the children +of `self` will also be pasted. The new element should not be used for +anything else and can only be used **once** in a pasting operation. In +particular, the new element itself is not an actual 'deep' copy of +`self`, but should be thought of as an intermediate object used for a +single paste operation. +## `deep` +Whether the copy is needed for pasting + +# Returns + +The newly create element, +copied from `self`. + +See `TimelineElementExt::edit_full`, which also gives an error. + +Note that the `layers` argument is currently ignored, so you should +just pass `None`. + +Feature: `v1_18` + +## `layers` +A whitelist of layers +where the edit can be performed, `None` allows all layers in the +timeline. +## `new_layer_priority` +The priority/index of the layer `self` should be +moved to. -1 means no move +## `mode` +The edit mode +## `edge` +The edge of `self` where the edit should occur +## `position` +The edit position: a new location for the edge of `self` +(in nanoseconds) in the timeline coordinates + +# Returns + +`true` if the edit of `self` completed, `false` on failure. + +Edits the element within its timeline by adjusting its +`TimelineElement:start`, `TimelineElement:duration` or +`TimelineElement:in-point`, and potentially doing the same for +other elements in the timeline. See `EditMode` for details about each +edit mode. An edit may fail if it would place one of these properties +out of bounds, or if it would place the timeline in an unsupported +configuration. + +Note that if you act on a `TrackElement`, this will edit its parent +`Clip` instead. Moreover, for any `TimelineElement`, if you select +`Edge::None` for `EditMode::Normal` or `EditMode::Ripple`, this +will edit the toplevel instead, but still in such a way as to make the +`TimelineElement:start` of `self` reach the edit `position`. + +Note that if the element's timeline has a +`Timeline:snapping-distance` set, then the edit position may be +snapped to the edge of some element under the edited element. + +`new_layer_priority` can be used to switch `self`, and other elements +moved by the edit, to a new layer. New layers may be be created if the +the corresponding layer priority/index does not yet exist for the +timeline. + +Feature: `v1_18` + +## `new_layer_priority` +The priority/index of the layer `self` should be +moved to. -1 means no move +## `mode` +The edit mode +## `edge` +The edge of `self` where the edit should occur +## `position` +The edit position: a new location for the edge of `self` +(in nanoseconds) in the timeline coordinates + +# Returns + +`true` if the edit of `self` completed, `false` on failure. + +Gets several of the children properties of the element. See +`TimelineElementExt::get_child_property`. ## `first_property_name` -The name of the first property to get +The name of the first child property to get + +Gets the property of a child of the element. + +`property_name` can either be in the format "prop-name" or +"TypeName::prop-name", where "prop-name" is the name of the property +to get (as used in `gobject::ObjectExt::get`), and "TypeName" is the type name of +the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is +useful when two children of different types share the same property +name. + +The first child found with the given "prop-name" property that was +registered with `TimelineElementExt::add_child_property` (and of the +type "TypeName", if it was given) will have the corresponding +property copied into `value`. + +Note that `TimelineElementExt::get_child_properties` may be more +convenient for C programming. +## `property_name` +The name of the child property to get +## `value` +The return location for the value + +# Returns + +`true` if the property was found and copied to `value`. + +Gets the property of a child of the element. Specifically, the property +corresponding to the `pspec` used in +`TimelineElementExt::add_child_property` is copied into `value`. +## `pspec` +The specification of a registered child property to get +## `value` +The return location for the value + +Gets several of the children properties of the element. See +`TimelineElementExt::get_child_property`. +## `first_property_name` +The name of the first child property to get ## `var_args` -value for the first property, followed optionally by more -name/return location pairs, followed by NULL +The return location for the first property, followed +optionally by more name/return location pairs, followed by `None` +Gets the `TimelineElement:duration` for the element. # Returns -The `duration` of `self` +The duration of `self` (in nanoseconds). +Gets the `TimelineElement:in-point` for the element. # Returns -The `inpoint` of `self` +The in-point of `self` (in nanoseconds). +Gets the priority of the layer the element is in. A `Group` may span +several layers, so this would return the highest priority (numerically, +the smallest) amongst them. Feature: `v1_16` # Returns -The priority of the first layer the element is in (note that only -groups can span over several layers). `GES_TIMELINE_ELEMENT_NO_LAYER_PRIORITY` -means that the element is not in a layer. +The priority of the layer `self` is in, or +`GES_TIMELINE_ELEMENT_NO_LAYER_PRIORITY` if `self` does not exist in a +layer. +Gets the `TimelineElement:max-duration` for the element. # Returns -The `maxduration` of `self` +The max-duration of `self` (in nanoseconds). -Returns a copy of the name of `self`. -Caller should `g_free` the return value after usage. +Gets the `TimelineElement:name` for the element. # Returns -The name of `self` +The name of `self`. + +Get the "natural" framerate of `self`. This is to say, for example +for a `VideoUriSource` the framerate of the source. + +Note that a `AudioSource` may also have a natural framerate if it derives +from the same `SourceClip` asset as a `VideoSource`, and its value will +be that of the video source. For example, if the uri of a `UriClip` points +to a file that contains both a video and audio stream, then the corresponding +`AudioUriSource` will share the natural framerate of the corresponding +`VideoUriSource`. + +Feature: `v1_18` + +## `framerate_n` +The framerate numerator +## `framerate_d` +The framerate denominator + +# Returns + +Whether `self` has a natural framerate or not, `framerate_n` +and `framerate_d` will be set to, respectively, 0 and -1 if it is +not the case. -Returns the parent of `self`. This function increases the refcount -of the parent object so you should `gst::ObjectExt::unref` it after usage. +Gets the `TimelineElement:parent` for the element. # Returns -parent of `self`, this can be `None` if -`self` has no parent. unref after usage. +The parent of `self`, or `None` if +`self` has no parent. +Gets the `TimelineElement:priority` for the element. # Returns -The `priority` of `self` +The priority of `self`. +Gets the `TimelineElement:start` for the element. # Returns -The `start` of `self` +The start of `self` (in nanoseconds). -Returns the timeline of `self`. This function increases the refcount -of the timeline so you should `gst::ObjectExt::unref` it after usage. +Gets the `TimelineElement:timeline` for the element. # Returns -timeline of `self`, this can be `None` if -`self` has no timeline. unref after usage. +The timeline of `self`, or `None` +if `self` has no timeline. -Gets the toplevel `TimelineElement` controlling `self` +Gets the toplevel `TimelineElement:parent` of the element. # Returns -The toplevel controlling parent of `self` +The toplevel parent of `self`. -Gets all the TrackTypes `self` will interact with +Gets the track types that the element can interact with, i.e. the type +of `Track` it can exist in, or will create `TrackElement`-s for. + +# Returns + +The track types that `self` supports. -Gets an array of `gobject::ParamSpec`* for all configurable properties of the -children of `self`. +Get a list of children properties of the element, which is a list of +all the specifications passed to +`TimelineElementExt::add_child_property`. ## `n_properties` -return location for the length of the returned array +The return location for the length of the +returned array # Returns -an array of `gobject::ParamSpec`* which should be freed after use or -`None` if something went wrong +An array of +`gobject::ParamSpec` corresponding to the child properties of `self`, or `None` if +something went wrong. -Looks up which `element` and `pspec` would be effected by the given `name`. If various -contained elements have this property name you will get the first one, unless you -specify the class name in `name`. +Looks up a child property of the element. + +`prop_name` can either be in the format "prop-name" or +"TypeName::prop-name", where "prop-name" is the name of the property +to look up (as used in `gobject::ObjectExt::get`), and "TypeName" is the type name +of the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is +useful when two children of different types share the same property +name. + +The first child found with the given "prop-name" property that was +registered with `TimelineElementExt::add_child_property` (and of the +type "TypeName", if it was given) will be passed to `child`, and the +registered specification of this property will be passed to `pspec`. ## `prop_name` -name of the property to look up. You can specify the name of the - class as such: "ClassName::property-name", to guarantee that you get the - proper GParamSpec in case various GstElement-s contain the same property - name. If you don't do so, you will get the first element found, having - this property and the and the corresponding GParamSpec. +The name of a child property ## `child` -pointer to a `gst::Element` that - takes the real object to set property on +The return location for the +found child ## `pspec` -pointer to take the `gobject::ParamSpec` - describing the property +The return location for the +specification of the child property # Returns -TRUE if `element` and `pspec` could be found. FALSE otherwise. In that -case the values for `pspec` and `element` are not modified. Unref `element` after -usage. +`true` if a child corresponding to the property was found, in +which case `child` and `pspec` are set. -Paste `self` inside the timeline. `self` must have been created -using ges_timeline_element_copy with recurse=TRUE set, -otherwise it will fail. +Paste an element inside the same timeline and layer as `self`. `self` +**must** be the return of `TimelineElementExt::copy` with `deep=TRUE`, +and it should not be changed before pasting. +`self` is not placed in the timeline, instead a new element is created, +alike to the originally copied element. Note that the originally +copied element must stay within the same timeline and layer, at both +the point of copying and pasting. + +Pasting may fail if it would place the timeline in an unsupported +configuration. + +After calling this function `element` should not be used. In particular, +`element` can **not** be pasted again. Instead, you can copy the +returned element and paste that copy (although, this is only possible +if the paste was successful). + +See also `TimelineExt::paste_element`. ## `paste_position` -The position in the timeline the element should -be copied to, meaning it will become the start of `self` +The position in the timeline `element` should be pasted +to, i.e. the `TimelineElement:start` value for the pasted element. # Returns -New element resulting of pasting `self` -or `None` - -Edits `self` in ripple mode. It allows you to modify the -start of `self` and move the following neighbours accordingly. -This will change the overall timeline duration. -## `start` -The new start of `self` in ripple mode. - -# Returns - -`true` if the self as been rippled properly, `false` if an error -occured - -Edits `self` in ripple mode. It allows you to modify the -duration of a `self` and move the following neighbours accordingly. -This will change the overall timeline duration. -## `end` -The new end (start + duration) of `self` in ripple mode. It will - basically only change the duration of `self`. - -# Returns - -`true` if the self as been rippled properly, `false` if an error -occured - -Edits `self` in roll mode. It allows you to modify the -duration of a `self` and trim (basicly change the start + inpoint -in this case) the following neighbours accordingly. -This will not change the overall timeline duration. -## `end` -The new end (start + duration) of `self` in roll mode - -# Returns - -`true` if the self as been rolled properly, `false` if an error -occured - -Edits `self` in roll mode. It allows you to modify the -start and inpoint of a `self` and "resize" (basicly change the duration -in this case) of the previous neighbours accordingly. -This will not change the overall timeline duration. -## `start` -The new start of `self` in roll mode, it will also adapat -the in-point of `self` according - -# Returns - -`true` if the self as been roll properly, `false` if an error -occured - -Sets a property of a child of `self`. If there are various child elements -that have the same property name, you can distinguish them using the following -syntax: 'ClasseName::property_name' as property name. If you don't, the -corresponding property of the first element found will be set. -## `first_property_name` -The name of the first property to set - -Sets a property of a child of `self` - -Note that `TimelineElementExt::set_child_property` is really -intended for language bindings, `TimelineElementExt::set_child_properties` -is much more convenient for C programming. -## `property_name` -The name of the property -## `value` -the value - -# Returns - -`true` if the property was set, `false` otherwize - -Sets a property of a child of `self`. +The newly created element, or +`None` if pasting fails. + +Remove a child property from the element. `pspec` should be a +specification that was passed to +`TimelineElementExt::add_child_property`. The corresponding property +will no longer be registered as a child property for the element. ## `pspec` -The `gobject::ParamSpec` that specifies the property you want to set -## `value` -the value - -Sets a property of a child of `self`. If there are various child elements -that have the same property name, you can distinguish them using the following -syntax: 'ClasseName::property_name' as property name. If you don't, the -corresponding property of the first element found will be set. +The specification for the property to remove + +# Returns + +`true` if the property was successfully un-registered for `self`. + +Edits the start time of an element within its timeline in ripple mode. +See `TimelineElementExt::edit` with `EditMode::Ripple` and +`Edge::None`. +## `start` +The new start time of `self` in ripple mode + +# Returns + +`true` if the ripple edit of `self` completed, `false` on +failure. + +Edits the end time of an element within its timeline in ripple mode. +See `TimelineElementExt::edit` with `EditMode::Ripple` and +`Edge::End`. +## `end` +The new end time of `self` in ripple mode + +# Returns + +`true` if the ripple edit of `self` completed, `false` on +failure. + +Edits the end time of an element within its timeline in roll mode. +See `TimelineElementExt::edit` with `EditMode::Roll` and +`Edge::End`. +## `end` +The new end time of `self` in roll mode + +# Returns + +`true` if the roll edit of `self` completed, `false` on failure. + +Edits the start time of an element within its timeline in roll mode. +See `TimelineElementExt::edit` with `EditMode::Roll` and +`Edge::Start`. +## `start` +The new start time of `self` in roll mode + +# Returns + +`true` if the roll edit of `self` completed, `false` on failure. + +Sets several of the children properties of the element. See +`TimelineElementExt::set_child_property`. ## `first_property_name` -The name of the first property to set +The name of the first child property to set + +See `TimelineElementExt::set_child_property_full`, which also gives an +error. + +Note that `TimelineElementExt::set_child_properties` may be more +convenient for C programming. +## `property_name` +The name of the child property to set +## `value` +The value to set the property to + +# Returns + +`true` if the property was found and set. + +Sets the property of a child of the element. Specifically, the property +corresponding to the `pspec` used in +`TimelineElementExt::add_child_property` is set to `value`. +## `pspec` +The specification of a registered child property to set +## `value` +The value to set the property to + +Sets the property of a child of the element. + +`property_name` can either be in the format "prop-name" or +"TypeName::prop-name", where "prop-name" is the name of the property +to set (as used in `gobject::ObjectExt::set`), and "TypeName" is the type name of +the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is +useful when two children of different types share the same property +name. + +The first child found with the given "prop-name" property that was +registered with `TimelineElementExt::add_child_property` (and of the +type "TypeName", if it was given) will have the corresponding +property set to `value`. Other children that may have also matched the +property name (and type name) are left unchanged! + +Feature: `v1_18` + +## `property_name` +The name of the child property to set +## `value` +The value to set the property to + +# Returns + +`true` if the property was found and set. + +Sets several of the children properties of the element. See +`TimelineElementExt::set_child_property`. +## `first_property_name` +The name of the first child property to set ## `var_args` -value for the first property, followed optionally by more -name/return location pairs, followed by NULL +The value for the first property, followed optionally by more +name/value pairs, followed by `None` -Set the duration of the object +Sets `TimelineElement:duration` for the element. -Note that if the timeline snap-distance property of the timeline containing -`self` is set, `self` will properly snap to its neighboors. +Whilst the element is part of a `Timeline`, this is the same as +editing the element with `TimelineElementExt::edit` under +`EditMode::Trim` with `Edge::End`. In particular, the +`TimelineElement:duration` of the element may be snapped to a +different timeline time difference from the one given. In addition, +setting may fail if it would place the timeline in an unsupported +configuration, or the element does not have enough internal content to +last the desired duration. ## `duration` -the duration in `gst::ClockTime` +The desired duration in its timeline # Returns -`true` if `duration` could be set. +`true` if `duration` could be set for `self`. -Set the in-point, that is the moment at which the `self` will start -outputting data from its contents. +Sets `TimelineElement:in-point` for the element. If the new in-point +is above the current `TimelineElement:max-duration` of the element, +this method will fail. ## `inpoint` -the in-point in `gst::ClockTime` +The in-point, in internal time coordinates # Returns -`true` if `inpoint` could be set. +`true` if `inpoint` could be set for `self`. -Set the maximun duration of the object +Sets `TimelineElement:max-duration` for the element. If the new +maximum duration is below the current `TimelineElement:in-point` of +the element, this method will fail. ## `maxduration` -the maximum duration in `gst::ClockTime` +The maximum duration, in internal time coordinates # Returns -`true` if `maxduration` could be set. +`true` if `maxduration` could be set for `self`. -Sets the name of object, or gives `self` a guaranteed unique name (if name is NULL). -This function makes a copy of the provided name, so the caller retains ownership -of the name it sent. +Sets the `TimelineElement:name` for the element. If `None` is given +for `name`, then the library will instead generate a new name based on +the type name of the element, such as the name "uriclip3" for a +`UriClip`, and will set that name instead. + +If `self` already has a `TimelineElement:timeline`, you should not +call this function with `name` set to `None`. + +You should ensure that, within each `Timeline`, every element has a +unique name. If you call this function with `name` as `None`, then +the library should ensure that the set generated name is unique from +previously **generated** names. However, if you choose a `name` that +interferes with the naming conventions of the library, the library will +attempt to ensure that the generated names will not conflict with the +chosen name, which may lead to a different name being set instead, but +the uniqueness between generated and user-chosen names is not +guaranteed. ## `name` -The name `self` should take (if avalaible<) - -Sets the parent of `self` to `parent`. The parents needs to already -own a hard reference on `self`. -## `parent` -new parent of self +The name `self` should take # Returns -`true` if `parent` could be set or `false` when `self` -already had a parent or `self` and `parent` are the same. - -Sets the priority of the object within the containing layer +`true` if `name` or a generated name for `self` could be set. + +Sets the `TimelineElement:parent` for the element. -# Deprecated +This is used internally and you should normally not call this. A +`Container` will set the `TimelineElement:parent` of its children +in `GESContainerExt::add` and `GESContainerExt::remove`. + +Note, if `parent` is not `None`, `self` must not already have a parent +set. Therefore, if you wish to switch parents, you will need to call +this function twice: first to set the parent to `None`, and then to the +new parent. + +If `parent` is not `None`, you must ensure it already has a +(non-floating) reference to `self` before calling this. + +# Returns + +`true` if `parent` could be set for `self`. + +Sets the priority of the element within the containing layer. + +# Deprecated since 1.10 All priority management is done by GES itself now. To set `Effect` priorities `ClipExt::set_top_effect_index` should be used. ## `priority` -the priority +The priority # Returns -`true` if `priority` could be set. +`true` if `priority` could be set for `self`. -Set the position of the object in its containing layer. +Sets `TimelineElement:start` for the element. If the element has a +parent, this will also move its siblings with the same shift. -Note that if the snapping-distance property of the timeline containing -`self` is set, `self` will properly snap to the edges around `start`. +Whilst the element is part of a `Timeline`, this is the same as +editing the element with `TimelineElementExt::edit` under +`EditMode::Normal` with `Edge::None`. In particular, the +`TimelineElement:start` of the element may be snapped to a different +timeline time from the one given. In addition, setting may fail if it +would place the timeline in an unsupported configuration. ## `start` -the position in `gst::ClockTime` +The desired start position of the element in its timeline # Returns -`true` if `start` could be set. +`true` if `start` could be set for `self`. -Sets the timeline of `self` to `timeline`. -## `timeline` -The `Timeline` `self` is in +Sets the `TimelineElement:timeline` of the element. + +This is used internally and you should normally not call this. A +`Clip` will have its `TimelineElement:timeline` set through its +`Layer`. A `Track` will similarly take care of setting the +`TimelineElement:timeline` of its `TrackElement`-s. A `Group` +will adopt the same `TimelineElement:timeline` as its children. + +If `timeline` is `None`, this will stop its current +`TimelineElement:timeline` from tracking it, otherwise `timeline` will +start tracking `self`. Note, in the latter case, `self` must not already +have a timeline set. Therefore, if you wish to switch timelines, you +will need to call this function twice: first to set the timeline to +`None`, and then to the new timeline. # Returns -`true` if `timeline` could be set or `false` when `timeline` -already had a timeline. +`true` if `timeline` could be set for `self`. -Edits `self` in trim mode. It allows you to modify the -inpoint and start of `self`. -This will not change the overall timeline duration. - -Note that to trim the end of an self you can just set its duration. The same way -as this method, it will take into account the snapping-distance property of the -timeline in which `self` is. +Edits the start time of an element within its timeline in trim mode. +See `TimelineElementExt::edit` with `EditMode::Trim` and +`Edge::Start`. ## `start` -The new start of `self` in trim mode, will adapt the inpoint -of `self` accordingly +The new start time of `self` in trim mode # Returns -`true` if the self as been trimmed properly, `false` if an error -occured - -The deep notify signal is used to be notified of property changes of all -the childs of `timeline_element` +`true` if the trim edit of `self` completed, `false` on failure. + +Emitted when the element has a new child property registered. See +`TimelineElementExt::add_child_property`. + +Note that some GES elements will be automatically created with +pre-registered children properties. You can use +`TimelineElementExt::list_children_properties` to list these. ## `prop_object` -the object that originated the signal +The child whose property has been registered ## `prop` -the property that changed +The specification for the property that has been registered + +Emitted when the element has a child property unregistered. See +`TimelineElementExt::remove_child_property`. +## `prop_object` +The child whose property has been unregistered +## `prop` +The specification for the property that has been unregistered + +Emitted when a child of the element has one of its registered +properties set. See `TimelineElementExt::add_child_property`. +Note that unlike `gobject::Object::notify`, a child property name can not be +used as a signal detail. +## `prop_object` +The child whose property has been set +## `prop` +The specification for the property that been set -The duration (in nanoseconds) which will be used in the container +The duration that the element is in effect for in the timeline (a +time difference in nanoseconds using the time coordinates of the +timeline). For example, for a source element, this would determine +for how long it should output its internal content for. For an +operation element, this would determine for how long its effect +should be applied to any source content. -The duration (in nanoseconds) which will be used in the container +The duration that the element is in effect for in the timeline (a +time difference in nanoseconds using the time coordinates of the +timeline). For example, for a source element, this would determine +for how long it should output its internal content for. For an +operation element, this would determine for how long its effect +should be applied to any source content. -The in-point at which this `TimelineElement` will start outputting data -from its contents (in nanoseconds). +The initial offset to use internally when outputting content (in +nanoseconds, but in the time coordinates of the internal content). -Ex : an in-point of 5 seconds means that the first outputted buffer will -be the one located 5 seconds in the controlled resource. +For example, for a `VideoUriSource` that references some media +file, the "internal content" is the media file data, and the +in-point would correspond to some timestamp in the media file. +When playing the timeline, and when the element is first reached at +timeline-time `TimelineElement:start`, it will begin outputting the +data from the timestamp in-point **onwards**, until it reaches the +end of its `TimelineElement:duration` in the timeline. + +For elements that have no internal content, this should be kept +as 0. -The in-point at which this `TimelineElement` will start outputting data -from its contents (in nanoseconds). +The initial offset to use internally when outputting content (in +nanoseconds, but in the time coordinates of the internal content). -Ex : an in-point of 5 seconds means that the first outputted buffer will -be the one located 5 seconds in the controlled resource. +For example, for a `VideoUriSource` that references some media +file, the "internal content" is the media file data, and the +in-point would correspond to some timestamp in the media file. +When playing the timeline, and when the element is first reached at +timeline-time `TimelineElement:start`, it will begin outputting the +data from the timestamp in-point **onwards**, until it reaches the +end of its `TimelineElement:duration` in the timeline. + +For elements that have no internal content, this should be kept +as 0. -The maximum duration (in nanoseconds) of the `TimelineElement`. +The full duration of internal content that is available (a time +difference in nanoseconds using the time coordinates of the internal +content). + +This will act as a cap on the `TimelineElement:in-point` of the +element (which is in the same time coordinates), and will sometimes +be used to limit the `TimelineElement:duration` of the element in +the timeline. + +For example, for a `VideoUriSource` that references some media +file, this would be the length of the media file. + +For elements that have no internal content, or whose content is +indefinite, this should be kept as `GST_CLOCK_TIME_NONE`. -The maximum duration (in nanoseconds) of the `TimelineElement`. +The full duration of internal content that is available (a time +difference in nanoseconds using the time coordinates of the internal +content). + +This will act as a cap on the `TimelineElement:in-point` of the +element (which is in the same time coordinates), and will sometimes +be used to limit the `TimelineElement:duration` of the element in +the timeline. + +For example, for a `VideoUriSource` that references some media +file, this would be the length of the media file. + +For elements that have no internal content, or whose content is +indefinite, this should be kept as `GST_CLOCK_TIME_NONE`. -The name of the object +The name of the element. This should be unique within its timeline. -The name of the object +The name of the element. This should be unique within its timeline. -The parent container of the object +The parent container of the element. -The parent container of the object +The parent container of the element. -The priority of the object. +The priority of the element. -Setting GESTimelineElement priorities is deprecated -as all priority management is done by GES itself now. +# Deprecated since 1.10 + +Priority management is now done by GES itself. -The priority of the object. +The priority of the element. -Setting GESTimelineElement priorities is deprecated -as all priority management is done by GES itself now. +# Deprecated since 1.10 + +Priority management is now done by GES itself. Whether the element should be serialized. Whether the element should be serialized. -The position of the object in its container (in nanoseconds). +The starting position of the element in the timeline (in nanoseconds +and in the time coordinates of the timeline). For example, for a +source element, this would determine the time at which it should +start outputting its internal content. For an operation element, this +would determine the time at which it should start applying its effect +to any source content. -The position of the object in its container (in nanoseconds). +The starting position of the element in the timeline (in nanoseconds +and in the time coordinates of the timeline). For example, for a +source element, this would determine the time at which it should +start outputting its internal content. For an operation element, this +would determine the time at which it should start applying its effect +to any source content. -The timeline in which `element` is +The timeline that the element lies within. -The timeline in which `element` is +The timeline that the element lies within. -Corresponds to one output format (i.e. audio OR video). +A `Track` acts an output source for a `Timeline`. Each one +essentially provides an additional `gst::Pad` for the timeline, with +`Track:restriction-caps` capabilities. Internally, a track +wraps an `nlecomposition` filtered by a `capsfilter`. -Contains the compatible TrackElement(s). +A track will contain a number of `TrackElement`-s, and its role is +to select and activate these elements according to their timings when +the timeline in played. For example, a track would activate a +`Source` when its `TimelineElement:start` is reached by outputting +its data for its `TimelineElement:duration`. Similarly, a +`Operation` would be activated by applying its effect to the source +data, starting from its `TimelineElement:start` time and lasting for +its `TimelineElement:duration`. + +For most users, it will usually be sufficient to add newly created +tracks to a timeline, but never directly add an element to a track. +Whenever a `Clip` is added to a timeline, the clip adds its +elements to the timeline's tracks and assumes responsibility for +updating them. # Implements @@ -1984,168 +3789,320 @@ Trait containing all `Track` methods. [`Track`](struct.Track.html) -Creates a new `Track` with the given `type_` and `caps`. +Creates a new track with the given track-type and caps. -The newly created track will steal a reference to the caps. If you wish to -use those caps elsewhere, you will have to take an extra reference. +If `type_` is `TrackType::Video`, and `caps` is a subset of +"video/x-raw(ANY)", then a `VideoTrack` is created. This will +automatically choose a gap creation method suitable for video data. You +will likely want to set `Track:restriction-caps` separately. You may +prefer to use the `VideoTrack::new` method instead. + +If `type_` is `TrackType::Audio`, and `caps` is a subset of +"audio/x-raw(ANY)", then a `AudioTrack` is created. This will +automatically choose a gap creation method suitable for audio data, and +will set the `Track:restriction-caps` to the default for +`AudioTrack`. You may prefer to use the `AudioTrack::new` method +instead. + +Otherwise, a plain `Track` is returned. You will likely want to set +the `Track:restriction-caps` and call +`GESTrackExt::set_create_element_for_gap_func` on the returned track. ## `type_` -The type of track +The `Track:track-type` for the track ## `caps` -The caps to restrict the output of the track to. +The `Track:caps` for the track # Returns -A new `Track`. +A new track. -Adds the given object to the track. Sets the object's controlling track, -and thus takes ownership of the `object`. - -An object can only be added to one track. +See `GESTrackExt::add_element`, which also gives an error. ## `object` -the `TrackElement` to add +The element to add # Returns -`true` if the object was properly added. `false` if the track does not -want to accept the object. +`true` if `object` was successfully added to `self`. + +Adds the given track element to the track, which takes ownership of the +element. + +Note that this can fail if it would break a configuration rule of the +track's `Timeline`. + +Note that a `TrackElement` can only be added to one track. + +Feature: `v1_18` + +## `object` +The element to add + +# Returns + +`true` if `object` was successfully added to `self`. -Commits all the pending changes of the TrackElement contained in the +Commits all the pending changes for the elements contained in the track. -When timing changes happen in a timeline, the changes are not -directly done inside NLE. This method needs to be called so any changes -on a clip contained in the timeline actually happen at the media -processing level. +When changes are made to the timing or priority of elements within a +track, they are not directly executed for the underlying +`nlecomposition` and its children. This method will finally execute +these changes so they are reflected in the data output of the track. + +Any pending changes will be executed in the backend. The +`Timeline::commited` signal will be emitted once this has completed. + +Note that `TimelineExt::commit` will call this method on all of its +tracks, so you are unlikely to need to use this directly. # Returns -`true` if something as been commited `false` if nothing needed -to be commited +`true` if pending changes were committed, or `false` if nothing +needed to be committed. -Get the `gst::Caps` this track is configured to output. +Get the `Track:caps` of the track. # Returns -The `gst::Caps` this track is configured to output. +The caps of `self`. -Gets the `TrackElement` contained in `self` +Gets the track elements contained in the track. The returned list is +sorted by the element's `TimelineElement:priority` and +`TimelineElement:start`. # Returns -the list of -`TrackElement` present in the Track sorted by priority and start. +A list of +all the `TrackElement`-s in `self`. -Gets if the underlying `NleComposition` contains an expandable mixer. +Gets the `Track:mixing` of the track. # Returns -`True` if there is a mixer, `False` otherwise. +Whether `self` is mixing. + +Gets the `Track:restriction-caps` of the track. + +Feature: `v1_18` + + +# Returns + +The restriction-caps of `self`. -Get the `Timeline` this track belongs to. Can be `None`. +Get the timeline this track belongs to. # Returns -The `Timeline` this track belongs to. Can be `None`. +The timeline that `self` belongs to, or `None` if +it does not belong to a timeline. -Removes the object from the track and unparents it. -Unparenting it means the reference owned by `self` on the `object` will be -removed. If you wish to use the `object` after this function, make sure you -call `gst::ObjectExt::ref` before removing it from the `self`. +See `GESTrackExt::remove_element_full`, which also returns an error. ## `object` -the `TrackElement` to remove +The element to remove # Returns -`true` if the object was removed, else `false` if the track -could not remove the object (like if it didn't belong to the track). - -Sets the function that should be used to create the GstElement used to fill gaps. -To avoid to provide such a function we advice you to use the -`AudioTrack::new` and `VideoTrack::new` constructor when possible. -## `func` -The `GESCreateElementForGapFunc` that will be used -to create `gst::Element` to fill gaps - -Sets if the `Track` should be mixing. -## `mixing` -TRUE if the track should be mixing, FALSE otherwise. - -Sets the given `caps` as the caps the track has to output. -## `caps` -the `gst::Caps` to set - -Sets `timeline` as the timeline controlling `self`. -## `timeline` -a `Timeline` - -Updates the restriction caps by modifying all the fields present in `caps` -in the original restriction caps. If for example the current restriction caps -are video/x-raw, format=I420, width=360 and `caps` is video/x-raw, format=RGB, -the restriction caps will be updated to video/x-raw, format=RGB, width=360. +`true` if `object` was successfully removed from `self`. + +Removes the given track element from the track, which revokes +ownership of the element. -Modification happens for each structure in the new caps, and -one can add new fields or structures through that function. +Feature: `v1_18` + +## `object` +The element to remove + +# Returns + +`true` if `object` was successfully removed from `self`. + +Sets the function that will be used to create a `gst::Element` that can be +used as a source to fill the gaps of the track. A gap is a timeline +region where the track has no `TrackElement` sources. Therefore, you +are likely to want the `gst::Element` returned by the function to always +produce 'empty' content, defined relative to the stream type, such as +transparent frames for a video, or mute samples for audio. + +`AudioTrack` and `VideoTrack` objects are created with such a +function already set appropriately. +## `func` +The function to be used to create a source +`gst::Element` that can fill gaps in `self` + +Sets the `Track:mixing` for the track. +## `mixing` +Whether `self` should be mixing + +Sets the `Track:restriction-caps` for the track. ## `caps` -the `gst::Caps` to update with +The new restriction-caps for `self` + +Informs the track that it belongs to the given timeline. Calling this +does not actually add the track to the timeline. For that, you should +use `TimelineExt::add_track`, which will also take care of informing +the track that it belongs to the timeline. As such, there is no need +for you to call this method. + +Updates the `Track:restriction-caps` of the track using the fields +found in the given caps. Each of the `gst::Structure`-s in `caps` is +compared against the existing structure with the same index in the +current `Track:restriction-caps`. If there is no corresponding +existing structure at that index, then the new structure is simply +copied to that index. Otherwise, any fields in the new structure are +copied into the existing structure. This will replace existing values, +and may introduce new ones, but any fields 'missing' in the new +structure are left unchanged in the existing structure. + +For example, if the existing `Track:restriction-caps` are +"video/x-raw, width=480, height=360", and the updating caps is +"video/x-raw, format=I420, width=500; video/x-bayer, width=400", then +the new `Track:restriction-caps` after calling this will be +"video/x-raw, width=500, height=360, format=I420; video/x-bayer, +width=400". +## `caps` +The caps to update the restriction-caps with + +This signal will be emitted once the changes initiated by +`GESTrackExt::commit` have been executed in the backend. In particular, +this will be emitted whenever the underlying `nlecomposition` has been +committed (see `nlecomposition::commited`). -Will be emitted after a track element was added to the track. +Will be emitted after a track element is added to the track. ## `effect` -the `TrackElement` that was added. +The element that was added -Will be emitted after a track element was removed from the track. +Will be emitted after a track element is removed from the track. ## `effect` -the `TrackElement` that was removed. +The element that was removed -Caps used to filter/choose the output stream. This is generally set to -a generic set of caps like 'video/x-raw' for raw video. +The capabilities used to choose the output of the `Track`'s +elements. Internally, this is used to select output streams when +several may be available, by determining whether its `gst::Pad` is +compatible (see `nlecomposition:caps` for `nlecomposition`). As such, +this is used as a weaker indication of the desired output type of the +track, **before** the `Track:restriction-caps` is applied. +Therefore, this should be set to a *generic* superset of the +`Track:restriction-caps`, such as "video/x-raw(ANY)". In addition, +it should match with the track's `Track:track-type`. + +Note that when you set this property, the `gst::CapsFeatures` of all its +`gst::Structure`-s will be automatically set to `GST_CAPS_FEATURES_ANY`. + +Once a track has been added to a `Timeline`, you should not change +this. Default value: `GST_CAPS_ANY`. -Caps used to filter/choose the output stream. This is generally set to -a generic set of caps like 'video/x-raw' for raw video. +The capabilities used to choose the output of the `Track`'s +elements. Internally, this is used to select output streams when +several may be available, by determining whether its `gst::Pad` is +compatible (see `nlecomposition:caps` for `nlecomposition`). As such, +this is used as a weaker indication of the desired output type of the +track, **before** the `Track:restriction-caps` is applied. +Therefore, this should be set to a *generic* superset of the +`Track:restriction-caps`, such as "video/x-raw(ANY)". In addition, +it should match with the track's `Track:track-type`. + +Note that when you set this property, the `gst::CapsFeatures` of all its +`gst::Structure`-s will be automatically set to `GST_CAPS_FEATURES_ANY`. + +Once a track has been added to a `Timeline`, you should not change +this. Default value: `GST_CAPS_ANY`. Current duration of the track Default value: O + +The `nlecomposition:id` of the underlying `nlecomposition`. + +Feature: `v1_18` + + +The `nlecomposition:id` of the underlying `nlecomposition`. + +Feature: `v1_18` + -Whether layer mixing is activated or not on the track. +Whether the track should support the mixing of `Layer` data, such +as composing the video data of each layer (when part of the video +data is transparent, the next layer will become visible) or adding +together the audio data. As such, for audio and video tracks, you'll +likely want to keep this set to `true`. -Whether layer mixing is activated or not on the track. +Whether the track should support the mixing of `Layer` data, such +as composing the video data of each layer (when part of the video +data is transparent, the next layer will become visible) or adding +together the audio data. As such, for audio and video tracks, you'll +likely want to keep this set to `true`. -Caps used to filter/choose the output stream. +The capabilities that specifies the final output format of the +`Track`. For example, for a video track, it would specify the +height, width, framerate and other properties of the stream. + +You may change this property after the track has been added to a +`Timeline`, but it must remain compatible with the track's +`Track:caps`. Default value: `GST_CAPS_ANY`. -Caps used to filter/choose the output stream. +The capabilities that specifies the final output format of the +`Track`. For example, for a video track, it would specify the +height, width, framerate and other properties of the stream. + +You may change this property after the track has been added to a +`Timeline`, but it must remain compatible with the track's +`Track:caps`. Default value: `GST_CAPS_ANY`. -Type of stream the track outputs. This is used when creating the `Track` -to specify in generic terms what type of content will be outputted. +The track type of the track. This controls the type of +`TrackElement`-s that can be added to the track. This should +match with the track's `Track:caps`. -It also serves as a 'fast' way to check what type of data will be outputted -from the `Track` without having to actually check the `Track`'s caps -property. +Once a track has been added to a `Timeline`, you should not change +this. -Type of stream the track outputs. This is used when creating the `Track` -to specify in generic terms what type of content will be outputted. +The track type of the track. This controls the type of +`TrackElement`-s that can be added to the track. This should +match with the track's `Track:caps`. -It also serves as a 'fast' way to check what type of data will be outputted -from the `Track` without having to actually check the `Track`'s caps -property. +Once a track has been added to a `Timeline`, you should not change +this. -`TrackElement` is the Base Class for any object that can be contained in a -`Track`. +A `TrackElement` is a `TimelineElement` that specifically belongs +to a single `Track` of its `TimelineElement:timeline`. Its +`TimelineElement:start` and `TimelineElement:duration` specify its +temporal extent in the track. Specifically, a track element wraps some +nleobject, such as an `nlesource` or `nleoperation`, which can be +retrieved with `TrackElementExt::get_nleobject`, and its +`TimelineElement:start`, `TimelineElement:duration`, +`TimelineElement:in-point`, `TimelineElement:priority` and +`TrackElement:active` properties expose the corresponding nleobject +properties. When a track element is added to a track, its nleobject is +added to the corresponding `nlecomposition` that the track wraps. -It contains the basic information as to the location of the object within -its container, like the start position, the inpoint, the duration and the -priority. +Most users will not have to work directly with track elements since a +`Clip` will automatically create track elements for its timeline's +tracks and take responsibility for updating them. The only track +elements that are not automatically created by clips, but a user is +likely to want to create, are `Effect`-s. + +## Control Bindings for Children Properties + +You can set up control bindings for a track element child property +using `TrackElementExt::set_control_source`. A +`GstTimedValueControlSource` should specify the timed values using the +internal source coordinates (see `TimelineElement`). By default, +these will be updated to lie between the `TimelineElement:in-point` +and out-point of the element. This can be switched off by setting +`TrackElement:auto-clamp-control-sources` to `false`. # Implements -[`TrackElementExt`](trait.TrackElementExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html) +[`TrackElementExt`](trait.TrackElementExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html), [`TimelineElementExtManual`](prelude/trait.TimelineElementExtManual.html) Trait containing all `TrackElement` methods. @@ -2153,47 +4110,92 @@ Trait containing all `TrackElement` methods. [`TrackElement`](struct.TrackElement.html) -Looks for the properties defines with the various parametters and add -them to the hashtable of children properties. +Adds all the properties of a `gst::Element` that match the criteria as +children properties of the track element. If the name of `element`'s +`gst::ElementFactory` is not in `blacklist`, and the factory's +`GST_ELEMENT_METADATA_KLASS` contains at least one member of +`wanted_categories` (e.g. `GST_ELEMENT_FACTORY_KLASS_DECODER`), then +all the properties of `element` that are also in `whitelist` are added as +child properties of `self` using +`TimelineElementExt::add_child_property`. -To be used by subclasses only +This is intended to be used by subclasses when constructing. ## `element` -The GstElement to retrieve properties from +The child object to retrieve properties from ## `wanted_categories` -An array of categories of GstElement to -take into account (as defined in the factory meta "klass" field) +An array of element factory "klass" categories to whitelist, or `None` +to accept all categories ## `blacklist` A -blacklist of elements factory names to not take into account +blacklist of element factory names, or `None` to not blacklist any +element factory ## `whitelist` -A list -of propery names to add as children properties +A +whitelist of element property names, or `None` to whitelist all +writeable properties + +Clamp the `GstTimedValueControlSource` for the specified child property +to lie between the `TimelineElement:in-point` and out-point of the +element. The out-point is the `GES_TIMELINE_ELEMENT_END` of the element +translated from the timeline coordinates to the internal source +coordinates of the element. + +If the property does not have a `GstTimedValueControlSource` set by +`TrackElementExt::set_control_source`, nothing happens. Otherwise, if +a timed value for the control source lies before the in-point of the +element, or after its out-point, then it will be removed. At the +in-point and out-point times, a new interpolated value will be placed. + +Feature: `v1_18` + +## `property_name` +The name of the child property to clamp the control +source of -Edit `self` in the different exisiting `EditMode` modes. In the case of -slide, and roll, you need to specify a `Edge` +Edits the element within its track. + +# Deprecated since 1.18 + +use `TimelineElementExt::edit` instead. ## `layers` -The layers you want the edit to - happen in, `None` means that the edition is done in all the - `GESLayers` contained in the current timeline. - FIXME: This is not implemented yet. +A whitelist of layers +where the edit can be performed, `None` allows all layers in the +timeline ## `mode` -The `EditMode` in which the edition will happen. +The edit mode ## `edge` -The `Edge` the edit should happen on. +The edge of `self` where the edit should occur ## `position` -The position at which to edit `self` (in nanosecond) +The edit position: a new location for the edge of `self` +(in nanoseconds) # Returns -`true` if the object as been edited properly, `false` if an error -occured +`true` if the edit of `self` completed, `false` on failure. +Get all the control bindings that have been created for the children +properties of the track element using +`TrackElementExt::set_control_source`. The keys used in the returned +hash table are the child property names that were passed to +`TrackElementExt::set_control_source`, and their values are the +corresponding created `gst::ControlBinding`. # Returns A -`glib::HashTable` containing all property_name: GstControlBinding +hash table containing all child-property-name/control-binding pairs +for `self`. + +Gets `TrackElement:auto-clamp-control-sources`. + +Feature: `v1_18` + + +# Returns + +Whether the control sources for the child properties of +`self` are automatically clamped. Gets properties of a child of `self`. @@ -2224,7 +4226,7 @@ be initialized if it is initialized with 0 # Returns -`true` if the property was found, `false` otherwize +`true` if the property was found, `false` otherwize. Gets a property of a child of `self`. @@ -2247,27 +4249,33 @@ Use `TimelineElementExt::get_child_property_valist` ## `first_property_name` The name of the first property to get ## `var_args` -value for the first property, followed optionally by more +Value for the first property, followed optionally by more name/return location pairs, followed by NULL -Looks up the various controlled properties for that `TrackElement`, -and returns the `gst::ControlBinding` which controls `property_name`. +Gets the control binding that was created for the specified child +property of the track element using +`TrackElementExt::set_control_source`. The given `property_name` must +be the same name of the child property that was passed to +`TrackElementExt::set_control_source`. ## `property_name` -The property_name to which the binding is associated. +The name of the child property to return the control +binding of # Returns -the `gst::ControlBinding` associated with -`property_name`, or `None` if that property is not controlled. +The control binding that was +created for the specified child property of `self`, or `None` if +`property_name` does not correspond to any control binding. -Get the `gst::Element` this track element is controlling within GNonLin. +Get the `gst::Element` that the track element's underlying nleobject +controls. # Returns -the `gst::Element` this track element is controlling -within GNonLin. +The `gst::Element` being controlled by the +nleobject that `self` wraps. -Get the NleObject object this object is controlling. +Get the GNonLin object this object is controlling. # Deprecated @@ -2275,27 +4283,60 @@ use `TrackElementExt::get_nleobject` instead. # Returns -the NleObject object this object is controlling. +The GNonLin object this object is controlling. -Get the GNonLin object this object is controlling. +Get the nleobject that this element wraps. # Returns -the GNonLin object this object is controlling. +The nleobject that `self` wraps. -Get the `Track` to which this object belongs. +Get the `TrackElement:track` for the element. # Returns -The `Track` to which this object -belongs. Can be `None` if it is not in any track +The track that `self` belongs to, +or `None` if it does not belong to a track. + +Gets the `TrackElement:track-type` for the element. + +# Returns + +The track-type of `self`. + +Gets `TrackElement:has-internal-source` for the element. + +# Returns + +`true` if `self` can have its 'internal time' properties set. -Lets you know if `self` will be used for playback and rendering, -or not. +Gets `TrackElement:active` for the element. # Returns -`true` if `self` is active, `false` otherwize +`true` if `self` is active in its track. + +Get whether the given track element is a core track element. That is, +it was created by the `create_track_elements` `ClipClass` method for +some `Clip`. + +Note that such a track element can only be added to a clip that shares +the same `Asset` as the clip that created it. For example, you are +allowed to move core children between clips that resulted from +`GESContainerExt::ungroup`, but you could not move the core child from a +`UriClip` to a `TitleClip` or another `UriClip` with a different +`UriClip:uri`. + +Moreover, if a core track element is added to a clip, it will always be +added as a core child. Therefore, if this returns `true`, then `element` +will be a core child of its parent clip. + +Feature: `v1_18` + + +# Returns + +`true` if `element` is a core track element. Gets an array of `gobject::ParamSpec`* for all configurable properties of the children of `self`. @@ -2308,8 +4349,8 @@ return location for the length of the returned array # Returns -an array of `gobject::ParamSpec`* which should be freed after use or -`None` if something went wrong +An array of `gobject::ParamSpec`* which should be freed after use or +`None` if something went wrong. Looks up which `element` and `pspec` would be effected by the given `name`. If various contained elements have this property name you will get the first one, unless you @@ -2319,7 +4360,7 @@ specify the class name in `name`. Use `TimelineElementExt::lookup_child` ## `prop_name` -name of the property to look up. You can specify the name of the +Name of the property to look up. You can specify the name of the class as such: "ClassName::property-name", to guarantee that you get the proper GParamSpec in case various GstElement-s contain the same property name. If you don't do so, you will get the first element found, having @@ -2328,7 +4369,7 @@ name of the property to look up. You can specify the name of the pointer to a `gst::Element` that takes the real object to set property on ## `pspec` -pointer to take the `gobject::ParamSpec` +pointer to take the specification describing the property # Returns @@ -2337,23 +4378,36 @@ TRUE if `element` and `pspec` could be found. FALSE otherwise. In that case the values for `pspec` and `element` are not modified. Unref `element` after usage. -Removes a `gst::ControlBinding` from `self`. +Removes the `gst::ControlBinding` that was created for the specified child +property of the track element using +`TrackElementExt::set_control_source`. The given `property_name` must +be the same name of the child property that was passed to +`TrackElementExt::set_control_source`. ## `property_name` -The name of the property to control. +The name of the child property to remove the control +binding from # Returns -`true` if the binding could be removed, `false` if an error -occured +`true` if the control binding was removed from the specified +child property of `self`, or `false` if an error occurred. -Sets the usage of the `self`. If `active` is `true`, the object will be used for -playback and rendering, else it will be ignored. +Sets `TrackElement:active` for the element. ## `active` -visibility +Whether `self` should be active in its track # Returns -`true` if the property was toggled, else `false` +`true` if the property was *toggled*. + +Sets `TrackElement:auto-clamp-control-sources`. If set to `true`, this +will immediately clamp all the control sources. + +Feature: `v1_18` + +## `auto_clamp` +Whether to automatically clamp the control sources for the +child properties of `self` Sets a property of a child of `self`. If there are various child elements that have the same property name, you can distinguish them using the following @@ -2378,11 +4432,11 @@ use `TimelineElementExt::set_child_property` instead ## `property_name` The name of the property ## `value` -the value +The value # Returns -`true` if the property was set, `false` otherwize +`true` if the property was set, `false` otherwize. Sets a property of a child of `self`. @@ -2392,7 +4446,7 @@ Use `ges_timeline_element_set_child_property_by_spec` ## `pspec` The `gobject::ParamSpec` that specifies the property you want to set ## `value` -the value +The value Sets a property of a child of `self`. If there are various child elements that have the same property name, you can distinguish them using the following @@ -2405,48 +4459,170 @@ Use `TimelineElementExt::set_child_property_valist` ## `first_property_name` The name of the first property to set ## `var_args` -value for the first property, followed optionally by more +Value for the first property, followed optionally by more name/return location pairs, followed by NULL -Creates a `gst::ControlBinding` and adds it to the `gst::Element` concerned by the -property. Use the same syntax as `TrackElementExt::lookup_child` for -the property name. +Creates a `gst::ControlBinding` for the specified child property of the +track element using the given control source. The given `property_name` +should refer to an existing child property of the track element, as +used in `TimelineElementExt::lookup_child`. + +If `binding_type` is "direct", then the control binding is created with +`gst_direct_control_binding_new` using the given control source. If +`binding_type` is "direct-absolute", it is created with +`gst_direct_control_binding_new_absolute` instead. ## `source` -the `gst::ControlSource` to set on the binding. +The control source to bind the child property to ## `property_name` -The name of the property to control. +The name of the child property to control ## `binding_type` -The type of binding to create. Currently the following values are valid: - - "direct": See `gst_direct_control_binding_new` - - "direct-absolute": See `gst_direct_control_binding_new_absolute` +The type of binding to create ("direct" or +"direct-absolute") # Returns -`true` if the binding could be created and added, `false` if an error -occured +`true` if the specified child property could be bound to +`source`, or `false` if an error occurred. + +Sets `TrackElement:has-internal-source` for the element. If this is +set to `false`, this method will also set the +`TimelineElement:in-point` of the element to 0 and its +`TimelineElement:max-duration` to `GST_CLOCK_TIME_NONE`. +## `has_internal_source` +Whether the `self` should be allowed to have its +'internal time' properties set. + +Sets the `TrackElement:track-type` for the element. +## `type_` +The new track-type for `self` -The control-binding-added signal is emitted each time a control binding -is added for a child property of `track_element` +This is emitted when a control binding is added to a child property +of the track element. ## `control_binding` -the `gst::ControlBinding` that has been added +The control binding that has been added -The control-binding-removed signal is emitted each time a control binding -is removed for a child property of `track_element` +This is emitted when a control binding is removed from a child +property of the track element. ## `control_binding` -the `gst::ControlBinding` that has been removed +The control binding that has been removed -Whether the object should be taken into account in the `Track` output. -If `false`, then its contents will not be used in the resulting track. +Whether the effect of the element should be applied in its +`TrackElement:track`. If set to `false`, it will not be used in +the output of the track. -Whether the object should be taken into account in the `Track` output. -If `false`, then its contents will not be used in the resulting track. +Whether the effect of the element should be applied in its +`TrackElement:track`. If set to `false`, it will not be used in +the output of the track. + +Whether the control sources on the element (see +`TrackElementExt::set_control_source`) will be automatically +updated whenever the `TimelineElement:in-point` or out-point of the +element change in value. + +See `TrackElementExt::clamp_control_source` for how this is done +per control source. + +Default value: `true` + +Whether the control sources on the element (see +`TrackElementExt::set_control_source`) will be automatically +updated whenever the `TimelineElement:in-point` or out-point of the +element change in value. + +See `TrackElementExt::clamp_control_source` for how this is done +per control source. + +Default value: `true` + +This property is used to determine whether the 'internal time' +properties of the element have any meaning. In particular, unless +this is set to `true`, the `TimelineElement:in-point` and +`TimelineElement:max-duration` can not be set to any value other +than the default 0 and `GST_CLOCK_TIME_NONE`, respectively. + +If an element has some *internal* *timed* source `gst::Element` that it +reads stream data from as part of its function in a `Track`, then +you'll likely want to set this to `true` to allow the +`TimelineElement:in-point` and `TimelineElement:max-duration` to +be set. + +The default value is determined by the `TrackElementClass` +`default_has_internal_source` class property. For most +`SourceClass`-es, this will be `true`, with the exception of those +that have a potentially *static* source, such as `ImageSourceClass` +and `TitleSourceClass`. Otherwise, this will usually be `false`. + +For most `Operation`-s you will likely want to leave this set to +`false`. The exception may be for an operation that reads some stream +data from some private internal source as part of manipulating the +input data from the usual linked upstream `TrackElement`. + +For example, you may want to set this to `true` for a +`TrackType::Video` operation that wraps a `textoverlay` that reads +from a subtitle file and places its text on top of the received video +data. The `TimelineElement:in-point` of the element would be used +to shift the initial seek time on the `textoverlay` away from 0, and +the `TimelineElement:max-duration` could be set to reflect the +time at which the subtitle file runs out of data. + +Note that GES can not support track elements that have both internal +content and manipulate the timing of their data streams (time +effects). + +This property is used to determine whether the 'internal time' +properties of the element have any meaning. In particular, unless +this is set to `true`, the `TimelineElement:in-point` and +`TimelineElement:max-duration` can not be set to any value other +than the default 0 and `GST_CLOCK_TIME_NONE`, respectively. + +If an element has some *internal* *timed* source `gst::Element` that it +reads stream data from as part of its function in a `Track`, then +you'll likely want to set this to `true` to allow the +`TimelineElement:in-point` and `TimelineElement:max-duration` to +be set. + +The default value is determined by the `TrackElementClass` +`default_has_internal_source` class property. For most +`SourceClass`-es, this will be `true`, with the exception of those +that have a potentially *static* source, such as `ImageSourceClass` +and `TitleSourceClass`. Otherwise, this will usually be `false`. + +For most `Operation`-s you will likely want to leave this set to +`false`. The exception may be for an operation that reads some stream +data from some private internal source as part of manipulating the +input data from the usual linked upstream `TrackElement`. + +For example, you may want to set this to `true` for a +`TrackType::Video` operation that wraps a `textoverlay` that reads +from a subtitle file and places its text on top of the received video +data. The `TimelineElement:in-point` of the element would be used +to shift the initial seek time on the `textoverlay` away from 0, and +the `TimelineElement:max-duration` could be set to reflect the +time at which the subtitle file runs out of data. + +Note that GES can not support track elements that have both internal +content and manipulate the timing of their data streams (time +effects). + +The track that this element belongs to, or `None` if it does not +belong to a track. + +The track type of the element, which determines the type of track the +element can be added to (see `Track:track-type`). This should +correspond to the type of data that the element can produce or +process. + +The track type of the element, which determines the type of track the +element can be added to (see `Track:track-type`). This should +correspond to the type of data that the element can produce or +process. Represents all the output streams from a particular uri. It is assumed that the URI points to a file of some type. # Implements -[`UriClipExt`](trait.UriClipExt.html), [`ClipExt`](trait.ClipExt.html), [`GESContainerExt`](trait.GESContainerExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html) +[`UriClipExt`](trait.UriClipExt.html), [`ClipExt`](trait.ClipExt.html), [`GESContainerExt`](trait.GESContainerExt.html), [`TimelineElementExt`](trait.TimelineElementExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ExtractableExt`](trait.ExtractableExt.html), [`TimelineElementExtManual`](prelude/trait.TimelineElementExtManual.html) Trait containing all `UriClip` methods. @@ -2503,10 +4679,7 @@ The location of the file/resource to use. The location of the file/resource to use. -The `UriClipAsset` is a special `Asset` that lets you handle -the media file to use inside the GStreamer Editing Services. It has APIs that -let you get information about the medias. Also, the tags found in the media file are -set as Metadata of the Asset. + # Implements @@ -2589,6 +4762,18 @@ Gets `gst_pbutils::DiscovererInfo` about the file # Returns `gst_pbutils::DiscovererInfo` of specified asset + +Gets maximum duration of the file represented by `self`, +it is usually the same as GESUriClipAsset::duration, +but in the case of nested timelines, for example, they +are different as those can be extended 'infinitely'. + +Feature: `v1_18` + + +# Returns + +The maximum duration of `self` Get the GESUriSourceAsset `self` containes @@ -2606,7 +4791,14 @@ Whether the file represented by `self` is an image or not The duration (in nanoseconds) of the media file The duration (in nanoseconds) of the media file + +The duration (in nanoseconds) of the media file + +Feature: `v1_18` + +Asset to create a stream specific `Source` for a media file. + NOTE: You should never request such a `Asset` as they will be created automatically by `UriClipAsset`-s. @@ -2631,3 +4823,10 @@ Get the `gst_pbutils::DiscovererStreamInfo` user by `self` # Returns a `UriClipAsset` + +Check if `self` contains a single image + +# Returns + +`true` if the video stream corresponds to an image (i.e. only +contains one frame) diff --git a/docs/gstreamer-gl/docs.md b/docs/gstreamer-gl/docs.md index 19f815c33..39b1c1bb1 100644 --- a/docs/gstreamer-gl/docs.md +++ b/docs/gstreamer-gl/docs.md @@ -2,8 +2,8 @@ `GLBaseFilter` handles the nitty gritty details of retrieving an OpenGL context. It also provided some wrappers around `gst_base::BaseTransform`'s -`start`, `stop` and `set_caps` virtual methods that ensure an OpenGL context -is available and current in the calling thread. +`start()`, `stop()` and `set_caps()` virtual methods that ensure an OpenGL +context is available and current in the calling thread. Feature: `v1_16` @@ -26,14 +26,14 @@ Feature: `v1_16` # Returns Whether an OpenGL context could be retrieved or created successfully - -GstGLBuffer is a `gst::Memory` subclass providing support for the mapping of -GL buffers. + -Data is uploaded or downloaded from the GPU as is necessary. - -Initializes the GL Buffer allocator. It is safe to call this function -multiple times. This must be called before any other `GLBuffer` operation. +Feature: `v1_18` + + +# Returns + +the `GLContext` found by `self` `GLColorConvert` is an object that converts between color spaces and/or formats using OpenGL Shaders. @@ -113,7 +113,7 @@ specified and must only be activated in a single thread. # Implements -[`GLContextExt`](trait.GLContextExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`GLContextExt`](trait.GLContextExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`GLContextExtManual`](prelude/trait.GLContextExtManual.html) Trait containing all `GLContext` methods. @@ -134,6 +134,10 @@ Wraps an existing OpenGL context into a `GLContext`. Note: The caller is responsible for ensuring that the OpenGL context represented by `handle` stays alive while the returned `GLContext` is active. + +`context_type` must not be `GLPlatform::None` or `GLPlatform::Any` + +`available_apis` must not be `GLAPI::None` or `GLAPI::Any` ## `display` a `GLDisplay` ## `handle` @@ -188,7 +192,7 @@ a `GLPlatform` specifying the type of context to retrieve The OpenGL context handle current in the calling thread or `None` Attempts to use the `context_type` specific GetProcAddress implementations -to retreive `name`. +to retrieve `name`. See also `GLContext::get_proc_address`. ## `context_type` @@ -318,7 +322,7 @@ return for the major version return for the minor version Returns the OpenGL version implemented by `self`. See -`GLContextExt::get_gl_api` for retreiving the OpenGL api implemented by +`GLContextExt::get_gl_api` for retrieving the OpenGL api implemented by `self`. ## `maj` resulting major version @@ -328,7 +332,7 @@ resulting minor version Get a function pointer to a specified opengl function, `name`. If the the specific function does not exist, NULL is returned instead. -Platform specfic functions (names starting 'egl', 'glX', 'wgl', etc) can also +Platform specific functions (names starting 'egl', 'glX', 'wgl', etc) can also be retrieved using this method. Note: This function may return valid function pointers that may not be valid @@ -440,7 +444,7 @@ glXCreateContext (or similar) failed A resource is not available `GLDisplay` represents a connection to the underlying windowing system. -Elements are required to make use of `gst::Context` to share and propogate +Elements are required to make use of `gst::Context` to share and propagate a `GLDisplay`. There are a number of environment variables that influence the choice of @@ -495,7 +499,6 @@ resulting `GLContext` whether a new context could be created. -It requires the display's object lock to be held. # Returns @@ -503,13 +506,15 @@ a new `GLWindow` for `self` or `None`. limit the use of OpenGL to the requested `gl_api`. This is intended to allow application and elements to request a specific set of OpenGL API's based on -what they support. See `GLContextExt::get_gl_api` for the retreiving the +what they support. See `GLContextExt::get_gl_api` for the retrieving the API supported by a `GLContext`. ## `gl_api` a `GLAPI` to filter with +Deprecated for `GLDisplayExt::retrieve_window`. + Execute `compare_func` over the list of windows stored by `self`. The -first argment to `compare_func` is the `GLWindow` being checked and the +first argument to `compare_func` is the `GLWindow` being checked and the second argument is `data`. ## `data` some data to pass to `compare_func` @@ -520,6 +525,14 @@ a comparison function to run The first `GLWindow` that causes a match from `compare_func` + + +Feature: `v1_18` + + +# Returns + +whether the context belongs to a foreign display see `GLDisplayExt::filter_gl_api` for what the returned value represents @@ -545,6 +558,13 @@ the native handle for the display # Returns the `GLDisplayType` of `self` + +Must be called with the object lock held. + +Feature: `v1_18` + +## `context` +the `GLContext` to remove ## `window` a `GLWindow` to remove @@ -552,6 +572,22 @@ a `GLWindow` to remove # Returns if `window` could be removed from `self` + +Execute `compare_func` over the list of windows stored by `self`. The +first argument to `compare_func` is the `GLWindow` being checked and the +second argument is `data`. + +Feature: `v1_18` + +## `data` +some data to pass to `compare_func` +## `compare_func` +a comparison function to run + +# Returns + +The first `GLWindow` that causes a match + from `compare_func` Overrides the `GLContext` creation mechanism. It can be called in any thread and it is emitted with @@ -595,7 +631,7 @@ through the provided API [`GLDisplayExt`](trait.GLDisplayExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) -Create a new `GLDisplayWayland` from the wayland display name. See `wl_display_connect` +Create a new `GLDisplayWayland` from the wayland display name. See `wl_display_connect`() for details on what is a valid name. ## `name` a display name @@ -619,7 +655,7 @@ through the provided API [`GLDisplayExt`](trait.GLDisplayExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) -Create a new `GLDisplayX11` from the x11 display name. See XOpenDisplay() +Create a new `GLDisplayX11` from the x11 display name. See `XOpenDisplay`() for details on what is a valid name. ## `name` a display name @@ -676,6 +712,10 @@ A single 16-bit component for depth information. A 24-bit component for depth information and a 8-bit component for stencil informat. + +Single 16-bit component stored in the R texture component + +Two 16-bit components stored in the R and G texture components A `GLFramebuffer` represents and holds an OpenGL framebuffer object with it's associated attachments. @@ -737,7 +777,7 @@ data to pass to `func` the result of executing `func` -Retreive the effective dimensions from the current attachments attached to +Retrieve the effective dimensions from the current attachments attached to `self`. ## `width` output width @@ -754,54 +794,6 @@ Opaque `GLOverlayCompositor` object # Implements [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) - -A `GLQuery` represents and holds an OpenGL query object. Various types of -queries can be run or counters retrieved. - -Record the result of a counter - -End counting the query - -Frees a `GLQuery` - -## `context` -a `GLContext` -## `query_type` -the `GLQueryType` - - -# Returns - -the result of the query - -Start counting the query - -Free any dynamically allocated resources - -Performs a GST_QUERY_CONTEXT query of type "gst.gl.local_context" on all -`GstPads` in `element` of `direction` for the local OpenGL context used by -GStreamer elements. -## `element` -a `gst::Element` to query from -## `direction` -the `gst::PadDirection` to query -## `context_ptr` -location containing the current and/or resulting - `GLContext` - -# Returns - -whether `context_ptr` contains a `GLContext` - -Free with `GLQuery::free` -## `context` -a `GLContext` -## `query_type` -the `GLQueryType` to create - -# Returns - -a new `GLQuery` no query @@ -812,11 +804,11 @@ query the current time Compilation stage that caused an error -Compilation error occured +Compilation error occurred -Link error occured +Link error occurred -General program error occured +General program error occurred `GLSLStage` holds and represents a single OpenGL shader stage. @@ -869,7 +861,7 @@ a new `GLSLStage` of the specified `type_` # Returns -whether the compilation suceeded +whether the compilation succeeded # Returns @@ -1061,14 +1053,14 @@ a `GLSLStage` to attach whether `stage` could be attached to `self` Bind attribute `name` to the specified location `index` using -glBindAttributeLocation(). +`glBindAttributeLocation()`. ## `index` attribute index to set ## `name` name of the attribute Bind attribute `name` to the specified location `index` using -glBindFragDataLocation(). +`glBindFragDataLocation()`. ## `index` attribute index to set ## `name` @@ -1132,13 +1124,13 @@ Releases the shader and stages. Note: must be called in the GL thread -Perform glUniform1f() for `name` on `self` +Perform `glUniform1f()` for `name` on `self` ## `name` name of the uniform ## `value` value to set -Perform glUniform1fv() for `name` on `self` +Perform `glUniform1fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1146,13 +1138,13 @@ number of values to set ## `value` values to set -Perform glUniform1i() for `name` on `self` +Perform `glUniform1i()` for `name` on `self` ## `name` name of the uniform ## `value` value to set -Perform glUniform1iv() for `name` on `self` +Perform `glUniform1iv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1160,7 +1152,7 @@ number of values to set ## `value` values to set -Perform glUniform2f() for `name` on `self` +Perform `glUniform2f()` for `name` on `self` ## `name` name of the uniform ## `v0` @@ -1168,7 +1160,7 @@ first value to set ## `v1` second value to set -Perform glUniform2fv() for `name` on `self` +Perform `glUniform2fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1176,7 +1168,7 @@ number of values to set ## `value` values to set -Perform glUniform2i() for `name` on `self` +Perform `glUniform2i()` for `name` on `self` ## `name` name of the uniform ## `v0` @@ -1184,7 +1176,7 @@ first value to set ## `v1` second value to set -Perform glUniform2iv() for `name` on `self` +Perform `glUniform2iv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1192,7 +1184,7 @@ number of values to set ## `value` values to set -Perform glUniform3f() for `name` on `self` +Perform `glUniform3f()` for `name` on `self` ## `name` name of the uniform ## `v0` @@ -1202,7 +1194,7 @@ second value to set ## `v2` third value to set -Perform glUniform3fv() for `name` on `self` +Perform `glUniform3fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1210,7 +1202,7 @@ number of values to set ## `value` values to set -Perform glUniform3i() for `name` on `self` +Perform `glUniform3i()` for `name` on `self` ## `name` name of the uniform ## `v0` @@ -1220,7 +1212,7 @@ second value to set ## `v2` third value to set -Perform glUniform3iv() for `name` on `self` +Perform `glUniform3iv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1228,7 +1220,7 @@ number of values to set ## `value` values to set -Perform glUniform4f() for `name` on `self` +Perform `glUniform4f()` for `name` on `self` ## `name` name of the uniform ## `v0` @@ -1240,7 +1232,7 @@ third value to set ## `v3` fourth value to set -Perform glUniform4fv() for `name` on `self` +Perform `glUniform4fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1248,7 +1240,7 @@ number of values to set ## `value` values to set -Perform glUniform4i() for `name` on `self` +Perform `glUniform4i()` for `name` on `self` ## `name` name of the uniform ## `v0` @@ -1260,7 +1252,7 @@ third value to set ## `v3` fourth value to set -Perform glUniform4iv() for `name` on `self` +Perform `glUniform4iv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1268,7 +1260,7 @@ number of values to set ## `value` values to set -Perform glUniformMatrix2fv() for `name` on `self` +Perform `glUniformMatrix2fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1278,7 +1270,7 @@ transpose the matrix ## `value` matrix to set -Perform glUniformMatrix2x3fv() for `name` on `self` +Perform `glUniformMatrix2x3fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1288,7 +1280,7 @@ transpose the matrix ## `value` values to set -Perform glUniformMatrix2x4fv() for `name` on `self` +Perform `glUniformMatrix2x4fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1298,7 +1290,7 @@ transpose the matrix ## `value` values to set -Perform glUniformMatrix3fv() for `name` on `self` +Perform `glUniformMatrix3fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1308,7 +1300,7 @@ transpose the matrix ## `value` values to set -Perform glUniformMatrix3x2fv() for `name` on `self` +Perform `glUniformMatrix3x2fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1318,7 +1310,7 @@ transpose the matrix ## `value` values to set -Perform glUniformMatrix3x4fv() for `name` on `self` +Perform `glUniformMatrix3x4fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1328,7 +1320,7 @@ transpose the matrix ## `value` values to set -Perform glUniformMatrix4fv() for `name` on `self` +Perform `glUniformMatrix4fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1338,7 +1330,7 @@ transpose the matrix ## `value` values to set -Perform glUniformMatrix4x2fv() for `name` on `self` +Perform `glUniformMatrix4x2fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1348,7 +1340,7 @@ transpose the matrix ## `value` values to set -Perform glUniformMatrix4x3fv() for `name` on `self` +Perform `glUniformMatrix4x3fv()` for `name` on `self` ## `name` name of the uniform ## `count` @@ -1429,11 +1421,13 @@ whether `in_caps` and `out_caps` could be set on `self` No further processing required -An unspecified error occured +An unspecified error occurred The configuration is unsupported. This element requires a reconfiguration. + +private return value. Convert stereoscopic/multiview video using fragment shaders. @@ -1568,6 +1562,15 @@ for them. This method allows you to disable events handling completely from the `self`. ## `handle_events` a `gboolean` indicating if events should be handled or not. + +Query whether `self` has output surface or not + +Feature: `v1_18` + + +# Returns + +`true` if `self` has useable output surface Queue resizing of `self`. @@ -1581,7 +1584,7 @@ new height Start the execution of the runloop. -Invoke `callback` with data on the window thread. `callback` is guarenteed to +Invoke `callback` with data on the window thread. `callback` is guaranteed to have executed when this function returns. ## `callback` function to invoke @@ -1596,6 +1599,20 @@ function to invoke data to invoke `callback` with ## `destroy` called when `data` is not needed anymore + +Notify a `self` about a scroll event. A scroll signal holding the event +coordinates will be emitted. + +Feature: `v1_18` + +## `posx` +x position of the mouse cursor +## `posy` +y position of the mouse cursor +## `delta_x` +the x offset of the scroll event +## `delta_y` +the y offset of the scroll event Sets the callback called when the window is about to close. ## `callback` @@ -1605,7 +1622,7 @@ data to invoke `callback` with ## `destroy_notify` called when `data` is not needed any more -Sets the draw callback called everytime `GLWindowExt::draw` is called +Sets the draw callback called every time `GLWindowExt::draw` is called ## `callback` function to invoke ## `data` @@ -1635,7 +1652,7 @@ height whether the specified region could be set -Sets the resize callback called everytime a resize of the window occurs. +Sets the resize callback called every time a resize of the window occurs. ## `callback` function to invoke ## `data` @@ -1665,6 +1682,19 @@ the id of the button the x coordinate of the mouse event ## `y` the y coordinate of the mouse event + +Will be emitted when a mouse scroll event is received by the GstGLwindow. + +Feature: `v1_18` + +## `x` +the x coordinate of the mouse event +## `y` +the y coordinate of the mouse event +## `delta_x` +the x offset of the scroll event +## `delta_y` +the y offset of the scroll event failed for a unspecified reason diff --git a/docs/gstreamer-net/docs.md b/docs/gstreamer-net/docs.md index 8b87249a1..b96e9fc2b 100644 --- a/docs/gstreamer-net/docs.md +++ b/docs/gstreamer-net/docs.md @@ -27,7 +27,7 @@ statistics about clock accuracy and network traffic. [`gst::ClockExt`](../gst/trait.ClockExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) -Create a new `GstNetClientInternalClock` that will report the time +Create a new `NetClientClock` that will report the time provided by the `NetTimeProvider` on `remote_address` and `remote_port`. ## `name` diff --git a/docs/gstreamer-pbutils/docs.md b/docs/gstreamer-pbutils/docs.md index 9761e62ad..bc8b15c4a 100644 --- a/docs/gstreamer-pbutils/docs.md +++ b/docs/gstreamer-pbutils/docs.md @@ -231,7 +231,7 @@ Get the installer details for missing elements # Returns An array of strings -containing informations about how to install the various missing elements +containing information about how to install the various missing elements for `self` to be usable. If you wish to use the strings after the life-time of `self`, you will need to copy them. @@ -367,7 +367,7 @@ a `glib::List` of `DiscovererStreamInfo` # Returns the `gst::Caps` of the stream. Unref with -`gst_caps_unref` after usage. +`gst::Caps::unref` after usage. # Deprecated @@ -509,7 +509,7 @@ the `gst::Caps` the preset(s) to use on the encoder, can be `None` ## `restriction` the `gst::Caps` used to restrict the input to the encoder, can be -NULL. See `EncodingProfileExt::get_restriction` for more details. +NULL. See `EncodingProfile::get_restriction` for more details. ## `presence` the number of time this stream must be used. 0 means any number of times (including never) @@ -635,7 +635,7 @@ Computes the full output caps that this `self` will be able to consume. # Returns The full caps the given `self` can consume. Call -`gst_caps_unref` when you are done with the caps. +`gst::Caps::unref` when you are done with the caps. # Returns @@ -668,6 +668,16 @@ properties of the raw stream (that is before encoding), such as height and width for video and depth and sampling rate for audio. Does not apply to `EncodingContainerProfile` (since there is no corresponding raw stream). Can be `None`. Unref after usage. + + +Feature: `v1_18` + + +# Returns + +`true` if the stream represented by `self` should use a single +segment before the encoder, `false` otherwise. This means that buffers will be retimestamped +and segments will be eat so as to appear as one segment. # Returns @@ -695,7 +705,7 @@ the description to set on the profile Set whether the profile should be used or not. ## `enabled` -`false` to disable `profile`, `true` to enable it +`false` to disable `self`, `true` to enable it Sets the media format used in the profile. ## `format` @@ -722,10 +732,19 @@ Sets the name of the `gst::Preset`'s factory to be used in the profile. The name of the preset to use in this `self`. Set the restriction `gst::Caps` to apply before the encoder -that will be used in the profile. See `EncodingProfileExt::get_restriction` +that will be used in the profile. See `EncodingProfile::get_restriction` for more about restrictions. Does not apply to `EncodingContainerProfile`. ## `restriction` the restriction to apply + +If using a single segment, buffers will be retimestamped +and segments will be eat so as to appear as one segment. + +Feature: `v1_18` + +## `single_segment` +`true` if the stream represented by `self` should use a single +segment before the encoder `false` otherwise. Collection of `EncodingProfile` for a specific target or use-case. @@ -742,9 +761,9 @@ The name and category can only consist of lowercase ASCII letters for the first character, followed by either lowercase ASCII letters, digits or hyphens ('-'). -The `category` ``should`` be one of the existing +The `category` *should* be one of the existing well-defined categories, like `GST_ENCODING_CATEGORY_DEVICE`, but it -``can`` be a application or user specific category if +*can* be a application or user specific category if needed. ## `name` The name of the target. @@ -867,7 +886,7 @@ the `gst::Caps` the preset(s) to use on the encoder, can be `None` ## `restriction` the `gst::Caps` used to restrict the input to the encoder, can be -NULL. See `EncodingProfileExt::get_restriction` for more details. +NULL. See `EncodingProfile::get_restriction` for more details. ## `presence` the number of time this stream must be used. 0 means any number of times (including never) diff --git a/docs/gstreamer-player/docs.md b/docs/gstreamer-player/docs.md index 78ff84f0d..f77cfe36f 100644 --- a/docs/gstreamer-player/docs.md +++ b/docs/gstreamer-player/docs.md @@ -337,7 +337,7 @@ stream index `true` or `false` -Sets the subtitle strack `stream_index`. +Sets the subtitle stack `stream_index`. Enable or disable the current subtitle track. ## `enabled` @@ -444,7 +444,7 @@ generic error. [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PlayerSignalDispatcherExt`](trait.PlayerSignalDispatcherExt.html) Creates a new GstPlayerSignalDispatcher that uses `application_context`, -or the thread default one if `None` is used. See `gst_player_new_full`. +or the thread default one if `None` is used. See `Player::new`. ## `application_context` GMainContext to use or `None` @@ -475,7 +475,7 @@ the container format. duration of the media. Function to get the image (or preview-image) stored in taglist. -Application can use gst_sample_*`_` API's to get caps, buffer etc. +Application can use `gst_sample_*_()` API's to get caps, buffer etc. # Returns @@ -567,7 +567,7 @@ the player is paused. the player is currently playing a stream. -Base structure for information concering a media stream. Depending on +Base structure for information concerning a media stream. Depending on the stream type, one can find more media-specific information in `PlayerVideoInfo`, `PlayerAudioInfo`, `PlayerSubtitleInfo`. diff --git a/docs/gstreamer-rtsp-server/docs.md b/docs/gstreamer-rtsp-server/docs.md index 5022fa44f..fa6424e12 100644 --- a/docs/gstreamer-rtsp-server/docs.md +++ b/docs/gstreamer-rtsp-server/docs.md @@ -15,7 +15,7 @@ An address pool, all member are private # Implements -[`RTSPAddressPoolExt`](trait.RTSPAddressPoolExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`RTSPAddressPoolExt`](trait.RTSPAddressPoolExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`RTSPAddressPoolExtManual`](prelude/trait.RTSPAddressPoolExtManual.html) Trait containing all `RTSPAddressPool` methods. @@ -118,7 +118,7 @@ The authentication structure. # Implements -[`RTSPAuthExt`](trait.RTSPAuthExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`RTSPAuthExt`](trait.RTSPAuthExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`RTSPAuthExtManual`](prelude/trait.RTSPAuthExtManual.html) Trait containing all `RTSPAuth` methods. @@ -298,7 +298,7 @@ The client object represents the connection and its state with a client. # Implements -[`RTSPClientExt`](trait.RTSPClientExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`RTSPClientExt`](trait.RTSPClientExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`RTSPClientExtManual`](prelude/trait.RTSPClientExtManual.html) Trait containing all `RTSPClient` methods. @@ -340,6 +340,15 @@ Get the `gst_rtsp::RTSPConnection` of `self`. the `gst_rtsp::RTSPConnection` of `self`. The connection object returned remains valid until the client is freed. + +Get the Content-Length limit of `self`. + +Feature: `v1_18` + + +# Returns + +the Content-Length limit. Get the `RTSPMountPoints` object that `self` uses to manage its sessions. @@ -352,6 +361,19 @@ Get the `RTSPSessionPool` object that `self` uses to manage its sessions. # Returns a `RTSPSessionPool`, unref after usage. + +This is useful when providing a send function through +`RTSPClientExt::set_send_func` when doing RTSP over TCP: +the send function must call gst_rtsp_stream_transport_message_sent () +on the appropriate transport when data has been received for streaming +to continue. + +Feature: `v1_18` + + +# Returns + +the `RTSPStreamTransport` associated with `channel`. Get the `RTSPThreadPool` used as the thread pool of `self`. @@ -413,6 +435,16 @@ a `gst_rtsp::RTSPConnection` # Returns `true` on success. + +Configure `self` to use the specified Content-Length limit. + +Define an appropriate request size limit and reject requests exceeding the +limit with response status 413 Request Entity Too Large + +Feature: `v1_18` + +## `limit` +Content-Length limit Set `mounts` as the mount points for `self` which it will use to map urls to media streams. These mount points are usually inherited from the server that @@ -622,21 +654,6 @@ 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` Possible return values for `RTSPSessionPoolExt::filter`. @@ -654,7 +671,7 @@ This object is usually created from a `RTSPMediaFactory`. # Implements -[`RTSPMediaExt`](trait.RTSPMediaExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`RTSPMediaExt`](trait.RTSPMediaExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`RTSPMediaExtManual`](prelude/trait.RTSPMediaExtManual.html) Trait containing all `RTSPMedia` methods. @@ -754,6 +771,15 @@ Feature: `v1_16` # Returns Whether retransmission requests will be sent + +Get the configured DSCP QoS of attached media. + +Feature: `v1_18` + + +# Returns + +the DSCP QoS value of attached streams or -1 if disabled. Get the element that was used when constructing `self`. @@ -817,6 +843,30 @@ the unit to use for the string # Returns The range as a string, `g_free` after usage. + + +Feature: `v1_18` + + +# Returns + +whether `self` will follow the Rate-Control=no behaviour as specified +in the ONVIF replay spec. + +Get the rate and applied_rate of the current segment. + +Feature: `v1_18` + +## `rate` +the rate of the current segment +## `applied_rate` +the applied_rate of the current segment + +# Returns + +`false` if looking up the rate and applied rate failed. Otherwise +`true` is returned and `rate` and `applied_rate` are set to the rate and +applied_rate of the current segment. Get the amount of time to store retransmission data. @@ -870,6 +920,15 @@ a `gst_sdp::SDPMessage` # Returns TRUE on success. + +See `RTSPStreamExt::is_complete`, `RTSPStreamExt::is_sender`. + +Feature: `v1_18` + + +# Returns + +whether `self` has at least one complete sender stream. Check if multicast sockets are configured to be bound to multicast addresses. @@ -886,6 +945,14 @@ unpreparing. # Returns `true` if the media will send EOS before unpreparing. + + +Feature: `v1_18` + + +# Returns + +`true` if `self` is receive-only, `false` otherwise. Check if the pipeline for `self` can be reused after an unprepare. @@ -914,6 +981,19 @@ Use `RTSPMediaExt::get_time_provider` to get the network clock. # Returns `true` if `self` can provide a `gst_net::NetTimeProvider`. + +Lock the entire media. This is needed by callers such as rtsp_client to +protect the media when it is shared by many clients. +The lock prevents that concurrent clients alters the shared media, +while one client already is working with it. +Typically the lock is taken in external RTSP API calls that uses shared media +such as DESCRIBE, SETUP, ANNOUNCE, TEARDOWN, PLAY, PAUSE. + +As best practice take the lock as soon as the function get hold of a shared +media object. Release the lock right before the function returns. + +Feature: `v1_18` + Get the number of streams in this media. @@ -923,7 +1003,7 @@ The number of streams. Prepare `self` for streaming. This function will create the objects to manage the streaming. A pipeline must have been set on `self` with -`RTSPMediaExt::take_pipeline`. +`RTSPMedia::take_pipeline`. It will preroll the pipeline and collect vital information about the streams such as the duration. @@ -944,11 +1024,10 @@ a `gst_rtsp::RTSPTimeRange` `true` on success. -Seek the pipeline of `self` to `range`. `self` must be prepared with -`RTSPMediaExt::prepare`. In order to perform the seek operation, -the pipeline must contain all needed transport parts (transport sinks). +Seek the pipeline of `self` to `range` with the given `flags`. +`self` must be prepared with `RTSPMediaExt::prepare`. -Feature: `v1_14` +Feature: `v1_18` ## `range` a `gst_rtsp::RTSPTimeRange` @@ -957,6 +1036,27 @@ The minimal set of `gst::SeekFlags` to use # Returns +`true` on success. + +Seek the pipeline of `self` to `range` with the given `flags` and `rate`, +and `trickmode_interval`. +`self` must be prepared with `RTSPMediaExt::prepare`. +In order to perform the seek operation, the pipeline must contain all +needed transport parts (transport sinks). + +Feature: `v1_18` + +## `range` +a `gst_rtsp::RTSPTimeRange` +## `flags` +The minimal set of `gst::SeekFlags` to use +## `rate` +the rate to use in the seek +## `trickmode_interval` +The trickmode interval to use for KEY_UNITS trick mode + +# Returns + `true` on success. Check if the pipeline for `self` seek and up to what point in time, @@ -995,6 +1095,13 @@ Set whether retransmission requests will be sent Feature: `v1_16` + +Configure the dscp qos of attached streams to `dscp_qos`. + +Feature: `v1_18` + +## `dscp_qos` +a new dscp qos value (0-63, or -1 to disable) Set or unset if an EOS event will be sent to the pipeline for `self` before it is unprepared. @@ -1039,6 +1146,12 @@ the new flags Sets if and how the media clock should be published according to RFC7273. ## `mode` the clock publish mode + +Define whether `self` will follow the Rate-Control=no behaviour as specified +in the ONVIF replay spec. + +Feature: `v1_18` + Set the amount of time to store retransmission packets. ## `time` @@ -1109,6 +1222,11 @@ Set `pipeline` as the `gst::Pipeline` for `self`. Ownership is taken of `pipeline`. ## `pipeline` a `gst::Pipeline` + +Unlock the media. + +Feature: `v1_18` + Unprepare `self`. After this call, the media should be prepared again before it can be used again. If the media is set to be non-reusable, a new instance @@ -1134,7 +1252,7 @@ can contain multiple streams like audio and video. # Implements -[`RTSPMediaFactoryExt`](trait.RTSPMediaFactoryExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`RTSPMediaFactoryExt`](trait.RTSPMediaFactoryExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`RTSPMediaFactoryExtManual`](prelude/trait.RTSPMediaFactoryExtManual.html) Trait containing all `RTSPMediaFactory` methods. @@ -1219,6 +1337,15 @@ Feature: `v1_16` # Returns Whether retransmission requests will be sent for receiving media + +Get the configured media DSCP QoS. + +Feature: `v1_18` + + +# Returns + +the media DSCP QoS value or -1 if disabled. Get the latency that is used for receiving media @@ -1344,6 +1471,13 @@ receiving media Feature: `v1_16` + +Configure the media dscp qos to `dscp_qos`. + +Feature: `v1_18` + +## `dscp_qos` +a new dscp qos value (0-63, or -1 to disable) Configure if media created from this factory will have an EOS sent to the pipeline before shutdown. @@ -1424,11 +1558,11 @@ Configure if this factory creates media for PLAY or RECORD modes. ## `mode` the new value -A media factory that creates a pipeline to play and uri. +A media factory that creates a pipeline to play any uri. # Implements -[`RTSPMediaFactoryURIExt`](trait.RTSPMediaFactoryURIExt.html), [`RTSPMediaFactoryExt`](trait.RTSPMediaFactoryExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`RTSPMediaFactoryURIExt`](trait.RTSPMediaFactoryURIExt.html), [`RTSPMediaFactoryExt`](trait.RTSPMediaFactoryExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`RTSPMediaFactoryExtManual`](prelude/trait.RTSPMediaFactoryExtManual.html) Trait containing all `RTSPMediaFactoryURI` methods. @@ -1535,7 +1669,7 @@ it. # Implements -[`RTSPServerExt`](trait.RTSPServerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`RTSPServerExt`](trait.RTSPServerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`RTSPServerExtManual`](prelude/trait.RTSPServerExtManual.html) Trait containing all `RTSPServer` methods. @@ -1657,6 +1791,15 @@ Get the port number where the server was bound to. # Returns the port number + +Get the Content-Length limit of `self`. + +Feature: `v1_18` + + +# Returns + +the Content-Length limit. Get the `RTSPMountPoints` used as the mount points of `self`. @@ -1701,6 +1844,12 @@ server. This function must be called before the server is bound. ## `backlog` the backlog + +Define an appropriate request size limit and reject requests exceeding the +limit. + +Feature: `v1_18` + configure `mounts` to be used as the mount points of `self`. ## `mounts` @@ -2012,7 +2161,7 @@ attached to a `RTSPServer` object to manage the sessions in that server. # Implements -[`RTSPSessionPoolExt`](trait.RTSPSessionPoolExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`RTSPSessionPoolExt`](trait.RTSPSessionPoolExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`RTSPSessionPoolExtManual`](prelude/trait.RTSPSessionPoolExtManual.html) Trait containing all `RTSPSessionPool` methods. @@ -2052,8 +2201,7 @@ what happens to the session. `func` will be called with the session pool locked so no further actions on `self` can be performed from `func`. If `func` returns `RTSPFilterResult::Remove`, the session will be set to the -expired state with `gst_rtsp_session_set_expired` and removed from -`self`. +expired state and removed from `self`. If `func` returns `RTSPFilterResult::Keep`, the session will remain in `self`. @@ -2113,7 +2261,7 @@ The definition of a media stream. # Implements -[`RTSPStreamExt`](trait.RTSPStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`RTSPStreamExt`](trait.RTSPStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`RTSPStreamExtManual`](prelude/trait.RTSPStreamExtManual.html) Trait containing all `RTSPStream` methods. @@ -2155,7 +2303,8 @@ socket family `true` if `destination` can be addedd and handled by `self`. Add the transport in `trans` to `self`. The media of `self` will -then also be send to the values configured in `trans`. +then also be send to the values configured in `trans`. Adding the +same transport twice will not add it a second time. `self` must be joined to a bin. @@ -2209,7 +2358,7 @@ Retrieve the current caps of `self`. # Returns the `gst::Caps` of `self`. -use `gst_caps_unref` after usage. +use `gst::Caps::unref` after usage. Get the control string to identify this stream. @@ -2301,6 +2450,28 @@ Gets if and how the stream clock should be published according to RFC7273. # Returns The GstRTSPPublishClockMode + + +Feature: `v1_18` + + +# Returns + +whether `self` will follow the Rate-Control=no behaviour as specified +in the ONVIF replay spec. + +Retrieve the current rate and/or applied_rate. + +Feature: `v1_18` + +## `rate` +the configured rate +## `applied_rate` +the configured applied_rate + +# Returns + +`true` if rate and/or applied_rate could be determined. Get the payload-type used for retransmission of this stream @@ -2719,6 +2890,12 @@ a `gst::Caps` Sets if and how the stream clock should be published according to RFC7273. ## `mode` the clock publish mode + +Define whether `self` will follow the Rate-Control=no behaviour as specified +in the ONVIF replay spec. + +Feature: `v1_18` + Set the payload type (pt) for retransmission of this stream. ## `rtx_pt` @@ -2792,7 +2969,7 @@ A Transport description for a stream # Implements -[`RTSPStreamTransportExt`](trait.RTSPStreamTransportExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`RTSPStreamTransportExt`](trait.RTSPStreamTransportExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`RTSPStreamTransportExtManual`](prelude/trait.RTSPStreamTransportExtManual.html) Trait containing all `RTSPStreamTransport` methods. @@ -2849,7 +3026,7 @@ Check if `self` is timed out. Signal the installed keep_alive callback for `self`. -Signal the installed message_sent callback for `self`. +Signal the installed message_sent / message_sent_full callback for `self`. Feature: `v1_16` @@ -2946,6 +3123,17 @@ user data passed to callbacks called with the user_data when no longer needed. Install a callback that will be called when a message has been sent on `self`. +## `message_sent` +a callback called when a message has been sent +## `user_data` +user data passed to callback +## `notify` +called with the user_data when no longer needed + +Install a callback that will be called when a message has been sent on `self`. + +Feature: `v1_18` + ## `message_sent` a callback called when a message has been sent ## `user_data` @@ -2974,6 +3162,25 @@ Media is not suspended Media is PAUSED in suspend The media is set to NULL when suspended + +Structure holding info about a mainloop running in a thread + +Create a new thread object that can run a mainloop. +## `type_` +the thread type + +# Returns + +a `RTSPThread`. + +Reuse the mainloop of `self` + +# Returns + +`true` if the mainloop could be reused + +Stop and unref `self`. When no threads are using the mainloop, the thread +will be stopped and the final ref to `self` will be released. The thread pool structure. diff --git a/docs/gstreamer-rtsp/docs.md b/docs/gstreamer-rtsp/docs.md index df553f7d9..2a51c25a2 100644 --- a/docs/gstreamer-rtsp/docs.md +++ b/docs/gstreamer-rtsp/docs.md @@ -9,6 +9,8 @@ basic authentication digest authentication RTSP Authentication parameter + +Feature: `v1_12` The possible network families. @@ -50,7 +52,7 @@ Result codes from the RTSP functions. no error -some unspecified error occured +some unspecified error occurred invalid arguments were provided to a function @@ -58,13 +60,13 @@ an operation was canceled no memory was available for the operation -a host resolve error occured +a host resolve error occurred function not implemented -a system error occured, errno contains more details +a system error occurred, errno contains more details -a parsing error occured +a parsing error occurred windows networking could not start @@ -72,11 +74,11 @@ windows networking stack has wrong version end-of-file was reached -a network problem occured, h_errno contains more details +a network problem occurred, h_errno contains more details the host is not an IP host -a timeout occured +a timeout occurred the tunnel GET request has been performed @@ -152,6 +154,19 @@ Get a newly allocated string describing the request URI for `self`. # Returns a string with the request URI. `g_free` after usage. + +Get a newly allocated string describing the request URI for `self` +combined with the control path for `control_path` + +Feature: `v1_18` + +## `control_path` +an RTSP aggregate control path + +# Returns + +a string with the request URI combined with the control path. +`g_free` after usage. Set the port number in `self` to `port`. ## `port` diff --git a/docs/gstreamer-video/docs.md b/docs/gstreamer-video/docs.md index f13c87576..e0d93d032 100644 --- a/docs/gstreamer-video/docs.md +++ b/docs/gstreamer-video/docs.md @@ -1,4 +1,110 @@ + +Enumeration of the different standards that may apply to AFD data: + +0) ETSI/DVB: +https://www.etsi.org/deliver/etsi_ts/101100_101199/101154/02.01.01_60/ts_101154v020101p.pdf + +1) ATSC A/53: +https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf + +2) SMPTE ST2016-1: + +AFD value is from DVB/ETSI standard + +AFD value is from ATSC A/53 standard + +Feature: `v1_18` + + +Enumeration of the various values for Active Format Description (AFD) + +AFD should be included in video user data whenever the rectangular +picture area containing useful information does not extend to the full height or width of the coded +frame. AFD data may also be included in user data when the rectangular picture area containing +useful information extends to the full height and width of the coded frame. + +For details, see Table 6.14 Active Format in: + +ATSC Digital Television Standard: +Part 4 – MPEG-2 Video System Characteristics + +https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf + +and Active Format Description in Complete list of AFD codes + +https://en.wikipedia.org/wiki/Active_Format_Description`Complete_list_of_AFD_codes` + +and SMPTE ST2016-1 + +Notes: + +1) AFD 0 is undefined for ATSC and SMPTE ST2016-1, indicating that AFD data is not available: +If Bar Data is not present, AFD '0000' indicates that exact information +is not available and the active image should be assumed to be the same as the coded frame. AFD '0000'. +AFD '0000' accompanied by Bar Data signals that the active image’s aspect ratio is narrower than 16:9, +but is not 4:3 or 14:9. As the exact aspect ratio cannot be conveyed by AFD alone, wherever possible, +AFD ‘0000’ should be accompanied by Bar Data to define the exact vertical or horizontal extent +of the active image. +2) AFD 0 is reserved for DVB/ETSI +3) values 1, 5, 6, 7, and 12 are reserved for both ATSC and DVB/ETSI +4) values 2 and 3 are not recommended for ATSC, but are valid for DVB/ETSI + +Unavailable (see note 0 below). + +For 4:3 coded frame, letterbox 16:9 image, + at top of the coded frame. For 16:9 coded frame, full frame 16:9 image, + the same as the coded frame. + +For 4:3 coded frame, letterbox 14:9 image, + at top of the coded frame. For 16:9 coded frame, pillarbox 14:9 image, + horizontally centered in the coded frame. + +For 4:3 coded frame, letterbox image with an aspect ratio + greater than 16:9, vertically centered in the coded frame. For 16:9 coded frame, + letterbox image with an aspect ratio greater than 16:9. + +For 4:3 coded frame, full frame 4:3 image, + the same as the coded frame. For 16:9 coded frame, full frame 16:9 image, the same as + the coded frame. + +For 4:3 coded frame, full frame 4:3 image, the same as + the coded frame. For 16:9 coded frame, pillarbox 4:3 image, horizontally centered in the + coded frame. + +For 4:3 coded frame, letterbox 16:9 image, vertically centered in + the coded frame with all image areas protected. For 16:9 coded frame, full frame 16:9 image, + with all image areas protected. + +For 4:3 coded frame, letterbox 14:9 image, vertically centered in + the coded frame. For 16:9 coded frame, pillarbox 14:9 image, horizontally centered in the + coded frame. + +For 4:3 coded frame, full frame 4:3 image, with alternative 14:9 + center. For 16:9 coded frame, pillarbox 4:3 image, with alternative 14:9 center. + +For 4:3 coded frame, letterbox 16:9 image, with alternative 14:9 + center. For 16:9 coded frame, full frame 16:9 image, with alternative 14:9 center. + +For 4:3 coded frame, letterbox 16:9 image, with alternative 4:3 + center. For 16:9 coded frame, full frame 16:9 image, with alternative 4:3 center. + +Feature: `v1_18` + + +Different alpha modes. + +When input and output have alpha, it will be copied. + When the input has no alpha, alpha will be set to + `GST_VIDEO_CONVERTER_OPT_ALPHA_VALUE` + +set all alpha to + `GST_VIDEO_CONVERTER_OPT_ALPHA_VALUE` + +multiply all alpha with + `GST_VIDEO_CONVERTER_OPT_ALPHA_VALUE`. + When the input format has no alpha but the output format has, the + alpha value will be set to `GST_VIDEO_CONVERTER_OPT_ALPHA_VALUE` @@ -44,6 +150,16 @@ CEA-708 (and optionally CEA-608) in Feature: `v1_16` + +Different chroma downsampling and upsampling modes + +do full chroma up and down sampling + +only perform chroma upsampling + +only perform chroma downsampling + +disable chroma resampling A `VideoCodecFrame` represents a video frame both in raw and encoded form. @@ -148,41 +264,6 @@ unknown range [16..235] for 8 bit components. Chroma has [16..240] range. - -Structure describing the color info. - -Parse the colorimetry string and update `self` with the parsed -values. -## `color` -a colorimetry string - -# Returns - -`true` if `color` points to valid colorimetry info. - -Compare the 2 colorimetry sets for equality -## `other` -another `VideoColorimetry` - -# Returns - -`true` if `self` and `other` are equal. - -Check if the colorimetry information in `info` matches that of the -string `color`. -## `color` -a colorimetry string - -# Returns - -`true` if `color` conveys the same colorimetry info as the color -information in `info`. - -Make a string representation of `self`. - -# Returns - -a string representation of `self`. This base class is for video decoders turning encoded data into raw video frames. @@ -247,7 +328,7 @@ follows: The subclass is responsible for providing pad template caps for source and sink pads. The pads need to be named "sink" and "src". It also -needs to provide information about the ouptput caps, when they are known. +needs to provide information about the output caps, when they are known. This may be when the base class calls the subclass' `set_format` function, though it might be during decoding, before calling `VideoDecoder::finish_frame`. This is done via @@ -290,7 +371,7 @@ The bare minimum that a functional subclass needs to implement is: # Implements -[`VideoDecoderExt`](trait.VideoDecoderExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`VideoDecoderExt`](trait.VideoDecoderExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`VideoDecoderExtManual`](prelude/trait.VideoDecoderExtManual.html) Trait containing all `VideoDecoder` methods. @@ -600,6 +681,34 @@ handler with `GST_PAD_SET_ACCEPT_INTERSECT` and `GST_PAD_SET_ACCEPT_TEMPLATE` ## `use_` if the default pad accept-caps query handling should be used + +If set to `true` the decoder will handle QoS events received +from downstream elements. +This includes dropping output frames which are detected as late +using the metrics reported by those events. + +Feature: `v1_18` + + +If set to `true` the decoder will handle QoS events received +from downstream elements. +This includes dropping output frames which are detected as late +using the metrics reported by those events. + +Feature: `v1_18` + + +Different dithering methods to use. + +no dithering + +propagate rounding errors downwards + +Dither with floyd-steinberg error diffusion + +Dither with Sierra Lite error diffusion + +ordered dither using a bayer pattern This base class is for video encoders turning raw video into encoded video data. @@ -662,7 +771,7 @@ pipeline to catch up. # Implements -[`VideoEncoderExt`](trait.VideoEncoderExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`VideoEncoderExt`](trait.VideoEncoderExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`VideoEncoderExtManual`](prelude/trait.VideoEncoderExtManual.html) Trait containing all `VideoEncoder` methods. @@ -709,6 +818,25 @@ an encoded `VideoCodecFrame` # Returns a `gst::FlowReturn` resulting from sending data downstream + +If multiple subframes are produced for one input frame then use this method +for each subframe, except for the last one. Before calling this function, +you need to fill frame->output_buffer with the encoded buffer to push. + +You must call `VideoEncoder::finish_frame`() for the last sub-frame +to tell the encoder that the frame has been fully encoded. + +This function will change the metadata of `frame` and frame->output_buffer +will be pushed downstream. + +Feature: `v1_18` + +## `frame` +a `VideoCodecFrame` being encoded + +# Returns + +a `gst::FlowReturn` resulting from pushing the buffer downstream. Lets `VideoEncoder` sub-classes to know the memory `allocator` used by the base class and its `params`. @@ -830,7 +958,7 @@ maximum latency Request minimal value for PTS passed to handle_frame. For streams with reordered frames this can be used to ensure that there -is enough time to accomodate first DTS, which may be less than first PTS +is enough time to accommodate first DTS, which may be less than first PTS ## `min_pts` minimal PTS that will be passed to handle_frame @@ -894,7 +1022,7 @@ to implement frame dropping. Enum value describing the most common video formats. -See the [GStreamer raw video format design document](https://gstreamer.freedesktop.org/documentation/design/mediatype-video-raw.html`formats`) +See the [GStreamer raw video format design document](https://gstreamer.freedesktop.org/documentation/additional/design/mediatype-video-raw.html`formats`) for details about the layout and packing of these formats in memory. Unknown or unset video format id @@ -1071,106 +1199,34 @@ packed 4:4:4 YUV, 10 bits per channel(A-V-Y-U...) (Since: 1.16) packed 4:4:4 YUV with alpha channel (V0-U0-Y0-A0...) (Since: 1.16) packed 4:4:4 RGB with alpha channel(B-G-R-A), 10 bits for R/G/B channel and MSB 2 bits for alpha channel (Since: 1.16) - -Information for a video format. - -A video frame obtained from `VideoFrame::map` - -Copy the contents from `src` to `self`. -## `src` -a `VideoFrame` - -# Returns - -TRUE if the contents could be copied. - -Copy the plane with index `plane` from `src` to `self`. -## `src` -a `VideoFrame` -## `plane` -a plane - -# Returns - -TRUE if the contents could be copied. - -Use `info` and `buffer` to fill in the values of `self`. `self` is usually -allocated on the stack, and you will pass the address to the `VideoFrame` -structure allocated on the stack; `VideoFrame::map` will then fill in -the structures with the various video-specific information you need to access -the pixels of the video buffer. You can then use accessor macros such as -GST_VIDEO_FRAME_COMP_DATA(), GST_VIDEO_FRAME_PLANE_DATA(), -GST_VIDEO_FRAME_COMP_STRIDE(), GST_VIDEO_FRAME_PLANE_STRIDE() etc. -to get to the pixels. - - -```C - GstVideoFrame vframe; - ... - // set RGB pixels to black one at a time - if (gst_video_frame_map (&vframe, video_info, video_buffer, GST_MAP_WRITE)) { - guint8 *pixels = GST_VIDEO_FRAME_PLANE_DATA (vframe, 0); - guint stride = GST_VIDEO_FRAME_PLANE_STRIDE (vframe, 0); - guint pixel_stride = GST_VIDEO_FRAME_COMP_PSTRIDE (vframe, 0); - - for (h = 0; h < height; ++h) { - for (w = 0; w < width; ++w) { - guint8 *pixel = pixels + h * stride + w * pixel_stride; - - memset (pixel, 0, pixel_stride); - } - } - - gst_video_frame_unmap (&vframe); - } - ... -``` - -All video planes of `buffer` will be mapped and the pointers will be set in -`self`->data. - -The purpose of this function is to make it easy for you to get to the video -pixels in a generic way, without you having to worry too much about details -such as whether the video data is allocated in one contiguous memory chunk -or multiple memory chunks (e.g. one for each plane); or if custom strides -and custom plane offsets are used or not (as signalled by GstVideoMeta on -each buffer). This function will just fill the `VideoFrame` structure -with the right values and if you use the accessor macros everything will -just work and you can access the data easily. It also maps the underlying -memory chunks for you. -## `info` -a `VideoInfo` -## `buffer` -the buffer to map -## `flags` -`gst::MapFlags` - -# Returns - -`true` on success. - -Use `info` and `buffer` to fill in the values of `self` with the video frame -information of frame `id`. - -When `id` is -1, the default frame is mapped. When `id` != -1, this function -will return `false` when there is no GstVideoMeta with that id. - -All video planes of `buffer` will be mapped and the pointers will be set in -`self`->data. -## `info` -a `VideoInfo` -## `buffer` -the buffer to map -## `id` -the frame id to map -## `flags` -`gst::MapFlags` - -# Returns - -`true` on success. - -Unmap the memory previously mapped with gst_video_frame_map. + +packed 4:4:4 RGB with alpha channel(R-G-B-A), 10 bits for R/G/B channel and MSB 2 bits for alpha channel (Since: 1.18) + +planar 4:4:4 YUV, 16 bits per channel (Since: 1.18) + +planar 4:4:4 YUV, 16 bits per channel (Since: 1.18) + +planar 4:2:0 YUV with interleaved UV plane, 16 bits per channel (Since: 1.18) + +planar 4:2:0 YUV with interleaved UV plane, 16 bits per channel (Since: 1.18) + +planar 4:2:0 YUV with interleaved UV plane, 12 bits per channel (Since: 1.18) + +planar 4:2:0 YUV with interleaved UV plane, 12 bits per channel (Since: 1.18) + +packed 4:2:2 YUV, 12 bits per channel (Y-U-Y-V) (Since: 1.18) + +packed 4:2:2 YUV, 12 bits per channel (Y-U-Y-V) (Since: 1.18) + +packed 4:4:4:4 YUV, 12 bits per channel(U-Y-V-A...) (Since: 1.18) + +packed 4:4:4:4 YUV, 12 bits per channel(U-Y-V-A...) (Since: 1.18) + + +disable gamma handling + +convert between input and output gamma +Different gamma conversion modes Information describing image properties. This information can be filled in from GstCaps with `VideoInfo::from_caps`. The information is also used @@ -1198,6 +1254,25 @@ alignment parameters `false` if alignment could not be applied, e.g. because the size of a frame can't be represented as a 32 bit integer (Since: 1.12) + +This variant of `VideoInfo::align` provides the updated size, in bytes, +of each video plane after the alignment, including all horizontal and vertical +paddings. + +In case of GST_VIDEO_INTERLACE_MODE_ALTERNATE info, the returned sizes are the +ones used to hold a single field, not the full frame. + +Feature: `v1_18` + +## `align` +alignment parameters +## `plane_size` +array used to store the plane sizes + +# Returns + +`false` if alignment could not be applied, e.g. because the + size of a frame can't be represented as a 32 bit integer Converts among various `gst::Format` types. This function handles GST_FORMAT_BYTES, GST_FORMAT_TIME, and GST_FORMAT_DEFAULT. For @@ -1309,6 +1384,18 @@ frames contains both interlaced and the buffer is carrying the top or bottom field, respectively. The top and bottom buffers are expected to alternate in the pipeline, with this mode (Since: 1.16). + +Different color matrix conversion modes + +do conversion between color matrices + +use the input color matrix to convert + to and from R'G'B + +use the output color matrix to convert + to and from R'G'B + +disable color matrix conversion. `VideoMultiviewFramePacking` represents the subset of `VideoMultiviewMode` values that can be applied to any video frame without needing extra metadata. @@ -1462,7 +1549,7 @@ main (int argc, char **argv) ## Two basic usage scenarios There are two basic usage scenarios: in the simplest case, the application -uses `playbin` or `plasink` or knows exactly what particular element is used +uses `playbin` or `playsink` or knows exactly what particular element is used for video output, which is usually the case when the application creates the videosink to use (e.g. `xvimagesink`, `ximagesink`, etc.) itself; in this case, the application can just create the videosink element, create and @@ -1495,10 +1582,10 @@ prepare-window-handle message is handled, because most GUI toolkits and windowing systems are not thread-safe at all and a lot of care would be required to co-ordinate the toolkit and window system calls of the different threads (Gtk+ users please note: prior to Gtk+ 2.18 -GDK_WINDOW_XID() was just a simple structure access, so generally fine to do +`GDK_WINDOW_XID` was just a simple structure access, so generally fine to do within the bus sync handler; this macro was changed to a function call in Gtk+ 2.18 and later, which is likely to cause problems when called from a -sync handler; see below for a better approach without GDK_WINDOW_XID() +sync handler; see below for a better approach without `GDK_WINDOW_XID` used in the callback). ## GstVideoOverlay and Gtk+ @@ -1664,7 +1751,7 @@ int main(int argc, char *argv[]) # Implements -[`VideoOverlayExt`](trait.VideoOverlayExt.html) +[`VideoOverlayExt`](trait.VideoOverlayExt.html), [`VideoOverlayExtManual`](prelude/trait.VideoOverlayExtManual.html) Trait containing all `VideoOverlay` methods. @@ -1757,6 +1844,63 @@ specific window (e.g. an XWindow on X11). Passing 0 as the `handle` will tell the overlay to stop using that window and create an internal one. ## `handle` a handle referencing the window. + +Different primaries conversion modes + +disable conversion between primaries + +do conversion between primaries only + when it can be merged with color matrix conversion. + +fast conversion between primaries + +Different subsampling and upsampling methods + +Duplicates the samples when + upsampling and drops when downsampling + +Uses linear interpolation to reconstruct + missing samples and averaging to downsample + +Uses cubic interpolation + +Uses sinc interpolation + +Uses lanczos interpolation + +Provides useful functions and a base class for video sinks. + +GstVideoSink will configure the default base sink to drop frames that +arrive later than 20ms as this is considered the default threshold for +observing out-of-sync frames. + +# Implements + +[`VideoSinkExt`](trait.VideoSinkExt.html), [`gst_base::BaseSinkExt`](../gst_base/trait.BaseSinkExt.html), [`gst::ElementExt`](../gst/trait.ElementExt.html), [`gst::ObjectExt`](../gst/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Trait containing all `VideoSink` methods. + +# Implementors + +[`VideoSink`](struct.VideoSink.html) + +Takes `src` rectangle and position it at the center of `dst` rectangle with or +without `scaling`. It handles clipping if the `src` rectangle is bigger than +the `dst` one and `scaling` is set to FALSE. +## `src` +the `VideoRectangle` describing the source area +## `dst` +the `VideoRectangle` describing the destination area +## `result` +a pointer to a `VideoRectangle` which will receive the result area +## `scaling` +a `gboolean` indicating if scaling should be applied or not + +Whether to show video frames during preroll. If set to `false`, video +frames will only be rendered in PLAYING state. + +Whether to show video frames during preroll. If set to `false`, video +frames will only be rendered in PLAYING state. Enum value describing the available tiling modes. @@ -2156,3 +2300,16 @@ Gamma 2.2 curve with a linear segment in the lower component. Since: 1.6 Gamma 2.19921875. Since: 1.8 + +Rec. ITU-R BT.2020-2 with 10 bits per component. + (functionally the same as the values + GST_VIDEO_TRANSFER_BT709 and GST_VIDEO_TRANSFER_BT2020_12). + Since: 1.18 + +SMPTE ST 2084 for 10, 12, 14, and 16-bit systems. + Known as perceptual quantization (PQ) + Since: 1.18 + +Association of Radio Industries and Businesses (ARIB) + STD-B67 and Rec. ITU-R BT.2100-1 hybrid loggamma (HLG) system + Since: 1.18 diff --git a/docs/gstreamer-webrtc/docs.md b/docs/gstreamer-webrtc/docs.md index 4a7dda95f..940d161a0 100644 --- a/docs/gstreamer-webrtc/docs.md +++ b/docs/gstreamer-webrtc/docs.md @@ -10,10 +10,14 @@ for more information. Feature: `v1_16` -GST_WEBRTC_DTLS_SETUP_NONE: none -GST_WEBRTC_DTLS_SETUP_ACTPASS: actpass -GST_WEBRTC_DTLS_SETUP_ACTIVE: sendonly -GST_WEBRTC_DTLS_SETUP_PASSIVE: recvonly + +none + +actpass + +sendonly + +recvonly @@ -21,18 +25,103 @@ GST_WEBRTC_DTLS_SETUP_PASSIVE: recvonly [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) -GST_WEBRTC_DTLS_TRANSPORT_STATE_NEW: new -GST_WEBRTC_DTLS_TRANSPORT_STATE_CLOSED: closed -GST_WEBRTC_DTLS_TRANSPORT_STATE_FAILED: failed -GST_WEBRTC_DTLS_TRANSPORT_STATE_CONNECTING: connecting -GST_WEBRTC_DTLS_TRANSPORT_STATE_CONNECTED: connected + +new + +closed + +failed + +connecting + +connected + + + +Feature: `v1_18` + +# Implements + +[`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Close the `self`. + +Feature: `v1_18` + + +Signal that the data channel reached a low buffered amount. Should only be used by subclasses. + +Feature: `v1_18` + + +Signal that the data channel was closed. Should only be used by subclasses. + +Feature: `v1_18` + + +Signal that the data channel had an error. Should only be used by subclasses. + +Feature: `v1_18` + +## `error` +a `glib::Error` + +Signal that the data channel received a data message. Should only be used by subclasses. + +Feature: `v1_18` + +## `data` +a `glib::Bytes` or `None` + +Signal that the data channel received a string message. Should only be used by subclasses. + +Feature: `v1_18` + +## `str` +a string or `None` + +Signal that the data channel was opened. Should only be used by subclasses. + +Feature: `v1_18` + + +Send `data` as a data message over `self`. + +Feature: `v1_18` + +## `data` +a `glib::Bytes` or `None` + +Send `str` as a string message over `self`. + +Feature: `v1_18` + +## `str` +a string or `None` + +Close the data channel + +## `error` +the `glib::Error` thrown + +## `data` +a `glib::Bytes` of the data received + +## `data` +the data received as a string + +## `data` +a `glib::Bytes` with the data + +## `data` +the data to send as a string GST_WEBRTC_DATA_CHANNEL_STATE_NEW: new GST_WEBRTC_DATA_CHANNEL_STATE_CONNECTING: connection GST_WEBRTC_DATA_CHANNEL_STATE_OPEN: open GST_WEBRTC_DATA_CHANNEL_STATE_CLOSING: closing GST_WEBRTC_DATA_CHANNEL_STATE_CLOSED: closed -See http://w3c.github.io/webrtc-pc/`dom`-rtcdatachannelstate`` +See Feature: `v1_16` @@ -45,25 +134,39 @@ ulpfec + red Feature: `v1_14_1` -GST_WEBRTC_ICE_COMPONENT_RTP, -GST_WEBRTC_ICE_COMPONENT_RTCP, + +RTP component + +RTCP component -GST_WEBRTC_ICE_CONNECTION_STATE_NEW: new -GST_WEBRTC_ICE_CONNECTION_STATE_CHECKING: checking -GST_WEBRTC_ICE_CONNECTION_STATE_CONNECTED: connected -GST_WEBRTC_ICE_CONNECTION_STATE_COMPLETED: completed -GST_WEBRTC_ICE_CONNECTION_STATE_FAILED: failed -GST_WEBRTC_ICE_CONNECTION_STATE_DISCONNECTED: disconnected -GST_WEBRTC_ICE_CONNECTION_STATE_CLOSED: closed -See http://w3c.github.io/webrtc-pc/`dom`-rtciceconnectionstate`` +See + +new + +checking + +connected + +completed + +failed + +disconnected + +closed -GST_WEBRTC_ICE_GATHERING_STATE_NEW: new -GST_WEBRTC_ICE_GATHERING_STATE_GATHERING: gathering -GST_WEBRTC_ICE_GATHERING_STATE_COMPLETE: complete -See http://w3c.github.io/webrtc-pc/`dom`-rtcicegatheringstate`` +See + +new + +gathering + +complete -GST_WEBRTC_ICE_ROLE_CONTROLLED: controlled -GST_WEBRTC_ICE_ROLE_CONTROLLING: controlling + +controlled + +controlling @@ -79,19 +182,25 @@ for more information. Feature: `v1_16` -GST_WEBRTC_PEER_CONNECTION_STATE_NEW: new -GST_WEBRTC_PEER_CONNECTION_STATE_CONNECTING: connecting -GST_WEBRTC_PEER_CONNECTION_STATE_CONNECTED: connected -GST_WEBRTC_PEER_CONNECTION_STATE_DISCONNECTED: disconnected -GST_WEBRTC_PEER_CONNECTION_STATE_FAILED: failed -GST_WEBRTC_PEER_CONNECTION_STATE_CLOSED: closed -See http://w3c.github.io/webrtc-pc/`dom`-rtcpeerconnectionstate`` +See + +new + +connecting + +connected + +disconnected + +failed + +closed GST_WEBRTC_PRIORITY_TYPE_VERY_LOW: very-low GST_WEBRTC_PRIORITY_TYPE_LOW: low GST_WEBRTC_PRIORITY_TYPE_MEDIUM: medium GST_WEBRTC_PRIORITY_TYPE_HIGH: high -See http://w3c.github.io/webrtc-pc/`dom`-rtcprioritytype`` +See Feature: `v1_16` @@ -113,24 +222,48 @@ Feature: `v1_16` # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) + +Direction of the transceiver. + +Feature: `v1_18` + + +Direction of the transceiver. + +Feature: `v1_18` + + +none + +inactive + +sendonly + +recvonly + +sendrecv GST_WEBRTC_SCTP_TRANSPORT_STATE_NEW: new GST_WEBRTC_SCTP_TRANSPORT_STATE_CONNECTING: connecting GST_WEBRTC_SCTP_TRANSPORT_STATE_CONNECTED: connected GST_WEBRTC_SCTP_TRANSPORT_STATE_CLOSED: closed -See http://w3c.github.io/webrtc-pc/`dom`-rtcsctptransportstate`` +See Feature: `v1_16` -GST_WEBRTC_SDP_TYPE_OFFER: offer -GST_WEBRTC_SDP_TYPE_PRANSWER: pranswer -GST_WEBRTC_SDP_TYPE_ANSWER: answer -GST_WEBRTC_SDP_TYPE_ROLLBACK: rollback -See http://w3c.github.io/webrtc-pc/`rtcsdptype``` +See + +offer + +pranswer + +answer + +rollback -See https://www.w3.org/TR/webrtc/`rtcsessiondescription`-class`` +See ## `type_` a `WebRTCSDPType` @@ -149,25 +282,45 @@ a new copy of `self` Free `self` and all associated resources -GST_WEBRTC_SIGNALING_STATE_STABLE: stable -GST_WEBRTC_SIGNALING_STATE_CLOSED: closed -GST_WEBRTC_SIGNALING_STATE_HAVE_LOCAL_OFFER: have-local-offer -GST_WEBRTC_SIGNALING_STATE_HAVE_REMOTE_OFFER: have-remote-offer -GST_WEBRTC_SIGNALING_STATE_HAVE_LOCAL_PRANSWER: have-local-pranswer -GST_WEBRTC_SIGNALING_STATE_HAVE_REMOTE_PRANSWER: have-remote-pranswer -See http://w3c.github.io/webrtc-pc/`dom`-rtcsignalingstate`` +See + +stable + +closed + +have-local-offer + +have-remote-offer + +have-local-pranswer + +have-remote-pranswer -GST_WEBRTC_STATS_CODEC: codec -GST_WEBRTC_STATS_INBOUND_RTP: inbound-rtp -GST_WEBRTC_STATS_OUTBOUND_RTP: outbound-rtp -GST_WEBRTC_STATS_REMOTE_INBOUND_RTP: remote-inbound-rtp -GST_WEBRTC_STATS_REMOTE_OUTBOUND_RTP: remote-outbound-rtp -GST_WEBRTC_STATS_CSRC: csrc -GST_WEBRTC_STATS_PEER_CONNECTION: peer-connectiion -GST_WEBRTC_STATS_DATA_CHANNEL: data-channel -GST_WEBRTC_STATS_STREAM: stream -GST_WEBRTC_STATS_TRANSPORT: transport -GST_WEBRTC_STATS_CANDIDATE_PAIR: candidate-pair -GST_WEBRTC_STATS_LOCAL_CANDIDATE: local-candidate -GST_WEBRTC_STATS_REMOTE_CANDIDATE: remote-candidate -GST_WEBRTC_STATS_CERTIFICATE: certificate + +codec + +inbound-rtp + +outbound-rtp + +remote-inbound-rtp + +remote-outbound-rtp + +csrc + +peer-connectiion + +data-channel + +stream + +transport + +candidate-pair + +local-candidate + +remote-candidate + +certificate diff --git a/docs/gstreamer/docs.md b/docs/gstreamer/docs.md index 971f05902..945c872d0 100644 --- a/docs/gstreamer/docs.md +++ b/docs/gstreamer/docs.md @@ -14,7 +14,7 @@ allocated elsewhere. # Implements -[`AllocatorExt`](trait.AllocatorExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`AllocatorExt`](trait.AllocatorExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`AllocatorExtManual`](prelude/trait.AllocatorExtManual.html) Trait containing all `Allocator` methods. @@ -115,12 +115,15 @@ of their segment. a SEGMENT_START have posted a SEGMENT_DONE. * GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change -in the stream duration. The default bin behaviour is to clear any -cached duration values so that the next duration query will perform -a full duration recalculation. The duration change is posted to the +in the stream duration. The duration change is posted to the application so that it can refetch the new duration with a duration query. Note that these messages can be posted before the bin is -prerolled, in which case the duration query might fail. +prerolled, in which case the duration query might fail. Note also that +there might be a discrepancy (due to internal buffering/queueing) between the +stream being currently displayed and the returned duration query. +Applications might want to also query for duration (and changes) by +listening to the GST_MESSAGE_STREAM_START message, signaling the active start +of a (new) stream. * GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it can no longer provide a clock. The default bin behaviour is to @@ -145,11 +148,8 @@ the parent of the bin. A `Bin` implements the following default behaviour for answering to a `Query`: -* GST_QUERY_DURATION:If the query has been asked before with the same format -and the bin is a toplevel bin (ie. has no parent), -use the cached previous value. If no previous value was cached, the -query is sent to all sink elements in the bin and the MAXIMUM of all -values is returned. If the bin is a toplevel bin the value is cached. +* GST_QUERY_DURATION: The bin will forward the query to all sink +elements contained within and will return the maximum value. If no sinks are available in the bin, the query fails. * GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the @@ -169,7 +169,7 @@ handler will return `true`. # Implements -[`GstBinExt`](trait.GstBinExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ChildProxyExt`](trait.ChildProxyExt.html) +[`GstBinExt`](trait.GstBinExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ChildProxyExt`](trait.ChildProxyExt.html), [`ElementExtManual`](prelude/trait.ElementExtManual.html), [`ChildProxyExtManual`](prelude/trait.ChildProxyExtManual.html) Trait containing all `Bin` methods. @@ -279,6 +279,23 @@ Feature: `v1_10` # Returns the bin's suppressed `ElementFlags`. + +Looks for all elements inside the bin with the given element factory name. +The function recurses inside child bins. The iterator will yield a series of +`Element` that should be unreffed after use. + +MT safe. Caller owns returned value. + +Feature: `v1_18` + +## `factory_name` +the name of the `ElementFactory` + +# Returns + +a `Iterator` of `Element` + for all elements in the bin with the given element factory name, + or `None`. Looks for all elements inside the bin that implements the given interface. You can safely cast all returned elements to the given interface. @@ -516,7 +533,7 @@ the end of the buffer. These can only be meaningfully interpreted if you know the media type of the buffer (the preceding CAPS event). Either or both can be set to `GST_BUFFER_OFFSET_NONE`. -`gst_buffer_ref` is used to increase the refcount of a buffer. This must be +`Buffer::ref` is used to increase the refcount of a buffer. This must be done when you want to keep a handle to the buffer after pushing it to the next element. The buffer refcount determines the writability of the buffer, a buffer is only writable when the refcount is exactly 1, i.e. when the caller @@ -545,7 +562,7 @@ Metadata can be retrieved with `Buffer::get_meta`. See also `Meta` An element should either unref the buffer or push it out on a src pad using `Pad::push` (see `Pad`). -Buffers are usually freed by unreffing them with `gst_buffer_unref`. When +Buffers are usually freed by unreffing them with `Buffer::unref`. When the refcount drops to 0, any memory and metadata pointed to by the buffer is unreffed as well. Buffers allocated from a `BufferPool` will be returned to the pool when the refcount drops to 0. @@ -722,6 +739,16 @@ the size or -1 of `buf2` the new `Buffer` that contains the memory of the two source buffers. + +Create a copy of the given buffer. This will only copy the buffer's +data to a newly allocated memory if needed (if the type of memory +requires it), otherwise the underlying data is just referenced. +Check `Buffer::copy_deep` if you want to force the data +to be copied to newly allocated memory. + +# Returns + +a new copy of `self`. Create a copy of the given buffer. This will make a newly allocated copy of the data the source buffer contains. @@ -1137,6 +1164,18 @@ This function is identical to `Buffer::insert_memory` with an index of 0. See `Buffer::insert_memory` for more details. ## `mem` a `Memory`. + +Increases the refcount of the given buffer by one. + +Note that the refcount affects the writability +of `self` and its metadata, see `gst_buffer_is_writable`. +It is important to note that keeping additional references to +GstBuffer instances can potentially increase the number +of memcpy operations in a pipeline. + +# Returns + +`self` Remove all the memory blocks in `self`. @@ -1223,6 +1262,9 @@ the new size Release the memory previously mapped with `Buffer::map`. ## `info` a `MapInfo` + +Decreases the refcount of the buffer. If the refcount reaches 0, the buffer +with the associated metadata and memory will be freed. Clears one or more buffer flags. @@ -1244,6 +1286,23 @@ together to make room for the new block. # Returns the maximum amount of memory blocks that a buffer can hold. + +Modifies a pointer to a `Buffer` to point to a different `Buffer`. The +modification is done atomically (so this is useful for ensuring thread safety +in some cases), and the reference counts are updated appropriately (the old +buffer is unreffed, the new is reffed). + +Either `nbuf` or the `Buffer` pointed to by `obuf` may be `None`. +## `obuf` +pointer to a pointer to + a `Buffer` to be replaced. +## `nbuf` +pointer to a `Buffer` that will + replace the buffer pointed to by `obuf`. + +# Returns + +`true` when `obuf` was different from `nbuf`. Buffer lists are an object containing a list of buffers. @@ -1261,7 +1320,7 @@ Free-function: gst_buffer_list_unref # Returns -the new `BufferList`. `gst_buffer_list_unref` +the new `BufferList`. `BufferList::unref` after usage. Creates a new, empty `BufferList`. The caller is responsible for unreffing @@ -1274,7 +1333,7 @@ an initial reserved size # Returns -the new `BufferList`. `gst_buffer_list_unref` +the new `BufferList`. `BufferList::unref` after usage. Calculates the size of the data contained in buffer list by adding the @@ -1286,6 +1345,14 @@ Feature: `v1_14` # Returns the size of the data contained in buffer list in bytes. + +Create a shallow copy of the given buffer list. This will make a newly +allocated copy of the source list with copies of buffer pointers. The +refcount of buffers pointed to will be increased by one. + +# Returns + +a new copy of `self`. Create a copy of the given buffer list. This will make a newly allocated copy of the buffer that the source buffer list contains. @@ -1352,6 +1419,17 @@ Returns the number of buffers in `self`. # Returns the number of buffers in the buffer list + +Increases the refcount of the given buffer list by one. + +Note that the refcount affects the writability of `self` and its data, see +`gst_buffer_list_make_writable`. It is important to note that keeping +additional references to GstBufferList instances can potentially increase +the number of memcpy operations in a pipeline. + +# Returns + +`self` Remove `length` buffers starting from `idx` in `self`. The following buffers are moved to close the gap. @@ -1359,6 +1437,9 @@ are moved to close the gap. the index ## `length` the amount to remove + +Decreases the refcount of the buffer list. If the refcount reaches 0, the +buffer list will be freed. A `BufferPool` is an object that can be used to pre-allocate and recycle buffers of the same size and with the same properties. @@ -1400,7 +1481,7 @@ 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) +[`BufferPoolExt`](trait.BufferPoolExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BufferPoolExtManual`](prelude/trait.BufferPoolExtManual.html) Trait containing all `BufferPool` methods. @@ -1773,7 +1854,7 @@ can set a new one. The bus watch will only work if a GLib main loop is being run. When `func` is called, the message belongs to the caller; if you want to -keep a copy of it, call `gst_message_ref` before leaving `func`. +keep a copy of it, call `Message::ref` before leaving `func`. 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 @@ -1837,9 +1918,9 @@ responsible for calling `Bus::disable_sync_message_emission` as many times as this function is called. While this function looks similar to `Bus::add_signal_watch`, it is not -exactly the same -- this function enables ``synchronous`` emission of +exactly the same -- this function enables *synchronous* emission of signals when messages arrive; `Bus::add_signal_watch` adds an idle callback -to pop messages off the bus ``asynchronously``. The sync-message signal +to pop messages off the bus *asynchronously*. The sync-message signal comes from the thread of whatever object posted the message; the "message" signal is marshalled to the main thread via the main loop. @@ -1924,7 +2005,7 @@ indefinitely. the message that was received, or `None` if the poll timed out. The message is taken from the - bus and needs to be unreffed with `gst_message_unref` after + bus and needs to be unreffed with `Message::unref` after usage. Get a message from the bus. @@ -1933,7 +2014,7 @@ Get a message from the bus. the `Message` that is on the bus, or `None` if the bus is empty. The message is taken from - the bus and needs to be unreffed with `gst_message_unref` after + the bus and needs to be unreffed with `Message::unref` after usage. MT safe. @@ -1951,7 +2032,7 @@ message types to take into account the next `Message` matching `type_` that is on the bus, or `None` if the bus is empty or there is no message matching `type_`. The message is taken from the bus - and needs to be unreffed with `gst_message_unref` after usage. + and needs to be unreffed with `Message::unref` after usage. MT safe. @@ -1991,8 +2072,8 @@ function is usually only called by the creator of the bus. Applications should handle messages asynchronously using the gst_bus watch and poll functions. -You cannot replace an existing sync_handler. You can pass `None` to this -function, which will clear the existing handler. +Before 1.16.3 it was not possible to replace an existing handler and +clearing an existing handler with `None` was not thread-safe. ## `func` The handler function to install ## `user_data` @@ -2024,7 +2105,7 @@ a timeout the `Message` that is on the bus after the specified timeout or `None` if the bus is empty after the timeout expired. The message is taken from the bus - and needs to be unreffed with `gst_message_unref` after usage. + and needs to be unreffed with `Message::unref` after usage. MT safe. @@ -2045,7 +2126,7 @@ message types to take into account, GST_MESSAGE_ANY for any type a `Message` matching the filter in `types`, or `None` if no matching message was found on the bus until the timeout expired. The message is taken from - the bus and needs to be unreffed with `gst_message_unref` after + the bus and needs to be unreffed with `Message::unref` after usage. MT safe. @@ -2199,11 +2280,11 @@ a `Caps` to intersect Creates a new `Caps` as a copy of the old `self`. The new caps will have a refcount of 1, owned by the caller. The structures are copied as well. -Note that this function is the semantic equivalent of a `gst_caps_ref` +Note that this function is the semantic equivalent of a `Caps::ref` followed by a `gst_caps_make_writable`. If you only want to hold on to a -reference to the data, you should use `gst_caps_ref`. +reference to the data, you should use `Caps::ref`. -When you are finished with the caps, call `gst_caps_unref` on it. +When you are finished with the caps, call `Caps::unref` on it. # Returns @@ -2238,7 +2319,13 @@ fixated with `Structure::fixate`. This function takes ownership of `self` and will call `gst_caps_make_writable` on it so you must not use `self` afterwards unless you keep an additional -reference to it with `gst_caps_ref`. +reference to it with `Caps::ref`. + +Note that it is not guaranteed that the returned caps have exactly one +structure. If `self` are empty caps then then returned caps will be +the empty too and contain no structure at all. + +Calling this function with any caps is not allowed. # Returns @@ -2459,11 +2546,24 @@ Returns a `Caps` that represents the same set of formats as This function takes ownership of `self` and will call `gst_caps_make_writable` on it so you must not use `self` afterwards unless you keep an additional -reference to it with `gst_caps_ref`. +reference to it with `Caps::ref`. # Returns the normalized `Caps` + +Add a reference to a `Caps` object. + +From this point on, until the caller calls `Caps::unref` or +`gst_caps_make_writable`, it is guaranteed that the caps object will not +change. This means its structures won't change, etc. To use a `Caps` +object, you must always have a refcount on it -- either the one made +implicitly by e.g. `Caps::new_simple`, or via taking one explicitly with +this function. + +# Returns + +the same `Caps` object. removes the structure with the given index from the list of structures contained in `self`. @@ -2510,7 +2610,7 @@ merged are also merged. This function takes ownership of `self` and will call `gst_caps_make_writable` on it if necessary, so you must not use `self` afterwards unless you keep an -additional reference to it with `gst_caps_ref`. +additional reference to it with `Caps::ref`. This method does not preserve the original order of `self`. @@ -2560,11 +2660,18 @@ fixating. This function takes ownership of `self` and will call `gst_caps_make_writable` on it if necessary, so you must not use `self` afterwards unless you keep an -additional reference to it with `gst_caps_ref`. +additional reference to it with `Caps::ref`. + +Note that it is not guaranteed that the returned caps have exactly one +structure. If `self` is any or empty caps then then returned caps will be +the same and contain no structure at all. # Returns truncated caps + +Unref a `Caps` and and free all its structures and the +structures' values when the refcount reaches 0. Converts `caps` from a string representation. @@ -2576,6 +2683,37 @@ a string to convert to `Caps` # Returns a newly allocated `Caps` + +Modifies a pointer to a `Caps` to point to a different `Caps`. The +modification is done atomically (so this is useful for ensuring thread safety +in some cases), and the reference counts are updated appropriately (the old +caps is unreffed, the new is reffed). + +Either `new_caps` or the `Caps` pointed to by `old_caps` may be `None`. +## `old_caps` +pointer to a pointer + to a `Caps` to be replaced. +## `new_caps` +pointer to a `Caps` that will + replace the caps pointed to by `old_caps`. + +# Returns + +`true` if `new_caps` was different from `old_caps` + +Modifies a pointer to a `Caps` to point to a different `Caps`. This +function is similar to `Caps::replace` except that it takes ownership +of `new_caps`. +## `old_caps` +pointer to a pointer to a `Caps` to be + replaced. +## `new_caps` +pointer to a `Caps` that will + replace the caps pointed to by `old_caps`. + +# Returns + +`true` if `new_caps` was different from `old_caps` Modes of caps intersection @@ -2618,7 +2756,7 @@ scheme is recursive. Thus "child1::child2::property" is valid too, if # Implements -[`ChildProxyExt`](trait.ChildProxyExt.html) +[`ChildProxyExt`](trait.ChildProxyExt.html), [`ChildProxyExtManual`](prelude/trait.ChildProxyExtManual.html) Trait containing all `ChildProxy` methods. @@ -2810,7 +2948,7 @@ defines the minimum number of samples before the calibration is performed. # Implements -[`ClockExt`](trait.ClockExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`ClockExt`](trait.ClockExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ClockExtManual`](prelude/trait.ClockExtManual.html) Trait containing all `Clock` methods. @@ -3332,6 +3470,9 @@ monotonic time since some unspecified starting point some other time source is used (Since: 1.0.5) + +time since Epoch, but using International Atomic Time + as reference (Since: 1.18) `Context` is a container object used to store contexts like a device context, a display server connection and similar concepts that should @@ -3526,6 +3667,18 @@ seconds from the Unix epoch # Returns the newly created `DateTime` + +Creates a new `DateTime` using the time since Jan 1, 1970 specified by +`usecs`. The `DateTime` is in the local timezone. + +Feature: `v1_18` + +## `usecs` +microseconds from the Unix epoch + +# Returns + +a newly created `DateTime` Creates a new `DateTime` using the time since Jan 1, 1970 specified by `secs`. The `DateTime` is in the UTC timezone. @@ -3537,6 +3690,18 @@ seconds from the Unix epoch # Returns the newly created `DateTime` + +Creates a new `DateTime` using the time since Jan 1, 1970 specified by +`usecs`. The `DateTime` is in UTC. + +Feature: `v1_18` + +## `usecs` +microseconds from the Unix epoch + +# Returns + +a newly created `DateTime` Creates a new `DateTime` using the date and times in the gregorian calendar in the local timezone. @@ -3845,7 +4010,7 @@ Getter for the `Caps` that this device supports. # Returns The `Caps` supported by this device. Unref with -`gst_caps_unref` when done. +`Caps::unref` when done. Gets the "class" of a device. This is a "/" separated list of classes that represent this device. They are a subset of the @@ -3965,7 +4130,7 @@ The basic use pattern of a device monitor is as follows: # Implements -[`DeviceMonitorExt`](trait.DeviceMonitorExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`DeviceMonitorExt`](trait.DeviceMonitorExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`DeviceMonitorExtManual`](prelude/trait.DeviceMonitorExtManual.html) Trait containing all `DeviceMonitor` methods. @@ -4024,7 +4189,7 @@ This A list of device provider factory names that are currently being monitored by `self` or `None` when nothing is being monitored. -Get if `self` is curretly showing all devices, even those from hidden +Get if `self` is currently showing all devices, even those from hidden providers. # Returns @@ -4067,7 +4232,7 @@ from all relevant providers. # Implements -[`DeviceProviderExt`](trait.DeviceProviderExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`DeviceProviderExt`](trait.DeviceProviderExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`DeviceProviderExtManual`](prelude/trait.DeviceProviderExtManual.html) Trait containing all `DeviceProvider` methods. @@ -4112,7 +4277,7 @@ Feature: `v1_16` ## `device` the new version of `changed_device` ## `changed_device` -the old version of the device that has been udpated +the old version of the device that has been updated Posts a message on the provider's `Bus` to inform applications that a device has been removed. @@ -4207,7 +4372,7 @@ convenient shortcut. # Implements -[`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PluginFeatureExtManual`](prelude/trait.PluginFeatureExtManual.html) Search for an device provider factory of the given name. Refs the returned device provider factory; caller is responsible for unreffing. @@ -4343,7 +4508,7 @@ specific situations. # Implements -[`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ElementExtManual`](prelude/trait.ElementExtManual.html) Trait containing all `Element` methods. @@ -4654,6 +4819,29 @@ MT safe. # Returns List of `Context` + +Returns the current clock time of the element, as in, the time of the +element's clock, or GST_CLOCK_TIME_NONE if there is no clock. + +Feature: `v1_18` + + +# Returns + +the clock time of the element, or GST_CLOCK_TIME_NONE if there is +no clock. + +Returns the running time of the element. The running time is the +element's clock time minus its base time. Will return GST_CLOCK_TIME_NONE +if the element has no clock, or if its base time has not been set. + +Feature: `v1_18` + + +# Returns + +the running time of the element, or GST_CLOCK_TIME_NONE if the +element has no clock or its base time has not been set. Retrieves the factory that was used to create this element. @@ -5223,7 +5411,7 @@ event handler, the event will be pushed on a random linked sink pad for downstream events or a random linked source pad for upstream events. This function takes ownership of the provided event so you should -`gst_event_ref` it if you want to reuse the event after this call. +`Event::ref` it if you want to reuse the event after this call. MT safe. ## `event` @@ -5396,7 +5584,7 @@ The following code example shows you how to create a GstFileSrc element. # Implements -[`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PluginFeatureExtManual`](prelude/trait.PluginFeatureExtManual.html) Search for an element factory of the given name. Refs the returned element factory; caller is responsible for unreffing. @@ -5581,7 +5769,7 @@ Events are usually created with gst_event_new_*() which takes event-type specific parameters as arguments. To send an event application will usually use `Element::send_event` and elements will use `Pad::send_event` or `Pad::push_event`. -The event should be unreffed with `gst_event_unref` if it has not been sent. +The event should be unreffed with `Event::unref` if it has not been sent. Events that have been received can be parsed with their respective gst_event_parse_*() functions. It is valid to pass `None` for unwanted details. @@ -5731,6 +5919,54 @@ the duration of the gap # Returns the new GAP event. + +Create a new instant-rate-change event. This event is sent by seek +handlers (e.g. demuxers) when receiving a seek with the +`SeekFlags::InstantRateChange` and signals to downstream elements that +the playback rate in the existing segment should be immediately multiplied +by the `rate_multiplier` factor. + +The flags provided replace any flags in the existing segment, for the +flags within the `GST_SEGMENT_INSTANT_FLAGS` set. Other GstSegmentFlags +are ignored and not transferred in the event. + +Feature: `v1_18` + +## `rate_multiplier` +the multiplier to be applied to the playback rate +## `new_flags` +A new subset of segment flags to replace in segments + +# Returns + +the new instant-rate-change event. + +Create a new instant-rate-sync-time event. This event is sent by the +pipeline to notify elements handling the instant-rate-change event about +the running-time when the new rate should be applied. The running time +may be in the past when elements handle this event, which can lead to +switching artifacts. The magnitude of those depends on the exact timing +of event delivery to each element and the magnitude of the change in +playback rate being applied. + +The `running_time` and `upstream_running_time` are the same if this +is the first instant-rate adjustment, but will differ for later ones +to compensate for the accumulated offset due to playing at a rate +different to the one indicated in the playback segments. + +Feature: `v1_18` + +## `rate_multiplier` +the new playback rate multiplier to be applied +## `running_time` +Running time when the rate change should be applied +## `upstream_running_time` +The upstream-centric running-time when the + rate change should be applied. + +# Returns + +the new instant-rate-sync-time event. Create a new latency event. The event is sent upstream from the sinks and notifies elements that they should add an additional `latency` to the @@ -6126,6 +6362,12 @@ UID in the TOC to start playback from. # Returns a new `Event`. + +Copy the event using the event specific copy function. + +# Returns + +the new event Parses a segment `self` and copies the `Segment` into the location given by `segment`. @@ -6184,6 +6426,18 @@ name to check # Returns +`true` if `name` matches the name of the event structure. + +Checks if `self` has the given `name`. This function is usually used to +check the name of a custom event. + +Feature: `v1_18` + +## `name` +name to check as a GQuark + +# Returns + `true` if `name` matches the name of the event structure. Get the format, minsize, maxsize and async-flag in the buffersize event. @@ -6220,6 +6474,31 @@ address of variable where to store the group id `true` if a group id was set on the event and could be parsed, `false` otherwise. + +Extract rate and flags from an instant-rate-change event. + +Feature: `v1_18` + +## `rate_multiplier` +location in which to store the rate + multiplier of the instant-rate-change event, or `None` +## `new_flags` +location in which to store the new + segment flags of the instant-rate-change event, or `None` + +Extract the rate multiplier and running times from an instant-rate-sync-time event. + +Feature: `v1_18` + +## `rate_multiplier` +location where to store the rate of + the instant-rate-sync-time event, or `None` +## `running_time` +location in which to store the running time + of the instant-rate-sync-time event, or `None` +## `upstream_running_time` +location in which to store the + upstream running time of the instant-rate-sync-time event, or `None` Get the latency in the latency event. ## `latency` @@ -6358,6 +6637,12 @@ pointer to store TOC updated flag. Parse a TOC select `self` and store the results in the given `uid` location. ## `uid` storage for the selection UID. + +Increase the refcount of this event. + +# Returns + +`self` (for convenience when doing assignments) All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the @@ -6402,6 +6687,8 @@ the stream object to set ## `flags` the stream flags to set + +Decrease the refcount of an event, freeing it if the refcount reaches 0. Get a writable version of the structure. @@ -6414,6 +6701,49 @@ This function checks if `self` is writable and will never return `None`. MT safe. + +Modifies a pointer to a `Event` to point to a different `Event`. The +modification is done atomically (so this is useful for ensuring thread safety +in some cases), and the reference counts are updated appropriately (the old +event is unreffed, the new one is reffed). + +Either `new_event` or the `Event` pointed to by `old_event` may be `None`. +## `old_event` +pointer to a + pointer to a `Event` to be replaced. +## `new_event` +pointer to a `Event` that will + replace the event pointed to by `old_event`. + +# Returns + +`true` if `new_event` was different from `old_event` + +Atomically replace the `Event` pointed to by `old_event` with `None` and +return the original event. +## `old_event` +pointer to a + pointer to a `Event` to be stolen. + +# Returns + +the `Event` that was in `old_event` + +Modifies a pointer to a `Event` to point to a different `Event`. This +function is similar to `Event::replace` except that it takes ownership of +`new_event`. + +Either `new_event` or the `Event` pointed to by `old_event` may be `None`. +## `old_event` +pointer to a + pointer to a `Event` to be stolen. +## `new_event` +pointer to a `Event` that will + replace the event pointed to by `old_event`. + +# Returns + +`true` if `new_event` was different from `old_event` `EventType` lists the standard event types that can be sent in a pipeline. @@ -6470,6 +6800,9 @@ An event which indicates that new or updated Marks the end of a segment playback. Marks a gap in the datastream. + +Notify downstream that a playback rate override + should be applied as soon as possible. (Since: 1.18) A quality message. Used to indicate to upstream elements that the downstream elements should adjust their processing @@ -6493,6 +6826,10 @@ A request for a new playback position based on TOC entry's UID. A request to select one or more streams (Since: 1.10) + +Sent by the pipeline to notify elements that handle the + instant-rate-change event about the running-time when + the rate multiplier should be applied (or was applied). (Since: 1.18) Upstream custom event @@ -6583,7 +6920,7 @@ Note that GhostPads add overhead to the data processing of a pipeline. # Implements -[`GhostPadExt`](trait.GhostPadExt.html), [`ProxyPadExt`](trait.ProxyPadExt.html), [`PadExt`](trait.PadExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`GhostPadExt`](trait.GhostPadExt.html), [`ProxyPadExt`](trait.ProxyPadExt.html), [`PadExt`](trait.PadExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ProxyPadExtManual`](prelude/trait.ProxyPadExtManual.html), [`PadExtManual`](prelude/trait.PadExtManual.html) Trait containing all `GhostPad` methods. @@ -7019,6 +7356,24 @@ A GstStructure with details # Returns the new warning message. + +Creates a new instant-rate-request message. Elements handling the +instant-rate-change event must post this message. The message is +handled at the pipeline, and allows the pipeline to select the +running time when the rate change should happen and to send an +`EventType::InstantRateSyncTime` event to notify the elements +in the pipeline. + +Feature: `v1_18` + +## `src` +The `Object` that posted the message +## `rate_multiplier` +the rate multiplier factor that should be applied + +# Returns + +a newly allocated `Message` This message can be posted by elements when their latency requirements have changed. @@ -7136,8 +7491,8 @@ optional. The tag list and structure are useful for additional metadata, such as bitrate statistics for the given location. By default, message recipients should treat entries in the order they are -stored. The recipient should therefore try entry `0` first, and if this -entry is not acceptable or working, try entry `1` etc. Senders must make +stored. The recipient should therefore try entry \#0 first, and if this +entry is not acceptable or working, try entry \#1 etc. Senders must make sure that they add entries in this order. However, recipients are free to ignore the order and pick an entry that is "best" for them. One example would be a recipient that scans the entries for the one with the highest @@ -7467,6 +7822,14 @@ location string for the new entry tag list for the new entry ## `entry_struct` structure for the new entry + +Creates a copy of the message. Returns a copy of the message. + +# Returns + +a new copy of `self`. + +MT safe Feature: `v1_10` @@ -7675,6 +8038,13 @@ Feature: `v1_10` ## `structure` A pointer to the returned details structure + +Parses the rate_multiplier from the instant-rate-request message. + +Feature: `v1_18` + +## `rate_multiplier` +return location for the rate, or `None` Extracts the new clock from the GstMessage. The clock object returned remains valid until the message is freed. @@ -7967,6 +8337,12 @@ Feature: `v1_10` ## `structure` A pointer to the returned details structure + +Convenience macro to increase the reference count of the message. + +# Returns + +`self` (for convenience when doing assignments) Configures the buffering stats values in `self`. ## `mode` @@ -8061,6 +8437,9 @@ Index of the stream to retrieve # Returns A `Stream` + +Convenience macro to decrease the reference count of the message, possibly +freeing it. Get a writable version of the structure. @@ -8076,6 +8455,23 @@ This function checks if `self` is writable and will never return `None`. MT safe. + +Modifies a pointer to a `Message` to point to a different `Message`. The +modification is done atomically (so this is useful for ensuring thread safety +in some cases), and the reference counts are updated appropriately (the old +message is unreffed, the new one is reffed). + +Either `new_message` or the `Message` pointed to by `old_message` may be `None`. +## `old_message` +pointer to a + pointer to a `Message` to be replaced. +## `new_message` +pointer to a `Message` that will + replace the message pointed to by `old_message`. + +# Returns + +`true` if `new_message` was different from `old_message` `Object` provides a root for the object hierarchy tree filed in by the GStreamer library. It is currently a thin wrapper on top of @@ -8530,7 +8926,7 @@ which takes a direction and a name as an argument. If the name is `None`, then a guaranteed unique name will be assigned to it. A `Element` creating a pad will typically use the various -gst_pad_set_*`_function` calls to register callbacks for events, queries or +gst_pad_set_*_function\() calls to register callbacks for events, queries or dataflow on the pads. `gst_pad_get_parent` will retrieve the `Element` that owns the pad. @@ -8575,7 +8971,7 @@ respectively. # Implements -[`PadExt`](trait.PadExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`PadExt`](trait.PadExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PadExtManual`](prelude/trait.PadExtManual.html) Trait containing all `Pad` methods. @@ -8936,7 +9332,7 @@ installed (see `gst_pad_set_getrange_function`) this function returns If `buffer` points to a variable holding `None`, a valid new `Buffer` will be placed in `buffer` when this function returns `FlowReturn::Ok`. The new buffer -must be freed with `gst_buffer_unref` after usage. +must be freed with `Buffer::unref` after usage. When `buffer` points to a variable that points to a valid `Buffer`, the buffer will be filled with the result data when this function returns @@ -8965,6 +9361,18 @@ a pointer to hold the `Buffer`, a `FlowReturn` from the pad. MT safe. + +If there is a single internal link of the given pad, this function will +return it. Otherwise, it will return NULL. + +Feature: `v1_18` + + +# Returns + +a `Pad`, or `None` if `self` has none +or more than one internal links. Unref returned pad with +`GstObjectExt::unref`. Returns a new reference of the sticky event of type `event_type` from the event. @@ -9289,7 +9697,7 @@ semantics of the arguments of this function. If `buffer` points to a variable holding `None`, a valid new `Buffer` will be placed in `buffer` when this function returns `FlowReturn::Ok`. The new buffer -must be freed with `gst_buffer_unref` after usage. When this function +must be freed with `Buffer::unref` after usage. When this function returns any other result value, `buffer` will still point to `None`. When `buffer` points to a variable that points to a valid `Buffer`, the @@ -9342,7 +9750,7 @@ mainly used by elements to send events to their peer elements. This function takes ownership of the provided event so you should -`gst_event_ref` it if you want to reuse the event after this call. +`Event::ref` it if you want to reuse the event after this call. ## `event` the `Event` to send to the pad. @@ -9496,7 +9904,7 @@ plugin doesn't need to bother itself with this information; the core handles all necessary locks and checks. This function takes ownership of the provided event so you should -`gst_event_ref` it if you want to reuse the event after this call. +`Event::ref` it if you want to reuse the event after this call. ## `event` the `Event` to send to the pad. @@ -10046,7 +10454,7 @@ in the PLAYING state. This default behaviour can be changed with the # Implements -[`PipelineExt`](trait.PipelineExt.html), [`GstBinExt`](trait.GstBinExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ChildProxyExt`](trait.ChildProxyExt.html) +[`PipelineExt`](trait.PipelineExt.html), [`GstBinExt`](trait.GstBinExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ChildProxyExt`](trait.ChildProxyExt.html), [`ElementExtManual`](prelude/trait.ElementExtManual.html), [`ChildProxyExtManual`](prelude/trait.ChildProxyExtManual.html) Trait containing all `Pipeline` methods. @@ -10212,15 +10620,15 @@ Latency to configure on the pipeline. See `PipelineExt::set_latency`. Latency to configure on the pipeline. See `PipelineExt::set_latency`. GStreamer is extensible, so `Element` instances can be loaded at runtime. -A plugin system can provide one or more of the basic -``GStreamer`` `PluginFeature` subclasses. +A plugin system can provide one or more of the basic GStreamer +`PluginFeature` subclasses. -A plugin should export a symbol ``gst_plugin_desc`` that is a +A plugin should export a symbol `gst_plugin_desc` that is a struct of type `PluginDesc`. the plugin loader will check the version of the core library the plugin was linked against and will create a new `Plugin`. It will then call the `GstPluginInitFunc` function that was provided in the -``gst_plugin_desc``. +`gst_plugin_desc`. Once you have a handle to a `Plugin` (e.g. from the `Registry`), you can add any object that subclasses `PluginFeature`. @@ -10500,7 +10908,7 @@ This is a base class for anything that can be added to a `Plugin`. # Implements -[`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PluginFeatureExtManual`](prelude/trait.PluginFeatureExtManual.html) Trait containing all `PluginFeature` methods. @@ -10755,14 +11163,16 @@ A task caused an error. An error message is also 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 +with `Promise::reply`. The exact value returned is defined by the API +contract of the producer and `None` may be a valid 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 @@ -10900,7 +11310,7 @@ Feature: `v1_14` # Implements -[`ProxyPadExt`](trait.ProxyPadExt.html), [`PadExt`](trait.PadExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`ProxyPadExt`](trait.ProxyPadExt.html), [`PadExt`](trait.PadExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ProxyPadExtManual`](prelude/trait.ProxyPadExtManual.html), [`PadExtManual`](prelude/trait.PadExtManual.html) Trait containing all `ProxyPad` methods. @@ -11014,7 +11424,7 @@ The following example shows how to query the duration of a pipeline: Constructs a new query object for querying if `caps` are accepted. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `caps` a fixed `Caps` @@ -11024,7 +11434,7 @@ a new `Query` Constructs a new query object for querying the allocation properties. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `caps` the negotiated caps ## `need_pool` @@ -11036,7 +11446,7 @@ a new `Query` Constructs a new query object for querying the bitrate. -Free-function: `gst_query_unref` +Free-function: `Query::unref` Feature: `v1_16` @@ -11048,7 +11458,7 @@ a new `Query` Constructs a new query object for querying the buffering status of a stream. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `format` the default `Format` for the new query @@ -11075,7 +11485,7 @@ The `filter` is used to restrict the result caps, only the caps matching `filter` should be returned from the CAPS query. Specifying a filter might greatly reduce the amount of processing an element needs to do. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `filter` a filter @@ -11085,7 +11495,7 @@ a new `Query` Constructs a new query object for querying the pipeline-local context. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `context_type` Context type to query @@ -11093,11 +11503,11 @@ Context type to query a new `Query` -Constructs a new convert query object. Use `gst_query_unref` +Constructs a new convert query object. Use `Query::unref` when done with it. A convert query is used to ask for a conversion between one format and another. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `src_format` the source `Format` for the new query ## `value` @@ -11109,10 +11519,10 @@ the target `Format` a `Query` -Constructs a new custom query object. Use `gst_query_unref` +Constructs a new custom query object. Use `Query::unref` when done with it. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `type_` the query type ## `structure` @@ -11124,17 +11534,17 @@ a new `Query` Constructs a new query object for querying the drain state. -Free-function: `gst_query_unref` +Free-function: `Query::unref` # Returns a new `Query` Constructs a new stream duration query object to query in the given format. -Use `gst_query_unref` when done with it. A duration query will give the +Use `Query::unref` when done with it. A duration query will give the total length of the stream. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `format` the `Format` for this duration query @@ -11145,28 +11555,28 @@ a new `Query` Constructs a new query object for querying formats of the stream. -Free-function: `gst_query_unref` +Free-function: `Query::unref` # Returns a new `Query` Constructs a new latency query object. -Use `gst_query_unref` when done with it. A latency query is usually performed +Use `Query::unref` when done with it. A latency query is usually performed by sinks to compensate for additional latency introduced by elements in the pipeline. -Free-function: `gst_query_unref` +Free-function: `Query::unref` # Returns a `Query` -Constructs a new query stream position query object. Use `gst_query_unref` +Constructs a new query stream position query object. Use `Query::unref` when done with it. A position query is used to query the current position of playback in the streams, in some format. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `format` the default `Format` for the new query @@ -11176,7 +11586,7 @@ a new `Query` Constructs a new query object for querying the scheduling properties. -Free-function: `gst_query_unref` +Free-function: `Query::unref` # Returns @@ -11185,7 +11595,7 @@ a new `Query` Constructs a new query object for querying seeking properties of the stream. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `format` the default `Format` for the new query @@ -11193,11 +11603,11 @@ the default `Format` for the new query a new `Query` -Constructs a new segment query object. Use `gst_query_unref` +Constructs a new segment query object. Use `Query::unref` when done with it. A segment query is used to discover information about the currently configured segment for playback. -Free-function: `gst_query_unref` +Free-function: `Query::unref` ## `format` the `Format` for the new query @@ -11205,11 +11615,11 @@ the `Format` for the new query a new `Query` -Constructs a new query URI query object. Use `gst_query_unref` +Constructs a new query URI query object. Use `Query::unref` when done with it. An URI query is used to query the current URI that is used by the source or sink. -Free-function: `gst_query_unref` +Free-function: `Query::unref` # Returns @@ -11251,6 +11661,14 @@ a `gboolean` indicating if the range was added or not. Add `mode` as one of the supported scheduling modes to `self`. ## `mode` a `PadMode` + +Copies the given query using the copy function of the parent `Structure`. + +Free-function: gst_query_unref + +# Returns + +a new copy of `self`. Check if `self` has metadata `api` set. When this function returns `true`, `index` will contain the index where the requested API and the parameters @@ -11762,6 +12180,9 @@ Answer a URI query by setting the requested URI redirection to permanent or not. ## `permanent` whether the redirect is permanent or not + +Decreases the refcount of the query. If the refcount reaches 0, the query +will be freed. Get the structure of a query. This method should be called with a writable `self` so that the returned structure is guaranteed to be writable. @@ -11771,6 +12192,23 @@ 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. + +Modifies a pointer to a `Query` to point to a different `Query`. The +modification is done atomically (so this is useful for ensuring thread safety +in some cases), and the reference counts are updated appropriately (the old +query is unreffed, the new one is reffed). + +Either `new_query` or the `Query` pointed to by `old_query` may be `None`. +## `old_query` +pointer to a pointer to a + `Query` to be replaced. +## `new_query` +pointer to a `Query` that will + replace the query pointed to by `old_query`. + +# Returns + +`true` if `new_query` was different from `old_query` Element priority ranks. Defines the order in which the autoplugger (or similar rank-picking mechanisms, such as e.g. `Element::make_from_uri`) @@ -12131,8 +12569,15 @@ a `Structure`, or `None` # Returns -the new `Sample`. `gst_sample_unref` +the new `Sample`. `Sample::unref` after usage. + +Create a copy of the given sample. This will also make a newly allocated +copy of the data the source sample contains. + +# Returns + +a new copy of `self`. Get the buffer associated with `self` @@ -12141,7 +12586,7 @@ Get the buffer associated with `self` the buffer of `self` or `None` when there is no buffer. The buffer remains valid as long as `self` is valid. If you need to hold on to it for longer than - that, take a ref to the buffer with `gst_buffer_ref`. + that, take a ref to the buffer with `Buffer::ref`. Get the buffer list associated with `self` @@ -12159,7 +12604,7 @@ Get the caps associated with `self` the caps of `self` or `None` when there is no caps. The caps remain valid as long as `self` is valid. If you need to hold on to the caps for longer than that, - take a ref to the caps with `gst_caps_ref`. + take a ref to the caps with `Caps::ref`. Get extra information associated with `self`. @@ -12174,6 +12619,12 @@ Get the segment associated with `self` the segment of `self`. The segment remains valid as long as `self` is valid. + +Increases the refcount of the given sample by one. + +# Returns + +`self` Set the buffer associated with `self`. `self` must be writable. @@ -12207,6 +12658,9 @@ Feature: `v1_16` ## `segment` A `Segment` + +Decreases the refcount of the sample. If the refcount reaches 0, the +sample will be freed. The different types of seek events. When constructing a seek event with `Event::new_seek` or when doing gst_segment_do_seek (). @@ -12694,38 +13148,6 @@ the state change will happen asynchronously the state change succeeded but the element cannot produce data in `State::Paused`. This typically happens with live sources. - -Datastructure to initialize `Caps` from a string description usually -used in conjunction with GST_STATIC_CAPS() and `StaticCaps::get` to -instantiate a `Caps`. - -Clean up the cached caps contained in `self`. - -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. - -Structure describing the `StaticPadTemplate`. - -Converts a `StaticPadTemplate` into a `PadTemplate`. - -# Returns - -a new `PadTemplate`. - -Gets the capabilities of the static pad template. - -# Returns - -the `Caps` of the static pad template. -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 high-level object representing a single stream. It might be backed, or not, by an actual flow of data in a pipeline (`Pad`). @@ -13025,6 +13447,22 @@ has limited support for nested `Caps` / `Structure` fields. It can only support one level of nesting. Using more levels will lead to unexpected behavior when using serialization features, such as `Caps::to_string` or `gst_value_serialize` and their counterparts. + +Creates a `Structure` from a string representation. +If end is not `None`, a pointer to the place inside the given string +where parsing ended will be returned. + +Free-function: gst_structure_free +## `string` +a string representation of a `Structure`. +## `end` +pointer to store the end of the string in. + +# Returns + +a new `Structure` or `None` + when the string could not be parsed. Free with + `Structure::free` after use. Creates a new `Structure` with the given name. Parses the list of variable arguments and sets fields to the values listed. @@ -13233,7 +13671,7 @@ Variable arguments should be in the form field name, field type The last variable argument should be `None`. For refcounted (mini)objects you will receive a new reference which -you must release with a suitable `_unref` when no longer needed. For +you must release with a suitable _unref\() when no longer needed. For strings and boxed types you will receive a copy which you will need to release with either `g_free` or the suitable function for the boxed type. ## `first_fieldname` @@ -13556,7 +13994,7 @@ more efficient since it saves the string-to-quark lookup in the global quark hashtable. For refcounted (mini)objects you will receive a new reference which -you must release with a suitable `_unref` when no longer needed. For +you must release with a suitable _unref\() when no longer needed. For strings and boxed types you will receive a copy which you will need to release with either `g_free` or the suitable function for the boxed type. ## `first_field_id` @@ -13796,22 +14234,27 @@ Free-function: g_free a pointer to string allocated by `g_malloc`. `g_free` after usage. - -Creates a `Structure` from a string representation. -If end is not `None`, a pointer to the place inside the given string -where parsing ended will be returned. + +Atomically modifies a pointer to point to a new structure. +The `Structure` `oldstr_ptr` is pointing to is freed and +`newstr` is taken ownership over. -Free-function: gst_structure_free -## `string` -a string representation of a `Structure`. -## `end` -pointer to store the end of the string in. +Either `newstr` and the value pointed to by `oldstr_ptr` may be `None`. + +It is a programming error if both `newstr` and the value pointed to by +`oldstr_ptr` refer to the same, non-`None` structure. + +Feature: `v1_18` + +## `oldstr_ptr` +pointer to a place of + a `Structure` to take +## `newstr` +a new `Structure` # Returns -a new `Structure` or `None` - when the string could not be parsed. Free with - `Structure::free` after use. +`true` if `newstr` was different from `oldstr_ptr` The type of a `MessageType::StructureChange`. @@ -13831,7 +14274,7 @@ wait operations. # Implements -[`SystemClockExt`](trait.SystemClockExt.html), [`ClockExt`](trait.ClockExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`SystemClockExt`](trait.SystemClockExt.html), [`ClockExt`](trait.ClockExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ClockExtManual`](prelude/trait.ClockExtManual.html) Trait containing all `SystemClock` methods. @@ -13895,7 +14338,7 @@ tag # Returns -a new `TagList`. Free with `gst_tag_list_unref` +a new `TagList`. Free with `TagList::unref` when no longer needed. Creates a new empty GstTagList. @@ -13924,7 +14367,7 @@ tag / value pairs to set # Returns -a new `TagList`. Free with `gst_tag_list_unref` +a new `TagList`. Free with `TagList::unref` when no longer needed. Sets the values for the given tags using the specified mode. @@ -13962,6 +14405,20 @@ Sets the GValues for the given tags using the specified mode. the mode to use ## `tag` tag + +Creates a new `TagList` as a copy of the old `self`. The new taglist +will have a refcount of 1, owned by the caller, and will be writable as +a result. + +Note that this function is the semantic equivalent of a `TagList::ref` +followed by a `gst_tag_list_make_writable`. If you only want to hold on to a +reference to the data, you should use `TagList::ref`. + +When you are finished with the taglist, call `TagList::unref` on it. + +# Returns + +the new `TagList` Calls the given function for each tag inside the tag list. Note that if there is no tag, the function won't be called at all. @@ -14193,7 +14650,7 @@ location for the result given list. Copies the first sample for the given tag in the taglist into the variable -pointed to by `sample`. Free the sample with `gst_sample_unref` when it is +pointed to by `sample`. Free the sample with `Sample::unref` when it is no longer needed. You can retrieve the buffer from the sample using `Sample::get_buffer` and the associated caps (if any) with `Sample::get_caps`. @@ -14212,7 +14669,7 @@ address of a GstSample Gets the sample that is at the given index for the given tag in the given list and copies it into the variable pointed to by `sample`. Free the sample -with `gst_sample_unref` when it is no longer needed. You can retrieve the +with `Sample::unref` when it is no longer needed. You can retrieve the buffer from the sample using `Sample::get_buffer` and the associated caps (if any) with `Sample::get_caps`. @@ -14414,6 +14871,18 @@ location for the result `true`, if a value was set, `false` if the tag didn't exist in the given list. + +Add a reference to a `TagList` mini object. + +From this point on, until the caller calls `TagList::unref` or +`gst_tag_list_make_writable`, it is guaranteed that the taglist object will +not change. To use a `TagList` object, you must always have a refcount on +it -- either the one made implicitly by e.g. `TagList::new`, or via +taking one explicitly with this function. + +# Returns + +the same `TagList` mini object. Removes the given tag from the taglist. ## `tag` @@ -14431,6 +14900,8 @@ Serializes a tag list to a string. a newly-allocated string, or `None` in case of an error. The string must be freed with `g_free` when no longer needed. + +Unref a `TagList`, and and free all its memory when the refcount reaches 0. Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated @@ -14456,64 +14927,14 @@ e.g. via `TagSetter::merge_tags` / `TagSetter::add_tags` or a In the table below this is shown for the cases that a tag exists in the list (A) or does not exists (!A) and combinations thereof. - - ``merge mode`` - - `` - `` - ``merge mode`` - ``A + B`` - ``A + !B`` - ``!A + B`` - ``!A + !B`` - `` - `` - `` - `` - ``REPLACE_ALL`` - ``B`` - ``-`` - ``B`` - ``-`` - `` - `` - ``REPLACE`` - ``B`` - ``A`` - ``B`` - ``-`` - `` - `` - ``APPEND`` - ``A, B`` - ``A`` - ``B`` - ``-`` - `` - `` - ``PREPEND`` - ``B, A`` - ``A`` - ``B`` - ``-`` - `` - `` - ``KEEP`` - ``A`` - ``A`` - ``B`` - ``-`` - `` - `` - ``KEEP_ALL`` - ``A`` - ``A`` - ``-`` - ``-`` - `` - `` - `` -`
` +| merge mode | A + B | A + !B | !A + B | !A + !B | +| ----------- | ----- | ------ | ------ | ------- | +| REPLACE_ALL | B | ø | B | ø | +| REPLACE | B | A | B | ø | +| APPEND | A, B | A | B | ø | +| PREPEND | B, A | A | B | ø | +| KEEP | A | A | B | ø | +| KEEP_ALL | A | A | ø | ø | undefined merge mode @@ -14582,7 +15003,7 @@ GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result); # Implements -[`TagSetterExt`](trait.TagSetterExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`TagSetterExt`](trait.TagSetterExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`TagSetterExtManual`](prelude/trait.TagSetterExtManual.html), [`ElementExtManual`](prelude/trait.ElementExtManual.html) Trait containing all `TagSetter` methods. @@ -14935,7 +15356,7 @@ with any TOC entries received from downstream. # Implements -[`TocSetterExt`](trait.TocSetterExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`TocSetterExt`](trait.TocSetterExt.html), [`ElementExt`](trait.ElementExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ElementExtManual`](prelude/trait.ElementExtManual.html) Trait containing all `TocSetter` methods. @@ -15012,7 +15433,7 @@ that though. # Implements -[`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) +[`PluginFeatureExt`](trait.PluginFeatureExt.html), [`GstObjectExt`](trait.GstObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PluginFeatureExtManual`](prelude/trait.PluginFeatureExtManual.html) Gets the list of all registered typefind factories. You must free the list using `PluginFeature::list_free`.