diff --git a/Cargo.toml b/Cargo.toml index 5b4d1b554..3519ff3e7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -45,7 +45,6 @@ members = [ "gstreamer-webrtc", "examples", "tutorials", - "docs", ] exclude = ["gir"] diff --git a/deny.toml b/deny.toml index 369463599..9bfa47129 100644 --- a/deny.toml +++ b/deny.toml @@ -22,10 +22,6 @@ copyleft = "deny" allow-osi-fsf-free = "either" confidence-threshold = 0.8 -[[licenses.exceptions]] -allow = ["LGPL-2.0"] -name = "gstreamer-rs-lgpl-docs" - [bans] multiple-versions = "deny" wildcards = "allow" diff --git a/docs/Cargo.toml b/docs/Cargo.toml deleted file mode 100644 index 575d4fdfe..000000000 --- a/docs/Cargo.toml +++ /dev/null @@ -1,15 +0,0 @@ -[package] -name = "gstreamer-rs-lgpl-docs" -version = "0.17.0" -authors = ["Sebastian Dröge "] -license = "LGPL-2.0" -description = "LGPL-licensed docs for gstreamer-rs crates" -repository = "https://gitlab.freedesktop.org/gstreamer/gstreamer-rs" -homepage = "https://gstreamer.freedesktop.org" -edition = "2018" - -[lib] -name = "lgpl_docs" - -[dependencies] -rustdoc-stripper = "0.1.6" diff --git a/docs/gstreamer-app/docs.md b/docs/gstreamer-app/docs.md deleted file mode 100644 index 04d5fd4a2..000000000 --- a/docs/gstreamer-app/docs.md +++ /dev/null @@ -1,792 +0,0 @@ - - -Appsink is a sink plugin that supports many different methods for making -the application get a handle on the GStreamer data in a pipeline. Unlike -most GStreamer elements, Appsink provides external API functions. - -appsink can be used by linking to the gstappsink.h header file to access the -methods or by using the appsink action signals and properties. - -The normal way of retrieving samples from appsink is by using the -`AppSink::pull_sample` and `AppSink::pull_preroll` methods. -These methods block until a sample becomes available in the sink or when the -sink is shut down or reaches EOS. There are also timed variants of these -methods, `AppSink::try_pull_sample` and `AppSink::try_pull_preroll`, -which accept a timeout parameter to limit the amount of time to wait. - -Appsink will internally use a queue to collect buffers from the streaming -thread. If the application is not pulling samples fast enough, this queue -will consume a lot of memory over time. The "max-buffers" property can be -used to limit the queue size. The "drop" property controls whether the -streaming thread blocks or if older buffers are dropped when the maximum -queue size is reached. Note that blocking the streaming thread can negatively -affect real-time performance and should be avoided. - -If a blocking behaviour is not desirable, setting the "emit-signals" property -to `true` will make appsink emit the "new-sample" and "new-preroll" signals -when a sample can be pulled without blocking. - -The "caps" property on appsink can be used to control the formats that -appsink can receive. This property can contain non-fixed caps, the format of -the pulled samples can be obtained by getting the sample caps. - -If one of the pull-preroll or pull-sample methods return `None`, the appsink -is stopped or in the EOS state. You can check for the EOS state with the -"eos" property or with the `AppSink::is_eos` method. - -The eos signal can also be used to be informed when the EOS state is reached -to avoid polling. - -# Implements - -[`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`trait@gst::URIHandlerExt`] - -Check if `self` supports buffer lists. - -Feature: `v1_12` - - -# Returns - -`true` if `self` supports buffer lists. - -Get the configured caps on `self`. - -# Returns - -the `gst::Caps` accepted by the sink. `gst_caps_unref` after usage. - -Check if `self` will drop old buffers when the maximum amount of queued -buffers is reached. - -# Returns - -`true` if `self` is dropping old buffers when the queue is -filled. - -Check if appsink will emit the "new-preroll" and "new-sample" signals. - -# Returns - -`true` if `self` is emitting the "new-preroll" and "new-sample" -signals. - -Get the maximum amount of buffers that can be queued in `self`. - -# Returns - -The maximum amount of buffers that can be queued. - -Check if `self` will wait for all buffers to be consumed when an EOS is -received. - -# Returns - -`true` if `self` will wait for all buffers to be consumed when an -EOS is received. - -Check if `self` is EOS, which is when no more samples can be pulled because -an EOS event was received. - -This function also returns `true` when the appsink is not in the PAUSED or -PLAYING state. - -# Returns - -`true` if no more samples can be pulled and the appsink is EOS. - -Get the last preroll sample in `self`. This was the sample that caused the -appsink to preroll in the PAUSED state. - -This function is typically used when dealing with a pipeline in the PAUSED -state. Calling this function after doing a seek will give the sample right -after the seek position. - -Calling this function will clear the internal reference to the preroll -buffer. - -Note that the preroll sample will also be returned as the first sample -when calling `AppSink::pull_sample`. - -If an EOS event was received before any buffers, this function returns -`None`. Use gst_app_sink_is_eos () to check for the EOS condition. - -This function blocks until a preroll sample or EOS is received or the appsink -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. - -This function blocks until a sample or EOS becomes available or the appsink -element is set to the READY/NULL state. - -This function will only return samples when the appsink is in the PLAYING -state. All rendered buffers will be put in a queue so that the application -can pull samples at its own rate. Note that when the application does not -pull samples fast enough, the queued buffers could consume a lot of memory, -especially when dealing with raw video frames. - -If an EOS event was received before any buffers, this function returns -`None`. Use gst_app_sink_is_eos () to check for the EOS condition. - -# Returns - -a `gst::Sample` or NULL when the appsink is stopped or EOS. - Call `gst_sample_unref` after usage. - -Instruct `self` to enable or disable buffer list support. - -For backwards-compatibility reasons applications need to opt in -to indicate that they will be able to handle buffer lists. - -Feature: `v1_12` - -## `enable_lists` -enable or disable buffer list support - -Set callbacks which will be executed for each new preroll, new sample and eos. -This is an alternative to using the signals, it has lower overhead and is thus -less expensive, but also less flexible. - -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` -a user_data argument for the callbacks -## `notify` -a destroy notify function - -Set the capabilities on the appsink element. This function takes -a copy of the caps structure. After calling this method, the sink will only -accept caps that match `caps`. If `caps` is non-fixed, or incomplete, -you must check the caps on the samples to get the actual used caps. -## `caps` -caps to set - -Instruct `self` to drop old buffers when the maximum amount of queued -buffers is reached. -## `drop` -the new state - -Make appsink emit the "new-preroll" and "new-sample" signals. This option is -by default disabled because signal emission is expensive and unneeded when -the application prefers to operate in pull mode. -## `emit` -the new state - -Set the maximum amount of buffers that can be queued in `self`. After this -amount of buffers are queued in appsink, any more buffers will block upstream -elements until a sample is pulled from `self`. -## `max` -the maximum number of buffers to queue - -Instruct `self` to wait for all buffers to be consumed when an EOS is received. -## `wait` -the new state - -Get the last preroll sample in `self`. This was the sample that caused the -appsink to preroll in the PAUSED state. - -This function is typically used when dealing with a pipeline in the PAUSED -state. Calling this function after doing a seek will give the sample right -after the seek position. - -Calling this function will clear the internal reference to the preroll -buffer. - -Note that the preroll sample will also be returned as the first sample -when calling `AppSink::pull_sample`. - -If an EOS event was received before any buffers or the timeout expires, -this function returns `None`. Use gst_app_sink_is_eos () to check for the EOS -condition. - -This function blocks until a preroll sample or EOS is received, the appsink -element is set to the READY/NULL state, or the timeout expires. - -Feature: `v1_10` - -## `timeout` -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. - -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. - -This function will only return samples when the appsink is in the PLAYING -state. All rendered buffers will be put in a queue so that the application -can pull samples at its own rate. Note that when the application does not -pull samples fast enough, the queued buffers could consume a lot of memory, -especially when dealing with raw video frames. - -If an EOS event was received before any buffers or the timeout expires, -this function returns `None`. Use gst_app_sink_is_eos () to check for the EOS -condition. - -Feature: `v1_10` - -## `timeout` -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. - -Signal that the end-of-stream has been reached. This signal is emitted from -the streaming thread. - -Signal that a new preroll sample is available. - -This signal is emitted from the streaming thread and only when the -"emit-signals" property is `true`. - -The new preroll sample can be retrieved with the "pull-preroll" action -signal or `AppSink::pull_preroll` either from this signal callback -or from any other thread. - -Note that this signal is only emitted when the "emit-signals" property is -set to `true`, which it is not by default for performance reasons. - -Signal that a new sample is available. - -This signal is emitted from the streaming thread and only when the -"emit-signals" property is `true`. - -The new sample can be retrieved with the "pull-sample" action -signal or `AppSink::pull_sample` either from this signal callback -or from any other thread. - -Note that this signal is only emitted when the "emit-signals" property is -set to `true`, which it is not by default for performance reasons. - -Get the last preroll sample in `appsink`. This was the sample that caused the -appsink to preroll in the PAUSED state. - -This function is typically used when dealing with a pipeline in the PAUSED -state. Calling this function after doing a seek will give the sample right -after the seek position. - -Calling this function will clear the internal reference to the preroll -buffer. - -Note that the preroll sample will also be returned as the first sample -when calling `AppSink::pull_sample` or the "pull-sample" action signal. - -If an EOS event was received before any buffers, this function returns -`None`. Use gst_app_sink_is_eos () to check for the EOS condition. - -This function blocks until a preroll sample or EOS is received or the appsink -element is set to the READY/NULL state. - -# Returns - -a `gst::Sample` or NULL when the appsink is stopped or EOS. - -This function blocks until a sample or EOS becomes available or the appsink -element is set to the READY/NULL state. - -This function will only return samples when the appsink is in the PLAYING -state. All rendered samples will be put in a queue so that the application -can pull samples at its own rate. - -Note that when the application does not pull samples fast enough, the -queued samples could consume a lot of memory, especially when dealing with -raw video frames. It's possible to control the behaviour of the queue with -the "drop" and "max-buffers" properties. - -If an EOS event was received before any buffers, this function returns -`None`. Use gst_app_sink_is_eos () to check for the EOS condition. - -# Returns - -a `gst::Sample` or NULL when the appsink is stopped or EOS. - -Get the last preroll sample in `appsink`. This was the sample that caused the -appsink to preroll in the PAUSED state. - -This function is typically used when dealing with a pipeline in the PAUSED -state. Calling this function after doing a seek will give the sample right -after the seek position. - -Calling this function will clear the internal reference to the preroll -buffer. - -Note that the preroll sample will also be returned as the first sample -when calling `AppSink::pull_sample` or the "pull-sample" action signal. - -If an EOS event was received before any buffers or the timeout expires, -this function returns `None`. Use gst_app_sink_is_eos () to check for the EOS -condition. - -This function blocks until a preroll sample or EOS is received, the appsink -element is set to the READY/NULL state, or the timeout expires. - -Feature: `v1_10` - -## `timeout` -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. - -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. - -This function will only return samples when the appsink is in the PLAYING -state. All rendered samples will be put in a queue so that the application -can pull samples at its own rate. - -Note that when the application does not pull samples fast enough, the -queued samples could consume a lot of memory, especially when dealing with -raw video frames. It's possible to control the behaviour of the queue with -the "drop" and "max-buffers" properties. - -If an EOS event was received before any buffers or the timeout expires, -this function returns `None`. Use gst_app_sink_is_eos () to check -for the EOS condition. - -Feature: `v1_10` - -## `timeout` -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. - -The appsrc element can be used by applications to insert data into a -GStreamer pipeline. Unlike most GStreamer elements, appsrc provides -external API functions. - -appsrc can be used by linking with the libgstapp library to access the -methods directly or by using the appsrc action signals. - -Before operating appsrc, the caps property must be set to fixed caps -describing the format of the data that will be pushed with appsrc. An -exception to this is when pushing buffers with unknown caps, in which case no -caps should be set. This is typically true of file-like sources that push raw -byte buffers. If you don't want to explicitly set the caps, you can use -gst_app_src_push_sample. This method gets the caps associated with the -sample and sets them on the appsrc replacing any previously set caps (if -different from sample's caps). - -The main way of handing data to the appsrc element is by calling the -`AppSrc::push_buffer` method or by emitting the push-buffer action signal. -This will put the buffer onto a queue from which appsrc will read from in its -streaming thread. It is important to note that data transport will not happen -from the thread that performed the push-buffer call. - -The "max-bytes" property controls how much data can be queued in appsrc -before appsrc considers the queue full. A filled internal queue will always -signal the "enough-data" signal, which signals the application that it should -stop pushing data into appsrc. The "block" property will cause appsrc to -block the push-buffer method until free data becomes available again. - -When the internal queue is running out of data, the "need-data" signal is -emitted, which signals the application that it should start pushing more data -into appsrc. - -In addition to the "need-data" and "enough-data" signals, appsrc can emit the -"seek-data" signal when the "stream-mode" property is set to "seekable" or -"random-access". The signal argument will contain the new desired position in -the stream expressed in the unit set with the "format" property. After -receiving the seek-data signal, the application should push-buffers from the -new position. - -These signals allow the application to operate the appsrc in two different -ways: - -The push mode, in which the application repeatedly calls the push-buffer/push-sample -method with a new buffer/sample. Optionally, the queue size in the appsrc -can be controlled with the enough-data and need-data signals by respectively -stopping/starting the push-buffer/push-sample calls. This is a typical -mode of operation for the stream-type "stream" and "seekable". Use this -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 accessible sources. In this mode, a -buffer of exactly the amount of bytes given by the need-data signal should be -pushed into appsrc. - -In all modes, the size property on appsrc should contain the total stream -size in bytes. Setting this property is mandatory in the random-access mode. -For the stream and seekable modes, setting this property is optional but -recommended. - -When the application has finished pushing data into appsrc, it should call -`AppSrc::end_of_stream` or emit the end-of-stream action signal. After -this call, no more buffers can be pushed into appsrc until a flushing seek -occurs or the state of the appsrc has gone through READY. - -# Implements - -[`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`trait@gst::URIHandlerExt`] - -Indicates to the appsrc element that the last buffer queued in the -element is the last buffer of the stream. - -# Returns - -`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. - -Get the number of currently queued bytes inside `self`. - -# Returns - -The number of currently queued bytes. - -Get the duration of the stream in nanoseconds. A value of GST_CLOCK_TIME_NONE means that the duration is -not known. - -Feature: `v1_10` - - -# Returns - -the duration of the stream previously set with `AppSrc::set_duration`; - -Check if appsrc will emit the "new-preroll" and "new-buffer" signals. - -# Returns - -`true` if `self` is emitting the "new-preroll" and "new-buffer" -signals. - -Retrieve the min and max latencies in `min` and `max` respectively. -## `min` -the min latency -## `max` -the max latency - -Get the maximum amount of bytes that can be queued in `self`. - -# Returns - -The maximum amount of bytes that can be queued. - -Get the size of the stream in bytes. A value of -1 means that the size is -not known. - -# Returns - -the size of the stream previously set with `AppSrc::set_size`; - -Get the stream type. Control the stream type of `self` -with `AppSrc::set_stream_type`. - -# Returns - -the stream type. - -Adds a buffer to the queue of buffers that the appsrc element will -push to its source pad. This function takes ownership of the buffer. - -When the block property is TRUE, this function can block until free -space becomes available in the queue. -## `buffer` -a `gst::Buffer` to push - -# Returns - -`gst::FlowReturn::Ok` when the buffer was successfully queued. -`gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING. -`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 -of `buffer_list`. - -When the block property is TRUE, this function can block until free -space becomes available in the queue. - -Feature: `v1_14` - -## `buffer_list` -a `gst::BufferList` to push - -# Returns - -`gst::FlowReturn::Ok` when the buffer list was successfully queued. -`gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING. -`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 -previous caps that were set on appsrc will be replaced by the caps -associated with the sample if not equal. - -This function does not take ownership of the -sample so the sample needs to be unreffed after calling this function. - -When the block property is TRUE, this function can block until free -space becomes available in the queue. -## `sample` -a `gst::Sample` from which buffer and caps may be -extracted - -# Returns - -`gst::FlowReturn::Ok` when the buffer was successfully queued. -`gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING. -`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. -This is an alternative to using the signals, it has lower overhead and is thus -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` -a user_data argument for the callbacks -## `notify` -a destroy notify function - -Set the capabilities on the appsrc element. This function takes -a copy of the caps structure. After calling this method, the source will -only produce caps that match `caps`. `caps` must be fixed and the caps on the -buffers must match the caps or left NULL. -## `caps` -caps to set - -Set the duration of the stream in nanoseconds. A value of GST_CLOCK_TIME_NONE means that the duration is -not known. - -Feature: `v1_10` - -## `duration` -the duration to set - -Make appsrc emit the "new-preroll" and "new-buffer" signals. This option is -by default disabled because signal emission is expensive and unneeded when -the application prefers to operate in pull mode. -## `emit` -the new state - -Configure the `min` and `max` latency in `src`. If `min` is set to -1, the -default latency calculations for pseudo-live sources will be used. -## `min` -the min latency -## `max` -the max latency - -Set the maximum amount of bytes that can be queued in `self`. -After the maximum amount of bytes are queued, `self` will emit the -"enough-data" signal. -## `max` -the maximum number of bytes to queue - -Set the size of the stream in bytes. A value of -1 means that the size is -not known. -## `size` -the size to set - -Set the stream type on `self`. For seekable streams, the "seek" signal must -be connected to. - -A stream_type stream -## `type_` -the new state - -Notify `appsrc` that no more buffer are available. - -Signal that the source has enough data. It is recommended that the -application stops calling push-buffer until the need-data signal is -emitted again to avoid excessive buffer queueing. - -Signal that the source needs more data. In the callback or from another -thread you should call push-buffer or end-of-stream. - -`length` is just a hint and when it is set to -1, any number of bytes can be -pushed into `appsrc`. - -You can call push-buffer multiple times until the enough-data signal is -fired. -## `length` -the amount of bytes needed. - -Adds a buffer to the queue of buffers that the appsrc element will -push to its source pad. This function does not take ownership of the -buffer so the buffer needs to be unreffed after calling this function. - -When the block property is TRUE, this function can block until free space -becomes available in the queue. -## `buffer` -a buffer to push - -Adds a buffer list to the queue of buffers and buffer lists that the -appsrc element will push to its source pad. This function does not take -ownership of the buffer list so the buffer list needs to be unreffed -after calling this function. - -When the block property is TRUE, this function can block until free space -becomes available in the queue. - -Feature: `v1_14` - -## `buffer_list` -a buffer list to push - -Extract a buffer from the provided sample and adds the extracted buffer -to the queue of buffers that the appsrc element will -push to its source pad. This function set the appsrc caps based on the caps -in the sample and reset the caps if they change. -Only the caps and the buffer of the provided sample are used and not -for example the segment in the sample. -This function does not take ownership of the -sample so the sample needs to be unreffed after calling this function. - -When the block property is TRUE, this function can block until free space -becomes available in the queue. -## `sample` -a sample from which extract buffer to push - -Seek to the given offset. The next push-buffer should produce buffers from -the new `offset`. -This callback is only called for seekable stream types. -## `offset` -the offset to seek to - -# Returns - -`true` if the seek succeeded. - -When max-bytes are queued and after the enough-data signal has been emitted, -block any further push-buffer calls until the amount of queued bytes drops -below the max-bytes limit. - -When max-bytes are queued and after the enough-data signal has been emitted, -block any further push-buffer calls until the amount of queued bytes drops -below the max-bytes limit. - -The GstCaps that will negotiated downstream and will be put -on outgoing buffers. - -The GstCaps that will negotiated downstream and will be put -on outgoing buffers. - -The number of currently queued bytes inside appsrc. - -The total duration in nanoseconds of the data stream. If the total duration is known, it -is recommended to configure it with this property. - -Feature: `v1_10` - - -The total duration in nanoseconds of the data stream. If the total duration is known, it -is recommended to configure it with this property. - -Feature: `v1_10` - - -Make appsrc emit the "need-data", "enough-data" and "seek-data" signals. -This option is by default enabled for backwards compatibility reasons but -can disabled when needed because signal emission is expensive. - -Make appsrc emit the "need-data", "enough-data" and "seek-data" signals. -This option is by default enabled for backwards compatibility reasons but -can disabled when needed because signal emission is expensive. - -The format to use for segment events. When the source is producing -timestamped buffers this property should be set to GST_FORMAT_TIME. - -The format to use for segment events. When the source is producing -timestamped buffers this property should be set to GST_FORMAT_TIME. - -When enabled, appsrc will check GstSegment in GstSample which was -pushed via `AppSrc::push_sample` or "push-sample" signal action. -If a GstSegment is changed, corresponding segment event will be followed -by next data flow. - -FIXME: currently only GST_FORMAT_TIME format is supported and therefore -GstAppSrc::format should be time. However, possibly `AppSrc` can support -other formats. - -Feature: `v1_18` - - -When enabled, appsrc will check GstSegment in GstSample which was -pushed via `AppSrc::push_sample` or "push-sample" signal action. -If a GstSegment is changed, corresponding segment event will be followed -by next data flow. - -FIXME: currently only GST_FORMAT_TIME format is supported and therefore -GstAppSrc::format should be time. However, possibly `AppSrc` can support -other formats. - -Feature: `v1_18` - - -Instruct the source to behave like a live source. This includes that it -will only push out buffers in the PLAYING state. - -Instruct the source to behave like a live source. This includes that it -will only push out buffers in the PLAYING state. - -The maximum amount of bytes that can be queued internally. -After the maximum amount of bytes are queued, appsrc will emit the -"enough-data" signal. - -The maximum amount of bytes that can be queued internally. -After the maximum amount of bytes are queued, appsrc will emit the -"enough-data" signal. - -The minimum latency of the source. A value of -1 will use the default -latency calculations of `gst_base::BaseSrc`. - -The minimum latency of the source. A value of -1 will use the default -latency calculations of `gst_base::BaseSrc`. - -Make appsrc emit the "need-data" signal when the amount of bytes in the -queue drops below this percentage of max-bytes. - -Make appsrc emit the "need-data" signal when the amount of bytes in the -queue drops below this percentage of max-bytes. - -The total size in bytes of the data stream. If the total size is known, it -is recommended to configure it with this property. - -The total size in bytes of the data stream. If the total size is known, it -is recommended to configure it with this property. - -The type of stream that this source is producing. For seekable streams the -application should connect to the seek-data signal. - -The type of stream that this source is producing. For seekable streams the -application should connect to the seek-data signal. - -The stream type. - -No seeking is supported in the stream, such as a -live stream. - -The stream is seekable but seeking might not -be very fast, such as data from a webserver. - -The stream is seekable and seeking is fast, -such as in a local file. diff --git a/docs/gstreamer-audio/docs.md b/docs/gstreamer-audio/docs.md deleted file mode 100644 index 4b1256468..000000000 --- a/docs/gstreamer-audio/docs.md +++ /dev/null @@ -1,1539 +0,0 @@ - - -This is the base class for audio sinks. Subclasses need to implement the -::create_ringbuffer vmethod. This base class will then take care of -writing samples to the ringbuffer, synchronisation, clipping and flushing. - -# Implements - -[`AudioBaseSinkExt`](trait@crate::AudioBaseSinkExt), [`trait@gst_base::BaseSinkExt`], [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Trait containing all `AudioBaseSink` methods. - -# Implementors - -[`AudioBaseSink`](struct@crate::AudioBaseSink), [`AudioSink`](struct@crate::AudioSink) - -Create and return the `AudioRingBuffer` for `self`. This function will -call the ::create_ringbuffer vmethod and will set `self` as the parent of -the returned buffer (see `gst::ObjectExt::set_parent`). - -# Returns - -The new ringbuffer of `self`. - -Get the current alignment threshold, in nanoseconds, used by `self`. - -# Returns - -The current alignment threshold used by `self`. - -Get the current discont wait, in nanoseconds, used by `self`. - -# Returns - -The current discont wait used by `self`. - -Get the current drift tolerance, in microseconds, used by `self`. - -# Returns - -The current drift tolerance used by `self`. - -Queries whether `self` will provide a clock or not. See also -gst_audio_base_sink_set_provide_clock. - -# Returns - -`true` if `self` will provide a clock. - -Get the current slave method used by `self`. - -# Returns - -The current slave method used by `self`. - -Informs this base class that the audio output device has failed for -some reason, causing a discontinuity (for example, because the device -recovered from the error, but lost all contents of its ring buffer). -This function is typically called by derived classes, and is useful -for the custom slave method. - -Controls the sink's alignment threshold. -## `alignment_threshold` -the new alignment threshold in nanoseconds - -Sets the custom slaving callback. This callback will -be invoked if the slave-method property is set to -GST_AUDIO_BASE_SINK_SLAVE_CUSTOM and the audio sink -receives and plays samples. - -Setting the callback to NULL causes the sink to -behave as if the GST_AUDIO_BASE_SINK_SLAVE_NONE -method were used. -## `callback` -a `GstAudioBaseSinkCustomSlavingCallback` -## `user_data` -user data passed to the callback -## `notify` -called when user_data becomes unused - -Controls how long the sink will wait before creating a discontinuity. -## `discont_wait` -the new discont wait in nanoseconds - -Controls the sink's drift tolerance. -## `drift_tolerance` -the new drift tolerance in microseconds - -Controls whether `self` will provide a clock or not. If `provide` is `true`, -`gst::ElementExt::provide_clock` will return a clock that reflects the datarate -of `self`. If `provide` is `false`, `gst::ElementExt::provide_clock` will return -NULL. -## `provide` -new state - -Controls how clock slaving will be performed in `self`. -## `method` -the new slave method - -A window of time in nanoseconds to wait before creating a discontinuity as -a result of breaching the drift-tolerance. - -A window of time in nanoseconds to wait before creating a discontinuity as -a result of breaching the drift-tolerance. - -Controls the amount of time in microseconds that clocks are allowed -to drift before resynchronisation happens. - -Controls the amount of time in microseconds that clocks are allowed -to drift before resynchronisation happens. - -This is the base class for audio sources. Subclasses need to implement the -::create_ringbuffer vmethod. This base class will then take care of -reading samples from the ringbuffer, synchronisation and flushing. - -# Implements - -[`AudioBaseSrcExt`](trait@crate::AudioBaseSrcExt), [`trait@gst_base::BaseSrcExt`], [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Trait containing all `AudioBaseSrc` methods. - -# Implementors - -[`AudioBaseSrc`](struct@crate::AudioBaseSrc), [`AudioSrc`](struct@crate::AudioSrc) - -Create and return the `AudioRingBuffer` for `self`. This function will call -the ::create_ringbuffer vmethod and will set `self` as the parent of the -returned buffer (see `gst::ObjectExt::set_parent`). - -# Returns - -The new ringbuffer of `self`. - -Queries whether `self` will provide a clock or not. See also -gst_audio_base_src_set_provide_clock. - -# Returns - -`true` if `self` will provide a clock. - -Get the current slave method used by `self`. - -# Returns - -The current slave method used by `self`. - -Controls whether `self` will provide a clock or not. If `provide` is `true`, -`gst::ElementExt::provide_clock` will return a clock that reflects the datarate -of `self`. If `provide` is `false`, `gst::ElementExt::provide_clock` will return NULL. -## `provide` -new state - -Controls how clock slaving will be performed in `self`. -## `method` -the new slave method - -Actual configured size of audio buffer in microseconds. - -Actual configured audio latency in microseconds. - -Audio channel positions. - -These are the channels defined in SMPTE 2036-2-2008 -Table 1 for 22.2 audio systems with the Surround and Wide channels from -DTS Coherent Acoustics (v.1.3.1) and 10.2 and 7.1 layouts. In the caps the -actual channel layout is expressed with a channel count and a channel mask, -which describes the existing channels. The positions in the bit mask correspond -to the enum values. -For negotiation it is allowed to have more bits set in the channel mask than -the number of channels to specify the allowed channel positions but this is -not allowed in negotiated caps. It is not allowed in any situation other -than the one mentioned below to have less bits set in the channel mask than -the number of channels. - -[`Mono`](Self::Mono) can only be used with a single mono channel that -has no direction information and would be mixed into all directional channels. -This is expressed in caps by having a single channel and no channel mask. - -[`None`](Self::None) can only be used if all channels have this position. -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 implicitly means that this is a stereo stream with a front left and front right -channel. - -used for position-less channels, e.g. - from a sound card that records 1024 channels; mutually exclusive with - any other channel position - -Mono without direction; - can only be used with 1 channel - -invalid position - -Front left - -Front right - -Front center - -Low-frequency effects 1 (subwoofer) - -Rear left - -Rear right - -Front left of center - -Front right of center - -Rear center - -Low-frequency effects 2 (subwoofer) - -Side left - -Side right - -Top front left - -Top front right - -Top front center - -Top center - -Top rear left - -Top rear right - -Top side right - -Top rear right - -Top rear center - -Bottom front center - -Bottom front left - -Bottom front right - -Wide left (between front left and side left) - -Wide right (between front right and side right) - -Surround left (between rear left and side left) - -Surround right (between rear right and side right) - -This base class is for audio decoders turning encoded data into -raw audio samples. - -GstAudioDecoder and subclass should cooperate as follows. - -## Configuration - - * Initially, GstAudioDecoder calls `start` when the decoder element - is activated, which allows subclass to perform any global setup. - Base class (context) parameters can already be set according to subclass - capabilities (or possibly upon receive more information in subsequent - `set_format`). - * GstAudioDecoder calls `set_format` to inform subclass of the format - of input audio data that it is about to receive. - While unlikely, it might be called more than once, if changing input - parameters require reconfiguration. - * GstAudioDecoder calls `stop` at end of all processing. - -As of configuration stage, and throughout processing, GstAudioDecoder -provides various (context) parameters, e.g. describing the format of -output audio data (valid when output caps have been set) or current parsing state. -Conversely, subclass can and should configure context to inform -base class of its expectation w.r.t. buffer handling. - -## Data processing - * Base class gathers input data, and optionally allows subclass - to parse this into subsequently manageable (as defined by subclass) - chunks. Such chunks are subsequently referred to as 'frames', - though they may or may not correspond to 1 (or more) audio format frame. - * Input frame is provided to subclass' `handle_frame`. - * If codec processing results in decoded data, subclass should call - [`finish_frame`](Self::finish_frame) to have decoded data pushed - downstream. - * Just prior to actually pushing a buffer downstream, - it is passed to `pre_push`. Subclass should either use this callback - to arrange for additional downstream pushing or otherwise ensure such - custom pushing occurs after at least a method call has finished since - setting src pad caps. - * During the parsing process GstAudioDecoderClass will handle both - srcpad and sinkpad events. Sink events will be passed to subclass - if `event` callback has been provided. - -## Shutdown phase - - * GstAudioDecoder class calls `stop` to inform the subclass that data - parsing will be stopped. - -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 set the fixed caps on srcpad, when the format is ensured. This -is typically when base class calls subclass' `set_format` function, though -it might be delayed until calling [`finish_frame`](Self::finish_frame). - -In summary, above process should have subclass concentrating on -codec data processing while leaving other matters to base class, -such as most notably timestamp handling. While it may exert more control -in this area (see e.g. `pre_push`), it is very much not recommended. - -In particular, base class will try to arrange for perfect output timestamps -as much as possible while tracking upstream timestamps. -To this end, if deviation between the next ideal expected perfect timestamp -and upstream exceeds `AudioDecoder:tolerance`, then resync to upstream -occurs (which would happen always if the tolerance mechanism is disabled). - -In non-live pipelines, baseclass can also (configurably) arrange for -output buffer aggregation which may help to redue large(r) numbers of -small(er) buffers being pushed and processed downstream. Note that this -feature is only available if the buffer layout is interleaved. For planar -buffers, the decoder implementation is fully responsible for the output -buffer size. - -On the other hand, it should be noted that baseclass only provides limited -seeking support (upon explicit subclass request), as full-fledged support -should rather be left to upstream demuxer, parser or alike. This simple -approach caters for seeking and duration reporting using estimated input -bitrates. - -Things that subclass need to take care of: - - * Provide pad templates - * Set source pad caps when appropriate - * Set user-configurable properties to sane defaults for format and - implementing codec at hand, and convey some subclass capabilities and - expectations in context. - - * Accept data in `handle_frame` and provide encoded results to - [`finish_frame`](Self::finish_frame). If it is prepared to perform - PLC, it should also accept NULL data in `handle_frame` and provide for - data for indicated duration. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`AudioDecoderExt`](trait@crate::AudioDecoderExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`AudioDecoderExtManual`](trait@crate::AudioDecoderExtManual) - -Trait containing all `AudioDecoder` methods. - -# Implementors - -[`AudioDecoder`](struct@crate::AudioDecoder) - -Helper function that allocates a buffer to hold an audio frame -for `self`'s current output format. -## `size` -size of the buffer - -# Returns - -allocated buffer - -Collects decoded data and pushes it downstream. - -`buf` may be NULL in which case the indicated number of frames -are discarded and considered to have produced no output -(e.g. lead-in or setup frames). -Otherwise, source pad caps must be set when it is called with valid -data in `buf`. - -Note that a frame received in `AudioDecoderClass.handle_frame`() may be -invalidated by a call to this function. -## `buf` -decoded data -## `frames` -number of decoded frames represented by decoded data - -# Returns - -a `gst::FlowReturn` that should be escalated to caller (of caller) - -Collects decoded data and pushes it downstream. This function may be called -multiple times for a given input frame. - -`buf` may be NULL in which case it is assumed that the current input frame is -finished. This is equivalent to calling `AudioDecoder::finish_subframe` -with a NULL buffer and frames=1 after having pushed out all decoded audio -subframes using this function. - -When called with valid data in `buf` the source pad caps must have been set -already. - -Note that a frame received in `AudioDecoderClass.handle_frame`() may be -invalidated by a call to this function. - -Feature: `v1_16` - -## `buf` -decoded data - -# Returns - -a `gst::FlowReturn` that should be escalated to caller (of caller) - -Lets `AudioDecoder` sub-classes to know the memory `allocator` -used by the base class and its `params`. - -Unref the `allocator` after use it. -## `allocator` -the `gst::Allocator` -used -## `params` -the -`gst::AllocationParams` of `allocator` - - -# Returns - -a `AudioInfo` describing the input audio format - - -# Returns - -currently configured decoder delay - -Queries decoder drain handling. - -# Returns - -TRUE if drainable handling is enabled. - -MT safe. - - -# Returns - -currently configured byte to time conversion setting - -Sets the variables pointed to by `min` and `max` to the currently configured -latency. -## `min` -a pointer to storage to hold minimum latency -## `max` -a pointer to storage to hold maximum latency - - -# Returns - -currently configured decoder tolerated error count. - -Queries decoder's latency aggregation. - -# Returns - -aggregation latency. - -MT safe. - -Queries decoder required format handling. - -# Returns - -TRUE if required format handling is enabled. - -MT safe. - -Return current parsing (sync and eos) state. -## `sync` -a pointer to a variable to hold the current sync state -## `eos` -a pointer to a variable to hold the current eos state - -Queries decoder packet loss concealment handling. - -# Returns - -TRUE if packet loss concealment is enabled. - -MT safe. - - -# Returns - -currently configured plc handling - -Queries current audio jitter tolerance threshold. - -# Returns - -decoder audio jitter tolerance threshold. - -MT safe. - -Sets the audio decoder tags and how they should be merged with any -upstream stream tags. This will override any tags previously-set -with `AudioDecoderExt::merge_tags`. - -Note that this is provided for convenience, and the subclass is -not required to use this and can still do tag handling on its own. -## `tags` -a `gst::TagList` to merge, or NULL -## `mode` -the `gst::TagMergeMode` to use, usually `gst::TagMergeMode::Replace` - -Negotiate with downstream elements to currently configured `AudioInfo`. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - -# Returns - -`true` if the negotiation succeeded, else `false`. - -Returns caps that express `caps` (or sink template caps if `caps` == NULL) -restricted to rate/channels/... combinations supported by downstream -elements. -## `caps` -initial caps -## `filter` -filter caps - -# Returns - -a `gst::Caps` owned by caller - -Sets a caps in allocation query which are different from the set -pad's caps. Use this function before calling -`AudioDecoder::negotiate`. Setting to `None` the allocation -query will use the caps from the pad. - -Feature: `v1_10` - -## `allocation_caps` -a `gst::Caps` or `None` - -Configures decoder drain handling. If drainable, subclass might -be handed a NULL buffer to have it return any leftover decoded data. -Otherwise, it is not considered so capable and will only ever be passed -real data. - -MT safe. -## `enabled` -new state - -Allows baseclass to perform byte to time estimated conversion. -## `enabled` -whether to enable byte to time conversion - -Sets decoder latency. -## `min` -minimum latency -## `max` -maximum latency - -Sets numbers of tolerated decoder errors, where a tolerated one is then only -warned about, but more than tolerated will lead to fatal error. You can set --1 for never returning fatal errors. Default is set to -GST_AUDIO_DECODER_MAX_ERRORS. -## `num` -max tolerated errors - -Sets decoder minimum aggregation latency. - -MT safe. -## `num` -new minimum latency - -Configures decoder format needs. If enabled, subclass needs to be -negotiated with format caps before it can process any data. It will then -never be handed any data before it has been configured. -Otherwise, it might be handed data without having been configured and -is then expected being able to do so either by default -or based on the input data. - -MT safe. -## `enabled` -new state - -Configure output caps on the srcpad of `self`. Similar to -`AudioDecoder::set_output_format`, but allows subclasses to specify -output caps that can't be expressed via `AudioInfo` e.g. caps that have -caps features. - -Feature: `v1_16` - -## `caps` -(fixed) `gst::Caps` - -# Returns - -`true` on success. - -Configure output info on the srcpad of `self`. -## `info` -`AudioInfo` - -# Returns - -`true` on success. - -Enable or disable decoder packet loss concealment, provided subclass -and codec are capable and allow handling plc. - -MT safe. -## `enabled` -new state - -Indicates whether or not subclass handles packet loss concealment (plc). -## `plc` -new plc state - -Configures decoder audio jitter tolerance threshold. - -MT safe. -## `tolerance` -new tolerance - -Lets `AudioDecoder` sub-classes decide if they want the sink pad -to use the default pad query handler to reply to accept-caps queries. - -By setting this to true it is possible to further customize the default -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 - -Maximum number of tolerated consecutive decode errors. See -`AudioDecoderExt::set_max_errors` for more details. - -Feature: `v1_18` - - -Maximum number of tolerated consecutive decode errors. See -`AudioDecoderExt::set_max_errors` for more details. - -Feature: `v1_18` - - -Set of available dithering methods. - -No dithering - -Rectangular dithering - -Triangular dithering (default) - -High frequency triangular dithering - -This base class is for audio encoders turning raw audio samples into -encoded audio data. - -GstAudioEncoder and subclass should cooperate as follows. - -## Configuration - - * Initially, GstAudioEncoder calls `start` when the encoder element - is activated, which allows subclass to perform any global setup. - - * GstAudioEncoder calls `set_format` to inform subclass of the format - of input audio data that it is about to receive. Subclass should - setup for encoding and configure various base class parameters - appropriately, notably those directing desired input data handling. - While unlikely, it might be called more than once, if changing input - parameters require reconfiguration. - - * GstAudioEncoder calls `stop` at end of all processing. - -As of configuration stage, and throughout processing, GstAudioEncoder -maintains various parameters that provide required context, -e.g. describing the format of input audio data. -Conversely, subclass can and should configure these context parameters -to inform base class of its expectation w.r.t. buffer handling. - -## Data processing - - * Base class gathers input sample data (as directed by the context's - frame_samples and frame_max) and provides this to subclass' `handle_frame`. - * If codec processing results in encoded data, subclass should call - `AudioEncoder::finish_frame` to have encoded data pushed - downstream. Alternatively, it might also call - `AudioEncoder::finish_frame` (with a NULL buffer and some number of - dropped samples) to indicate dropped (non-encoded) samples. - * Just prior to actually pushing a buffer downstream, - it is passed to `pre_push`. - * During the parsing process GstAudioEncoderClass will handle both - srcpad and sinkpad events. Sink events will be passed to subclass - if `event` callback has been provided. - -## Shutdown phase - - * GstAudioEncoder class calls `stop` to inform the subclass that data - parsing will be stopped. - -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 set the fixed caps on srcpad, when the format is ensured. This -is typically when base class calls subclass' `set_format` function, though -it might be delayed until calling [`finish_frame`](Self::finish_frame). - -In summary, above process should have subclass concentrating on -codec data processing while leaving other matters to base class, -such as most notably timestamp handling. While it may exert more control -in this area (see e.g. `pre_push`), it is very much not recommended. - -In particular, base class will either favor tracking upstream timestamps -(at the possible expense of jitter) or aim to arrange for a perfect stream of -output timestamps, depending on `AudioEncoder:perfect-timestamp`. -However, in the latter case, the input may not be so perfect or ideal, which -is handled as follows. An input timestamp is compared with the expected -timestamp as dictated by input sample stream and if the deviation is less -than `AudioEncoder:tolerance`, the deviation is discarded. -Otherwise, it is considered a discontuinity and subsequent output timestamp -is resynced to the new position after performing configured discontinuity -processing. In the non-perfect-timestamp case, an upstream variation -exceeding tolerance only leads to marking DISCONT on subsequent outgoing -(while timestamps are adjusted to upstream regardless of variation). -While DISCONT is also marked in the perfect-timestamp case, this one -optionally (see `AudioEncoder:hard-resync`) -performs some additional steps, such as clipping of (early) input samples -or draining all currently remaining input data, depending on the direction -of the discontuinity. - -If perfect timestamps are arranged, it is also possible to request baseclass -(usually set by subclass) to provide additional buffer metadata (in OFFSET -and OFFSET_END) fields according to granule defined semantics currently -needed by oggmux. Specifically, OFFSET is set to granulepos (= sample count -including buffer) and OFFSET_END to corresponding timestamp (as determined -by same sample count and sample rate). - -Things that subclass need to take care of: - - * Provide pad templates - * Set source pad caps when appropriate - * Inform base class of buffer processing needs using context's - frame_samples and frame_bytes. - * Set user-configurable properties to sane defaults for format and - implementing codec at hand, e.g. those controlling timestamp behaviour - and discontinuity processing. - * Accept data in `handle_frame` and provide encoded results to - `AudioEncoder::finish_frame`. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`AudioEncoderExt`](trait@crate::AudioEncoderExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`AudioEncoderExtManual`](trait@crate::AudioEncoderExtManual) - -Trait containing all `AudioEncoder` methods. - -# Implementors - -[`AudioEncoder`](struct@crate::AudioEncoder) - -Helper function that allocates a buffer to hold an encoded audio frame -for `self`'s current output format. -## `size` -size of the buffer - -# Returns - -allocated buffer - -Collects encoded data and pushes encoded data downstream. -Source pad caps must be set when this is called. - -If `samples` < 0, then best estimate is all samples provided to encoder -(subclass) so far. `buf` may be NULL, in which case next number of `samples` -are considered discarded, e.g. as a result of discontinuous transmission, -and a discontinuity is marked. - -Note that samples received in `AudioEncoderClass.handle_frame`() -may be invalidated by a call to this function. -## `buffer` -encoded data -## `samples` -number of samples (per channel) represented by encoded data - -# Returns - -a `gst::FlowReturn` that should be escalated to caller (of caller) - -Lets `AudioEncoder` sub-classes to know the memory `allocator` -used by the base class and its `params`. - -Unref the `allocator` after use it. -## `allocator` -the `gst::Allocator` -used -## `params` -the -`gst::AllocationParams` of `allocator` - - -# Returns - -a `AudioInfo` describing the input audio format - -Queries encoder drain handling. - -# Returns - -TRUE if drainable handling is enabled. - -MT safe. - - -# Returns - -currently configured maximum handled frames - - -# Returns - -currently maximum requested samples per frame - - -# Returns - -currently minimum requested samples per frame - -Queries encoder hard minimum handling. - -# Returns - -TRUE if hard minimum handling is enabled. - -MT safe. - -Sets the variables pointed to by `min` and `max` to the currently configured -latency. -## `min` -a pointer to storage to hold minimum latency -## `max` -a pointer to storage to hold maximum latency - - -# Returns - -currently configured encoder lookahead - -Queries if the encoder will handle granule marking. - -# Returns - -TRUE if granule marking is enabled. - -MT safe. - -Queries encoder perfect timestamp behaviour. - -# Returns - -TRUE if perfect timestamp setting enabled. - -MT safe. - -Queries current audio jitter tolerance threshold. - -# Returns - -encoder audio jitter tolerance threshold. - -MT safe. - -Sets the audio encoder tags and how they should be merged with any -upstream stream tags. This will override any tags previously-set -with `AudioEncoderExt::merge_tags`. - -Note that this is provided for convenience, and the subclass is -not required to use this and can still do tag handling on its own. - -MT safe. -## `tags` -a `gst::TagList` to merge, or NULL to unset - previously-set tags -## `mode` -the `gst::TagMergeMode` to use, usually `gst::TagMergeMode::Replace` - -Negotiate with downstream elements to currently configured `gst::Caps`. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - -# Returns - -`true` if the negotiation succeeded, else `false`. - -Returns caps that express `caps` (or sink template caps if `caps` == NULL) -restricted to channel/rate combinations supported by downstream elements -(e.g. muxers). -## `caps` -initial caps -## `filter` -filter caps - -# Returns - -a `gst::Caps` owned by caller - -Sets a caps in allocation query which are different from the set -pad's caps. Use this function before calling -`AudioEncoder::negotiate`. Setting to `None` the allocation -query will use the caps from the pad. - -Feature: `v1_10` - -## `allocation_caps` -a `gst::Caps` or `None` - -Configures encoder drain handling. If drainable, subclass might -be handed a NULL buffer to have it return any leftover encoded data. -Otherwise, it is not considered so capable and will only ever be passed -real data. - -MT safe. -## `enabled` -new state - -Sets max number of frames accepted at once (assumed minimally 1). -Requires `frame_samples_min` and `frame_samples_max` to be the equal. - -Note: This value will be reset to 0 every time before -`AudioEncoderClass.set_format`() is called. -## `num` -number of frames - -Sets number of samples (per channel) subclass needs to be handed, -at most or will be handed all available if 0. - -If an exact number of samples is required, `AudioEncoderExt::set_frame_samples_min` -must be called with the same number. - -Note: This value will be reset to 0 every time before -`AudioEncoderClass.set_format`() is called. -## `num` -number of samples per frame - -Sets number of samples (per channel) subclass needs to be handed, -at least or will be handed all available if 0. - -If an exact number of samples is required, `AudioEncoderExt::set_frame_samples_max` -must be called with the same number. - -Note: This value will be reset to 0 every time before -`AudioEncoderClass.set_format`() is called. -## `num` -number of samples per frame - -Configures encoder hard minimum handling. If enabled, subclass -will never be handed less samples than it configured, which otherwise -might occur near end-of-data handling. Instead, the leftover samples -will simply be discarded. - -MT safe. -## `enabled` -new state - -Set the codec headers to be sent downstream whenever requested. -## `headers` -a list of - `gst::Buffer` containing the codec header - -Sets encoder latency. -## `min` -minimum latency -## `max` -maximum latency - -Sets encoder lookahead (in units of input rate samples) - -Note: This value will be reset to 0 every time before -`AudioEncoderClass.set_format`() is called. -## `num` -lookahead - -Enable or disable encoder granule handling. - -MT safe. -## `enabled` -new state - -Configure output caps on the srcpad of `self`. -## `caps` -`gst::Caps` - -# Returns - -`true` on success. - -Enable or disable encoder perfect output timestamp preference. - -MT safe. -## `enabled` -new state - -Configures encoder audio jitter tolerance threshold. - -MT safe. -## `tolerance` -new tolerance - -Extra audio flags - -no valid flag - -the position array explicitly - contains unpositioned channels. - -Enum value describing the most common audio formats. - -unknown or unset audio format - -encoded audio format - -8 bits in 8 bits, signed - -8 bits in 8 bits, unsigned - -16 bits in 16 bits, signed, little endian - -16 bits in 16 bits, signed, big endian - -16 bits in 16 bits, unsigned, little endian - -16 bits in 16 bits, unsigned, big endian - -24 bits in 32 bits, signed, little endian - -24 bits in 32 bits, signed, big endian - -24 bits in 32 bits, unsigned, little endian - -24 bits in 32 bits, unsigned, big endian - -32 bits in 32 bits, signed, little endian - -32 bits in 32 bits, signed, big endian - -32 bits in 32 bits, unsigned, little endian - -32 bits in 32 bits, unsigned, big endian - -24 bits in 24 bits, signed, little endian - -24 bits in 24 bits, signed, big endian - -24 bits in 24 bits, unsigned, little endian - -24 bits in 24 bits, unsigned, big endian - -20 bits in 24 bits, signed, little endian - -20 bits in 24 bits, signed, big endian - -20 bits in 24 bits, unsigned, little endian - -20 bits in 24 bits, unsigned, big endian - -18 bits in 24 bits, signed, little endian - -18 bits in 24 bits, signed, big endian - -18 bits in 24 bits, unsigned, little endian - -18 bits in 24 bits, unsigned, big endian - -32-bit floating point samples, little endian - -32-bit floating point samples, big endian - -64-bit floating point samples, little endian - -64-bit floating point samples, big endian - -16 bits in 16 bits, signed, native endianness - -16 bits in 16 bits, unsigned, native endianness - -24 bits in 32 bits, signed, native endianness - -24 bits in 32 bits, unsigned, native endianness - -32 bits in 32 bits, signed, native endianness - -32 bits in 32 bits, unsigned, native endianness - -24 bits in 24 bits, signed, native endianness - -24 bits in 24 bits, unsigned, native endianness - -20 bits in 24 bits, signed, native endianness - -20 bits in 24 bits, unsigned, native endianness - -18 bits in 24 bits, signed, native endianness - -18 bits in 24 bits, unsigned, native endianness - -32-bit floating point samples, native endianness - -64-bit floating point samples, native endianness - -The different audio flags that a format info can have. - -integer samples - -float samples - -signed samples - -complex layout - -the format can be used in -`GstAudioFormatUnpack` and `GstAudioFormatPack` functions - -Information for an audio format. - -Information describing audio properties. This information can be filled -in from GstCaps with `AudioInfo::from_caps`. - -Use the provided macros to access the info in this structure. - -Allocate a new `AudioInfo` that is also initialized with -`AudioInfo::init`. - -# Returns - -a new `AudioInfo`. free with `AudioInfo::free`. - -Converts among various `gst::Format` types. This function handles -GST_FORMAT_BYTES, GST_FORMAT_TIME, and GST_FORMAT_DEFAULT. For -raw audio, GST_FORMAT_DEFAULT corresponds to audio frames. This -function can be used to handle pad queries of the type GST_QUERY_CONVERT. -## `src_fmt` -`gst::Format` of the `src_val` -## `src_val` -value to convert -## `dest_fmt` -`gst::Format` of the `dest_val` -## `dest_val` -pointer to destination value - -# Returns - -TRUE if the conversion was successful. - -Copy a GstAudioInfo structure. - -# Returns - -a new `AudioInfo`. free with gst_audio_info_free. - -Free a GstAudioInfo structure previously allocated with `AudioInfo::new` -or `AudioInfo::copy`. - -Parse `caps` and update `self`. -## `caps` -a `gst::Caps` - -# Returns - -TRUE if `caps` could be parsed - -Initialize `self` with default values. - -Compares two `AudioInfo` and returns whether they are equal or not -## `other` -a `AudioInfo` - -# Returns - -`true` if `self` and `other` are equal, else `false`. - -Set the default info for the audio info of `format` and `rate` and `channels`. - -Note: This initializes `self` first, no values are preserved. -## `format` -the format -## `rate` -the samplerate -## `channels` -the number of channels -## `position` -the channel positions - -Convert the values of `self` into a `gst::Caps`. - -# Returns - -the new `gst::Caps` containing the - info of `self`. - -Layout of the audio samples for the different channels. - -interleaved audio - -non-interleaved audio - -Set of available noise shaping methods - -No noise shaping (default) - -Error feedback - -Simple 2-pole noise shaping - -Medium 5-pole noise shaping - -High 8-pole noise shaping - -The different flags that can be used when packing and unpacking. - -No flag - -When the source has a smaller depth - than the target format, set the least significant bits of the target - to 0. This is likely slightly faster but less accurate. When this flag - is not specified, the most significant bits of the source are duplicated - in the least significant bits of the destination. - -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 Blackman-Nuttall windowed sinc interpolation - -Uses Kaiser windowed sinc interpolation - -Feature: `v1_10` - - -The format of the samples in the ringbuffer. - -samples in linear or float - -samples in mulaw - -samples in alaw - -samples in ima adpcm - -samples in mpeg audio (but not AAC) format - -samples in gsm format - -samples in IEC958 frames (e.g. AC3) - -samples in AC3 format - -samples in EAC3 format - -samples in DTS format - -samples in MPEG-2 AAC ADTS format - -samples in MPEG-4 AAC ADTS format - -samples in MPEG-2 AAC raw format (Since: 1.12) - -samples in MPEG-4 AAC raw format (Since: 1.12) - -samples in FLAC format (Since: 1.12) - -This is the most simple base class for audio sinks that only requires -subclasses to implement a set of simple functions: - -* `open()` :Open the device. - -* `prepare()` :Configure the device with the specified format. - -* `write()` :Write samples to the device. - -* `reset()` :Unblock writes and flush the device. - -* `delay()` :Get the number of samples written but not yet played -by the device. - -* `unprepare()` :Undo operations done by prepare. - -* `close()` :Close the device. - -All scheduling of samples and timestamps is done in this base class -together with `AudioBaseSink` using a default implementation of a -`AudioRingBuffer` that uses threads. - -# Implements - -[`AudioBaseSinkExt`](trait@crate::AudioBaseSinkExt), [`trait@gst_base::BaseSinkExt`], [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -This is the most simple base class for audio sources that only requires -subclasses to implement a set of simple functions: - -* `open()` :Open the device. -* `prepare()` :Configure the device with the specified format. -* `read()` :Read samples from the device. -* `reset()` :Unblock reads and flush the device. -* `delay()` :Get the number of samples in the device but not yet read. -* `unprepare()` :Undo operations done by prepare. -* `close()` :Close the device. - -All scheduling of samples and timestamps is done in this base class -together with `AudioBaseSrc` using a default implementation of a -`AudioRingBuffer` that uses threads. - -# Implements - -[`AudioBaseSrcExt`](trait@crate::AudioBaseSrcExt), [`trait@gst_base::BaseSrcExt`], [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -`AudioStreamAlign` provides a helper object that helps tracking audio -stream alignment and discontinuities, and detects discontinuities if -possible. - -See `AudioStreamAlign::new` for a description of its parameters and -`AudioStreamAlign::process` for the details of the processing. - -Feature: `v1_14` - -Allocate a new `AudioStreamAlign` with the given configuration. All -processing happens according to sample rate `rate`, until -`AudioStreamAlign::set_rate` is called with a new `rate`. -A negative rate can be used for reverse playback. - -`alignment_threshold` gives the tolerance in nanoseconds after which a -timestamp difference is considered a discontinuity. Once detected, -`discont_wait` nanoseconds have to pass without going below the threshold -again until the output buffer is marked as a discontinuity. These can later -be re-configured with `AudioStreamAlign::set_alignment_threshold` and -`AudioStreamAlign::set_discont_wait`. - -Feature: `v1_14` - -## `rate` -a sample rate -## `alignment_threshold` -a alignment threshold in nanoseconds -## `discont_wait` -discont wait in nanoseconds - -# Returns - -a new `AudioStreamAlign`. free with `AudioStreamAlign::free`. - -Copy a GstAudioStreamAlign structure. - -Feature: `v1_14` - - -# Returns - -a new `AudioStreamAlign`. free with gst_audio_stream_align_free. - -Free a GstAudioStreamAlign structure previously allocated with `AudioStreamAlign::new` -or `AudioStreamAlign::copy`. - -Feature: `v1_14` - - -Gets the currently configured alignment threshold. - -Feature: `v1_14` - - -# Returns - -The currently configured alignment threshold - -Gets the currently configured discont wait. - -Feature: `v1_14` - - -# Returns - -The currently configured discont wait - -Gets the currently configured sample rate. - -Feature: `v1_14` - - -# Returns - -The currently configured sample rate - -Returns the number of samples that were processed since the last -discontinuity was detected. - -Feature: `v1_14` - - -# Returns - -The number of samples processed since the last discontinuity. - -Timestamp that was passed when a discontinuity was detected, i.e. the first -timestamp after the discontinuity. - -Feature: `v1_14` - - -# Returns - -The last timestamp at when a discontinuity was detected - -Marks the next buffer as discontinuous and resets timestamp tracking. - -Feature: `v1_14` - - -Processes data with `timestamp` and `n_samples`, and returns the output -timestamp, duration and sample position together with a boolean to signal -whether a discontinuity was detected or not. All non-discontinuous data -will have perfect timestamps and durations. - -A discontinuity is detected once the difference between the actual -timestamp and the timestamp calculated from the sample count since the last -discontinuity differs by more than the alignment threshold for a duration -longer than discont wait. - -Note: In reverse playback, every buffer is considered discontinuous in the -context of buffer flags because the last sample of the previous buffer is -discontinuous with the first sample of the current one. However for this -function they are only considered discontinuous in reverse playback if the -first sample of the previous buffer is discontinuous with the last sample -of the current one. - -Feature: `v1_14` - -## `discont` -if this data is considered to be discontinuous -## `timestamp` -a `gst::ClockTime` of the start of the data -## `n_samples` -number of samples to process -## `out_timestamp` -output timestamp of the data -## `out_duration` -output duration of the data -## `out_sample_position` -output sample position of the start of the data - -# Returns - -`true` if a discontinuity was detected, `false` otherwise. - -Sets `alignment_treshold` as new alignment threshold for the following processing. - -Feature: `v1_14` - -## `alignment_threshold` -a new alignment threshold - -Sets `alignment_treshold` as new discont wait for the following processing. - -Feature: `v1_14` - -## `discont_wait` -a new discont wait - -Sets `rate` as new sample rate for the following processing. If the sample -rate differs this implicitly marks the next data as discontinuous. - -Feature: `v1_14` - -## `rate` -a new sample rate - -This interface is implemented by elements that provide a stream volume. Examples for -such elements are `volume` and `playbin`. - -Applications can use this interface to get or set the current stream volume. For this -the "volume" `glib::object::Object` property can be used or the helper functions `StreamVolume::set_volume` -and `StreamVolume::get_volume`. This volume is always a linear factor, i.e. 0.0 is muted -1.0 is 100%. For showing the volume in a GUI it might make sense to convert it to -a different format by using `StreamVolume::convert_volume`. Volume sliders should usually -use a cubic volume. - -Separate from the volume the stream can also be muted by the "mute" `glib::object::Object` property or -`StreamVolume::set_mute` and `StreamVolume::get_mute`. - -Elements that provide some kind of stream volume should implement the "volume" and -"mute" `glib::object::Object` properties and handle setting and getting of them properly. -The volume property is defined to be a linear volume factor. - -# Implements - -[`StreamVolumeExt`](trait@crate::StreamVolumeExt) - -Trait containing all `StreamVolume` methods. - -# Implementors - -[`StreamVolume`](struct@crate::StreamVolume) - -## `from` -`StreamVolumeFormat` to convert from -## `to` -`StreamVolumeFormat` to convert to -## `val` -Volume in `from` format that should be converted - -# Returns - -the converted volume - - -# Returns - -Returns `true` if the stream is muted - -## `format` -`StreamVolumeFormat` which should be returned - -# Returns - -The current stream volume as linear factor - -## `mute` -Mute state that should be set - -## `format` -`StreamVolumeFormat` of `val` -## `val` -Linear volume factor that should be set - -Different representations of a stream volume. `StreamVolume::convert_volume` -allows to convert between the different representations. - -Formulas to convert from a linear to a cubic or dB volume are -cbrt(val) and 20 * log10 (val). - -Linear scale factor, 1.0 = 100% - -Cubic volume scale - -Logarithmic volume scale (dB, amplitude not power) diff --git a/docs/gstreamer-base/docs.md b/docs/gstreamer-base/docs.md deleted file mode 100644 index a03489254..000000000 --- a/docs/gstreamer-base/docs.md +++ /dev/null @@ -1,2585 +0,0 @@ - - -This class is for elements that receive buffers in an undesired size. -While for example raw video contains one image per buffer, the same is not -true for a lot of other formats, especially those that come directly from -a file. So if you have undefined buffer sizes and require a specific size, -this object is for you. - -An adapter is created with `Adapter::new`. It can be freed again with -`glib::object::ObjectExt::unref`. - -The theory of operation is like this: All buffers received are put -into the adapter using `Adapter::push` and the data is then read back -in chunks of the desired size using `Adapter::map`/`Adapter::unmap` -and/or `Adapter::copy`. After the data has been processed, it is freed -using `Adapter::unmap`. - -Other methods such as `Adapter::take` and `Adapter::take_buffer` -combine `Adapter::map` and `Adapter::unmap` in one method and are -potentially more convenient for some use cases. - -For example, a sink pad's chain function that needs to pass data to a library -in 512-byte chunks could be implemented like this: - -```C -static GstFlowReturn -sink_pad_chain (GstPad *pad, GstObject *parent, GstBuffer *buffer) -{ - MyElement *this; - GstAdapter *adapter; - GstFlowReturn ret = GST_FLOW_OK; - - this = MY_ELEMENT (parent); - - adapter = this->adapter; - - // put buffer into adapter - gst_adapter_push (adapter, buffer); - - // while we can read out 512 bytes, process them - while (gst_adapter_available (adapter) >= 512 && ret == GST_FLOW_OK) { - const guint8 *data = gst_adapter_map (adapter, 512); - // use flowreturn as an error value - ret = my_library_foo (data); - gst_adapter_unmap (adapter); - gst_adapter_flush (adapter, 512); - } - return ret; -} -``` - -For another example, a simple element inside GStreamer that uses `Adapter` -is the libvisual element. - -An element using `Adapter` in its sink pad chain function should ensure that -when the FLUSH_STOP event is received, that any queued data is cleared using -`Adapter::clear`. Data should also be cleared or processed on EOS and -when changing state from `gst::State::Paused` to `gst::State::Ready`. - -Also check the GST_BUFFER_FLAG_DISCONT flag on the buffer. Some elements might -need to clear the adapter after a discontinuity. - -The adapter will keep track of the timestamps of the buffers -that were pushed. The last seen timestamp before the current position -can be queried with `Adapter::prev_pts`. This function can -optionally return the number of bytes between the start of the buffer that -carried the timestamp and the current adapter position. The distance is -useful when dealing with, for example, raw audio samples because it allows -you to calculate the timestamp of the current adapter position by using the -last seen timestamp and the amount of bytes since. Additionally, the -`Adapter::prev_pts_at_offset` can be used to determine the last -seen timestamp at a particular offset in the adapter. - -The adapter will also keep track of the offset of the buffers -(`GST_BUFFER_OFFSET`) that were pushed. The last seen offset before the -current position can be queried with `Adapter::prev_offset`. This function -can optionally return the number of bytes between the start of the buffer -that carried the offset and the current adapter position. - -Additionally the adapter also keeps track of the PTS, DTS and buffer offset -at the last discontinuity, which can be retrieved with -`Adapter::pts_at_discont`, `Adapter::dts_at_discont` and -`Adapter::offset_at_discont`. The number of bytes that were consumed -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 -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) -user provided buffer. - -`Adapter` is not MT safe. All operations on an adapter must be serialized by -the caller. This is not normally a problem, however, as the normal use case -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 -access the buffer later. The adapter will never modify the data in the -buffer pushed in it. - -# Implements - -[`trait@glib::object::ObjectExt`] - -Creates a new `Adapter`. Free with `glib::object::ObjectExt::unref`. - -# Returns - -a new `Adapter` - -Gets the maximum amount of bytes available, that is it returns the maximum -value that can be supplied to `Adapter::map` without that function -returning `None`. - -# Returns - -number of bytes available in `self` - -Gets the maximum number of bytes that are immediately available without -requiring any expensive operations (like copying the data into a -temporary buffer). - -# Returns - -number of bytes that are available in `self` without expensive -operations - -Removes all buffers from `self`. - -Copies `size` bytes of data starting at `offset` out of the buffers -contained in `Adapter` into an array `dest` provided by the caller. - -The array `dest` should be large enough to contain `size` bytes. -The user should check that the adapter has (`offset` + `size`) bytes -available before calling this function. -## `dest` - - the memory to copy into -## `offset` -the bytes offset in the adapter to start from -## `size` -the number of bytes to copy - -Similar to gst_adapter_copy, but more suitable for language bindings. `size` -bytes of data starting at `offset` will be copied out of the buffers contained -in `self` and into a new `glib::Bytes` structure which is returned. Depending on -the value of the `size` argument an empty `glib::Bytes` structure may be returned. -## `offset` -the bytes offset in the adapter to start from -## `size` -the number of bytes to copy - -# Returns - -A new `glib::Bytes` structure containing the copied data. - -Get the distance in bytes since the last buffer with the -`gst::BufferFlags::Discont` flag. - -The distance will be reset to 0 for all buffers with -`gst::BufferFlags::Discont` on them, and then calculated for all other -following buffers based on their size. - -Feature: `v1_10` - - -# Returns - -The offset. Can be `GST_BUFFER_OFFSET_NONE`. - -Get the DTS that was on the last buffer with the GST_BUFFER_FLAG_DISCONT -flag, or GST_CLOCK_TIME_NONE. - -Feature: `v1_10` - - -# Returns - -The DTS at the last discont or GST_CLOCK_TIME_NONE. - -Flushes the first `flush` bytes in the `self`. The caller must ensure that -at least this many bytes are available. - -See also: `Adapter::map`, `Adapter::unmap` -## `flush` -the number of bytes to flush - -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 -usage. - -Free-function: gst_buffer_unref -## `nbytes` -the number of bytes to get - -# Returns - -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. - -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 -usage. - -Free-function: gst_buffer_unref -## `nbytes` -the number of bytes to get - -# Returns - -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. - -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 -the list after usage. -## `nbytes` -the number of bytes to get - -# Returns - -a `gst::BufferList` of buffers containing - the first `nbytes` of the adapter, or `None` if `nbytes` bytes are not - available - -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 -buffer in the list before freeing the list after usage. -## `nbytes` -the number of bytes to get - -# Returns - -a `glib::List` of - buffers containing the first `nbytes` of the adapter, or `None` if `nbytes` - bytes are not available - -Gets the first `size` bytes stored in the `self`. The returned pointer is -valid until the next function is called on the adapter. - -Note that setting the returned pointer as the data of a `gst::Buffer` is -incorrect for general-purpose plugins. The reason is that if a downstream -element stores the buffer so that it has access to it outside of the bounds -of its chain function, the buffer will have an invalid data pointer after -your element flushes the bytes. In that case you should use -`Adapter::take`, which returns a freshly-allocated buffer that you can set -as `gst::Buffer` memory or the potentially more performant -`Adapter::take_buffer`. - -Returns `None` if `size` bytes are not available. -## `size` -the number of bytes to map/peek - -# Returns - - - a pointer to the first `size` bytes of data, or `None` - -Scan for pattern `pattern` with applied mask `mask` in the adapter data, -starting from offset `offset`. - -The bytes in `pattern` and `mask` are interpreted left-to-right, regardless -of endianness. All four bytes of the pattern must be present in the -adapter for it to match, even if the first or last bytes are masked out. - -It is an error to call this function without making sure that there is -enough data (offset+size bytes) in the adapter. - -This function calls `Adapter::masked_scan_uint32_peek` passing `None` -for value. -## `mask` -mask to apply to data before matching against `pattern` -## `pattern` -pattern to match (after mask is applied) -## `offset` -offset into the adapter data from which to start scanning, returns - the last scanned position. -## `size` -number of bytes to scan from offset - -# Returns - -offset of the first match, or -1 if no match was found. - -Example: - -```text -// Assume the adapter contains 0x00 0x01 0x02 ... 0xfe 0xff - -gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 0, 256); -// -> returns 0 -gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 1, 255); -// -> returns -1 -gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x01020304, 1, 255); -// -> returns 1 -gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0001, 0, 256); -// -> returns -1 -gst_adapter_masked_scan_uint32 (adapter, 0xffff, 0x0203, 0, 256); -// -> returns 0 -gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 256); -// -> returns 2 -gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 4); -// -> returns -1 -``` - -Scan for pattern `pattern` with applied mask `mask` in the adapter data, -starting from offset `offset`. If a match is found, the value that matched -is returned through `value`, otherwise `value` is left untouched. - -The bytes in `pattern` and `mask` are interpreted left-to-right, regardless -of endianness. All four bytes of the pattern must be present in the -adapter for it to match, even if the first or last bytes are masked out. - -It is an error to call this function without making sure that there is -enough data (offset+size bytes) in the adapter. -## `mask` -mask to apply to data before matching against `pattern` -## `pattern` -pattern to match (after mask is applied) -## `offset` -offset into the adapter data from which to start scanning, returns - the last scanned position. -## `size` -number of bytes to scan from offset -## `value` -pointer to uint32 to return matching data - -# Returns - -offset of the first match, or -1 if no match was found. - -Get the offset that was on the last buffer with the GST_BUFFER_FLAG_DISCONT -flag, or GST_BUFFER_OFFSET_NONE. - -Feature: `v1_10` - - -# Returns - -The offset at the last discont or GST_BUFFER_OFFSET_NONE. - -Get the dts that was before the current byte in the adapter. When -`distance` is given, the amount of bytes between the dts and the current -position is returned. - -The dts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when -the adapter is first created or when it is cleared. This also means that before -the first byte with a dts is removed from the adapter, the dts -and distance returned are GST_CLOCK_TIME_NONE and 0 respectively. -## `distance` -pointer to location for distance, or `None` - -# Returns - -The previously seen dts. - -Get the dts that was before the byte at offset `offset` in the adapter. When -`distance` is given, the amount of bytes between the dts and the current -position is returned. - -The dts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when -the adapter is first created or when it is cleared. This also means that before -the first byte with a dts is removed from the adapter, the dts -and distance returned are GST_CLOCK_TIME_NONE and 0 respectively. -## `offset` -the offset in the adapter at which to get timestamp -## `distance` -pointer to location for distance, or `None` - -# Returns - -The previously seen dts at given offset. - -Get the offset that was before the current byte in the adapter. When -`distance` is given, the amount of bytes between the offset and the current -position is returned. - -The offset is reset to GST_BUFFER_OFFSET_NONE and the distance is set to 0 -when the adapter is first created or when it is cleared. This also means that -before the first byte with an offset is removed from the adapter, the offset -and distance returned are GST_BUFFER_OFFSET_NONE and 0 respectively. - -Feature: `v1_10` - -## `distance` -pointer to a location for distance, or `None` - -# Returns - -The previous seen offset. - -Get the pts that was before the current byte in the adapter. When -`distance` is given, the amount of bytes between the pts and the current -position is returned. - -The pts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when -the adapter is first created or when it is cleared. This also means that before -the first byte with a pts is removed from the adapter, the pts -and distance returned are GST_CLOCK_TIME_NONE and 0 respectively. -## `distance` -pointer to location for distance, or `None` - -# Returns - -The previously seen pts. - -Get the pts that was before the byte at offset `offset` in the adapter. When -`distance` is given, the amount of bytes between the pts and the current -position is returned. - -The pts is reset to GST_CLOCK_TIME_NONE and the distance is set to 0 when -the adapter is first created or when it is cleared. This also means that before -the first byte with a pts is removed from the adapter, the pts -and distance returned are GST_CLOCK_TIME_NONE and 0 respectively. -## `offset` -the offset in the adapter at which to get timestamp -## `distance` -pointer to location for distance, or `None` - -# Returns - -The previously seen pts at given offset. - -Get the PTS that was on the last buffer with the GST_BUFFER_FLAG_DISCONT -flag, or GST_CLOCK_TIME_NONE. - -Feature: `v1_10` - - -# Returns - -The PTS at the last discont or GST_CLOCK_TIME_NONE. - -Adds the data from `buf` to the data stored inside `self` and takes -ownership of the buffer. -## `buf` -a `gst::Buffer` to add to queue in the adapter - -Returns a freshly allocated buffer containing the first `nbytes` bytes of the -`self`. The returned bytes will be flushed from the adapter. - -Caller owns returned value. g_free after usage. - -Free-function: g_free -## `nbytes` -the number of bytes to take - -# Returns - - - oven-fresh hot data, or `None` if `nbytes` bytes are not available - -Returns a `gst::Buffer` containing the first `nbytes` bytes of the -`self`. The returned bytes will be flushed from the adapter. -This function is potentially more performant than -`Adapter::take` since it can reuse the memory in pushed buffers -by subbuffering or merging. This function will always return a -buffer with a single memory region. - -Note that no assumptions should be made as to whether certain buffer -flags such as the DISCONT flag are set on the returned buffer, or not. -The caller needs to explicitly set or unset flags that should be set or -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 -usage. - -Free-function: gst_buffer_unref -## `nbytes` -the number of bytes to take - -# Returns - -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. - -Returns a `gst::Buffer` containing the first `nbytes` of the `self`. -The returned bytes will be flushed from the adapter. This function -is potentially more performant than `Adapter::take_buffer` since -it can reuse the memory in pushed buffers by subbuffering or -merging. Unlike `Adapter::take_buffer`, the returned buffer may -be composed of multiple non-contiguous `gst::Memory` objects, no -copies are made. - -Note that no assumptions should be made as to whether certain buffer -flags such as the DISCONT flag are set on the returned buffer, or not. -The caller needs to explicitly set or unset flags that should be set or -unset. - -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. - -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 -usage. - -Free-function: gst_buffer_unref -## `nbytes` -the number of bytes to take - -# Returns - -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. - -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 -the list after usage. -## `nbytes` -the number of bytes to take - -# Returns - -a `gst::BufferList` of buffers containing - the first `nbytes` of the adapter, or `None` if `nbytes` bytes are not - available - -Returns a `glib::List` 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 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 - -# Returns - -a `glib::List` of - buffers containing the first `nbytes` of the adapter, or `None` if `nbytes` - bytes are not available - -Releases the memory obtained with the last `Adapter::map`. - -Manages a set of pads with the purpose of aggregating their buffers. -Control is given to the subclass when all pads have data. - - * Base class for mixers and muxers. Subclasses should at least implement - the `AggregatorClass.aggregate`() virtual method. - - * Installs a `GstPadChainFunction`, a `GstPadEventFullFunction` and a - `GstPadQueryFunction` to queue all serialized data packets per sink pad. - Subclasses should not overwrite those, but instead implement - `AggregatorClass.sink_event`() and `AggregatorClass.sink_query`() as - needed. - - * When data is queued on all pads, the aggregate vmethod is called. - - * One can peek at the data on any given GstAggregatorPad with the - `AggregatorPadExt::peek_buffer` method, and remove it from the pad - with the gst_aggregator_pad_pop_buffer () method. When a buffer - has been taken with pop_buffer (), a new buffer can be queued - on that pad. - - * When `AggregatorPadExt::peek_buffer` or `AggregatorPadExt::has_buffer` - are called, a reference is taken to the returned buffer, which stays - valid until either: - - - `AggregatorPadExt::pop_buffer` is called, in which case the caller - is guaranteed that the buffer they receive is the same as the peeked - buffer. - - `AggregatorPadExt::drop_buffer` is called, in which case the caller - is guaranteed that the dropped buffer is the one that was peeked. - - the subclass implementation of `AggregatorClass.aggregate` returns. - - Subsequent calls to `AggregatorPadExt::peek_buffer` or - `AggregatorPadExt::has_buffer` return / check the same buffer that was - returned / checked, until one of the conditions listed above is met. - - Subclasses are only allowed to call these methods from the aggregate - thread. - - * If the subclass wishes to push a buffer downstream in its aggregate - implementation, it should do so through the - `Aggregator::finish_buffer` method. This method will take care - of sending and ordering mandatory events such as stream start, caps - and segment. Buffer lists can also be pushed out with - `Aggregator::finish_buffer_list`. - - * Same goes for EOS events, which should not be pushed directly by the - subclass, it should instead return GST_FLOW_EOS in its aggregate - implementation. - - * Note that the aggregator logic regarding gap event handling is to turn - these into gap buffers with matching PTS and duration. It will also - flag these buffers with GST_BUFFER_FLAG_GAP and GST_BUFFER_FLAG_DROPPABLE - to ease their identification and subsequent processing. - - * Subclasses must use (a subclass of) `AggregatorPad` for both their - sink and source pads. - See `gst::ElementClass::add_static_pad_template_with_gtype`. - -This class used to live in gst-plugins-bad and was moved to core. - -This is an Abstract Base Class, you cannot instantiate it. - -Feature: `v1_14` - -# Implements - -[`AggregatorExt`](trait@crate::AggregatorExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`AggregatorExtManual`](trait@crate::AggregatorExtManual) - -Trait containing all `Aggregator` methods. - -Feature: `v1_14` - -# Implementors - -[`Aggregator`](struct@crate::Aggregator) - -This method will push the provided output buffer downstream. If needed, -mandatory events such as stream-start, caps, and segment events will be -sent before pushing the buffer. - -Feature: `v1_14` - -## `buffer` -the `gst::Buffer` to push. - -This method will push the provided output buffer list downstream. If needed, -mandatory events such as stream-start, caps, and segment events will be -sent before pushing the buffer. - -Feature: `v1_18` - -## `bufferlist` -the `gst::BufferList` to push. - -Lets `Aggregator` sub-classes get the memory `allocator` -acquired by the base class and its `params`. - -Unref the `allocator` after use it. - -Feature: `v1_14` - -## `allocator` -the `gst::Allocator` -used -## `params` -the -`gst::AllocationParams` of `allocator` - - -Feature: `v1_14` - - -# Returns - -the instance of the `gst::BufferPool` used -by `trans`; free it after use it - -Retrieves the latency values reported by `self` in response to the latency -query, or `GST_CLOCK_TIME_NONE` if there is not live source connected and the element -will not wait for the clock. - -Typically only called by subclasses. - -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`. - -Use this function to determine what input buffers will be aggregated -to produce the next output buffer. This should only be called from -a `Aggregator::samples-selected` handler, and can be used to precisely -control aggregating parameters for a given set of input samples. - -Feature: `v1_18` - - -# Returns - -The sample that is about to be aggregated. It may hold a `gst::Buffer` - or a `gst::BufferList`. The contents of its info structure is subclass-dependent, - and documented on a subclass basis. The buffers held by the sample are - not writable. - -Subclasses should call this when they have prepared the -buffers they will aggregate for each of their sink pads, but -before using any of the properties of the pads that govern -*how* aggregation should be performed, for example z-index -for video aggregators. - -If `AggregatorExt::update_segment` is used by the subclass, -it MUST be called before `Aggregator::selected_samples`. - -This function MUST only be called from the `AggregatorClass::aggregate`() -function. - -Feature: `v1_18` - -## `pts` -The presentation timestamp of the next output buffer -## `dts` -The decoding timestamp of the next output buffer -## `duration` -The duration of the next output buffer -## `info` -a `gst::Structure` containing additional information - -Lets `Aggregator` sub-classes tell the baseclass what their internal -latency is. Will also post a LATENCY message on the bus so the pipeline -can reconfigure its global latency. - -Feature: `v1_14` - -## `min_latency` -minimum latency -## `max_latency` -maximum latency - -Sets the caps to be used on the src pad. - -Feature: `v1_14` - -## `caps` -The `gst::Caps` to set on the src pad. - -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. - -This is the desired behaviour in most cases where you have a live source -and you have a dead line based aggregator subclass. - -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. - -Subclasses MUST call this before `Aggregator::selected_samples`, -if it is used at all. - -Feature: `v1_18` - - -Signals that the `Aggregator` subclass has selected the next set -of input samples it will aggregate. Handlers may call -`AggregatorExt::peek_next_sample` at that point. - -Feature: `v1_18` - -## `segment` -The `gst::Segment` the next output buffer is part of -## `pts` -The presentation timestamp of the next output buffer -## `dts` -The decoding timestamp of the next output buffer -## `duration` -The duration of the next output buffer -## `info` -a `gst::Structure` containing additional information - -Enables the emission of signals such as `Aggregator::samples-selected` - -Feature: `v1_18` - - -Enables the emission of signals such as `Aggregator::samples-selected` - -Feature: `v1_18` - - -Force minimum upstream latency (in nanoseconds). When sources with a -higher latency are expected to be plugged in dynamically after the -aggregator has started playing, this allows overriding the minimum -latency reported by the initial source(s). This is only taken into -account when larger than the actually reported minimum latency. - -Feature: `v1_16` - - -Force minimum upstream latency (in nanoseconds). When sources with a -higher latency are expected to be plugged in dynamically after the -aggregator has started playing, this allows overriding the minimum -latency reported by the initial source(s). This is only taken into -account when larger than the actually reported minimum latency. - -Feature: `v1_16` - - -Pads managed by a `Aggregator` subclass. - -This class used to live in gst-plugins-bad and was moved to core. - -Feature: `v1_14` - -# Implements - -[`AggregatorPadExt`](trait@crate::AggregatorPadExt), [`trait@gst::PadExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`AggregatorPadExtManual`](trait@crate::AggregatorPadExtManual) - -Trait containing all `AggregatorPad` methods. - -Feature: `v1_14` - -# Implementors - -[`AggregatorPad`](struct@crate::AggregatorPad) - -Drop the buffer currently queued in `self`. - -Feature: `v1_14` - - -# Returns - -TRUE if there was a buffer queued in `self`, or FALSE if not. - -This checks if a pad has a buffer available that will be returned by -a call to `AggregatorPadExt::peek_buffer` or -`AggregatorPadExt::pop_buffer`. - -Feature: `v1_14_1` - - -# Returns - -`true` if the pad has a buffer available as the next thing. - - -Feature: `v1_14` - - -# Returns - -`true` if the pad is EOS, otherwise `false`. - - -Feature: `v1_14` - - -# Returns - -A reference to the buffer in `self` or -NULL if no buffer was queued. You should unref the buffer after -usage. - -Steal the ref to the buffer currently queued in `self`. - -Feature: `v1_14` - - -# Returns - -The buffer in `self` or NULL if no buffer was - queued. You should unref the buffer after usage. - -Enables the emission of signals such as `AggregatorPad::buffer-consumed` - -Feature: `v1_16` - - -Enables the emission of signals such as `AggregatorPad::buffer-consumed` - -Feature: `v1_16` - - - -Start at running time 0. - -Start at the running time of -the first buffer that is received. - -Start at the running time -selected by the `start-time` property. - -Feature: `v1_18` - - -This base class is for parser elements that process data and splits it -into separate audio/video/whatever frames. - -It provides for: - - * provides one sink pad and one source pad - * handles state changes - * can operate in pull mode or push mode - * handles seeking in both modes - * handles events (SEGMENT/EOS/FLUSH) - * handles queries (POSITION/DURATION/SEEKING/FORMAT/CONVERT) - * handles flushing - -The purpose of this base class is to provide the basic functionality of -a parser and share a lot of rather complex code. - -# Description of the parsing mechanism: - -## Set-up phase - - * `BaseParse` calls `BaseParseClass.start`() to inform subclass - that data processing is about to start now. - - * `BaseParse` class calls `BaseParseClass.set_sink_caps`() to - inform the subclass about incoming sinkpad caps. Subclass could - already set the srcpad caps accordingly, but this might be delayed - until calling `BaseParse::finish_frame` with a non-queued frame. - - * At least at this point subclass needs to tell the `BaseParse` class - how big data chunks it wants to receive (minimum frame size ). It can - do this with `BaseParseExt::set_min_frame_size`. - - * `BaseParse` class sets up appropriate data passing mode (pull/push) - and starts to process the data. - -## Parsing phase - - * `BaseParse` gathers at least min_frame_size bytes of data either - by pulling it from upstream or collecting buffers in an internal - `Adapter`. - - * A buffer of (at least) min_frame_size bytes is passed to subclass - with `BaseParseClass.handle_frame`(). Subclass checks the contents - and can optionally return `gst::FlowReturn::Ok` along with an amount of data - to be skipped to find a valid frame (which will result in a - subsequent DISCONT). If, otherwise, the buffer does not hold a - complete frame, `BaseParseClass.handle_frame`() can merely return - and will be called again when additional data is available. In push - mode this amounts to an additional input buffer (thus minimal - additional latency), in pull mode this amounts to some arbitrary - reasonable buffer size increase. - - Of course, `BaseParseExt::set_min_frame_size` could also be used if - a very specific known amount of additional data is required. If, - however, the buffer holds a complete valid frame, it can pass the - size of this frame to `BaseParse::finish_frame`. - - If acting as a converter, it can also merely indicate consumed input - data while simultaneously providing custom output data. Note that - baseclass performs some processing (such as tracking overall consumed - data rate versus duration) for each finished frame, but other state - is only updated upon each call to `BaseParseClass.handle_frame`() - (such as tracking upstream input timestamp). - - Subclass is also responsible for setting the buffer metadata - (e.g. buffer timestamp and duration, or keyframe if applicable). - (although the latter can also be done by `BaseParse` if it is - appropriately configured, see below). Frame is provided with - timestamp derived from upstream (as much as generally possible), - duration obtained from configuration (see below), and offset - if meaningful (in pull mode). - - Note that `BaseParseClass.handle_frame`() might receive any small - amount of input data when leftover data is being drained (e.g. at - EOS). - - * As part of finish frame processing, just prior to actually pushing - the buffer in question, it is passed to - `BaseParseClass.pre_push_frame`() which gives subclass yet one last - chance to examine buffer metadata, or to send some custom (tag) - events, or to perform custom (segment) filtering. - - * During the parsing process `BaseParseClass` will handle both srcpad - and sinkpad events. They will be passed to subclass if - `BaseParseClass.sink_event`() or `BaseParseClass.src_event`() - implementations have been provided. - -## Shutdown phase - -* `BaseParse` class calls `BaseParseClass.stop`() to inform the - subclass that data parsing will be stopped. - -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 -set the fixed caps on srcpad, when the format is ensured (e.g. when -base class calls subclass' `BaseParseClass.set_sink_caps`() function). - -This base class uses `gst::Format::Default` as a meaning of frames. So, -subclass conversion routine needs to know that conversion from -`gst::Format::Time` to `gst::Format::Default` must return the -frame number that can be found from the given byte position. - -`BaseParse` uses subclasses conversion methods also for seeking (or -otherwise uses its own default one, see also below). - -Subclass `start` and `stop` functions will be called to inform the beginning -and end of data processing. - -Things that subclass need to take care of: - -* Provide pad templates -* Fixate the source pad caps when appropriate -* Inform base class how big data chunks should be retrieved. This is - done with `BaseParseExt::set_min_frame_size` function. -* Examine data chunks passed to subclass with - `BaseParseClass.handle_frame`() and pass proper frame(s) to - `BaseParse::finish_frame`, and setting src pad caps and timestamps - on frame. -* Provide conversion functions -* Update the duration information with `BaseParse::set_duration` -* Optionally passthrough using `BaseParseExt::set_passthrough` -* Configure various baseparse parameters using - `BaseParseExt::set_average_bitrate`, `BaseParseExt::set_syncable` - and `BaseParse::set_frame_rate`. - -* In particular, if subclass is unable to determine a duration, but - parsing (or specs) yields a frames per seconds rate, then this can be - provided to `BaseParse` to enable it to cater for buffer time - metadata (which will be taken from upstream as much as - possible). Internally keeping track of frame durations and respective - sizes that have been pushed provides `BaseParse` with an estimated - bitrate. A default `BaseParseClass.convert`() (used if not - overridden) will then use these rates to perform obvious conversions. - These rates are also used to update (estimated) duration at regular - frame intervals. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`BaseParseExt`](trait@crate::BaseParseExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`BaseParseExtManual`](trait@crate::BaseParseExtManual) - -Trait containing all `BaseParse` methods. - -# Implementors - -[`BaseParse`](struct@crate::BaseParse) - -Adds an entry to the index associating `offset` to `ts`. It is recommended -to only add keyframe entries. `force` allows to bypass checks, such as -whether the stream is (upstream) seekable, another entry is already "close" -to the new entry, etc. -## `offset` -offset of entry -## `ts` -timestamp associated with offset -## `key` -whether entry refers to keyframe -## `force` -add entry disregarding sanity checks - -# Returns - -`gboolean` indicating whether entry was added - -Default implementation of `BaseParseClass.convert`(). -## `src_format` -`gst::Format` describing the source format. -## `src_value` -Source value to be converted. -## `dest_format` -`gst::Format` defining the converted format. -## `dest_value` -Pointer where the conversion result will be put. - -# Returns - -`true` if conversion was successful. - -Drains the adapter until it is empty. It decreases the min_frame_size to -match the current adapter size and calls chain method until the adapter -is emptied or chain returns with error. - -Feature: `v1_12` - - -Collects parsed data and pushes this downstream. -Source pad caps must be set when this is called. - -If `frame`'s out_buffer is set, that will be used as subsequent frame data. -Otherwise, `size` samples will be taken from the input and used for output, -and the output's metadata (timestamps etc) will be taken as (optionally) -set by the subclass on `frame`'s (input) buffer (which is otherwise -ignored for any but the above purpose/information). - -Note that the latter buffer is invalidated by this call, whereas the -caller retains ownership of `frame`. -## `frame` -a `BaseParseFrame` -## `size` -consumed input data represented by frame - -# Returns - -a `gst::FlowReturn` that should be escalated to caller (of caller) - -Sets the parser subclass's tags and how they should be merged with any -upstream stream tags. This will override any tags previously-set -with `BaseParseExt::merge_tags`. - -Note that this is provided for convenience, and the subclass is -not required to use this and can still do tag handling on its own. -## `tags` -a `gst::TagList` to merge, or NULL to unset - previously-set tags -## `mode` -the `gst::TagMergeMode` to use, usually `gst::TagMergeMode::Replace` - -Pushes the frame's buffer downstream, sends any pending events and -does some timestamp and segment handling. Takes ownership of -frame's buffer, though caller retains ownership of `frame`. - -This must be called with sinkpad STREAM_LOCK held. -## `frame` -a `BaseParseFrame` - -# Returns - -`gst::FlowReturn` - -Optionally sets the average bitrate detected in media (if non-zero), -e.g. based on metadata, as it will be posted to the application. - -By default, announced average bitrate is estimated. The average bitrate -is used to estimate the total duration of the stream and to estimate -a seek position, if there's no index and the format is syncable -(see `BaseParseExt::set_syncable`). -## `bitrate` -average bitrate in bits/second - -Sets the duration of the currently playing media. Subclass can use this -when it is able to determine duration and/or notices a change in the media -duration. Alternatively, if `interval` is non-zero (default), then stream -duration is determined based on estimated bitrate, and updated every `interval` -frames. -## `fmt` -`gst::Format`. -## `duration` -duration value. -## `interval` -how often to update the duration estimate based on bitrate, or 0. - -If frames per second is configured, parser can take care of buffer duration -and timestamping. When performing segment clipping, or seeking to a specific -location, a corresponding decoder might need an initial `lead_in` and a -following `lead_out` number of frames to ensure the desired segment is -entirely filled upon decoding. -## `fps_num` -frames per second (numerator). -## `fps_den` -frames per second (denominator). -## `lead_in` -frames needed before a segment for subsequent decode -## `lead_out` -frames needed after a segment - -Set if frames carry timing information which the subclass can (generally) -parse and provide. In particular, intrinsic (rather than estimated) time -can be obtained following a seek. -## `has_timing` -whether frames carry timing information - -By default, the base class might try to infer PTS from DTS and vice -versa. While this is generally correct for audio data, it may not -be otherwise. Sub-classes implementing such formats should disable -timestamp inferring. -## `infer_ts` -`true` if parser should infer DTS/PTS from each other - -Sets the minimum and maximum (which may likely be equal) latency introduced -by the parsing process. If there is such a latency, which depends on the -particular parsing of the format, it typically corresponds to 1 frame duration. -## `min_latency` -minimum parse latency -## `max_latency` -maximum parse latency - -Subclass can use this function to tell the base class that it needs to -be given buffers of at least `min_size` bytes. -## `min_size` -Minimum size in bytes of the data that this base class should - give to subclass. - -Set if the nature of the format or configuration does not allow (much) -parsing, and the parser should operate in passthrough mode (which only -applies when operating in push mode). That is, incoming buffers are -pushed through unmodified, i.e. no `BaseParseClass.handle_frame`() -will be invoked, but `BaseParseClass.pre_push_frame`() will still be -invoked, so subclass can perform as much or as little is appropriate for -passthrough semantics in `BaseParseClass.pre_push_frame`(). -## `passthrough` -`true` if parser should run in passthrough mode - -By default, the base class will guess PTS timestamps using a simple -interpolation (previous timestamp + duration), which is incorrect for -data streams with reordering, where PTS can go backward. Sub-classes -implementing such formats should disable PTS interpolation. -## `pts_interpolate` -`true` if parser should interpolate PTS timestamps - -Set if frame starts can be identified. This is set by default and -determines whether seeking based on bitrate averages -is possible for a format/stream. -## `syncable` -set if frame starts can be identified - -This function should only be called from a `handle_frame` implementation. - -`BaseParse` creates initial timestamps for frames by using the last -timestamp seen in the stream before the frame starts. In certain -cases, the correct timestamps will occur in the stream after the -start of the frame, but before the start of the actual picture data. -This function can be used to set the timestamps based on the offset -into the frame data that the picture starts. -## `offset` -offset into current buffer - -If set to `true`, baseparse will unconditionally force parsing of the -incoming data. This can be required in the rare cases where the incoming -side-data (caps, pts, dts, ...) is not trusted by the user and wants to -force validation and parsing of the incoming data. -If set to `false`, decision of whether to parse the data or not is up to -the implementation (standard behaviour). - -If set to `true`, baseparse will unconditionally force parsing of the -incoming data. This can be required in the rare cases where the incoming -side-data (caps, pts, dts, ...) is not trusted by the user and wants to -force validation and parsing of the incoming data. -If set to `false`, decision of whether to parse the data or not is up to -the implementation (standard behaviour). - -Frame (context) data passed to each frame parsing virtual methods. In -addition to providing the data to be checked for a valid frame or an already -identified frame, it conveys additional metadata or control information -from and to the subclass w.r.t. the particular frame in question (rather -than global parameters). Some of these may apply to each parsing stage, others -only to some a particular one. These parameters are effectively zeroed at start -of each frame's processing, i.e. parsing virtual method invocation sequence. - -Allocates a new `BaseParseFrame`. This function is mainly for bindings, -elements written in C should usually allocate the frame on the stack and -then use `BaseParseFrame::init` to initialise it. -## `buffer` -a `gst::Buffer` -## `flags` -the flags -## `overhead` -number of bytes in this frame which should be counted as - metadata overhead, ie. not used to calculate the average bitrate. - Set to -1 to mark the entire frame as metadata. If in doubt, set to 0. - -# Returns - -a newly-allocated `BaseParseFrame`. Free with - `BaseParseFrame::free` when no longer needed. - -Copies a `BaseParseFrame`. - -Feature: `v1_12_1` - - -# Returns - -A copy of `self` - -Frees the provided `self`. - -Sets a `BaseParseFrame` to initial state. Currently this means -all public fields are zero-ed and a private flag is set to make -sure `BaseParseFrame::free` only frees the contents but not -the actual frame. Use this function to initialise a `BaseParseFrame` -allocated on the stack. - -Flags to be used in a `BaseParseFrame`. - -no flag - -set by baseclass if current frame - is passed for processing to the subclass for the first time - (and not set on subsequent calls with same data). - -set to indicate this buffer should not be - counted as frame, e.g. if this frame is dependent on a previous one. - As it is not counted as a frame, bitrate increases but frame to time - conversions are maintained. - -`pre_push_frame` can set this to indicate - that regular segment clipping can still be performed (as opposed to - any custom one having been done). - -indicates to `finish_frame` that the - the frame should be dropped (and might be handled internally by subclass) - -indicates to `finish_frame` that the - the frame should be queued for now and processed fully later - when the first non-queued frame is finished - -`BaseSink` is the base class for sink elements in GStreamer, such as -xvimagesink or filesink. It is a layer on top of `gst::Element` that provides a -simplified interface to plugin writers. `BaseSink` handles many details -for you, for example: preroll, clock synchronization, state changes, -activation in push or pull mode, and queries. - -In most cases, when writing sink elements, there is no need to implement -class methods from `gst::Element` or to set functions on pads, because the -`BaseSink` infrastructure should be sufficient. - -`BaseSink` provides support for exactly one sink pad, which should be -named "sink". A sink implementation (subclass of `BaseSink`) should -install a pad template in its class_init function, like so: - -```C -static void -my_element_class_init (GstMyElementClass *klass) -{ - GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass); - - // sinktemplate should be a #GstStaticPadTemplate with direction - // %GST_PAD_SINK and name "sink" - gst_element_class_add_static_pad_template (gstelement_class, &sinktemplate); - - gst_element_class_set_static_metadata (gstelement_class, - "Sink name", - "Sink", - "My Sink element", - "The author "); -} -``` - -`BaseSink` will handle the prerolling correctly. This means that it will -return `gst::StateChangeReturn::Async` from a state change to PAUSED until the first -buffer arrives in this element. The base class will call the -`BaseSinkClass.preroll`() vmethod with this preroll buffer and will then -commit the state change to the next asynchronously pending state. - -When the element is set to PLAYING, `BaseSink` will synchronise on the -clock using the times returned from `BaseSinkClass.get_times`(). If this -function returns `GST_CLOCK_TIME_NONE` for the start time, no synchronisation -will be done. Synchronisation can be disabled entirely by setting the object -`BaseSink:sync` property to `false`. - -After synchronisation the virtual method `BaseSinkClass.render`() will be -called. Subclasses should minimally implement this method. - -Subclasses that synchronise on the clock in the `BaseSinkClass.render`() -method are supported as well. These classes typically receive a buffer in -the render method and can then potentially block on the clock while -rendering. A typical example is an audiosink. -These subclasses can use `BaseSink::wait_preroll` to perform the -blocking wait. - -Upon receiving the EOS event in the PLAYING state, `BaseSink` will wait -for the clock to reach the time indicated by the stop time of the last -`BaseSinkClass.get_times`() call before posting an EOS message. When the -element receives EOS in PAUSED, preroll completes, the event is queued and an -EOS message is posted when going to PLAYING. - -`BaseSink` will internally use the `gst::EventType::Segment` events to schedule -synchronisation and clipping of buffers. Buffers that fall completely outside -of the current segment are dropped. Buffers that fall partially in the -segment are rendered (and prerolled). Subclasses should do any subbuffer -clipping themselves when needed. - -`BaseSink` will by default report the current playback position in -`gst::Format::Time` based on the current clock time and segment information. -If no clock has been set on the element, the query will be forwarded -upstream. - -The `BaseSinkClass.set_caps`() function will be called when the subclass -should configure itself to process a specific media type. - -The `BaseSinkClass.start`() and `BaseSinkClass.stop`() virtual methods -will be called when resources should be allocated. Any -`BaseSinkClass.preroll`(), `BaseSinkClass.render`() and -`BaseSinkClass.set_caps`() function will be called between the -`BaseSinkClass.start`() and `BaseSinkClass.stop`() calls. - -The `BaseSinkClass.event`() virtual method will be called when an event is -received by `BaseSink`. Normally this method should only be overridden by -very specific elements (such as file sinks) which need to handle the -newsegment event specially. - -The `BaseSinkClass.unlock`() method is called when the elements should -unblock any blocking operations they perform in the -`BaseSinkClass.render`() method. This is mostly useful when the -`BaseSinkClass.render`() method performs a blocking write on a file -descriptor, for example. - -The `BaseSink:max-lateness` property affects how the sink deals with -buffers that arrive too late in the sink. A buffer arrives too late in the -sink when the presentation time (as a combination of the last segment, buffer -timestamp and element base_time) plus the duration is before the current -time of the clock. -If the frame is later than max-lateness, the sink will drop the buffer -without calling the render method. -This feature is disabled if sync is disabled, the -`BaseSinkClass.get_times`() method does not return a valid start time or -max-lateness is set to -1 (the default). -Subclasses can use `BaseSinkExt::set_max_lateness` to configure the -max-lateness value. - -The `BaseSink:qos` property will enable the quality-of-service features of -the basesink which gather statistics about the real-time performance of the -clock synchronisation. For each buffer received in the sink, statistics are -gathered and a QOS event is sent upstream with these numbers. This -information can then be used by upstream elements to reduce their processing -rate, for example. - -The `BaseSink:async` property can be used to instruct the sink to never -perform an ASYNC state change. This feature is mostly usable when dealing -with non-synchronized streams or sparse streams. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`BaseSinkExt`](trait@crate::BaseSinkExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`BaseSinkExtManual`](trait@crate::BaseSinkExtManual) - -Trait containing all `BaseSink` methods. - -# Implementors - -[`BaseSink`](struct@crate::BaseSink) - -If the `self` spawns its own thread for pulling buffers from upstream it -should call this method after it has pulled a buffer. If the element needed -to preroll, this function will perform the preroll and will then block -until the element state is changed. - -This function should be called with the PREROLL_LOCK held. -## `obj` -the mini object that caused the preroll - -# Returns - -`gst::FlowReturn::Ok` if the preroll completed and processing can -continue. Any other return value should be returned from the render vmethod. - -Get the number of bytes that the sink will pull when it is operating in pull -mode. - -# Returns - -the number of bytes `self` will pull in pull mode. - -Checks if `self` is currently configured to drop buffers which are outside -the current segment - -Feature: `v1_12` - - -# Returns - -`true` if the sink is configured to drop buffers outside the -current segment. - -Get the last sample that arrived in the sink and was used for preroll or for -rendering. This property can be used to generate thumbnails. - -The `gst::Caps` on the sample can be used to determine the type of the buffer. - -Free-function: gst_sample_unref - -# Returns - -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. - -Get the currently configured latency. - -# Returns - -The configured latency. - -Get the maximum amount of bits per second that the sink will render. - -# Returns - -the maximum number of bits per second `self` will render. - -Gets the max lateness value. See `BaseSinkExt::set_max_lateness` for -more details. - -# Returns - -The maximum time in nanoseconds that a buffer can be late -before it is dropped and not rendered. A value of -1 means an -unlimited time. - -Get the processing deadline of `self`. see -`BaseSinkExt::set_processing_deadline` for more information about -the processing deadline. - -Feature: `v1_16` - - -# Returns - -the processing deadline - -Get the render delay of `self`. see `BaseSinkExt::set_render_delay` for more -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. - -# Returns - -`true` if the sink is configured to synchronize against the clock. - -Get the time that will be inserted between frames to control the -maximum buffers per second. - -# Returns - -the number of nanoseconds `self` will put between frames. - -Get the synchronisation offset of `self`. - -# Returns - -The synchronisation offset. - -Checks if `self` is currently configured to perform asynchronous state -changes to PAUSED. - -# Returns - -`true` if the sink is configured to perform asynchronous state -changes. - -Checks if `self` is currently configured to store the last received sample in -the last-sample property. - -# Returns - -`true` if the sink is configured to store the last received sample. - -Checks if `self` is currently configured to send Quality-of-Service events -upstream. - -# Returns - -`true` if the sink is configured to perform Quality-of-Service. - -Query the sink for the latency parameters. The latency will be queried from -the upstream elements. `live` will be `true` if `self` is configured to -synchronize against the clock. `upstream_live` will be `true` if an upstream -element is live. - -If both `live` and `upstream_live` are `true`, the sink will want to compensate -for the latency introduced by the upstream elements by setting the -`min_latency` to a strictly positive value. - -This function is mostly used by subclasses. -## `live` -if the sink is live -## `upstream_live` -if an upstream element is live -## `min_latency` -the min latency of the upstream elements -## `max_latency` -the max latency of the upstream elements - -# Returns - -`true` if the query succeeded. - -Configures `self` to perform all state changes asynchronously. When async is -disabled, the sink will immediately go to PAUSED instead of waiting for a -preroll buffer. This feature is useful if the sink does not synchronize -against the clock or when it is dealing with sparse streams. -## `enabled` -the new async value. - -Set the number of bytes that the sink will pull when it is operating in pull -mode. -## `blocksize` -the blocksize in bytes - -Configure `self` to drop buffers which are outside the current segment - -Feature: `v1_12` - -## `drop_out_of_segment` -drop buffers outside the segment - -Configures `self` to store the last received sample in the last-sample -property. -## `enabled` -the new enable-last-sample value. - -Set the maximum amount of bits per second that the sink will render. -## `max_bitrate` -the max_bitrate in bits per second - -Sets the new max lateness value to `max_lateness`. This value is -used to decide if a buffer should be dropped or not based on the -buffer timestamp and the current clock time. A value of -1 means -an unlimited time. -## `max_lateness` -the new max lateness value. - -Maximum amount of time (in nanoseconds) that the pipeline can take -for processing the buffer. This is added to the latency of live -pipelines. - -This function is usually called by subclasses. - -Feature: `v1_16` - -## `processing_deadline` -the new processing deadline in nanoseconds. - -Configures `self` to send Quality-of-Service events upstream. -## `enabled` -the new qos value. - -Set the render delay in `self` to `delay`. The render delay is the time -between actual rendering of a buffer and its synchronisation time. Some -devices might delay media rendering which can be compensated for with this -function. - -After calling this function, this sink will report additional latency and -other sinks will adjust their latency to delay the rendering of their media. - -This function is usually called by subclasses. -## `delay` -the new delay - -Configures `self` to synchronize on the clock or not. When -`sync` is `false`, incoming samples will be played as fast as -possible. If `sync` is `true`, the timestamps of the incoming -buffers will be used to schedule the exact render time of its -contents. -## `sync` -the new sync value. - -Set the time that will be inserted between rendered buffers. This -can be used to control the maximum buffers per second that the sink -will render. -## `throttle` -the throttle time in nanoseconds - -Adjust the synchronisation of `self` with `offset`. A negative value will -render buffers earlier than their timestamp. A positive value will delay -rendering. This function can be used to fix playback of badly timestamped -buffers. -## `offset` -the new offset - -This function will wait for preroll to complete and will then block until `time` -is reached. It is usually called by subclasses that use their own internal -synchronisation but want to let some synchronization (like EOS) be handled -by the base class. - -This function should only be called with the PREROLL_LOCK held (like when -receiving an EOS event in the ::event vmethod or when handling buffers in -::render). - -The `time` argument should be the running_time of when the timeout should happen -and will be adjusted with any latency and offset configured in the sink. -## `time` -the running_time to be reached -## `jitter` -the jitter to be filled with time diff, or `None` - -# Returns - -`gst::FlowReturn` - -This function will block until `time` is reached. It is usually called by -subclasses that use their own internal synchronisation. - -If `time` is not valid, no synchronisation is done and `gst::ClockReturn::Badtime` is -returned. Likewise, if synchronisation is disabled in the element or there -is no clock, no synchronisation is done and `gst::ClockReturn::Badtime` is returned. - -This function should only be called with the PREROLL_LOCK held, like when -receiving an EOS event in the `BaseSinkClass.event`() vmethod or when -receiving a buffer in -the `BaseSinkClass.render`() vmethod. - -The `time` argument should be the running_time of when this method should -return and is not adjusted with any latency or offset configured in the -sink. -## `time` -the running_time to be reached -## `jitter` -the jitter to be filled with time diff, or `None` - -# Returns - -`gst::ClockReturn` - -If the `BaseSinkClass.render`() method performs its own synchronisation -against the clock it must unblock when going from PLAYING to the PAUSED state -and call this method before continuing to render the remaining data. - -If the `BaseSinkClass.render`() method can block on something else than -the clock, it must also be ready to unblock immediately on -the `BaseSinkClass.unlock`() method and cause the -`BaseSinkClass.render`() method to immediately call this function. -In this case, the subclass must be prepared to continue rendering where it -left off if this function returns `gst::FlowReturn::Ok`. - -This function will block until a state change to PLAYING happens (in which -case this function returns `gst::FlowReturn::Ok`) or the processing must be stopped due -to a state change to READY or a FLUSH event (in which case this function -returns `gst::FlowReturn::Flushing`). - -This function should only be called with the PREROLL_LOCK held, like in the -render function. - -# Returns - -`gst::FlowReturn::Ok` if the preroll completed and processing can -continue. Any other return value should be returned from the render vmethod. - -If set to `true`, the basesink will perform asynchronous state changes. -When set to `false`, the sink will not signal the parent when it prerolls. -Use this option when dealing with sparse streams or when synchronisation is -not required. - -If set to `true`, the basesink will perform asynchronous state changes. -When set to `false`, the sink will not signal the parent when it prerolls. -Use this option when dealing with sparse streams or when synchronisation is -not required. - -The amount of bytes to pull when operating in pull mode. - -The amount of bytes to pull when operating in pull mode. - -Enable the last-sample property. If `false`, basesink doesn't keep a -reference to the last buffer arrived and the last-sample property is always -set to `None`. This can be useful if you need buffers to be released as soon -as possible, eg. if you're using a buffer pool. - -Enable the last-sample property. If `false`, basesink doesn't keep a -reference to the last buffer arrived and the last-sample property is always -set to `None`. This can be useful if you need buffers to be released as soon -as possible, eg. if you're using a buffer pool. - -The last buffer that arrived in the sink and was used for preroll or for -rendering. This property can be used to generate thumbnails. This property -can be `None` when the sink has not yet received a buffer. - -Control the maximum amount of bits that will be rendered per second. -Setting this property to a value bigger than 0 will make the sink delay -rendering of the buffers when it would exceed to max-bitrate. - -Control the maximum amount of bits that will be rendered per second. -Setting this property to a value bigger than 0 will make the sink delay -rendering of the buffers when it would exceed to max-bitrate. - -Maximum amount of time (in nanoseconds) that the pipeline can take -for processing the buffer. This is added to the latency of live -pipelines. - -Feature: `v1_16` - - -Maximum amount of time (in nanoseconds) that the pipeline can take -for processing the buffer. This is added to the latency of live -pipelines. - -Feature: `v1_16` - - -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. - -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 -to a value bigger than 0 will make the sink create THROTTLE QoS events. - -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 -to a value bigger than 0 will make the sink create THROTTLE QoS events. - -Controls the final synchronisation, a negative value will render the buffer -earlier while a positive value delays playback. This property can be -used to fix synchronisation in bad files. - -Controls the final synchronisation, a negative value will render the buffer -earlier while a positive value delays playback. This property can be -used to fix synchronisation in bad files. - -This is a generic base class for source elements. The following -types of sources are supported: - - * random access sources like files - * seekable sources - * live sources - -The source can be configured to operate in any `gst::Format` with the -`BaseSrcExt::set_format` method. The currently set format determines -the format of the internal `gst::Segment` and any `gst::EventType::Segment` -events. The default format for `BaseSrc` is `gst::Format::Bytes`. - -`BaseSrc` always supports push mode scheduling. If the following -conditions are met, it also supports pull mode scheduling: - - * The format is set to `gst::Format::Bytes` (default). - * `BaseSrcClass.is_seekable`() returns `true`. - -If all the conditions are met for operating in pull mode, `BaseSrc` is -automatically seekable in push mode as well. The following conditions must -be met to make the element seekable in push mode when the format is not -`gst::Format::Bytes`: - -* `BaseSrcClass.is_seekable`() returns `true`. -* `BaseSrcClass.query`() can convert all supported seek formats to the - internal format as set with `BaseSrcExt::set_format`. -* `BaseSrcClass.do_seek`() is implemented, performs the seek and returns - `true`. - -When the element does not meet the requirements to operate in pull mode, the -offset and length in the `BaseSrcClass.create`() method should be ignored. -It is recommended to subclass `PushSrc` instead, in this situation. If the -element can operate in pull mode but only with specific offsets and -lengths, it is allowed to generate an error when the wrong values are passed -to the `BaseSrcClass.create`() function. - -`BaseSrc` has support for live sources. Live sources are sources that when -paused discard data, such as audio or video capture devices. A typical live -source also produces data at a fixed rate and thus provides a clock to publish -this rate. -Use `BaseSrcExt::set_live` to activate the live source mode. - -A live source does not produce data in the PAUSED state. This means that the -`BaseSrcClass.create`() method will not be called in PAUSED but only in -PLAYING. To signal the pipeline that the element will not produce data, the -return value from the READY to PAUSED state will be -`gst::StateChangeReturn::NoPreroll`. - -A typical live source will timestamp the buffers it creates with the -current running time of the pipeline. This is one reason why a live source -can only produce data in the PLAYING state, when the clock is actually -distributed and running. - -Live sources that synchronize and block on the clock (an audio source, for -example) can use `BaseSrc::wait_playing` when the -`BaseSrcClass.create`() function was interrupted by a state change to -PAUSED. - -The `BaseSrcClass.get_times`() method can be used to implement pseudo-live -sources. It only makes sense to implement the `BaseSrcClass.get_times`() -function if the source is a live source. The `BaseSrcClass.get_times`() -function should return timestamps starting from 0, as if it were a non-live -source. The base class will make sure that the timestamps are transformed -into the current running_time. The base source will then wait for the -calculated running_time before pushing out the buffer. - -For live sources, the base class will by default report a latency of 0. -For pseudo live sources, the base class will by default measure the difference -between the first buffer timestamp and the start time of get_times and will -report this value as the latency. -Subclasses should override the query function when this behaviour is not -acceptable. - -There is only support in `BaseSrc` for exactly one source pad, which -should be named "src". A source implementation (subclass of `BaseSrc`) -should install a pad template in its class_init function, like so: - -```C -static void -my_element_class_init (GstMyElementClass *klass) -{ - GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass); - // srctemplate should be a #GstStaticPadTemplate with direction - // %GST_PAD_SRC and name "src" - gst_element_class_add_static_pad_template (gstelement_class, &srctemplate); - - gst_element_class_set_static_metadata (gstelement_class, - "Source name", - "Source", - "My Source element", - "The author "); -} -``` - -## Controlled shutdown of live sources in applications - -Applications that record from a live source may want to stop recording -in a controlled way, so that the recording is stopped, but the data -already in the pipeline is processed to the end (remember that many live -sources would go on recording forever otherwise). For that to happen the -application needs to make the source stop recording and send an EOS -event down the pipeline. The application would then wait for an -EOS message posted on the pipeline's bus to know when all data has -been processed and the pipeline can safely be stopped. - -An application may send an EOS event to a source element to make it -perform the EOS logic (send EOS event downstream or post a -`gst::MessageType::SegmentDone` on the bus). This can typically be done -with the `gst::ElementExt::send_event` function on the element or its parent bin. - -After the EOS has been sent to the element, the application should wait for -an EOS message to be posted on the pipeline's bus. Once this EOS message is -received, it may safely shut down the entire pipeline. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`BaseSrcExt`](trait@crate::BaseSrcExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`BaseSrcExtManual`](trait@crate::BaseSrcExtManual) - -Trait containing all `BaseSrc` methods. - -# Implementors - -[`BaseSrc`](struct@crate::BaseSrc), [`PushSrc`](struct@crate::PushSrc) - -Lets `BaseSrc` sub-classes to know the memory `allocator` -used by the base class and its `params`. - -Unref the `allocator` after usage. -## `allocator` -the `gst::Allocator` -used -## `params` -the `gst::AllocationParams` of `allocator` - -Get the number of bytes that `self` will push out with each buffer. - -# Returns - -the number of bytes pushed with each buffer. - - -# Returns - -the instance of the `gst::BufferPool` used -by the src; unref it after usage. - -Query if `self` timestamps outgoing buffers based on the current running_time. - -# Returns - -`true` if the base class will automatically timestamp outgoing buffers. - -Get the current async behaviour of `self`. See also `BaseSrcExt::set_async`. - -# Returns - -`true` if `self` is operating in async mode. - -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 `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 -configured with `BaseSrcExt::set_format` - -# Deprecated since 1.18 - -Use `BaseSrc::new_segment` -## `start` -The new start value for the segment -## `stop` -Stop value for the new segment -## `time` -The new time value for the start of the new segment - -# Returns - -`true` if preparation of the seamless segment succeeded. - -Prepare a new segment for emission downstream. This function must -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 `segment` must be identical with the current format -of the source, as configured with `BaseSrcExt::set_format`. - -The format of `self` must not be `gst::Format::Undefined` and the format -should be configured via `BaseSrcExt::set_format` before calling this method. - -Feature: `v1_18` - -## `segment` -a pointer to a `gst::Segment` - -# Returns - -`true` if preparation of new segment succeeded. - -Query the source for the latency parameters. `live` will be `true` when `self` is -configured as a live source. `min_latency` and `max_latency` will be set -to the difference between the running time and the timestamp of the first -buffer. - -This function is mostly used by subclasses. -## `live` -if the source is live -## `min_latency` -the min latency of the source -## `max_latency` -the max latency of the source - -# Returns - -`true` if the query succeeded. - -Configure async behaviour in `self`, no state change will block. The open, -close, start, stop, play and pause virtual methods will be executed in a -different thread and are thus allowed to perform blocking operations. Any -blocking operation should be unblocked with the unlock vmethod. -## `async_` -new async mode - -If `automatic_eos` is `true`, `self` will automatically go EOS if a buffer -after the total size is returned. By default this is `true` but sources -that can't return an authoritative size and only know that they're EOS -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 `BaseSrcClass.create`() implementation -returns `gst::FlowReturn::Eos`. -## `automatic_eos` -automatic eos - -Set the number of bytes that `self` will push out with each buffer. When -`blocksize` is set to -1, a default length will be used. -## `blocksize` -the new blocksize in bytes - -Set new caps on the basesrc source pad. -## `caps` -a `gst::Caps` - -# Returns - -`true` if the caps could be set - -Configure `self` to automatically timestamp outgoing buffers based on the -current running_time of the pipeline. This property is mostly useful for live -sources. -## `timestamp` -enable or disable timestamping - -If not `dynamic`, size is only updated when needed, such as when trying to -read past current tracked size. Otherwise, size is checked for upon each -read. -## `dynamic` -new dynamic size mode - -Sets the default format of the source. This will be the format used -for sending SEGMENT events and for performing seeks. - -If a format of GST_FORMAT_BYTES is set, the element will be able to -operate in pull mode if the `BaseSrcClass.is_seekable`() returns `true`. - -This function must only be called in states < `gst::State::Paused`. -## `format` -the format to use - -If the element listens to a live source, `live` should -be set to `true`. - -A live source will not produce data in the PAUSED state and -will therefore not be able to participate in the PREROLL phase -of a pipeline. To signal this fact to the application and the -pipeline, the state change return value of the live source will -be GST_STATE_CHANGE_NO_PREROLL. -## `live` -new live-mode - -Complete an asynchronous start operation. When the subclass overrides the -start method, it should call `BaseSrc::start_complete` when the start -operation completes either from the same thread or from an asynchronous -helper thread. -## `ret` -a `gst::FlowReturn` - -Wait until the start operation completes. - -# Returns - -a `gst::FlowReturn`. - -Subclasses can call this from their create virtual method implementation -to submit a buffer list to be pushed out later. This is useful in -cases where the create function wants to produce multiple buffers to be -pushed out in one go in form of a `gst::BufferList`, which can reduce overhead -drastically, especially for packetised inputs (for data streams where -the packetisation/chunking is not important it is usually more efficient -to return larger buffers instead). - -Subclasses that use this function from their create function must return -`gst::FlowReturn::Ok` and no buffer from their create virtual method implementation. -If a buffer is returned after a buffer list has also been submitted via this -function the behaviour is undefined. - -Subclasses must only call this function once per create function call and -subclasses must only call this function when the source operates in push -mode. - -Feature: `v1_14` - -## `buffer_list` -a `gst::BufferList` - -If the `BaseSrcClass.create`() method performs its own synchronisation -against the clock it must unblock when going from PLAYING to the PAUSED state -and call this method before continuing to produce the remaining data. - -This function will block until a state change to PLAYING happens (in which -case this function returns `gst::FlowReturn::Ok`) or the processing must be stopped due -to a state change to READY or a FLUSH event (in which case this function -returns `gst::FlowReturn::Flushing`). - -# Returns - -`gst::FlowReturn::Ok` if `self` is PLAYING and processing can -continue. Any other return value should be returned from the create vmethod. - -This base class is for filter elements that process data. Elements -that are suitable for implementation using `BaseTransform` are ones -where the size and caps of the output is known entirely from the input -caps and buffer sizes. These include elements that directly transform -one buffer into another, modify the contents of a buffer in-place, as -well as elements that collate multiple input buffers into one output buffer, -or that expand one input buffer into multiple output buffers. See below -for more concrete use cases. - -It provides for: - -* one sinkpad and one srcpad -* Possible formats on sink and source pad implemented - with custom transform_caps function. By default uses - same format on sink and source. - -* Handles state changes -* Does flushing -* Push mode -* Pull mode if the sub-class transform can operate on arbitrary data - -# Use Cases - -## Passthrough mode - - * Element has no interest in modifying the buffer. It may want to inspect it, - in which case the element should have a transform_ip function. If there - is no transform_ip function in passthrough mode, the buffer is pushed - intact. - - * The `BaseTransformClass.passthrough_on_same_caps` variable - will automatically set/unset passthrough based on whether the - element negotiates the same caps on both pads. - - * `BaseTransformClass.passthrough_on_same_caps` on an element that - doesn't implement a transform_caps function is useful for elements that - only inspect data (such as level) - - * Example elements - - * Level - * Videoscale, audioconvert, videoconvert, audioresample in certain modes. - -## Modifications in-place - input buffer and output buffer are the same thing. - -* The element must implement a transform_ip function. -* Output buffer size must <= input buffer size -* If the always_in_place flag is set, non-writable buffers will be copied - and passed to the transform_ip function, otherwise a new buffer will be - created and the transform function called. - -* Incoming writable buffers will be passed to the transform_ip function - immediately. -* only implementing transform_ip and not transform implies always_in_place = `true` - - * Example elements: - * Volume - * Audioconvert in certain modes (signed/unsigned conversion) - * videoconvert in certain modes (endianness swapping) - -## Modifications only to the caps/metadata of a buffer - -* The element does not require writable data, but non-writable buffers - should be subbuffered so that the meta-information can be replaced. - -* Elements wishing to operate in this mode should replace the - prepare_output_buffer method to create subbuffers of the input buffer - and set always_in_place to `true` - -* Example elements - * Capsfilter when setting caps on outgoing buffers that have - none. - * identity when it is going to re-timestamp buffers by - datarate. - -## Normal mode - * always_in_place flag is not set, or there is no transform_ip function - * Element will receive an input buffer and output buffer to operate on. - * Output buffer is allocated by calling the prepare_output_buffer function. - * Example elements: - * Videoscale, videoconvert, audioconvert when doing - scaling/conversions - -## Special output buffer allocations - * Elements which need to do special allocation of their output buffers - beyond allocating output buffers via the negotiated allocator or - buffer pool should implement the prepare_output_buffer method. - - * Example elements: - * efence - -# Sub-class settable flags on GstBaseTransform - -* passthrough - - * Implies that in the current configuration, the sub-class is not interested in modifying the buffers. - * Elements which are always in passthrough mode whenever the same caps has been negotiated on both pads can set the class variable passthrough_on_same_caps to have this behaviour automatically. - -* always_in_place - * Determines whether a non-writable buffer will be copied before passing - to the transform_ip function. - - * Implied `true` if no transform function is implemented. - * Implied `false` if ONLY transform function is implemented. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`BaseTransformExt`](trait@crate::BaseTransformExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`BaseTransformExtManual`](trait@crate::BaseTransformExtManual) - -Trait containing all `BaseTransform` methods. - -# Implementors - -[`BaseTransform`](struct@crate::BaseTransform) - -Lets `BaseTransform` sub-classes know the memory `allocator` -used by the base class and its `params`. - -Unref the `allocator` after use. -## `allocator` -the `gst::Allocator` -used -## `params` -the `gst::AllocationParams` of `allocator` - - -# Returns - -the instance of the `gst::BufferPool` used -by `self`; free it after use - -See if `self` is configured as a in_place transform. - -# Returns - -`true` if the transform is configured in in_place mode. - -MT safe. - -See if `self` is configured as a passthrough transform. - -# Returns - -`true` if the transform is configured in passthrough mode. - -MT safe. - -Queries if the transform will handle QoS. - -# Returns - -`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 -influence the input format. - -Instructs `self` to renegotiate a new downstream transform on the next -buffer. This function is typically called after properties on the transform -were set that influence the output format. - -If `gap_aware` is `false` (the default), output buffers will have the -`gst::BufferFlags::Gap` flag unset. - -If set to `true`, the element must handle output buffers with this flag set -correctly, i.e. it can assume that the buffer contains neutral data but must -unset the flag if the output is no neutral data. - -MT safe. -## `gap_aware` -New state - -Determines whether a non-writable buffer will be copied before passing -to the transform_ip function. - - * Always `true` if no transform function is implemented. - * Always `false` if ONLY transform function is implemented. - -MT safe. -## `in_place` -Boolean value indicating that we would like to operate -on in_place buffers. - -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 or generate_output method. - -MT safe. -## `passthrough` -boolean indicating passthrough mode. - -If `prefer_passthrough` is `true` (the default), `self` will check and -prefer passthrough caps from the list of caps returned by the -transform_caps vmethod. - -If set to `false`, the element must order the caps returned from the -transform_caps function in such a way that the preferred format is -first in the list. This can be interesting for transforms that can do -passthrough transforms but prefer to do something else, like a -capsfilter. - -MT safe. -## `prefer_passthrough` -New state - -Enable or disable QoS handling in the transform. - -MT safe. -## `enabled` -new state - -Set the QoS parameters in the transform. This function is called internally -when a QOS event is received but subclasses can provide custom information -when needed. - -MT safe. -## `proportion` -the proportion -## `diff` -the diff against the clock -## `timestamp` -the timestamp of the buffer generating the QoS expressed in -running_time. - -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 -buffer. -## `updated_caps` -An updated version of the srcpad caps to be pushed -downstream - -# Returns - -`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 -the different `gst::FlowReturn` for those pads. - -`FlowCombiner` works by using the last `gst::FlowReturn` for all `gst::Pad` -it has in its list and computes the combined return value and provides -it to the caller. - -To add a new pad to the `FlowCombiner` use `FlowCombiner::add_pad`. -The new `gst::Pad` is stored with a default value of `gst::FlowReturn::Ok`. - -In case you want a `gst::Pad` to be removed, use `FlowCombiner::remove_pad`. - -Please be aware that this struct isn't thread safe as its designed to be - used by demuxers, those usually will have a single thread operating it. - -These functions will take refs on the passed `gst::Pad`s. - -Aside from reducing the user's code size, the main advantage of using this -helper struct is to follow the standard rules for `gst::FlowReturn` combination. -These rules are: - -* `gst::FlowReturn::Eos`: only if all returns are EOS too -* `gst::FlowReturn::NotLinked`: only if all returns are NOT_LINKED too -* `gst::FlowReturn::Error` or below: if at least one returns an error return -* `gst::FlowReturn::NotNegotiated`: if at least one returns a not-negotiated return -* `gst::FlowReturn::Flushing`: if at least one returns flushing -* `gst::FlowReturn::Ok`: otherwise - -`gst::FlowReturn::Error` or below, GST_FLOW_NOT_NEGOTIATED and GST_FLOW_FLUSHING are -returned immediately from the `FlowCombiner::update_flow` function. - -Creates a new `FlowCombiner`, use `FlowCombiner::free` to free it. - -# Returns - -A new `FlowCombiner` - -Adds a new `gst::Pad` to the `FlowCombiner`. -## `pad` -the `gst::Pad` that is being added - -Removes all pads from a `FlowCombiner` and resets it to its initial state. - -Frees a `FlowCombiner` struct and all its internal data. - -Increments the reference count on the `FlowCombiner`. - -Feature: `v1_12_1` - - -# Returns - -the `FlowCombiner`. - -Removes a `gst::Pad` from the `FlowCombiner`. -## `pad` -the `gst::Pad` to remove - -Reset flow combiner and all pads to their initial state without removing pads. - -Decrements the reference count on the `FlowCombiner`. - -Feature: `v1_12_1` - - -Computes the combined flow return for the pads in it. - -The `gst::FlowReturn` parameter should be the last flow return update for a pad -in this `FlowCombiner`. It will use this value to be able to shortcut some -combinations and avoid looking over all pads again. e.g. The last combined -return is the same as the latest obtained `gst::FlowReturn`. -## `fret` -the latest `gst::FlowReturn` received for a pad in this `FlowCombiner` - -# Returns - -The combined `gst::FlowReturn` - -Sets the provided pad's last flow return to provided value and computes -the combined flow return for the pads in it. - -The `gst::FlowReturn` parameter should be the last flow return update for a pad -in this `FlowCombiner`. It will use this value to be able to shortcut some -combinations and avoid looking over all pads again. e.g. The last combined -return is the same as the latest obtained `gst::FlowReturn`. -## `pad` -the `gst::Pad` whose `gst::FlowReturn` to update -## `fret` -the latest `gst::FlowReturn` received for a pad in this `FlowCombiner` - -# Returns - -The combined `gst::FlowReturn` - -This class is mostly useful for elements that cannot do -random access, or at least very slowly. The source usually -prefers to push out a fixed size buffer. - -Subclasses usually operate in a format that is different from the -default GST_FORMAT_BYTES format of `BaseSrc`. - -Classes extending this base class will usually be scheduled -in a push based mode. If the peer accepts to operate without -offsets and within the limits of the allowed block size, this -class can operate in getrange based mode automatically. To make -this possible, the subclass should implement and override the -SCHEDULING query. - -The subclass should extend the methods from the baseclass in -addition to the ::create method. - -Seeking, flushing, scheduling and sync is all handled by this -base class. - -# Implements - -[`BaseSrcExt`](trait@crate::BaseSrcExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`BaseSrcExtManual`](trait@crate::BaseSrcExtManual) diff --git a/docs/gstreamer-check/docs.md b/docs/gstreamer-check/docs.md deleted file mode 100644 index d9d7a65b1..000000000 --- a/docs/gstreamer-check/docs.md +++ /dev/null @@ -1,1356 +0,0 @@ - - -`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 [`crate::Harness`] (XXX: @-reference does not belong to Harness!) srcpad. - -MT safe. -## `sinkpad` -a `gst::Pad` to link to the harness srcpad - -Links the specified `gst::Pad` the [`crate::Harness`] (XXX: @-reference does not belong to 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 a `gst::Buffer` from the `glib::AsyncQueue` on the `Harness` sinkpad. The pull -will block until an EOS event is received, or timeout in 60 seconds. -MT safe. - -Feature: `v1_18` - -## `buf` -A `gst::Buffer`, or `None` if EOS or timeout occures - first. - -# Returns - -`true` on success, `false` on timeout. - -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 [`crate::Harness`] (XXX: @-reference does not belong to 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 [`crate::Harness`] (XXX: @-reference does not belong to 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 [`crate::Harness`] (XXX: @-reference does not belong to Harness!) sinkpad caps. - -MT safe. -## `caps` -a `gst::Caps` to set on the harness sinkpad - -Sets the [`crate::Harness`] (XXX: @-reference does not belong to Harness!) sinkpad caps using a string. - -MT safe. -## `str` -a `gchar` describing a `gst::Caps` to set on the harness sinkpad - -Sets the [`crate::Harness`] (XXX: @-reference does not belong to 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 [`crate::Harness`] (XXX: @-reference does not belong to 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 `glib::object::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 [`crate::Harness`] (XXX: @-reference does not belong to 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 [`crate::Harness`] (XXX: @-reference does not belong to 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 -according to the system time, while time for `TestClock` changes only -when `TestClock::set_time` or `TestClock::advance_time` are -called. `TestClock` provides unit tests with the possibility to -precisely advance the time in a deterministic manner, independent of the -system time or any other external factors. - -## Advancing the time of a `TestClock` - - -```C - #include - #include - - GstClock *clock; - GstTestClock *test_clock; - - clock = gst_test_clock_new (); - test_clock = GST_TEST_CLOCK (clock); - GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); - gst_test_clock_advance_time ( test_clock, 1 * GST_SECOND); - GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); - g_usleep (10 * G_USEC_PER_SEC); - GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); - gst_test_clock_set_time (test_clock, 42 * GST_SECOND); - GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); - ... -``` - -`gst::Clock` allows for setting up single shot or periodic clock notifications -as well as waiting for these notifications synchronously (using -`gst::Clock::id_wait`) or asynchronously (using `gst::Clock::id_wait_async` or -`gst::Clock::id_wait_async`). This is used by many GStreamer elements, -among them `GstBaseSrc` and `GstBaseSink`. - -`TestClock` keeps track of these clock notifications. By calling -`TestClock::wait_for_next_pending_id` or -`TestClock::wait_for_multiple_pending_ids` a unit tests may wait for the -next one or several clock notifications to be requested. Additionally unit -tests may release blocked waits in a controlled fashion by calling -`TestClock::process_next_clock_id`. This way a unit test can control the -inaccuracy (jitter) of clock notifications, since the test can decide to -release blocked waits when the clock time has advanced exactly to, or past, -the requested clock notification time. - -There are also interfaces for determining if a notification belongs to a -`TestClock` or not, as well as getting the number of requested clock -notifications so far. - -N.B.: When a unit test waits for a certain amount of clock notifications to -be requested in `TestClock::wait_for_next_pending_id` or -`TestClock::wait_for_multiple_pending_ids` then these functions may block -for a long time. If they block forever then the expected clock notifications -were never requested from `TestClock`, and so the assumptions in the code -of the unit test are wrong. The unit test case runner in gstcheck is -expected to catch these cases either by the default test case timeout or the -one set for the unit test by calling tcase_set_timeout\(\). - -The sample code below assumes that the element under test will delay a -buffer pushed on the source pad by some latency until it arrives on the sink -pad. Moreover it is assumed that the element will at some point call -`gst::Clock::id_wait` to synchronously wait for a specific time. The first -buffer sent will arrive exactly on time only delayed by the latency. The -second buffer will arrive a little late (7ms) due to simulated jitter in the -clock notification. - -## Demonstration of how to work with clock notifications and `TestClock` - - -```C - #include - #include - #include - - GstClockTime latency; - GstElement *element; - GstPad *srcpad; - GstClock *clock; - GstTestClock *test_clock; - GstBuffer buf; - GstClockID pending_id; - GstClockID processed_id; - - latency = 42 * GST_MSECOND; - element = create_element (latency, ...); - srcpad = get_source_pad (element); - - clock = gst_test_clock_new (); - test_clock = GST_TEST_CLOCK (clock); - gst_element_set_clock (element, clock); - - GST_INFO ("Set time, create and push the first buffer\n"); - gst_test_clock_set_time (test_clock, 0); - buf = create_test_buffer (gst_clock_get_time (clock), ...); - gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK); - - GST_INFO ("Block until element is waiting for a clock notification\n"); - gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id); - GST_INFO ("Advance to the requested time of the clock notification\n"); - gst_test_clock_advance_time (test_clock, latency); - GST_INFO ("Release the next blocking wait and make sure it is the one from element\n"); - processed_id = gst_test_clock_process_next_clock_id (test_clock); - g_assert (processed_id == pending_id); - g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK); - gst_clock_id_unref (pending_id); - gst_clock_id_unref (processed_id); - - GST_INFO ("Validate that element produced an output buffer and check its timestamp\n"); - g_assert_cmpint (get_number_of_output_buffer (...), ==, 1); - buf = get_buffer_pushed_by_element (element, ...); - g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==, latency); - gst_buffer_unref (buf); - GST_INFO ("Check that element does not wait for any clock notification\n"); - g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL)); - - GST_INFO ("Set time, create and push the second buffer\n"); - gst_test_clock_advance_time (test_clock, 10 * GST_SECOND); - buf = create_test_buffer (gst_clock_get_time (clock), ...); - gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK); - - GST_INFO ("Block until element is waiting for a new clock notification\n"); - (gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id); - GST_INFO ("Advance past 7ms beyond the requested time of the clock notification\n"); - gst_test_clock_advance_time (test_clock, latency + 7 * GST_MSECOND); - GST_INFO ("Release the next blocking wait and make sure it is the one from element\n"); - processed_id = gst_test_clock_process_next_clock_id (test_clock); - g_assert (processed_id == pending_id); - g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK); - gst_clock_id_unref (pending_id); - gst_clock_id_unref (processed_id); - - GST_INFO ("Validate that element produced an output buffer and check its timestamp\n"); - g_assert_cmpint (get_number_of_output_buffer (...), ==, 1); - buf = get_buffer_pushed_by_element (element, ...); - g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==, - 10 * GST_SECOND + latency + 7 * GST_MSECOND); - gst_buffer_unref (buf); - GST_INFO ("Check that element does not wait for any clock notification\n"); - g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL)); - ... -``` - -Since `TestClock` is only supposed to be used in unit tests it calls -`g_assert`, `g_assert_cmpint` or `g_assert_cmpuint` to validate all function -arguments. This will highlight any issues with the unit test code itself. - -# Implements - -[`trait@gst::ClockExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Creates a new test clock with its time set to zero. - -MT safe. - -# Returns - -a `TestClock` cast to `gst::Clock`. - -Creates a new test clock with its time set to the specified time. - -MT safe. -## `start_time` -a `gst::ClockTime` set to the desired start time of the clock. - -# Returns - -a `TestClock` cast to `gst::Clock`. - -Finds the latest time inside the list. - -MT safe. -## `pending_list` -List - of of pending `GstClockIDs` - -Advances the time of the `self` by the amount given by `delta`. The -time of `self` is monotonically increasing, therefore providing a -`delta` which is negative or zero is a programming error. - -MT safe. -## `delta` -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, 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. - -# Returns - -`true` if the crank was successful, `false` otherwise. - -MT safe. - -Retrieve the requested time for the next pending clock notification. - -MT safe. - -# Returns - -a `gst::ClockTime` set to the time of the next pending clock -notification. If no clock notifications have been requested -`GST_CLOCK_TIME_NONE` will be returned. - -Checks whether `self` was requested to provide the clock notification -given by `id`. - -MT safe. -## `id` -a `gst::ClockID` clock notification - -# Returns - -`true` if the clock has been asked to provide the given clock -notification, `false` otherwise. - -Determine the number of pending clock notifications that have been -requested from the `self`. - -MT safe. - -# Returns - -the number of pending clock notifications. - -Determines if the `pending_id` is the next clock notification scheduled to -be triggered given the current time of the `self`. - -MT safe. -## `pending_id` -a `gst::ClockID` clock -notification to look for - -# Returns - -`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. - -MT safe. -## `pending_list` -List - of pending `GstClockIDs` - -MT safe. - -# Returns - -a `gst::ClockID` containing the next pending clock -notification. - -Sets the time of `self` to the time given by `new_time`. The time of -`self` is monotonically increasing, therefore providing a `new_time` -which is earlier or equal to the time of the clock as given by -`gst::ClockExt::get_time` is a programming error. - -MT safe. -## `new_time` -a `gst::ClockTime` later than that returned by `gst::ClockExt::get_time` - -Blocks until at least `count` clock notifications have been requested from -`self`, or the timeout expires. - -MT safe. - -Feature: `v1_16` - -## `count` -the number of pending clock notifications to wait for -## `timeout_ms` -the timeout in milliseconds -## `pending_list` -Address - of a `glib::List` pointer variable to store the list of pending `GstClockIDs` - that expired, or `None` - -# 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) - -Blocks until at least `count` clock notifications have been requested from -`self`. There is no timeout for this wait, see the main description of -`TestClock`. - -MT safe. -## `count` -the number of pending clock notifications to wait for -## `pending_list` -Address - of a `glib::List` pointer variable to store the list of pending `GstClockIDs` - that expired, or `None` - -Waits until a clock notification is requested from `self`. There is no -timeout for this wait, see the main description of `TestClock`. A reference -to the pending clock notification is stored in `pending_id`. - -MT safe. -## `pending_id` -`gst::ClockID` -with information about the pending clock notification - -Blocks until at least `count` clock notifications have been requested from -`self`. There is no timeout for this wait, see the main description of -`TestClock`. - -# Deprecated - -use `TestClock::wait_for_multiple_pending_ids` instead. -## `count` -the number of pending clock notifications to wait for - -When a `TestClock` is constructed it will have a certain start time set. -If the clock was created using `TestClock::new_with_start_time` then -this property contains the value of the `start_time` argument. If -`TestClock::new` was called the clock started at time zero, and thus -this property contains the value 0. - -When a `TestClock` is constructed it will have a certain start time set. -If the clock was created using `TestClock::new_with_start_time` then -this property contains the value of the `start_time` argument. If -`TestClock::new` was called the clock started at time zero, and thus -this property contains the value 0. diff --git a/docs/gstreamer-controller/docs.md b/docs/gstreamer-controller/docs.md deleted file mode 100644 index 342d55466..000000000 --- a/docs/gstreamer-controller/docs.md +++ /dev/null @@ -1,339 +0,0 @@ - - -A value mapping object that attaches multiple control sources to a guint -gobject properties representing a color. A control value of 0.0 will turn the -color component off and a value of 1.0 will be the color level. - -# Implements - -[`ARGBControlBindingExt`](trait@crate::ARGBControlBindingExt), [`trait@gst::ControlBindingExt`], [`trait@gst::ObjectExt`] - -Trait containing all `ARGBControlBinding` methods. - -# Implementors - -[`ARGBControlBinding`](struct@crate::ARGBControlBinding) - -Create a new control-binding that attaches the given `gst::ControlSource` to the -`glib::object::Object` property. -## `object` -the object of the property -## `property_name` -the property-name to attach the control source -## `cs_a` -the control source for the alpha channel -## `cs_r` -the control source for the red channel -## `cs_g` -the control source for the green channel -## `cs_b` -the control source for the blue channel - -# Returns - -the new `ARGBControlBinding` - -An internal structure for value+time and various temporary -values used for interpolation. This "inherits" from -GstTimedValue. - -Copies a `ControlPoint` - -# Returns - -A copy of `self` - -Frees all data allocated by a `ControlPoint` instance. - -A value mapping object that attaches control sources to gobject properties. It -will map the control values directly to the target property range. If a -non-absolute direct control binding is used, the value range [0.0 ... 1.0] -is mapped to full target property range, and all values outside the range -will be clipped. An absolute control binding will not do any value -transformations. - -# Implements - -[`DirectControlBindingExt`](trait@crate::DirectControlBindingExt), [`trait@gst::ControlBindingExt`], [`trait@gst::ObjectExt`] - -Trait containing all `DirectControlBinding` methods. - -# Implementors - -[`DirectControlBinding`](struct@crate::DirectControlBinding) - -Create a new control-binding that attaches the `gst::ControlSource` to the -`glib::object::Object` property. It will map the control source range [0.0 ... 1.0] to -the full target property range, and clip all values outside this range. -## `object` -the object of the property -## `property_name` -the property-name to attach the control source -## `cs` -the control source - -# Returns - -the new `DirectControlBinding` - -Create a new control-binding that attaches the `gst::ControlSource` to the -`glib::object::Object` property. It will directly map the control source values to the -target property range without any transformations. -## `object` -the object of the property -## `property_name` -the property-name to attach the control source -## `cs` -the control source - -# Returns - -the new `DirectControlBinding` - -`InterpolationControlSource` is a `gst::ControlSource`, that interpolates values between user-given -control points. It supports several interpolation modes and property types. - -To use `InterpolationControlSource` get a new instance by calling -`InterpolationControlSource::new`, bind it to a `glib::object::ParamSpec` and set some -control points by calling `TimedValueControlSourceExt::set`. - -All functions are MT-safe. - -# Implements - -[`InterpolationControlSourceExt`](trait@crate::InterpolationControlSourceExt), [`TimedValueControlSourceExt`](trait@crate::TimedValueControlSourceExt), [`trait@gst::ControlSourceExt`], [`trait@gst::ObjectExt`] - -Trait containing all `InterpolationControlSource` methods. - -# Implementors - -[`InterpolationControlSource`](struct@crate::InterpolationControlSource) - -This returns a new, unbound `InterpolationControlSource`. - -# Returns - -a new, unbound `InterpolationControlSource`. - -The various interpolation modes available. - -steps-like interpolation, default - -linear interpolation - -cubic interpolation (natural), may overshoot - the min or max values set by the control point, but is more 'curvy' - -monotonic cubic interpolation, will not - produce any values outside of the min-max range set by the control points - (Since: 1.8) - -`LFOControlSource` is a `gst::ControlSource`, that provides several periodic -waveforms as control values. - -To use `LFOControlSource` get a new instance by calling -`LFOControlSource::new`, bind it to a `glib::object::ParamSpec` and set the relevant -properties. - -All functions are MT-safe. - -# Implements - -[`LFOControlSourceExt`](trait@crate::LFOControlSourceExt), [`trait@gst::ControlSourceExt`], [`trait@gst::ObjectExt`] - -Trait containing all `LFOControlSource` methods. - -# Implementors - -[`LFOControlSource`](struct@crate::LFOControlSource) - -This returns a new, unbound `LFOControlSource`. - -# Returns - -a new, unbound `LFOControlSource`. - -Specifies the amplitude for the waveform of this `LFOControlSource`. - -Specifies the amplitude for the waveform of this `LFOControlSource`. - -Specifies the frequency that should be used for the waveform -of this `LFOControlSource`. It should be large enough -so that the period is longer than one nanosecond. - -Specifies the frequency that should be used for the waveform -of this `LFOControlSource`. It should be large enough -so that the period is longer than one nanosecond. - -Specifies the value offset for the waveform of this `LFOControlSource`. - -Specifies the value offset for the waveform of this `LFOControlSource`. - -Specifies the timeshift to the right that should be used for the waveform -of this `LFOControlSource` in nanoseconds. - -To get a n nanosecond shift to the left use -"(GST_SECOND / frequency) - n". - -Specifies the timeshift to the right that should be used for the waveform -of this `LFOControlSource` in nanoseconds. - -To get a n nanosecond shift to the left use -"(GST_SECOND / frequency) - n". - -Specifies the waveform that should be used for this `LFOControlSource`. - -Specifies the waveform that should be used for this `LFOControlSource`. - -The various waveform modes available. - -sine waveform - -square waveform - -saw waveform - -reverse saw waveform - -triangle waveform - -A `gst::ControlBinding` that forwards requests to another `gst::ControlBinding` - -Feature: `v1_12` - -# Implements - -[`trait@gst::ControlBindingExt`], [`trait@gst::ObjectExt`] - -`ProxyControlBinding` forwards all access to data or `sync_values()` -requests from `property_name` on `object` to the control binding at -`ref_property_name` on `ref_object`. - -Feature: `v1_12` - -## `object` -a `gst::Object` -## `property_name` -the property name in `object` to control -## `ref_object` -a `gst::Object` to forward all - `gst::ControlBinding` requests to -## `ref_property_name` -the property_name in `ref_object` to control - -# Returns - -a new `gst::ControlBinding` that proxies the control interface between -properties on different `gst::Object`'s - -Base class for `gst::ControlSource` that use time-stamped values. - -When overriding bind, chain up first to give this bind implementation a -chance to setup things. - -All functions are MT-safe. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`TimedValueControlSourceExt`](trait@crate::TimedValueControlSourceExt), [`trait@gst::ControlSourceExt`], [`trait@gst::ObjectExt`] - -Trait containing all `TimedValueControlSource` methods. - -# Implementors - -[`InterpolationControlSource`](struct@crate::InterpolationControlSource), [`TimedValueControlSource`](struct@crate::TimedValueControlSource), [`TriggerControlSource`](struct@crate::TriggerControlSource) - -Find last value before given timestamp in control point list. -If all values in the control point list come after the given -timestamp or no values exist, `None` is returned. - -For use in control source implementations. -## `timestamp` -the search key - -# Returns - -the found `glib::SequenceIter` or `None` - -Returns a read-only copy of the list of `gst::TimedValue` for the given property. -Free the list after done with it. - -# Returns - -a copy -of the list, or `None` if the property isn't handled by the controller - -Get the number of control points that are set. - -# Returns - -the number of control points that are set. - -Set the value of given controller-handled property at a certain time. -## `timestamp` -the time the control-change is scheduled for -## `value` -the control-value - -# Returns - -FALSE if the values couldn't be set, TRUE otherwise. - -Sets multiple timed values at once. -## `timedvalues` -a list -with `gst::TimedValue` items - -# Returns - -FALSE if the values couldn't be set, TRUE otherwise. - -Used to remove the value of given controller-handled property at a certain -time. -## `timestamp` -the time the control-change should be removed from - -# Returns - -FALSE if the value couldn't be unset (i.e. not found, TRUE otherwise. - -Used to remove all time-stamped values of given controller-handled property - -Emitted right after the new value has been added to `self_` -## `timed_value` -The newly added `gst::TimedValue` - -Emitted right after the new value has been set on `timed_signals` -## `timed_value` -The `gst::TimedValue` where the value changed - -Emitted when `timed_value` is removed from `self_` -## `timed_value` -The removed `gst::TimedValue` - -`TriggerControlSource` is a `gst::ControlSource`, that returns values from user-given -control points. It allows for a tolerance on the time-stamps. - -To use `TriggerControlSource` get a new instance by calling -`TriggerControlSource::new`, bind it to a `glib::object::ParamSpec` and set some -control points by calling `TimedValueControlSourceExt::set`. - -All functions are MT-safe. - -# Implements - -[`TriggerControlSourceExt`](trait@crate::TriggerControlSourceExt), [`TimedValueControlSourceExt`](trait@crate::TimedValueControlSourceExt), [`trait@gst::ControlSourceExt`], [`trait@gst::ObjectExt`] - -Trait containing all `TriggerControlSource` methods. - -# Implementors - -[`TriggerControlSource`](struct@crate::TriggerControlSource) - -This returns a new, unbound `TriggerControlSource`. - -# Returns - -a new, unbound `TriggerControlSource`. diff --git a/docs/gstreamer-editing-services/docs.md b/docs/gstreamer-editing-services/docs.md deleted file mode 100644 index b25d9bde9..000000000 --- a/docs/gstreamer-editing-services/docs.md +++ /dev/null @@ -1,5177 +0,0 @@ - - -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`. - -``` c -GESAsset *effect_asset; -GESEffect *effect; - -// You create an asset for an effect -effect_asset = ges_asset_request (GES_TYPE_EFFECT, "agingtv", NULL); - -// And now you can extract an instance of GESEffect from that asset -effect = GES_EFFECT (ges_asset_extract (effect_asset)); - -``` - -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. - -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. - -For example, to display information about the supported formats, you -could do the following: - -```text - GList *formatter_assets, *tmp; - - // List all the transitions - formatter_assets = ges_list_assets (GES_TYPE_FORMATTER); - - // 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)); - } - - g_list_free (transition_assets); - -``` - -## 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 - -[`AssetExt`](trait@crate::AssetExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `Asset` methods. - -# Implementors - -[`Asset`](struct@crate::Asset), [`Project`](struct@crate::Project) - -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. - -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 `Asset:extractable-type` of the asset that -needs reloading -## `id` -The `Asset:id` of the asset asset that needs -reloading - -# Returns - -`true` if the specified asset exists in the cache and could be -marked for reloading. - -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. - -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 `Asset:extractable-type` of the asset -## `id` -The `Asset:id` of the asset - -# Returns - -A reference to the requested -asset, or `None` if an error occurred. - -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`. - -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. - -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: -``` c -// The request callback -static void -asset_loaded_cb (GESAsset * source, GAsyncResult * res, gpointer user_data) -{ - GESAsset *asset; - GError *error = NULL; - - asset = ges_asset_request_finish (res, &error); - if (asset) { - g_print ("The file: %s is usable as a GESUriClip", - ges_asset_get_id (asset)); - } else { - g_print ("The file: %s is *not* usable as a GESUriClip because: %s", - ges_asset_get_id (source), error->message); - } - - gst_object_unref (asset); -} - -// The request: -ges_asset_request_async (GES_TYPE_URI_CLIP, some_uri, NULL, - (GAsyncReadyCallback) asset_loaded_cb, user_data); -``` -## `extractable_type` -The `Asset:extractable-type` of the asset -## `id` -The `Asset:id` of the asset -## `cancellable` -An object to allow cancellation of the -asset request, or `None` to ignore -## `callback` -A function to call when the initialization is finished -## `user_data` -Data to be passed to `callback` - -Fetches an asset requested by `Asset::request_async`, which -finalises the request. -## `res` -The task result to fetch the asset from - -# Returns - -The requested asset, or `None` if an error -occurred. - -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 object, or `None` if an -error occurred. - -Retrieve the error that was set on the asset when it was loaded. - -# Returns - -The error set on `asset`, or -`None` if no error occurred when `asset` was loaded. - -Gets the `Asset:extractable-type` of the asset. - -# Returns - -The extractable type of `self`. - -Gets the `Asset:id` of the asset. - -# Returns - -The ID of `self`. - -Gets the default `Asset:proxy` of the asset. - -# Returns - -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 `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 -that `self` has. - -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` -A new default proxy for `self` - -# Returns - -`true` if `proxy` was successfully set as the default for -`self`. - -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` -An existing proxy of `self` - -# Returns - -`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 `glib::object::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 `glib::object::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 `glib::object::Object::notify` for this property is emitted after -the `Asset:proxy` `glib::object::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`. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`BaseEffectExt`](trait@crate::BaseEffectExt), [`TrackElementExt`](trait@crate::TrackElementExt), [`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -Trait containing all `BaseEffect` methods. - -# Implementors - -[`BaseEffect`](struct@crate::BaseEffect), [`Effect`](struct@crate::Effect) - -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. - - - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`OperationClipExt`](trait@crate::OperationClipExt), [`ClipExt`](trait@crate::ClipExt), [`GESContainerExt`](trait@crate::GESContainerExt), [`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -`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. - -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); -} -``` - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`ClipExt`](trait@crate::ClipExt), [`GESContainerExt`](trait@crate::GESContainerExt), [`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -Trait containing all `Clip` methods. - -# Implementors - -[`Clip`](struct@crate::Clip), [`OperationClip`](struct@crate::OperationClip) - -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` -An asset with `GES_TYPE_TRACK_ELEMENT` as its -`Asset:extractable-type` - -# Returns - -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. - -Feature: `v1_18` - -## `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 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 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` -The track to search in, or `None` to search in -all tracks -## `type_` -The type of track element to search for, or `G_TYPE_NONE` to -match any type - -# Returns - -The element controlled by -`self`, in `track`, and of the given `type_`, or `None` if no such element -could be found. - -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` -The track to search in, or `None` to search in -all tracks -## `track_type` -The track-type of the track element to search for, or -`TrackType::Unknown` to match any track type -## `type_` -The type of track element to search for, or `G_TYPE_NONE` to -match any type - -# Returns - -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. - -Gets the `Clip:layer` of the clip. - -# Returns - -The layer `self` is in, or `None` if -`self` is not in any layer. - -Gets the `Clip:supported-formats` of the clip. - -# Returns - -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. - -Feature: `v1_18` - -## `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 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 effect we want to get the index of - -# Returns - -The index of `effect` in `self`, or -1 if something went wrong. - -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 list of all -`BaseEffect`-s that have been added to `self`. - -See `ClipExt::move_to_layer_full`, which also gives an error. -## `layer` -The new layer - -# Returns - -`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 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 index for `effect` in `self` - -# Returns - -`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`. - -See `ClipExt::split_full`, which also gives an error. -## `position` -The timeline position at which to perform the split - -# Returns - -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. - -Feature: `v1_18` - - -The layer this clip lies in. - -If you want to connect to this property's `glib::object::Object::notify` signal, -you should connect to it with `g_signal_connect_after` since the -signal emission may be stopped internally. - -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 `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. - -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. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`GESContainerExt`](trait@crate::GESContainerExt), [`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -Trait containing all `Container` methods. - -# Implementors - -[`Clip`](struct@crate::Clip), [`Container`](struct@crate::Container), [`Group`](struct@crate::Group) - -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`-s to group - -# Returns - -The container created by merging -`containers`, or `None` if they could not be merged into a single -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 element to add as a child - -# Returns - -`true` if `child` was successfully added to `self`. - -Edits the container within its timeline. - -# Deprecated since 1.18 - -use `TimelineElementExt::edit` instead. -## `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) - -# Returns - -`true` if the edit of `self` completed, `false` on failure. - -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 -`TimelineElement`-s contained in `self`. - -Removes a timeline element from the container. The element will no -longer be controlled by the container. -## `child` -The child to remove - -# Returns - -`true` if `child` was successfully removed from `self`. - -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` -Whether to recursively ungroup `self` - -# Returns - -The list of -new `Container`-s created from the splitting of `self`. - -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 child that was added - -Will be emitted after a child is removed from the container. -## `element` -The child that was removed - -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 working with any edge of an - object. - -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 N sinkpads and one single srcpad. -Apart from `gesaudiomixer` and `gescompositor` which can be used as effects -and where sinkpads will be requested as needed based on the timeline topology -GES will always request at most one sinkpad per effect (when required). - -> Note: GES always adds converters (`audioconvert ! audioresample ! -> audioconvert` for audio effects and `videoconvert` for video effects) to -> make it simpler for end users. - -# Implements - -[`EffectExt`](trait@crate::EffectExt), [`BaseEffectExt`](trait@crate::BaseEffectExt), [`TrackElementExt`](trait@crate::TrackElementExt), [`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -Trait containing all `Effect` methods. - -# Implementors - -[`Effect`](struct@crate::Effect) - -Creates a new `Effect` from the description of the bin. It should be -possible to determine the type of the effect through the element -'klass' metadata of the GstElements that will be created. -In that corner case, you should use: -`Asset::request` (GES_TYPE_EFFECT, "audio your ! bin ! description", NULL); -and extract that asset to be in full control. -## `bin_description` -The gst-launch like bin description of the effect - -# Returns - -a newly created `Effect`, or `None` if something went -wrong. - -The description of the effect bin with a gst-launch-style -pipeline description. - -Example: "videobalance saturation=1.5 hue=+0.5" - -The description of the effect bin with a gst-launch-style -pipeline description. - -Example: "videobalance saturation=1.5 hue=+0.5" - -A `glib::object::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 - -[`ExtractableExt`](trait@crate::ExtractableExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `Extractable` methods. - -# Implementors - -[`BaseEffect`](struct@crate::BaseEffect), [`BaseTransitionClip`](struct@crate::BaseTransitionClip), [`Clip`](struct@crate::Clip), [`Container`](struct@crate::Container), [`Effect`](struct@crate::Effect), [`Extractable`](struct@crate::Extractable), [`Group`](struct@crate::Group), [`Layer`](struct@crate::Layer), [`OperationClip`](struct@crate::OperationClip), [`TimelineElement`](struct@crate::TimelineElement), [`Timeline`](struct@crate::Timeline), [`TrackElement`](struct@crate::TrackElement), [`TransitionClip`](struct@crate::TransitionClip), [`UriClip`](struct@crate::UriClip) - -Get the asset that has been set on the extractable object. - -# Returns - -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 `Asset:id` of some associated `Asset` -that is compatible with `self`'s current state. - -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 - -# Returns - -`true` if `asset` could be successfully set on `self`. - -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 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@crate::GroupExt), [`GESContainerExt`](trait@crate::GESContainerExt), [`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -Trait containing all `Group` methods. - -# Implementors - -[`Group`](struct@crate::Group) - -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. - -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. - -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. - -An overwrite of the `TimelineElement:in-point` property. This has -no meaning for a group and should not be set. - -An overwrite of the `TimelineElement:in-point` property. This has -no meaning for a group and should not be set. - -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: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. - -An overwrite of the `TimelineElement:start` property. For a -`Group`, this is the earliest `TimelineElement:start` time -amongst its children. - -An overwrite of the `TimelineElement:start` property. For a -`Group`, this is the earliest `TimelineElement:start` time -amongst its children. - -`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 - -[`LayerExt`](trait@crate::LayerExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt) - -Trait containing all `Layer` methods. - -# Implementors - -[`Layer`](struct@crate::Layer) - -Creates a new layer. - -# Returns - -A new layer. - -See `LayerExt::add_asset_full`, which also gives an error. -## `asset` -The asset to extract the new clip from -## `start` -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 - -The newly created clip. - -Extracts a new clip from an asset and adds it to the layer with -the given properties. - -Feature: `v1_18` - -## `asset` -The asset to extract the new clip from -## `start` -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 - -The newly created clip. - -See `LayerExt::add_clip_full`, which also gives an error. -## `clip` -The clip to add - -# Returns - -`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`. - -Feature: `v1_18` - -## `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. - -Feature: `v1_18` - -## `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 `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 transitions should be automatically added to -the layer - -Sets the layer to the given priority. See `Layer:priority`. - -# Deprecated since 1.16 - -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 - -Will be emitted whenever the layer is activated or deactivated -for some `Track`. See `LayerExt::set_active_for_tracks`. - -Feature: `v1_18` - -## `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 is added to the layer. -## `clip` -The clip that was added - -Will be emitted after the clip is removed from the layer. -## `clip` -The clip that was removed - -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. - -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 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 committed (with `TimelineExt::commit`) -for the change to be taken into account. - -# Deprecated since 1.16 - -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. - -The priority of the layer in the `Timeline`. 0 is the highest -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 committed (with `TimelineExt::commit`) -for the change to be taken into account. - -# Deprecated since 1.16 - -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. - -Operations are any kind of object that both outputs AND consumes data. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`ClipExt`](trait@crate::ClipExt), [`GESContainerExt`](trait@crate::GESContainerExt), [`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -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 - -[`GESPipelineExt`](trait@crate::GESPipelineExt), [`trait@gst::PipelineExt`], [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Trait containing all `Pipeline` methods. - -# Implementors - -[`Pipeline`](struct@crate::Pipeline) - -Creates a new pipeline. - -# Returns - -The newly created pipeline. - -Gets the `Pipeline:mode` of the pipeline. - -# Returns - -The current mode of `self`. - -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` -Some caps to specifying the desired format, or -`GST_CAPS_ANY` to use the native format - -# Returns - -A sample of `self`'s current image preview in -the format given by `caps`, or `None` if an error prevented fetching the -sample. - -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. - -See `GESPipelineExt::get_thumbnail`. -## `width` -The requested pixel width of the image, or -1 to use the native -size -## `height` -The requested pixel height of the image, or -1 to use the -native size - -# Returns - -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. - -Gets the `Pipeline:audio-sink` of the pipeline. - -# Returns - -The audio sink used by `self` for preview. - -Gets the `Pipeline:video-sink` of the pipeline. - -# Returns - -The video sink used by `self` for preview. - -Sets the `Pipeline:audio-sink` of the pipeline. -## `sink` -A audio sink for `self` to use for preview - -Sets the `Pipeline:video-sink` of the pipeline. -## `sink` -A video sink for `self` to use for preview - -Saves the currently displayed image of the pipeline in preview to the -given location, in the specified dimensions and format. -## `width` -The requested pixel width of the image, or -1 to use the native -size -## `height` -The requested pixel height of the image, or -1 to use the -native size -## `format` -The desired mime type (for example, "image/jpeg") -## `location` -The path to save the thumbnail to - -# Returns - -`true` if `self`'s current image preview was successfully saved -to `location` using the given `format`, `height` and `width`. - -Sets the `Pipeline:mode` of the pipeline. - -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. - -> **NOTE**: [Rendering settings](ges_pipeline_set_render_settings) need to be -> set before setting `mode` to `PipelineFlags::Render` or -> `PipelineFlags::SmartRender`, the call to this method will fail -> otherwise. -## `mode` -The mode to set for `self` - -# Returns - -`true` if the mode of `self` was successfully set to `mode`. - -Specifies encoding setting to be used by the pipeline to render its -`Pipeline:timeline`, and where the result should be written to. - -This method **must** be called before setting the pipeline mode to -`PipelineFlags::Render`. -## `output_uri` -The URI to save the `Pipeline:timeline` rendering -result to -## `profile` -The encoding to use for rendering the `Pipeline:timeline` - -# Returns - -`true` if the settings were successfully set on `self`. - -Takes the given timeline and sets it as the `Pipeline:timeline` for -the pipeline. - -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 for `self` - -# Returns - -`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`. - -The audio sink used for preview. This exposes the -`playsink:audio-sink` property of the internal `playsink`. - -The audio sink used for preview. This exposes the -`playsink:audio-sink` property of the internal `playsink`. - -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. - -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. - -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 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`. - -The video sink used for preview. This exposes the -`playsink:video-sink` property of the internal `playsink`. - -The video sink used for preview. This exposes the -`playsink:video-sink` property of the internal `playsink`. - -The various modes a `Pipeline` can be configured to. - -Output the `Pipeline:timeline`'s -audio to the soundcard - -Output the `Pipeline:timeline`'s -video to the screen - -Output both the `Pipeline:timeline`'s -audio and video to the soundcard and screen (default) - -Render the `Pipeline:timeline` with -forced decoding (the underlying `encodebin` has its -`encodebin:avoid-reencoding` property set to `false`) - -Render the `Pipeline:timeline`, -avoiding decoding/reencoding (the underlying `encodebin` has its -`encodebin:avoid-reencoding` property set to `true`). -> NOTE: Smart rendering can not work in tracks where `Track:mixing` -> is enabled. - -The `Project` is used to control a set of `Asset` and is a -`Asset` with `GES_TYPE_TIMELINE` as `extractable_type` itself. That -means that you can extract `Timeline` from a project as followed: - - -```text - GESProject *project; - GESTimeline *timeline; - - project = ges_project_new ("file:///path/to/a/valid/project/uri"); - - // Here you can connect to the various signal to get more infos about - // what is happening and recover from errors if possible - ... - - timeline = ges_asset_extract (GES_ASSET (project)); -``` - -The `Project` class offers a higher level API to handle `Asset`-s. -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@crate::ProjectExt), [`AssetExt`](trait@crate::AssetExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `Project` methods. - -# Implementors - -[`Project`](struct@crate::Project) - -Creates a new `Project` and sets its uri to `uri` if provided. Note that -if `uri` is not valid or `None`, the uri of the project will then be set -the first time you save the project. If you then save the project to -other locations, it will never be updated again and the first valid URI is -the URI it will keep refering to. -## `uri` -The uri to be set after creating the project. - -# Returns - -A newly created `Project` - -Adds a `Asset` to `self`, the project will keep a reference on -`asset`. -## `asset` -A `Asset` to add to `self` - -# Returns - -`true` if the asset could be added `false` it was already -in the project - -Adds `profile` to the project. It lets you save in what format -the project has been renders and keep a reference to those formats. -Also, those formats will be saves to the project file when possible. -## `profile` -A `gst_pbutils::EncodingProfile` to add to the project. If a profile with -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 -`self` -## `id` -The id of the asset to create and add to `self` -## `extractable_type` -The `glib::Type` of the asset to create - -# Returns - -`true` if the asset started to be added `false` it was already -in the project - -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 -`self` -## `id` -The id of the asset to create and add to `self` -## `extractable_type` -The `glib::Type` of the asset to create - -# Returns - -The newly created `Asset` or `None`. - -## `id` -The id of the asset to retrieve -## `extractable_type` -The extractable_type of the asset -to retrieve from `object` - -# Returns - -The `Asset` with -`id` or `None` if no asset with `id` as an ID - -Get the assets that are being loaded - -# Returns - -A set of loading asset -that will be added to `self`. Note that those Asset are *not* loaded yet, -and thus can not be used - -Retrieve the uri that is currently set on `self` - -# Returns - -a newly allocated string representing uri. - -List all `asset` contained in `self` filtering per extractable_type -as defined by `filter`. It copies the asset and thus will not be updated -in time. -## `filter` -Type of assets to list, `GES_TYPE_EXTRACTABLE` will list -all assets - -# Returns - -The list of -`Asset` the object contains - -Lists the encoding profile that have been set to `self`. The first one -is the latest added. - -# Returns - -The -list of `gst_pbutils::EncodingProfile` used in `self` - -Loads `self` into `timeline` -## `timeline` -A blank timeline to load `self` into - -# Returns - -`true` if the project could be loaded `false` otherwize. - -remove a `asset` to from `self`. -## `asset` -A `Asset` to remove from `self` - -# Returns - -`true` if the asset could be removed `false` otherwise - -Save the timeline of `self` to `uri`. You should make sure that `timeline` -is one of the timelines that have been extracted from `self` -(using ges_asset_extract (`self`);) -## `timeline` -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 best formatter -as defined in `ges_find_formatter_for_uri` -## `overwrite` -`true` to overwrite file if it exists - -# Returns - -`true` if the project could be save, `false` otherwize - -## `asset` -The `Asset` that has been added to `project` - -## `asset` -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` -`gst::CoreError::MissingPlugin` -## `error` -The `glib::Error` defining the error that occured, might be `None` -## `id` -The `id` of the asset that failed loading -## `extractable_type` -The `extractable_type` of the asset that -failed loading - -## `timeline` -The `Timeline` that completed loading - - -Feature: `v1_18` - -## `timeline` -The `Timeline` that started loading - - -```text -static gchar -source_moved_cb (GESProject *project, GError *error, GESAsset *asset_with_error) -{ - return g_strdup ("file:///the/new/uri.ogg"); -} - -static int -main (int argc, gchar ** argv) -{ - GESTimeline *timeline; - GESProject *project = ges_project_new ("file:///some/uri.xges"); - - g_signal_connect (project, "missing-uri", source_moved_cb, NULL); - timeline = ges_asset_extract (GES_ASSET (project)); -} -``` -## `error` -The error that happened -## `wrong_asset` -The asset with the wrong ID, you should us it and its content -only to find out what the new location is. - -# Returns - -The new URI of `wrong_asset` - -`Timeline` is the central object for any multimedia timeline. - -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 contained tracks define the supported types of the timeline -and provide the media output. Essentially, each track provides an -additional source `gst::Pad`. - -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. - -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 - -[`TimelineExt`](trait@crate::TimelineExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt) - -Trait containing all `Timeline` methods. - -# Implementors - -[`Timeline`](struct@crate::Timeline) - -Creates a new empty timeline. - -# Returns - -The new timeline. - -Creates a new timeline containing a single `AudioTrack` and a -single `VideoTrack`. - -# Returns - -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 - -# Returns - -A new timeline if the uri was loaded -successfully, or `None` if the uri could not be loaded. - -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 - -# Returns - -`true` if `layer` was properly added. - -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 - -# Returns - -`true` if `track` was properly added. - -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. - -Commit all the pending changes of the clips contained in the -timeline. - -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 before receiving this signal. You can use -`TimelineExt::commit_sync` if you do not want to perform other tasks in -the mean time. - -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 committed, or `false` if nothing -needed to be committed. - -Commit all the pending changes of the clips contained in the -timeline and wait for the changes to complete. - -See `TimelineExt::commit`. - -# Returns - -`true` if pending changes were committed, or `false` if nothing -needed to be committed. - -Gets `Timeline:auto-transition` for the timeline. - -# Returns - -The auto-transition of `self_`. - -Get the current `Timeline:duration` of the timeline - -# Returns - -The current duration of `self`. - -Gets the element contained in the timeline with the given name. -## `name` -The name of the element to find - -# Returns - -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. - -Feature: `v1_18` - -## `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. - -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 output of `self`. - -Get the list of `Group`-s present in the timeline. - -# Returns - -The list of -groups that contain clips present in `self`'s layers. -Must not be changed. - -Retrieve the layer whose index in the timeline matches the given -priority. -## `priority` -The priority/index of the layer to find - -# Returns - -The layer with the given -`priority`, or `None` if none was found. - -Since 1.6 - -Get the list of `Layer`-s present in the timeline. - -# Returns - -The list of -layers present in `self` sorted by priority. - -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` -A track - -# Returns - -The pad corresponding to `track`, -or `None` if there is an error. - -Gets the `Timeline:snapping-distance` for the timeline. - -# Returns - -The snapping distance (in nanoseconds) of `self`. - -Search for the `Track` corresponding to the given timeline's pad. -## `pad` -A pad - -# Returns - -The track corresponding to `pad`, -or `None` if there is an error. - -Get the list of `Track`-s used by the timeline. - -# Returns - -The list of tracks -used by `self`. - -Check whether the timeline is empty or not. - -# Returns - -`true` if `self` is empty. - -Loads the contents of URI into the timeline. -## `uri` -The URI to load from - -# Returns - -`true` if the timeline was loaded successfully from `uri`. - -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` -A layer within `self`, whose priority should be changed -## `new_layer_priority` -The new index for `layer` - -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 element to paste -## `position` -The position in the timeline `element` should be pasted to, -i.e. the `TimelineElement:start` value for the pasted element. -## `layer_priority` -The layer into which the element should be pasted. --1 means paste to the same layer from which `element` has been copied from - -# Returns - -The newly created element, or -`None` if pasting fails. - -Removes a layer from the timeline. -## `layer` -The layer to remove - -# Returns - -`true` if `layer` was properly removed. - -Remove a track from the timeline. -## `track` -The track to remove - -# Returns - -`true` if `track` was properly removed. - -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` -## `overwrite` -`true` to overwrite file if it exists - -# Returns - -`true` if `self` was successfully saved to `uri`. - -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 transitions should be automatically added -to `self`'s layers - -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` -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 do not want to have to connect -to this signal. - -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 that was added to `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 that was removed from `timeline` -## `children` -A list -of `Container`-s that _were_ the children of the removed `group` - -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 `timeline` - -Will be emitted after the layer is removed from the timeline. -## `layer` -The layer that was removed from `timeline` - -Simplified version of `Timeline::select-tracks-for-object` which only -allows `track_element` to be added to a single `Track`. - -Feature: `v1_18` - -## `clip` -The clip that `track_element` is being added to -## `track_element` -The element being added - -# Returns - -A track to put `track_element` into, or `None` if -it should be discarded. - -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 that `track_element` is being added to -## `track_element` -The element being added - -# Returns - -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 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 element that was snapping -## `obj2` -The second element that was snapping -## `position` -The position where the two objects were to be snapped to - -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 element that is snapping -## `obj2` -The second element that is snapping -## `position` -The position where the two objects will snap to - -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 `timeline` - -Will be emitted after the track is removed from the timeline. -## `track` -The track that was removed from `timeline` - -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. - -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. - -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. - -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 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. - -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`. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -Trait containing all `TimelineElement` methods. - -# Implementors - -[`Container`](struct@crate::Container), [`TimelineElement`](struct@crate::TimelineElement), [`TrackElement`](struct@crate::TrackElement) - -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. - -`pspec` should be unique from other children properties that have been -registered on `self`. -## `pspec` -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 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 `glib::object::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` -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` (in nanoseconds). - -Gets the `TimelineElement:in-point` for the element. - -# Returns - -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 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 max-duration of `self` (in nanoseconds). - -Gets the `TimelineElement:name` for the element. - -# Returns - -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. - -Gets the `TimelineElement:parent` for the element. - -# Returns - -The parent of `self`, or `None` if -`self` has no parent. - -Gets the `TimelineElement:priority` for the element. - -# Returns - -The priority of `self`. - -Gets the `TimelineElement:start` for the element. - -# Returns - -The start of `self` (in nanoseconds). - -Gets the `TimelineElement:timeline` for the element. - -# Returns - -The timeline of `self`, or `None` -if `self` has no timeline. - -Gets the toplevel `TimelineElement:parent` of the element. - -# Returns - -The toplevel parent of `self`. - -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. - -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` -The return location for the length of the -returned array - -# Returns - -An array of -`glib::object::ParamSpec` corresponding to the child properties of `self`, or `None` if -something went wrong. - -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 `glib::object::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` -The name of a child property -## `child` -The return location for the -found child -## `pspec` -The return location for the -specification of the child property - -# Returns - -`true` if a child corresponding to the property was found, in -which case `child` and `pspec` are set. - -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 `element` should be pasted -to, i.e. the `TimelineElement:start` value for the pasted element. - -# Returns - -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 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 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 `glib::object::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` -The value for the first property, followed optionally by more -name/value pairs, followed by `None` - -Sets `TimelineElement:duration` for the element. - -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 desired duration in its timeline - -# Returns - -`true` if `duration` could be set for `self`. - -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 internal time coordinates - -# Returns - -`true` if `inpoint` could be set for `self`. - -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 internal time coordinates - -# Returns - -`true` if `maxduration` could be set for `self`. - -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 - -# Returns - -`true` if `name` or a generated name for `self` could be set. - -Sets the `TimelineElement:parent` for the element. - -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 - -# Returns - -`true` if `priority` could be set for `self`. - -Sets `TimelineElement:start` for the element. If the element has a -parent, this will also move its siblings with the same shift. - -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 desired start position of the element in its timeline - -# Returns - -`true` if `start` could be set for `self`. - -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 for `self`. - -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 time of `self` in trim mode - -# Returns - -`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. - -Feature: `v1_18` - -## `prop_object` -The child whose property has been registered -## `prop` -The specification for the property that has been registered - -Emitted when the element has a child property unregistered. See -`TimelineElementExt::remove_child_property`. - -Feature: `v1_18` - -## `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 `glib::object::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 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 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 initial offset to use internally when outputting content (in -nanoseconds, but in the time coordinates of the internal content). - -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 initial offset to use internally when outputting content (in -nanoseconds, but in the time coordinates of the internal content). - -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 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 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 element. This should be unique within its timeline. - -The name of the element. This should be unique within its timeline. - -The parent container of the element. - -The parent container of the element. - -The priority of the element. - -# Deprecated since 1.10 - -Priority management is now done by GES itself. - -The priority of the element. - -# 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 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 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 that the element lies within. - -The timeline that the element lies within. - -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`. - -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 - -[`GESTrackExt`](trait@crate::GESTrackExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Trait containing all `Track` methods. - -# Implementors - -[`Track`](struct@crate::Track) - -Creates a new track with the given track-type and caps. - -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 `Track:track-type` for the track -## `caps` -The `Track:caps` for the track - -# Returns - -A new track. - -See `GESTrackExt::add_element`, which also gives an error. -## `object` -The element to add - -# Returns - -`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 for the elements contained in the -track. - -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 pending changes were committed, or `false` if nothing -needed to be committed. - -Get the `Track:caps` of the track. - -# Returns - -The caps of `self`. - -Gets the track elements contained in the track. The returned list is -sorted by the element's `TimelineElement:priority` and -`TimelineElement:start`. - -# Returns - -A list of -all the `TrackElement`-s in `self`. - -Gets the `Track:mixing` of the track. - -# Returns - -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. - -# Returns - -The timeline that `self` belongs to, or `None` if -it does not belong to a timeline. - -See `GESTrackExt::remove_element_full`, which also returns an error. -## `object` -The element to remove - -# Returns - -`true` if `object` was successfully removed from `self`. - -Removes the given track element from the track, which revokes -ownership of the element. - -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. - -> **NOTE**: Restriction caps are **not** taken into account when -> using `Pipeline:mode`=`PipelineFlags::SmartRender`. -## `caps` -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 is added to the track. -## `effect` -The element that was added - -Will be emitted after a track element is removed from the track. -## `effect` -The element that was removed - -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 `NleObject: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`. - -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 `NleObject: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 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 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`. - -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`. - -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`. - -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`. - -Once a track has been added to a `Timeline`, you should not change -this. - -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`. - -Once a track has been added to a `Timeline`, you should not change -this. - -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. - -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`. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`TrackElementExt`](trait@crate::TrackElementExt), [`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -Trait containing all `TrackElement` methods. - -# Implementors - -[`TrackElement`](struct@crate::TrackElement) - -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`. - -This is intended to be used by subclasses when constructing. -## `element` -The child object to retrieve properties from -## `wanted_categories` - -An array of element factory "klass" categories to whitelist, or `None` -to accept all categories -## `blacklist` -A -blacklist of element factory names, or `None` to not blacklist any -element factory -## `whitelist` -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 - -Edits the element within its track. - -# Deprecated since 1.18 - -use `TimelineElementExt::edit` instead. -## `layers` -A whitelist of layers -where the edit can be performed, `None` allows all layers in the -timeline -## `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) - -# Returns - -`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 -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`. - -# Deprecated - -Use `TimelineElementExt::get_child_properties` -## `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 -`glib::object::Value::unset`. - -Gets a property of a GstElement contained in `self`. - -Note that `TrackElement::get_child_property` is really -intended for language bindings, `TrackElement::get_child_properties` -is much more convenient for C programming. - -# Deprecated - -Use `TimelineElementExt::get_child_property` -## `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` otherwise. - -Gets a property of a child of `self`. - -# Deprecated - -Use `TimelineElementExt::get_child_property_by_pspec` -## `pspec` -The `glib::object::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. - -# Deprecated - -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 -name/return location pairs, followed by NULL - -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 name of the child property to return the control -binding of - -# Returns - -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` that the track element's underlying nleobject -controls. - -# Returns - -The `gst::Element` being controlled by the -nleobject that `self` wraps. - -Get the GNonLin object this object is controlling. - -# Deprecated - -use `TrackElementExt::get_nleobject` instead. - -# Returns - -The GNonLin object this object is controlling. - -Get the nleobject that this element wraps. - -# Returns - -The nleobject that `self` wraps. - -Get the `TrackElement:track` for the element. - -# Returns - -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. - -Feature: `v1_18` - - -# Returns - -`true` if `self` can have its 'internal time' properties set. - -Gets `TrackElement:active` for the element. - -# Returns - -`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 `glib::object::ParamSpec`* for all configurable properties of the -children of `self`. - -# Deprecated - -Use `TimelineElementExt::list_children_properties` -## `n_properties` -return location for the length of the returned array - -# Returns - -An array of `glib::object::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 -specify the class name in `name`. - -# Deprecated - -Use `TimelineElementExt::lookup_child` -## `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. -## `element` -pointer to a `gst::Element` that - takes the real object to set property on -## `pspec` -pointer to take the specification - describing the 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. - -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 child property to remove the control -binding from - -# Returns - -`true` if the control binding was removed from the specified -child property of `self`, or `false` if an error occurred. - -Sets `TrackElement:active` for the element. -## `active` -Whether `self` should be active in its track - -# Returns - -`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 -syntax: 'ClasseName::property_name' as property name. If you don't, the -corresponding property of the first element found will be set. - -# Deprecated - -Use `TimelineElementExt::set_child_properties` -## `first_property_name` -The name of the first property to set - -Sets a property of a GstElement contained in `self`. - -Note that `TrackElement::set_child_property` is really -intended for language bindings, `TrackElement::set_child_properties` -is much more convenient for C programming. - -# Deprecated - -use `TimelineElementExt::set_child_property` instead -## `property_name` -The name of the property -## `value` -The value - -# Returns - -`true` if the property was set, `false` otherwise. - -Sets a property of a child of `self`. - -# Deprecated - -Use `ges_timeline_element_set_child_property_by_spec` -## `pspec` -The `glib::object::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. - -# Deprecated - -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 -name/return location pairs, followed by NULL - -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 control source to bind the child property to -## `property_name` -The name of the child property to control -## `binding_type` -The type of binding to create ("direct" or -"direct-absolute") - -# Returns - -`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`. - -Feature: `v1_18` - -## `has_internal_source` -Whether the `self` should be allowed to have its -'internal time' properties set. - -# Returns - -`false` if `has_internal_source` is forbidden for `self` and -`true` in any other case. - -Sets the `TrackElement:track-type` for the element. -## `type_` -The new track-type for `self` - -This is emitted when a control binding is added to a child property -of the track element. -## `control_binding` -The control binding that has been added - -This is emitted when a control binding is removed from a child -property of the track element. -## `control_binding` -The control binding that has been removed - -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 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` - -Feature: `v1_18` - - -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` - -Feature: `v1_18` - - -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). - -Feature: `v1_18` - - -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). - -Feature: `v1_18` - - -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. - -Types of content handled by a track. If the content is not one of -[`Audio`](Self::Audio), [`Video`](Self::Video) or [`Text`](Self::Text), -the user of the `Track` must set the type to [`Custom`](Self::Custom). - -[`Unknown`](Self::Unknown) is for internal purposes and should not be used -by users - -A track of unknown type (i.e. invalid) - -An audio track - -A video track - -A text (subtitle) track - -A custom-content track - -Creates an object that mixes together the two underlying objects, A and B. -The A object is assumed to have a higher prioirity (lower number) than the -B object. At the transition in point, only A will be visible, and by the -end only B will be visible. - -The shape of the video transition depends on the value of the "vtype" -property. The default value is "crossfade". For audio, only "crossfade" is -supported. - -The ID of the ExtractableType is the nickname of the vtype property value. Note -that this value can be changed after creation and the GESExtractable.asset value -will be updated when needed. - -# Implements - -[`TransitionClipExt`](trait@crate::TransitionClipExt), [`BaseTransitionClipExt`](trait@crate::BaseTransitionClipExt), [`OperationClipExt`](trait@crate::OperationClipExt), [`ClipExt`](trait@crate::ClipExt), [`GESContainerExt`](trait@crate::GESContainerExt), [`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -Trait containing all `TransitionClip` methods. - -# Implementors - -[`TransitionClip`](struct@crate::TransitionClip) - -Creates a new `TransitionClip`. -## `vtype` -the type of transition to create - -# Returns - -a newly created `TransitionClip`, -or `None` if something went wrong. - -Creates a new `TransitionClip` for the provided `nick`. -## `nick` -a string representing the type of transition to create - -# Returns - -The newly created `TransitionClip`, -or `None` if something went wrong - -a `VideoStandardTransitionType` representing the wipe to use - -a `VideoStandardTransitionType` representing the wipe to use - -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@crate::UriClipExt), [`ClipExt`](trait@crate::ClipExt), [`GESContainerExt`](trait@crate::GESContainerExt), [`TimelineElementExt`](trait@crate::TimelineElementExt), [`trait@glib::object::ObjectExt`], [`ExtractableExt`](trait@crate::ExtractableExt), [`TimelineElementExtManual`](trait@crate::TimelineElementExtManual) - -Trait containing all `UriClip` methods. - -# Implementors - -[`UriClip`](struct@crate::UriClip) - -Creates a new `UriClip` for the provided `uri`. - -> **WARNING**: This function might 'discover` @uri **synchrounously**, it is -> an IO and processing intensive task that you probably don't want to run in -> an application mainloop. Have a look at #ges_asset_request_async to see how -> to make that operation happen **asynchronously**. -## `uri` -the URI the source should control - -# Returns - -The newly created `UriClip`, or -`None` if there was an error. - -Get the location of the resource. - -# Returns - -The location of the resource. - -Lets you know if `self` is an image or not. - -# Returns - -`true` if `self` is a still image `false` otherwise. - -Lets you know if the audio track of `self` is muted or not. - -# Returns - -`true` if the audio track of `self` is muted, `false` otherwise. - -Sets whether the clip is a still image or not. -## `is_image` -`true` if `self` is a still image, `false` otherwise - -Sets whether the audio track of this clip is muted or not. -## `mute` -`true` to mute `self` audio track, `false` to unmute it - -Whether this uri clip represents a still image or not. This must be set -before create_track_elements is called. - -Whether this uri clip represents a still image or not. This must be set -before create_track_elements is called. - -Whether the sound will be played or not. - -Whether the sound will be played or not. - -The location of the file/resource to use. - -The location of the file/resource to use. - - - -# Implements - -[`UriClipAssetExt`](trait@crate::UriClipAssetExt), [`AssetExt`](trait@crate::AssetExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `UriClipAsset` methods. - -# Implementors - -[`UriClipAsset`](struct@crate::UriClipAsset) - -Finalize the request of an async `UriClipAsset` - -Feature: `v1_16` - -## `res` -The `gio::AsyncResult` from which to get the newly created `UriClipAsset` - -# Returns - -The `UriClipAsset` previously requested - -Creates a `UriClipAsset` for `uri` - -Example of request of a GESUriClipAsset: - -```text -// The request callback -static void -filesource_asset_loaded_cb (GESAsset * source, GAsyncResult * res, gpointer user_data) -{ - GError *error = NULL; - GESUriClipAsset *filesource_asset; - - filesource_asset = ges_uri_clip_asset_finish (res, &error); - if (filesource_asset) { - g_print ("The file: %s is usable as a FileSource, it is%s an image and lasts %" GST_TIME_FORMAT, - ges_asset_get_id (GES_ASSET (filesource_asset)) - ges_uri_clip_asset_is_image (filesource_asset) ? "" : " not", - GST_TIME_ARGS (ges_uri_clip_asset_get_duration (filesource_asset)); - } else { - g_print ("The file: %s is *not* usable as a FileSource because: %s", - ges_asset_get_id (source), error->message); - } - - gst_object_unref (mfs); -} - -// The request: -ges_uri_clip_asset_new (uri, (GAsyncReadyCallback) filesource_asset_loaded_cb, user_data); -``` -## `uri` -The URI of the file for which to create a `UriClipAsset` -## `cancellable` -optional `gio::Cancellable` object, `None` to ignore. -## `callback` -a `GAsyncReadyCallback` to call when the initialization is finished -## `user_data` -The user data to pass when `callback` is called - -Creates a `UriClipAsset` for `uri` syncronously. You should avoid -to use it in application, and rather create `UriClipAsset` asynchronously -## `uri` -The URI of the file for which to create a `UriClipAsset`. -You can also use multi file uris for `MultiFileSource`. - -# Returns - -A reference to the requested asset or `None` if -an error happened - -Gets duration of the file represented by `self` - -# Returns - -The duration of `self` - -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 - -# Returns - -a -`glib::List` of `UriSourceAsset` - -Gets Whether the file represented by `self` is an image or not - -Feature: `v1_18` - - -# Returns - -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. - -# Implements - -[`UriSourceAssetExt`](trait@crate::UriSourceAssetExt), [`AssetExt`](trait@crate::AssetExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `UriSourceAsset` methods. - -# Implementors - -[`UriSourceAsset`](struct@crate::UriSourceAsset) - -Get the `UriClipAsset` `self_` is contained in - -# Returns - -a `UriClipAsset` - -Get the `gst_pbutils::DiscovererStreamInfo` user by `self` - -# Returns - -a `UriClipAsset` - -Check if `self` contains a single image - -Feature: `v1_18` - - -# Returns - -`true` if the video stream corresponds to an image (i.e. only -contains one frame) - - -Transition type has not been set, - -A bar moves from left to right, - -A bar moves from top to bottom, - -A box expands from the upper-left corner to the lower-right corner, - -A box expands from the upper-right corner to the lower-left corner, - -A box expands from the lower-right corner to the upper-left corner, - -A box expands from the lower-left corner to the upper-right corner, - -A box shape expands from each of the four corners toward the center, - -A box shape expands from the center of each quadrant toward the corners of each quadrant, - -A central, vertical line splits and expands toward the left and right edges, - -A central, horizontal line splits and expands toward the top and bottom edges, - -A box expands from the top edge's midpoint to the bottom corners, - -A box expands from the right edge's midpoint to the left corners, - -A box expands from the bottom edge's midpoint to the top corners, - -A box expands from the left edge's midpoint to the right corners, - -A diagonal line moves from the upper-left corner to the lower-right corner, - -A diagonal line moves from the upper right corner to the lower-left corner, - -Two wedge shapes slide in from the top and bottom edges toward the center, - -Two wedge shapes slide in from the left and right edges toward the center, - -A diagonal line from the lower-left to upper-right corners splits and expands toward the opposite corners, - -A diagonal line from upper-left to lower-right corners splits and expands toward the opposite corners, - -Four wedge shapes split from the center and retract toward the four edges, - -A diamond connecting the four edge midpoints simultaneously contracts toward the center and expands toward the edges, - -A wedge shape moves from top to bottom, - -A wedge shape moves from right to left, - -A wedge shape moves from bottom to top, - -A wedge shape moves from left to right, - -A 'V' shape extending from the bottom edge's midpoint to the opposite corners contracts toward the center and expands toward the edges, - -A 'V' shape extending from the left edge's midpoint to the opposite corners contracts toward the center and expands toward the edges, - -A 'V' shape extending from the top edge's midpoint to the opposite corners contracts toward the center and expands toward the edges, - -A 'V' shape extending from the right edge's midpoint to the opposite corners contracts toward the center and expands toward the edges, - -A rectangle expands from the center., - -A radial hand sweeps clockwise from the twelve o'clock position, - -A radial hand sweeps clockwise from the three o'clock position, - -A radial hand sweeps clockwise from the six o'clock position, - -A radial hand sweeps clockwise from the nine o'clock position, - -Two radial hands sweep clockwise from the twelve and six o'clock positions, - -Two radial hands sweep clockwise from the nine and three o'clock positions, - -Four radial hands sweep clockwise, - -A fan unfolds from the top edge, the fan axis at the center, - -A fan unfolds from the right edge, the fan axis at the center, - -Two fans, their axes at the center, unfold from the top and bottom, - -Two fans, their axes at the center, unfold from the left and right, - -A radial hand sweeps clockwise from the top edge's midpoint, - -A radial hand sweeps clockwise from the right edge's midpoint, - -A radial hand sweeps clockwise from the bottom edge's midpoint, - -A radial hand sweeps clockwise from the left edge's midpoint, - -Two radial hands sweep clockwise and counter-clockwise from the top and bottom edges' midpoints, - -Two radial hands sweep clockwise and counter-clockwise from the left and right edges' midpoints, - -Two radial hands attached at the top and bottom edges' midpoints sweep from right to left, - -Two radial hands attached at the left and right edges' midpoints sweep from top to bottom, - -A fan unfolds from the bottom, the fan axis at the top edge's midpoint, - -A fan unfolds from the left, the fan axis at the right edge's midpoint, - -A fan unfolds from the top, the fan axis at the bottom edge's midpoint, - -A fan unfolds from the right, the fan axis at the left edge's midpoint, - -Two fans, their axes at the top and bottom, unfold from the center, - -Two fans, their axes at the left and right, unfold from the center, - -A radial hand sweeps clockwise from the upper-left corner, - -A radial hand sweeps counter-clockwise from the lower-left corner., - -A radial hand sweeps clockwise from the lower-right corner, - -A radial hand sweeps counter-clockwise from the upper-right corner, - -Two radial hands attached at the upper-left and lower-right corners sweep down and up, - -Two radial hands attached at the lower-left and upper-right corners sweep down and up, - -Two radial hands attached at the upper-left and upper-right corners sweep down, - -Two radial hands attached at the upper-left and lower-left corners sweep to the right, - -Two radial hands attached at the lower-left and lower-right corners sweep up, - -Two radial hands attached at the upper-right and lower-right corners sweep to the left, - -Two radial hands attached at the midpoints of the top and bottom halves sweep from right to left, - -Two radial hands attached at the midpoints of the left and right halves sweep from top to bottom, - -Two sets of radial hands attached at the midpoints of the top and bottom halves sweep from top to bottom and bottom to top, - -Two sets of radial hands attached at the midpoints of the left and right halves sweep from left to right and right to left, - -Crossfade diff --git a/docs/gstreamer-gl/docs.md b/docs/gstreamer-gl/docs.md deleted file mode 100644 index cd5841d85..000000000 --- a/docs/gstreamer-gl/docs.md +++ /dev/null @@ -1,2203 +0,0 @@ - - - -no API - -Desktop OpenGL up to and including 3.1. The - compatibility profile when the OpenGL version is >= 3.2 - -Desktop OpenGL >= 3.2 core profile - -OpenGL ES 1.x - -OpenGL ES 2.x and 3.x - -Any OpenGL API - - - -# Returns - -a copy of the `GLAllocationParams` specified by - `self` or `None` on failure - -Copies the dynamically allocated data from `self` to `dest`. Direct subclasses -should call this function in their own overridden copy function. -## `dest` -the destination `GLAllocationParams` - -Frees the `GLAllocationParams` and all associated data. - -Frees the dynamically allocated data in `self`. Direct subclasses -should call this function in their own overridden free function. - -`notify` will be called once for each allocated memory using these `self` -when freeing the memory. -## `struct_size` -the struct size of the implementation -## `alloc_flags` -some alloc flags -## `copy` -a copy function -## `free` -a free function -## `context` -a `GLContext` -## `alloc_size` -the number of bytes to allocate. -## `alloc_params` -a `gst::AllocationParams` to apply -## `wrapped_data` -a sysmem data pointer to initialize the allocation with -## `gl_handle` -a GL handle to initialize the allocation with -## `user_data` -user data to call `notify` with -## `notify` -a `GDestroyNotify` - -# Returns - -whether the parameters could be initialized - -`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. - -# Implements - -[`GLBaseFilterExt`](trait@crate::GLBaseFilterExt), [`trait@gst_base::BaseTransformExt`], [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Trait containing all `GLBaseFilter` methods. - -# Implementors - -[`GLBaseFilter`](struct@crate::GLBaseFilter), [`GLFilter`](struct@crate::GLFilter) - - -Feature: `v1_16` - - -# Returns - -Whether an OpenGL context could be retrieved or created successfully - - -Feature: `v1_18` - - -# Returns - -the `GLContext` found by `self` - -GstGLBaseMemory is a `gst::Memory` subclass providing the basis of support -for the mapping of GL buffers. - -Data is uploaded or downloaded from the GPU as is necessary. - -Note: only intended for subclass usage to allocate the system memory buffer -on demand. If there is already a non-NULL data pointer in `self`->data, -then this function imply returns TRUE. - -# Returns - -whether the system memory could be allocated - -Initializes `self` with the required parameters -## `allocator` -the `gst::Allocator` to initialize with -## `parent` -the parent `gst::Memory` to initialize with -## `context` -the `GLContext` to initialize with -## `params` -the [`crate::gst::AllocationParams`] (XXX: @-reference does not belong to GLBaseMemory!) to initialize with -## `size` -the number of bytes to be allocated -## `user_data` -user data to call `notify` with -## `notify` -a `GDestroyNotify` - -## `dest` -the destination `GLBaseMemory` -## `offset` -the offset to start at -## `size` -the number of bytes to copy - -# Returns - -whether the copy succeeded. - -## `allocator` -a `GLBaseMemoryAllocator` -## `params` -the `GLAllocationParams` to allocate the memory with - -# Returns - -a new `GLBaseMemory` from `allocator` with the requested `params`. - -Initializes the GL Base Memory allocator. It is safe to call this function -multiple times. This must be called before any other GstGLBaseMemory operation. - -Opaque `GLBaseMemoryAllocator` struct - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`trait@gst::AllocatorExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -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. - -`GLColorConvert` is an object that converts between color spaces and/or -formats using OpenGL Shaders. - -A `GLColorConvert` can be created with `GLColorConvert::new`, the -configuration negotiated with `GLColorConvert::transform_caps` and the -conversion performed with `GLColorConvert::perform`. - -The glcolorconvertelement provides a GStreamer element that uses -`GLColorConvert` to convert between video formats and color spaces. - -# Implements - -[`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -## `context` -a `GLContext` - -# Returns - -a new `GLColorConvert` object - -Provides an implementation of `gst_base::BaseTransformClass.fixate_caps`() -## `context` -a `GLContext` to use for transforming `caps` -## `direction` -a `gst::PadDirection` -## `caps` -the `gst::Caps` of `direction` -## `other` -the `gst::Caps` to fixate - -# Returns - -the fixated `gst::Caps` - -Provides an implementation of `gst_base::BaseTransformClass.transform_caps`() -## `context` -a `GLContext` to use for transforming `caps` -## `direction` -a `gst::PadDirection` -## `caps` -the `gst::Caps` to transform -## `filter` -a set of filter `gst::Caps` - -# Returns - -the converted `gst::Caps` - -Provides an implementation of `gst_base::BaseTransformClass.decide_allocation`() -## `query` -a completed ALLOCATION `gst::Query` - -# Returns - -whether the allocation parameters were successfully chosen - -Converts the data contained by `inbuf` using the formats specified by the -`gst::Caps` passed to `GLColorConvert::set_caps` -## `inbuf` -the `GLMemory` filled `gst::Buffer` to convert - -# Returns - -a converted `gst::Buffer` or `None` - -Initializes `self` with the information required for conversion. -## `in_caps` -input `gst::Caps` -## `out_caps` -output `gst::Caps` - -`GLContext` wraps an OpenGL context object in a uniform API. As a result -of the limitation on OpenGL context, this object is not thread safe unless -specified and must only be activated in a single thread. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`GLContextExt`](trait@crate::GLContextExt), [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`GLContextExtManual`](trait@crate::GLContextExtManual) - -Trait containing all `GLContext` methods. - -# Implementors - -[`GLContext`](struct@crate::GLContext) - -Create a new `GLContext` with the specified `display` -## `display` -a `GLDisplay` - -# Returns - -a new `GLContext` - -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` -the OpenGL context to wrap -## `context_type` -a `GLPlatform` specifying the type of context in `handle` -## `available_apis` -a `GLAPI` containing the available OpenGL apis in `handle` - -# Returns - -a `GLContext` wrapping `handle` - -A default implementation of the various GetProcAddress functions that looks -for `name` in the OpenGL shared libraries or in the current process. - -See also: `GLContext::get_proc_address` -## `gl_api` -a `GLAPI` -## `name` -then function to get the address of - -# Returns - -an address pointing to `name` or `None` - -See also `GLContextExt::activate`. - -# Returns - -the `GLContext` active in the current thread or `None` - -If an error occurs, `major` and `minor` are not modified and `GLAPI::None` is -returned. -## `platform` -the `GLPlatform` to retrieve the API for -## `major` -the major version -## `minor` -the minor version - -# Returns - -The version supported by the OpenGL context current in the calling - thread or `GLAPI::None` - -## `context_type` -a `GLPlatform` specifying the type of context to retrieve - -# Returns - -The OpenGL context handle current in the calling thread or `None` - -Attempts to use the `context_type` specific GetProcAddress implementations -to retrieve `name`. - -See also `GLContext::get_proc_address`. -## `context_type` -a `GLPlatform` -## `gl_api` -a `GLAPI` -## `name` -the name of the function to retrieve - -# Returns - -a function pointer for `name`, or `None` - -(De)activate the OpenGL context represented by this `self`. - -In OpenGL terms, calls eglMakeCurrent or similar with this context and the -currently set window. See `GLContextExt::set_window` for details. -## `activate` -`true` to activate, `false` to deactivate - -# Returns - -Whether the activation succeeded - -Note: This will always fail for two wrapped `GLContext`'s -## `other_context` -another `GLContext` - -# Returns - -whether `self` and `other_context` are able to share OpenGL - resources. - -Check for an OpenGL `feature` being supported. - -Note: Most features require that the context be created before it is -possible to determine their existence and so will fail if that is not the -case. -## `feature` -a platform specific feature - -# Returns - -Whether `feature` is supported by `self` - -## `fbo_target` -the GL value of the framebuffer target, GL_FRAMEBUFFER, - GL_READ_FRAMEBUFFER, GL_DRAW_FRAMEBUFFER - -# Returns - -whether whether the current framebuffer is complete - -## `api` -api type required -## `maj` -major version required -## `min` -minor version required - -# Returns - -whether OpenGL context implements the required api and specified -version. - -Unbind the current framebuffer - -Clear's the currently set shader from the GL state machine. - -Note: must be called in the GL thread. - -Creates an OpenGL context with the specified `other_context` as a context -to share shareable OpenGL objects with. See the OpenGL specification for -what is shared between OpenGL contexts. - -If an error occurs, and `error` is not `None`, then error will contain details -of the error and `false` will be returned. - -Should only be called once. -## `other_context` -a `GLContext` to share OpenGL objects with - -# Returns - -whether the context could successfully be created - -Destroys an OpenGL context. - -Should only be called after `GLContextExt::create` has been successfully -called for this context. - -Fills `self`'s info (version, extensions, vtable, etc) from the GL -context in the current thread. Typically used with wrapped contexts to -allow wrapped contexts to be used as regular `GLContext`'s. - - -# Returns - -the `GLDisplay` associated with this `self` - -Get the currently enabled OpenGL api. - -The currently available API may be limited by the `GLDisplay` in use and/or -the `GLWindow` chosen. - -# Returns - -the available OpenGL api - -Gets the backing OpenGL context used by `self`. - -# Returns - -The platform specific backing OpenGL context - -Gets the OpenGL platform that used by `self`. - -# Returns - -The platform specific backing OpenGL context - -Get the version of the OpenGL platform (GLX, EGL, etc) used. Only valid -after a call to `GLContextExt::create`. -## `major` -return for the major version -## `minor` -return for the minor version - -Returns the OpenGL version implemented by `self`. See -`GLContextExt::get_gl_api` for retrieving the OpenGL api implemented by -`self`. -## `maj` -resulting major version -## `min` -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 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 -to call in `self`. The caller is responsible for ensuring that the -returned function is a valid function to call in `self` by either checking -the OpenGL API and version or for an appropriate OpenGL extension. - -Note: On success, you need to cast the returned function pointer to the -correct type to be able to call it correctly. On 32-bit Windows, this will -include the `GSTGLAPI` identifier to use the correct calling convention. -e.g. - - -```C -void (GSTGLAPI *PFN_glGetIntegerv) (GLenum name, GLint * ret) -``` -## `name` -an opengl function name - -# Returns - -a function pointer or `None` - - -# Returns - -The `glib::Thread`, `self` is current in or NULL - - -# Returns - -the currently set window - - -# Returns - -Whether the `GLContext` has been shared with another `GLContext` - -Will internally set `self` as shared with `share` -## `share` -another `GLContext` - -Set's the current window on `self` to `window`. The window can only be -changed before `GLContextExt::create` has been called and the `window` is not -already running. -## `window` -a `GLWindow` - -# Returns - -Whether the window was successfully updated - -## `version` -a `GLSLVersion` -## `profile` -a `GLSLProfile` - -# Returns - -Whether `self` supports the combination of `version` with `profile` - - -Feature: `v1_16` - -## `version` -a `GLSLVersion` -## `profile` -a `GLSLProfile` - -# Returns - -whether `self` supports the 'precision' specifier in GLSL shaders - - -Feature: `v1_16` - -## `version` -a `GLSLVersion` -## `profile` -a `GLSLProfile` - -# Returns - -whether `self` supports the 'precision highp' specifier in GLSL shaders - -Swap the front and back buffers on the window attached to `self`. -This will display the frame on the next refresh cycle. - -Execute `func` in the OpenGL thread of `self` with `data` - -MT-safe -## `func` -a `GstGLContextThreadFunc` -## `data` -user data to call `func` with - -OpenGL context errors. - -Failed for an unspecified reason - -The configuration requested is not correct - -The OpenGL API requested is not correct - -The OpenGL libraries are too old - -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 propagate -a `GLDisplay`. - -There are a number of environment variables that influence the choice of -platform and window system specific functionality. -- GST_GL_WINDOW influences the window system to use. Common values are - 'x11', 'wayland', 'win32' or 'cocoa'. -- GST_GL_PLATFORM influences the OpenGL platform to use. Common values are - 'egl', 'glx', 'wgl' or 'cgl'. -- GST_GL_API influences the OpenGL API requested by the OpenGL platform. - Common values are 'opengl', 'opengl3' and 'gles2'. - -> Certain window systems require a special function to be called to -> initialize threading support. As this GStreamer GL library does not preclude -> concurrent access to the windowing system, it is strongly advised that -> applications ensure that threading support has been initialized before any -> other toolkit/library functionality is accessed. Failure to do so could -> result in sudden application abortion during execution. The most notably -> example of such a function is X11's XInitThreads\(). - -# Implements - -[`GLDisplayExt`](trait@crate::GLDisplayExt), [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Trait containing all `GLDisplay` methods. - -# Implementors - -[`GLDisplay`](struct@crate::GLDisplay) - - -# Returns - -a new `GLDisplay` - -## `context` -a `GLContext` - -# Returns - -whether `context` was successfully added. `false` may be returned -if there already exists another context for `context`'s active thread. - -Must be called with the object lock held. - -It requires the display's object lock to be held. -## `other_context` -other `GLContext` to share resources with. -## `p_context` -resulting `GLContext` - -# Returns - -whether a new context could be created. - - -# Returns - -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 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 argument to `compare_func` is the `GLWindow` being checked and the -second argument is `data`. -## `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` - -see `GLDisplayExt::filter_gl_api` for what the returned value represents - -# Returns - -the `GLAPI` configured for `self` - -## `thread` -a `glib::Thread` - -# Returns - -the `GLContext` current on `thread` or `None` - -Must be called with the object lock held. - - -# Returns - -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 - -# 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 [`crate::GLContext`] (XXX: @-reference does not belong to GLDisplayExt!) creation mechanism. -It can be called in any thread and it is emitted with -display's object lock held. -## `context` -other context to share resources with. - -# Returns - -the new context. - - -no display type - -X11 display - -Wayland display - -Cocoa display - -Win32 display - -Dispmanx display - -EGL display - -Vivante Framebuffer display - -Mesa3D GBM display - -EGLDevice display (Since: 1.18) - -any display type - -`GLFilter` helps to implement simple OpenGL filter elements taking a -single input and producing a single output with a `GLFramebuffer` - -# Implements - -[`GLFilterExt`](trait@crate::GLFilterExt), [`GLBaseFilterExt`](trait@crate::GLBaseFilterExt), [`trait@gst_base::BaseTransformExt`], [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Trait containing all `GLFilter` methods. - -# Implementors - -[`GLFilter`](struct@crate::GLFilter) - -Render a fullscreen quad using the current GL state. The only GL state this -modifies is the necessary vertex/index buffers and, if necessary, a -Vertex Array Object for drawing a fullscreen quad. Framebuffer state, -any shaders, viewport state, etc must be setup by the caller. - -Calls filter_texture vfunc with correctly mapped `GstGLMemorys` -## `input` -an input buffer -## `output` -an output buffer - -# Returns - -whether the transformation succeeded - -Transforms `input` into `output` using `func` on through FBO. -## `input` -the input texture -## `output` -the output texture -## `func` -the function to transform `input` into `output`. called with `data` -## `data` -the data associated with `func` - -# Returns - -the return value of `func` - -Transforms `input` into `output` using `shader` with a FBO. - -See also: `GLFilterExt::render_to_target` -## `input` -the input texture -## `output` -the output texture -## `shader` -the shader to use. - - -Single component replicated across R, G, and B textures - components - -Single component stored in the A texture component - -Combination of `GLFormat::Luminance` and `GLFormat::Alpha` - -Single component stored in the R texture component - -Single 8-bit component stored in the R texture component - -Two components stored in the R and G texture components - -Two 8-bit components stored in the R and G texture components - -Three components stored in the R, G, and B texture components - -Three 8-bit components stored in the R, G, and B - texture components - -Three components of bit depth 5, 6 and 5 stored in the R, G, - and B texture components respectively. - -Three 16-bit components stored in the R, G, and B - texture components - -Four components stored in the R, G, B, and A texture - components respectively. - -Four 8-bit components stored in the R, G, B, and A texture - components respectively. - -Four 16-bit components stored in the R, G, B, and A texture - components respectively. - -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. - -A `GLFramebuffer` can be created with `GLFramebuffer::new` or -`GLFramebuffer::new_with_default_depth` and bound with -`GLFramebufferExt::bind`. Other resources can be bound with -`GLFramebufferExt::attach` - -Note: OpenGL framebuffers are not shareable resources so cannot be used -between multiple OpenGL contexts. - -# Implements - -[`GLFramebufferExt`](trait@crate::GLFramebufferExt), [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Trait containing all `GLFramebuffer` methods. - -# Implementors - -[`GLFramebuffer`](struct@crate::GLFramebuffer) - -## `context` -a `GLContext` - -# Returns - -a new `GLFramebuffer` - -## `context` -a `GLContext` -## `width` -width for the depth buffer -## `height` -for the depth buffer - -# Returns - -a new `GLFramebuffer` with a depth buffer of `width` and `height` - -attach `mem` to `attachment_point` -## `attachment_point` -the OpenGL attachment point to bind `mem` to -## `mem` -the memory object to bind to `attachment_point` - -Bind `self` into the current thread - -Perform the steps necessary to have the output of a glDraw* command in -`func` update the contents of `mem`. -## `mem` -the `GLMemory` to draw to -## `func` -the function to run -## `user_data` -data to pass to `func` - -# Returns - -the result of executing `func` - -Retrieve the effective dimensions from the current attachments attached to -`self`. -## `width` -output width -## `height` -output height - - -# Returns - -the OpenGL id for `self` - -GstGLMemory is a `GLBaseMemory` subclass providing support for the mapping of -OpenGL textures. - -`GLMemory` is created or wrapped through `GLBaseMemory::alloc` -with `GLVideoAllocationParams`. - -Data is uploaded or downloaded from the GPU as is necessary. - -The `gst::Caps` that is used for `GLMemory` based buffers should contain -the `GST_CAPS_FEATURE_MEMORY_GL_MEMORY` as a `gst::CapsFeatures` and should -contain a 'texture-target' field with one of the `GLTextureTarget` values -as a string, i.e. some combination of 'texture-target=(string){2D, -rectangle, external-oes}'. - -Copies `self` into the texture specified by `tex_id`. The format of `tex_id` -is specified by `tex_format`, `width` and `height`. -## `tex_id` -OpenGL texture id -## `target` -the `GLTextureTarget` -## `tex_format` -the `GLFormat` -## `width` -width of `tex_id` -## `height` -height of `tex_id` - -# Returns - -Whether the copy succeeded - -Copies the texture in `GLMemory` into the texture specified by `tex_id`, -`out_target`, `out_tex_format`, `out_width` and `out_height`. -## `tex_id` -the destination texture id -## `out_target` -the destination `GLTextureTarget` -## `out_tex_format` -the destination `GLFormat` -## `out_width` -the destination width -## `out_height` -the destination height - -# Returns - -whether the copy succeeded. - - -# Returns - -the `GLFormat` of `self` - - -# Returns - -the texture height of `self` - - -# Returns - -the OpenGL texture handle of `self` - - -# Returns - -the `GLTextureTarget` of `self` - - -# Returns - -the texture width of `self` - -Initializes `self` with the required parameters. `info` is assumed to have -already have been modified with `gst_video::VideoInfo::align`. -## `allocator` -the `gst::Allocator` to initialize with -## `parent` -the parent `gst::Memory` to initialize with -## `context` -the `GLContext` to initialize with -## `target` -the `GLTextureTarget` for this `GLMemory` -## `tex_format` -the `GLFormat` for this `GLMemory` -## `params` -the [`crate::gst::AllocationParams`] (XXX: @-reference does not belong to GLMemory!) to initialize with -## `info` -the `gst_video::VideoInfo` for this `GLMemory` -## `plane` -the plane number (starting from 0) for this `GLMemory` -## `valign` -optional `gst_video::VideoAlignment` parameters -## `user_data` -user data to call `notify` with -## `notify` -a `GDestroyNotify` - -Reads the texture in `GLMemory` into `write_pointer` if no buffer is bound -to `GL_PIXEL_PACK_BUFFER`. Otherwise `write_pointer` is the byte offset into -the currently bound `GL_PIXEL_PACK_BUFFER` buffer to store the result of -glReadPixels. See the OpenGL specification for glReadPixels for more -details. -## `write_pointer` -the data pointer to pass to glReadPixels - -# Returns - -whether theread operation succeeded - -Reads the texture in `read_pointer` into `self`. - -See `GLMemory::read_pixels` for what `read_pointer` signifies. -## `read_pointer` -the data pointer to pass to glTexSubImage - -Initializes the GL Base Texture allocator. It is safe to call this function -multiple times. This must be called before any other GstGLMemory operation. - -## `allocator` -the [`crate::GLMemoryAllocator`] (XXX: @-reference does not belong to GLMemory!) to allocate from -## `buffer` -a `gst::Buffer` to setup -## `params` -the `GLVideoAllocationParams` to allocate with -## `tex_formats` - - a list of `GLFormat`'s to allocate with. -## `wrapped_data` - - a list of wrapped data pointers -## `n_wrapped_pointers` -the number of elements in `tex_formats` and `wrapped_data` - -# Returns - -whether the buffer was correctly setup - -Opaque `GLMemoryAllocator` struct - -# Implements - -[`GLBaseMemoryAllocatorExt`](trait@crate::GLBaseMemoryAllocatorExt), [`trait@gst::AllocatorExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -## `context` -a `GLContext` - -# Returns - -the default `GLMemoryAllocator` supported by - `context` - -Opaque `GLOverlayCompositor` object - -# Implements - -[`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - - -no platform - -the EGL platform used primarily with the X11, wayland - and android window systems as well as on embedded Linux - -the GLX platform used primarily with the X11 window system - -the WGL platform used primarily on Windows - -the CGL platform used primarily on OS X - -the EAGL platform used primarily on iOS - -any OpenGL platform - -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 - -query the time elapsed - -query the current time - -Compilation stage that caused an error - -Compilation error occurred - -Link error occurred - -General program error occurred - -GLSL profiles - -no profile supported/available - -OpenGL|ES profile - -OpenGL core profile - -OpenGL compatibility profile - -any OpenGL/OpenGL|ES profile - -`GLSLStage` holds and represents a single OpenGL shader stage. - -# Implements - -[`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -## `context` -a `GLContext` -## `type_` -the GL enum shader stage type - -# Returns - -a new `GLSLStage` of the specified `type_` - -## `context` -a `GLContext` -## `type_` -the GL enum shader stage type -## `version` -the `GLSLVersion` -## `profile` -the `GLSLProfile` -## `str` -a shader string - -# Returns - -a new `GLSLStage` of the specified `type_` - -## `context` -a `GLContext` -## `type_` -the GL enum shader stage type -## `version` -the `GLSLVersion` -## `profile` -the `GLSLProfile` -## `n_strings` -the number of strings in `str` -## `str` - - an array of strings concatted together to produce a shader - -# Returns - -a new `GLSLStage` of the specified `type_` - - -# Returns - -whether the compilation succeeded - - -# Returns - -The GL handle for this shader stage - - -# Returns - -The GLSL profile for the current shader stage - - -# Returns - -The GL shader type for this shader stage - - -# Returns - -The GLSL version for the current shader stage - -Replaces the current shader string with `str`. -## `version` -a `GLSLVersion` -## `profile` -a `GLSLProfile` -## `n_strings` -number of strings in `str` -## `str` -a GLSL shader string - -GLSL version list - -no version - -version 100 (only valid for ES) - -version 110 (only valid for compatibility desktop GL) - -version 120 (only valid for compatibility desktop GL) - -version 130 (only valid for compatibility desktop GL) - -version 140 (only valid for compatibility desktop GL) - -version 150 (valid for compatibility/core desktop GL) - -version 300 (only valid for ES) - -version 310 (only valid for ES) - -version 320 (only valid for ES) - -version 330 (valid for compatibility/core desktop GL) - -version 400 (valid for compatibility/core desktop GL) - -version 410 (valid for compatibility/core desktop GL) - -version 420 (valid for compatibility/core desktop GL) - -version 430 (valid for compatibility/core desktop GL) - -version 440 (valid for compatibility/core desktop GL) - -version 450 (valid for compatibility/core desktop GL) - - - -# Implements - -[`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Note: must be called in the GL thread -## `context` -a `GLContext` - -# Returns - -a new empty `shader` - -Note: must be called in the GL thread -## `context` -a `GLContext` - -# Returns - -a default `shader` or `None` on failure - -Each stage will attempt to be compiled and attached to `shader`. Then -the shader will be linked. On error, `None` will be returned and `error` will -contain the details of the error. - -Note: must be called in the GL thread -## `context` -a `GLContext` -## `error` -a `glib::Error` - -# Returns - -a new `shader` with the specified stages. - -Each stage will attempt to be compiled and attached to `shader`. On error, -`None` will be returned and `error` will contain the details of the error. - -Note: must be called in the GL thread -## `context` -a `GLContext` -## `error` -a `glib::Error` - -# Returns - -a new `shader` with the specified stages. - - -Feature: `v1_16` - -## `context` -a `GLContext` -## `version` -a `GLSLVersion` -## `profile` -a `GLSLProfile` - -# Returns - -a passthrough shader string for copying an input external-oes - texture to the output - - -Feature: `v1_16` - -## `context` -a `GLContext` -## `version` -a `GLSLVersion` -## `profile` -a `GLSLProfile` - -# Returns - -a passthrough shader string for copying an input texture to - the output - -Generates a shader string that defines the precision of float types in -GLSL shaders. This is particularly needed for fragment shaders in a -GLSL ES context where there is no default precision specified. - -Practically, this will return the string 'precision mediump float' -or 'precision highp float' depending on if high precision floats are -determined to be supported. - -Feature: `v1_16` - -## `context` -a `GLContext` -## `version` -a `GLSLVersion` -## `profile` -a `GLSLProfile` - -# Returns - -a shader string defining the precision of float types based on - `context`, `version` and `profile` - -Attaches `stage` to `self`. `stage` must have been successfully compiled -with `GLSLStage::compile`. - -Note: must be called in the GL thread -## `stage` -a `GLSLStage` to attach - -# Returns - -whether `stage` could be attached to `self` - -Attaches `stage` to `self`. `stage` must have been successfully compiled -with `GLSLStage::compile`. - -Note: must be called in the GL thread -## `stage` -a `GLSLStage` to attach - -# Returns - -whether `stage` could be attached to `self` - -Bind attribute `name` to the specified location `index` using -`glBindAttributeLocation()`. -## `index` -attribute index to set -## `name` -name of the attribute - -Bind attribute `name` to the specified location `index` using -`glBindFragDataLocation()`. -## `index` -attribute index to set -## `name` -name of the attribute - -Compiles `stage` and attaches it to `self`. - -Note: must be called in the GL thread -## `stage` -a `GLSLStage` to attach - -# Returns - -whether `stage` could be compiled and attached to `self` - -Detaches `stage` from `self`. `stage` must have been successfully attached -to `self` with `GLShader::attach` or `GLShader::attach_unlocked`. - -Note: must be called in the GL thread -## `stage` -a `GLSLStage` to attach - -Detaches `stage` from `self`. `stage` must have been successfully attached -to `self` with `GLShader::attach` or `GLShader::attach_unlocked`. - -Note: must be called in the GL thread -## `stage` -a `GLSLStage` to attach - -## `name` -name of the attribute - -# Returns - -the attribute index for `name` in `self` or -1 on failure - - -# Returns - -the GL program handle for this shader - -Note: must be called in the GL thread - -# Returns - -whether `self` has been successfully linked - -Links the current list of `GLSLStage`'s in `self`. - -Note: must be called in the GL thread - -# Returns - -whether `self` could be linked together. - -Releases the shader and stages. - -Note: must be called in the GL thread - -Releases the shader and stages. - -Note: must be called in the GL thread - -Perform `glUniform1f()` for `name` on `self` -## `name` -name of the uniform -## `value` -value to set - -Perform `glUniform1fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of values to set -## `value` -values to set - -Perform `glUniform1i()` for `name` on `self` -## `name` -name of the uniform -## `value` -value to set - -Perform `glUniform1iv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of values to set -## `value` -values to set - -Perform `glUniform2f()` for `name` on `self` -## `name` -name of the uniform -## `v0` -first value to set -## `v1` -second value to set - -Perform `glUniform2fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of values to set -## `value` -values to set - -Perform `glUniform2i()` for `name` on `self` -## `name` -name of the uniform -## `v0` -first value to set -## `v1` -second value to set - -Perform `glUniform2iv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of values to set -## `value` -values to set - -Perform `glUniform3f()` for `name` on `self` -## `name` -name of the uniform -## `v0` -first value to set -## `v1` -second value to set -## `v2` -third value to set - -Perform `glUniform3fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of values to set -## `value` -values to set - -Perform `glUniform3i()` for `name` on `self` -## `name` -name of the uniform -## `v0` -first value to set -## `v1` -second value to set -## `v2` -third value to set - -Perform `glUniform3iv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of values to set -## `value` -values to set - -Perform `glUniform4f()` for `name` on `self` -## `name` -name of the uniform -## `v0` -first value to set -## `v1` -second value to set -## `v2` -third value to set -## `v3` -fourth value to set - -Perform `glUniform4fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of values to set -## `value` -values to set - -Perform `glUniform4i()` for `name` on `self` -## `name` -name of the uniform -## `v0` -first value to set -## `v1` -second value to set -## `v2` -third value to set -## `v3` -fourth value to set - -Perform `glUniform4iv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of values to set -## `value` -values to set - -Perform `glUniformMatrix2fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of 2x2 matrices to set -## `transpose` -transpose the matrix -## `value` -matrix to set - -Perform `glUniformMatrix2x3fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of 2x3 matrices to set -## `transpose` -transpose the matrix -## `value` -values to set - -Perform `glUniformMatrix2x4fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of 2x4 matrices to set -## `transpose` -transpose the matrix -## `value` -values to set - -Perform `glUniformMatrix3fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of 3x3 matrices to set -## `transpose` -transpose the matrix -## `value` -values to set - -Perform `glUniformMatrix3x2fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of 3x2 matrices to set -## `transpose` -transpose the matrix -## `value` -values to set - -Perform `glUniformMatrix3x4fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of 3x4 matrices to set -## `transpose` -transpose the matrix -## `value` -values to set - -Perform `glUniformMatrix4fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of 4x4 matrices to set -## `transpose` -transpose the matrix -## `value` -values to set - -Perform `glUniformMatrix4x2fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of 4x2 matrices to set -## `transpose` -transpose the matrix -## `value` -values to set - -Perform `glUniformMatrix4x3fv()` for `name` on `self` -## `name` -name of the uniform -## `count` -number of 4x3 matrices to set -## `transpose` -transpose the matrix -## `value` -values to set - -Mark's `self` as being used for the next GL draw command. - -Note: must be called in the GL thread and `self` must have been linked. - -Output anaglyph type to generate when downmixing to mono - -Dubois optimised Green-Magenta anaglyph - -Dubois optimised Red-Cyan anaglyph - -Dubois optimised Amber-Blue anaglyph - -The OpenGL texture target that an OpenGL texture can be bound to. The -`gst_gl_value_set_texture_target_from_mask`, -`gst_gl_value_get_texture_target_mask`, and -`gst_gl_value_set_texture_target` functions can be used for handling texture -targets with `glib::object::Value`'s when e.g. dealing with `gst::Caps`. - -no texture target - -2D texture target (`GL_TEXTURE_2D`) - -rectangle texture target - (`GL_TEXTURE_RECTANGLE`) - -external oes texture target - (`GL_TEXTURE_EXTERNAL_OES`) - -`GLUpload` is an object that uploads data from system memory into GL textures. - -A `GLUpload` can be created with `GLUpload::new` - -# Implements - -[`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -## `context` -a `GLContext` - -# Returns - -a new `GLUpload` object - -## `in_caps` -the input `gst::Caps` -## `out_caps` -the output `gst::Caps` - -Uploads `buffer` using the transformation specified by -`GLUpload::set_caps` creating a new `gst::Buffer` in `outbuf_ptr`. -## `buffer` -input `gst::Buffer` -## `outbuf_ptr` -resulting `gst::Buffer` - -# Returns - -whether the upload was successful - -Adds the required allocation parameters to support uploading. -## `decide_query` -a `gst::Query` from a decide allocation -## `query` -the proposed allocation query - -Initializes `self` with the information required for upload. -## `in_caps` -input `gst::Caps` -## `out_caps` -output `gst::Caps` - -# Returns - -whether `in_caps` and `out_caps` could be set on `self` - - -No further processing required - -An unspecified error occurred - -The configuration is unsupported. - -This element requires a reconfiguration. - -private return value. - - -## `context` -a `GLContext` -## `alloc_params` -the `gst::AllocationParams` for sysmem mappings of the texture -## `v_info` -the `gst_video::VideoInfo` for the texture -## `plane` -the video plane of `v_info` to allocate -## `valign` -any `gst_video::VideoAlignment` applied to symem mappings of the texture -## `target` -the `GLTextureTarget` for the created textures -## `tex_format` -the `GLFormat` for the created textures - -# Returns - -a new `GLVideoAllocationParams` for allocating `GLMemory`'s - -## `context` -a `GLContext` -## `alloc_params` -the `gst::AllocationParams` for `wrapped_data` -## `v_info` -the `gst_video::VideoInfo` for `wrapped_data` -## `plane` -the video plane `wrapped_data` represents -## `valign` -any `gst_video::VideoAlignment` applied to symem mappings of `wrapped_data` -## `target` -the `GLTextureTarget` for `wrapped_data` -## `tex_format` -the `GLFormat` for `wrapped_data` -## `wrapped_data` -the data pointer to wrap -## `user_data` -user data to call `notify` with -## `notify` -a `GDestroyNotify` - -# Returns - -a new `GLVideoAllocationParams` for wrapping `wrapped_data` - -`gl_handle` is defined by the specific OpenGL handle being wrapped -For `GLMemory` and `GLMemoryPBO` it is an OpenGL texture id. -Other memory types may define it to require a different type of parameter. -## `context` -a `GLContext` -## `alloc_params` -the `gst::AllocationParams` for `tex_id` -## `v_info` -the `gst_video::VideoInfo` for `tex_id` -## `plane` -the video plane `tex_id` represents -## `valign` -any `gst_video::VideoAlignment` applied to symem mappings of `tex_id` -## `target` -the `GLTextureTarget` for `tex_id` -## `tex_format` -the `GLFormat` for `tex_id` -## `gl_handle` -the GL handle to wrap -## `user_data` -user data to call `notify` with -## `notify` -a `GDestroyNotify` - -# Returns - -a new `GLVideoAllocationParams` for wrapping `gl_handle` - -## `context` -a `GLContext` -## `alloc_params` -the `gst::AllocationParams` for `tex_id` -## `v_info` -the `gst_video::VideoInfo` for `tex_id` -## `plane` -the video plane `tex_id` represents -## `valign` -any `gst_video::VideoAlignment` applied to symem mappings of `tex_id` -## `target` -the `GLTextureTarget` for `tex_id` -## `tex_format` -the `GLFormat` for `tex_id` -## `tex_id` -the GL texture to wrap -## `user_data` -user data to call `notify` with -## `notify` -a `GDestroyNotify` - -# Returns - -a new `GLVideoAllocationParams` for wrapping `tex_id` - -Copy and set any dynamically allocated resources in `dest_vid`. Intended -for subclass usage only to chain up at the end of a subclass copy function. -## `dest_vid` -destination `GLVideoAllocationParams` to copy into - -Unset and free any dynamically allocated resources. Intended for subclass -usage only to chain up at the end of a subclass free function. - -Intended for subclass usage -## `struct_size` -the size of the struct in `self` -## `alloc_flags` -some allocation flags -## `copy` -a copy function -## `free` -a free function -## `context` -a `GLContext` -## `alloc_params` -the `gst::AllocationParams` for `wrapped_data` -## `v_info` -the `gst_video::VideoInfo` for `wrapped_data` -## `plane` -the video plane `wrapped_data` represents -## `valign` -any `gst_video::VideoAlignment` applied to symem mappings of `wrapped_data` -## `target` -the `GLTextureTarget` -## `tex_format` -the `GLFormat` -## `wrapped_data` -the optional data pointer to wrap -## `gl_handle` -the optional OpenGL handle to wrap or 0 -## `user_data` -user data to call `notify` with -## `notify` -a `GDestroyNotify` - -# Returns - -initializes `self` with the parameters specified - -Convert stereoscopic/multiview video using fragment shaders. - -# Implements - -[`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - - -# Returns - -a new `GLViewConvert` - -Provides an implementation of `gst_base::BaseTransformClass.fixate_caps`() -## `direction` -a `gst::PadDirection` -## `caps` -the `gst::Caps` of `direction` -## `othercaps` -the `gst::Caps` to fixate - -# Returns - -the fixated `gst::Caps` - -Retrieve the processed output buffer placing the output in `outbuf_ptr`. -## `outbuf_ptr` -a `gst::Buffer` - -# Returns - -a `gst::FlowReturn` - -Converts the data contained by `inbuf` using the formats specified by the -`gst::Caps` passed to `GLViewConvert::set_caps` -## `inbuf` -the `GLMemory` filled `gst::Buffer` to convert - -# Returns - -a converted `gst::Buffer` or `None` - -Reset `self` to the default state. Further operation will require -setting the caps with `GLViewConvert::set_caps`. - -Initializes `self` with the information required for conversion. -## `in_caps` -input `gst::Caps` -## `out_caps` -output `gst::Caps` - -Set `context` on `self` -## `context` -the `GLContext` to set - -Submit `input` to be processed by `self` -## `is_discont` -true if we have a discontinuity -## `input` -a `gst::Buffer` - -# Returns - -a `gst::FlowReturn` - -Provides an implementation of `gst_base::BaseTransformClass.transform_caps`() -## `direction` -a `gst::PadDirection` -## `caps` -the `gst::Caps` to transform -## `filter` -a set of filter `gst::Caps` - -# Returns - -the converted `gst::Caps` - -GstGLWindow represents a window that elements can render into. A window can -either be a user visible window (onscreen) or hidden (offscreen). - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`GLWindowExt`](trait@crate::GLWindowExt), [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Trait containing all `GLWindow` methods. - -# Implementors - -[`GLWindow`](struct@crate::GLWindow) - -## `display` -a `GLDisplay` - -# Returns - -a new `GLWindow` using `display`'s connection - -Checks if `self` controls the GL viewport. - -Feature: `v1_16` - - -# Returns - -`true` if `self` controls the GL viewport, otherwise `false` - -Redraw the window contents. Implementations should invoke the draw callback. - - -# Returns - -the `GLContext` associated with this `self` - - -# Returns - -the windowing system display handle for this `self` - -## `width` -resulting surface width -## `height` -resulting surface height - - -# Returns - -the window handle we are currently rendering into - -Tell a `self` that it should handle events from the window system. These -events are forwarded upstream as navigation events. In some window systems -events are not propagated in the window hierarchy if a client is listening -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`. - -Quit the runloop's execution. - -Resize `self` to the given `width` and `height`. -## `width` -new width -## `height` -new height - -Start the execution of the runloop. - -Invoke `callback` with data on the window thread. `callback` is guaranteed to -have executed when this function returns. -## `callback` -function to invoke -## `data` -data to invoke `callback` with - -Invoke `callback` with `data` on the window thread. The callback may not -have been executed when this function returns. -## `callback` -function to invoke -## `data` -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` -function to invoke -## `data` -data to invoke `callback` with -## `destroy_notify` -called when `data` is not needed any more - -Sets the draw callback called every time `GLWindowExt::draw` is called -## `callback` -function to invoke -## `data` -data to invoke `callback` with -## `destroy_notify` -called when `data` is not needed any more - -Set the preferred width and height of the window. Implementations are free -to ignore this information. -## `width` -new preferred width -## `height` -new preferred height - -Tell a `self` that it should render into a specific region of the window -according to the `gst_video::VideoOverlay` interface. -## `x` -x position -## `y` -y position -## `width` -width -## `height` -height - -# Returns - -whether the specified region could be set - -Sets the resize callback called every time a resize of the window occurs. -## `callback` -function to invoke -## `data` -data to invoke `callback` with -## `destroy_notify` -called when `data` is not needed any more - -Sets the window that this `self` should render into. Some implementations -require this to be called with a valid handle before drawing can commence. -## `handle` -handle to the window - -Present the window to the screen. - -Will be emitted when a key event is received by the GstGLwindow. -## `id` -the name of the event -## `key` -the id of the key pressed - -Will be emitted when a mouse event is received by the GstGLwindow. -## `id` -the name of the event -## `button` -the id of the button -## `x` -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 - -the implementation is too old - -no such resource was found diff --git a/docs/gstreamer-gl/egl/docs.md b/docs/gstreamer-gl/egl/docs.md deleted file mode 100644 index 460c75b6c..000000000 --- a/docs/gstreamer-gl/egl/docs.md +++ /dev/null @@ -1,37 +0,0 @@ - - -the contents of a `GLDisplayEGL` are private and should only be accessed -through the provided API - -# Implements - -[`trait@gst_gl::GLDisplayExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Create a new `GLDisplayEGL` using the default EGL_DEFAULT_DISPLAY. - -# Returns - -a new `GLDisplayEGL` or `None` - -Creates a EGL display connection from a native Display. - -This function will return the same value for multiple calls with the same -`display`. -## `display` -an existing `gst_gl::GLDisplay` - -# Returns - -a new `GLDisplayEGL` - -Attempts to create a new `EGLDisplay` from `display`. If `type_` is -`gst_gl::GLDisplayType::Any`, then `display` must be 0. `type_` must not be -`gst_gl::GLDisplayType::None`. -## `type_` -a `gst_gl::GLDisplayType` -## `display` -pointer to a display (or 0) - -# Returns - -A `EGLDisplay` or `EGL_NO_DISPLAY` diff --git a/docs/gstreamer-gl/wayland/docs.md b/docs/gstreamer-gl/wayland/docs.md deleted file mode 100644 index 88056b18c..000000000 --- a/docs/gstreamer-gl/wayland/docs.md +++ /dev/null @@ -1,25 +0,0 @@ - - -the contents of a `GLDisplayWayland` are private and should only be accessed -through the provided API - -# Implements - -[`trait@gst_gl::GLDisplayExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -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 - -# Returns - -a new `GLDisplayWayland` or `None` - -Creates a new display connection from a wl_display Display. -## `display` -an existing, wayland display - -# Returns - -a new `GLDisplayWayland` diff --git a/docs/gstreamer-gl/x11/docs.md b/docs/gstreamer-gl/x11/docs.md deleted file mode 100644 index 4ae63c246..000000000 --- a/docs/gstreamer-gl/x11/docs.md +++ /dev/null @@ -1,25 +0,0 @@ - - -the contents of a `GLDisplayX11` are private and should only be accessed -through the provided API - -# Implements - -[`trait@gst_gl::GLDisplayExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Create a new `GLDisplayX11` from the x11 display name. See `XOpenDisplay`() -for details on what is a valid name. -## `name` -a display name - -# Returns - -a new `GLDisplayX11` or `None` - -Creates a new display connection from a X11 Display. -## `display` -an existing, x11 display - -# Returns - -a new `GLDisplayX11` diff --git a/docs/gstreamer-net/docs.md b/docs/gstreamer-net/docs.md deleted file mode 100644 index 5b72afa02..000000000 --- a/docs/gstreamer-net/docs.md +++ /dev/null @@ -1,140 +0,0 @@ - - -`NetClientClock` implements a custom `gst::Clock` that synchronizes its time -to a remote time provider such as `NetTimeProvider`. `NtpClock` -implements a `gst::Clock` that synchronizes its time to a remote NTPv4 server. - -A new clock is created with `NetClientClock::new` or -`NtpClock::new`, which takes the address and port of the remote time -provider along with a name and an initial time. - -This clock will poll the time provider and will update its calibration -parameters based on the local and remote observations. - -The "round-trip" property limits the maximum round trip packets can take. - -Various parameters of the clock can be configured with the parent `gst::Clock` -"timeout", "window-size" and "window-threshold" object properties. - -A `NetClientClock` and `NtpClock` is typically set on a `gst::Pipeline` with -`gst::Pipeline::use_clock`. - -If you set a `gst::Bus` on the clock via the "bus" object property, it will -send [`crate::gst::MessageType::Element`] (XXX: @-reference does not belong to NetClientClock!) messages with an attached `gst::Structure` containing -statistics about clock accuracy and network traffic. - -# Implements - -[`trait@gst::ClockExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Create a new `NetClientClock` that will report the time -provided by the `NetTimeProvider` on `remote_address` and -`remote_port`. -## `name` -a name for the clock -## `remote_address` -the address or hostname of the remote clock provider -## `remote_port` -the port of the remote clock provider -## `base_time` -initial time of the clock - -# Returns - -a new `gst::Clock` that receives a time from the remote -clock. - -This object exposes the time of a `gst::Clock` on the network. - -A `NetTimeProvider` is created with `NetTimeProvider::new` which -takes a `gst::Clock`, an address and a port number as arguments. - -After creating the object, a client clock such as `NetClientClock` can -query the exposed clock over the network for its values. - -The `NetTimeProvider` typically wraps the clock used by a `gst::Pipeline`. - -# Implements - -[`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Allows network clients to get the current time of `clock`. -## `clock` -a `gst::Clock` to export over the network -## `address` -an address to bind on as a dotted quad - (xxx.xxx.xxx.xxx), IPv6 address, or NULL to bind to all addresses -## `port` -a port to bind on, or 0 to let the kernel choose - -# Returns - -the new `NetTimeProvider`, or NULL on error - - - -# Implements - -[`NetClientClockExt`](trait@crate::NetClientClockExt), [`trait@gst::ClockExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Create a new `NtpClock` that will report the time provided by -the NTPv4 server on `remote_address` and `remote_port`. -## `name` -a name for the clock -## `remote_address` -the address or hostname of the remote clock provider -## `remote_port` -the port of the remote clock provider -## `base_time` -initial time of the clock - -# Returns - -a new `gst::Clock` that receives a time from the remote -clock. - -GstPtpClock implements a PTP (IEEE1588:2008) ordinary clock in slave-only -mode, that allows a GStreamer pipeline to synchronize to a PTP network -clock in some specific domain. - -The PTP subsystem can be initialized with `gst_ptp_init`, which then starts -a helper process to do the actual communication via the PTP ports. This is -required as PTP listens on ports < 1024 and thus requires special -privileges. Once this helper process is started, the main process will -synchronize to all PTP domains that are detected on the selected -interfaces. - -`PtpClock::new` then allows to create a GstClock that provides the PTP -time from a master clock inside a specific PTP domain. This clock will only -return valid timestamps once the timestamps in the PTP domain are known. To -check this, you can use `gst::ClockExt::wait_for_sync`, the GstClock::synced -signal and `gst::ClockExt::is_synced`. - -To gather statistics about the PTP clock synchronization, -`gst_ptp_statistics_callback_add` can be used. This gives the application -the possibility to collect all kinds of statistics from the clock -synchronization. - -# Implements - -[`trait@gst::ClockExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Creates a new PTP clock instance that exports the PTP time of the master -clock in `domain`. This clock can be slaved to other clocks as needed. - -If `gst_ptp_init` was not called before, this will call `gst_ptp_init` with -default parameters. - -This clock only returns valid timestamps after it received the first -times from the PTP master clock on the network. Once this happens the -GstPtpClock::internal-clock property will become non-NULL. You can -check this with `gst::ClockExt::wait_for_sync`, the GstClock::synced signal and -`gst::ClockExt::is_synced`. -## `name` -Name of the clock -## `domain` -PTP domain - -# Returns - -A new `gst::Clock` diff --git a/docs/gstreamer-pbutils/docs.md b/docs/gstreamer-pbutils/docs.md deleted file mode 100644 index 925337069..000000000 --- a/docs/gstreamer-pbutils/docs.md +++ /dev/null @@ -1,949 +0,0 @@ - - -The `Discoverer` is a utility object which allows to get as much -information as possible from one or many URIs. - -It provides two APIs, allowing usage in blocking or non-blocking mode. - -The blocking mode just requires calling `Discoverer::discover_uri` -with the URI one wishes to discover. - -The non-blocking mode requires a running `glib::MainLoop` iterating a -`glib::MainContext`, where one connects to the various signals, appends the -URIs to be processed (through `Discoverer::discover_uri_async`) and then -asks for the discovery to begin (through `Discoverer::start`). -By default this will use the GLib default main context unless you have -set a custom context using `glib::MainContext::push_thread_default`. - -All the information is returned in a `DiscovererInfo` structure. - -# Implements - -[`trait@glib::object::ObjectExt`] - -Creates a new `Discoverer` with the provided timeout. -## `timeout` -timeout per file, in nanoseconds. Allowed are values between - one second (`GST_SECOND`) and one hour (3600 * `GST_SECOND`) - -# Returns - -The new `Discoverer`. -If an error occurred when creating the discoverer, `err` will be set -accordingly and `None` will be returned. If `err` is set, the caller must -free it when no longer needed using `glib::Error::free`. - -Synchronously discovers the given `uri`. - -A copy of `uri` will be made internally, so the caller can safely `g_free` -afterwards. -## `uri` -The URI to run on. - -# Returns - -the result of the scanning. Can be `None` if an -error occurred. - -Appends the given `uri` to the list of URIs to discoverer. The actual -discovery of the `uri` will only take place if `Discoverer::start` has -been called. - -A copy of `uri` will be made internally, so the caller can safely `g_free` -afterwards. -## `uri` -the URI to add. - -# Returns - -`true` if the `uri` was successfully appended to the list of pending -uris, else `false` - -Allow asynchronous discovering of URIs to take place. -A `glib::MainLoop` must be available for `Discoverer` to properly work in -asynchronous mode. - -Stop the discovery of any pending URIs and clears the list of -pending URIS (if any). - -Will be emitted in async mode when all information on a URI could be -discovered, or an error occurred. - -When an error occurs, `info` might still contain some partial information, -depending on the circumstances of the error. -## `info` -the results `DiscovererInfo` -## `error` -`glib::Error`, which will be non-NULL - if an error occurred during - discovery. You must not free - this `glib::Error`, it will be freed by - the discoverer. - -Will be emitted in async mode when all pending URIs have been processed. - -This signal is emitted after the source element has been created for, so -the URI being discovered, so it can be configured by setting additional -properties (e.g. set a proxy server for an http source, or set the device -and read speed for an audio cd source). - -This signal is usually emitted from the context of a GStreamer streaming -thread. -## `source` -source element - -Will be emitted when the discover starts analyzing the pending URIs - -The duration (in nanoseconds) after which the discovery of an individual -URI will timeout. - -If the discovery of a URI times out, the `DiscovererResult::Timeout` will be -set on the result flags. - -The duration (in nanoseconds) after which the discovery of an individual -URI will timeout. - -If the discovery of a URI times out, the `DiscovererResult::Timeout` will be -set on the result flags. - -`DiscovererStreamInfo` specific to audio streams. - -# Implements - -[`DiscovererStreamInfoExt`](trait@crate::DiscovererStreamInfoExt), [`trait@glib::object::ObjectExt`] - - -# Returns - -the average or nominal bitrate of the stream in bits/second. - - -Feature: `v1_14` - - -# Returns - -the channel-mask of the stream, refer to -`gst_audio_channel_positions_from_mask` for more -information. - - -# Returns - -the number of channels in the stream. - - -# Returns - -the number of bits used per sample in each channel. - - -# Returns - -the language of the stream, or NULL if unknown. - - -# Returns - -the maximum bitrate of the stream in bits/second. - - -# Returns - -the sample rate of the stream in Hertz. - -`DiscovererStreamInfo` specific to container streams. - -# Implements - -[`DiscovererStreamInfoExt`](trait@crate::DiscovererStreamInfoExt), [`trait@glib::object::ObjectExt`] - - -# Returns - -the list of -`DiscovererStreamInfo` this container stream offers. -Free with `DiscovererStreamInfo::list_free` after usage. - -Structure containing the information of a URI analyzed by `Discoverer`. - -# Implements - -[`trait@glib::object::ObjectExt`] - -Parses a `glib::Variant` as produced by `DiscovererInfo::to_variant` -back to a `DiscovererInfo`. -## `variant` -A `glib::Variant` to deserialize into a `DiscovererInfo`. - -# Returns - -A newly-allocated `DiscovererInfo`. - - -# Returns - -A copy of the `DiscovererInfo` - -Finds all the `DiscovererAudioInfo` contained in `self` - -# Returns - -A `glib::List` of -matching `DiscovererStreamInfo`. The caller should free it with -`DiscovererStreamInfo::list_free`. - -Finds all the `DiscovererContainerInfo` contained in `self` - -# Returns - -A `glib::List` of -matching `DiscovererStreamInfo`. The caller should free it with -`DiscovererStreamInfo::list_free`. - - -# Returns - -the duration of the URI in `gst::ClockTime` (nanoseconds). - - -Feature: `v1_14` - - -# Returns - -whether the URI is live. - - -# Deprecated - -This functions is deprecated since version 1.4, use -`DiscovererInfo::get_missing_elements_installer_details` - -# Returns - -Miscellaneous information stored as a `gst::Structure` -(for example: information about missing plugins). If you wish to use the -`gst::Structure` after the life-time of `self`, you will need to copy it. - -Get the installer details for missing elements - -# Returns - -An array of strings -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. - - -# Returns - -the result of the discovery as a `DiscovererResult`. - - -# Returns - -the whether the URI is seekable. - - -# Returns - -the structure (or topology) of the URI as a -`DiscovererStreamInfo`. -This structure can be traversed to see the original hierarchy. Unref with -`gst_discoverer_stream_info_unref` after usage. - - -# Returns - -the list of -all streams contained in the `info`. Free after usage -with `DiscovererStreamInfo::list_free`. - -Finds the `DiscovererStreamInfo` contained in `self` that match the -given `streamtype`. -## `streamtype` -a `glib::Type` derived from `DiscovererStreamInfo` - -# Returns - -A `glib::List` of -matching `DiscovererStreamInfo`. The caller should free it with -`DiscovererStreamInfo::list_free`. - -Finds all the `DiscovererSubtitleInfo` contained in `self` - -# Returns - -A `glib::List` of -matching `DiscovererStreamInfo`. The caller should free it with -`DiscovererStreamInfo::list_free`. - - -# Returns - -all tags contained in the URI. If you wish to use -the tags after the life-time of `self`, you will need to copy them. - - -# Returns - -TOC contained in the URI. If you wish to use -the TOC after the life-time of `self`, you will need to copy it. - - -# Returns - -the URI to which this information corresponds to. -Copy it if you wish to use it after the life-time of `self`. - -Finds all the `DiscovererVideoInfo` contained in `self` - -# Returns - -A `glib::List` of -matching `DiscovererStreamInfo`. The caller should free it with -`DiscovererStreamInfo::list_free`. - -Serializes `self` to a `glib::Variant` that can be parsed again -through `DiscovererInfo::from_variant`. - -Note that any `gst::Toc` (s) that might have been discovered will not be serialized -for now. -## `flags` -A combination of `DiscovererSerializeFlags` to specify -what needs to be serialized. - -# Returns - -A newly-allocated `glib::Variant` representing `self`. - -Result values for the discovery process. - -The discovery was successful - -the URI is invalid - -an error happened and the GError is set - -the discovery timed-out - -the discoverer was already discovering a file - -Some plugins are missing for full discovery - -You can use these flags to control what is serialized by -`DiscovererInfo::to_variant` - -Serialize only basic information, excluding -caps, tags and miscellaneous information - -Serialize the caps for each stream - -Serialize the tags for each stream - -Serialize miscellaneous information for each stream - -Serialize all the available info, including -caps, tags and miscellaneous information - -Base structure for information concerning a media stream. Depending on the -stream type, one can find more media-specific information in -`DiscovererAudioInfo`, `DiscovererVideoInfo`, and -`DiscovererContainerInfo`. - -The `DiscovererStreamInfo` represents the topology of the stream. Siblings -can be iterated over with `DiscovererStreamInfoExt::get_next` and -`DiscovererStreamInfoExt::get_previous`. Children (sub-streams) of a -stream can be accessed using the `DiscovererContainerInfo` API. - -As a simple example, if you run `Discoverer` on an AVI file with one audio -and one video stream, you will get a `DiscovererContainerInfo` -corresponding to the AVI container, which in turn will have a -`DiscovererAudioInfo` sub-stream and a `DiscovererVideoInfo` sub-stream -for the audio and video streams respectively. - -# Implements - -[`DiscovererStreamInfoExt`](trait@crate::DiscovererStreamInfoExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `DiscovererStreamInfo` methods. - -# Implementors - -[`DiscovererAudioInfo`](struct@crate::DiscovererAudioInfo), [`DiscovererContainerInfo`](struct@crate::DiscovererContainerInfo), [`DiscovererStreamInfo`](struct@crate::DiscovererStreamInfo), [`DiscovererSubtitleInfo`](struct@crate::DiscovererSubtitleInfo), [`DiscovererVideoInfo`](struct@crate::DiscovererVideoInfo) - -Decrements the reference count of all contained `DiscovererStreamInfo` -and fress the `glib::List`. -## `infos` -a `glib::List` of `DiscovererStreamInfo` - - -# Returns - -the `gst::Caps` of the stream. Unref with -`gst_caps_unref` after usage. - - -# Deprecated - -This functions is deprecated since version 1.4, use -`DiscovererInfo::get_missing_elements_installer_details` - -# Returns - -additional information regarding the stream (for -example codec version, profile, etc..). If you wish to use the `gst::Structure` -after the life-time of `self` you will need to copy it. - - -# Returns - -the next `DiscovererStreamInfo` in a chain. `None` -for final streams. -Unref with `gst_discoverer_stream_info_unref` after usage. - - -# Returns - -the previous `DiscovererStreamInfo` in a chain. -`None` for starting points. Unref with `gst_discoverer_stream_info_unref` -after usage. - - -# Returns - -the stream ID of this stream. If you wish to -use the stream ID after the life-time of `self` you will need to copy it. - - -# Returns - -a human readable name for the stream type of the given `self` (ex : "audio", -"container",...). - - -# Returns - -the tags contained in this stream. If you wish to -use the tags after the life-time of `self` you will need to copy them. - - -# Returns - -the TOC contained in this stream. If you wish to -use the TOC after the life-time of `self` you will need to copy it. - -`DiscovererStreamInfo` specific to subtitle streams (this includes text and -image based ones). - -# Implements - -[`DiscovererStreamInfoExt`](trait@crate::DiscovererStreamInfoExt), [`trait@glib::object::ObjectExt`] - - -# Returns - -the language of the stream, or NULL if unknown. - -`DiscovererStreamInfo` specific to video streams (this includes images). - -# Implements - -[`DiscovererStreamInfoExt`](trait@crate::DiscovererStreamInfoExt), [`trait@glib::object::ObjectExt`] - - -# Returns - -the average or nominal bitrate of the video stream in bits/second. - - -# Returns - -the depth in bits of the video stream. - - -# Returns - -the framerate of the video stream (denominator). - - -# Returns - -the framerate of the video stream (numerator). - - -# Returns - -the height of the video stream in pixels. - - -# Returns - -the maximum bitrate of the video stream in bits/second. - - -# Returns - -the Pixel Aspect Ratio (PAR) of the video stream (denominator). - - -# Returns - -the Pixel Aspect Ratio (PAR) of the video stream (numerator). - - -# Returns - -the width of the video stream in pixels. - - -# Returns - -`true` if the video stream corresponds to an image (i.e. only contains -one frame). - - -# Returns - -`true` if the stream is interlaced, else `false`. - -Variant of `EncodingProfile` for audio streams. - -# Implements - -[`EncodingProfileExt`](trait@crate::EncodingProfileExt), [`trait@glib::object::ObjectExt`] - -Creates a new `EncodingAudioProfile` - -All provided allocatable arguments will be internally copied, so can be -safely freed/unreferenced after calling this method. -## `format` -the `gst::Caps` -## `preset` -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 `EncodingProfile::get_restriction` for more details. -## `presence` -the number of time this stream must be used. 0 means any number of - times (including never) - -# Returns - -the newly created `EncodingAudioProfile`. - -Encoding profiles for containers. Keeps track of a list of `EncodingProfile` - -# Implements - -[`EncodingProfileExt`](trait@crate::EncodingProfileExt), [`trait@glib::object::ObjectExt`] - -Creates a new `EncodingContainerProfile`. -## `name` -The name of the container profile, can be `None` -## `description` -The description of the container profile, - can be `None` -## `format` -The format to use for this profile -## `preset` -The preset to use for this profile. - -# Returns - -The newly created `EncodingContainerProfile`. - -Add a `EncodingProfile` to the list of profiles handled by `self`. - -No copy of `profile` will be made, if you wish to use it elsewhere after this -method you should increment its reference count. -## `profile` -the `EncodingProfile` to add. - -# Returns - -`true` if the `stream` was properly added, else `false`. - -Checks if `self` contains a `EncodingProfile` identical to -`profile`. -## `profile` -a `EncodingProfile` - -# Returns - -`true` if `self` contains a `EncodingProfile` identical -to `profile`, else `false`. - - -# Returns - - -the list of contained `EncodingProfile`. - -The opaque base class object for all encoding profiles. This contains generic -information like name, description, format and preset. - -# Implements - -[`EncodingProfileExt`](trait@crate::EncodingProfileExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `EncodingProfile` methods. - -# Implementors - -[`EncodingAudioProfile`](struct@crate::EncodingAudioProfile), [`EncodingContainerProfile`](struct@crate::EncodingContainerProfile), [`EncodingProfile`](struct@crate::EncodingProfile), [`EncodingVideoProfile`](struct@crate::EncodingVideoProfile) - -Find the `EncodingProfile` with the specified name and category. -## `targetname` -The name of the target -## `profilename` -The name of the profile, if `None` -provided, it will default to the encoding profile called `default`. -## `category` -The target category. Can be `None` - -# Returns - -The matching `EncodingProfile` or `None`. - -Creates a `EncodingProfile` matching the formats from the given -`DiscovererInfo`. Streams other than audio or video (eg, -subtitles), are currently ignored. -## `info` -The `DiscovererInfo` to read from - -# Returns - -The new `EncodingProfile` or `None`. - -Makes a deep copy of `self` - -Feature: `v1_12` - - -# Returns - -The copy of `self` - -Get whether the format that has been negotiated in at some point can be renegotiated -later during the encoding. - - -# Returns - -the description of the profile, can be `None`. - - -# Returns - -a suitable file extension for `self`, or NULL. - - -# Returns - -the `gst::Caps` corresponding to the media format used -in the profile. Unref after usage. - -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. - - -# Returns - -the name of the profile, can be `None`. - - -# Returns - -The number of times the profile is used in its parent -container profile. If 0, it is not a mandatory stream. - - -# Returns - -the name of the `gst::Preset` to be used in the profile. -This is the name that has been set when saving the preset. - - -# Returns - -the name of the `gst::Preset` factory to be used in the profile. - - -# Returns - -The restriction `gst::Caps` to apply before the encoder -that will be used in the profile. The fields present in restriction caps are -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 - -the human-readable name of the type of `self`. - -Checks whether the two `EncodingProfile` are equal -## `b` -a `EncodingProfile` - -# Returns - -`true` if `self` and `b` are equal, else `false`. - -Sets whether the format that has been negotiated in at some point can be renegotiated -later during the encoding. -## `allow_dynamic_output` -Whether the format that has been negotiated first can be renegotiated -during the encoding - -Set `description` as the given description for the `self`. A copy of -`description` will be made internally. -## `description` -the description to set on the profile - -Set whether the profile should be used or not. -## `enabled` -`false` to disable `self`, `true` to enable it - -Sets the media format used in the profile. -## `format` -the media format to use in the profile. - -Set `name` as the given name for the `self`. A copy of `name` will be made -internally. -## `name` -the name to set on the profile - -Set the number of time the profile is used in its parent -container profile. If 0, it is not a mandatory stream -## `presence` -the number of time the profile can be used - -Sets the name of the `gst::Element` that implements the `gst::Preset` interface -to use for the profile. -This is the name that has been set when saving the preset. -## `preset` -the element preset to use - -Sets the name of the `gst::Preset`'s factory to be used in the profile. -## `preset_name` -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 `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. - -> *NOTE*: Single segment is not property supported when using -> `encodebin:avoid-reencoding` - -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. - -When being stored/loaded, targets come from a specific category, like -`GST_ENCODING_CATEGORY_DEVICE`. - -# Implements - -[`trait@glib::object::ObjectExt`] - -Creates a new `EncodingTarget`. - -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 -well-defined categories, like `GST_ENCODING_CATEGORY_DEVICE`, but it -*can* be a application or user specific category if -needed. -## `name` -The name of the target. -## `category` -The name of the category to which this `target` -belongs. For example: `GST_ENCODING_CATEGORY_DEVICE`. -## `description` -A description of `EncodingTarget` in the -current locale. -## `profiles` -A `glib::List` of -`EncodingProfile`. - -# Returns - -The newly created `EncodingTarget` or `None` if -there was an error. - -Searches for the `EncodingTarget` with the given name, loads it -and returns it. - -If the category name is specified only targets from that category will be -searched for. -## `name` -the name of the `EncodingTarget` to load (automatically -converted to lower case internally as capital letters are not -valid for target names). -## `category` -the name of the target category, like -`GST_ENCODING_CATEGORY_DEVICE`. Can be `None` - -# Returns - -The `EncodingTarget` if available, else `None`. - -Opens the provided file and returns the contained `EncodingTarget`. -## `filepath` -The file location to load the `EncodingTarget` from - -# Returns - -The `EncodingTarget` contained in the file, else -`None` - -Adds the given `profile` to the `self`. Each added profile must have -a unique name within the profile. - -The `self` will steal a reference to the `profile`. If you wish to use -the profile after calling this method, you should increase its reference -count. -## `profile` -the `EncodingProfile` to add - -# Returns - -`true` if the profile was added, else `false`. - - -# Returns - -The category of the `self`. For example: -`GST_ENCODING_CATEGORY_DEVICE`. - - -# Returns - -The description of the `self`. - - -# Returns - -The name of the `self`. - - -Feature: `v1_18` - - -# Returns - -The path to the `self` file. - -## `name` -the name of the profile to retrieve - -# Returns - -The matching `EncodingProfile`, or `None`. - - -# Returns - -A list of -`EncodingProfile`(s) this `self` handles. - -Saves the `self` to a default user-local directory. - -# Returns - -`true` if the target was correctly saved, else `false`. - -Saves the `self` to the provided file location. -## `filepath` -the location to store the `self` at. - -# Returns - -`true` if the target was correctly saved, else `false`. - -Variant of `EncodingProfile` for video streams, allows specifying the `pass`. - -# Implements - -[`EncodingProfileExt`](trait@crate::EncodingProfileExt), [`trait@glib::object::ObjectExt`] - -Creates a new `EncodingVideoProfile` - -All provided allocatable arguments will be internally copied, so can be -safely freed/unreferenced after calling this method. - -If you wish to control the pass number (in case of multi-pass scenarios), -please refer to the `EncodingVideoProfile::set_pass` documentation. - -If you wish to use/force a constant framerate please refer to the -`EncodingVideoProfile::set_variableframerate` documentation. -## `format` -the `gst::Caps` -## `preset` -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 `EncodingProfile::get_restriction` for more details. -## `presence` -the number of time this stream must be used. 0 means any number of - times (including never) - -# Returns - -the newly created `EncodingVideoProfile`. - -Get the pass number if this is part of a multi-pass profile. - -# Returns - -The pass number. Starts at 1 for multi-pass. 0 if this is -not a multi-pass profile - -> *NOTE*: Fixed framerate won't be enforced when `encodebin:avoid-reencoding` -> is set. - -# Returns - -Whether non-constant video framerate is allowed for encoding. - -Sets the pass number of this video profile. The first pass profile should have -this value set to 1. If this video profile isn't part of a multi-pass profile, -you may set it to 0 (the default value). -## `pass` -the pass number for this profile - -If set to `true`, then the incoming stream will be allowed to have non-constant -framerate. If set to `false` (default value), then the incoming stream will -be normalized by dropping/duplicating frames in order to produce a -constance framerate. -## `variableframerate` -a boolean diff --git a/docs/gstreamer-player/docs.md b/docs/gstreamer-player/docs.md deleted file mode 100644 index 9e0deaeb8..000000000 --- a/docs/gstreamer-player/docs.md +++ /dev/null @@ -1,742 +0,0 @@ - - - - -# Implements - -[`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Creates a new `Player` instance that uses `signal_dispatcher` to dispatch -signals to some event loop system, or emits signals directly if NULL is -passed. See `PlayerGMainContextSignalDispatcher::new`. - -Video is going to be rendered by `video_renderer`, or if `None` is provided -no special video set up will be done and some default handling will be -performed. -## `video_renderer` -GstPlayerVideoRenderer to use -## `signal_dispatcher` -GstPlayerSignalDispatcher to use - -# Returns - -a new `Player` instance - -## `config` -a `Player` configuration - -# Returns - -current position update interval in milliseconds - -## `config` -a `Player` configuration - -# Returns - -`true` if accurate seeking is enabled - -Return the user agent which has been configured using -`Player::config_set_user_agent` if any. -## `config` -a `Player` configuration - -# Returns - -the configured agent, or `None` - -set interval in milliseconds between two position-updated signals. -pass 0 to stop updating the position. -## `config` -a `Player` configuration -## `interval` -interval in ms - -Enable or disable accurate seeking. When enabled, elements will try harder -to seek as accurately as possible to the requested seek position. Generally -it will be slower especially for formats that don't have any indexes or -timestamp markers in the stream. - -If accurate seeking is disabled, elements will seek as close as the request -position without slowing down seeking too much. - -Accurate seeking is disabled by default. -## `config` -a `Player` configuration -## `accurate` -accurate seek or not - -Set the user agent to pass to the server if `player` needs to connect -to a server during playback. This is typically used when playing HTTP -or RTSP streams. -## `config` -a `Player` configuration -## `agent` -the string to use as user agent - -## `info` -a `PlayerMediaInfo` - -# Returns - -A `glib::List` of -matching `PlayerAudioInfo`. - -## `info` -a `PlayerMediaInfo` - -# Returns - -A `glib::List` of -matching `PlayerSubtitleInfo`. - -## `info` -a `PlayerMediaInfo` - -# Returns - -A `glib::List` of -matching `PlayerVideoInfo`. - -Frees a `None` terminated array of `PlayerVisualization`. -## `viss` -a `None` terminated array of `PlayerVisualization` to free - - -# Returns - - - a `None` terminated array containing all available - visualizations. Use `Player::visualizations_free` after - usage. - -Retrieve the current value of audio-video-offset property - -# Returns - -The current value of audio-video-offset in nanoseconds - -Retrieve the current value of the indicated `type_`. -## `type_` -`PlayerColorBalanceType` - -# Returns - -The current value of `type_`, between [0,1]. In case of - error -1 is returned. - -Get a copy of the current configuration of the player. This configuration -can either be modified and used for the `Player::set_config` call -or it must be freed after usage. - -# Returns - -a copy of the current configuration of `self`. Use -`gst::Structure::free` after usage or `Player::set_config`. - -A Function to get current audio `PlayerAudioInfo` instance. - -# Returns - -current audio track. - -The caller should free it with `glib::object::ObjectExt::unref` - -A Function to get current subtitle `PlayerSubtitleInfo` instance. - -# Returns - -current subtitle track. - -The caller should free it with `glib::object::ObjectExt::unref` - -A Function to get current video `PlayerVideoInfo` instance. - -# Returns - -current video track. - -The caller should free it with `glib::object::ObjectExt::unref` - - -# Returns - -Name of the currently enabled visualization. - `g_free` after usage. - -Retrieves the duration of the media stream that self represents. - -# Returns - -the duration of the currently-playing media stream, in -nanoseconds. - -A Function to get the current media info `PlayerMediaInfo` instance. - -# Returns - -media info instance. - -The caller should free it with `glib::object::ObjectExt::unref` - -Retrieve the current value of the indicated `type_`. - -# Returns - -The current value of `type_`, Default: 0x00000000 "none - -Retrieve the current value of the indicated `type_`. - -# Returns - -The current value of `type_`, Default: -1 "none" - - -# Returns - -`true` if the currently-playing stream is muted. - - -# Returns - -The internal playbin instance - - -# Returns - -the absolute position time, in nanoseconds, of the -currently-playing stream. - - -# Returns - -current playback rate - -current subtitle URI - -# Returns - -URI of the current external subtitle. - `g_free` after usage. - -Retrieve the current value of subtitle-video-offset property - -Feature: `v1_16` - - -# Returns - -The current value of subtitle-video-offset in nanoseconds - -Gets the URI of the currently-playing stream. - -# Returns - -a string containing the URI of the -currently-playing stream. `g_free` after usage. - -Get a snapshot of the currently selected video stream, if any. The format can be -selected with `format` and optional configuration is possible with `config` -Currently supported settings are: -- width, height of type G_TYPE_INT -- pixel-aspect-ratio of type GST_TYPE_FRACTION - Except for GST_PLAYER_THUMBNAIL_RAW_NATIVE format, if no config is set, pixel-aspect-ratio would be 1/1 -## `format` -output format of the video snapshot -## `config` -Additional configuration - -# Returns - -Current video snapshot sample or `None` on failure - -Returns the current volume level, as a percentage between 0 and 1. - -# Returns - -the volume as percentage between 0 and 1. - -Checks whether the `self` has color balance support available. - -# Returns - -`true` if `self` has color balance support. Otherwise, - `false`. - -Pauses the current stream. - -Request to play the loaded stream. - -Seeks the currently-playing stream to the absolute `position` time -in nanoseconds. -## `position` -position to seek in nanoseconds - -## `stream_index` -stream index - -# Returns - -`true` or `false` - -Sets the audio track `stream_idex`. - -Enable or disable the current audio track. -## `enabled` -TRUE or FALSE - -Sets audio-video-offset property by value of `offset` -## `offset` -`gint64` in nanoseconds - -Sets the current value of the indicated channel `type_` to the passed -value. -## `type_` -`PlayerColorBalanceType` -## `value` -The new value for the `type_`, ranged [0,1] - -Set the configuration of the player. If the player is already configured, and -the configuration haven't change, this function will return `true`. If the -player is not in the GST_PLAYER_STATE_STOPPED, this method will return `false` -and active configuration will remain. - -`config` is a `gst::Structure` that contains the configuration parameters for -the player. - -This function takes ownership of `config`. -## `config` -a `gst::Structure` - -# Returns - -`true` when the configuration could be set. - -Sets the current value of the indicated mode `type_` to the passed -value. -## `flags` -The new value for the `type_` - -Sets the current value of the indicated mode `type_` to the passed -value. -## `mode` -The new value for the `type_` - -`true` if the currently-playing stream should be muted. -## `val` -Mute state the should be set - -Playback at specified rate -## `rate` -playback rate - -## `stream_index` -stream index - -# Returns - -`true` or `false` - -Sets the subtitle stack `stream_index`. - -Enable or disable the current subtitle track. -## `enabled` -TRUE or FALSE - -Sets the external subtitle URI. This should be combined with a call to -gst_player_set_subtitle_track_enabled(`self`, TRUE) so the subtitles are actually -rendered. -## `uri` -subtitle URI - -Sets subtitle-video-offset property by value of `offset` - -Feature: `v1_16` - -## `offset` -`gint64` in nanoseconds - -Sets the next URI to play. -## `uri` -next URI to play. - -## `stream_index` -stream index - -# Returns - -`true` or `false` - -Sets the video track `stream_index`. - -Enable or disable the current video track. -## `enabled` -TRUE or FALSE - -## `name` -visualization element obtained from -`Player::visualizations_get`() - -# Returns - -`true` if the visualizations was set correctly. Otherwise, -`false`. - -Enable or disable the visualization. -## `enabled` -TRUE or FALSE - -Sets the volume level of the stream as a percentage between 0 and 1. -## `val` -the new volume level, as a percentage between 0 and 1 - -Stops playing the current stream and resets to the first position -in the stream. - -`PlayerStreamInfo` specific to audio streams. - -# Implements - -[`PlayerStreamInfoExt`](trait@crate::PlayerStreamInfoExt), [`trait@glib::object::ObjectExt`] - - -# Returns - -the audio bitrate in `PlayerAudioInfo`. - - -# Returns - -the number of audio channels in `PlayerAudioInfo`. - - -# Returns - -the language of the stream, or NULL if unknown. - - -# Returns - -the audio maximum bitrate in `PlayerAudioInfo`. - - -# Returns - -the audio sample rate in `PlayerAudioInfo`. - - -hue or color balance. - -brightness or black level. - -color saturation or chroma -gain. - -contrast or luma gain. - - -generic error. - - - -# Implements - -[`trait@glib::object::ObjectExt`], [`PlayerSignalDispatcherExt`](trait@crate::PlayerSignalDispatcherExt) - -Creates a new GstPlayerSignalDispatcher that uses `application_context`, -or the thread default one if `None` is used. See `Player::new`. -## `application_context` -GMainContext to use or `None` - -# Returns - -the new GstPlayerSignalDispatcher - -Structure containing the media information of a URI. - -# Implements - -[`trait@glib::object::ObjectExt`] - - -# Returns - -A `glib::List` of -matching `PlayerAudioInfo`. - - -# Returns - -the container format. - - -# Returns - -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. - -# Returns - -GstSample or NULL. - - -# Returns - -number of audio streams. - - -# Returns - -number of total streams. - - -# Returns - -number of subtitle streams. - - -# Returns - -number of video streams. - - -# Returns - -A `glib::List` of -matching `PlayerStreamInfo`. - - -# Returns - -A `glib::List` of -matching `PlayerSubtitleInfo`. - - -# Returns - -the tags contained in media info. - - -# Returns - -the media title. - - -# Returns - -the URI associated with `PlayerMediaInfo`. - - -# Returns - -A `glib::List` of -matching `PlayerVideoInfo`. - - -# Returns - -`true` if the media is live. - - -# Returns - -`true` if the media is seekable. - - - -# Implements - -[`PlayerSignalDispatcherExt`](trait@crate::PlayerSignalDispatcherExt) - -Trait containing all `PlayerSignalDispatcher` methods. - -# Implementors - -[`PlayerGMainContextSignalDispatcher`](struct@crate::PlayerGMainContextSignalDispatcher), [`PlayerSignalDispatcher`](struct@crate::PlayerSignalDispatcher) - - - -the player is stopped. - -the player is buffering. - -the player is paused. - -the player is currently playing a -stream. - -Base structure for information concerning a media stream. Depending on -the stream type, one can find more media-specific information in -`PlayerVideoInfo`, `PlayerAudioInfo`, `PlayerSubtitleInfo`. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`PlayerStreamInfoExt`](trait@crate::PlayerStreamInfoExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `PlayerStreamInfo` methods. - -# Implementors - -[`PlayerAudioInfo`](struct@crate::PlayerAudioInfo), [`PlayerStreamInfo`](struct@crate::PlayerStreamInfo), [`PlayerSubtitleInfo`](struct@crate::PlayerSubtitleInfo), [`PlayerVideoInfo`](struct@crate::PlayerVideoInfo) - - -# Returns - -the `gst::Caps` of the stream. - -A string describing codec used in `PlayerStreamInfo`. - -# Returns - -codec string or NULL on unknown. - -Function to get stream index from `PlayerStreamInfo` instance. - -# Returns - -the stream index of this stream. - -Function to return human readable name for the stream type -of the given `self` (ex: "audio", "video", "subtitle") - -# Returns - -a human readable name - - -# Returns - -the tags contained in this stream. - -`PlayerStreamInfo` specific to subtitle streams. - -# Implements - -[`PlayerStreamInfoExt`](trait@crate::PlayerStreamInfoExt), [`trait@glib::object::ObjectExt`] - - -# Returns - -the language of the stream, or NULL if unknown. - -`PlayerStreamInfo` specific to video streams. - -# Implements - -[`PlayerStreamInfoExt`](trait@crate::PlayerStreamInfoExt), [`trait@glib::object::ObjectExt`] - - -# Returns - -the current bitrate of video in `PlayerVideoInfo`. - -## `fps_n` -Numerator of frame rate -## `fps_d` -Denominator of frame rate - - -# Returns - -the height of video in `PlayerVideoInfo`. - - -# Returns - -the maximum bitrate of video in `PlayerVideoInfo`. - -Returns the pixel aspect ratio in `par_n` and `par_d` -## `par_n` -numerator -## `par_d` -denominator - - -# Returns - -the width of video in `PlayerVideoInfo`. - - - -# Implements - -[`trait@glib::object::ObjectExt`], [`PlayerVideoRendererExt`](trait@crate::PlayerVideoRendererExt) - -## `window_handle` -Window handle to use or `None` - -## `window_handle` -Window handle to use or `None` -## `video_sink` -the custom video_sink element to be set for the video renderer - -Tell an overlay that it has been exposed. This will redraw the current frame -in the drawable even if the pipeline is PAUSED. - -Return the currently configured render rectangle. See `PlayerVideoOverlayVideoRenderer::set_render_rectangle` -for details. -## `x` -the horizontal offset of the render area inside the window -## `y` -the vertical offset of the render area inside the window -## `width` -the width of the render area inside the window -## `height` -the height of the render area inside the window - - -# Returns - -The currently set, platform specific window -handle - -Configure a subregion as a video target within the window set by -`PlayerVideoOverlayVideoRenderer::set_window_handle`. If this is not -used or not supported the video will fill the area of the window set as the -overlay to 100%. By specifying the rectangle, the video can be overlaid to -a specific region of that window only. After setting the new rectangle one -should call `PlayerVideoOverlayVideoRenderer::expose` to force a -redraw. To unset the region pass -1 for the `width` and `height` parameters. - -This method is needed for non fullscreen video overlay in UI toolkits that -do not support subwindows. -## `x` -the horizontal offset of the render area inside the window -## `y` -the vertical offset of the render area inside the window -## `width` -the width of the render area inside the window -## `height` -the height of the render area inside the window - -Sets the platform specific window handle into which the video -should be rendered -## `window_handle` -handle referencing to the platform specific window - - - -# Implements - -[`PlayerVideoRendererExt`](trait@crate::PlayerVideoRendererExt) - -Trait containing all `PlayerVideoRenderer` methods. - -# Implementors - -[`PlayerVideoOverlayVideoRenderer`](struct@crate::PlayerVideoOverlayVideoRenderer), [`PlayerVideoRenderer`](struct@crate::PlayerVideoRenderer) - -A `PlayerVisualization` descriptor. - -Makes a copy of the `PlayerVisualization`. The result must be -freed using `PlayerVisualization::free`. - -# Returns - -an allocated copy of `self`. - -Frees a `PlayerVisualization`. diff --git a/docs/gstreamer-rtp/docs.md b/docs/gstreamer-rtp/docs.md deleted file mode 100644 index 57a6d5e87..000000000 --- a/docs/gstreamer-rtp/docs.md +++ /dev/null @@ -1,199 +0,0 @@ - - -Different types of feedback messages. - -Invalid type - -Generic NACK - -Temporary Maximum Media Stream Bit Rate Request - -Temporary Maximum Media Stream Bit Rate - Notification - -Request an SR packet for early - synchronization - -Picture Loss Indication - -Slice Loss Indication - -Reference Picture Selection Indication - -Application layer Feedback - -Full Intra Request Command - -Temporal-Spatial Trade-off Request - -Temporal-Spatial Trade-off Notification - -Video Back Channel Message - -Different types of SDES content. - -Invalid SDES entry - -End of SDES list - -Canonical name - -User name - -User's electronic mail address - -User's phone number - -Geographic user location - -Name of application or tool - -Notice about the source - -Private extensions - -Different RTCP packet types. - -Invalid type - -Sender report - -Receiver report - -Source description - -Goodbye - -Application defined - -Transport layer feedback. - -Payload-specific feedback. - -Extended report. - -Types of RTCP Extended Reports, those are defined in RFC 3611 and other RFCs -according to the [IANA registry](https://www.iana.org/assignments/rtcp-xr-block-types/rtcp-xr-block-types.xhtml). - -Invalid XR Report Block - -Loss RLE Report Block - -Duplicate RLE Report Block - -Packet Receipt Times Report Block - -Receiver Reference Time Report Block - -Delay since the last Receiver Report - -Statistics Summary Report Block - -VoIP Metrics Report Block - -Feature: `v1_16` - - -Additional RTP buffer flags. These flags can potentially be used on any -buffers carrying RTP packets. - -Note that these are only valid for `gst::Caps` of type: application/x-rtp (x-rtcp). -They can conflict with other extended buffer flags. - -The `gst::Buffer` was once wrapped - in a retransmitted packet as specified by RFC 4588. - -The packet represents redundant RTP packet. - The flag is used in gstrtpstorage to be able to hold the packetback - and use it only for recovery from packet loss. - Since: 1.14 - -Offset to define more flags. - -Feature: `v1_10` - - -Additional mapping flags for `RTPBuffer::map`. - -Skip mapping and validation of RTP - padding and RTP pad count when present. Useful for buffers where - the padding may be encrypted. - -Offset to define more flags - -Standard predefined fixed payload types. - -The official list is at: -http://www.iana.org/assignments/rtp-parameters - -Audio: -reserved: 19 -unassigned: 20-23, - -Video: -unassigned: 24, 27, 29, 30, 35-71, 77-95 -Reserved for RTCP conflict avoidance: 72-76 - -ITU-T G.711. mu-law audio (RFC 3551) - -RFC 3551 says reserved - -RFC 3551 says reserved - -GSM audio - -ITU G.723.1 audio - -IMA ADPCM wave type (RFC 3551) - -IMA ADPCM wave type (RFC 3551) - -experimental linear predictive encoding - -ITU-T G.711 A-law audio (RFC 3551) - -ITU-T G.722 (RFC 3551) - -stereo PCM - -mono PCM - -EIA & TIA standard IS-733 - -Comfort Noise (RFC 3389) - -Audio MPEG 1-3. - -ITU-T G.728 Speech coder (RFC 3551) - -IMA ADPCM wave type (RFC 3551) - -IMA ADPCM wave type (RFC 3551) - -ITU-T G.729 Speech coder (RFC 3551) - -See RFC 2029 - -ISO Standards 10918-1 and 10918-2 (RFC 2435) - -nv encoding by Ron Frederick - -ITU-T Recommendation H.261 (RFC 2032) - -Video MPEG 1 & 2 (RFC 2250) - -MPEG-2 transport stream (RFC 2250) - -Video H263 (RFC 2190) - -The transfer profile to use. - -invalid profile - -the Audio/Visual profile (RFC 3551) - -the secure Audio/Visual profile (RFC 3711) - -the Audio/Visual profile with feedback (RFC 4585) - -the secure Audio/Visual profile with feedback (RFC 5124) diff --git a/docs/gstreamer-rtsp-server/docs.md b/docs/gstreamer-rtsp-server/docs.md deleted file mode 100644 index 7a0e2c5c6..000000000 --- a/docs/gstreamer-rtsp-server/docs.md +++ /dev/null @@ -1,3356 +0,0 @@ - - -An address - -Make a copy of `self`. - -# Returns - -a copy of `self`. - -Free `self` and releasing it back into the pool when owned by a -pool. - -Flags used to control allocation of addresses - -no flags - -an IPv4 address - -and IPv6 address - -address with an even port - -a multicast address - -a unicast address - -An address pool, all member are private - -# Implements - -[`RTSPAddressPoolExt`](trait@crate::RTSPAddressPoolExt), [`trait@glib::object::ObjectExt`], [`RTSPAddressPoolExtManual`](trait@crate::RTSPAddressPoolExtManual) - -Trait containing all `RTSPAddressPool` methods. - -# Implementors - -[`RTSPAddressPool`](struct@crate::RTSPAddressPool) - -Make a new `RTSPAddressPool`. - -# Returns - -a new `RTSPAddressPool` - -Take an address and ports from `self`. `flags` can be used to control the -allocation. `n_ports` consecutive ports will be allocated of which the first -one can be found in `port`. -## `flags` -flags -## `n_ports` -the amount of ports - -# Returns - -a `RTSPAddress` that should be freed with -gst_rtsp_address_free after use or `None` when no address could be -acquired. - -Adds the addresses from `min_addess` to `max_address` (inclusive) -to `self`. The valid port range for the addresses will be from `min_port` to -`max_port` inclusive. - -When `ttl` is 0, `min_address` and `max_address` should be unicast addresses. -`min_address` and `max_address` can be set to -`GST_RTSP_ADDRESS_POOL_ANY_IPV4` or `GST_RTSP_ADDRESS_POOL_ANY_IPV6` to bind -to all available IPv4 or IPv6 addresses. - -When `ttl` > 0, `min_address` and `max_address` should be multicast addresses. -## `min_address` -a minimum address to add -## `max_address` -a maximum address to add -## `min_port` -the minimum port -## `max_port` -the maximum port -## `ttl` -a TTL or 0 for unicast addresses - -# Returns - -`true` if the addresses could be added. - -Clear all addresses in `self`. There should be no outstanding -allocations. - -Dump the free and allocated addresses to stdout. - -Used to know if the pool includes any unicast addresses. - -# Returns - -`true` if the pool includes any unicast addresses, `false` otherwise - -Take a specific address and ports from `self`. `n_ports` consecutive -ports will be allocated of which the first one can be found in -`port`. - -If `ttl` is 0, `address` should be a unicast address. If `ttl` > 0, `address` -should be a valid multicast address. -## `ip_address` -The IP address to reserve -## `port` -The first port to reserve -## `n_ports` -The number of ports -## `ttl` -The requested ttl -## `address` -storage for a `RTSPAddress` - -# Returns - -`RTSPAddressPoolResult::Ok` if an address was reserved. The address -is returned in `address` and should be freed with gst_rtsp_address_free -after use. - -Result codes from RTSP address pool functions. - -no error - -invalid arguments were provided to a function - -the addres has already been reserved - -the address is not in the pool - -last error - -The authentication structure. - -# Implements - -[`RTSPAuthExt`](trait@crate::RTSPAuthExt), [`trait@glib::object::ObjectExt`], [`RTSPAuthExtManual`](trait@crate::RTSPAuthExtManual) - -Trait containing all `RTSPAuth` methods. - -# Implementors - -[`RTSPAuth`](struct@crate::RTSPAuth) - -Create a new `RTSPAuth` instance. - -# Returns - -a new `RTSPAuth` - -Check if `check` is allowed in the current context. -## `check` -the item to check - -# Returns - -FALSE if check failed. - -Construct a Basic authorisation token from `user` and `pass`. -## `user` -a userid -## `pass` -a password - -# Returns - -the base64 encoding of the string `user`:`pass`. -`g_free` after usage. - -Add a basic token for the default authentication algorithm that -enables the client with privileges listed in `token`. -## `basic` -the basic token -## `token` -authorisation token - -Add a digest `user` and `pass` for the default authentication algorithm that -enables the client with privileges listed in `token`. - -Feature: `v1_12` - -## `user` -the digest user name -## `pass` -the digest password -## `token` -authorisation token - -Get the default token for `self`. This token will be used for unauthenticated -users. - -# Returns - -the `RTSPToken` of `self`. `gst_rtsp_token_unref` after -usage. - - -Feature: `v1_16` - - -# Returns - -the `realm` of `self` - -Gets the supported authentication methods of `self`. - -Feature: `v1_12` - - -# Returns - -The supported authentication methods - -Get the `gio::TlsAuthenticationMode`. - -# Returns - -the `gio::TlsAuthenticationMode`. - -Get the `gio::TlsCertificate` used for negotiating TLS `self`. - -# Returns - -the `gio::TlsCertificate` of `self`. `glib::object::ObjectExt::unref` after -usage. - -Get the `gio::TlsDatabase` used for verifying client certificate. - -# Returns - -the `gio::TlsDatabase` of `self`. `glib::object::ObjectExt::unref` after -usage. - -Parse the contents of the file at `path` and enable the privileges -listed in `token` for the users it describes. - -The format of the file is expected to match the format described by -, -as output by the `htdigest` command. - -Feature: `v1_16` - -## `path` -Path to the htdigest file -## `token` -authorisation token - -# Returns - -`true` if the file was successfully parsed, `false` otherwise. - -Removes `basic` authentication token. -## `basic` -the basic token - -Removes a digest user. - -Feature: `v1_12` - -## `user` -the digest user name - -Set the default `RTSPToken` to `token` in `self`. The default token will -be used for unauthenticated users. -## `token` -a `RTSPToken` - -Set the `realm` of `self` - -Feature: `v1_16` - - -Sets the supported authentication `methods` for `self`. - -Feature: `v1_12` - -## `methods` -supported methods - -The `gio::TlsAuthenticationMode` to set on the underlying GTlsServerConnection. -When set to another value than `gio::TlsAuthenticationMode::None`, -`RTSPAuth::accept-certificate` signal will be emitted and must be handled. -## `mode` -a `gio::TlsAuthenticationMode` - -Set the TLS certificate for the auth. Client connections will only -be accepted when TLS is negotiated. -## `cert` -a `gio::TlsCertificate` - -Sets the certificate database that is used to verify peer certificates. -If set to `None` (the default), then peer certificate validation will always -set the `gio::TlsCertificateFlags::UnknownCa` error. -## `database` -a `gio::TlsDatabase` - -Emitted during the TLS handshake after the client certificate has -been received. See also `RTSPAuthExt::set_tls_authentication_mode`. -## `connection` -a `gio::TlsConnection` -## `peer_cert` -the peer's `gio::TlsCertificate` -## `errors` -the problems with `peer_cert`. - -# Returns - -`true` to accept `peer_cert` (which will also -immediately end the signal emission). `false` to allow the signal -emission to continue, which will cause the handshake to fail if -no one else overrides it. - -The client object represents the connection and its state with a client. - -# Implements - -[`RTSPClientExt`](trait@crate::RTSPClientExt), [`trait@glib::object::ObjectExt`], [`RTSPClientExtManual`](trait@crate::RTSPClientExtManual) - -Trait containing all `RTSPClient` methods. - -# Implementors - -[`RTSPClient`](struct@crate::RTSPClient) - -Create a new `RTSPClient` instance. - -# Returns - -a new `RTSPClient` - -Attaches `self` to `context`. When the mainloop for `context` is run, the -client will be dispatched. When `context` is `None`, the default context will be -used). - -This function should be called when the client properties and urls are fully -configured and the client is ready to start. -## `context` -a `glib::MainContext` - -# Returns - -the ID (greater than 0) for the source within the GMainContext. - -Close the connection of `self` and remove all media it was managing. - -Get the `RTSPAuth` used as the authentication manager of `self`. - -# Returns - -the `RTSPAuth` of `self`. -`glib::object::ObjectExt::unref` after usage. - -Get the `gst_rtsp::RTSPConnection` of `self`. - -# Returns - -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. - -# Returns - -a `RTSPMountPoints`, unref after usage. - -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`. - -# Returns - -the `RTSPThreadPool` of `self`. `glib::object::ObjectExt::unref` after -usage. - -Let the client handle `message`. -## `message` -an `gst_rtsp::RTSPMessage` - -# Returns - -a `gst_rtsp::RTSPResult`. - -Send a message message to the remote end. `message` must be a -`gst_rtsp::RTSPMsgType::Request` or a `gst_rtsp::RTSPMsgType::Response`. -## `session` -a `RTSPSession` to send - the message to or `None` -## `message` -The `gst_rtsp::RTSPMessage` to send - -Call `func` for each session managed by `self`. The result value of `func` -determines what happens to the session. `func` will be called with `self` -locked so no further actions on `self` can be performed from `func`. - -If `func` returns `RTSPFilterResult::Remove`, the session will be removed from -`self`. - -If `func` returns `RTSPFilterResult::Keep`, the session will remain in `self`. - -If `func` returns `RTSPFilterResult::Ref`, the session will remain in `self` but -will also be added with an additional ref to the result `glib::List` of this -function.. - -When `func` is `None`, `RTSPFilterResult::Ref` will be assumed for each session. -## `func` -a callback -## `user_data` -user data passed to `func` - -# Returns - -a `glib::List` with all -sessions for which `func` returned `RTSPFilterResult::Ref`. After usage, each -element in the `glib::List` should be unreffed before the list is freed. - -configure `auth` to be used as the authentication manager of `self`. -## `auth` -a `RTSPAuth` - -Set the `gst_rtsp::RTSPConnection` of `self`. This function takes ownership of -`conn`. -## `conn` -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 -created the client but can be overriden later. -## `mounts` -a `RTSPMountPoints` - -Set `func` as the callback that will be called when a new message needs to be -sent to the client. `user_data` is passed to `func` and `notify` is called when -`user_data` is no longer in use. - -By default, the client will send the messages on the `gst_rtsp::RTSPConnection` that -was configured with `RTSPClient::attach` was called. - -It is only allowed to set either a `send_func` or a `send_messages_func` -but not both at the same time. -## `func` -a `GstRTSPClientSendFunc` -## `user_data` -user data passed to `func` -## `notify` -called when `user_data` is no longer in use - -Set `func` as the callback that will be called when new messages needs to be -sent to the client. `user_data` is passed to `func` and `notify` is called when -`user_data` is no longer in use. - -By default, the client will send the messages on the `gst_rtsp::RTSPConnection` that -was configured with `RTSPClient::attach` was called. - -It is only allowed to set either a `send_func` or a `send_messages_func` -but not both at the same time. - -Feature: `v1_16` - -## `func` -a `GstRTSPClientSendMessagesFunc` -## `user_data` -user data passed to `func` -## `notify` -called when `user_data` is no longer in use - -Set `pool` as the sessionpool for `self` which it will use to find -or allocate sessions. the sessionpool is usually inherited from the server -that created the client but can be overridden later. -## `pool` -a `RTSPSessionPool` - -configure `pool` to be used as the thread pool of `self`. -## `pool` -a `RTSPThreadPool` - -## `ctx` -a `RTSPContext` - -## `ctx` -a `RTSPContext` -## `arr` -a NULL-terminated array of strings - -# Returns - -a newly allocated string with comma-separated list of - unsupported options. An empty string must be returned if - all options are supported. - -## `ctx` -a `RTSPContext` - -## `ctx` -a `RTSPContext` - -## `ctx` -a `RTSPContext` - -## `ctx` -a `RTSPContext` - -## `ctx` -a `RTSPContext` - -## `ctx` -a `RTSPContext` - - -Feature: `v1_12` - -## `ctx` -a `RTSPContext` - -# Returns - -a `gst_rtsp::RTSPStatusCode`, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - -Feature: `v1_12` - -## `ctx` -a `RTSPContext` - -# Returns - -a `gst_rtsp::RTSPStatusCode`, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - -Feature: `v1_12` - -## `ctx` -a `RTSPContext` - -# Returns - -a `gst_rtsp::RTSPStatusCode`, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - -Feature: `v1_12` - -## `ctx` -a `RTSPContext` - -# Returns - -a `gst_rtsp::RTSPStatusCode`, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - -Feature: `v1_12` - -## `ctx` -a `RTSPContext` - -# Returns - -a `gst_rtsp::RTSPStatusCode`, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - -Feature: `v1_12` - -## `ctx` -a `RTSPContext` - -# Returns - -a `gst_rtsp::RTSPStatusCode`, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - -Feature: `v1_12` - -## `ctx` -a `RTSPContext` - -# Returns - -a `gst_rtsp::RTSPStatusCode`, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - -Feature: `v1_12` - -## `ctx` -a `RTSPContext` - -# Returns - -a `gst_rtsp::RTSPStatusCode`, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - -Feature: `v1_12` - -## `ctx` -a `RTSPContext` - -# Returns - -a `gst_rtsp::RTSPStatusCode`, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - - -Feature: `v1_12` - -## `ctx` -a `RTSPContext` - -# Returns - -a `gst_rtsp::RTSPStatusCode`, GST_RTSP_STS_OK in case of success, - otherwise an appropriate return code - -## `ctx` -a `RTSPContext` - -## `session` -The session -## `message` -The message - -## `ctx` -a `RTSPContext` - -## `ctx` -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`. - -Remove session - -Keep session in the pool - -Ref session in the result list - -A class that contains the GStreamer element along with a list of -`RTSPStream` objects that can produce data. - -This object is usually created from a `RTSPMediaFactory`. - -# Implements - -[`RTSPMediaExt`](trait@crate::RTSPMediaExt), [`trait@glib::object::ObjectExt`], [`RTSPMediaExtManual`](trait@crate::RTSPMediaExtManual) - -Trait containing all `RTSPMedia` methods. - -# Implementors - -[`RTSPMedia`](struct@crate::RTSPMedia) - -Create a new `RTSPMedia` instance. `element` is the bin element that -provides the different streams. The `RTSPMedia` object contains the -element to produce RTP data for one or more related (audio/video/..) -streams. - -Ownership is taken of `element`. -## `element` -a `gst::Element` - -# Returns - -a new `RTSPMedia` object. - -Find all payloader elements, they should be named pay\%d in the -element of `self`, and create `GstRTSPStreams` for them. - -Collect all dynamic elements, named dynpay\%d, and add them to -the list of dynamic elements. - -Find all depayloader elements, they should be named depay\%d in the -element of `self`, and create `GstRTSPStreams` for them. - -Add a receiver and sender parts to the pipeline based on the transport from -SETUP. - -Feature: `v1_14` - -## `transports` -a list of `gst_rtsp::RTSPTransport` - -# Returns - -`true` if the media pipeline has been sucessfully updated. - -Create a new stream in `self` that provides RTP data on `pad`. -`pad` should be a pad of an element inside `self`->element. -## `payloader` -a `gst::Element` -## `pad` -a `gst::Pad` - -# Returns - -a new `RTSPStream` that remains valid for as long -as `self` exists. - -Find a stream in `self` with `control` as the control uri. -## `control` -the control of the stream - -# Returns - -the `RTSPStream` with -control uri `control` or `None` when a stream with that control did -not exist. - -Get the `RTSPAddressPool` used as the address pool of `self`. - -# Returns - -the `RTSPAddressPool` of `self`. -`glib::object::ObjectExt::unref` after usage. - -Get the base_time that is used by the pipeline in `self`. - -`self` must be prepared before this method returns a valid base_time. - -# Returns - -the base_time used by `self`. - -Get the kernel UDP buffer size. - -# Returns - -the kernel UDP buffer size. - -Get the clock that is used by the pipeline in `self`. - -`self` must be prepared before this method returns a valid clock object. - -# Returns - -the `gst::Clock` used by `self`. unref after usage. - - -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`. - -# Returns - -a `gst::Element`. Unref after usage. - -Get the latency that is used for receiving media. - -# Returns - -latency in milliseconds - -Get the the maximum time-to-live value of outgoing multicast packets. - -Feature: `v1_16` - - -# Returns - -the maximum time-to-live value of outgoing multicast packets. - -Get the multicast interface used for `self`. - -# Returns - -the multicast interface for `self`. -`g_free` after usage. - -Get the permissions object from `self`. - -# Returns - -a `RTSPPermissions` object, unref after usage. - -Get the allowed profiles of `self`. - -# Returns - -a `gst_rtsp::RTSPProfile` - -Get the allowed protocols of `self`. - -# Returns - -a `gst_rtsp::RTSPLowerTrans` - -Gets if and how the media clock should be published according to RFC7273. - -# Returns - -The GstRTSPPublishClockMode - -Get the current range as a string. `self` must be prepared with -gst_rtsp_media_prepare (). -## `play` -for the PLAY request -## `unit` -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. - -# Returns - -the amount of time to store retransmission data. - -Get the status of `self`. When `self` is busy preparing, this function waits -until `self` is prepared or in error. - -# Returns - -the status of `self`. - -Retrieve the stream with index `idx` from `self`. -## `idx` -the stream index - -# Returns - -the `RTSPStream` at index -`idx` or `None` when a stream with that index did not exist. - -Get how `self` will be suspended. - -# Returns - -`RTSPSuspendMode`. - -Get the `gst_net::NetTimeProvider` for the clock used by `self`. The time provider -will listen on `address` and `port` for client time requests. -## `address` -an address or `None` -## `port` -a port or 0 - -# Returns - -the `gst_net::NetTimeProvider` of `self`. - -Check if the pipeline for `self` can be used for PLAY or RECORD methods. - -# Returns - -The transport mode. - -Configure an SDP on `self` for receiving streams -## `sdp` -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. - -Feature: `v1_16` - - -# Returns - -`true` if multicast sockets are configured to be bound to multicast addresses. - -Check if the pipeline for `self` will send an EOS down the pipeline before -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. - -# Returns - -`true` if the media can be reused - -Check if the pipeline for `self` can be shared between multiple clients. - -# Returns - -`true` if the media can be shared between clients. - -Check if the pipeline for `self` will be stopped when a client disconnects -without sending TEARDOWN. - -# Returns - -`true` if the media will be stopped when a client disconnects - without sending TEARDOWN. - -Check if `self` can provide a `gst_net::NetTimeProvider` for its pipeline clock. - -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. - -# Returns - -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 -`RTSPMedia::take_pipeline`. - -It will preroll the pipeline and collect vital information about the streams -such as the duration. -## `thread` -a `RTSPThread` to run the - bus handler or `None` - -# Returns - -`true` on success. - -Seek the pipeline of `self` to `range`. `self` must be prepared with -`RTSPMediaExt::prepare`. -## `range` -a `gst_rtsp::RTSPTimeRange` - -# Returns - -`true` on success. - -Seek the pipeline of `self` to `range` with the given `flags`. -`self` must be prepared with `RTSPMediaExt::prepare`. - -Feature: `v1_18` - -## `range` -a `gst_rtsp::RTSPTimeRange` -## `flags` -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, -it can seek. - -Feature: `v1_14` - - -# Returns - --1 if the stream is not seekable, 0 if seekable only to the beginning -and > 0 to indicate the longest duration between any two random access points. -`G_MAXINT64` means any value is possible. - -configure `pool` to be used as the address pool of `self`. -## `pool` -a `RTSPAddressPool` - -Decide whether the multicast socket should be bound to a multicast address or -INADDR_ANY. - -Feature: `v1_16` - -## `bind_mcast_addr` -the new value - -Set the kernel UDP buffer size. -## `size` -the new value - -Configure the clock used for the media. -## `clock` -`gst::Clock` to be used - -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. -## `eos_shutdown` -the new value - -Configure the latency used for receiving media. -## `latency` -latency in milliseconds - -Set the maximum time-to-live value of outgoing multicast packets. - -Feature: `v1_16` - -## `ttl` -the new multicast ttl value - -# Returns - -`true` if the requested ttl has been set successfully. - -configure `multicast_iface` to be used for `self`. -## `multicast_iface` -a multicast interface name - -Set `permissions` on `self`. -## `permissions` -a `RTSPPermissions` - -Set the state of the pipeline managed by `self` to `state` -## `state` -the target state of the pipeline - -Configure the allowed lower transport for `self`. -## `profiles` -the new flags - -Configure the allowed lower transport for `self`. -## `protocols` -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` -the new value - -Set or unset if the pipeline for `self` can be reused after the pipeline has -been unprepared. -## `reusable` -the new value - -Set or unset if the pipeline for `self` can be shared will multiple clients. -When `shared` is `true`, client requests for this media will share the media -pipeline. -## `shared` -the new value - -Set the state of `self` to `state` and for the transports in `transports`. - -`self` must be prepared with `RTSPMediaExt::prepare`; -## `state` -the target state of the media -## `transports` - -a `glib::PtrArray` of `RTSPStreamTransport` pointers - -# Returns - -`true` on success. - -Set or unset if the pipeline for `self` should be stopped when a -client disconnects without sending TEARDOWN. -## `stop_on_disconnect` -the new value - -Control how @ media will be suspended after the SDP has been generated and -after a PAUSE request has been performed. - -Media must be unprepared when setting the suspend mode. -## `mode` -the new `RTSPSuspendMode` - -Sets if the media pipeline can work in PLAY or RECORD mode -## `mode` -the new value - -Add `self` specific info to `sdp`. `info` is used to configure the connection -information in the SDP. -## `sdp` -a `gst_sdp::SDPMessage` -## `info` -a `SDPInfo` - -# Returns - -TRUE on success. - -Suspend `self`. The state of the pipeline managed by `self` is set to -GST_STATE_NULL but all streams are kept. `self` can be prepared again -with `RTSPMediaExt::unsuspend` - -`self` must be prepared with `RTSPMediaExt::prepare`; - -# Returns - -`true` on success. - -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 -must be created. - -# Returns - -`true` on success. - -Unsuspend `self` if it was in a suspended state. This method does nothing -when the media was not in the suspended state. - -# Returns - -`true` on success. - -Set `self` to provide a `gst_net::NetTimeProvider`. -## `time_provider` -if a `gst_net::NetTimeProvider` should be used - -The definition and logic for constructing the pipeline for a media. The media -can contain multiple streams like audio and video. - -# Implements - -[`RTSPMediaFactoryExt`](trait@crate::RTSPMediaFactoryExt), [`trait@glib::object::ObjectExt`], [`RTSPMediaFactoryExtManual`](trait@crate::RTSPMediaFactoryExtManual) - -Trait containing all `RTSPMediaFactory` methods. - -# Implementors - -[`RTSPMediaFactoryURI`](struct@crate::RTSPMediaFactoryURI), [`RTSPMediaFactory`](struct@crate::RTSPMediaFactory) - -Create a new `RTSPMediaFactory` instance. - -# Returns - -a new `RTSPMediaFactory` object. - -A convenience method to add `role` with `fieldname` and additional arguments to -the permissions of `self`. If `self` had no permissions, new permissions -will be created and the role will be added to it. -## `role` -a role -## `fieldname` -the first field name - -A convenience wrapper around `RTSPPermissions::add_role_from_structure`. -If `self` had no permissions, new permissions will be created and the -role will be added to it. - -Feature: `v1_14` - - -Construct the media object and create its streams. Implementations -should create the needed gstreamer elements and add them to the result -object. No state changes should be performed on them yet. - -One or more GstRTSPStream objects should be created from the result -with gst_rtsp_media_create_stream (). - -After the media is constructed, it can be configured and then prepared -with gst_rtsp_media_prepare (). -## `url` -the url used - -# Returns - -a new `RTSPMedia` if the media could be prepared. - -Construct and return a `gst::Element` that is a `gst::Bin` containing -the elements to use for streaming the media. - -The bin should contain payloaders pay\%d for each stream. The default -implementation of this function returns the bin created from the -launch parameter. -## `url` -the url used - -# Returns - -a new `gst::Element`. - -Get the `RTSPAddressPool` used as the address pool of `self`. - -# Returns - -the `RTSPAddressPool` of `self`. `glib::object::ObjectExt::unref` after -usage. - -Get the kernel UDP buffer size. - -# Returns - -the kernel UDP buffer size. - -Returns the clock that is going to be used by the pipelines -of all medias created from this factory. - -# Returns - -The GstClock - - -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 - -# Returns - -latency in milliseconds - -Get the `gst_parse_launch` pipeline description that will be used in the -default prepare vmethod. - -# Returns - -the configured launch description. `g_free` after -usage. - -Get the the maximum time-to-live value of outgoing multicast packets. - -Feature: `v1_16` - - -# Returns - -the maximum time-to-live value of outgoing multicast packets. - -Return the GType of the GstRTSPMedia subclass this -factory will create. - -Get the multicast interface used for `self`. - -# Returns - -the multicast interface for `self`. `g_free` after -usage. - -Get the permissions object from `self`. - -# Returns - -a `RTSPPermissions` object, unref after usage. - -Get the allowed profiles of `self`. - -# Returns - -a `gst_rtsp::RTSPProfile` - -Get the allowed protocols of `self`. - -# Returns - -a `gst_rtsp::RTSPLowerTrans` - -Gets if and how the media clock should be published according to RFC7273. - -# Returns - -The GstRTSPPublishClockMode - -Get the time that is stored for retransmission purposes - -# Returns - -a `gst::ClockTime` - -Get how media created from this factory will be suspended. - -# Returns - -a `RTSPSuspendMode`. - -Get if media created from this factory can be used for PLAY or RECORD -methods. - -# Returns - -The transport mode. - -Check if multicast sockets are configured to be bound to multicast addresses. - -Feature: `v1_16` - - -# Returns - -`true` if multicast sockets are configured to be bound to multicast addresses. - -Get if media created from this factory will have an EOS event sent to the -pipeline before shutdown. - -# Returns - -`true` if the media will receive EOS before shutdown. - -Get if media created from this factory can be shared between clients. - -# Returns - -`true` if the media will be shared between clients. - -configure `pool` to be used as the address pool of `self`. -## `pool` -a `RTSPAddressPool` - -Decide whether the multicast socket should be bound to a multicast address or -INADDR_ANY. - -Feature: `v1_16` - -## `bind_mcast_addr` -the new value - -Set the kernel UDP buffer size. -## `size` -the new value - -Configures a specific clock to be used by the pipelines -of all medias created from this factory. -## `clock` -the clock to be used by the media factory - -Set whether retransmission requests will be sent for -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. -## `eos_shutdown` -the new value - -Configure the latency used for receiving media -## `latency` -latency in milliseconds - -The `gst_parse_launch` line to use for constructing the pipeline in the -default prepare vmethod. - -The pipeline description should return a GstBin as the toplevel element -which can be accomplished by enclosing the description with brackets '(' -')'. - -The description should return a pipeline with payloaders named pay0, pay1, -etc.. Each of the payloaders will result in a stream. -## `launch` -the launch description - -Set the maximum time-to-live value of outgoing multicast packets. - -Feature: `v1_16` - -## `ttl` -the new multicast ttl value - -# Returns - -`true` if the requested ttl has been set successfully. - -Configure the GType of the GstRTSPMedia subclass to -create (by default, overridden construct vmethods -may of course do something different) -## `media_gtype` -the GType of the class to create - -configure `multicast_iface` to be used for `self`. -## `multicast_iface` -a multicast interface name - -Set `permissions` on `self`. -## `permissions` -a `RTSPPermissions` - -Configure the allowed profiles for `self`. -## `profiles` -the new flags - -Configure the allowed lower transport for `self`. -## `protocols` -the new flags - -Sets if and how the media clock should be published according to RFC7273. -## `mode` -the clock publish mode - -Configure the time to store for possible retransmission -## `time` -a `gst::ClockTime` - -Configure if media created from this factory can be shared between clients. -## `shared` -the new value - -Configure if media created from this factory should be stopped -when a client disconnects without sending TEARDOWN. -## `stop_on_disconnect` -the new value - -Configure how media created from this factory will be suspended. -## `mode` -the new `RTSPSuspendMode` - -Configure if this factory creates media for PLAY or RECORD modes. -## `mode` -the new value - -A media factory that creates a pipeline to play any uri. - -# Implements - -[`RTSPMediaFactoryURIExt`](trait@crate::RTSPMediaFactoryURIExt), [`RTSPMediaFactoryExt`](trait@crate::RTSPMediaFactoryExt), [`trait@glib::object::ObjectExt`], [`RTSPMediaFactoryExtManual`](trait@crate::RTSPMediaFactoryExtManual) - -Trait containing all `RTSPMediaFactoryURI` methods. - -# Implementors - -[`RTSPMediaFactoryURI`](struct@crate::RTSPMediaFactoryURI) - -Create a new `RTSPMediaFactoryURI` instance. - -# Returns - -a new `RTSPMediaFactoryURI` object. - -Get the URI that will provide media for this factory. - -# Returns - -the configured URI. `g_free` after usage. - -Set the URI of the resource that will be streamed by this factory. -## `uri` -the uri the stream - -The state of the media pipeline. - -media pipeline not prerolled - -media pipeline is busy doing a clean - shutdown. - -media pipeline is prerolling - -media pipeline is prerolled - -media is suspended - -media pipeline is in error - -Creates a `RTSPMediaFactory` object for a given url. - -# Implements - -[`RTSPMountPointsExt`](trait@crate::RTSPMountPointsExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `RTSPMountPoints` methods. - -# Implementors - -[`RTSPMountPoints`](struct@crate::RTSPMountPoints) - -Make a new mount points object. - -# Returns - -a new `RTSPMountPoints` - -Attach `factory` to the mount point `path` in `self`. - -`path` is of the form (/node)+. Any previous mount point will be freed. - -Ownership is taken of the reference on `factory` so that `factory` should not be -used after calling this function. -## `path` -a mount point -## `factory` -a `RTSPMediaFactory` - -Make a path string from `url`. -## `url` -a `gst_rtsp::RTSPUrl` - -# Returns - -a path string for `url`, `g_free` after usage. - -Find the factory in `self` that has the longest match with `path`. - -If `matched` is `None`, `path` will match the factory exactly otherwise -the amount of characters that matched is returned in `matched`. -## `path` -a mount point -## `matched` -the amount of `path` matched - -# Returns - -the `RTSPMediaFactory` for `path`. -`glib::object::ObjectExt::unref` after usage. - -Remove the `RTSPMediaFactory` associated with `path` in `self`. -## `path` -a mount point - -Whether the clock and possibly RTP/clock offset should be published according to RFC7273. - -Publish nothing - -Publish the clock but not the offset - -Publish the clock and offset - -This object listens on a port, creates and manages the clients connected to -it. - -# Implements - -[`RTSPServerExt`](trait@crate::RTSPServerExt), [`trait@glib::object::ObjectExt`], [`RTSPServerExtManual`](trait@crate::RTSPServerExtManual) - -Trait containing all `RTSPServer` methods. - -# Implementors - -[`RTSPServer`](struct@crate::RTSPServer) - -Create a new `RTSPServer` instance. - -# Returns - -a new `RTSPServer` - -A default `GSocketSourceFunc` that creates a new `RTSPClient` to accept and handle a -new connection on `socket` or `server`. -## `socket` -a `gio::Socket` -## `condition` -the condition on `source` -## `server` -a `RTSPServer` - -# Returns - -TRUE if the source could be connected, FALSE if an error occurred. - -Attaches `self` to `context`. When the mainloop for `context` is run, the -server will be dispatched. When `context` is `None`, the default context will be -used). - -This function should be called when the server properties and urls are fully -configured and the server is ready to start. - -This takes a reference on `self` until the source is destroyed. Note that -if `context` is not the default main context as returned by -`glib::MainContext::default` (or `None`), `glib::Source::remove` cannot be used to -destroy the source. In that case it is recommended to use -`RTSPServerExt::create_source` and attach it to `context` manually. -## `context` -a `glib::MainContext` - -# Returns - -the ID (greater than 0) for the source within the GMainContext. - -Call `func` for each client managed by `self`. The result value of `func` -determines what happens to the client. `func` will be called with `self` -locked so no further actions on `self` can be performed from `func`. - -If `func` returns `RTSPFilterResult::Remove`, the client will be removed from -`self`. - -If `func` returns `RTSPFilterResult::Keep`, the client will remain in `self`. - -If `func` returns `RTSPFilterResult::Ref`, the client will remain in `self` but -will also be added with an additional ref to the result `glib::List` of this -function.. - -When `func` is `None`, `RTSPFilterResult::Ref` will be assumed for each client. -## `func` -a callback -## `user_data` -user data passed to `func` - -# Returns - -a `glib::List` with all -clients for which `func` returned `RTSPFilterResult::Ref`. After usage, each -element in the `glib::List` should be unreffed before the list is freed. - -Create a `gio::Socket` for `self`. The socket will listen on the -configured service. -## `cancellable` -a `gio::Cancellable` - -# Returns - -the `gio::Socket` for `self` or `None` when an error -occurred. - -Create a `glib::Source` for `self`. The new source will have a default -`GSocketSourceFunc` of `RTSPServer::io_func`. - -`cancellable` if not `None` can be used to cancel the source, which will cause -the source to trigger, reporting the current condition (which is likely 0 -unless cancellation happened at the same time as a condition change). You can -check for this in the callback using `gio::CancellableExt::is_cancelled`. - -This takes a reference on `self` until `source` is destroyed. -## `cancellable` -a `gio::Cancellable` or `None`. - -# Returns - -the `glib::Source` for `self` or `None` when an error -occurred. Free with g_source_unref () - -Get the address on which the server will accept connections. - -# Returns - -the server address. `g_free` after usage. - -Get the `RTSPAuth` used as the authentication manager of `self`. - -# Returns - -the `RTSPAuth` of `self`. `glib::object::ObjectExt::unref` after -usage. - -The maximum amount of queued requests for the server. - -# Returns - -the server backlog. - -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`. - -# Returns - -the `RTSPMountPoints` of `self`. `glib::object::ObjectExt::unref` after -usage. - -Get the service on which the server will accept connections. - -# Returns - -the service. use `g_free` after usage. - -Get the `RTSPSessionPool` used as the session pool of `self`. - -# Returns - -the `RTSPSessionPool` used for sessions. `glib::object::ObjectExt::unref` after -usage. - -Get the `RTSPThreadPool` used as the thread pool of `self`. - -# Returns - -the `RTSPThreadPool` of `self`. `glib::object::ObjectExt::unref` after -usage. - -Configure `self` to accept connections on the given address. - -This function must be called before the server is bound. -## `address` -the address - -configure `auth` to be used as the authentication manager of `self`. -## `auth` -a `RTSPAuth` - -configure the maximum amount of requests that may be queued for the -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` -a `RTSPMountPoints` - -Configure `self` to accept connections on the given service. -`service` should be a string containing the service name (see services(5)) or -a string containing a port number between 1 and 65535. - -When `service` is set to "0", the server will listen on a random free -port. The actual used port can be retrieved with -`RTSPServerExt::get_bound_port`. - -This function must be called before the server is bound. -## `service` -the service - -configure `pool` to be used as the session pool of `self`. -## `pool` -a `RTSPSessionPool` - -configure `pool` to be used as the thread pool of `self`. -## `pool` -a `RTSPThreadPool` - -Take an existing network socket and use it for an RTSP connection. This -is used when transferring a socket from an HTTP server which should be used -as an RTSP over HTTP tunnel. The `initial_buffer` contains any remaining data -that the HTTP server read from the socket while parsing the HTTP header. -## `socket` -a network socket -## `ip` -the IP address of the remote client -## `port` -the port used by the other end -## `initial_buffer` -any initial data that was already read from the socket - -# Returns - -TRUE if all was ok, FALSE if an error occurred. - -Session information kept by the server for a specific client. -One client session, identified with a session id, can handle multiple medias -identified with the url of a media. - -# Implements - -[`RTSPSessionExt`](trait@crate::RTSPSessionExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `RTSPSession` methods. - -# Implementors - -[`RTSPSession`](struct@crate::RTSPSession) - -Create a new `RTSPSession` instance with `sessionid`. -## `sessionid` -a session id - -# Returns - -a new `RTSPSession` - -Allow `self` to expire. This method must be called an equal -amount of time as `RTSPSessionExt::prevent_expire`. - -Call `func` for each media in `self`. The result value of `func` determines -what happens to the media. `func` will be called with `self` -locked so no further actions on `self` can be performed from `func`. - -If `func` returns `RTSPFilterResult::Remove`, the media will be removed from -`self`. - -If `func` returns `RTSPFilterResult::Keep`, the media will remain in `self`. - -If `func` returns `RTSPFilterResult::Ref`, the media will remain in `self` but -will also be added with an additional ref to the result `glib::List` of this -function.. - -When `func` is `None`, `RTSPFilterResult::Ref` will be assumed for all media. -## `func` -a callback -## `user_data` -user data passed to `func` - -# Returns - -a GList with all -media for which `func` returned `RTSPFilterResult::Ref`. After usage, each -element in the `glib::List` should be unreffed before the list is freed. - -Get the string that can be placed in the Session header field. - -# Returns - -the Session header of `self`. -`g_free` after usage. - -Get the session media for `path`. `matched` will contain the number of matched -characters of `path`. -## `path` -the path for the media -## `matched` -the amount of matched characters - -# Returns - -the configuration for `path` in `self`. - -Get the sessionid of `self`. - -# Returns - -the sessionid of `self`. -The value remains valid as long as `self` is alive. - -Get the timeout value of `self`. - -# Returns - -the timeout of `self` in seconds. - -Check if `self` timeout out. - -# Deprecated - -Use `RTSPSessionExt::is_expired_usec` instead. -## `now` -the current system time - -# Returns - -`true` if `self` timed out - -Check if `self` timeout out. -## `now` -the current monotonic time - -# Returns - -`true` if `self` timed out - -Manage the media object `obj` in `self`. `path` will be used to retrieve this -media from the session with `RTSPSessionExt::get_media`. - -Ownership is taken from `media`. -## `path` -the path for the media -## `media` -a `RTSPMedia` - -# Returns - -a new [`crate::RTSPSessionMedia`] (XXX: @-reference does not belong to RTSPSessionExt!) object. - -Get the amount of milliseconds till the session will expire. - -# Deprecated - -Use `RTSPSessionExt::next_timeout_usec` instead. -## `now` -the current system time - -# Returns - -the amount of milliseconds since the session will time out. - -Get the amount of milliseconds till the session will expire. -## `now` -the current monotonic time - -# Returns - -the amount of milliseconds since the session will time out. - -Prevent `self` from expiring. - -Release the managed `media` in `self`, freeing the memory allocated by it. -## `media` -a `RTSPMedia` - -# Returns - -`true` if there are more media session left in `self`. - -Configure `self` for a timeout of `timeout` seconds. The session will be -cleaned up when there is no activity for `timeout` seconds. -## `timeout` -the new timeout - -Update the last_access time of the session to the current time. - -State of a client session regarding a specific media identified by path. - -# Implements - -[`RTSPSessionMediaExt`](trait@crate::RTSPSessionMediaExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `RTSPSessionMedia` methods. - -# Implementors - -[`RTSPSessionMedia`](struct@crate::RTSPSessionMedia) - -Create a new `RTSPSessionMedia` that manages the streams -in `media` for `path`. `media` should be prepared. - -Ownership is taken of `media`. -## `path` -the path -## `media` -the `RTSPMedia` - -# Returns - -a new `RTSPSessionMedia`. - -Fill `range` with the next available min and max channels for -interleaved transport. -## `range` -a `gst_rtsp::RTSPRange` - -# Returns - -`true` on success. - -Get the base_time of the `RTSPMedia` in `self` - -# Returns - -the base_time of the media. - -Get the `RTSPMedia` that was used when constructing `self` - -# Returns - -the `RTSPMedia` of `self`. -Remains valid as long as `self` is valid. - -Retrieve the RTP-Info header string for all streams in `self` -with configured transports. - -# Returns - -The RTP-Info as a string or -`None` when no RTP-Info could be generated, `g_free` after usage. - -Get the current RTSP state of `self`. - -# Returns - -the current RTSP state of `self`. - -Get a previously created `RTSPStreamTransport` for the stream at `idx`. -## `idx` -the stream index - -# Returns - -a `RTSPStreamTransport` that is -valid until the session of `self` is unreffed. - -Get a list of all available `RTSPStreamTransport` in this session. - -Feature: `v1_14` - - -# Returns - -a -list of `RTSPStreamTransport`, g_ptr_array_unref () after usage. - -Check if the path of `self` matches `path`. It `path` matches, the amount of -matched characters is returned in `matched`. -## `path` -a path -## `matched` -the amount of matched characters of `path` - -# Returns - -`true` when `path` matches the path of `self`. - -Set the RTSP state of `self` to `state`. -## `state` -a `gst_rtsp::RTSPState` - -Tell the media object `self` to change to `state`. -## `state` -the new state - -# Returns - -`true` on success. - -Configure the transport for `stream` to `tr` in `self`. -## `stream` -a `RTSPStream` -## `tr` -a `gst_rtsp::RTSPTransport` - -# Returns - -the new or updated `RTSPStreamTransport` for `stream`. - -An object that keeps track of the active sessions. This object is usually -attached to a `RTSPServer` object to manage the sessions in that server. - -# Implements - -[`RTSPSessionPoolExt`](trait@crate::RTSPSessionPoolExt), [`trait@glib::object::ObjectExt`], [`RTSPSessionPoolExtManual`](trait@crate::RTSPSessionPoolExtManual) - -Trait containing all `RTSPSessionPool` methods. - -# Implementors - -[`RTSPSessionPool`](struct@crate::RTSPSessionPool) - -Create a new `RTSPSessionPool` instance. - -# Returns - -A new `RTSPSessionPool`. `glib::object::ObjectExt::unref` after -usage. - -Inspect all the sessions in `self` and remove the sessions that are inactive -for more than their timeout. - -# Returns - -the amount of sessions that got removed. - -Create a new `RTSPSession` object in `self`. - -# Returns - -a new `RTSPSession`. - -Create a `glib::Source` that will be dispatched when the session should be cleaned -up. - -# Returns - -a `glib::Source` - -Call `func` for each session in `self`. The result value of `func` determines -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 and removed from `self`. - -If `func` returns `RTSPFilterResult::Keep`, the session will remain in `self`. - -If `func` returns `RTSPFilterResult::Ref`, the session will remain in `self` but -will also be added with an additional ref to the result GList of this -function.. - -When `func` is `None`, `RTSPFilterResult::Ref` will be assumed for all sessions. -## `func` -a callback -## `user_data` -user data passed to `func` - -# Returns - -a GList with all -sessions for which `func` returned `RTSPFilterResult::Ref`. After usage, each -element in the GList should be unreffed before the list is freed. - -Find the session with `sessionid` in `self`. The access time of the session -will be updated with `RTSPSessionExt::touch`. -## `sessionid` -the session id - -# Returns - -the `RTSPSession` with `sessionid` -or `None` when the session did not exist. `glib::object::ObjectExt::unref` after usage. - -Get the maximum allowed number of sessions in `self`. 0 means an unlimited -amount of sessions. - -# Returns - -the maximum allowed number of sessions. - -Get the amount of active sessions in `self`. - -# Returns - -the amount of active sessions in `self`. - -Remove `sess` from `self`, releasing the ref that the pool has on `sess`. -## `sess` -a `RTSPSession` - -# Returns - -`true` if the session was found and removed. - -Configure the maximum allowed number of sessions in `self` to `max`. -A value of 0 means an unlimited amount of sessions. -## `max` -the maximum number of sessions - -The definition of a media stream. - -# Implements - -[`RTSPStreamExt`](trait@crate::RTSPStreamExt), [`trait@glib::object::ObjectExt`], [`RTSPStreamExtManual`](trait@crate::RTSPStreamExtManual) - -Trait containing all `RTSPStream` methods. - -# Implementors - -[`RTSPStream`](struct@crate::RTSPStream) - -Create a new media stream with index `idx` that handles RTP data on -`pad` and has a payloader element `payloader` if `pad` is a source pad -or a depayloader element `payloader` if `pad` is a sink pad. -## `idx` -an index -## `payloader` -a `gst::Element` -## `pad` -a `gst::Pad` - -# Returns - -a new `RTSPStream` - -Add multicast client address to stream. At this point, the sockets that -will stream RTP and RTCP data to `destination` are supposed to be -allocated. - -Feature: `v1_16` - -## `destination` -a multicast address to add -## `rtp_port` -RTP port -## `rtcp_port` -RTCP port -## `family` -socket family - -# Returns - -`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`. Adding the -same transport twice will not add it a second time. - -`self` must be joined to a bin. - -`trans` must contain a valid `gst_rtsp::RTSPTransport`. -## `trans` -a `RTSPStreamTransport` - -# Returns - -`true` if `trans` was added - -Allocates RTP and RTCP ports. -## `family` -protocol family -## `transport` -transport method -## `use_client_settings` -Whether to use client settings or not - -# Returns - -`true` if the RTP and RTCP sockets have been succeccully allocated. - -Add a receiver and sender part to the pipeline based on the transport from -SETUP. - -Feature: `v1_14` - -## `transport` -a `gst_rtsp::RTSPTransport` - -# Returns - -`true` if the stream has been sucessfully updated. - -Get the `RTSPAddressPool` used as the address pool of `self`. - -# Returns - -the `RTSPAddressPool` of `self`. -`glib::object::ObjectExt::unref` after usage. - -Get the size of the UDP transmission buffer (in bytes) - -# Returns - -the size of the UDP TX buffer - -Retrieve the current caps of `self`. - -# Returns - -the `gst::Caps` of `self`. -use `gst_caps_unref` after usage. - -Get the control string to identify this stream. - -# Returns - -the control string. `g_free` after usage. - -Get the configured DSCP QoS in of the outgoing sockets. - -# Returns - -the DSCP QoS value of the outgoing sockets, or -1 if disbled. - -Get the stream index. - -# Returns - -the stream index. - -Get the previous joined bin with `RTSPStreamExt::join_bin` or NULL. - -# Returns - -the joined bin or NULL. - -Get the the maximum time-to-live value of outgoing multicast packets. - -Feature: `v1_16` - - -# Returns - -the maximum time-to-live value of outgoing multicast packets. - -Get the configured MTU in the payloader of `self`. - -# Returns - -the MTU of the payloader. - -Get the multicast address of `self` for `family`. The original -`RTSPAddress` is cached and copy is returned, so freeing the return value -won't release the address from the pool. -## `family` -the `gio::SocketFamily` - -# Returns - -the `RTSPAddress` of `self` -or `None` when no address could be allocated. `RTSPAddress::free` -after usage. - -Get all multicast client addresses that RTP data will be sent to - -Feature: `v1_16` - - -# Returns - -A comma separated list of host:port pairs with destinations - -Get the multicast interface used for `self`. - -# Returns - -the multicast interface for `self`. -`g_free` after usage. - -Get the allowed profiles of `self`. - -# Returns - -a `gst_rtsp::RTSPProfile` - -Get the allowed protocols of `self`. - -# Returns - -a `gst_rtsp::RTSPLowerTrans` - -Get the stream payload type. - -# Returns - -the stream payload type. - -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 - -# Returns - -The retransmission PT. - -Get the amount of time to store retransmission data. - -# Returns - -the amount of time to store retransmission data. - -Get the multicast RTCP socket from `self` for a `family`. - -Feature: `v1_14` - -## `family` -the socket family - -# Returns - -the multicast RTCP socket or `None` if no -socket could be allocated for `family`. Unref after usage - -Get the RTCP socket from `self` for a `family`. - -`self` must be joined to a bin. -## `family` -the socket family - -# Returns - -the RTCP socket or `None` if no -socket could be allocated for `family`. Unref after usage - -Get the multicast RTP socket from `self` for a `family`. -## `family` -the socket family - -# Returns - -the multicast RTP socket or `None` if no - -socket could be allocated for `family`. Unref after usage - -Get the RTP socket from `self` for a `family`. - -`self` must be joined to a bin. -## `family` -the socket family - -# Returns - -the RTP socket or `None` if no -socket could be allocated for `family`. Unref after usage - -Retrieve the current rtptime, seq and running-time. This is used to -construct a RTPInfo reply header. -## `rtptime` -result RTP timestamp -## `seq` -result RTP seqnum -## `clock_rate` -the clock rate -## `running_time` -result running-time - -# Returns - -`true` when rtptime, seq and running-time could be determined. - -Get the RTP session of this stream. - -# Returns - -The RTP session of this stream. Unref after usage. - -Fill `server_port` with the port pair used by the server. This function can -only be called when `self` has been joined. -## `server_port` -result server port -## `family` -the port family to get - -Get the sinkpad associated with `self`. - -# Returns - -the sinkpad. Unref after usage. - -Get the srcpad associated with `self`. - -# Returns - -the srcpad. Unref after usage. - -Get the SRTP encoder for this stream. - -# Returns - -The SRTP encoder for this stream. Unref after usage. - -Get the SSRC used by the RTP session of this stream. This function can only -be called when `self` has been joined. -## `ssrc` -result ssrc - - -Feature: `v1_16` - - -# Returns - -the amount of redundancy applied when creating ULPFEC -protection packets. - - -Feature: `v1_16` - - -# Returns - -the payload type used for ULPFEC protection packets - -Parse and handle a KeyMgmt header. - -Feature: `v1_16` - -## `keymgmt` -a keymgmt header - -Check if `self` has the control string `control`. -## `control` -a control string - -# Returns - -`true` is `self` has `control` as the control string - -Check if multicast sockets are configured to be bound to multicast addresses. - -Feature: `v1_16` - - -# Returns - -`true` if multicast sockets are configured to be bound to multicast addresses. - -Check if `self` is blocking on a `gst::Buffer`. - -# Returns - -`true` if `self` is blocking - -See `RTSPStreamExt::set_client_side` - -# Returns - -TRUE if this `RTSPStream` is client-side. - -Checks whether the stream is complete, contains the receiver and the sender -parts. As the stream contains sink(s) element(s), it's possible to perform -seek operations on it. - -Feature: `v1_14` - - -# Returns - -`true` if the stream contains at least one sink element. - -Checks whether the stream is a receiver. - -Feature: `v1_14` - - -# Returns - -`true` if the stream is a receiver and `false` otherwise. - -Checks whether the stream is a sender. - -Feature: `v1_14` - - -# Returns - -`true` if the stream is a sender and `false` otherwise. - -Check if `transport` can be handled by stream -## `transport` -a `gst_rtsp::RTSPTransport` - -# Returns - -`true` if `transport` can be handled by `self`. - -Join the `gst::Bin` `bin` that contains the element `rtpbin`. - -`self` will link to `rtpbin`, which must be inside `bin`. The elements -added to `bin` will be set to the state given in `state`. -## `bin` -a `gst::Bin` to join -## `rtpbin` -a rtpbin element in `bin` -## `state` -the target state of the new elements - -# Returns - -`true` on success. - -Remove the elements of `self` from `bin`. -## `bin` -a `gst::Bin` -## `rtpbin` -a rtpbin `gst::Element` - -# Returns - -`true` on success. - -Query the position of the stream in `gst::Format::Time`. This only considers -the RTP parts of the pipeline and not the RTCP parts. -## `position` -current position of a `RTSPStream` - -# Returns - -`true` if the position could be queried - -Query the stop of the stream in `gst::Format::Time`. This only considers -the RTP parts of the pipeline and not the RTCP parts. -## `stop` -current stop of a `RTSPStream` - -# Returns - -`true` if the stop could be queried - -Handle an RTCP buffer for the stream. This method is usually called when a -message has been received from a client using the TCP transport. - -This function takes ownership of `buffer`. -## `buffer` -a `gst::Buffer` - -# Returns - -a GstFlowReturn. - -Handle an RTP buffer for the stream. This method is usually called when a -message has been received from a client using the TCP transport. - -This function takes ownership of `buffer`. -## `buffer` -a `gst::Buffer` - -# Returns - -a GstFlowReturn. - -Remove the transport in `trans` from `self`. The media of `self` will -not be sent to the values configured in `trans`. - -`self` must be joined to a bin. - -`trans` must contain a valid `gst_rtsp::RTSPTransport`. -## `trans` -a `RTSPStreamTransport` - -# Returns - -`true` if `trans` was removed - -Creating a rtxreceive bin - -Feature: `v1_16` - -## `sessid` -the session id - -# Returns - -a `gst::Element`. - -Creating a rtxsend bin -## `sessid` -the session id - -# Returns - -a `gst::Element`. - -Creating a rtpulpfecdec element - -Feature: `v1_16` - - -# Returns - -a `gst::Element`. - -Creating a rtpulpfecenc element - -Feature: `v1_16` - - -# Returns - -a `gst::Element`. - -Reserve `address` and `port` as the address and port of `self`. The original -`RTSPAddress` is cached and copy is returned, so freeing the return value -won't release the address from the pool. -## `address` -an address -## `port` -a port -## `n_ports` -n_ports -## `ttl` -a TTL - -# Returns - -the `RTSPAddress` of `self` or `None` when -the address could not be reserved. `RTSPAddress::free` after -usage. - -Checks whether the individual `self` is seekable. - -Feature: `v1_14` - - -# Returns - -`true` if `self` is seekable, else `false`. - -configure `pool` to be used as the address pool of `self`. -## `pool` -a `RTSPAddressPool` - -Decide whether the multicast socket should be bound to a multicast address or -INADDR_ANY. - -Feature: `v1_16` - -## `bind_mcast_addr` -the new value - -Blocks or unblocks the dataflow on `self`. -## `blocked` -boolean indicating we should block or unblock - -# Returns - -`true` on success - -Set the size of the UDP transmission buffer (in bytes) -Needs to be set before the stream is joined to a bin. -## `size` -the buffer size - -Sets the `RTSPStream` as a 'client side' stream - used for sending -streams to an RTSP server via RECORD. This has the practical effect -of changing which UDP port numbers are used when setting up the local -side of the stream sending to be either the 'server' or 'client' pair -of a configured UDP transport. -## `client_side` -TRUE if this `RTSPStream` is running on the 'client' side of -an RTSP connection. - -Set the control string in `self`. -## `control` -a control string - -Configure the dscp qos of the outgoing sockets to `dscp_qos`. -## `dscp_qos` -a new dscp qos value (0-63, or -1 to disable) - -Set the maximum time-to-live value of outgoing multicast packets. - -Feature: `v1_16` - -## `ttl` -the new multicast ttl value - -# Returns - -`true` if the requested ttl has been set successfully. - -Configure the mtu in the payloader of `self` to `mtu`. -## `mtu` -a new MTU - -configure `multicast_iface` to be used for `self`. -## `multicast_iface` -a multicast interface name - -Configure the allowed profiles for `self`. -## `profiles` -the new profiles - -Configure the allowed lower transport for `self`. -## `protocols` -the new flags - -Configure a pt map between `pt` and `caps`. -## `pt` -the pt -## `caps` -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` -a `guint` - -Set the amount of time to store retransmission packets. -## `time` -a `gst::ClockTime` - -Sets the amount of redundancy to apply when creating ULPFEC -protection packets. - -Feature: `v1_16` - - -Set the payload type to be used for ULPFEC protection packets - -Feature: `v1_16` - - -Call `func` for each transport managed by `self`. The result value of `func` -determines what happens to the transport. `func` will be called with `self` -locked so no further actions on `self` can be performed from `func`. - -If `func` returns `RTSPFilterResult::Remove`, the transport will be removed from -`self`. - -If `func` returns `RTSPFilterResult::Keep`, the transport will remain in `self`. - -If `func` returns `RTSPFilterResult::Ref`, the transport will remain in `self` but -will also be added with an additional ref to the result `glib::List` of this -function.. - -When `func` is `None`, `RTSPFilterResult::Ref` will be assumed for each transport. -## `func` -a callback -## `user_data` -user data passed to `func` - -# Returns - -a `glib::List` with all -transports for which `func` returned `RTSPFilterResult::Ref`. After usage, each -element in the `glib::List` should be unreffed before the list is freed. - -Update the new crypto information for `ssrc` in `self`. If information -for `ssrc` did not exist, it will be added. If information -for `ssrc` existed, it will be replaced. If `crypto` is `None`, it will -be removed from `self`. -## `ssrc` -the SSRC -## `crypto` -a `gst::Caps` with crypto info - -# Returns - -`true` if `crypto` could be updated - -Check if the requested multicast ttl value is allowed. - -Feature: `v1_16` - -## `ttl` -a requested multicast ttl - -# Returns - -TRUE if the requested ttl value is allowed. - -A Transport description for a stream - -# Implements - -[`RTSPStreamTransportExt`](trait@crate::RTSPStreamTransportExt), [`trait@glib::object::ObjectExt`], [`RTSPStreamTransportExtManual`](trait@crate::RTSPStreamTransportExtManual) - -Trait containing all `RTSPStreamTransport` methods. - -# Implementors - -[`RTSPStreamTransport`](struct@crate::RTSPStreamTransport) - -Create a new `RTSPStreamTransport` that can be used to manage -`stream` with transport `tr`. -## `stream` -a `RTSPStream` -## `tr` -a GstRTSPTransport - -# Returns - -a new `RTSPStreamTransport` - -Get the RTP-Info string for `self` and `start_time`. -## `start_time` -a star time - -# Returns - -the RTPInfo string for `self` -and `start_time` or `None` when the RTP-Info could not be -determined. `g_free` after usage. - -Get the `RTSPStream` used when constructing `self`. - -# Returns - -the stream used when constructing `self`. - -Get the transport configured in `self`. - -# Returns - -the transport configured in `self`. It remains -valid for as long as `self` is valid. - -Get the url configured in `self`. - -# Returns - -the url configured in `self`. -It remains valid for as long as `self` is valid. - -Check if `self` is timed out. - -# Returns - -`true` if `self` timed out. - -Signal the installed keep_alive callback for `self`. - -Signal the installed message_sent / message_sent_full callback for `self`. - -Feature: `v1_16` - - -Receive `buffer` on `channel` `self`. -## `channel` -a channel -## `buffer` -a `gst::Buffer` - -# Returns - -a `gst::FlowReturn`. Returns GST_FLOW_NOT_LINKED when `channel` is not - configured in the transport of `self`. - -Send `buffer` to the installed RTCP callback for `self`. -## `buffer` -a `gst::Buffer` - -# Returns - -`true` on success - -Send `buffer_list` to the installed RTCP callback for `self`. - -Feature: `v1_16` - -## `buffer_list` -a `gst::Buffer` - -# Returns - -`true` on success - -Send `buffer` to the installed RTP callback for `self`. -## `buffer` -a `gst::Buffer` - -# Returns - -`true` on success - -Send `buffer_list` to the installed RTP callback for `self`. - -Feature: `v1_16` - -## `buffer_list` -a `gst::BufferList` - -# Returns - -`true` on success - -Activate or deactivate datatransfer configured in `self`. -## `active` -new state of `self` - -# Returns - -`true` when the state was changed. - -Install callbacks that will be called when data for a stream should be sent -to a client. This is usually used when sending RTP/RTCP over TCP. -## `send_rtp` -a callback called when RTP should be sent -## `send_rtcp` -a callback called when RTCP should be sent -## `user_data` -user data passed to callbacks -## `notify` -called with the user_data when no longer needed. - -Install callbacks that will be called when RTCP packets are received from the -receiver of `self`. -## `keep_alive` -a callback called when the receiver is active -## `user_data` -user data passed to callback -## `notify` -called with the user_data when no longer needed. - -Install callbacks that will be called when data for a stream should be sent -to a client. This is usually used when sending RTP/RTCP over TCP. - -Feature: `v1_16` - -## `send_rtp_list` -a callback called when RTP should be sent -## `send_rtcp_list` -a callback called when RTCP should be sent -## `user_data` -user data passed to callbacks -## `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`. -## `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` -user data passed to callback -## `notify` -called with the user_data when no longer needed - -Set the timed out state of `self` to `timedout` -## `timedout` -timed out value - -Set `tr` as the client transport. This function takes ownership of the -passed `tr`. -## `tr` -a client `gst_rtsp::RTSPTransport` - -Set `url` as the client url. -## `url` -a client `gst_rtsp::RTSPUrl` - -The suspend mode of the media pipeline. A media pipeline is suspended right -after creating the SDP and when the client performs a PAUSED request. - -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. - -# Implements - -[`RTSPThreadPoolExt`](trait@crate::RTSPThreadPoolExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `RTSPThreadPool` methods. - -# Implementors - -[`RTSPThreadPool`](struct@crate::RTSPThreadPool) - -Create a new `RTSPThreadPool` instance. - -# Returns - -a new `RTSPThreadPool` - -Wait for all tasks to be stopped and free all allocated resources. This is -mainly used in test suites to ensure proper cleanup of internal data -structures. - -Get the maximum number of threads used for client connections. -See `RTSPThreadPoolExt::set_max_threads`. - -# Returns - -the maximum number of threads. - -Get a new `RTSPThread` for `type_` and `ctx`. -## `type_` -the `RTSPThreadType` -## `ctx` -a `RTSPContext` - -# Returns - -a new `RTSPThread`, -`RTSPThread::stop` after usage - -Set the maximum threads used by the pool to handle client requests. -A value of 0 will use the pool mainloop, a value of -1 will use an -unlimited number of threads. -## `max_threads` -maximum threads - -Different thread types - -a thread to handle the client communication - -a thread to handle media - -An opaque object used for checking authorisations. -It is generated after successful authentication. - -Create a new Authorization token with the given fieldnames and values. -Arguments are given similar to `gst::Structure::new`. -## `firstfield` -the first fieldname - -# Returns - -a new authorization token. - -Create a new empty Authorization token. - -# Returns - -a new empty authorization token. - -Create a new Authorization token with the given fieldnames and values. -Arguments are given similar to `gst::Structure::new_valist`. -## `firstfield` -the first fieldname -## `var_args` -additional arguments - -# Returns - -a new authorization token. - -Get the string value of `field` in `self`. -## `field` -a field name - -# Returns - -the string value of `field` in -`self` or `None` when `field` is not defined in `self`. The string -becomes invalid when you free `self`. - -Access the structure of the token. - -# Returns - -The structure of the token. The structure is still -owned by the token, which means that you should not free it and that the -pointer becomes invalid when you free the token. - -MT safe. - -Check if `self` has a boolean `field` and if it is set to `true`. -## `field` -a field name - -# Returns - -`true` if `self` has a boolean field named `field` set to `true`. - -Sets a boolean value on `self`. - -Feature: `v1_14` - -## `field` -field to set -## `bool_value` -boolean value to set - -Sets a string value on `self`. - -Feature: `v1_14` - -## `field` -field to set -## `string_value` -string value to set - -Get a writable version of the structure. - -# Returns - -The structure of the token. The structure is still -owned by the token, which means that you should not free it and that the -pointer becomes invalid when you free the token. This function checks if -`self` is writable and will never return `None`. - -MT safe. - -The supported modes of the media. - -Transport supports PLAY mode - -Transport supports RECORD mode diff --git a/docs/gstreamer-rtsp/docs.md b/docs/gstreamer-rtsp/docs.md deleted file mode 100644 index 72121975e..000000000 --- a/docs/gstreamer-rtsp/docs.md +++ /dev/null @@ -1,258 +0,0 @@ - - -Authentication methods, ordered by strength - -no authentication - -basic authentication - -digest authentication - -RTSP Authentication parameter - -Feature: `v1_12` - -The possible events for the connection. - -connection is readable - -connection is writable - -The possible network families. - -unknown network family - -internet - -internet V6 - -Enumeration of rtsp header fields - -The different transport methods. - -invalid transport flag - -stream data over UDP - -stream data over UDP multicast - -stream data over TCP - -stream data tunneled over HTTP. - -encrypt TCP and HTTP with TLS - -The different supported RTSP methods. - -invalid method - -the DESCRIBE method - -the ANNOUNCE method - -the GET_PARAMETER method - -the OPTIONS method - -the PAUSE method - -the PLAY method - -the RECORD method - -the REDIRECT method - -the SETUP method - -the SET_PARAMETER method - -the TEARDOWN method - -the GET method (HTTP). - -the POST method (HTTP). - -The type of a message. - -invalid message type - -RTSP request message - -RTSP response message - -HTTP request message. - -HTTP response message. - -data message - -The transfer profile to use. - -invalid profile - -the Audio/Visual profile (RFC 3551) - -the secure Audio/Visual profile (RFC 3711) - -the Audio/Visual profile with feedback (RFC 4585) - -the secure Audio/Visual profile with feedback (RFC 5124) - -Different possible time range units. - -SMPTE timecode - -29.97 frames per second - -25 frames per second - -Normal play time - -Absolute time expressed as ISO 8601 timestamps - -Result codes from the RTSP functions. - -no error - -some unspecified error occurred - -invalid arguments were provided to a function - -an operation was canceled - -no memory was available for the operation - -a host resolve error occurred - -function not implemented - -a system error occurred, errno contains more details - -a parsing error occurred - -windows networking could not start - -windows networking stack has wrong version - -end-of-file was reached - -a network problem occurred, h_errno contains more details - -the host is not an IP host - -a timeout occurred - -the tunnel GET request has been performed - -the tunnel POST request has been performed - -last error - -The different RTSP states. - -invalid state - -initializing - -ready for operation - -seeking in progress - -playing - -recording - -Enumeration of rtsp status codes - -Possible time types. - -seconds - -now - -end - -frames and subframes - -UTC time - -The transfer mode to use. - -invalid tansport mode - -transfer RTP data - -transfer RDT (RealMedia) data - -Provides helper functions to handle RTSP urls. - -Make a copy of `self`. - -# Returns - -a copy of `self`. Free with gst_rtsp_url_free () after usage. - -Splits the path of `self` on '/' boundaries, decoding the resulting components, - -The decoding performed by this routine is "URI decoding", as defined in RFC -3986, commonly known as percent-decoding. For example, a string "foo\%2fbar" -will decode to "foo/bar" -- the \%2f being replaced by the corresponding byte -with hex value 0x2f. Note that there is no guarantee that the resulting byte -sequence is valid in any given encoding. As a special case, \%00 is not -unescaped to NUL, as that would prematurely terminate the string. - -Also note that since paths usually start with a slash, the first component -will usually be the empty string. - -# Returns - -`None`-terminated array of URL components. Free with -`g_strfreev` when no longer needed. - -Free the memory used by `self`. - -Get the port number of `self`. -## `port` -location to hold the port - -# Returns - -`RTSPResult::Ok`. - -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` -the port - -# Returns - -`RTSPResult::Ok`. - -Parse the RTSP `urlstr` into a newly allocated `RTSPUrl`. Free after usage -with `RTSPUrl::free`. -## `urlstr` -the url string to parse -## `url` -location to hold the result. - -# Returns - -a `RTSPResult`. diff --git a/docs/gstreamer-sdp/docs.md b/docs/gstreamer-sdp/docs.md deleted file mode 100644 index d4fffaed4..000000000 --- a/docs/gstreamer-sdp/docs.md +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/gstreamer-video/docs.md b/docs/gstreamer-video/docs.md deleted file mode 100644 index 4df856901..000000000 --- a/docs/gstreamer-video/docs.md +++ /dev/null @@ -1,2856 +0,0 @@ - - -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` - -Additional video buffer flags. These flags can potentially be used on any -buffers carrying closed caption data, or video data - even encoded data. - -Note that these are only valid for `gst::Caps` of type: video/... and caption/... -They can conflict with other extended buffer flags. - -If the `gst::Buffer` is interlaced. In mixed - interlace-mode, this flags specifies if the frame is - interlaced or progressive. - -If the `gst::Buffer` is interlaced, then the first field - in the video frame is the top field. If unset, the - bottom field is first. - -If the `gst::Buffer` is interlaced, then the first field - (as defined by the `VideoBufferFlags::Tff` flag setting) - is repeated. - -If the `gst::Buffer` is interlaced, then only the - first field (as defined by the `VideoBufferFlags::Tff` - flag setting) is to be displayed (Since: 1.16). - -The `gst::Buffer` contains one or more specific views, - such as left or right eye view. This flags is set on - any buffer that contains non-mono content - even for - streams that contain only a single viewpoint. In mixed - mono / non-mono streams, the absence of the flag marks - mono buffers. - -When conveying stereo/multiview content with - frame-by-frame methods, this flag marks the first buffer - in a bundle of frames that belong together. - -The video frame has the top field only. This is the - same as GST_VIDEO_BUFFER_FLAG_TFF | - GST_VIDEO_BUFFER_FLAG_ONEFIELD (Since: 1.16). - Use GST_VIDEO_BUFFER_IS_TOP_FIELD() to check for this flag. - -The video frame has the bottom field only. This is - the same as GST_VIDEO_BUFFER_FLAG_ONEFIELD - (GST_VIDEO_BUFFER_FLAG_TFF flag unset) (Since: 1.16). - Use GST_VIDEO_BUFFER_IS_BOTTOM_FIELD() to check for this flag. - -The `gst::Buffer` contains the end of a video field or frame - boundary such as the last subframe or packet (Since: 1.18). - -Offset to define more flags - - - -# Implements - -[`trait@gst::BufferPoolExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Create a new bufferpool that can allocate video frames. This bufferpool -supports all the video bufferpool options. - -# Returns - -a new `gst::BufferPool` to allocate video frames - -The various known types of Closed Caption (CC). - -Unknown type of CC - -CEA-608 as byte pairs. Note that - this format is not recommended since is does not specify to - which field the caption comes from and therefore assumes - it comes from the first field (and that there is no information - on the second field). Use [`Cea708Raw`](Self::Cea708Raw) - if you wish to store CEA-608 from two fields and prefix each byte pair - with 0xFC for the first field and 0xFD for the second field. - -CEA-608 as byte triplets as defined - in SMPTE S334-1 Annex A. The second and third byte of the byte triplet - is the raw CEA608 data, the first byte is a bitfield: The top/7th bit is - 0 for the second field, 1 for the first field, bit 6 and 5 are 0 and - bits 4 to 0 are a 5 bit unsigned integer that represents the line - offset relative to the base-line of the original image format (line 9 - for 525-line field 1, line 272 for 525-line field 2, line 5 for - 625-line field 1 and line 318 for 625-line field 2). - -CEA-708 as cc_data byte triplets. They - can also contain 608-in-708 and the first byte of each triplet has to - be inspected for detecting the type. - -CEA-708 (and optionally CEA-608) in - a CDP (Caption Distribution Packet) defined by SMPTE S-334-2. - Contains the whole CDP (starting with 0x9669). - -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 - -Various Chroma sitings. - -unknown cositing - -no cositing - -chroma is horizontally cosited - -chroma is vertically cosited - -choma samples are sited on alternate lines - -chroma samples cosited with luma samples - -jpeg style cositing, also for mpeg1 and mjpeg - -mpeg2 style cositing - -DV style cositing - -A `VideoCodecFrame` represents a video frame both in raw and -encoded form. - -Gets private data set on the frame by the subclass via -`VideoCodecFrame::set_user_data` previously. - -# Returns - -The previously set user_data - -Increases the refcount of the given frame by one. - -# Returns - -`buf` - -Sets `user_data` on the frame and the `GDestroyNotify` that will be called when -the frame is freed. Allows to attach private data by the subclass to frames. - -If a `user_data` was previously set, then the previous set `notify` will be called -before the `user_data` is replaced. -## `user_data` -private data -## `notify` -a `GDestroyNotify` - -Decreases the refcount of the frame. If the refcount reaches 0, the frame -will be freed. - -Flags for `VideoCodecFrame` - -is the frame only meant to be decoded - -is the frame a synchronization point (keyframe) - -should the output frame be made a keyframe - -should the encoder output stream headers - -Structure representing the state of an incoming or outgoing video -stream for encoders and decoders. - -Decoders and encoders will receive such a state through their -respective `set_format` vmethods. - -Decoders and encoders can set the downstream state, by using the -[`crate::VideoDecoder::set_output_state`] (XXX: @-reference does not belong to VideoCodecState!)() or -[`crate::VideoEncoder::set_output_state`] (XXX: @-reference does not belong to VideoCodecState!)() methods. - -Increases the refcount of the given state by one. - -# Returns - -`buf` - -Decreases the refcount of the state. If the refcount reaches 0, the state -will be freed. - -The color matrix is used to convert between Y'PbPr and -non-linear RGB (R'G'B') - -unknown matrix - -identity matrix. Order of coefficients is -actually GBR, also IEC 61966-2-1 (sRGB) - -FCC Title 47 Code of Federal Regulations 73.682 (a)(20) - -ITU-R BT.709 color matrix, also ITU-R BT1361 -/ IEC 61966-2-4 xvYCC709 / SMPTE RP177 Annex B - -ITU-R BT.601 color matrix, also SMPTE170M / ITU-R BT1358 525 / ITU-R BT1700 NTSC - -SMPTE 240M color matrix - -ITU-R BT.2020 color matrix. Since: 1.6 - -The color primaries define the how to transform linear RGB values to and from -the CIE XYZ colorspace. - -unknown color primaries - -BT709 primaries, also ITU-R BT1361 / IEC -61966-2-4 / SMPTE RP177 Annex B - -BT470M primaries, also FCC Title 47 Code -of Federal Regulations 73.682 (a)(20) - -BT470BG primaries, also ITU-R BT601-6 -625 / ITU-R BT1358 625 / ITU-R BT1700 625 PAL & SECAM - -SMPTE170M primaries, also ITU-R -BT601-6 525 / ITU-R BT1358 525 / ITU-R BT1700 NTSC - -SMPTE240M primaries - -Generic film (colour filters using -Illuminant C) - -ITU-R BT2020 primaries. Since: 1.6 - -Adobe RGB primaries. Since: 1.8 - -SMPTE ST 428 primaries (CIE 1931 -XYZ). Since: 1.16 - -SMPTE RP 431 primaries (ST 431-2 -(2011) / DCI P3). Since: 1.16 - -SMPTE EG 432 primaries (ST 432-1 -(2010) / P3 D65). Since: 1.16 - -EBU 3213 primaries (JEDEC P22 -phosphors). Since: 1.16 - -Possible color range values. These constants are defined for 8 bit color -values and can be scaled for other bit depths. - -unknown range - -[0..255] for 8 bit components - -[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` -or `None` if all the entries of `self` are unknown values. - -This base class is for video decoders turning encoded data into raw video -frames. - -The GstVideoDecoder base class and derived subclasses should cooperate as -follows: - -## Configuration - - * Initially, GstVideoDecoder calls `start` when the decoder element - is activated, which allows the subclass to perform any global setup. - - * GstVideoDecoder calls `set_format` to inform the subclass of caps - describing input video data that it is about to receive, including - possibly configuration data. - While unlikely, it might be called more than once, if changing input - parameters require reconfiguration. - - * Incoming data buffers are processed as needed, described in Data - Processing below. - - * GstVideoDecoder calls `stop` at end of all processing. - -## Data processing - - * The base class gathers input data, and optionally allows subclass - to parse this into subsequently manageable chunks, typically - corresponding to and referred to as 'frames'. - - * Each input frame is provided in turn to the subclass' `handle_frame` - callback. - The ownership of the frame is given to the `handle_frame` callback. - - * If codec processing results in decoded data, the subclass should call - [`finish_frame`](Self::finish_frame) to have decoded data pushed. - downstream. Otherwise, the subclass must call - [`drop_frame`](Self::drop_frame), to allow the base class to do timestamp - and offset tracking, and possibly to requeue the frame for a later - attempt in the case of reverse playback. - -## Shutdown phase - - * The GstVideoDecoder class calls `stop` to inform the subclass that data - parsing will be stopped. - -## Additional Notes - - * Seeking/Flushing - - * When the pipeline is seeked or otherwise flushed, the subclass is - informed via a call to its `reset` callback, with the hard parameter - set to true. This indicates the subclass should drop any internal data - queues and timestamps and prepare for a fresh set of buffers to arrive - for parsing and decoding. - - * End Of Stream - - * At end-of-stream, the subclass `parse` function may be called some final - times with the at_eos parameter set to true, indicating that the element - should not expect any more data to be arriving, and it should parse and - remaining frames and call `VideoDecoder::have_frame` if possible. - -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 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 -[`finish_frame`](Self::finish_frame). This is done via -[`set_output_state`](Self::set_output_state) - -The subclass is also responsible for providing (presentation) timestamps -(likely based on corresponding input ones). If that is not applicable -or possible, the base class provides limited framerate based interpolation. - -Similarly, the base class provides some limited (legacy) seeking support -if specifically requested by the subclass, as full-fledged support -should rather be left to upstream demuxer, parser or alike. This simple -approach caters for seeking and duration reporting using estimated input -bitrates. To enable it, a subclass should call -[`crate::VideoDecoderExt::set_estimate_rate`] (XXX: @-reference does not belong to VideoDecoder!) to enable handling of incoming -byte-streams. - -The base class provides some support for reverse playback, in particular -in case incoming data is not packetized or upstream does not provide -fragments on keyframe boundaries. However, the subclass should then be -prepared for the parsing and frame processing stage to occur separately -(in normal forward processing, the latter immediately follows the former), -The subclass also needs to ensure the parsing stage properly marks -keyframes, unless it knows the upstream elements will do so properly for -incoming data. - -The bare minimum that a functional subclass needs to implement is: - - * Provide pad templates - * Inform the base class of output caps via - [`set_output_state`](Self::set_output_state) - - * Parse input data, if it is not considered packetized from upstream - Data will be provided to `parse` which should invoke - [`crate::VideoDecoderExt::add_to_frame`] (XXX: @-reference does not belong to VideoDecoder!) and [`have_frame`](Self::have_frame) to - separate the data belonging to each video frame. - - * Accept data in `handle_frame` and provide decoded results to - [`finish_frame`](Self::finish_frame), or call [`drop_frame`](Self::drop_frame). - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`VideoDecoderExt`](trait@crate::VideoDecoderExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`VideoDecoderExtManual`](trait@crate::VideoDecoderExtManual) - -Trait containing all `VideoDecoder` methods. - -# Implementors - -[`VideoDecoder`](struct@crate::VideoDecoder) - -Removes next `n_bytes` of input data and adds it to currently parsed frame. -## `n_bytes` -the number of bytes to add - -Helper function that allocates a buffer to hold a video frame for `self`'s -current `VideoCodecState`. - -You should use `VideoDecoder::allocate_output_frame` instead of this -function, if possible at all. - -# Returns - -allocated buffer, or NULL if no buffer could be - allocated (e.g. when downstream is flushing or shutting down) - -Helper function that allocates a buffer to hold a video frame for `self`'s -current `VideoCodecState`. Subclass should already have configured video -state and set src pad caps. - -The buffer allocated here is owned by the frame and you should only -keep references to the frame, not the buffer. -## `frame` -a `VideoCodecFrame` - -# Returns - -`gst::FlowReturn::Ok` if an output buffer could be allocated - -Same as `VideoDecoder::allocate_output_frame` except it allows passing -`gst::BufferPoolAcquireParams` to the sub call gst_buffer_pool_acquire_buffer. - -Feature: `v1_12` - -## `frame` -a `VideoCodecFrame` -## `params` -a `gst::BufferPoolAcquireParams` - -# Returns - -`gst::FlowReturn::Ok` if an output buffer could be allocated - -Similar to `VideoDecoder::finish_frame`, but drops `frame` in any -case and posts a QoS message with the frame's details on the bus. -In any case, the frame is considered finished and released. -## `frame` -the `VideoCodecFrame` to drop - -# Returns - -a `gst::FlowReturn`, usually GST_FLOW_OK. - -`frame` should have a valid decoded data buffer, whose metadata fields -are then appropriately set according to frame data and pushed downstream. -If no output data is provided, `frame` is considered skipped. -In any case, the frame is considered finished and released. - -After calling this function the output buffer of the frame is to be -considered read-only. This function will also change the metadata -of the buffer. -## `frame` -a decoded `VideoCodecFrame` - -# Returns - -a `gst::FlowReturn` resulting from sending data downstream - -Lets `VideoDecoder` sub-classes to know the memory `allocator` -used by the base class and its `params`. - -Unref the `allocator` after use it. -## `allocator` -the `gst::Allocator` -used -## `params` -the -`gst::AllocationParams` of `allocator` - - -# Returns - -the instance of the `gst::BufferPool` used -by the decoder; free it after use it - - -# Returns - -currently configured byte to time conversion setting - -Get a pending unfinished `VideoCodecFrame` -## `frame_number` -system_frame_number of a frame - -# Returns - -pending unfinished `VideoCodecFrame` identified by `frame_number`. - -Get all pending unfinished `VideoCodecFrame` - -# Returns - -pending unfinished `VideoCodecFrame`. - -Query the configured decoder latency. Results will be returned via -`min_latency` and `max_latency`. -## `min_latency` -address of variable in which to store the - configured minimum latency, or `None` -## `max_latency` -address of variable in which to store the - configured mximum latency, or `None` - -Determines maximum possible decoding time for `frame` that will -allow it to decode and arrive in time (as determined by QoS events). -In particular, a negative result means decoding in time is no longer possible -and should therefore occur as soon/skippy as possible. -## `frame` -a `VideoCodecFrame` - -# Returns - -max decoding time. - - -# Returns - -currently configured decoder tolerated error count. - -Queries decoder required format handling. - -# Returns - -`true` if required format handling is enabled. - -Get the oldest pending unfinished `VideoCodecFrame` - -# Returns - -oldest pending unfinished `VideoCodecFrame`. - -Get the `VideoCodecState` currently describing the output stream. - -# Returns - -`VideoCodecState` describing format of video data. - -Queries whether input data is considered packetized or not by the -base class. - -# Returns - -TRUE if input data is considered packetized. - -Returns the number of bytes previously added to the current frame -by calling `VideoDecoderExt::add_to_frame`. - -# Returns - -The number of bytes pending for the current frame - - -# Returns - -The current QoS proportion. - -Gathers all data collected for currently parsed frame, gathers corresponding -metadata and passes it along for further processing, i.e. `handle_frame`. - -# Returns - -a `gst::FlowReturn` - -Sets the audio decoder tags and how they should be merged with any -upstream stream tags. This will override any tags previously-set -with `gst_audio_decoder_merge_tags`. - -Note that this is provided for convenience, and the subclass is -not required to use this and can still do tag handling on its own. - -MT safe. -## `tags` -a `gst::TagList` to merge, or NULL to unset - previously-set tags -## `mode` -the `gst::TagMergeMode` to use, usually `gst::TagMergeMode::Replace` - -Negotiate with downstream elements to currently configured `VideoCodecState`. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - -# Returns - -`true` if the negotiation succeeded, else `false`. - -Returns caps that express `caps` (or sink template caps if `caps` == NULL) -restricted to resolution/format/... combinations supported by downstream -elements. -## `caps` -initial caps -## `filter` -filter caps - -# Returns - -a `gst::Caps` owned by caller - -Similar to `VideoDecoder::drop_frame`, but simply releases `frame` -without any processing other than removing it from list of pending frames, -after which it is considered finished and released. -## `frame` -the `VideoCodecFrame` to release - -Allows baseclass to perform byte to time estimated conversion. -## `enabled` -whether to enable byte to time conversion - -Same as `VideoDecoder::set_output_state`() but also allows you to also set -the interlacing mode. - -Feature: `v1_16` - -## `fmt` -a `VideoFormat` -## `interlace_mode` -A `VideoInterlaceMode` -## `width` -The width in pixels -## `height` -The height in pixels -## `reference` -An optional reference `VideoCodecState` - -# Returns - -the newly configured output state. - -Lets `VideoDecoder` sub-classes tell the baseclass what the decoder -latency is. Will also post a LATENCY message on the bus so the pipeline -can reconfigure its global latency. -## `min_latency` -minimum latency -## `max_latency` -maximum latency - -Sets numbers of tolerated decoder errors, where a tolerated one is then only -warned about, but more than tolerated will lead to fatal error. You can set --1 for never returning fatal errors. Default is set to -GST_VIDEO_DECODER_MAX_ERRORS. - -The '-1' option was added in 1.4 -## `num` -max tolerated errors - -Configures decoder format needs. If enabled, subclass needs to be -negotiated with format caps before it can process any data. It will then -never be handed any data before it has been configured. -Otherwise, it might be handed data without having been configured and -is then expected being able to do so either by default -or based on the input data. -## `enabled` -new state - -Creates a new `VideoCodecState` with the specified `fmt`, `width` and `height` -as the output state for the decoder. -Any previously set output state on `self` will be replaced by the newly -created one. - -If the subclass wishes to copy over existing fields (like pixel aspec ratio, -or framerate) from an existing `VideoCodecState`, it can be provided as a -`reference`. - -If the subclass wishes to override some fields from the output state (like -pixel-aspect-ratio or framerate) it can do so on the returned `VideoCodecState`. - -The new output state will only take effect (set on pads and buffers) starting -from the next call to `VideoDecoder::finish_frame`(). -## `fmt` -a `VideoFormat` -## `width` -The width in pixels -## `height` -The height in pixels -## `reference` -An optional reference `VideoCodecState` - -# Returns - -the newly configured output state. - -Allows baseclass to consider input data as packetized or not. If the -input is packetized, then the `parse` method will not be called. -## `packetized` -whether the input data should be considered as packetized. - -Lets `VideoDecoder` sub-classes decide if they want the sink pad -to use the default pad query handler to reply to accept-caps queries. - -By setting this to true it is possible to further customize the default -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 - -Maximum number of tolerated consecutive decode errors. See -`VideoDecoderExt::set_max_errors` for more details. - -Feature: `v1_18` - - -Maximum number of tolerated consecutive decode errors. See -`VideoDecoderExt::set_max_errors` for more details. - -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` - - -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. - -GstVideoEncoder and subclass should cooperate as follows. - -## Configuration - - * Initially, GstVideoEncoder calls `start` when the encoder element - is activated, which allows subclass to perform any global setup. - * GstVideoEncoder calls `set_format` to inform subclass of the format - of input video data that it is about to receive. Subclass should - setup for encoding and configure base class as appropriate - (e.g. latency). While unlikely, it might be called more than once, - if changing input parameters require reconfiguration. Baseclass - will ensure that processing of current configuration is finished. - * GstVideoEncoder calls `stop` at end of all processing. - -## Data processing - - * Base class collects input data and metadata into a frame and hands - this to subclass' `handle_frame`. - - * If codec processing results in encoded data, subclass should call - [`finish_frame`](Self::finish_frame) to have encoded data pushed - downstream. - - * If implemented, baseclass calls subclass `pre_push` just prior to - pushing to allow subclasses to modify some metadata on the buffer. - If it returns GST_FLOW_OK, the buffer is pushed downstream. - - * GstVideoEncoderClass will handle both srcpad and sinkpad events. - Sink events will be passed to subclass if `event` callback has been - provided. - -## Shutdown phase - - * GstVideoEncoder class calls `stop` to inform the subclass that data - parsing will be stopped. - -Subclass is responsible for providing pad template caps for -source and sink pads. The pads need to be named "sink" and "src". It should -also be able to provide fixed src pad caps in `getcaps` by the time it calls -[`finish_frame`](Self::finish_frame). - -Things that subclass need to take care of: - - * Provide pad templates - * Provide source pad caps before pushing the first buffer - * Accept data in `handle_frame` and provide encoded results to - [`finish_frame`](Self::finish_frame). - - -The `VideoEncoder:qos` property will enable the Quality-of-Service -features of the encoder which gather statistics about the real-time -performance of the downstream elements. If enabled, subclasses can -use `VideoEncoderExt::get_max_encode_time` to check if input frames -are already late and drop them right away to give a chance to the -pipeline to catch up. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`VideoEncoderExt`](trait@crate::VideoEncoderExt), [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`], [`VideoEncoderExtManual`](trait@crate::VideoEncoderExtManual) - -Trait containing all `VideoEncoder` methods. - -# Implementors - -[`VideoEncoder`](struct@crate::VideoEncoder) - -Helper function that allocates a buffer to hold an encoded video frame -for `self`'s current `VideoCodecState`. -## `size` -size of the buffer - -# Returns - -allocated buffer - -Helper function that allocates a buffer to hold an encoded video frame for `self`'s -current `VideoCodecState`. Subclass should already have configured video -state and set src pad caps. - -The buffer allocated here is owned by the frame and you should only -keep references to the frame, not the buffer. -## `frame` -a `VideoCodecFrame` -## `size` -size of the buffer - -# Returns - -`gst::FlowReturn::Ok` if an output buffer could be allocated - -`frame` must have a valid encoded data buffer, whose metadata fields -are then appropriately set according to frame data or no buffer at -all if the frame should be dropped. -It is subsequently pushed downstream or provided to `pre_push`. -In any case, the frame is considered finished and released. - -After calling this function the output buffer of the frame is to be -considered read-only. This function will also change the metadata -of the buffer. -## `frame` -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`. - -Unref the `allocator` after use it. -## `allocator` -the `gst::Allocator` -used -## `params` -the -`gst::AllocationParams` of `allocator` - -Get a pending unfinished `VideoCodecFrame` -## `frame_number` -system_frame_number of a frame - -# Returns - -pending unfinished `VideoCodecFrame` identified by `frame_number`. - -Get all pending unfinished `VideoCodecFrame` - -# Returns - -pending unfinished `VideoCodecFrame`. - -Query the configured encoding latency. Results will be returned via -`min_latency` and `max_latency`. -## `min_latency` -address of variable in which to store the - configured minimum latency, or `None` -## `max_latency` -address of variable in which to store the - configured maximum latency, or `None` - -Determines maximum possible encoding time for `frame` that will -allow it to encode and arrive in time (as determined by QoS events). -In particular, a negative result means encoding in time is no longer possible -and should therefore occur as soon/skippy as possible. - -If no QoS events have been received from downstream, or if -`VideoEncoder:qos` is disabled this function returns `G_MAXINT64`. - -Feature: `v1_14` - -## `frame` -a `VideoCodecFrame` - -# Returns - -max decoding time. - -Returns the minimum force-keyunit interval, see `VideoEncoderExt::set_min_force_key_unit_interval` -for more details. - -Feature: `v1_18` - - -# Returns - -the minimum force-keyunit interval - -Get the oldest unfinished pending `VideoCodecFrame` - -# Returns - -oldest unfinished pending `VideoCodecFrame` - -Get the current `VideoCodecState` - -# Returns - -`VideoCodecState` describing format of video data. - -Checks if `self` is currently configured to handle Quality-of-Service -events from downstream. - -Feature: `v1_14` - - -# Returns - -`true` if the encoder is configured to perform Quality-of-Service. - -Sets the video encoder tags and how they should be merged with any -upstream stream tags. This will override any tags previously-set -with `VideoEncoderExt::merge_tags`. - -Note that this is provided for convenience, and the subclass is -not required to use this and can still do tag handling on its own. - -MT safe. -## `tags` -a `gst::TagList` to merge, or NULL to unset - previously-set tags -## `mode` -the `gst::TagMergeMode` to use, usually `gst::TagMergeMode::Replace` - -Negotiate with downstream elements to currently configured `VideoCodecState`. -Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if -negotiate fails. - -# Returns - -`true` if the negotiation succeeded, else `false`. - -Returns caps that express `caps` (or sink template caps if `caps` == NULL) -restricted to resolution/format/... combinations supported by downstream -elements (e.g. muxers). -## `caps` -initial caps -## `filter` -filter caps - -# Returns - -a `gst::Caps` owned by caller - -Set the codec headers to be sent downstream whenever requested. -## `headers` -a list of `gst::Buffer` containing the codec header - -Informs baseclass of encoding latency. -## `min_latency` -minimum latency -## `max_latency` -maximum latency - -Sets the minimum interval for requesting keyframes based on force-keyunit -events. Setting this to 0 will allow to handle every event, setting this to -`GST_CLOCK_TIME_NONE` causes force-keyunit events to be ignored. - -Feature: `v1_18` - -## `interval` -minimum interval - -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 accommodate first DTS, which may be less than first PTS -## `min_pts` -minimal PTS that will be passed to handle_frame - -Creates a new `VideoCodecState` with the specified caps as the output state -for the encoder. -Any previously set output state on `self` will be replaced by the newly -created one. - -The specified `caps` should not contain any resolution, pixel-aspect-ratio, -framerate, codec-data, .... Those should be specified instead in the returned -`VideoCodecState`. - -If the subclass wishes to copy over existing fields (like pixel aspect ratio, -or framerate) from an existing `VideoCodecState`, it can be provided as a -`reference`. - -If the subclass wishes to override some fields from the output state (like -pixel-aspect-ratio or framerate) it can do so on the returned `VideoCodecState`. - -The new output state will only take effect (set on pads and buffers) starting -from the next call to `VideoEncoder::finish_frame`(). -## `caps` -the `gst::Caps` to use for the output -## `reference` -An optional reference [`crate::VideoCodecState`] (XXX: @-reference does not belong to VideoEncoderExt!) - -# Returns - -the newly configured output state. - -Configures `self` to handle Quality-of-Service events from downstream. - -Feature: `v1_14` - -## `enabled` -the new qos value. - -Minimum interval between force-keyunit requests in nanoseconds. See -`VideoEncoderExt::set_min_force_key_unit_interval` for more details. - -Feature: `v1_18` - - -Minimum interval between force-keyunit requests in nanoseconds. See -`VideoEncoderExt::set_min_force_key_unit_interval` for more details. - -Feature: `v1_18` - - -Field order of interlaced content. This is only valid for -interlace-mode=interleaved and not interlace-mode=mixed. In the case of -mixed or GST_VIDEO_FIELD_ORDER_UNKOWN, the field order is signalled via -buffer flags. - -unknown field order for interlaced content. - The actual field order is signalled via buffer flags. - -top field is first - -bottom field is first - -Feature: `v1_12` - - -Provides useful functions and a base class for video filters. - -The videofilter will by default enable QoS on the parent GstBaseTransform -to implement frame dropping. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`trait@gst_base::BaseTransformExt`], [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Extra video flags - -no flags - -a variable fps is selected, fps_n and fps_d - denote the maximum fps of the video - -Each color has been scaled by the alpha - value. - -Enum value describing the most common video 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 - -Encoded video format. Only ever use that in caps for - special video formats in combination with non-system - memory GstCapsFeatures where it does not make sense - to specify a real video format. - -planar 4:2:0 YUV - -planar 4:2:0 YVU (like I420 but UV planes swapped) - -packed 4:2:2 YUV (Y0-U0-Y1-V0 Y2-U2-Y3-V2 Y4 ...) - -packed 4:2:2 YUV (U0-Y0-V0-Y1 U2-Y2-V2-Y3 U4 ...) - -packed 4:4:4 YUV with alpha channel (A0-Y0-U0-V0 ...) - -sparse rgb packed into 32 bit, space last - -sparse reverse rgb packed into 32 bit, space last - -sparse rgb packed into 32 bit, space first - -sparse reverse rgb packed into 32 bit, space first - -rgb with alpha channel last - -reverse rgb with alpha channel last - -rgb with alpha channel first - -reverse rgb with alpha channel first - -RGB packed into 24 bits without padding (`R-G-B-R-G-B`) - -reverse RGB packed into 24 bits without padding (`B-G-R-B-G-R`) - -planar 4:1:1 YUV - -planar 4:2:2 YUV - -packed 4:2:2 YUV (Y0-V0-Y1-U0 Y2-V2-Y3-U2 Y4 ...) - -planar 4:4:4 YUV - -packed 4:2:2 10-bit YUV, complex format - -packed 4:2:2 16-bit YUV, Y0-U0-Y1-V1 order - -planar 4:2:0 YUV with interleaved UV plane - -planar 4:2:0 YUV with interleaved VU plane - -8-bit grayscale - -16-bit grayscale, most significant byte first - -16-bit grayscale, least significant byte first - -packed 4:4:4 YUV (Y-U-V ...) - -rgb 5-6-5 bits per component - -reverse rgb 5-6-5 bits per component - -rgb 5-5-5 bits per component - -reverse rgb 5-5-5 bits per component - -packed 10-bit 4:2:2 YUV (U0-Y0-V0-Y1 U2-Y2-V2-Y3 U4 ...) - -planar 4:4:2:0 AYUV - -8-bit paletted RGB - -planar 4:1:0 YUV - -planar 4:1:0 YUV (like YUV9 but UV planes swapped) - -packed 4:1:1 YUV (Cb-Y0-Y1-Cr-Y2-Y3 ...) - -rgb with alpha channel first, 16 bits per channel - -packed 4:4:4 YUV with alpha channel, 16 bits per channel (A0-Y0-U0-V0 ...) - -packed 4:4:4 RGB, 10 bits per channel - -planar 4:2:0 YUV, 10 bits per channel - -planar 4:2:0 YUV, 10 bits per channel - -planar 4:2:2 YUV, 10 bits per channel - -planar 4:2:2 YUV, 10 bits per channel - -planar 4:4:4 YUV, 10 bits per channel (Since: 1.2) - -planar 4:4:4 YUV, 10 bits per channel (Since: 1.2) - -planar 4:4:4 RGB, 8 bits per channel (Since: 1.2) - -planar 4:4:4 RGB, 10 bits per channel (Since: 1.2) - -planar 4:4:4 RGB, 10 bits per channel (Since: 1.2) - -planar 4:2:2 YUV with interleaved UV plane (Since: 1.2) - -planar 4:4:4 YUV with interleaved UV plane (Since: 1.2) - -NV12 with 64x32 tiling in zigzag pattern (Since: 1.4) - -planar 4:4:2:0 YUV, 10 bits per channel (Since: 1.6) - -planar 4:4:2:0 YUV, 10 bits per channel (Since: 1.6) - -planar 4:4:2:2 YUV, 10 bits per channel (Since: 1.6) - -planar 4:4:2:2 YUV, 10 bits per channel (Since: 1.6) - -planar 4:4:4:4 YUV, 10 bits per channel (Since: 1.6) - -planar 4:4:4:4 YUV, 10 bits per channel (Since: 1.6) - -planar 4:2:2 YUV with interleaved VU plane (Since: 1.6) - -planar 4:2:0 YUV with interleaved UV plane, 10 bits per channel (Since: 1.10) - -planar 4:2:0 YUV with interleaved UV plane, 10 bits per channel (Since: 1.10) - -packed 4:4:4 YUV (U-Y-V ...) (Since: 1.10) - -packed 4:2:2 YUV (V0-Y0-U0-Y1 V2-Y2-U2-Y3 V4 ...) - -planar 4:4:4:4 ARGB, 8 bits per channel (Since: 1.12) - -planar 4:4:4:4 ARGB, 10 bits per channel (Since: 1.12) - -planar 4:4:4:4 ARGB, 10 bits per channel (Since: 1.12) - -planar 4:4:4 RGB, 12 bits per channel (Since: 1.12) - -planar 4:4:4 RGB, 12 bits per channel (Since: 1.12) - -planar 4:4:4:4 ARGB, 12 bits per channel (Since: 1.12) - -planar 4:4:4:4 ARGB, 12 bits per channel (Since: 1.12) - -planar 4:2:0 YUV, 12 bits per channel (Since: 1.12) - -planar 4:2:0 YUV, 12 bits per channel (Since: 1.12) - -planar 4:2:2 YUV, 12 bits per channel (Since: 1.12) - -planar 4:2:2 YUV, 12 bits per channel (Since: 1.12) - -planar 4:4:4 YUV, 12 bits per channel (Since: 1.12) - -planar 4:4:4 YUV, 12 bits per channel (Since: 1.12) - -10-bit grayscale, packed into 32bit words (2 bits padding) (Since: 1.14) - -10-bit variant of [`Nv12`](Self::Nv12), packed into 32bit words (MSB 2 bits padding) (Since: 1.14) - -10-bit variant of [`Nv16`](Self::Nv16), packed into 32bit words (MSB 2 bits padding) (Since: 1.14) - -Fully packed variant of NV12_10LE32 (Since: 1.16) - -packed 4:2:2 YUV, 10 bits per channel (Since: 1.16) - -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) - -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) - -NV12 with 4x4 tiles in linear order. - -NV12 with 32x32 tiles in linear order. - -The different video flags that a format info can have. - -The video format is YUV, components are numbered - 0=Y, 1=U, 2=V. - -The video format is RGB, components are numbered - 0=R, 1=G, 2=B. - -The video is gray, there is one gray component - with index 0. - -The video format has an alpha components with - the number 3. - -The video format has data stored in little - endianness. - -The video format has a palette. The palette - is stored in the second plane and indexes are stored in the first plane. - -The video format has a complex layout that - can't be described with the usual information in the `VideoFormatInfo`. - -This format can be used in a - `GstVideoFormatUnpack` and `GstVideoFormatPack` function. - -The format is tiled, there is tiling information - in the last plane. - -Information for a video format. - -Feature: `v1_18` - -Fill `components` with the number of all the components packed in plane `p` -for the format `self`. A value of -1 in `components` indicates that no more -components are packed in the plane. - -Feature: `v1_18` - -## `plane` -a plane number -## `components` -array used to store component numbers - -A video frame obtained from `VideoFrame::map` - -Copy the contents from `src` to `self`. - -Note: Since: 1.18, `self` dimensions are allowed to be -smaller than `src` dimensions. -## `src` -a `VideoFrame` - -# Returns - -TRUE if the contents could be copied. - -Copy the plane with index `plane` from `src` to `self`. - -Note: Since: 1.18, `self` dimensions are allowed to be -smaller than `src` dimensions. -## `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. - -Extra video frame flags - -no flags - -The video frame is interlaced. In mixed - interlace-mode, this flag specifies if the frame is interlaced or - progressive. - -The video frame has the top field first - -The video frame has the repeat flag - -The video frame has one field - -The video contains one or - more non-mono views - -The video frame is the first - in a set of corresponding views provided as sequential frames. - -The video frame has the top field only. This - is the same as GST_VIDEO_FRAME_FLAG_TFF | GST_VIDEO_FRAME_FLAG_ONEFIELD - (Since: 1.16). - -The video frame has the bottom field - only. This is the same as GST_VIDEO_FRAME_FLAG_ONEFIELD - (GST_VIDEO_FRAME_FLAG_TFF flag unset) (Since: 1.16). - - -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 -to store the specific video info when mapping a video frame with -`VideoFrame::map`. - -Use the provided macros to access the info in this structure. - -Allocate a new `VideoInfo` that is also initialized with -`VideoInfo::init`. - -# Returns - -a new `VideoInfo`. free with `VideoInfo::free`. - -Adjust the offset and stride fields in `self` so that the padding and -stride alignment in `align` is respected. - -Extra padding will be added to the right side when stride alignment padding -is required and `align` will be updated with the new padding values. -## `align` -alignment parameters - -# 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 (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 -raw video, GST_FORMAT_DEFAULT corresponds to video frames. This -function can be used to handle pad queries of the type GST_QUERY_CONVERT. -## `src_format` -`gst::Format` of the `src_value` -## `src_value` -value to convert -## `dest_format` -`gst::Format` of the `dest_value` -## `dest_value` -pointer to destination value - -# Returns - -TRUE if the conversion was successful. - -Copy a GstVideoInfo structure. - -# Returns - -a new `VideoInfo`. free with gst_video_info_free. - -Free a GstVideoInfo structure previously allocated with `VideoInfo::new` -or `VideoInfo::copy`. - -Parse `caps` and update `self`. -## `caps` -a `gst::Caps` - -# Returns - -TRUE if `caps` could be parsed - -Initialize `self` with default values. - -Compares two `VideoInfo` and returns whether they are equal or not -## `other` -a `VideoInfo` - -# Returns - -`true` if `self` and `other` are equal, else `false`. - -Set the default info for a video frame of `format` and `width` and `height`. - -Note: This initializes `self` first, no values are preserved. This function -does not set the offsets correctly for interlaced vertically -subsampled formats. -## `format` -the format -## `width` -a width -## `height` -a height - -# Returns - -`false` if the returned video info is invalid, e.g. because the - size of a frame can't be represented as a 32 bit integer (Since: 1.12) - -Same as `VideoInfo::set_format` but also allowing to set the interlaced -mode. - -Feature: `v1_16` - -## `format` -the format -## `mode` -a `VideoInterlaceMode` -## `width` -a width -## `height` -a height - -# Returns - -`false` if the returned video info is invalid, e.g. because the - size of a frame can't be represented as a 32 bit integer. - -Convert the values of `self` into a `gst::Caps`. - -# Returns - -a new `gst::Caps` containing the info of `self`. - -The possible values of the `VideoInterlaceMode` describing the interlace -mode of the stream. - -all frames are progressive - -2 fields are interleaved in one video - frame. Extra buffer flags describe the field order. - -frames contains both interlaced and - progressive video, the buffer flags describe the frame and fields. - -2 fields are stored in one buffer, use the - frame ID to get access to the required field. For multiview (the - 'views' property > 1) the fields of view N can be found at frame ID - (N * 2) and (N * 2) + 1. - Each field has only half the amount of lines as noted in the - height property. This mode requires multiple GstVideoMeta metadata - to describe the fields. - -1 field is stored in one buffer, - `GST_VIDEO_BUFFER_FLAG_TF` or `GST_VIDEO_BUFFER_FLAG_BF` indicates if - the buffer is carrying the top or bottom field, respectively. The top and - bottom buffers must 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. - -GstVideoMultiviewFlags are used to indicate extra properties of a -stereo/multiview stream beyond the frame layout and buffer mapping -that is conveyed in the `VideoMultiviewMode`. - -No flags - -For stereo streams, the - normal arrangement of left and right views is reversed. - -The left view is vertically - mirrored. - -The left view is horizontally - mirrored. - -The right view is - vertically mirrored. - -The right view is - horizontally mirrored. - -For frame-packed - multiview modes, indicates that the individual - views have been encoded with half the true width or height - and should be scaled back up for display. This flag - is used for overriding input layout interpretation - by adjusting pixel-aspect-ratio. - For side-by-side, column interleaved or checkerboard packings, the - pixel width will be doubled. For row interleaved and top-bottom - encodings, pixel height will be doubled. - -The video stream contains both - mono and multiview portions, signalled on each buffer by the - absence or presence of the [`crate::VideoBufferFlags::MultipleView`] (XXX: @-reference does not belong to VideoMultiviewFlags!) - buffer flag. - -`VideoMultiviewFramePacking` represents the subset of `VideoMultiviewMode` -values that can be applied to any video frame without needing extra metadata. -It can be used by elements that provide a property to override the -multiview interpretation of a video stream when the video doesn't contain -any markers. - -This enum is used (for example) on playbin, to re-interpret a played -video stream as a stereoscopic video. The individual enum values are -equivalent to and have the same value as the matching `VideoMultiviewMode`. - -A special value indicating -no frame packing info. - -All frames are monoscopic. - -All frames represent a left-eye view. - -All frames represent a right-eye view. - -Left and right eye views are -provided in the left and right half of the frame respectively. - -Left and right eye -views are provided in the left and right half of the frame, but -have been sampled using quincunx method, with half-pixel offset -between the 2 views. - -Alternating vertical -columns of pixels represent the left and right eye view respectively. - -Alternating horizontal -rows of pixels represent the left and right eye view respectively. - -The top half of the frame -contains the left eye, and the bottom half the right eye. - -Pixels are arranged with -alternating pixels representing left and right eye views in a -checkerboard fashion. - -All possible stereoscopic 3D and multiview representations. -In conjunction with `VideoMultiviewFlags`, describes how -multiview content is being transported in the stream. - -A special value indicating -no multiview information. Used in GstVideoInfo and other places to -indicate that no specific multiview handling has been requested or -provided. This value is never carried on caps. - -All frames are monoscopic. - -All frames represent a left-eye view. - -All frames represent a right-eye view. - -Left and right eye views are -provided in the left and right half of the frame respectively. - -Left and right eye -views are provided in the left and right half of the frame, but -have been sampled using quincunx method, with half-pixel offset -between the 2 views. - -Alternating vertical -columns of pixels represent the left and right eye view respectively. - -Alternating horizontal -rows of pixels represent the left and right eye view respectively. - -The top half of the frame -contains the left eye, and the bottom half the right eye. - -Pixels are arranged with -alternating pixels representing left and right eye views in a -checkerboard fashion. - -Left and right eye views -are provided in separate frames alternately. - -Multiple -independent views are provided in separate frames in sequence. -This method only applies to raw video buffers at the moment. -Specific view identification is via the `GstVideoMultiviewMeta` -and `VideoMeta`(s) on raw video buffers. - -Multiple views are -provided as separate `gst::Memory` framebuffers attached to each -`gst::Buffer`, described by the `GstVideoMultiviewMeta` -and `VideoMeta`(s) - -The interface allows unified access to control flipping and autocenter -operation of video-sources or operators. - -# Implements - -[`VideoOrientationExt`](trait@crate::VideoOrientationExt) - -Trait containing all `VideoOrientation` methods. - -# Implementors - -[`VideoOrientation`](struct@crate::VideoOrientation) - -Get the horizontal centering offset from the given object. -## `center` -return location for the result - -# Returns - -`true` in case the element supports centering - -Get the horizontal flipping state (`true` for flipped) from the given object. -## `flip` -return location for the result - -# Returns - -`true` in case the element supports flipping - -Get the vertical centering offset from the given object. -## `center` -return location for the result - -# Returns - -`true` in case the element supports centering - -Get the vertical flipping state (`true` for flipped) from the given object. -## `flip` -return location for the result - -# Returns - -`true` in case the element supports flipping - -Set the horizontal centering offset for the given object. -## `center` -centering offset - -# Returns - -`true` in case the element supports centering - -Set the horizontal flipping state (`true` for flipped) for the given object. -## `flip` -use flipping - -# Returns - -`true` in case the element supports flipping - -Set the vertical centering offset for the given object. -## `center` -centering offset - -# Returns - -`true` in case the element supports centering - -Set the vertical flipping state (`true` for flipped) for the given object. -## `flip` -use flipping - -# Returns - -`true` in case the element supports flipping - -The different video orientation methods. - -Identity (no rotation) - -Rotate clockwise 90 degrees - -Rotate 180 degrees - -Rotate counter-clockwise 90 degrees - -Flip horizontally - -Flip vertically - -Flip across upper left/lower right diagonal - -Flip across upper right/lower left diagonal - -Select flip method based on image-orientation tag - -Current status depends on plugin internal setup - -Feature: `v1_10` - - -The `VideoOverlay` interface is used for 2 main purposes : - -* To get a grab on the Window where the video sink element is going to render. - This is achieved by either being informed about the Window identifier that - the video sink element generated, or by forcing the video sink element to use - a specific Window identifier for rendering. -* To force a redrawing of the latest video frame the video sink element - displayed on the Window. Indeed if the `gst::Pipeline` is in `gst::State::Paused` - state, moving the Window around will damage its content. Application - developers will want to handle the Expose events themselves and force the - video sink element to refresh the Window's content. - -Using the Window created by the video sink is probably the simplest scenario, -in some cases, though, it might not be flexible enough for application -developers if they need to catch events such as mouse moves and button -clicks. - -Setting a specific Window identifier on the video sink element is the most -flexible solution but it has some issues. Indeed the application needs to set -its Window identifier at the right time to avoid internal Window creation -from the video sink element. To solve this issue a `gst::Message` is posted on -the bus to inform the application that it should set the Window identifier -immediately. Here is an example on how to do that correctly: - -```text -static GstBusSyncReply -create_window (GstBus * bus, GstMessage * message, GstPipeline * pipeline) -{ - // ignore anything but 'prepare-window-handle' element messages - if (!gst_is_video_overlay_prepare_window_handle_message (message)) - return GST_BUS_PASS; - - win = XCreateSimpleWindow (disp, root, 0, 0, 320, 240, 0, 0, 0); - - XSetWindowBackgroundPixmap (disp, win, None); - - XMapRaised (disp, win); - - XSync (disp, FALSE); - - gst_video_overlay_set_window_handle (GST_VIDEO_OVERLAY (GST_MESSAGE_SRC (message)), - win); - - gst_message_unref (message); - - return GST_BUS_DROP; -} -... -int -main (int argc, char **argv) -{ -... - bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); - gst_bus_set_sync_handler (bus, (GstBusSyncHandler) create_window, pipeline, - NULL); -... -} -``` - -## Two basic usage scenarios - -There are two basic usage scenarios: in the simplest case, the application -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 -realize the window to render the video on and then -call `VideoOverlay::set_window_handle` directly with the XID or native -window handle, before starting up the pipeline. -As `playbin` and `playsink` implement the video overlay interface and proxy -it transparently to the actual video sink even if it is created later, this -case also applies when using these elements. - -In the other and more common case, the application does not know in advance -what GStreamer video sink element will be used for video output. This is -usually the case when an element such as `autovideosink` is used. -In this case, the video sink element itself is created -asynchronously from a GStreamer streaming thread some time after the -pipeline has been started up. When that happens, however, the video sink -will need to know right then whether to render onto an already existing -application window or whether to create its own window. This is when it -posts a prepare-window-handle message, and that is also why this message needs -to be handled in a sync bus handler which will be called from the streaming -thread directly (because the video sink will need an answer right then). - -As response to the prepare-window-handle element message in the bus sync -handler, the application may use `VideoOverlay::set_window_handle` to tell -the video sink to render onto an existing window surface. At this point the -application should already have obtained the window handle / XID, so it -just needs to set it. It is generally not advisable to call any GUI toolkit -functions or window system functions from the streaming thread in which the -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 -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` -used in the callback). - -## GstVideoOverlay and Gtk+ - - -```text -#include <gst/video/videooverlay.h> -#include <gtk/gtk.h> -#ifdef GDK_WINDOWING_X11 -#include <gdk/gdkx.h> // for GDK_WINDOW_XID -#endif -#ifdef GDK_WINDOWING_WIN32 -#include <gdk/gdkwin32.h> // for GDK_WINDOW_HWND -#endif -... -static guintptr video_window_handle = 0; -... -static GstBusSyncReply -bus_sync_handler (GstBus * bus, GstMessage * message, gpointer user_data) -{ - // ignore anything but 'prepare-window-handle' element messages - if (!gst_is_video_overlay_prepare_window_handle_message (message)) - return GST_BUS_PASS; - - if (video_window_handle != 0) { - GstVideoOverlay *overlay; - - // GST_MESSAGE_SRC (message) will be the video sink element - overlay = GST_VIDEO_OVERLAY (GST_MESSAGE_SRC (message)); - gst_video_overlay_set_window_handle (overlay, video_window_handle); - } else { - g_warning ("Should have obtained video_window_handle by now!"); - } - - gst_message_unref (message); - return GST_BUS_DROP; -} -... -static void -video_widget_realize_cb (GtkWidget * widget, gpointer data) -{ -#if GTK_CHECK_VERSION(2,18,0) - // Tell Gtk+/Gdk to create a native window for this widget instead of - // drawing onto the parent widget. - // This is here just for pedagogical purposes, GDK_WINDOW_XID will call - // it as well in newer Gtk versions - if (!gdk_window_ensure_native (widget->window)) - g_error ("Couldn't create native window needed for GstVideoOverlay!"); -#endif - -#ifdef GDK_WINDOWING_X11 - { - gulong xid = GDK_WINDOW_XID (gtk_widget_get_window (video_window)); - video_window_handle = xid; - } -#endif -#ifdef GDK_WINDOWING_WIN32 - { - HWND wnd = GDK_WINDOW_HWND (gtk_widget_get_window (video_window)); - video_window_handle = (guintptr) wnd; - } -#endif -} -... -int -main (int argc, char **argv) -{ - GtkWidget *video_window; - GtkWidget *app_window; - ... - app_window = gtk_window_new (GTK_WINDOW_TOPLEVEL); - ... - video_window = gtk_drawing_area_new (); - g_signal_connect (video_window, "realize", - G_CALLBACK (video_widget_realize_cb), NULL); - gtk_widget_set_double_buffered (video_window, FALSE); - ... - // usually the video_window will not be directly embedded into the - // application window like this, but there will be many other widgets - // and the video window will be embedded in one of them instead - gtk_container_add (GTK_CONTAINER (ap_window), video_window); - ... - // show the GUI - gtk_widget_show_all (app_window); - - // realize window now so that the video window gets created and we can - // obtain its XID/HWND before the pipeline is started up and the videosink - // asks for the XID/HWND of the window to render onto - gtk_widget_realize (video_window); - - // we should have the XID/HWND now - g_assert (video_window_handle != 0); - ... - // set up sync handler for setting the xid once the pipeline is started - bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); - gst_bus_set_sync_handler (bus, (GstBusSyncHandler) bus_sync_handler, NULL, - NULL); - gst_object_unref (bus); - ... - gst_element_set_state (pipeline, GST_STATE_PLAYING); - ... -} -``` - -## GstVideoOverlay and Qt - - -```text -#include ; -#include ; -#include ; - -#include ; -#include ; -#include ; - -int main(int argc, char *argv[]) -{ - if (!g_thread_supported ()) - g_thread_init (NULL); - - gst_init (&argc, &argv); - QApplication app(argc, argv); - app.connect(&app, SIGNAL(lastWindowClosed()), &app, SLOT(quit ())); - - // prepare the pipeline - - GstElement *pipeline = gst_pipeline_new ("xvoverlay"); - GstElement *src = gst_element_factory_make ("videotestsrc", NULL); - GstElement *sink = gst_element_factory_make ("xvimagesink", NULL); - gst_bin_add_many (GST_BIN (pipeline), src, sink, NULL); - gst_element_link (src, sink); - - // prepare the ui - - QWidget window; - window.resize(320, 240); - window.show(); - - WId xwinid = window.winId(); - gst_video_overlay_set_window_handle (GST_VIDEO_OVERLAY (sink), xwinid); - - // run the pipeline - - GstStateChangeReturn sret = gst_element_set_state (pipeline, - GST_STATE_PLAYING); - if (sret == GST_STATE_CHANGE_FAILURE) { - gst_element_set_state (pipeline, GST_STATE_NULL); - gst_object_unref (pipeline); - // Exit application - QTimer::singleShot(0, QApplication::activeWindow(), SLOT(quit())); - } - - int ret = app.exec(); - - window.hide(); - gst_element_set_state (pipeline, GST_STATE_NULL); - gst_object_unref (pipeline); - - return ret; -} -``` - -# Implements - -[`VideoOverlayExt`](trait@crate::VideoOverlayExt), [`VideoOverlayExtManual`](trait@crate::VideoOverlayExtManual) - -Trait containing all `VideoOverlay` methods. - -# Implementors - -[`VideoOverlay`](struct@crate::VideoOverlay) - -This helper shall be used by classes implementing the `VideoOverlay` -interface that want the render rectangle to be controllable using -properties. This helper will install "render-rectangle" property into the -class. - -Feature: `v1_14` - -## `oclass` -The class on which the properties will be installed -## `last_prop_id` -The first free property ID to use - -This helper shall be used by classes implementing the `VideoOverlay` -interface that want the render rectangle to be controllable using -properties. This helper will parse and set the render rectangle calling -`VideoOverlay::set_render_rectangle`. - -Feature: `v1_14` - -## `object` -The instance on which the property is set -## `last_prop_id` -The highest property ID. -## `property_id` -The property ID -## `value` -The `glib::object::Value` to be set - -# Returns - -`true` if the `property_id` matches the GstVideoOverlay property - -Tell an overlay that it has been exposed. This will redraw the current frame -in the drawable even if the pipeline is PAUSED. - -This will post a "have-window-handle" element message on the bus. - -This function should only be used by video overlay plugin developers. -## `handle` -a platform-specific handle referencing the window - -Tell an overlay that it should handle events from the window system. These -events are forwarded upstream as navigation events. In some window system, -events are not propagated in the window hierarchy if a client is listening -for them. This method allows you to disable events handling completely -from the `VideoOverlay`. -## `handle_events` -a `gboolean` indicating if events should be handled or not. - -This will post a "prepare-window-handle" element message on the bus -to give applications an opportunity to call -`VideoOverlay::set_window_handle` before a plugin creates its own -window. - -This function should only be used by video overlay plugin developers. - -Configure a subregion as a video target within the window set by -`VideoOverlay::set_window_handle`. If this is not used or not supported -the video will fill the area of the window set as the overlay to 100%. -By specifying the rectangle, the video can be overlayed to a specific region -of that window only. After setting the new rectangle one should call -`VideoOverlay::expose` to force a redraw. To unset the region pass -1 for -the `width` and `height` parameters. - -This method is needed for non fullscreen video overlay in UI toolkits that -do not support subwindows. -## `x` -the horizontal offset of the render area inside the window -## `y` -the vertical offset of the render area inside the window -## `width` -the width of the render area inside the window -## `height` -the height of the render area inside the window - -# Returns - -`false` if not supported by the sink. - -This will call the video overlay's set_window_handle method. You -should use this method to tell to an overlay to display video output to a -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. - -Overlay format flags. - -no flags - -RGB are premultiplied by A/255. - -a global-alpha value != 1 is set. - -The different flags that can be used when packing and unpacking. - -No flag - -When the source has a smaller depth - than the target format, set the least significant bits of the target - to 0. This is likely slightly faster but less accurate. When this flag - is not specified, the most significant bits of the source are duplicated - in the least significant bits of the destination. - -The source is interlaced. The unpacked - format will be interlaced as well with each line containing - information from alternating fields. (Since: 1.2) - -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@crate::VideoSinkExt), [`trait@gst_base::BaseSinkExt`], [`trait@gst::ElementExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`] - -Trait containing all `VideoSink` methods. - -# Implementors - -[`VideoSink`](struct@crate::VideoSink) - -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. - -Unknown or unset tile mode - -Every four adjacent blocks - two - horizontally and two vertically are grouped together and are located - in memory in Z or flipped Z order. In case of odd rows, the last row - of blocks is arranged in linear order. - -Tiles are in row order. - -`field_count` must be 0 for progressive video and 1 or 2 for interlaced. - -A representation of a SMPTE time code. - -`hours` must be positive and less than 24. Will wrap around otherwise. -`minutes` and `seconds` must be positive and less than 60. -`frames` must be less than or equal to `config.fps_n` / `config.fps_d` -These values are *NOT* automatically normalized. - -Feature: `v1_10` - -`field_count` is 0 for progressive, 1 or 2 for interlaced. -`latest_daiy_jam` reference is stolen from caller. - -Feature: `v1_10` - -## `fps_n` -Numerator of the frame rate -## `fps_d` -Denominator of the frame rate -## `latest_daily_jam` -The latest daily jam of the `VideoTimeCode` -## `flags` -`VideoTimeCodeFlags` -## `hours` -the hours field of `VideoTimeCode` -## `minutes` -the minutes field of `VideoTimeCode` -## `seconds` -the seconds field of `VideoTimeCode` -## `frames` -the frames field of `VideoTimeCode` -## `field_count` -Interlaced video field count - -# Returns - -a new `VideoTimeCode` with the given values. -The values are not checked for being in a valid range. To see if your -timecode actually has valid content, use `VideoTimeCode::is_valid`. - - -Feature: `v1_10` - - -# Returns - -a new empty, invalid `VideoTimeCode` - -The resulting config->latest_daily_jam is set to -midnight, and timecode is set to the given time. - -This might return a completely invalid timecode, use -`VideoTimeCode::new_from_date_time_full` to ensure -that you would get `None` instead in that case. - -Feature: `v1_12` - -## `fps_n` -Numerator of the frame rate -## `fps_d` -Denominator of the frame rate -## `dt` -`glib::DateTime` to convert -## `flags` -`VideoTimeCodeFlags` -## `field_count` -Interlaced video field count - -# Returns - -the `VideoTimeCode` representation of `dt`. - -The resulting config->latest_daily_jam is set to -midnight, and timecode is set to the given time. - -Feature: `v1_16` - -## `fps_n` -Numerator of the frame rate -## `fps_d` -Denominator of the frame rate -## `dt` -`glib::DateTime` to convert -## `flags` -`VideoTimeCodeFlags` -## `field_count` -Interlaced video field count - -# Returns - -the `VideoTimeCode` representation of `dt`, or `None` if - no valid timecode could be created. - - -Feature: `v1_12` - -## `tc_str` -The string that represents the `VideoTimeCode` - -# Returns - -a new `VideoTimeCode` from the given string or `None` - if the string could not be passed. - -Adds or subtracts `frames` amount of frames to `self`. tc needs to -contain valid data, as verified by `VideoTimeCode::is_valid`. - -Feature: `v1_10` - -## `frames` -How many frames to add or subtract - -This makes a component-wise addition of `tc_inter` to `self`. For example, -adding ("01:02:03:04", "00:01:00:00") will return "01:03:03:04". -When it comes to drop-frame timecodes, -adding ("00:00:00;00", "00:01:00:00") will return "00:01:00;02" -because of drop-frame oddities. However, -adding ("00:09:00;02", "00:01:00:00") will return "00:10:00;00" -because this time we can have an exact minute. - -Feature: `v1_12` - -## `tc_inter` -The `VideoTimeCodeInterval` to add to `self`. -The interval must contain valid values, except that for drop-frame -timecode, it may also contain timecodes which would normally -be dropped. These are then corrected to the next reasonable timecode. - -# Returns - -A new `VideoTimeCode` with `tc_inter` added or `None` - if the interval can't be added. - -Initializes `self` with empty/zero/NULL values and frees any memory -it might currently use. - -Feature: `v1_10` - - -Compares `self` and `tc2`. If both have latest daily jam information, it is -taken into account. Otherwise, it is assumed that the daily jam of both -`self` and `tc2` was at the same time. Both time codes must be valid. - -Feature: `v1_10` - -## `tc2` -another valid `VideoTimeCode` - -# Returns - -1 if `self` is after `tc2`, -1 if `self` is before `tc2`, 0 otherwise. - - -Feature: `v1_10` - - -# Returns - -a new `VideoTimeCode` with the same values as `self`. - - -Feature: `v1_10` - - -# Returns - -how many frames have passed since the daily jam of `self`. - -Frees `self`. - -Feature: `v1_10` - - -Adds one frame to `self`. - -Feature: `v1_10` - - -`field_count` is 0 for progressive, 1 or 2 for interlaced. -`latest_daiy_jam` reference is stolen from caller. - -Initializes `self` with the given values. -The values are not checked for being in a valid range. To see if your -timecode actually has valid content, use `VideoTimeCode::is_valid`. - -Feature: `v1_10` - -## `fps_n` -Numerator of the frame rate -## `fps_d` -Denominator of the frame rate -## `latest_daily_jam` -The latest daily jam of the `VideoTimeCode` -## `flags` -`VideoTimeCodeFlags` -## `hours` -the hours field of `VideoTimeCode` -## `minutes` -the minutes field of `VideoTimeCode` -## `seconds` -the seconds field of `VideoTimeCode` -## `frames` -the frames field of `VideoTimeCode` -## `field_count` -Interlaced video field count - -The resulting config->latest_daily_jam is set to midnight, and timecode is -set to the given time. - -Will assert on invalid parameters, use `VideoTimeCode::init_from_date_time_full` -for being able to handle invalid parameters. - -Feature: `v1_12` - -## `fps_n` -Numerator of the frame rate -## `fps_d` -Denominator of the frame rate -## `dt` -`glib::DateTime` to convert -## `flags` -`VideoTimeCodeFlags` -## `field_count` -Interlaced video field count - -The resulting config->latest_daily_jam is set to -midnight, and timecode is set to the given time. - -Feature: `v1_16` - -## `fps_n` -Numerator of the frame rate -## `fps_d` -Denominator of the frame rate -## `dt` -`glib::DateTime` to convert -## `flags` -`VideoTimeCodeFlags` -## `field_count` -Interlaced video field count - -# Returns - -`true` if `self` could be correctly initialized to a valid timecode - - -Feature: `v1_10` - - -# Returns - -whether `self` is a valid timecode (supported frame rate, -hours/minutes/seconds/frames not overflowing) - - -Feature: `v1_10` - - -# Returns - -how many nsec have passed since the daily jam of `self`. - -The `self.config`->latest_daily_jam is required to be non-NULL. - -Feature: `v1_10` - - -# Returns - -the `glib::DateTime` representation of `self` or `None` if `self` - has no daily jam. - - -Feature: `v1_10` - - -# Returns - -the SMPTE ST 2059-1:2015 string representation of `self`. That will -take the form hh:mm:ss:ff. The last separator (between seconds and frames) -may vary: - -';' for drop-frame, non-interlaced content and for drop-frame interlaced -field 2 -',' for drop-frame interlaced field 1 -':' for non-drop-frame, non-interlaced content and for non-drop-frame -interlaced field 2 -'.' for non-drop-frame interlaced field 1 - -Flags related to the time code information. -For drop frame, only 30000/1001 and 60000/1001 frame rates are supported. - -No flags - -Whether we have drop frame rate - -Whether we have interlaced video - -Feature: `v1_10` - - -A representation of a difference between two `VideoTimeCode` instances. -Will not necessarily correspond to a real timecode (e.g. 00:00:10;00) - -Feature: `v1_12` - - -Feature: `v1_12` - -## `hours` -the hours field of `VideoTimeCodeInterval` -## `minutes` -the minutes field of `VideoTimeCodeInterval` -## `seconds` -the seconds field of `VideoTimeCodeInterval` -## `frames` -the frames field of `VideoTimeCodeInterval` - -# Returns - -a new `VideoTimeCodeInterval` with the given values. - -`tc_inter_str` must only have ":" as separators. - -Feature: `v1_12` - -## `tc_inter_str` -The string that represents the `VideoTimeCodeInterval` - -# Returns - -a new `VideoTimeCodeInterval` from the given string - or `None` if the string could not be passed. - -Initializes `self` with empty/zero/NULL values. - -Feature: `v1_12` - - - -Feature: `v1_12` - - -# Returns - -a new `VideoTimeCodeInterval` with the same values as `self`. - -Frees `self`. - -Feature: `v1_12` - - -Initializes `self` with the given values. - -Feature: `v1_12` - -## `hours` -the hours field of `VideoTimeCodeInterval` -## `minutes` -the minutes field of `VideoTimeCodeInterval` -## `seconds` -the seconds field of `VideoTimeCodeInterval` -## `frames` -the frames field of `VideoTimeCodeInterval` - -The video transfer function defines the formula for converting between -non-linear RGB (R'G'B') and linear RGB - -unknown transfer function - -linear RGB, gamma 1.0 curve - -Gamma 1.8 curve - -Gamma 2.0 curve - -Gamma 2.2 curve - -Gamma 2.2 curve with a linear segment in the lower - range, also ITU-R BT470M / ITU-R BT1700 625 PAL & - SECAM / ITU-R BT1361 - -Gamma 2.2 curve with a linear segment in the - lower range - -Gamma 2.4 curve with a linear segment in the lower - range. IEC 61966-2-1 (sRGB or sYCC) - -Gamma 2.8 curve, also ITU-R BT470BG - -Logarithmic transfer characteristic - 100:1 range - -Logarithmic transfer characteristic - 316.22777:1 range (100 * sqrt(10) : 1) - -Gamma 2.2 curve with a linear segment in the lower - range. Used for BT.2020 with 12 bits per - 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_BT601). - 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 - -also known as SMPTE170M / ITU-R BT1358 525 or 625 / ITU-R BT1700 NTSC diff --git a/docs/gstreamer-webrtc/docs.md b/docs/gstreamer-webrtc/docs.md deleted file mode 100644 index 36ecd231b..000000000 --- a/docs/gstreamer-webrtc/docs.md +++ /dev/null @@ -1,332 +0,0 @@ - - -GST_WEBRTC_BUNDLE_POLICY_NONE: none -GST_WEBRTC_BUNDLE_POLICY_BALANCED: balanced -GST_WEBRTC_BUNDLE_POLICY_MAX_COMPAT: max-compat -GST_WEBRTC_BUNDLE_POLICY_MAX_BUNDLE: max-bundle -See https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24`section`-4.1.1 -for more information. - -Feature: `v1_16` - - - -none - -actpass - -sendonly - -recvonly - - - -# Implements - -[`trait@glib::object::ObjectExt`] - - -new - -closed - -failed - -connecting - -connected - - - -This is an Abstract Base Class, you cannot instantiate it. - -Feature: `v1_18` - -# Implements - -[`trait@glib::object::ObjectExt`] - -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 - -Feature: `v1_16` - - - -none - -ulpfec + red - -Feature: `v1_14_1` - - - -RTP component - -RTCP component - -See - -new - -checking - -connected - -completed - -failed - -disconnected - -closed - -See - -new - -gathering - -complete - - -controlled - -controlling - - - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`trait@glib::object::ObjectExt`] - -GST_WEBRTC_ICE_TRANSPORT_POLICY_ALL: all -GST_WEBRTC_ICE_TRANSPORT_POLICY_RELAY: relay -See https://tools.ietf.org/html/draft-ietf-rtcweb-jsep-24`section`-4.1.1 -for more information. - -Feature: `v1_16` - - -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 - -Feature: `v1_16` - - - - -# Implements - -[`trait@glib::object::ObjectExt`] - - - -# Implements - -[`trait@glib::object::ObjectExt`] - - - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`trait@glib::object::ObjectExt`] - -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 - -Feature: `v1_16` - - -See - -offer - -pranswer - -answer - -rollback - -See - -## `type_` -a `WebRTCSDPType` -## `sdp` -a `gst_sdp::SDPMessage` - -# Returns - -a new `WebRTCSessionDescription` from `type_` - and `sdp` - - -# Returns - -a new copy of `self` - -Free `self` and all associated resources - -See - -stable - -closed - -have-local-offer - -have-remote-offer - -have-local-pranswer - -have-remote-pranswer - - -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 deleted file mode 100644 index 0cbd79723..000000000 --- a/docs/gstreamer/docs.md +++ /dev/null @@ -1,16449 +0,0 @@ - - -Parameters to control the allocation of memory - -Create a copy of `self`. - -Free-function: gst_allocation_params_free - -# Returns - -a new #`AllocationParams`, free with -`AllocationParams::free`. - -Free `self` - -Initialize `self` to its default values - -Memory is usually created by allocators with a `AllocatorExt::alloc` -method call. When `None` is used as the allocator, the default allocator will -be used. - -New allocators can be registered with `Allocator::register`. -Allocators are identified by name and can be retrieved with -`Allocator::find`. `AllocatorExt::set_default` can be used to change the -default allocator. - -New memory can be created with `Memory::new_wrapped` that wraps the memory -allocated elsewhere. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`AllocatorExt`](trait@crate::AllocatorExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `Allocator` methods. - -# Implementors - -[`Allocator`](struct@crate::Allocator) - -Find a previously registered allocator with `name`. When `name` is `None`, the -default allocator will be returned. -## `name` -the name of the allocator - -# Returns - -a `Allocator` or `None` when -the allocator with `name` was not registered. Use `GstObjectExt::unref` -to release the allocator after usage. - -Registers the memory `allocator` with `name`. This function takes ownership of -`allocator`. -## `name` -the name of the allocator -## `allocator` -`Allocator` - -Use `self` to allocate a new memory block with memory that is at least -`size` big. - -The optional `params` can specify the prefix and padding for the memory. If -`None` is passed, no flags, no extra prefix/padding and a default alignment is -used. - -The prefix/padding will be filled with 0 if flags contains -`MemoryFlags::ZeroPrefixed` and `MemoryFlags::ZeroPadded` respectively. - -When `self` is `None`, the default allocator will be used. - -The alignment in `params` is given as a bitmask so that `align` + 1 equals -the amount of bytes to align to. For example, to align to 8 bytes, -use an alignment of 7. -## `size` -size of the visible memory area -## `params` -optional parameters - -# Returns - -a new `Memory`. - -Free `memory` that was previously allocated with `AllocatorExt::alloc`. -## `memory` -the memory to free - -Set the default allocator. This function takes ownership of `self`. - -`Bin` is an element that can contain other `Element`, allowing them to be -managed as a group. -Pads from the child elements can be ghosted to the bin, see `GhostPad`. -This makes the bin look like any other elements and enables creation of -higher-level abstraction elements. - -A new `Bin` is created with `Bin::new`. Use a `Pipeline` instead if you -want to create a toplevel bin because a normal bin doesn't have a bus or -handle clock distribution of its own. - -After the bin has been created you will typically add elements to it with -`GstBinExt::add`. You can remove elements with `GstBinExt::remove`. - -An element can be retrieved from a bin with `GstBinExt::get_by_name`, using the -elements name. `GstBinExt::get_by_name_recurse_up` is mainly used for internal -purposes and will query the parent bins when the element is not found in the -current bin. - -An iterator of elements in a bin can be retrieved with -`GstBinExt::iterate_elements`. Various other iterators exist to retrieve the -elements in a bin. - -`GstObjectExt::unref` is used to drop your reference to the bin. - -The `Bin::element-added` signal is fired whenever a new element is added to -the bin. Likewise the `Bin::element-removed` signal is fired whenever an -element is removed from the bin. - -## Notes - -A `Bin` internally intercepts every `Message` posted by its children and -implements the following default behaviour for each of them: - -* GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING -state. If all sinks posted the EOS message, this bin will post and EOS -message upwards. - -* GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards. -The messages are used to decide when all elements have completed playback -of their segment. - -* GST_MESSAGE_SEGMENT_DONE: Is posted by `Bin` when all elements that posted -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 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. 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 -check if the lost clock was the one provided by the bin. If so and -the bin is currently in the PLAYING state, the message is forwarded to -the bin parent. -This message is also generated when a clock provider is removed from -the bin. If this message is received by the application, it should -PAUSE the pipeline and set it back to PLAYING to force a new clock -distribution. - -* GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element -can provide a clock. This mostly happens when a new clock -provider is added to the bin. The default behaviour of the bin is to -mark the currently selected clock as dirty, which will perform a clock -recalculation the next time the bin is asked to provide a clock. -This message is never sent tot the application but is forwarded to -the parent of the bin. - -* OTHERS: posted upwards. - -A `Bin` implements the following default behaviour for answering to a -`Query`: - -* 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 -MAXIMUM of all values is returned. If no sinks are available in the bin, -the query fails. - -* OTHERS:the query is forwarded to all sink elements, the result -of the first sink that answers the query successfully is returned. If no -sink is in the bin, the query fails. - -A `Bin` will by default forward any event sent to it to all sink -(`EventTypeFlags::Downstream`) or source (`EventTypeFlags::Upstream`) elements -depending on the event type. -If all the elements return `true`, the bin will also return `true`, else `false` -is returned. If no elements of the required type are in the bin, the event -handler will return `true`. - -# Implements - -[`GstBinExt`](trait@crate::GstBinExt), [`ElementExt`](trait@crate::ElementExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`ChildProxyExt`](trait@crate::ChildProxyExt), [`ElementExtManual`](trait@crate::ElementExtManual), [`ChildProxyExtManual`](trait@crate::ChildProxyExtManual) - -Trait containing all `Bin` methods. - -# Implementors - -[`Bin`](struct@crate::Bin), [`Pipeline`](struct@crate::Pipeline) - -Creates a new bin with the given name. -## `name` -the name of the new bin - -# Returns - -a new `Bin` - -Adds the given element to the bin. Sets the element's parent, and thus -takes ownership of the element. An element can only be added to one bin. - -If the element's pads are linked to other pads, the pads will be unlinked -before the element is added to the bin. - -> When you add an element to an already-running pipeline, you will have to -> take care to set the state of the newly-added element to the desired -> state (usually PLAYING or PAUSED, same you set the pipeline to originally) -> with `Element::set_state`, or use `ElementExt::sync_state_with_parent`. -> The bin or pipeline will not take care of this for you. - -MT safe. -## `element` -the `Element` to add - -# Returns - -`true` if the element could be added, `false` if -the bin does not want to accept the element. - -Adds a `None`-terminated list of elements to a bin. This function is -equivalent to calling `GstBinExt::add` for each member of the list. The return -value of each `GstBinExt::add` is ignored. -## `element_1` -the `Element` element to add to the bin - -Recursively looks for elements with an unlinked pad of the given -direction within the specified bin and returns an unlinked pad -if one is found, or `None` otherwise. If a pad is found, the caller -owns a reference to it and should use `GstObjectExt::unref` on the -pad when it is not needed any longer. -## `direction` -whether to look for an unlinked source or sink pad - -# Returns - -unlinked pad of the given -direction, `None`. - -Looks for an element inside the bin that implements the given -interface. If such an element is found, it returns the element. -You can cast this element to the given interface afterwards. If you want -all elements that implement the interface, use -`GstBinExt::iterate_all_by_interface`. This function recurses into child bins. - -MT safe. Caller owns returned reference. -## `iface` -the `glib::Type` of an interface - -# Returns - -A `Element` inside the bin -implementing the interface - -Gets the element with the given name from a bin. This -function recurses into child bins. - -Returns `None` if no element with the given name is found in the bin. - -MT safe. Caller owns returned reference. -## `name` -the element name to search for - -# Returns - -the `Element` with the given -name, or `None` - -Gets the element with the given name from this bin. If the -element is not found, a recursion is performed on the parent bin. - -Returns `None` if: -- no element with the given name is found in the bin - -MT safe. Caller owns returned reference. -## `name` -the element name to search for - -# Returns - -the `Element` with the given -name, or `None` - -Return the suppressed flags of the bin. - -MT safe. - -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. -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. -## `iface` -the `glib::Type` of an interface - -# Returns - -a `Iterator` of `Element` - for all elements in the bin implementing the given interface, - or `None` - -Gets an iterator for the elements in this bin. - -MT safe. Caller owns returned value. - -# Returns - -a `Iterator` of `Element`, -or `None` - -Gets an iterator for the elements in this bin. -This iterator recurses into GstBin children. - -MT safe. Caller owns returned value. - -# Returns - -a `Iterator` of `Element`, -or `None` - -Gets an iterator for all elements in the bin that have the -`ElementFlags::Sink` flag set. - -MT safe. Caller owns returned value. - -# Returns - -a `Iterator` of `Element`, -or `None` - -Gets an iterator for the elements in this bin in topologically -sorted order. This means that the elements are returned from -the most downstream elements (sinks) to the sources. - -This function is used internally to perform the state changes -of the bin elements and for clock selection. - -MT safe. Caller owns returned value. - -# Returns - -a `Iterator` of `Element`, -or `None` - -Gets an iterator for all elements in the bin that have the -`ElementFlags::Source` flag set. - -MT safe. Caller owns returned value. - -# Returns - -a `Iterator` of `Element`, -or `None` - -Query `self` for the current latency using and reconfigures this latency to all the -elements with a LATENCY event. - -This method is typically called on the pipeline when a `MessageType::Latency` -is posted on the bus. - -This function simply emits the 'do-latency' signal so any custom latency -calculations will be performed. - -# Returns - -`true` if the latency could be queried and reconfigured. - -Removes the element from the bin, unparenting it as well. -Unparenting the element means that the element will be dereferenced, -so if the bin holds the only reference to the element, the element -will be freed in the process of removing it from the bin. If you -want the element to still exist after removing, you need to call -`GstObjectExt::ref` before removing it from the bin. - -If the element's pads are linked to other pads, the pads will be unlinked -before the element is removed from the bin. - -MT safe. -## `element` -the `Element` to remove - -# Returns - -`true` if the element could be removed, `false` if -the bin does not want to remove the element. - -Remove a list of elements from a bin. This function is equivalent -to calling `GstBinExt::remove` with each member of the list. -## `element_1` -the first `Element` to remove from the bin - -Suppress the given flags on the bin. `ElementFlags` of a -child element are propagated when it is added to the bin. -When suppressed flags are set, those specified flags will -not be propagated to the bin. - -MT safe. - -Feature: `v1_10` - -## `flags` -the `ElementFlags` to suppress - -Synchronizes the state of every child of `self` with the state -of `self`. See also `ElementExt::sync_state_with_parent`. - -# Returns - -`true` if syncing the state was successful for all children, - otherwise `false`. - -Will be emitted after the element was added to sub_bin. - -Feature: `v1_10` - -## `sub_bin` -the `Bin` the element was added to -## `element` -the `Element` that was added to `sub_bin` - -Will be emitted after the element was removed from sub_bin. - -Feature: `v1_10` - -## `sub_bin` -the `Bin` the element was removed from -## `element` -the `Element` that was removed from `sub_bin` - -Will be emitted when the bin needs to perform latency calculations. This -signal is only emitted for toplevel bins or when async-handling is -enabled. - -Only one signal handler is invoked. If no signals are connected, the -default handler is invoked, which will query and distribute the lowest -possible latency to all sinks. - -Connect to this signal if the default latency calculations are not -sufficient, like when you need different latencies for different sinks in -the same pipeline. - -Will be emitted after the element was added to the bin. -## `element` -the `Element` that was added to the bin - -Will be emitted after the element was removed from the bin. -## `element` -the `Element` that was removed from the bin - -If set to `true`, the bin will handle asynchronous state changes. -This should be used only if the bin subclass is modifying the state -of its children on its own. - -If set to `true`, the bin will handle asynchronous state changes. -This should be used only if the bin subclass is modifying the state -of its children on its own. - -Forward all children messages, even those that would normally be filtered by -the bin. This can be interesting when one wants to be notified of the EOS -state of individual elements, for example. - -The messages are converted to an ELEMENT message with the bin as the -source. The structure of the message is named 'GstBinForwarded' and contains -a field named 'message' of type GST_TYPE_MESSAGE that contains the original -forwarded message. - -Forward all children messages, even those that would normally be filtered by -the bin. This can be interesting when one wants to be notified of the EOS -state of individual elements, for example. - -The messages are converted to an ELEMENT message with the bin as the -source. The structure of the message is named 'GstBinForwarded' and contains -a field named 'message' of type GST_TYPE_MESSAGE that contains the original -forwarded message. - -GstBinFlags are a set of flags specific to bins. Most are set/used -internally. They can be checked using the GST_OBJECT_FLAG_IS_SET () macro, -and (un)set using GST_OBJECT_FLAG_SET () and GST_OBJECT_FLAG_UNSET (). - -don't resync a state change when elements are - added or linked in the bin (Since: 1.0.5) - -Indicates whether the bin can handle elements - that add/remove source pads at any point in time without - first posting a no-more-pads signal (Since: 1.10) - -the last enum in the series of flags for bins. -Derived classes can use this as first value in a list of flags. - -Buffers are the basic unit of data transfer in GStreamer. They contain the -timing and offset along with other arbitrary metadata that is associated -with the `Memory` blocks that the buffer contains. - -Buffers are usually created with `Buffer::new`. After a buffer has been -created one will typically allocate memory for it and add it to the buffer. -The following example creates a buffer that can hold a given video frame -with a given width, height and bits per plane. - -```C - GstBuffer *buffer; - GstMemory *memory; - gint size, width, height, bpp; - ... - size = width * height * bpp; - buffer = gst_buffer_new (); - memory = gst_allocator_alloc (NULL, size, NULL); - gst_buffer_insert_memory (buffer, -1, memory); - ... -``` - -Alternatively, use `Buffer::new_allocate` to create a buffer with -preallocated data of a given size. - -Buffers can contain a list of `Memory` objects. You can retrieve how many -memory objects with `Buffer::n_memory` and you can get a pointer -to memory with `Buffer::peek_memory` - -A buffer will usually have timestamps, and a duration, but neither of these -are guaranteed (they may be set to `GST_CLOCK_TIME_NONE`). Whenever a -meaningful value can be given for these, they should be set. The timestamps -and duration are measured in nanoseconds (they are `ClockTime` values). - -The buffer DTS refers to the timestamp when the buffer should be decoded and -is usually monotonically increasing. The buffer PTS refers to the timestamp when -the buffer content should be presented to the user and is not always -monotonically increasing. - -A buffer can also have one or both of a start and an end offset. These are -media-type specific. For video buffers, the start offset will generally be -the frame number. For audio buffers, it will be the number of samples -produced so far. For compressed data, it could be the byte offset in a -source or destination file. Likewise, the end offset will be the offset of -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 -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 -has the only reference to the buffer. - -To efficiently create a smaller buffer out of an existing one, you can -use `Buffer::copy_region`. This method tries to share the memory objects -between the two buffers. - -If a plug-in wants to modify the buffer data or metadata in-place, it should -first obtain a buffer that is safe to modify by using -`gst_buffer_make_writable`. This function is optimized so that a copy will -only be made when it is necessary. - -Several flags of the buffer can be set and unset with the -GST_BUFFER_FLAG_SET() and GST_BUFFER_FLAG_UNSET() macros. Use -GST_BUFFER_FLAG_IS_SET() to test if a certain `BufferFlags` flag is set. - -Buffers can be efficiently merged into a larger buffer with -`Buffer::append`. Copying of memory will only be done when absolutely -needed. - -Arbitrary extra metadata can be set on a buffer with `Buffer::add_meta`. -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 -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. - -The `ParentBufferMeta` is a meta which can be attached to a `Buffer` -to hold a reference to another buffer that is only released when the child -`Buffer` is released. - -Typically, `ParentBufferMeta` is used when the child buffer is directly -using the `Memory` of the parent buffer, and wants to prevent the parent -buffer from being returned to a buffer pool until the `Memory` is available -for re-use. (Since: 1.6) - -Creates a newly allocated buffer without any data. - -MT safe. - -# Returns - -the new `Buffer`. - -Tries to create a newly allocated buffer with data of the given size and -extra parameters from `allocator`. If the requested amount of memory can't be -allocated, `None` will be returned. The allocated buffer memory is not cleared. - -When `allocator` is `None`, the default memory allocator will be used. - -Note that when `size` == 0, the buffer will not have memory associated with it. - -MT safe. -## `allocator` -the `Allocator` to use, or `None` to use the - default allocator -## `size` -the size in bytes of the new buffer's data. -## `params` -optional parameters - -# Returns - -a new `Buffer`, or `None` if - the memory couldn't be allocated. - -Creates a new buffer that wraps the given `data`. The memory will be freed -with g_free and will be marked writable. - -MT safe. -## `data` -data to wrap -## `size` -allocated size of `data` - -# Returns - -a new `Buffer` - -Creates a new `Buffer` that wraps the given `bytes`. The data inside -`bytes` cannot be `None` and the resulting buffer will be marked as read only. - -MT safe. - -Feature: `v1_16` - -## `bytes` -a `glib::Bytes` to wrap - -# Returns - -a new `Buffer` wrapping `bytes` - -Allocate a new buffer that wraps the given memory. `data` must point to -`maxsize` of memory, the wrapped buffer will have the region from `offset` and -`size` visible. - -When the buffer is destroyed, `notify` will be called with `user_data`. - -The prefix/padding must be filled with 0 if `flags` contains -`MemoryFlags::ZeroPrefixed` and `MemoryFlags::ZeroPadded` respectively. -## `flags` -`MemoryFlags` -## `data` -data to wrap -## `maxsize` -allocated size of `data` -## `offset` -offset in `data` -## `size` -size of valid data -## `user_data` -user_data -## `notify` -called with `user_data` when the memory is freed - -# Returns - -a new `Buffer` - -Add metadata for `info` to `self` using the parameters in `params`. -## `info` -a `MetaInfo` -## `params` -params for `info` - -# Returns - -the metadata for the api in `info` on `self`. - -Add a `ParentBufferMeta` to `self` that holds a reference on -`ref_` until the buffer is freed. -## `ref_` -a `Buffer` to ref - -# Returns - -The `ParentBufferMeta` that was added to the buffer - -Attaches protection metadata to a `Buffer`. -## `info` -a `Structure` holding cryptographic - information relating to the sample contained in `self`. This - function takes ownership of `info`. - -# Returns - -a pointer to the added `ProtectionMeta` if successful; `None` if -unsuccessful. - -Add a `ReferenceTimestampMeta` to `self` that holds a `timestamp` and -optionally `duration` based on a specific timestamp `reference`. See the -documentation of `ReferenceTimestampMeta` for details. - -Feature: `v1_14` - -## `reference` -identifier for the timestamp reference. -## `timestamp` -timestamp -## `duration` -duration, or `GST_CLOCK_TIME_NONE` - -# Returns - -The `ReferenceTimestampMeta` that was added to the buffer - -Append all the memory from `buf2` to `self`. The result buffer will contain a -concatenation of the memory of `self` and `buf2`. -## `buf2` -the second source `Buffer` to append. - -# Returns - -the new `Buffer` that contains the memory - of the two source buffers. - -Append the memory block `mem` to `self`. This function takes -ownership of `mem` and thus doesn't increase its refcount. - -This function is identical to `Buffer::insert_memory` with an index of -1. -See `Buffer::insert_memory` for more details. -## `mem` -a `Memory`. - -Append `size` bytes at `offset` from `buf2` to `self`. The result buffer will -contain a concatenation of the memory of `self` and the requested region of -`buf2`. -## `buf2` -the second source `Buffer` to append. -## `offset` -the offset in `buf2` -## `size` -the size or -1 of `buf2` - -# Returns - -the new `Buffer` that contains the memory - of the two source buffers. - -Create a copy of the given buffer. This will make a newly allocated -copy of the data the source buffer contains. - -# Returns - -a new copy of `self`. - -Copies the information from `src` into `self`. - -If `self` already contains memory and `flags` contains GST_BUFFER_COPY_MEMORY, -the memory from `src` will be appended to `self`. - -`flags` indicate which fields will be copied. -## `src` -a source `Buffer` -## `flags` -flags indicating what metadata fields should be copied. -## `offset` -offset to copy from -## `size` -total size to copy. If -1, all data is copied. - -# Returns - -`true` if the copying succeeded, `false` otherwise. - -Creates a sub-buffer from `self` at `offset` and `size`. -This sub-buffer uses the actual memory space of the parent buffer. -This function will copy the offset and timestamp fields when the -offset is 0. If not, they will be set to `GST_CLOCK_TIME_NONE` and -`GST_BUFFER_OFFSET_NONE`. -If `offset` equals 0 and `size` equals the total size of `buffer`, the -duration and offset end fields are also copied. If not they will be set -to `GST_CLOCK_TIME_NONE` and `GST_BUFFER_OFFSET_NONE`. - -MT safe. -## `flags` -the `BufferCopyFlags` -## `offset` -the offset into parent `Buffer` at which the new sub-buffer - begins. -## `size` -the size of the new `Buffer` sub-buffer, in bytes. If -1, all - data is copied. - -# Returns - -the new `Buffer` or `None` if the arguments were - invalid. - -Copy `size` bytes starting from `offset` in `self` to `dest`. -## `offset` -the offset to extract -## `dest` - - the destination address -## `size` -the size to extract - -# Returns - -The amount of bytes extracted. This value can be lower than `size` - when `self` did not contain enough data. - -Extracts a copy of at most `size` bytes the data at `offset` into -newly-allocated memory. `dest` must be freed using `g_free` when done. -## `offset` -the offset to extract -## `size` -the size to extract -## `dest` -A pointer where - the destination array will be written. Might be `None` if the size is 0. -## `dest_size` -A location where the size of `dest` can be written - -Copy `size` bytes from `src` to `self` at `offset`. -## `offset` -the offset to fill -## `src` -the source address -## `size` -the size to fill - -# Returns - -The amount of bytes copied. This value can be lower than `size` - when `self` did not contain enough data. - -Find the memory blocks that span `size` bytes starting from `offset` -in `self`. - -When this function returns `true`, `idx` will contain the index of the first -memory block where the byte for `offset` can be found and `length` contains the -number of memory blocks containing the `size` remaining bytes. `skip` contains -the number of bytes to skip in the memory block at `idx` to get to the byte -for `offset`. - -`size` can be -1 to get all the memory blocks after `idx`. -## `offset` -an offset -## `size` -a size -## `idx` -pointer to index -## `length` -pointer to length -## `skip` -pointer to skip - -# Returns - -`true` when `size` bytes starting from `offset` could be found in -`self` and `idx`, `length` and `skip` will be filled. - -Call `func` with `user_data` for each meta in `self`. - -`func` can modify the passed meta pointer or its contents. The return value -of `func` define if this function returns or if the remaining metadata items -in the buffer should be skipped. -## `func` -a `GstBufferForeachMetaFunc` to call -## `user_data` -user data passed to `func` - -# Returns - -`false` when `func` returned `false` for one of the metadata. - -Get all the memory block in `self`. The memory blocks will be merged -into one large `Memory`. - -# Returns - -a `Memory` that contains the merged memory. -Use gst_memory_unref () after usage. - -Get the `BufferFlags` flags set on this buffer. - -Feature: `v1_10` - - -# Returns - -the flags set on this buffer. - -Get the memory block at index `idx` in `self`. -## `idx` -an index - -# Returns - -a `Memory` that contains the data of the -memory block at `idx`. Use gst_memory_unref () after usage. - -Get `length` memory blocks in `self` starting at `idx`. The memory blocks will -be merged into one large `Memory`. - -If `length` is -1, all memory starting from `idx` is merged. -## `idx` -an index -## `length` -a length - -# Returns - -a `Memory` that contains the merged data of `length` - blocks starting at `idx`. Use gst_memory_unref () after usage. - -Get the metadata for `api` on buffer. When there is no such metadata, `None` is -returned. If multiple metadata with the given `api` are attached to this -buffer only the first one is returned. To handle multiple metadata with a -given API use `Buffer::iterate_meta` or `Buffer::foreach_meta` instead -and check the meta->info.api member for the API type. -## `api` -the `glib::Type` of an API - -# Returns - -the metadata for `api` on -`self`. - - -Feature: `v1_14` - -## `api_type` -the `glib::Type` of an API - -# Returns - -number of metas of type `api_type` on `self`. - -Find the first `ReferenceTimestampMeta` on `self` that conforms to -`reference`. Conformance is tested by checking if the meta's reference is a -subset of `reference`. - -Buffers can contain multiple `ReferenceTimestampMeta` metadata items. - -Feature: `v1_14` - -## `reference` -a reference `Caps` - -# Returns - -the `ReferenceTimestampMeta` or `None` when there -is no such metadata on `self`. - -Get the total size of the memory blocks in `self`. - -# Returns - -total size of the memory blocks in `self`. - -Get the total size of the memory blocks in `b`. - -When not `None`, `offset` will contain the offset of the data in the -first memory block in `self` and `maxsize` will contain the sum of -the size and `offset` and the amount of extra padding on the last -memory block. `offset` and `maxsize` can be used to resize the -buffer memory blocks with `Buffer::resize`. -## `offset` -a pointer to the offset -## `maxsize` -a pointer to the maxsize - -# Returns - -total size of the memory blocks in `self`. - -Get the total size of `length` memory blocks stating from `idx` in `self`. - -When not `None`, `offset` will contain the offset of the data in the -memory block in `self` at `idx` and `maxsize` will contain the sum of the size -and `offset` and the amount of extra padding on the memory block at `idx` + -`length` -1. -`offset` and `maxsize` can be used to resize the buffer memory blocks with -`Buffer::resize_range`. -## `idx` -an index -## `length` -a length -## `offset` -a pointer to the offset -## `maxsize` -a pointer to the maxsize - -# Returns - -total size of `length` memory blocks starting at `idx` in `self`. - -Gives the status of a specific flag on a buffer. - -Feature: `v1_10` - -## `flags` -the `BufferFlags` flag to check. - -# Returns - -`true` if all flags in `flags` are found on `self`. - -Insert the memory block `mem` to `self` at `idx`. This function takes ownership -of `mem` and thus doesn't increase its refcount. - -Only `Buffer::get_max_memory` can be added to a buffer. If more memory is -added, existing memory blocks will automatically be merged to make room for -the new memory. -## `idx` -the index to add the memory at, or -1 to append it to the end -## `mem` -a `Memory`. - -Check if all memory blocks in `self` are writable. - -Note that this function does not check if `self` is writable, use -`gst_buffer_is_writable` to check that if needed. - -# Returns - -`true` if all memory blocks in `self` are writable - -Check if `length` memory blocks in `self` starting from `idx` are writable. - -`length` can be -1 to check all the memory blocks after `idx`. - -Note that this function does not check if `self` is writable, use -`gst_buffer_is_writable` to check that if needed. -## `idx` -an index -## `length` -a length should not be 0 - -# Returns - -`true` if the memory range is writable - -Retrieve the next `Meta` after `current`. If `state` points -to `None`, the first metadata is returned. - -`state` will be updated with an opaque state pointer -## `state` -an opaque state pointer - -# Returns - -The next `Meta` or `None` -when there are no more items. - -Retrieve the next `Meta` of type `meta_api_type` after the current one -according to `state`. If `state` points to `None`, the first metadata of -type `meta_api_type` is returned. - -`state` will be updated with an opaque state pointer - -Feature: `v1_12` - -## `state` -an opaque state pointer -## `meta_api_type` -only return `Meta` of this type - -# Returns - -The next `Meta` of type -`meta_api_type` or `None` when there are no more items. - -This function fills `info` with the `MapInfo` of all merged memory -blocks in `self`. - -`flags` describe the desired access of the memory. When `flags` is -`MapFlags::Write`, `self` should be writable (as returned from -`gst_buffer_is_writable`). - -When `self` is writable but the memory isn't, a writable copy will -automatically be created and returned. The readonly copy of the -buffer memory will then also be replaced with this writable copy. - -The memory in `info` should be unmapped with `Buffer::unmap` after -usage. -## `info` -info about the mapping -## `flags` -flags for the mapping - -# Returns - -`true` if the map succeeded and `info` contains valid data. - -This function fills `info` with the `MapInfo` of `length` merged memory blocks -starting at `idx` in `self`. When `length` is -1, all memory blocks starting -from `idx` are merged and mapped. - -`flags` describe the desired access of the memory. When `flags` is -`MapFlags::Write`, `self` should be writable (as returned from -`gst_buffer_is_writable`). - -When `self` is writable but the memory isn't, a writable copy will -automatically be created and returned. The readonly copy of the buffer memory -will then also be replaced with this writable copy. - -The memory in `info` should be unmapped with `Buffer::unmap` after usage. -## `idx` -an index -## `length` -a length -## `info` -info about the mapping -## `flags` -flags for the mapping - -# Returns - -`true` if the map succeeded and `info` contains valid -data. - -Compare `size` bytes starting from `offset` in `self` with the memory in `mem`. -## `offset` -the offset in `self` -## `mem` -the memory to compare -## `size` -the size to compare - -# Returns - -0 if the memory is equal. - -Fill `buf` with `size` bytes with `val` starting from `offset`. -## `offset` -the offset in `self` -## `val` -the value to set -## `size` -the size to set - -# Returns - -The amount of bytes filled. This value can be lower than `size` - when `self` did not contain enough data. - -Get the amount of memory blocks that this buffer has. This amount is never -larger than what `Buffer::get_max_memory` returns. - -# Returns - -the number of memory blocks this buffer is made of. - -Get the memory block at `idx` in `self`. The memory block stays valid until -the memory block in `self` is removed, replaced or merged, typically with -any call that modifies the memory in `self`. -## `idx` -an index - -# Returns - -the `Memory` at `idx`. - -Prepend the memory block `mem` to `self`. This function takes -ownership of `mem` and thus doesn't increase its refcount. - -This function is identical to `Buffer::insert_memory` with an index of 0. -See `Buffer::insert_memory` for more details. -## `mem` -a `Memory`. - -Remove all the memory blocks in `self`. - -Remove the memory block in `b` at index `i`. -## `idx` -an index - -Remove `length` memory blocks in `self` starting from `idx`. - -`length` can be -1, in which case all memory starting from `idx` is removed. -## `idx` -an index -## `length` -a length - -Remove the metadata for `meta` on `self`. -## `meta` -a `Meta` - -# Returns - -`true` if the metadata existed and was removed, `false` if no such -metadata was on `self`. - -Replaces all memory in `self` with `mem`. -## `mem` -a `Memory` - -Replaces the memory block at index `idx` in `self` with `mem`. -## `idx` -an index -## `mem` -a `Memory` - -Replaces `length` memory blocks in `self` starting at `idx` with `mem`. - -If `length` is -1, all memory starting from `idx` will be removed and -replaced with `mem`. - -`self` should be writable. -## `idx` -an index -## `length` -a length should not be 0 -## `mem` -a `Memory` - -Set the offset and total size of the memory blocks in `self`. -## `offset` -the offset adjustment -## `size` -the new size or -1 to just adjust the offset - -Set the total size of the `length` memory blocks starting at `idx` in -`self` -## `idx` -an index -## `length` -a length -## `offset` -the offset adjustment -## `size` -the new size or -1 to just adjust the offset - -# Returns - -`true` if resizing succeeded, `false` otherwise. - -Sets one or more buffer flags on a buffer. - -Feature: `v1_10` - -## `flags` -the `BufferFlags` to set. - -# Returns - -`true` if `flags` were successfully set on buffer. - -Set the total size of the memory blocks in `self`. -## `size` -the new size - -Release the memory previously mapped with `Buffer::map`. -## `info` -a `MapInfo` - -Clears one or more buffer flags. - -Feature: `v1_10` - -## `flags` -the `BufferFlags` to clear - -# Returns - -true if `flags` is successfully cleared from buffer. - -Get the maximum amount of memory blocks that a buffer can hold. This is a -compile time constant that can be queried with the function. - -When more memory blocks are added, existing memory blocks will be merged -together to make room for the new block. - -# Returns - -the maximum amount of memory blocks that a buffer can hold. - -A set of flags that can be provided to the `Buffer::copy_into` -function to specify which items should be copied. - -copy nothing - -flag indicating that buffer flags should be copied - -flag indicating that buffer pts, dts, - duration, offset and offset_end should be copied - -flag indicating that buffer meta should be - copied - -flag indicating that buffer memory should be reffed - and appended to already existing memory. Unless the memory is marked as - NO_SHARE, no actual copy of the memory is made but it is simply reffed. - Add [`Deep`](Self::Deep) to force a real copy. - -flag indicating that buffer memory should be - merged - -flag indicating that memory should always be - copied instead of reffed (Since: 1.2) - -A set of buffer flags used to describe properties of a `Buffer`. - -the buffer is live data and should be discarded in - the PAUSED state. - -the buffer contains data that should be dropped - because it will be clipped against the segment - boundaries or because it does not contain data - that should be shown to the user. - -the buffer marks a data discontinuity in the stream. - This typically occurs after a seek or a dropped buffer - from a live or network source. - -the buffer timestamps might have a discontinuity - and this buffer is a good point to resynchronize. - -the buffer data is corrupted. - -the buffer contains a media specific marker. for - video this is the end of a frame boundary, for audio - this is the start of a talkspurt. - -the buffer contains header information that is - needed to decode the following data. - -the buffer has been created to fill a gap in the - stream and contains media neutral data (elements can - switch to optimized code path that ignores the buffer - content). - -the buffer can be dropped without breaking the - stream, for example to reduce bandwidth. - -this unit cannot be decoded independently. - -this flag is set when memory of the buffer - is added/removed - -Elements which write to disk or permanent - storage should ensure the data is synced after - writing the contents of this buffer. (Since: 1.6) - -This buffer is important and should not be dropped. - This can be used to mark important buffers, e.g. to flag - RTP packets carrying keyframes or codec setup data for RTP - Forward Error Correction purposes, or to prevent still video - frames from being dropped by elements due to QoS. (Since: 1.14) - -additional media specific flags can be added starting from - this flag. - -Buffer lists are an object containing a list of buffers. - -Buffer lists are created with `BufferList::new` and filled with data -using a `BufferList::insert`. - -Buffer lists can be pushed on a srcpad with `Pad::push_list`. This is -interesting when multiple buffers need to be pushed in one go because it -can reduce the amount of overhead for pushing each buffer individually. - -Creates a new, empty `BufferList`. The caller is responsible for unreffing -the returned `BufferList`. - -Free-function: gst_buffer_list_unref - -# Returns - -the new `BufferList`. `gst_buffer_list_unref` - after usage. - -Creates a new, empty `BufferList`. The caller is responsible for unreffing -the returned `BufferList`. The list will have `size` space preallocated so -that memory reallocations can be avoided. - -Free-function: gst_buffer_list_unref -## `size` -an initial reserved size - -# Returns - -the new `BufferList`. `gst_buffer_list_unref` - after usage. - -Calculates the size of the data contained in buffer list by adding the -size of all buffers. - -Feature: `v1_14` - - -# Returns - -the size of the data contained in buffer list in bytes. - -Create a copy of the given buffer list. This will make a newly allocated -copy of the buffer that the source buffer list contains. - -# Returns - -a new copy of `self`. - -Call `func` with `data` for each buffer in `self`. - -`func` can modify the passed buffer pointer or its contents. The return value -of `func` define if this function returns or if the remaining buffers in -the list should be skipped. -## `func` -a `GstBufferListFunc` to call -## `user_data` -user data passed to `func` - -# Returns - -`true` when `func` returned `true` for each buffer in `self` or when -`self` is empty. - -Get the buffer at `idx`. - -You must make sure that `idx` does not exceed the number of -buffers available. -## `idx` -the index - -# Returns - -the buffer at `idx` in `group` - or `None` when there is no buffer. The buffer remains valid as - long as `self` is valid and buffer is not removed from the list. - -Gets the buffer at `idx`, ensuring it is a writable buffer. - -You must make sure that `idx` does not exceed the number of -buffers available. - -Feature: `v1_14` - -## `idx` -the index - -# Returns - -the buffer at `idx` in `group`. - The returned buffer remains valid as long as `self` is valid and - the buffer is not removed from the list. - -Insert `buffer` at `idx` in `self`. Other buffers are moved to make room for -this new buffer. - -A -1 value for `idx` will append the buffer at the end. -## `idx` -the index -## `buffer` -a `Buffer` - -Returns the number of buffers in `self`. - -# Returns - -the number of buffers in the buffer list - -Remove `length` buffers starting from `idx` in `self`. The following buffers -are moved to close the gap. -## `idx` -the index -## `length` -the amount to remove - -A `BufferPool` is an object that can be used to pre-allocate and recycle -buffers of the same size and with the same properties. - -A `BufferPool` is created with `BufferPool::new`. - -Once a pool is created, it needs to be configured. A call to -`BufferPool::get_config` returns the current configuration structure from -the pool. With `BufferPool::config_set_params` and -`BufferPool::config_set_allocator` the bufferpool parameters and -allocator can be configured. Other properties can be configured in the pool -depending on the pool implementation. - -A bufferpool can have extra options that can be enabled with -`BufferPool::config_add_option`. The available options can be retrieved -with `BufferPoolExt::get_options`. Some options allow for additional -configuration properties to be set. - -After the configuration structure has been configured, -`BufferPool::set_config` updates the configuration in the pool. This can -fail when the configuration structure is not accepted. - -After the a pool has been configured, it can be activated with -`BufferPoolExt::set_active`. This will preallocate the configured resources -in the pool. - -When the pool is active, `BufferPool::acquire_buffer` can be used to -retrieve a buffer from the pool. - -Buffers allocated from a bufferpool will automatically be returned to the -pool with `BufferPool::release_buffer` when their refcount drops to 0. - -The bufferpool can be deactivated again with `BufferPoolExt::set_active`. -All further `BufferPool::acquire_buffer` calls will return an error. When -all buffers are returned to the pool they will be freed. - -Use `GstObjectExt::unref` to release the reference to a bufferpool. If the -refcount of the pool reaches 0, the pool will be freed. - -# Implements - -[`BufferPoolExt`](trait@crate::BufferPoolExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`BufferPoolExtManual`](trait@crate::BufferPoolExtManual) - -Trait containing all `BufferPool` methods. - -# Implementors - -[`BufferPool`](struct@crate::BufferPool) - -Creates a new `BufferPool` instance. - -# Returns - -a new `BufferPool` instance - -Enabled the option in `config`. This will instruct the `bufferpool` to enable -the specified option on the buffers that it allocates. - -The supported options by `pool` can be retrieved with `BufferPoolExt::get_options`. -## `config` -a `BufferPool` configuration -## `option` -an option to add - -Get the `allocator` and `params` from `config`. -## `config` -a `BufferPool` configuration -## `allocator` -a `Allocator`, or `None` -## `params` -`AllocationParams`, or `None` - -# Returns - -`true`, if the values are set. - -Parse an available `config` and get the option at `index` of the options API -array. -## `config` -a `BufferPool` configuration -## `index` -position in the option array to read - -# Returns - -a `gchar` of the option at `index`. - -Get the configuration values from `config`. -## `config` -a `BufferPool` configuration -## `caps` -the caps of buffers -## `size` -the size of each buffer, not including prefix and padding -## `min_buffers` -the minimum amount of buffers to allocate. -## `max_buffers` -the maximum amount of buffers to allocate or 0 for unlimited. - -# Returns - -`true` if all parameters could be fetched. - -Check if `config` contains `option`. -## `config` -a `BufferPool` configuration -## `option` -an option - -# Returns - -`true` if the options array contains `option`. - -Retrieve the number of values currently stored in the options array of the -`config` structure. -## `config` -a `BufferPool` configuration - -# Returns - -the options array size as a `guint`. - -Set the `allocator` and `params` on `config`. - -One of `allocator` and `params` can be `None`, but not both. When `allocator` -is `None`, the default allocator of the pool will use the values in `param` -to perform its allocation. When `param` is `None`, the pool will use the -provided `allocator` with its default `AllocationParams`. - -A call to `BufferPool::set_config` can update the allocator and params -with the values that it is able to do. Some pools are, for example, not able -to operate with different allocators or cannot allocate with the values -specified in `params`. Use `BufferPool::get_config` to get the currently -used values. -## `config` -a `BufferPool` configuration -## `allocator` -a `Allocator` -## `params` -`AllocationParams` - -Configure `config` with the given parameters. -## `config` -a `BufferPool` configuration -## `caps` -caps for the buffers -## `size` -the size of each buffer, not including prefix and padding -## `min_buffers` -the minimum amount of buffers to allocate. -## `max_buffers` -the maximum amount of buffers to allocate or 0 for unlimited. - -Validate that changes made to `config` are still valid in the context of the -expected parameters. This function is a helper that can be used to validate -changes made by a pool to a config when `BufferPool::set_config` -returns `false`. This expects that `caps` haven't changed and that -`min_buffers` aren't lower then what we initially expected. -This does not check if options or allocator parameters are still valid, -won't check if size have changed, since changing the size is valid to adapt -padding. -## `config` -a `BufferPool` configuration -## `caps` -the excepted caps of buffers -## `size` -the expected size of each buffer, not including prefix and padding -## `min_buffers` -the expected minimum amount of buffers to allocate. -## `max_buffers` -the expect maximum amount of buffers to allocate or 0 for unlimited. - -# Returns - -`true`, if the parameters are valid in this context. - -Acquire a buffer from `self`. `buffer` should point to a memory location that -can hold a pointer to the new buffer. - -`params` can be `None` or contain optional parameters to influence the -allocation. -## `buffer` -a location for a `Buffer` -## `params` -parameters. - -# Returns - -a `FlowReturn` such as `FlowReturn::Flushing` when the pool is -inactive. - -Get a copy of the current configuration of the pool. This configuration -can either be modified and used for the `BufferPool::set_config` call -or it must be freed after usage. - -# Returns - -a copy of the current configuration of `self`. use -`Structure::free` after usage or `BufferPool::set_config`. - -Get a `None` terminated array of string with supported bufferpool options for -`self`. An option would typically be enabled with -`BufferPool::config_add_option`. - -# Returns - -a `None` terminated array - of strings. - -Check if the bufferpool supports `option`. -## `option` -an option - -# Returns - -`true` if the buffer pool contains `option`. - -Check if `self` is active. A pool can be activated with the -`BufferPoolExt::set_active` call. - -# Returns - -`true` when the pool is active. - -Release `buffer` to `self`. `buffer` should have previously been allocated from -`self` with `BufferPool::acquire_buffer`. - -This function is usually called automatically when the last ref on `buffer` -disappears. -## `buffer` -a `Buffer` - -Control the active state of `self`. When the pool is inactive, new calls to -`BufferPool::acquire_buffer` will return with `FlowReturn::Flushing`. - -Activating the bufferpool will preallocate all resources in the pool based on -the configuration of the pool. - -Deactivating will free the resources again when there are no outstanding -buffers. When there are outstanding buffers, they will be freed as soon as -they are all returned to the pool. -## `active` -the new active state - -# Returns - -`false` when the pool was not configured or when preallocation of the -buffers failed. - -Set the configuration of the pool. If the pool is already configured, and -the configuration haven't change, this function will return `true`. If the -pool is active, this method will return `false` and active configuration -will remain. Buffers allocated form this pool must be returned or else this -function will do nothing and return `false`. - -`config` is a `Structure` that contains the configuration parameters for -the pool. A default and mandatory set of parameters can be configured with -`BufferPool::config_set_params`, `BufferPool::config_set_allocator` -and `BufferPool::config_add_option`. - -If the parameters in `config` can not be set exactly, this function returns -`false` and will try to update as much state as possible. The new state can -then be retrieved and refined with `BufferPool::get_config`. - -This function takes ownership of `config`. -## `config` -a `Structure` - -# Returns - -`true` when the configuration could be set. - -Enable or disable the flushing state of a `self` without freeing or -allocating buffers. -## `flushing` -whether to start or stop flushing - -Additional flags to control the allocation of a buffer - -no flags - -buffer is keyframe - -when the bufferpool is empty, acquire_buffer -will by default block until a buffer is released into the pool again. Setting -this flag makes acquire_buffer return `FlowReturn::Eos` instead of blocking. - -buffer is discont - -last flag, subclasses can use private flags - starting from this value. - -The different types of buffering methods. - -a small amount of data is buffered - -the stream is being downloaded - -the stream is being downloaded in a ringbuffer - -the stream is a live stream - -The `Bus` is an object responsible for delivering `Message` packets in -a first-in first-out way from the streaming threads (see `Task`) to the -application. - -Since the application typically only wants to deal with delivery of these -messages from one thread, the GstBus will marshall the messages between -different threads. This is important since the actual streaming of media -is done in another thread than the application. - -The GstBus provides support for `glib::Source` based notifications. This makes it -possible to handle the delivery in the glib mainloop. - -The `glib::Source` callback function `Bus::async_signal_func` can be used to -convert all bus messages into signal emissions. - -A message is posted on the bus with the `Bus::post` method. With the -`Bus::peek` and `Bus::pop` methods one can look at or retrieve a -previously posted message. - -The bus can be polled with the `Bus::poll` method. This methods blocks -up to the specified timeout value until one of the specified messages types -is posted on the bus. The application can then `Bus::pop` the messages -from the bus to handle them. -Alternatively the application can register an asynchronous bus function -using `Bus::add_watch_full` or `Bus::add_watch`. This function will -install a `glib::Source` in the default glib main loop and will deliver messages -a short while after they have been posted. Note that the main loop should -be running for the asynchronous callbacks. - -It is also possible to get messages from the bus without any thread -marshalling with the `Bus::set_sync_handler` method. This makes it -possible to react to a message in the same thread that posted the -message on the bus. This should only be used if the application is able -to deal with messages from different threads. - -Every `Pipeline` has one bus. - -Note that a `Pipeline` will set its bus into flushing state when changing -from READY to NULL state. - -# Implements - -[`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`] - -Creates a new `Bus` instance. - -# Returns - -a new `Bus` instance - -Adds a bus signal watch to the default main context with the default priority -(`G_PRIORITY_DEFAULT`). It is also possible to use a non-default -main context set up using `glib::MainContext::push_thread_default` (before -one had to create a bus watch source and attach it to the desired main -context 'manually'). - -After calling this statement, the bus will emit the "message" signal for each -message posted on the bus. - -This function may be called multiple times. To clean up, the caller is -responsible for calling `Bus::remove_signal_watch` as many times as this -function is called. - -MT safe. - -Adds a bus signal watch to the default main context with the given `priority` -(e.g. `G_PRIORITY_DEFAULT`). It is also possible to use a non-default main -context set up using `glib::MainContext::push_thread_default` -(before one had to create a bus watch source and attach it to the desired -main context 'manually'). - -After calling this statement, the bus will emit the "message" signal for each -message posted on the bus when the main loop is running. - -This function may be called multiple times. To clean up, the caller is -responsible for calling `Bus::remove_signal_watch` as many times as this -function is called. - -There can only be a single bus watch per bus, you must remove any signal -watch before you can set another type of watch. - -MT safe. -## `priority` -The priority of the watch. - -Adds a bus watch to the default main context with the default priority -(`G_PRIORITY_DEFAULT`). It is also possible to use a non-default main -context set up using `glib::MainContext::push_thread_default` (before -one had to create a bus watch source and attach it to the desired main -context 'manually'). - -This function is used to receive asynchronous messages in the main loop. -There can only be a single bus watch per bus, you must remove it before you -can set a new one. - -The bus watch will only work if a GLib main loop is being run. - -The watch can be removed using `Bus::remove_watch` or by returning `false` -from `func`. If the watch was added to the default main context it is also -possible to remove the watch using `glib::Source::remove`. - -The bus watch will take its own reference to the `self`, so it is safe to unref -`self` using `GstObjectExt::unref` after setting the bus watch. - -MT safe. -## `func` -A function to call when a message is received. -## `user_data` -user data passed to `func`. - -# Returns - -The event source id or 0 if `self` already got an event source. - -Adds a bus watch to the default main context with the given `priority` (e.g. -`G_PRIORITY_DEFAULT`). It is also possible to use a non-default main -context set up using `glib::MainContext::push_thread_default` (before -one had to create a bus watch source and attach it to the desired main -context 'manually'). - -This function is used to receive asynchronous messages in the main loop. -There can only be a single bus watch per bus, you must remove it before you -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`. - -The watch can be removed using `Bus::remove_watch` or by returning `false` -from `func`. If the watch was added to the default main context it is also -possible to remove the watch using `glib::Source::remove`. - -The bus watch will take its own reference to the `self`, so it is safe to unref -`self` using `GstObjectExt::unref` after setting the bus watch. - -MT safe. -## `priority` -The priority of the watch. -## `func` -A function to call when a message is received. -## `user_data` -user data passed to `func`. -## `notify` -the function to call when the source is removed. - -# Returns - -The event source id or 0 if `self` already got an event source. - -A helper `GstBusFunc` that can be used to convert all asynchronous messages -into signals. -## `message` -the `Message` received -## `data` -user data - -# Returns - -`true` - -Create watch for this bus. The GSource will be dispatched whenever -a message is on the bus. After the GSource is dispatched, the -message is popped off the bus and unreffed. - -# Returns - -a `glib::Source` that can be added to a mainloop. - -Instructs GStreamer to stop emitting the "sync-message" signal for this bus. -See `Bus::enable_sync_message_emission` for more information. - -In the event that multiple pieces of code have called -`Bus::enable_sync_message_emission`, the sync-message emissions will only -be stopped after all calls to `Bus::enable_sync_message_emission` were -"cancelled" by calling this function. In this way the semantics are exactly -the same as `GstObjectExt::ref` that which calls enable should also call -disable. - -MT safe. - -Instructs GStreamer to emit the "sync-message" signal after running the bus's -sync handler. This function is here so that code can ensure that they can -synchronously receive messages without having to affect what the bin's sync -handler is. - -This function may be called multiple times. To clean up, the caller is -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 -signals when messages arrive; `Bus::add_signal_watch` adds an idle callback -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. - -MT safe. - -Gets the file descriptor from the bus which can be used to get notified about -messages being available with functions like `g_poll`, and allows integration -into other event loops based on file descriptors. -Whenever a message is available, the POLLIN / `glib::IOCondition::In` event is set. - -Warning: NEVER read or write anything to the returned fd but only use it -for getting notifications via `g_poll` or similar and then use the normal -GstBus API, e.g. `Bus::pop`. - -Feature: `v1_14` - -## `fd` -A GPollFD to fill - -Check if there are pending messages on the bus that -should be handled. - -# Returns - -`true` if there are messages on the bus to be handled, `false` -otherwise. - -MT safe. - -Peek the message on the top of the bus' queue. The message will remain -on the bus' message queue. A reference is returned, and needs to be unreffed -by the caller. - -# Returns - -the `Message` that is on the - bus, or `None` if the bus is empty. - -MT safe. - -Poll the bus for messages. Will block while waiting for messages to come. -You can specify a maximum time to poll with the `timeout` parameter. If -`timeout` is negative, this function will block indefinitely. - -All messages not in `events` will be popped off the bus and will be ignored. -It is not possible to use message enums beyond `MessageType::Extended` in the -`events` mask - -Because poll is implemented using the "message" signal enabled by -`Bus::add_signal_watch`, calling `Bus::poll` will cause the "message" -signal to be emitted for every message that poll sees. Thus a "message" -signal handler will see the same messages that this function sees -- neither -will steal messages from the other. - -This function will run a main loop from the default main context when -polling. - -You should never use this function, since it is pure evil. This is -especially true for GUI applications based on Gtk+ or Qt, but also for any -other non-trivial application that uses the GLib main loop. As this function -runs a GLib main loop, any callback attached to the default GLib main -context may be invoked. This could be timeouts, GUI events, I/O events etc.; -even if `Bus::poll` is called with a 0 timeout. Any of these callbacks -may do things you do not expect, e.g. destroy the main application window or -some other resource; change other application state; display a dialog and -run another main loop until the user clicks it away. In short, using this -function may add a lot of complexity to your code through unexpected -re-entrancy and unexpected changes to your application's state. - -For 0 timeouts use `Bus::pop_filtered` instead of this function; for -other short timeouts use `Bus::timed_pop_filtered`; everything else is -better handled by setting up an asynchronous bus watch and doing things -from there. -## `events` -a mask of `MessageType`, representing the set of message types to -poll for (note special handling of extended message types below) -## `timeout` -the poll timeout, as a `ClockTime`, or `GST_CLOCK_TIME_NONE` to poll -indefinitely. - -# Returns - -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 - usage. - -Get a message from the bus. - -# Returns - -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 - usage. - -MT safe. - -Get a message matching `type_` from the bus. Will discard all messages on -the bus that do not match `type_` and that have been posted before the first -message that does match `type_`. If there is no message matching `type_` on -the bus, all messages will be discarded. It is not possible to use message -enums beyond `MessageType::Extended` in the `events` mask. -## `types` -message types to take into account - -# Returns - -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. - -MT safe. - -Post a message on the given bus. Ownership of the message -is taken by the bus. -## `message` -the `Message` to post - -# Returns - -`true` if the message could be posted, `false` if the bus is flushing. - -MT safe. - -Removes a signal watch previously added with `Bus::add_signal_watch`. - -MT safe. - -Removes an installed bus watch from `self`. - -# Returns - -`true` on success or `false` if `self` has no event source. - -If `flushing`, flush out and unref any messages queued in the bus. Releases -references to the message origin objects. Will flush future messages until -`Bus::set_flushing` sets `flushing` to `false`. - -MT safe. -## `flushing` -whether or not to flush the bus - -Sets the synchronous handler on the bus. The function will be called -every time a new message is posted on the bus. Note that the function -will be called in the same thread context as the posting object. This -function is usually only called by the creator of the bus. Applications -should handle messages asynchronously using the gst_bus watch and poll -functions. - -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` -User data that will be sent to the handler function. -## `notify` -called when `user_data` becomes unused - -A helper GstBusSyncHandler that can be used to convert all synchronous -messages into signals. -## `message` -the `Message` received -## `data` -user data - -# Returns - -GST_BUS_PASS - -Get a message from the bus, waiting up to the specified timeout. - -If `timeout` is 0, this function behaves like `Bus::pop`. If `timeout` is -`GST_CLOCK_TIME_NONE`, this function will block forever until a message was -posted on the bus. -## `timeout` -a timeout - -# Returns - -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. - -MT safe. - -Get a message from the bus whose type matches the message type mask `types`, -waiting up to the specified timeout (and discarding any messages that do not -match the mask provided). - -If `timeout` is 0, this function behaves like `Bus::pop_filtered`. If -`timeout` is `GST_CLOCK_TIME_NONE`, this function will block forever until a -matching message was posted on the bus. -## `timeout` -a timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever -## `types` -message types to take into account, GST_MESSAGE_ANY for any type - -# Returns - -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 - usage. - -MT safe. - -A message has been posted on the bus. This signal is emitted from a -GSource added to the mainloop. this signal will only be emitted when -there is a mainloop running. -## `message` -the message that has been posted asynchronously - -A message has been posted on the bus. This signal is emitted from the -thread that posted the message so one has to be careful with locking. - -This signal will not be emitted by default, you have to call -`Bus::enable_sync_message_emission` before. -## `message` -the message that has been posted synchronously - -The result values for a GstBusSyncHandler. - -drop the message - -pass the message to the async queue - -pass message to async queue, continue if message is handled - -Caps (capabilities) are lightweight refcounted objects describing media types. -They are composed of an array of `Structure`. - -Caps are exposed on `PadTemplate` to describe all possible types a -given pad can handle. They are also stored in the `Registry` along with -a description of the `Element`. - -Caps are exposed on the element pads using the `PadExt::query_caps` pad -function. This function describes the possible types that the pad can -handle or produce at runtime. - -A `Caps` can be constructed with the following code fragment: - -```C - GstCaps *caps = gst_caps_new_simple ("video/x-raw", - "format", G_TYPE_STRING, "I420", - "framerate", GST_TYPE_FRACTION, 25, 1, - "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1, - "width", G_TYPE_INT, 320, - "height", G_TYPE_INT, 240, - NULL); -``` - -A `Caps` is fixed when it has no properties with ranges or lists. Use -`Caps::is_fixed` to test for fixed caps. Fixed caps can be used in a -caps event to notify downstream elements of the current media type. - -Various methods exist to work with the media types such as subtracting -or intersecting. - -Be aware that the current `Caps` / `Structure` serialization into string -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 new `Caps` that indicates that it is compatible with -any media format. - -# Returns - -the new `Caps` - -Creates a new `Caps` that is empty. That is, the returned -`Caps` contains no media formats. -The `Caps` is guaranteed to be writable. -Caller is responsible for unreffing the returned caps. - -# Returns - -the new `Caps` - -Creates a new `Caps` that contains one `Structure` with name -`media_type`. -Caller is responsible for unreffing the returned caps. -## `media_type` -the media type of the structure - -# Returns - -the new `Caps` - -Creates a new `Caps` and adds all the structures listed as -arguments. The list must be `None`-terminated. The structures -are not copied; the returned `Caps` owns the structures. -## `struct1` -the first structure to add - -# Returns - -the new `Caps` - -Creates a new `Caps` and adds all the structures listed as -arguments. The list must be `None`-terminated. The structures -are not copied; the returned `Caps` owns the structures. -## `structure` -the first structure to add -## `var_args` -additional structures to add - -# Returns - -the new `Caps` - -Creates a new `Caps` that contains one `Structure`. The -structure is defined by the arguments, which have the same format -as `Structure::new`. -Caller is responsible for unreffing the returned caps. -## `media_type` -the media type of the structure -## `fieldname` -first field to set - -# Returns - -the new `Caps` - -Appends the structures contained in `caps2` to `self`. The structures in -`caps2` are not copied -- they are transferred to `self`, and then `caps2` is -freed. If either caps is ANY, the resulting caps will be ANY. -## `caps2` -the `Caps` to append - -Appends `structure` to `self`. The structure is not copied; `self` -becomes the owner of `structure`. -## `structure` -the `Structure` to append - -Appends `structure` with `features` to `self`. The structure is not copied; `self` -becomes the owner of `structure`. -## `structure` -the `Structure` to append -## `features` -the `CapsFeatures` to append - -Tries intersecting `self` and `caps2` and reports whether the result would not -be empty -## `caps2` -a `Caps` to intersect - -# Returns - -`true` if intersection would be not empty - -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` -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`. - -When you are finished with the caps, call `gst_caps_unref` on it. - -# Returns - -the new `Caps` - -Creates a new `Caps` and appends a copy of the nth structure -contained in `self`. - -Feature: `v1_16` - -## `nth` -the nth structure to copy - -# Returns - -the new `Caps` - -Calls the provided function once for each structure and caps feature in the -`Caps`. In contrast to `Caps::foreach`, the function may modify the -structure and features. In contrast to `Caps::filter_and_map_in_place`, -the structure and features are removed from the caps if `false` is returned -from the function. -The caps must be mutable. -## `func` -a function to call for each field -## `user_data` -private data - -Modifies the given `self` into a representation with only fixed -values. First the caps will be truncated and then the first structure will be -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`. - -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 - -the fixated caps - -Calls the provided function once for each structure and caps feature in the -`Caps`. The function must not modify the fields. -Also see `Caps::map_in_place` and `Caps::filter_and_map_in_place`. -## `func` -a function to call for each field -## `user_data` -private data - -# Returns - -`true` if the supplied function returns `true` for each call, -`false` otherwise. - -Finds the features in `self` that has the index `index`, and -returns it. - -WARNING: This function takes a const GstCaps *, but returns a -non-const GstCapsFeatures *. This is for programming convenience -- -the caller should be aware that structures inside a constant -`Caps` should not be modified. However, if you know the caps -are writable, either because you have just copied them or made -them writable with `gst_caps_make_writable`, you may modify the -features returned in the usual way, e.g. with functions like -`CapsFeatures::add`. - -You do not need to free or unref the structure returned, it -belongs to the `Caps`. -## `index` -the index of the structure - -# Returns - -a pointer to the `CapsFeatures` - corresponding to `index` - -Gets the number of structures contained in `self`. - -# Returns - -the number of structures that `self` contains - -Finds the structure in `self` that has the index `index`, and -returns it. - -WARNING: This function takes a const GstCaps *, but returns a -non-const GstStructure *. This is for programming convenience -- -the caller should be aware that structures inside a constant -`Caps` should not be modified. However, if you know the caps -are writable, either because you have just copied them or made -them writable with `gst_caps_make_writable`, you may modify the -structure returned in the usual way, e.g. with functions like -`Structure::set`. - -You do not need to free or unref the structure returned, it -belongs to the `Caps`. -## `index` -the index of the structure - -# Returns - -a pointer to the `Structure` corresponding - to `index` - -Creates a new `Caps` that contains all the formats that are common -to both `self` and `caps2`. Defaults to `CapsIntersectMode::ZigZag` mode. -## `caps2` -a `Caps` to intersect - -# Returns - -the new `Caps` - -Creates a new `Caps` that contains all the formats that are common -to both `self` and `caps2`, the order is defined by the `CapsIntersectMode` -used. -## `caps2` -a `Caps` to intersect -## `mode` -The intersection algorithm/mode to use - -# Returns - -the new `Caps` - -A given `Caps` structure is always compatible with another if -every media format that is in the first is also contained in the -second. That is, `self` is a subset of `caps2`. -## `caps2` -the `Caps` to test - -# Returns - -`true` if `self` is a subset of `caps2`. - -Determines if `self` represents any media format. - -# Returns - -`true` if `self` represents any format. - -Determines if `self` represents no media formats. - -# Returns - -`true` if `self` represents no formats. - -Checks if the given caps represent the same set of caps. -## `caps2` -another `Caps` - -# Returns - -`true` if both caps are equal. - -Tests if two `Caps` are equal. This function only works on fixed -`Caps`. -## `caps2` -the `Caps` to test - -# Returns - -`true` if the arguments represent the same format - -Fixed `Caps` describe exactly one format, that is, they have exactly -one structure, and each field in the structure describes a fixed type. -Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST. - -# Returns - -`true` if `self` is fixed - -Checks if the given caps are exactly the same set of caps. -## `caps2` -another `Caps` - -# Returns - -`true` if both caps are strictly equal. - -Checks if all caps represented by `self` are also represented by `superset`. -## `superset` -a potentially greater `Caps` - -# Returns - -`true` if `self` is a subset of `superset` - -Checks if `structure` is a subset of `self`. See `Caps::is_subset` -for more information. -## `structure` -a potential `Structure` subset of `self` - -# Returns - -`true` if `structure` is a subset of `self` - -Checks if `structure` is a subset of `self`. See `Caps::is_subset` -for more information. -## `structure` -a potential `Structure` subset of `self` -## `features` -a `CapsFeatures` for `structure` - -# Returns - -`true` if `structure` is a subset of `self` - -Calls the provided function once for each structure and caps feature in the -`Caps`. In contrast to `Caps::foreach`, the function may modify but not -delete the structures and features. The caps must be mutable. -## `func` -a function to call for each field -## `user_data` -private data - -# Returns - -`true` if the supplied function returns `true` for each call, -`false` otherwise. - -Appends the structures contained in `caps2` to `self` if they are not yet -expressed by `self`. The structures in `caps2` are not copied -- they are -transferred to a writable copy of `self`, and then `caps2` is freed. -If either caps is ANY, the resulting caps will be ANY. -## `caps2` -the `Caps` to merge in - -# Returns - -the merged caps. - -Appends `structure` to `self` if its not already expressed by `self`. -## `structure` -the `Structure` to merge - -# Returns - -the merged caps. - -Appends `structure` with `features` to `self` if its not already expressed by `self`. -## `structure` -the `Structure` to merge -## `features` -the `CapsFeatures` to merge - -# Returns - -the merged caps. - -Returns a `Caps` that represents the same set of formats as -`self`, but contains no lists. Each list is expanded into separate -`GstStructures`. - -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`. - -# Returns - -the normalized `Caps` - -removes the structure with the given index from the list of structures -contained in `self`. -## `idx` -Index of the structure to remove - -Sets the `CapsFeatures` `features` for the structure at `index`. -## `index` -the index of the structure -## `features` -the `CapsFeatures` to set - -Sets the `CapsFeatures` `features` for all the structures of `self`. - -Feature: `v1_16` - -## `features` -the `CapsFeatures` to set - -Sets fields in a `Caps`. The arguments must be passed in the same -manner as `Structure::set`, and be `None`-terminated. -## `field` -first field to set - -Sets fields in a `Caps`. The arguments must be passed in the same -manner as `Structure::set`, and be `None`-terminated. -## `field` -first field to set -## `varargs` -additional parameters - -Sets the given `field` on all structures of `self` to the given `value`. -This is a convenience function for calling `Structure::set_value` on -all structures of `self`. -## `field` -name of the field to set -## `value` -value to set the field to - -Converts the given `self` into a representation that represents the -same set of formats, but in a simpler form. Component structures that are -identical are merged. Component structures that have values that can be -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`. - -This method does not preserve the original order of `self`. - -# Returns - -The simplified caps. - -Retrieves the structure with the given index from the list of structures -contained in `self`. The caller becomes the owner of the returned structure. -## `index` -Index of the structure to retrieve - -# Returns - -a pointer to the `Structure` - corresponding to `index`. - -Subtracts the `subtrahend` from the `self`. -> This function does not work reliably if optional properties for caps -> are included on one caps and omitted on the other. -## `subtrahend` -`Caps` to subtract - -# Returns - -the resulting caps - -Converts `self` to a string representation. This string representation -can be converted back to a `Caps` by `Caps::from_string`. - -For debugging purposes its easier to do something like this: - -```C -GST_LOG ("caps are %" GST_PTR_FORMAT, caps); -``` -This prints the caps in human readable form. - -The current implementation of serialization will lead to unexpected results -when there are nested `Caps` / `Structure` deeper than one level. - -# Returns - -a newly allocated string representing `self`. - -Discard all but the first structure from `self`. Useful when -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`. - -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 - -Converts `caps` from a string representation. - -The current implementation of serialization will lead to unexpected results -when there are nested `Caps` / `Structure` deeper than one level. -## `string` -a string to convert to `Caps` - -# Returns - -a newly allocated `Caps` - -Modes of caps intersection - -[`ZigZag`](Self::ZigZag) tries to preserve overall order of both caps -by iterating on the caps' structures as the following matrix shows: - -```text - caps1 - +------------- - | 1 2 4 7 -caps2 | 3 5 8 10 - | 6 9 11 12 -``` -Used when there is no explicit precedence of one caps over the other. e.g. -tee's sink pad getcaps function, it will probe its src pad peers' for their -caps and intersect them with this mode. - -[`First`](Self::First) is useful when an element wants to preserve -another element's caps priority order when intersecting with its own caps. -Example: If caps1 is [A, B, C] and caps2 is [E, B, D, A], the result -would be [A, B], maintaining the first caps priority on the intersection. - -Zig-zags over both caps. - -Keeps the first caps order. - -This interface abstracts handling of property sets for elements with -children. Imagine elements such as mixers or polyphonic generators. They all -have multiple `Pad` or some kind of voice objects. Another use case are -container elements like `Bin`. -The element implementing the interface acts as a parent for those child -objects. - -By implementing this interface the child properties can be accessed from the -parent element by using `ChildProxy::get` and `ChildProxy::set`. - -Property names are written as "child-name::property-name". The whole naming -scheme is recursive. Thus "child1::child2::property" is valid too, if -"child1" and "child2" implement the `ChildProxy` interface. - -# Implements - -[`ChildProxyExt`](trait@crate::ChildProxyExt), [`ChildProxyExtManual`](trait@crate::ChildProxyExtManual) - -Trait containing all `ChildProxy` methods. - -# Implementors - -[`Bin`](struct@crate::Bin), [`ChildProxy`](struct@crate::ChildProxy), [`Pipeline`](struct@crate::Pipeline) - -Emits the "child-added" signal. -## `child` -the newly added child -## `name` -the name of the new child - -Emits the "child-removed" signal. -## `child` -the removed child -## `name` -the name of the old child - -Gets properties of the parent object and its children. -## `first_property_name` -name of the first property to get - -Fetches a child by its number. -## `index` -the child's position in the child list - -# Returns - -the child object or `None` if - not found (index too high). Unref after usage. - -MT safe. - -Looks up a child element by the given name. - -This virtual method has a default implementation that uses `Object` -together with `GstObjectExt::get_name`. If the interface is to be used with -`GObjects`, this methods needs to be overridden. -## `name` -the child's name - -# Returns - -the child object or `None` if - not found. Unref after usage. - -MT safe. - -Gets the number of child objects this parent contains. - -# Returns - -the number of child objects - -MT safe. - -Gets a single property using the GstChildProxy mechanism. -You are responsible for freeing it by calling `glib::object::Value::unset` -## `name` -name of the property -## `value` -a `glib::object::Value` that should take the result. - -Gets properties of the parent object and its children. -## `first_property_name` -name of the first property to get -## `var_args` -return location for the first property, followed optionally by more name/return location pairs, followed by `None` - -Looks up which object and `glib::object::ParamSpec` would be effected by the given `name`. - -MT safe. -## `name` -name of the property to look up -## `target` -pointer to a `glib::object::Object` that - takes the real object to set property on -## `pspec` -pointer to take the `glib::object::ParamSpec` - describing the property - -# Returns - -`true` if `target` and `pspec` could be found. `false` otherwise. In that -case the values for `pspec` and `target` are not modified. Unref `target` after -usage. For plain GObjects `target` is the same as `self`. - -Sets properties of the parent object and its children. -## `first_property_name` -name of the first property to set - -Sets a single property using the GstChildProxy mechanism. -## `name` -name of the property to set -## `value` -new `glib::object::Value` for the property - -Sets properties of the parent object and its children. -## `first_property_name` -name of the first property to set -## `var_args` -value for the first property, followed optionally by more name/value pairs, followed by `None` - -Will be emitted after the `object` was added to the `child_proxy`. -## `object` -the `glib::object::Object` that was added -## `name` -the name of the new child - -Will be emitted after the `object` was removed from the `child_proxy`. -## `object` -the `glib::object::Object` that was removed -## `name` -the name of the old child - -GStreamer uses a global clock to synchronize the plugins in a pipeline. -Different clock implementations are possible by implementing this abstract -base class or, more conveniently, by subclassing `SystemClock`. - -The `Clock` returns a monotonically increasing time with the method -`ClockExt::get_time`. Its accuracy and base time depend on the specific -clock implementation but time is always expressed in nanoseconds. Since the -baseline of the clock is undefined, the clock time returned is not -meaningful in itself, what matters are the deltas between two clock times. -The time returned by a clock is called the absolute time. - -The pipeline uses the clock to calculate the running time. Usually all -renderers synchronize to the global clock using the buffer timestamps, the -newsegment events and the element's base time, see `Pipeline`. - -A clock implementation can support periodic and single shot clock -notifications both synchronous and asynchronous. - -One first needs to create a `ClockID` for the periodic or single shot -notification using `ClockExt::new_single_shot_id` or -`ClockExt::new_periodic_id`. - -To perform a blocking wait for the specific time of the `ClockID` use the -`Clock::id_wait`. To receive a callback when the specific time is reached -in the clock use `Clock::id_wait_async`. Both these calls can be -interrupted with the `Clock::id_unschedule` call. If the blocking wait is -unscheduled a return value of `ClockReturn::Unscheduled` is returned. - -Periodic callbacks scheduled async will be repeatedly called automatically -until it is unscheduled. To schedule a sync periodic callback, -`Clock::id_wait` should be called repeatedly. - -The async callbacks can happen from any thread, either provided by the core -or from a streaming thread. The application should be prepared for this. - -A `ClockID` that has been unscheduled cannot be used again for any wait -operation, a new `ClockID` should be created and the old unscheduled one -should be destroyed with `Clock::id_unref`. - -It is possible to perform a blocking wait on the same `ClockID` from -multiple threads. However, registering the same `ClockID` for multiple -async notifications is not possible, the callback will only be called for -the thread registering the entry last. - -None of the wait operations unref the `ClockID`, the owner is responsible -for unreffing the ids itself. This holds for both periodic and single shot -notifications. The reason being that the owner of the `ClockID` has to -keep a handle to the `ClockID` to unblock the wait on FLUSHING events or -state changes and if the entry would be unreffed automatically, the handle -might become invalid without any notification. - -These clock operations do not operate on the running time, so the callbacks -will also occur when not in PLAYING state as if the clock just keeps on -running. Some clocks however do not progress when the element that provided -the clock is not PLAYING. - -When a clock has the `ClockFlags::CanSetMaster` flag set, it can be -slaved to another `Clock` with the `ClockExt::set_master`. The clock will -then automatically be synchronized to this master clock by repeatedly -sampling the master clock and the slave clock and recalibrating the slave -clock with `ClockExt::set_calibration`. This feature is mostly useful for -plugins that have an internal clock but must operate with another clock -selected by the `Pipeline`. They can track the offset and rate difference -of their internal clock relative to the master clock by using the -`ClockExt::get_calibration` function. - -The master/slave synchronisation can be tuned with the `Clock:timeout`, -`Clock:window-size` and `Clock:window-threshold` properties. -The `Clock:timeout` property defines the interval to sample the master -clock and run the calibration functions. `Clock:window-size` defines the -number of samples to use when calibrating and `Clock:window-threshold` -defines the minimum number of samples before the calibration is performed. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`ClockExt`](trait@crate::ClockExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`ClockExtManual`](trait@crate::ClockExtManual) - -Trait containing all `Clock` methods. - -# Implementors - -[`Clock`](struct@crate::Clock), [`SystemClock`](struct@crate::SystemClock) - -Compares the two `ClockID` instances. This function can be used -as a GCompareFunc when sorting ids. -## `id1` -A `ClockID` -## `id2` -A `ClockID` to compare with - -# Returns - -negative value if a < b; zero if a = b; positive value if a > b - -MT safe. - -This function returns the underlying clock. - -Feature: `v1_16` - -## `id` -a `ClockID` - -# Returns - -a `Clock` or `None` when the - underlying clock has been freed. Unref after usage. - -MT safe. - -Get the time of the clock ID -## `id` -The `ClockID` to query - -# Returns - -the time of the given clock id. - -MT safe. - -Increase the refcount of given `id`. -## `id` -The `ClockID` to ref - -# Returns - -The same `ClockID` with increased refcount. - -MT safe. - -Unref given `id`. When the refcount reaches 0 the -`ClockID` will be freed. - -MT safe. -## `id` -The `ClockID` to unref - -Cancel an outstanding request with `id`. This can either -be an outstanding async notification or a pending sync notification. -After this call, `id` cannot be used anymore to receive sync or -async notifications, you need to create a new `ClockID`. - -MT safe. -## `id` -The id to unschedule - -This function returns whether `id` uses `clock` as the underlying clock. -`clock` can be NULL, in which case the return value indicates whether -the underlying clock has been freed. If this is the case, the `id` is -no longer usable and should be freed. - -Feature: `v1_16` - -## `id` -a `ClockID` to check -## `clock` -a `Clock` to compare against - -# Returns - -whether the clock `id` uses the same underlying `Clock` `clock`. - -MT safe. - -Perform a blocking wait on `id`. -`id` should have been created with `ClockExt::new_single_shot_id` -or `ClockExt::new_periodic_id` and should not have been unscheduled -with a call to `Clock::id_unschedule`. - -If the `jitter` argument is not `None` and this function returns `ClockReturn::Ok` -or `ClockReturn::Early`, it will contain the difference -against the clock and the time of `id` when this method was -called. -Positive values indicate how late `id` was relative to the clock -(in which case this function will return `ClockReturn::Early`). -Negative values indicate how much time was spent waiting on the clock -before this function returned. -## `id` -The `ClockID` to wait on -## `jitter` -a pointer that will contain the jitter, - can be `None`. - -# Returns - -the result of the blocking wait. `ClockReturn::Early` will be returned -if the current clock time is past the time of `id`, `ClockReturn::Ok` if -`id` was scheduled in time. `ClockReturn::Unscheduled` if `id` was -unscheduled with `Clock::id_unschedule`. - -MT safe. - -Register a callback on the given `ClockID` `id` with the given -function and user_data. When passing a `ClockID` with an invalid -time to this function, the callback will be called immediately -with a time set to GST_CLOCK_TIME_NONE. The callback will -be called when the time of `id` has been reached. - -The callback `func` can be invoked from any thread, either provided by the -core or from a streaming thread. The application should be prepared for this. -## `id` -a `ClockID` to wait on -## `func` -The callback function -## `user_data` -User data passed in the callback -## `destroy_data` -`GDestroyNotify` for user_data - -# Returns - -the result of the non blocking wait. - -MT safe. - -The time `master` of the master clock and the time `slave` of the slave -clock are added to the list of observations. If enough observations -are available, a linear regression algorithm is run on the -observations and `self` is recalibrated. - -If this functions returns `true`, `r_squared` will contain the -correlation coefficient of the interpolation. A value of 1.0 -means a perfect regression was performed. This value can -be used to control the sampling frequency of the master and slave -clocks. -## `slave` -a time on the slave -## `master` -a time on the master -## `r_squared` -a pointer to hold the result - -# Returns - -`true` if enough observations were added to run the -regression algorithm. - -MT safe. - -Add a clock observation to the internal slaving algorithm the same as -`ClockExt::add_observation`, and return the result of the master clock -estimation, without updating the internal calibration. - -The caller can then take the results and call `ClockExt::set_calibration` -with the values, or some modified version of them. -## `slave` -a time on the slave -## `master` -a time on the master -## `r_squared` -a pointer to hold the result -## `internal` -a location to store the internal time -## `external` -a location to store the external time -## `rate_num` -a location to store the rate numerator -## `rate_denom` -a location to store the rate denominator - -Converts the given `internal` clock time to the external time, adjusting for the -rate and reference time set with `ClockExt::set_calibration` and making sure -that the returned time is increasing. This function should be called with the -clock's OBJECT_LOCK held and is mainly used by clock subclasses. - -This function is the reverse of `ClockExt::unadjust_unlocked`. -## `internal` -a clock time - -# Returns - -the converted time of the clock. - -Converts the given `internal_target` clock time to the external time, -using the passed calibration parameters. This function performs the -same calculation as `ClockExt::adjust_unlocked` when called using the -current calibration parameters, but doesn't ensure a monotonically -increasing result as `ClockExt::adjust_unlocked` does. - -Note: The `self` parameter is unused and can be NULL -## `internal_target` -a clock time -## `cinternal` -a reference internal time -## `cexternal` -a reference external time -## `cnum` -the numerator of the rate of the clock relative to its - internal time -## `cdenom` -the denominator of the rate of the clock - -# Returns - -the converted time of the clock. - -Gets the internal rate and reference time of `self`. See -`ClockExt::set_calibration` for more information. - -`internal`, `external`, `rate_num`, and `rate_denom` can be left `None` if the -caller is not interested in the values. - -MT safe. -## `internal` -a location to store the internal time -## `external` -a location to store the external time -## `rate_num` -a location to store the rate numerator -## `rate_denom` -a location to store the rate denominator - -Gets the current internal time of the given clock. The time is returned -unadjusted for the offset and the rate. - -# Returns - -the internal time of the clock. Or GST_CLOCK_TIME_NONE when -given invalid input. - -MT safe. - -Get the master clock that `self` is slaved to or `None` when the clock is -not slaved to any master clock. - -# Returns - -a master `Clock` or `None` - when this clock is not slaved to a master clock. Unref after - usage. - -MT safe. - -Get the accuracy of the clock. The accuracy of the clock is the granularity -of the values returned by `ClockExt::get_time`. - -# Returns - -the resolution of the clock in units of `ClockTime`. - -MT safe. - -Gets the current time of the given clock. The time is always -monotonically increasing and adjusted according to the current -offset and rate. - -# Returns - -the time of the clock. Or GST_CLOCK_TIME_NONE when -given invalid input. - -MT safe. - -Get the amount of time that master and slave clocks are sampled. - -# Returns - -the interval between samples. - -Checks if the clock is currently synced. - -This returns if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock. - -# Returns - -`true` if the clock is currently synced - -Get an ID from `self` to trigger a periodic notification. -The periodic notifications will start at time `start_time` and -will then be fired with the given `interval`. `id` should be unreffed -after usage. - -Free-function: gst_clock_id_unref -## `start_time` -the requested start time -## `interval` -the requested interval - -# Returns - -a `ClockID` that can be used to request the - time notification. - -MT safe. - -Get a `ClockID` from `self` to trigger a single shot -notification at the requested time. The single shot id should be -unreffed after usage. - -Free-function: gst_clock_id_unref -## `time` -the requested time - -# Returns - -a `ClockID` that can be used to request the - time notification. - -MT safe. - -Reinitializes the provided periodic `id` to the provided start time and -interval. Does not modify the reference count. -## `id` -a `ClockID` -## `start_time` -the requested start time -## `interval` -the requested interval - -# Returns - -`true` if the GstClockID could be reinitialized to the provided -`time`, else `false`. - -Adjusts the rate and time of `self`. A rate of 1/1 is the normal speed of -the clock. Values bigger than 1/1 make the clock go faster. - -`internal` and `external` are calibration parameters that arrange that -`ClockExt::get_time` should have been `external` at internal time `internal`. -This internal time should not be in the future; that is, it should be less -than the value of `ClockExt::get_internal_time` when this function is called. - -Subsequent calls to `ClockExt::get_time` will return clock times computed as -follows: - - -```text - time = (internal_time - internal) * rate_num / rate_denom + external -``` - -This formula is implemented in `ClockExt::adjust_unlocked`. Of course, it -tries to do the integer arithmetic as precisely as possible. - -Note that `ClockExt::get_time` always returns increasing values so when you -move the clock backwards, `ClockExt::get_time` will report the previous value -until the clock catches up. - -MT safe. -## `internal` -a reference internal time -## `external` -a reference external time -## `rate_num` -the numerator of the rate of the clock relative to its - internal time -## `rate_denom` -the denominator of the rate of the clock - -Set `master` as the master clock for `self`. `self` will be automatically -calibrated so that `ClockExt::get_time` reports the same time as the -master clock. - -A clock provider that slaves its clock to a master can get the current -calibration values with `ClockExt::get_calibration`. - -`master` can be `None` in which case `self` will not be slaved anymore. It will -however keep reporting its time adjusted with the last configured rate -and time offsets. -## `master` -a master `Clock` - -# Returns - -`true` if the clock is capable of being slaved to a master clock. -Trying to set a master on a clock without the -`ClockFlags::CanSetMaster` flag will make this function return `false`. - -MT safe. - -Set the accuracy of the clock. Some clocks have the possibility to operate -with different accuracy at the expense of more resource usage. There is -normally no need to change the default resolution of a clock. The resolution -of a clock can only be changed if the clock has the -`ClockFlags::CanSetResolution` flag set. -## `resolution` -The resolution to set - -# Returns - -the new resolution of the clock. - -Sets `self` to synced and emits the GstClock::synced signal, and wakes up any -thread waiting in `ClockExt::wait_for_sync`. - -This function must only be called if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC -is set on the clock, and is intended to be called by subclasses only. -## `synced` -if the clock is synced - -Set the amount of time, in nanoseconds, to sample master and slave -clocks -## `timeout` -a timeout - -Reinitializes the provided single shot `id` to the provided time. Does not -modify the reference count. -## `id` -a `ClockID` -## `time` -The requested time. - -# Returns - -`true` if the GstClockID could be reinitialized to the provided -`time`, else `false`. - -Converts the given `external` clock time to the internal time of `self`, -using the rate and reference time set with `ClockExt::set_calibration`. -This function should be called with the clock's OBJECT_LOCK held and -is mainly used by clock subclasses. - -This function is the reverse of `ClockExt::adjust_unlocked`. -## `external` -an external clock time - -# Returns - -the internal time of the clock corresponding to `external`. - -Converts the given `external_target` clock time to the internal time, -using the passed calibration parameters. This function performs the -same calculation as `ClockExt::unadjust_unlocked` when called using the -current calibration parameters. - -Note: The `self` parameter is unused and can be NULL -## `external_target` -a clock time -## `cinternal` -a reference internal time -## `cexternal` -a reference external time -## `cnum` -the numerator of the rate of the clock relative to its - internal time -## `cdenom` -the denominator of the rate of the clock - -# Returns - -the converted time of the clock. - -Waits until `self` is synced for reporting the current time. If `timeout` -is `GST_CLOCK_TIME_NONE` it will wait forever, otherwise it will time out -after `timeout` nanoseconds. - -For asynchronous waiting, the GstClock::synced signal can be used. - -This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC -is not set on the clock, or if the clock is already synced. -## `timeout` -timeout for waiting or `GST_CLOCK_TIME_NONE` - -# Returns - -`true` if waiting was successful, or `false` on timeout - -Signaled on clocks with GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once -the clock is synchronized, or when it completely lost synchronization. -This signal will not be emitted on clocks without the flag. - -This signal will be emitted from an arbitrary thread, most likely not -the application's main thread. -## `synced` -if the clock is synced now - -The type of the clock entry - -a single shot timeout - -a periodic timeout request - -The capabilities of this clock - -clock can do a single sync timeout request - -clock can do a single async timeout request - -clock can do sync periodic timeout requests - -clock can do async periodic timeout callbacks - -clock's resolution can be changed - -clock can be slaved to a master clock - -clock needs to be synced before it can be used - (Since: 1.6) - -subclasses can add additional flags starting from this flag - -The return value of a clock operation. - -The operation succeeded. - -The operation was scheduled too late. - -The clockID was unscheduled - -The ClockID is busy - -A bad time was provided to a function. - -An error occurred - -Operation is not supported - -The ClockID is done waiting - -The different kind of clocks. - -time since Epoch - -monotonic time since some unspecified starting - point - -some other time source is used (Since: 1.0.5) - -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 -be shared between multiple elements. - -Applications can set a context on a complete pipeline by using -`ElementExt::set_context`, which will then be propagated to all -child elements. Elements can handle these in `ElementClass.set_context`() -and merge them with the context information they already have. - -When an element needs a context it will do the following actions in this -order until one step succeeds: -1. Check if the element already has a context -2. Query downstream with GST_QUERY_CONTEXT for the context -3. Query upstream with GST_QUERY_CONTEXT for the context -4. Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required - context types and afterwards check if a usable context was set now -5. Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message - on the bus. - -Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously -known context on the element that asks for it if possible. Otherwise the -application should provide one if it can. - -`Context`s can be persistent. -A persistent `Context` is kept in elements when they reach -`State::Null`, non-persistent ones will be removed. -Also, a non-persistent context won't override a previous persistent -context set to an element. - -Create a new context. -## `context_type` -Context type -## `persistent` -Persistent context - -# Returns - -The new context. - -Get the type of `self`. - -# Returns - -The type of the context. - -Access the structure of the context. - -# Returns - -The structure of the context. The structure is -still owned by the context, which means that you should not modify it, -free it and that the pointer becomes invalid when you free the context. - -Checks if `self` has `context_type`. -## `context_type` -Context type to check. - -# Returns - -`true` if `self` has `context_type`. - -Check if `self` is persistent. - -# Returns - -`true` if the context is persistent. - -Get a writable version of the structure. - -# Returns - -The structure of the context. The structure is still -owned by the context, which means that you should not free it and -that the pointer becomes invalid when you free the context. -This function checks if `self` is writable. - -A base class for value mapping objects that attaches control sources to gobject -properties. Such an object is taking one or more `ControlSource` instances, -combines them and maps the resulting value to the type and value range of the -bound property. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`ControlBindingExt`](trait@crate::ControlBindingExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`ControlBindingExtManual`](trait@crate::ControlBindingExtManual) - -Trait containing all `ControlBinding` methods. - -# Implementors - -[`ControlBinding`](struct@crate::ControlBinding) - -Gets a number of `GValues` for the given controlled property starting at the -requested time. The array `values` need to hold enough space for `n_values` of -`glib::object::Value`. - -This function is useful if one wants to e.g. draw a graph of the control -curve or apply a control curve sample by sample. -## `timestamp` -the time that should be processed -## `interval` -the time spacing between subsequent values -## `n_values` -the number of values -## `values` -array to put control-values in - -# Returns - -`true` if the given array could be filled, `false` otherwise - -Gets the value for the given controlled property at the requested time. -## `timestamp` -the time the control-change should be read from - -# Returns - -the GValue of the property at the given time, -or `None` if the property isn't controlled. - -Gets a number of values for the given controlled property starting at the -requested time. The array `values` need to hold enough space for `n_values` of -the same type as the objects property's type. - -This function is useful if one wants to e.g. draw a graph of the control -curve or apply a control curve sample by sample. - -The values are unboxed and ready to be used. The similar function -`ControlBinding::get_g_value_array` returns the array as `GValues` and is -more suitable for bindings. -## `timestamp` -the time that should be processed -## `interval` -the time spacing between subsequent values -## `n_values` -the number of values -## `values` -array to put control-values in - -# Returns - -`true` if the given array could be filled, `false` otherwise - -Check if the control binding is disabled. - -# Returns - -`true` if the binding is inactive - -This function is used to disable a control binding for some time, i.e. -`GstObjectExt::sync_values` will do nothing. -## `disabled` -boolean that specifies whether to disable the controller -or not. - -Sets the property of the `object`, according to the `GstControlSources` that -handle them and for the given timestamp. - -If this function fails, it is most likely the application developers fault. -Most probably the control sources are not setup correctly. -## `object` -the object that has controlled properties -## `timestamp` -the time that should be processed -## `last_sync` -the last time this was called - -# Returns - -`true` if the controller value could be applied to the object -property, `false` otherwise - -The `ControlSource` is a base class for control value sources that could -be used to get timestamp-value pairs. A control source essentially is a -function over time. - -A `ControlSource` is used by first getting an instance of a specific -control-source, creating a binding for the control-source to the target property -of the element and then adding the binding to the element. The binding will -convert the data types and value range to fit to the bound property. - -For implementing a new `ControlSource` one has to implement -`GstControlSourceGetValue` and `GstControlSourceGetValueArray` functions. -These are then used by `ControlSourceExt::control_source_get_value` and -`ControlSource::control_source_get_value_array` to get values for specific timestamps. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`ControlSourceExt`](trait@crate::ControlSourceExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`ControlSourceExtManual`](trait@crate::ControlSourceExtManual) - -Trait containing all `ControlSource` methods. - -# Implementors - -[`ControlSource`](struct@crate::ControlSource) - -Gets the value for this `ControlSource` at a given timestamp. -## `timestamp` -the time for which the value should be returned -## `value` -the value - -# Returns - -`false` if the value couldn't be returned, `true` otherwise. - -Gets an array of values for for this `ControlSource`. Values that are -undefined contain NANs. -## `timestamp` -the first timestamp -## `interval` -the time steps -## `n_values` -the number of values to fetch -## `values` -array to put control-values in - -# Returns - -`true` if the given array could be filled, `false` otherwise - -Core errors are errors inside the core GStreamer library. - -a general error which doesn't fit in any other -category. Make sure you add a custom message to the error call. - -do not use this except as a placeholder for -deciding where to go while developing code. - -use this when you do not want to implement -this functionality yet. - -used for state change errors. - -used for pad-related errors. - -used for thread-related errors. - -used for negotiation-related errors. - -used for event-related errors. - -used for seek-related errors. - -used for caps-related errors. - -used for negotiation-related errors. - -used if a plugin is missing. - -used for clock related errors. - -used if functionality has been disabled at - compile time. - -the number of core error types. - -Struct to store date, time and timezone information altogether. -`DateTime` is refcounted and immutable. - -Date information is handled using the proleptic Gregorian calendar. - -Provides basic creation functions and accessor functions to its fields. - -Creates a new `DateTime` using the date and times in the gregorian calendar -in the supplied timezone. - -`year` should be from 1 to 9999, `month` should be from 1 to 12, `day` from -1 to 31, `hour` from 0 to 23, `minutes` and `seconds` from 0 to 59. - -Note that `tzoffset` is a float and was chosen so for being able to handle -some fractional timezones, while it still keeps the readability of -representing it in hours for most timezones. - -If value is -1 then all over value will be ignored. For example -if `month` == -1, then `DateTime` will created only for `year`. If -`day` == -1, then `DateTime` will created for `year` and `month` and -so on. - -Free-function: gst_date_time_unref -## `tzoffset` -Offset from UTC in hours. -## `year` -the gregorian year -## `month` -the gregorian month -## `day` -the day of the gregorian month -## `hour` -the hour of the day -## `minute` -the minute of the hour -## `seconds` -the second of the minute - -# Returns - -the newly created `DateTime` - -Creates a new `DateTime` from a `glib::DateTime` object. - -Free-function: gst_date_time_unref -## `dt` -the `glib::DateTime`. The new `DateTime` takes ownership. - -# Returns - -a newly created `DateTime`, -or `None` on error - -Tries to parse common variants of ISO-8601 datetime strings into a -`DateTime`. Possible input formats are (for example): -2012-06-30T22:46:43Z, 2012, 2012-06, 2012-06-30, 2012-06-30T22:46:43-0430, -2012-06-30T22:46Z, 2012-06-30T22:46-0430, 2012-06-30 22:46, -2012-06-30 22:46:43, 2012-06-00, 2012-00-00, 2012-00-30, 22:46:43Z, 22:46Z, -22:46:43-0430, 22:46-0430, 22:46:30, 22:46 -If no date is provided, it is assumed to be "today" in the timezone -provided (if any), otherwise UTC. - -Free-function: gst_date_time_unref -## `string` -ISO 8601-formatted datetime string. - -# Returns - -a newly created `DateTime`, -or `None` on error - -Creates a new `DateTime` using the time since Jan 1, 1970 specified by -`secs`. The `DateTime` is in the local timezone. - -Free-function: gst_date_time_unref -## `secs` -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. - -Free-function: gst_date_time_unref -## `secs` -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. - -`year` should be from 1 to 9999, `month` should be from 1 to 12, `day` from -1 to 31, `hour` from 0 to 23, `minutes` and `seconds` from 0 to 59. - -If `month` is -1, then the `DateTime` created will only contain `year`, -and all other fields will be considered not set. - -If `day` is -1, then the `DateTime` created will only contain `year` and -`month` and all other fields will be considered not set. - -If `hour` is -1, then the `DateTime` created will only contain `year` and -`month` and `day`, and the time fields will be considered not set. In this -case `minute` and `seconds` should also be -1. - -Free-function: gst_date_time_unref -## `year` -the gregorian year -## `month` -the gregorian month, or -1 -## `day` -the day of the gregorian month, or -1 -## `hour` -the hour of the day, or -1 -## `minute` -the minute of the hour, or -1 -## `seconds` -the second of the minute, or -1 - -# Returns - -the newly created `DateTime` - -Creates a new `DateTime` representing the current date and time. - -Free-function: gst_date_time_unref - -# Returns - -the newly created `DateTime` which should - be freed with `DateTime::unref`. - -Creates a new `DateTime` that represents the current instant at Universal -coordinated time. - -Free-function: gst_date_time_unref - -# Returns - -the newly created `DateTime` which should - be freed with `DateTime::unref`. - -Creates a new `DateTime` using the date and times in the gregorian calendar -in the local timezone. - -`year` should be from 1 to 9999. - -Free-function: gst_date_time_unref -## `year` -the gregorian year - -# Returns - -the newly created `DateTime` - -Creates a new `DateTime` using the date and times in the gregorian calendar -in the local timezone. - -`year` should be from 1 to 9999, `month` should be from 1 to 12. - -If value is -1 then all over value will be ignored. For example -if `month` == -1, then `DateTime` will created only for `year`. - -Free-function: gst_date_time_unref -## `year` -the gregorian year -## `month` -the gregorian month - -# Returns - -the newly created `DateTime` - -Creates a new `DateTime` using the date and times in the gregorian calendar -in the local timezone. - -`year` should be from 1 to 9999, `month` should be from 1 to 12, `day` from -1 to 31. - -If value is -1 then all over value will be ignored. For example -if `month` == -1, then `DateTime` will created only for `year`. If -`day` == -1, then `DateTime` will created for `year` and `month` and -so on. - -Free-function: gst_date_time_unref -## `year` -the gregorian year -## `month` -the gregorian month -## `day` -the day of the gregorian month - -# Returns - -the newly created `DateTime` - -Returns the day of the month of this `DateTime`. -Call `DateTime::has_day` before, to avoid warnings. - -# Returns - -The day of this `DateTime` - -Retrieves the hour of the day represented by `self` in the gregorian -calendar. The return is in the range of 0 to 23. -Call `DateTime::has_time` before, to avoid warnings. - -# Returns - -the hour of the day - -Retrieves the fractional part of the seconds in microseconds represented by -`self` in the gregorian calendar. - -# Returns - -the microsecond of the second - -Retrieves the minute of the hour represented by `self` in the gregorian -calendar. -Call `DateTime::has_time` before, to avoid warnings. - -# Returns - -the minute of the hour - -Returns the month of this `DateTime`. January is 1, February is 2, etc.. -Call `DateTime::has_month` before, to avoid warnings. - -# Returns - -The month of this `DateTime` - -Retrieves the second of the minute represented by `self` in the gregorian -calendar. -Call `DateTime::has_time` before, to avoid warnings. - -# Returns - -the second represented by `self` - -Retrieves the offset from UTC in hours that the timezone specified -by `self` represents. Timezones ahead (to the east) of UTC have positive -values, timezones before (to the west) of UTC have negative values. -If `self` represents UTC time, then the offset is zero. - -# Returns - -the offset from UTC in hours - -Returns the year of this `DateTime` -Call `DateTime::has_year` before, to avoid warnings. - -# Returns - -The year of this `DateTime` - - -# Returns - -`true` if `self`'s day field is set, otherwise `false` - - -# Returns - -`true` if `self`'s month field is set, otherwise `false` - - -# Returns - -`true` if `self`'s second field is set, otherwise `false` - - -# Returns - -`true` if `self`'s hour and minute fields are set, - otherwise `false` - - -# Returns - -`true` if `self`'s year field is set (which should always - be the case), otherwise `false` - -Atomically increments the reference count of `self` by one. - -# Returns - -the reference `self` - -Creates a new `glib::DateTime` from a fully defined `DateTime` object. - -Free-function: g_date_time_unref - -# Returns - -a newly created `glib::DateTime`, or -`None` on error - -Create a minimal string compatible with ISO-8601. Possible output formats -are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z, -2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100 - -# Returns - -a newly allocated string formatted according - to ISO 8601 and only including the datetime fields that are - valid, or `None` in case there was an error. The string should - be freed with `g_free`. - -Atomically decrements the reference count of `self` by one. When the -reference count reaches zero, the structure is freed. - -These are some terminal style flags you can use when creating your -debugging categories to make them stand out in debugging output. - -Use black as foreground color. - -Use red as foreground color. - -Use green as foreground color. - -Use yellow as foreground color. - -Use blue as foreground color. - -Use magenta as foreground color. - -Use cyan as foreground color. - -Use white as foreground color. - -Use black as background color. - -Use red as background color. - -Use green as background color. - -Use yellow as background color. - -Use blue as background color. - -Use magenta as background color. - -Use cyan as background color. - -Use white as background color. - -Make the output bold. - -Underline the output. - -Available details for pipeline graphs produced by GST_DEBUG_BIN_TO_DOT_FILE() -and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS(). - -show caps-name on edges - -show caps-details on edges - -show modified parameters on - elements - -show element states - -show full element parameter values even - if they are very long - -show all the typical details that one might want - -show all details regardless of how large or - verbose they make the resulting output - -The level defines the importance of a debugging message. The more important a -message is, the greater the probability that the debugging system outputs it. - -No debugging level specified or desired. Used to deactivate - debugging output. - -Error messages are to be used only when an error occurred - that stops the application from keeping working correctly. - An examples is gst_element_error, which outputs a message with this priority. - It does not mean that the application is terminating as with g_error. - -Warning messages are to inform about abnormal behaviour - that could lead to problems or weird behaviour later on. An example of this - would be clocking issues ("your computer is pretty slow") or broken input - data ("Can't synchronize to stream.") - -Fixme messages are messages that indicate that something - in the executed code path is not fully implemented or handled yet. Note - that this does not replace proper error handling in any way, the purpose - of this message is to make it easier to spot incomplete/unfinished pieces - of code when reading the debug log. - -Informational messages should be used to keep the developer - updated about what is happening. - Examples where this should be used are when a typefind function has - successfully determined the type of the stream or when an mp3 plugin detects - the format to be used. ("This file has mono sound.") - -Debugging messages should be used when something common - happens that is not the expected default behavior, or something that's - useful to know but doesn't happen all the time (ie. per loop iteration or - buffer processed or event handled). - An example would be notifications about state changes or receiving/sending - of events. - -Log messages are messages that are very common but might be - useful to know. As a rule of thumb a pipeline that is running as expected - should never output anything else but LOG messages whilst processing data. - Use this log level to log recurring information in chain functions and - loop functions, for example. - -Tracing-related messages. - Examples for this are referencing/dereferencing of objects. - -memory dump messages are used to log (small) chunks of - data as memory dumps in the log. They will be displayed as hexdump with - ASCII characters. - -The number of defined debugging levels. - -`Device` are objects representing a device, they contain -relevant metadata about the device, such as its class and the `Caps` -representing the media types it can produce or handle. - -`Device` are created by `DeviceProvider` objects which can be -aggregated by `DeviceMonitor` objects. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`DeviceExt`](trait@crate::DeviceExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `Device` methods. - -# Implementors - -[`Device`](struct@crate::Device) - -Creates the element with all of the required parameters set to use -this device. -## `name` -name of new element, or `None` to automatically -create a unique name. - -# Returns - -a new `Element` configured to use -this device - -Getter for the `Caps` that this device supports. - -# Returns - -The `Caps` supported by this device. Unref with -`gst_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 -classes of the `DeviceProvider` that produced this device. - -# Returns - -The device class. Free with `g_free` after use. - -Gets the user-friendly name of the device. - -# Returns - -The device name. Free with `g_free` after use. - -Gets the extra properties of a device. - -# Returns - -The extra properties or `None` when there are none. - Free with `Structure::free` after use. - -Check if `self` matches all of the given classes -## `classes` -a "/"-separated list of device classes to match, only match if - all classes are matched - -# Returns - -`true` if `self` matches. - -Check if `factory` matches all of the given classes -## `classes` -a `None` terminated array of classes - to match, only match if all classes are matched - -# Returns - -`true` if `self` matches. - -Tries to reconfigure an existing element to use the device. If this -function fails, then one must destroy the element and create a new one -using `DeviceExt::create_element`. - -Note: This should only be implemented for elements can change their -device in the PLAYING state. -## `element` -a `Element` - -# Returns - -`true` if the element could be reconfigured to use this device, -`false` otherwise. - -Applications should create a `DeviceMonitor` when they want -to probe, list and monitor devices of a specific type. The -`DeviceMonitor` will create the appropriate -`DeviceProvider` objects and manage them. It will then post -messages on its `Bus` for devices that have been added and -removed. - -The device monitor will monitor all devices matching the filters that -the application has set. - -The basic use pattern of a device monitor is as follows: - -```text - static gboolean - my_bus_func (GstBus * bus, GstMessage * message, gpointer user_data) - { - GstDevice *device; - gchar *name; - - switch (GST_MESSAGE_TYPE (message)) { - case GST_MESSAGE_DEVICE_ADDED: - gst_message_parse_device_added (message, &device); - name = gst_device_get_display_name (device); - g_print("Device added: %s\n", name); - g_free (name); - gst_object_unref (device); - break; - case GST_MESSAGE_DEVICE_REMOVED: - gst_message_parse_device_removed (message, &device); - name = gst_device_get_display_name (device); - g_print("Device removed: %s\n", name); - g_free (name); - gst_object_unref (device); - break; - default: - break; - } - - return G_SOURCE_CONTINUE; - } - - GstDeviceMonitor * - setup_raw_video_source_device_monitor (void) { - GstDeviceMonitor *monitor; - GstBus *bus; - GstCaps *caps; - - monitor = gst_device_monitor_new (); - - bus = gst_device_monitor_get_bus (monitor); - gst_bus_add_watch (bus, my_bus_func, NULL); - gst_object_unref (bus); - - caps = gst_caps_new_empty_simple ("video/x-raw"); - gst_device_monitor_add_filter (monitor, "Video/Source", caps); - gst_caps_unref (caps); - - gst_device_monitor_start (monitor); - - return monitor; - } -``` - -# Implements - -[`DeviceMonitorExt`](trait@crate::DeviceMonitorExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`DeviceMonitorExtManual`](trait@crate::DeviceMonitorExtManual) - -Trait containing all `DeviceMonitor` methods. - -# Implementors - -[`DeviceMonitor`](struct@crate::DeviceMonitor) - -Create a new `DeviceMonitor` - -# Returns - -a new device monitor. - -Adds a filter for which `Device` will be monitored, any device that matches -all these classes and the `Caps` will be returned. - -If this function is called multiple times to add more filters, each will be -matched independently. That is, adding more filters will not further restrict -what devices are matched. - -The `Caps` supported by the device as returned by `DeviceExt::get_caps` are -not intersected with caps filters added using this function. - -Filters must be added before the `DeviceMonitor` is started. -## `classes` -device classes to use as filter or `None` for any class -## `caps` -the `Caps` to filter or `None` for ANY - -# Returns - -The id of the new filter or 0 if no provider matched the filter's - classes. - -Gets the `Bus` of this `DeviceMonitor` - -# Returns - -a `Bus` - -Gets a list of devices from all of the relevant monitors. This may actually -probe the hardware if the monitor is not currently started. - -# Returns - -a `glib::List` of - `Device` - -Get a list of the currently selected device provider factories. - -This - -# Returns - - - 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 currently showing all devices, even those from hidden -providers. - -# Returns - -`true` when all devices will be shown. - -Removes a filter from the `DeviceMonitor` using the id that was returned -by `DeviceMonitor::add_filter`. -## `filter_id` -the id of the filter - -# Returns - -`true` of the filter id was valid, `false` otherwise - -Set if all devices should be visible, even those devices from hidden -providers. Setting `show_all` to true might show some devices multiple times. -## `show_all` -show all devices - -Starts monitoring the devices, one this has succeeded, the -`MessageType::DeviceAdded` and `MessageType::DeviceRemoved` messages -will be emitted on the bus when the list of devices changes. - -# Returns - -`true` if the device monitoring could be started - -Stops monitoring the devices. - -A `DeviceProvider` subclass is provided by a plugin that handles devices -if there is a way to programmatically list connected devices. It can also -optionally provide updates to the list of connected devices. - -Each `DeviceProvider` subclass is a singleton, a plugin should -normally provide a single subclass for all devices. - -Applications would normally use a `DeviceMonitor` to monitor devices -from all relevant providers. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`DeviceProviderExt`](trait@crate::DeviceProviderExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`DeviceProviderExtManual`](trait@crate::DeviceProviderExtManual) - -Trait containing all `DeviceProvider` methods. - -# Implementors - -[`DeviceProvider`](struct@crate::DeviceProvider) - -Create a new device providerfactory capable of instantiating objects of the -`type_` and add the factory to `plugin`. -## `plugin` -`Plugin` to register the device provider with, or `None` for - a static device provider. -## `name` -name of device providers of this type -## `rank` -rank of device provider (higher rank means more importance when autoplugging) -## `type_` -GType of device provider to register - -# Returns - -`true`, if the registering succeeded, `false` on error - -Posts a message on the provider's `Bus` to inform applications that -a new device has been added. - -This is for use by subclasses. - -`device`'s reference count will be incremented, and any floating reference -will be removed (see `Object::ref_sink`). -## `device` -a `Device` that has been added - -This function is used when `changed_device` was modified into its new form -`device`. This will post a `DEVICE_CHANGED` message on the bus to let -the application know that the device was modified. `Device` is immutable -for MT. safety purposes so this is an "atomic" way of letting the application -know when a device was modified. - -Feature: `v1_16` - -## `device` -the new version of `changed_device` -## `changed_device` -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. - -This is for use by subclasses. -## `device` -a `Device` that has been removed - -Gets the `Bus` of this `DeviceProvider` - -# Returns - -a `Bus` - -Gets a list of devices that this provider understands. This may actually -probe the hardware if the provider is not currently started. - -If the provider has been started, this will returned the same `Device` -objedcts that have been returned by the `MessageType::DeviceAdded` messages. - -# Returns - -a `glib::List` of - `Device` - -Retrieves the factory that was used to create this device provider. - -# Returns - -the `DeviceProviderFactory` used for - creating this device provider. no refcounting is needed. - -Get the provider factory names of the `DeviceProvider` instances that -are hidden by `self`. - -# Returns - - - a list of hidden providers factory names or `None` when - nothing is hidden by `self`. Free with g_strfreev. - -Get metadata with `key` in `self`. - -Feature: `v1_14` - -## `key` -the key to get - -# Returns - -the metadata for `key`. - -Make `self` hide the devices from the factory with `name`. - -This function is used when `self` will also provide the devices reported -by provider factory `name`. A monitor should stop monitoring the -device provider with `name` to avoid duplicate devices. -## `name` -a provider factory name - -Starts providering the devices. This will cause `MessageType::DeviceAdded` -and `MessageType::DeviceRemoved` messages to be posted on the provider's bus -when devices are added or removed from the system. - -Since the `DeviceProvider` is a singleton, -`DeviceProviderExt::start` may already have been called by another -user of the object, `DeviceProviderExt::stop` needs to be called the same -number of times. - -After this function has been called, `DeviceProviderExt::get_devices` will -return the same objects that have been received from the -`MessageType::DeviceAdded` messages and will no longer probe. - -# Returns - -`true` if the device providering could be started - -Decreases the use-count by one. If the use count reaches zero, this -`DeviceProvider` will stop providering the devices. This needs to be -called the same number of times that `DeviceProviderExt::start` was called. - -Make `self` unhide the devices from factory `name`. - -This function is used when `self` will no longer provide the devices -reported by provider factory `name`. A monitor should start -monitoring the devices from provider factory `name` in order to see -all devices again. -## `name` -a provider factory name - -`DeviceProviderFactory` is used to create instances of device providers. A -GstDeviceProviderfactory can be added to a `Plugin` as it is also a -`PluginFeature`. - -Use the `DeviceProviderFactory::find` and -`DeviceProviderFactory::get` functions to create device -provider instances or use `DeviceProviderFactory::get_by_name` as a -convenient shortcut. - -# Implements - -[`PluginFeatureExt`](trait@crate::PluginFeatureExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`PluginFeatureExtManual`](trait@crate::PluginFeatureExtManual) - -Search for an device provider factory of the given name. Refs the returned -device provider factory; caller is responsible for unreffing. -## `name` -name of factory to find - -# Returns - -`DeviceProviderFactory` if -found, `None` otherwise - -Returns the device provider of the type defined by the given device -provider factory. -## `factoryname` -a named factory to instantiate - -# Returns - -a `DeviceProvider` or `None` -if unable to create device provider - -Get a list of factories with a rank greater or equal to `minrank`. -The list of factories is returned by decreasing rank. -## `minrank` -Minimum rank - -# Returns - - -a `glib::List` of `DeviceProviderFactory` device providers. Use -`PluginFeature::list_free` after usage. - -Returns the device provider of the type defined by the given device -providerfactory. - -# Returns - -the `DeviceProvider` or `None` -if the device provider couldn't be created - -Get the `glib::Type` for device providers managed by this factory. The type can -only be retrieved if the device provider factory is loaded, which can be -assured with `PluginFeature::load`. - -# Returns - -the `glib::Type` for device providers managed by this factory. - -Get the metadata on `self` with `key`. -## `key` -a key - -# Returns - -the metadata with `key` on `self` or `None` -when there was no metadata with the given `key`. - -Get the available keys for the metadata on `self`. - -# Returns - - -a `None`-terminated array of key strings, or `None` when there is no -metadata. Free with `g_strfreev` when no longer needed. - -Check if `self` matches all of the given `classes` -## `classes` -a "/" separate list of classes to match, only match - if all classes are matched - -# Returns - -`true` if `self` matches or if `classes` is `None`. - -Check if `self` matches all of the given classes -## `classes` -a `None` terminated array - of classes to match, only match if all classes are matched - -# Returns - -`true` if `self` matches. - -GstElement is the abstract base class needed to construct an element that -can be used in a GStreamer pipeline. Please refer to the plugin writers -guide for more information on creating `Element` subclasses. - -The name of a `Element` can be get with `gst_element_get_name` and set with -`gst_element_set_name`. For speed, GST_ELEMENT_NAME() can be used in the -core when using the appropriate locking. Do not use this in plug-ins or -applications in order to retain ABI compatibility. - -Elements can have pads (of the type `Pad`). These pads link to pads on -other elements. `Buffer` flow between these linked pads. -A `Element` has a `glib::List` of `Pad` structures for all their input (or sink) -and output (or source) pads. -Core and plug-in writers can add and remove pads with `ElementExt::add_pad` -and `ElementExt::remove_pad`. - -An existing pad of an element can be retrieved by name with -`ElementExt::get_static_pad`. A new dynamic pad can be created using -`ElementExt::request_pad` with a `PadTemplate`. -An iterator of all pads can be retrieved with `ElementExt::iterate_pads`. - -Elements can be linked through their pads. -If the link is straightforward, use the `ElementExt::link` -convenience function to link two elements, or `ElementExt::link_many` -for more elements in a row. -Use `ElementExt::link_filtered` to link two elements constrained by -a specified set of `Caps`. -For finer control, use `ElementExt::link_pads` and -`ElementExt::link_pads_filtered` to specify the pads to link on -each element by name. - -Each element has a state (see `State`). You can get and set the state -of an element with `Element::get_state` and `Element::set_state`. -Setting a state triggers a `StateChange`. To get a string representation -of a `State`, use `Element::state_get_name`. - -You can get and set a `Clock` on an element using `ElementExt::get_clock` -and `ElementExt::set_clock`. -Some elements can provide a clock for the pipeline if -the `ElementFlags::ProvideClock` flag is set. With the -`ElementExt::provide_clock` method one can retrieve the clock provided by -such an element. -Not all elements require a clock to operate correctly. If the -`ElementFlags::RequireClock`() flag is set, a clock should be set on the -element with `ElementExt::set_clock`. - -Note that clock selection and distribution is normally handled by the -toplevel `Pipeline` so the clock functions are only to be used in very -specific situations. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`ElementExt`](trait@crate::ElementExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`ElementExtManual`](trait@crate::ElementExtManual) - -Trait containing all `Element` methods. - -# Implementors - -[`Bin`](struct@crate::Bin), [`Element`](struct@crate::Element), [`TagSetter`](struct@crate::TagSetter), [`TocSetter`](struct@crate::TocSetter) - -Creates an element for handling the given URI. -## `type_` -Whether to create a source or a sink -## `uri` -URI to create an element for -## `elementname` -Name of created element, can be `None`. - -# Returns - -a new element or `None` if none -could be created - -Create a new elementfactory capable of instantiating objects of the -`type_` and add the factory to `plugin`. -## `plugin` -`Plugin` to register the element with, or `None` for - a static element. -## `name` -name of elements of this type -## `rank` -rank of element (higher rank means more importance when autoplugging) -## `type_` -GType of element to register - -# Returns - -`true`, if the registering succeeded, `false` on error - -Gets a string representing the given state change result. -## `state_ret` -a `StateChangeReturn` to get the name of. - -# Returns - -a string with the name of the state - result. - -Gets a string representing the given state. -## `state` -a `State` to get the name of. - -# Returns - -a string with the name of the state. - -Abort the state change of the element. This function is used -by elements that do asynchronous state changes and find out -something is wrong. - -This function should be called with the STATE_LOCK held. - -MT safe. - -Adds a pad (link point) to `self`. `pad`'s parent will be set to `self`; -see `GstObjectExt::set_parent` for refcounting information. - -Pads are automatically activated when added in the PAUSED or PLAYING -state. - -The pad and the element should be unlocked when calling this function. - -This function will emit the `Element::pad-added` signal on the element. -## `pad` -the `Pad` to add to the element. - -# Returns - -`true` if the pad could be added. This function can fail when -a pad with the same name already existed or the pad already had another -parent. - -MT safe. - - -Feature: `v1_10` - -## `property_name` -name of property to watch for changes, or - NULL to watch all properties -## `include_value` -whether to include the new property value in the message - -# Returns - -a watch id, which can be used in connection with - `Element::remove_property_notify_watch` to remove the watch again. - - -Feature: `v1_10` - -## `property_name` -name of property to watch for changes, or - NULL to watch all properties -## `include_value` -whether to include the new property value in the message - -# Returns - -a watch id, which can be used in connection with - `Element::remove_property_notify_watch` to remove the watch again. - -Calls `func` from another thread and passes `user_data` to it. This is to be -used for cases when a state change has to be performed from a streaming -thread, directly via `Element::set_state` or indirectly e.g. via SEEK -events. - -Calling those functions directly from the streaming thread will cause -deadlocks in many situations, as they might involve waiting for the -streaming thread to shut down from this very streaming thread. - -MT safe. - -Feature: `v1_10` - -## `func` -Function to call asynchronously from another thread -## `user_data` -Data to pass to `func` -## `destroy_notify` -GDestroyNotify for `user_data` - -Perform `transition` on `self`. - -This function must be called with STATE_LOCK held and is mainly used -internally. -## `transition` -the requested transition - -# Returns - -the `StateChangeReturn` of the state transition. - -Commit the state change of the element and proceed to the next -pending state if any. This function is used -by elements that do asynchronous state changes. -The core will normally call this method automatically when an -element returned `StateChangeReturn::Success` from the state change function. - -If after calling this method the element still has not reached -the pending state, the next state change is performed. - -This method is used internally and should normally not be called by plugins -or applications. - -This function must be called with STATE_LOCK held. -## `ret` -The previous state return value - -# Returns - -The result of the commit state change. - -MT safe. - -Creates a pad for each pad template that is always available. -This function is only useful during object initialization of -subclasses of `Element`. - -Call `func` with `user_data` for each of `self`'s pads. `func` will be called -exactly once for each pad that exists at the time of this call, unless -one of the calls to `func` returns `false` in which case we will stop -iterating pads and return early. If new pads are added or pads are removed -while pads are being iterated, this will not be taken into account until -next time this function is used. - -Feature: `v1_14` - -## `func` -function to call for each pad -## `user_data` -user data passed to `func` - -# Returns - -`false` if `self` had no pads or if one of the calls to `func` - returned `false`. - -Call `func` with `user_data` for each of `self`'s sink pads. `func` will be -called exactly once for each sink pad that exists at the time of this call, -unless one of the calls to `func` returns `false` in which case we will stop -iterating pads and return early. If new sink pads are added or sink pads -are removed while the sink pads are being iterated, this will not be taken -into account until next time this function is used. - -Feature: `v1_14` - -## `func` -function to call for each sink pad -## `user_data` -user data passed to `func` - -# Returns - -`false` if `self` had no sink pads or if one of the calls to `func` - returned `false`. - -Call `func` with `user_data` for each of `self`'s source pads. `func` will be -called exactly once for each source pad that exists at the time of this call, -unless one of the calls to `func` returns `false` in which case we will stop -iterating pads and return early. If new source pads are added or source pads -are removed while the source pads are being iterated, this will not be taken -into account until next time this function is used. - -Feature: `v1_14` - -## `func` -function to call for each source pad -## `user_data` -user data passed to `func` - -# Returns - -`false` if `self` had no source pads or if one of the calls - to `func` returned `false`. - -Returns the base time of the element. The base time is the -absolute time of the clock when this element was last put to -PLAYING. Subtracting the base time from the clock time gives -the running time of the element. - -# Returns - -the base time of the element. - -MT safe. - -Returns the bus of the element. Note that only a `Pipeline` will provide a -bus for the application. - -# Returns - -the element's `Bus`. unref after -usage. - -MT safe. - -Gets the currently configured clock of the element. This is the clock as was -last set with `ElementExt::set_clock`. - -Elements in a pipeline will only have their clock set when the -pipeline is in the PLAYING state. - -# Returns - -the `Clock` of the element. unref after usage. - -MT safe. - -Looks for an unlinked pad to which the given pad can link. It is not -guaranteed that linking the pads will work, though it should work in most -cases. - -This function will first attempt to find a compatible unlinked ALWAYS pad, -and if none can be found, it will request a compatible REQUEST pad by looking -at the templates of `self`. -## `pad` -the `Pad` to find a compatible one for. -## `caps` -the `Caps` to use as a filter. - -# Returns - -the `Pad` to which a link - can be made, or `None` if one cannot be found. `GstObjectExt::unref` - after usage. - -Retrieves a pad template from `self` that is compatible with `compattempl`. -Pads from compatible templates can be linked together. -## `compattempl` -the `PadTemplate` to find a compatible - template for - -# Returns - -a compatible `PadTemplate`, - or `None` if none was found. No unreferencing is necessary. - -Gets the context with `context_type` set on the element or NULL. - -MT safe. -## `context_type` -a name of a context to retrieve - -# Returns - -A `Context` or NULL - -Gets the context with `context_type` set on the element or NULL. -## `context_type` -a name of a context to retrieve - -# Returns - -A `Context` or NULL - -Gets the contexts set on the element. - -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. - -# Returns - -the `ElementFactory` used for creating this - element or `None` if element has not been registered (static element). no refcounting is needed. - -Get metadata with `key` in `klass`. - -Feature: `v1_14` - -## `key` -the key to get - -# Returns - -the metadata for `key`. - -Retrieves a padtemplate from `self` with the given name. - -Feature: `v1_14` - -## `name` -the name of the `PadTemplate` to get. - -# Returns - -the `PadTemplate` with the - given name, or `None` if none was found. No unreferencing is - necessary. - -Retrieves a list of the pad templates associated with `self`. The -list must not be modified by the calling code. - -Feature: `v1_14` - - -# Returns - -the `glib::List` of - pad templates. - -Retrieves a pad from the element by name (e.g. "src_\%d"). This version only -retrieves request pads. The pad should be released with -`ElementExt::release_request_pad`. - -This method is slower than manually getting the pad template and calling -`ElementExt::request_pad` if the pads should have a specific name (e.g. -`name` is "src_1" instead of "src_\%u"). -## `name` -the name of the request `Pad` to retrieve. - -# Returns - -requested `Pad` if found, - otherwise `None`. Release after usage. - -Returns the start time of the element. The start time is the -running time of the clock when this element was last put to PAUSED. - -Usually the start_time is managed by a toplevel element such as -`Pipeline`. - -MT safe. - -# Returns - -the start time of the element. - -Gets the state of the element. - -For elements that performed an ASYNC state change, as reported by -`Element::set_state`, this function will block up to the -specified timeout value for the state change to complete. -If the element completes the state change or goes into -an error, this function returns immediately with a return value of -`StateChangeReturn::Success` or `StateChangeReturn::Failure` respectively. - -For elements that did not return `StateChangeReturn::Async`, this function -returns the current and pending state immediately. - -This function returns `StateChangeReturn::NoPreroll` if the element -successfully changed its state but is not able to provide data yet. -This mostly happens for live sources that only produce data in -`State::Playing`. While the state change return is equivalent to -`StateChangeReturn::Success`, it is returned to the application to signal that -some sink elements might not be able to complete their state change because -an element is not producing data to complete the preroll. When setting the -element to playing, the preroll will complete and playback will start. -## `state` -a pointer to `State` to hold the state. - Can be `None`. -## `pending` -a pointer to `State` to hold the pending - state. Can be `None`. -## `timeout` -a `ClockTime` to specify the timeout for an async - state change or `GST_CLOCK_TIME_NONE` for infinite timeout. - -# Returns - -`StateChangeReturn::Success` if the element has no more pending state - and the last state change succeeded, `StateChangeReturn::Async` if the - element is still performing a state change or - `StateChangeReturn::Failure` if the last state change failed. - -MT safe. - -Retrieves a pad from `self` by name. This version only retrieves -already-existing (i.e. 'static') pads. -## `name` -the name of the static `Pad` to retrieve. - -# Returns - -the requested `Pad` if - found, otherwise `None`. unref after usage. - -MT safe. - -Checks if the state of an element is locked. -If the state of an element is locked, state changes of the parent don't -affect the element. -This way you can leave currently unused elements inside bins. Just lock their -state before changing the state from `State::Null`. - -MT safe. - -# Returns - -`true`, if the element's state is locked. - -Retrieves an iterator of `self`'s pads. The iterator should -be freed after usage. Also more specialized iterators exists such as -`ElementExt::iterate_src_pads` or `ElementExt::iterate_sink_pads`. - -The order of pads returned by the iterator will be the order in which -the pads were added to the element. - -# Returns - -the `Iterator` of `Pad`. - -MT safe. - -Retrieves an iterator of `self`'s sink pads. - -The order of pads returned by the iterator will be the order in which -the pads were added to the element. - -# Returns - -the `Iterator` of `Pad`. - -MT safe. - -Retrieves an iterator of `self`'s source pads. - -The order of pads returned by the iterator will be the order in which -the pads were added to the element. - -# Returns - -the `Iterator` of `Pad`. - -MT safe. - -Links `self` to `dest`. The link must be from source to -destination; the other direction will not be tried. The function looks for -existing pads that aren't linked yet. It will request new pads if necessary. -Such pads need to be released manually when unlinking. -If multiple links are possible, only one is established. - -Make sure you have added your elements to a bin or pipeline with -`GstBinExt::add` before trying to link them. -## `dest` -the `Element` containing the destination pad. - -# Returns - -`true` if the elements could be linked, `false` otherwise. - -Links `self` to `dest` using the given caps as filtercaps. -The link must be from source to -destination; the other direction will not be tried. The function looks for -existing pads that aren't linked yet. It will request new pads if necessary. -If multiple links are possible, only one is established. - -Make sure you have added your elements to a bin or pipeline with -`GstBinExt::add` before trying to link them. -## `dest` -the `Element` containing the destination pad. -## `filter` -the `Caps` to filter the link, - or `None` for no filter. - -# Returns - -`true` if the pads could be linked, `false` otherwise. - -Chain together a series of elements. Uses `ElementExt::link`. -Make sure you have added your elements to a bin or pipeline with -`GstBinExt::add` before trying to link them. -## `element_2` -the second `Element` in the link chain. - -# Returns - -`true` on success, `false` otherwise. - -Links the two named pads of the source and destination elements. -Side effect is that if one of the pads has no parent, it becomes a -child of the parent of the other element. If they have different -parents, the link fails. -## `srcpadname` -the name of the `Pad` in source element - or `None` for any pad. -## `dest` -the `Element` containing the destination pad. -## `destpadname` -the name of the `Pad` in destination element, -or `None` for any pad. - -# Returns - -`true` if the pads could be linked, `false` otherwise. - -Links the two named pads of the source and destination elements. Side effect -is that if one of the pads has no parent, it becomes a child of the parent of -the other element. If they have different parents, the link fails. If `caps` -is not `None`, makes sure that the caps of the link is a subset of `caps`. -## `srcpadname` -the name of the `Pad` in source element - or `None` for any pad. -## `dest` -the `Element` containing the destination pad. -## `destpadname` -the name of the `Pad` in destination element - or `None` for any pad. -## `filter` -the `Caps` to filter the link, - or `None` for no filter. - -# Returns - -`true` if the pads could be linked, `false` otherwise. - -Links the two named pads of the source and destination elements. -Side effect is that if one of the pads has no parent, it becomes a -child of the parent of the other element. If they have different -parents, the link fails. - -Calling `ElementExt::link_pads_full` with `flags` == `PadLinkCheck::Default` -is the same as calling `ElementExt::link_pads` and the recommended way of -linking pads with safety checks applied. - -This is a convenience function for `Pad::link_full`. -## `srcpadname` -the name of the `Pad` in source element - or `None` for any pad. -## `dest` -the `Element` containing the destination pad. -## `destpadname` -the name of the `Pad` in destination element, -or `None` for any pad. -## `flags` -the `PadLinkCheck` to be performed when linking pads. - -# Returns - -`true` if the pads could be linked, `false` otherwise. - -Brings the element to the lost state. The current state of the -element is copied to the pending state so that any call to -`Element::get_state` will return `StateChangeReturn::Async`. - -An ASYNC_START message is posted. If the element was PLAYING, it will -go to PAUSED. The element will be restored to its PLAYING state by -the parent pipeline when it prerolls again. - -This is mostly used for elements that lost their preroll buffer -in the `State::Paused` or `State::Playing` state after a flush, -they will go to their pending state again when a new preroll buffer is -queued. This function can only be called when the element is currently -not in error or an async state change. - -This function is used internally and should normally not be called from -plugins or applications. - -Post an error, warning or info message on the bus from inside an element. - -`type_` must be of `MessageType::Error`, `MessageType::Warning` or -`MessageType::Info`. - -MT safe. -## `type_` -the `MessageType` -## `domain` -the GStreamer GError domain this message belongs to -## `code` -the GError code belonging to the domain -## `text` -an allocated text string to be used - as a replacement for the default message connected to code, - or `None` -## `debug` -an allocated debug message to be - used as a replacement for the default debugging information, - or `None` -## `file` -the source code file where the error was generated -## `function` -the source code function where the error was generated -## `line` -the source code line where the error was generated - -Post an error, warning or info message on the bus from inside an element. - -`type_` must be of `MessageType::Error`, `MessageType::Warning` or -`MessageType::Info`. - -Feature: `v1_10` - -## `type_` -the `MessageType` -## `domain` -the GStreamer GError domain this message belongs to -## `code` -the GError code belonging to the domain -## `text` -an allocated text string to be used - as a replacement for the default message connected to code, - or `None` -## `debug` -an allocated debug message to be - used as a replacement for the default debugging information, - or `None` -## `file` -the source code file where the error was generated -## `function` -the source code function where the error was generated -## `line` -the source code line where the error was generated -## `structure` -optional details structure - -Use this function to signal that the element does not expect any more pads -to show up in the current pipeline. This function should be called whenever -pads have been added by the element itself. Elements with `PadPresence::Sometimes` -pad templates use this in combination with autopluggers to figure out that -the element is done initializing its pads. - -This function emits the `Element::no-more-pads` signal. - -MT safe. - -Post a message on the element's `Bus`. This function takes ownership of the -message; if you want to access the message after this call, you should add an -additional reference before calling. -## `message` -a `Message` to post - -# Returns - -`true` if the message was successfully posted. The function returns -`false` if the element did not have a bus. - -MT safe. - -Get the clock provided by the given element. -> An element is only required to provide a clock in the PAUSED -> state. Some elements can provide a clock in other states. - -# Returns - -the GstClock provided by the -element or `None` if no clock could be provided. Unref after usage. - -MT safe. - -Performs a query on the given element. - -For elements that don't implement a query handler, this function -forwards the query to a random srcpad or to the peer of a -random linked sinkpad of this element. - -Please note that some queries might need a running pipeline to work. -## `query` -the `Query`. - -# Returns - -`true` if the query could be performed. - -MT safe. - -Queries an element to convert `src_val` in `src_format` to `dest_format`. -## `src_format` -a `Format` to convert from. -## `src_val` -a value to convert. -## `dest_format` -the `Format` to convert to. -## `dest_val` -a pointer to the result. - -# Returns - -`true` if the query could be performed. - -Queries an element (usually top-level pipeline or playbin element) for the -total stream duration in nanoseconds. This query will only work once the -pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application -will receive an ASYNC_DONE message on the pipeline bus when that is the case. - -If the duration changes for some reason, you will get a DURATION_CHANGED -message on the pipeline bus, in which case you should re-query the duration -using this function. -## `format` -the `Format` requested -## `duration` -A location in which to store the total duration, or `None`. - -# Returns - -`true` if the query could be performed. - -Queries an element (usually top-level pipeline or playbin element) for the -stream position in nanoseconds. This will be a value between 0 and the -stream duration (if the stream duration is known). This query will usually -only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING -state). The application will receive an ASYNC_DONE message on the pipeline -bus when that is the case. - -If one repeatedly calls this function one can also create a query and reuse -it in `Element::query`. -## `format` -the `Format` requested -## `cur` -a location in which to store the current - position, or `None`. - -# Returns - -`true` if the query could be performed. - -Makes the element free the previously requested pad as obtained -with `ElementExt::request_pad`. - -This does not unref the pad. If the pad was created by using -`ElementExt::request_pad`, `ElementExt::release_request_pad` needs to be -followed by `GstObjectExt::unref` to free the `pad`. - -MT safe. -## `pad` -the `Pad` to release. - -Removes `pad` from `self`. `pad` will be destroyed if it has not been -referenced elsewhere using `GstObjectExt::unparent`. - -This function is used by plugin developers and should not be used -by applications. Pads that were dynamically requested from elements -with `ElementExt::request_pad` should be released with the -`ElementExt::release_request_pad` function instead. - -Pads are not automatically deactivated so elements should perform the needed -steps to deactivate the pad in case this pad is removed in the PAUSED or -PLAYING state. See `PadExt::set_active` for more information about -deactivating pads. - -The pad and the element should be unlocked when calling this function. - -This function will emit the `Element::pad-removed` signal on the element. -## `pad` -the `Pad` to remove from the element. - -# Returns - -`true` if the pad could be removed. Can return `false` if the -pad does not belong to the provided element. - -MT safe. - - -Feature: `v1_10` - -## `watch_id` -watch id to remove - -Retrieves a request pad from the element according to the provided template. -Pad templates can be looked up using -`ElementFactory::get_static_pad_templates`. - -The pad should be released with `ElementExt::release_request_pad`. -## `templ` -a `PadTemplate` of which we want a pad of. -## `name` -the name of the request `Pad` -to retrieve. Can be `None`. -## `caps` -the caps of the pad we want to -request. Can be `None`. - -# Returns - -requested `Pad` if found, - otherwise `None`. Release after usage. - -Sends a seek event to an element. See `Event::new_seek` for the details of -the parameters. The seek event is sent to the element using -`Element::send_event`. - -MT safe. -## `rate` -The new playback rate -## `format` -The format of the seek values -## `flags` -The optional seek flags. -## `start_type` -The type and flags for the new start position -## `start` -The value of the new start position -## `stop_type` -The type and flags for the new stop position -## `stop` -The value of the new stop position - -# Returns - -`true` if the event was handled. Flushing seeks will trigger a -preroll, which will emit `MessageType::AsyncDone`. - -Simple API to perform a seek on the given element, meaning it just seeks -to the given position relative to the start of the stream. For more complex -operations like segment seeks (e.g. for looping) or changing the playback -rate or seeking relative to the last configured playback segment you should -use `Element::seek`. - -In a completely prerolled PAUSED or PLAYING pipeline, seeking is always -guaranteed to return `true` on a seekable media type or `false` when the media -type is certainly not seekable (such as a live stream). - -Some elements allow for seeking in the READY state, in this -case they will store the seek event and execute it when they are put to -PAUSED. If the element supports seek in READY, it will always return `true` when -it receives the event in the READY state. -## `format` -a `Format` to execute the seek in, such as `Format::Time` -## `seek_flags` -seek options; playback applications will usually want to use - GST_SEEK_FLAG_FLUSH | GST_SEEK_FLAG_KEY_UNIT here -## `seek_pos` -position to seek to (relative to the start); if you are doing - a seek in `Format::Time` this value is in nanoseconds - - multiply with `GST_SECOND` to convert seconds to nanoseconds or - with `GST_MSECOND` to convert milliseconds to nanoseconds. - -# Returns - -`true` if the seek operation succeeded. Flushing seeks will trigger a -preroll, which will emit `MessageType::AsyncDone`. - -Sends an event to an element. If the element doesn't implement an -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. - -MT safe. -## `event` -the `Event` to send to the element. - -# Returns - -`true` if the event was handled. Events that trigger a preroll (such -as flushing seeks and steps) will emit `MessageType::AsyncDone`. - -Set the base time of an element. See `ElementExt::get_base_time`. - -MT safe. -## `time` -the base time to set. - -Sets the bus of the element. Increases the refcount on the bus. -For internal use only, unless you're testing elements. - -MT safe. -## `bus` -the `Bus` to set. - -Sets the clock for the element. This function increases the -refcount on the clock. Any previously set clock on the object -is unreffed. -## `clock` -the `Clock` to set for the element. - -# Returns - -`true` if the element accepted the clock. An element can refuse a -clock when it, for example, is not able to slave its internal clock to the -`clock` or when it requires a specific clock to operate. - -MT safe. - -Sets the context of the element. Increases the refcount of the context. - -MT safe. -## `context` -the `Context` to set. - -Locks the state of an element, so state changes of the parent don't affect -this element anymore. - -Note that this is racy if the state lock of the parent bin is not taken. -The parent bin might've just checked the flag in another thread and as the -next step proceed to change the child element's state. - -MT safe. -## `locked_state` -`true` to lock the element's state - -# Returns - -`true` if the state was changed, `false` if bad parameters were given -or the elements state-locking needed no change. - -Set the start time of an element. The start time of the element is the -running time of the element when it last went to the PAUSED state. In READY -or after a flushing seek, it is set to 0. - -Toplevel elements like `Pipeline` will manage the start_time and -base_time on its children. Setting the start_time to `GST_CLOCK_TIME_NONE` -on such a toplevel element will disable the distribution of the base_time to -the children and can be useful if the application manages the base_time -itself, for example if you want to synchronize capture from multiple -pipelines, and you can also ensure that the pipelines have the same clock. - -MT safe. -## `time` -the base time to set. - -Sets the state of the element. This function will try to set the -requested state by going through all the intermediary states and calling -the class's state change function for each. - -This function can return `StateChangeReturn::Async`, in which case the -element will perform the remainder of the state change asynchronously in -another thread. -An application can use `Element::get_state` to wait for the completion -of the state change or it can wait for a `MessageType::AsyncDone` or -`MessageType::StateChanged` on the bus. - -State changes to `State::Ready` or `State::Null` never return -`StateChangeReturn::Async`. -## `state` -the element's new `State`. - -# Returns - -Result of the state change using `StateChangeReturn`. - -MT safe. - -Tries to change the state of the element to the same as its parent. -If this function returns `false`, the state of element is undefined. - -# Returns - -`true`, if the element's state could be synced to the parent's state. - -MT safe. - -Unlinks all source pads of the source element with all sink pads -of the sink element to which they are linked. - -If the link has been made using `ElementExt::link`, it could have created an -requestpad, which has to be released using `ElementExt::release_request_pad`. -## `dest` -the sink `Element` to unlink. - -Unlinks a series of elements. Uses `ElementExt::unlink`. -## `element_2` -the second `Element` in the link chain. - -Unlinks the two named pads of the source and destination elements. - -This is a convenience function for `PadExt::unlink`. -## `srcpadname` -the name of the `Pad` in source element. -## `dest` -a `Element` containing the destination pad. -## `destpadname` -the name of the `Pad` in destination element. - -This signals that the element will not generate more dynamic pads. -Note that this signal will usually be emitted from the context of -the streaming thread. - -a new `Pad` has been added to the element. Note that this signal will -usually be emitted from the context of the streaming thread. Also keep in -mind that if you add new elements to the pipeline in the signal handler -you will need to set them to the desired target state with -`Element::set_state` or `ElementExt::sync_state_with_parent`. -## `new_pad` -the pad that has been added - -a `Pad` has been removed from the element -## `old_pad` -the pad that has been removed - -`ElementFactory` is used to create instances of elements. A -GstElementFactory can be added to a `Plugin` as it is also a -`PluginFeature`. - -Use the `ElementFactory::find` and `ElementFactory::create` -functions to create element instances or use `ElementFactory::make` as a -convenient shortcut. - -The following code example shows you how to create a GstFileSrc element. - -## Using an element factory - -```C - #include <gst/gst.h> - - GstElement *src; - GstElementFactory *srcfactory; - - gst_init (&argc, &argv); - - srcfactory = gst_element_factory_find ("filesrc"); - g_return_if_fail (srcfactory != NULL); - src = gst_element_factory_create (srcfactory, "src"); - g_return_if_fail (src != NULL); - ... -``` - -# Implements - -[`PluginFeatureExt`](trait@crate::PluginFeatureExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`PluginFeatureExtManual`](trait@crate::PluginFeatureExtManual) - -Search for an element factory of the given name. Refs the returned -element factory; caller is responsible for unreffing. -## `name` -name of factory to find - -# Returns - -`ElementFactory` if found, -`None` otherwise - -Filter out all the elementfactories in `list` that can handle `caps` in -the given direction. - -If `subsetonly` is `true`, then only the elements whose pads templates -are a complete superset of `caps` will be returned. Else any element -whose pad templates caps can intersect with `caps` will be returned. -## `list` -a `glib::List` of - `ElementFactory` to filter -## `caps` -a `Caps` -## `direction` -a `PadDirection` to filter on -## `subsetonly` -whether to filter on caps subsets or not. - -# Returns - -a `glib::List` of - `ElementFactory` elements that match the given requisites. - Use `PluginFeature::list_free` after usage. - -Get a list of factories that match the given `type_`. Only elements -with a rank greater or equal to `minrank` will be returned. -The list of factories is returned by decreasing rank. -## `type_` -a `ElementFactoryListType` -## `minrank` -Minimum rank - -# Returns - -a `glib::List` of - `ElementFactory` elements. Use `PluginFeature::list_free` after - usage. - -Create a new element of the type defined by the given element factory. -If name is `None`, then the element will receive a guaranteed unique name, -consisting of the element factory name and a number. -If name is given, it will be given the name supplied. -## `factoryname` -a named factory to instantiate -## `name` -name of new element, or `None` to automatically create - a unique name - -# Returns - -new `Element` or `None` -if unable to create element - -Checks if the factory can sink all possible capabilities. -## `caps` -the caps to check - -# Returns - -`true` if the caps are fully compatible. - -Checks if the factory can sink any possible capability. -## `caps` -the caps to check - -# Returns - -`true` if the caps have a common subset. - -Checks if the factory can src all possible capabilities. -## `caps` -the caps to check - -# Returns - -`true` if the caps are fully compatible. - -Checks if the factory can src any possible capability. -## `caps` -the caps to check - -# Returns - -`true` if the caps have a common subset. - -Create a new element of the type defined by the given elementfactory. -It will be given the name supplied, since all elements require a name as -their first argument. -## `name` -name of new element, or `None` to automatically create - a unique name - -# Returns - -new `Element` or `None` - if the element couldn't be created - -Get the `glib::Type` for elements managed by this factory. The type can -only be retrieved if the element factory is loaded, which can be -assured with `PluginFeature::load`. - -# Returns - -the `glib::Type` for elements managed by this factory or 0 if -the factory is not loaded. - -Get the metadata on `self` with `key`. -## `key` -a key - -# Returns - -the metadata with `key` on `self` or `None` -when there was no metadata with the given `key`. - -Get the available keys for the metadata on `self`. - -# Returns - - -a `None`-terminated array of key strings, or `None` when there is no -metadata. Free with `g_strfreev` when no longer needed. - -Gets the number of pad_templates in this factory. - -# Returns - -the number of pad_templates - -Gets the `glib::List` of `StaticPadTemplate` for this factory. - -# Returns - -the - static pad templates - -Gets a `None`-terminated array of protocols this element supports or `None` if -no protocols are supported. You may not change the contents of the returned -array, as it is still owned by the element factory. Use `g_strdupv` to -make a copy of the protocol string array if you need to. - -# Returns - -the supported protocols - or `None` - -Gets the type of URIs the element supports or `URIType::Unknown` if none. - -# Returns - -type of URIs this element supports - -Check if `self` implements the interface with name `interfacename`. -## `interfacename` -an interface name - -# Returns - -`true` when `self` implement the interface. - -Check if `self` is of the given types. -## `type_` -a `ElementFactoryListType` - -# Returns - -`true` if `self` is of `type_`. - -The standard flags that an element may have. - -ignore state changes from parent - -the element is a sink - -the element is a source. - -the element can provide a clock - -the element requires a clock - -the element can use an index - -offset to define more flags - -The event class provides factory methods to construct events for sending -and functions to query (parse) received events. - -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. - -Events that have been received can be parsed with their respective -gst_event_parse_*() functions. It is valid to pass `None` for unwanted details. - -Events are passed between elements in parallel to the data stream. Some events -are serialized with buffers, others are not. Some events only travel downstream, -others only upstream. Some events can travel both upstream and downstream. - -The events are used to signal special conditions in the datastream such as -EOS (end of stream) or the start of a new stream-segment. -Events are also used to flush the pipeline of any pending data. - -Most of the event API is used inside plugins. Applications usually only -construct and use seek events. -To do that `Event::new_seek` is used to create a seek event. It takes -the needed parameters to specify seeking time and mode. - -```C - GstEvent *event; - gboolean result; - ... - // construct a seek event to play the media from second 2 to 5, flush - // the pipeline to decrease latency. - event = gst_event_new_seek (1.0, - GST_FORMAT_TIME, - GST_SEEK_FLAG_FLUSH, - GST_SEEK_TYPE_SET, 2 * GST_SECOND, - GST_SEEK_TYPE_SET, 5 * GST_SECOND); - ... - result = gst_element_send_event (pipeline, event); - if (!result) - g_warning ("seek failed"); - ... -``` - -Create a new buffersize event. The event is sent downstream and notifies -elements that they should provide a buffer of the specified dimensions. - -When the `async_` flag is set, a thread boundary is preferred. -## `format` -buffer format -## `minsize` -minimum buffer size -## `maxsize` -maximum buffer size -## `async_` -thread behavior - -# Returns - -a new `Event` - -Create a new CAPS event for `caps`. The caps event can only travel downstream -synchronized with the buffer flow and contains the format of the buffers -that will follow after the event. -## `caps` -a `Caps` - -# Returns - -the new CAPS event. - -Create a new custom-typed event. This can be used for anything not -handled by other event-specific functions to pass an event to another -element. - -Make sure to allocate an event type with the `GST_EVENT_MAKE_TYPE` macro, -assigning a free number and filling in the correct direction and -serialization flags. - -New custom events can also be created by subclassing the event type if -needed. -## `type_` -The type of the new event -## `structure` -the structure for the event. The event will - take ownership of the structure. - -# Returns - -the new custom event. - -Create a new EOS event. The eos event can only travel downstream -synchronized with the buffer flow. Elements that receive the EOS -event on a pad can return `FlowReturn::Eos` as a `FlowReturn` -when data after the EOS event arrives. - -The EOS event will travel down to the sink elements in the pipeline -which will then post the `MessageType::Eos` on the bus after they have -finished playing any buffered data. - -When all sinks have posted an EOS message, an EOS message is -forwarded to the application. - -The EOS event itself will not cause any state transitions of the pipeline. - -# Returns - -the new EOS event. - -Allocate a new flush start event. The flush start event can be sent -upstream and downstream and travels out-of-bounds with the dataflow. - -It marks pads as being flushing and will make them return -`FlowReturn::Flushing` when used for data flow with `Pad::push`, -`Pad::chain`, `Pad::get_range` and `Pad::pull_range`. -Any event (except a `EventType::FlushStop`) received -on a flushing pad will return `false` immediately. - -Elements should unlock any blocking functions and exit their streaming -functions as fast as possible when this event is received. - -This event is typically generated after a seek to flush out all queued data -in the pipeline so that the new media is played as soon as possible. - -# Returns - -a new flush start event. - -Allocate a new flush stop event. The flush stop event can be sent -upstream and downstream and travels serialized with the dataflow. -It is typically sent after sending a FLUSH_START event to make the -pads accept data again. - -Elements can process this event synchronized with the dataflow since -the preceding FLUSH_START event stopped the dataflow. - -This event is typically generated to complete a seek and to resume -dataflow. -## `reset_time` -if time should be reset - -# Returns - -a new flush stop event. - -Create a new GAP event. A gap event can be thought of as conceptually -equivalent to a buffer to signal that there is no data for a certain -amount of time. This is useful to signal a gap to downstream elements -which may wait for data, such as muxers or mixers or overlays, especially -for sparse streams such as subtitle streams. -## `timestamp` -the start time (pts) of the gap -## `duration` -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 -running time before synchronising against the clock. - -The latency is mostly used in live sinks and is always expressed in -the time format. -## `latency` -the new latency value - -# Returns - -a new `Event` - -Create a new navigation event from the given description. -## `structure` -description of the event. The event will take - ownership of the structure. - -# Returns - -a new `Event` - -Creates a new event containing information specific to a particular -protection system (uniquely identified by `system_id`), by which that -protection system can acquire key(s) to decrypt a protected stream. - -In order for a decryption element to decrypt media -protected using a specific system, it first needs all the -protection system specific information necessary to acquire the decryption -key(s) for that stream. The functions defined here enable this information -to be passed in events from elements that extract it -(e.g., ISOBMFF demuxers, MPEG DASH demuxers) to protection decrypter -elements that use it. - -Events containing protection system specific information are created using -`Event::new_protection`, and they can be parsed by downstream elements -using `Event::parse_protection`. - -In Common Encryption, protection system specific information may be located -within ISOBMFF files, both in movie (moov) boxes and movie fragment (moof) -boxes; it may also be contained in ContentProtection elements within MPEG -DASH MPDs. The events created by `Event::new_protection` contain data -identifying from which of these locations the encapsulated protection system -specific information originated. This origin information is required as -some protection systems use different encodings depending upon where the -information originates. - -The events returned by `Event::new_protection` are implemented -in such a way as to ensure that the most recently-pushed protection info -event of a particular `origin` and `system_id` will -be stuck to the output pad of the sending element. -## `system_id` -a string holding a UUID that uniquely -identifies a protection system. -## `data` -a `Buffer` holding protection system specific -information. The reference count of the buffer will be incremented by one. -## `origin` -a string indicating where the protection -information carried in the event was extracted from. The allowed values -of this string will depend upon the protection scheme. - -# Returns - -a `EventType::Protection` event, if successful; `None` -if unsuccessful. - -Allocate a new qos event with the given values. -The QOS event is generated in an element that wants an upstream -element to either reduce or increase its rate because of -high/low CPU load or other resource usage such as network performance or -throttling. Typically sinks generate these events for each buffer -they receive. - -`type_` indicates the reason for the QoS event. `QOSType::Overflow` is -used when a buffer arrived in time or when the sink cannot keep up with -the upstream datarate. `QOSType::Underflow` is when the sink is not -receiving buffers fast enough and thus has to drop late buffers. -`QOSType::Throttle` is used when the datarate is artificially limited -by the application, for example to reduce power consumption. - -`proportion` indicates the real-time performance of the streaming in the -element that generated the QoS event (usually the sink). The value is -generally computed based on more long term statistics about the streams -timestamps compared to the clock. -A value < 1.0 indicates that the upstream element is producing data faster -than real-time. A value > 1.0 indicates that the upstream element is not -producing data fast enough. 1.0 is the ideal `proportion` value. The -proportion value can safely be used to lower or increase the quality of -the element. - -`diff` is the difference against the clock in running time of the last -buffer that caused the element to generate the QOS event. A negative value -means that the buffer with `timestamp` arrived in time. A positive value -indicates how late the buffer with `timestamp` was. When throttling is -enabled, `diff` will be set to the requested throttling interval. - -`timestamp` is the timestamp of the last buffer that cause the element -to generate the QOS event. It is expressed in running time and thus an ever -increasing value. - -The upstream element can use the `diff` and `timestamp` values to decide -whether to process more buffers. For positive `diff`, all buffers with -timestamp <= `timestamp` + `diff` will certainly arrive late in the sink -as well. A (negative) `diff` value so that `timestamp` + `diff` would yield a -result smaller than 0 is not allowed. - -The application can use general event probes to intercept the QoS -event and implement custom application specific QoS handling. -## `type_` -the QoS type -## `proportion` -the proportion of the qos message -## `diff` -The time difference of the last Clock sync -## `timestamp` -The timestamp of the buffer - -# Returns - -a new QOS event. - -Create a new reconfigure event. The purpose of the reconfigure event is -to travel upstream and make elements renegotiate their caps or reconfigure -their buffer pools. This is useful when changing properties on elements -or changing the topology of the pipeline. - -# Returns - -a new `Event` - -Allocate a new seek event with the given parameters. - -The seek event configures playback of the pipeline between `start` to `stop` -at the speed given in `rate`, also called a playback segment. -The `start` and `stop` values are expressed in `format`. - -A `rate` of 1.0 means normal playback rate, 2.0 means double speed. -Negatives values means backwards playback. A value of 0.0 for the -rate is not allowed and should be accomplished instead by PAUSING the -pipeline. - -A pipeline has a default playback segment configured with a start -position of 0, a stop position of -1 and a rate of 1.0. The currently -configured playback segment can be queried with `QueryType::Segment`. - -`start_type` and `stop_type` specify how to adjust the currently configured -start and stop fields in playback segment. Adjustments can be made relative -or absolute to the last configured values. A type of `SeekType::None` -means that the position should not be updated. - -When the rate is positive and `start` has been updated, playback will start -from the newly configured start position. - -For negative rates, playback will start from the newly configured stop -position (if any). If the stop position is updated, it must be different from --1 (`GST_CLOCK_TIME_NONE`) for negative rates. - -It is not possible to seek relative to the current playback position, to do -this, PAUSE the pipeline, query the current playback position with -`QueryType::Position` and update the playback segment current position with a -`SeekType::Set` to the desired position. -## `rate` -The new playback rate -## `format` -The format of the seek values -## `flags` -The optional seek flags -## `start_type` -The type and flags for the new start position -## `start` -The value of the new start position -## `stop_type` -The type and flags for the new stop position -## `stop` -The value of the new stop position - -# Returns - -a new seek event. - -Create a new SEGMENT event for `segment`. The segment event can only travel -downstream synchronized with the buffer flow and contains timing information -and playback properties for the buffers that will follow. - -The segment event marks the range of buffers to be processed. All -data not within the segment range is not to be processed. This can be -used intelligently by plugins to apply more efficient methods of skipping -unneeded data. The valid range is expressed with the `start` and `stop` -values. - -The time value of the segment is used in conjunction with the start -value to convert the buffer timestamps into the stream time. This is -usually done in sinks to report the current stream_time. -`time` represents the stream_time of a buffer carrying a timestamp of -`start`. `time` cannot be -1. - -`start` cannot be -1, `stop` can be -1. If there -is a valid `stop` given, it must be greater or equal the `start`, including -when the indicated playback `rate` is < 0. - -The `applied_rate` value provides information about any rate adjustment that -has already been made to the timestamps and content on the buffers of the -stream. (`rate` * `applied_rate`) should always equal the rate that has been -requested for playback. For example, if an element has an input segment -with intended playback `rate` of 2.0 and applied_rate of 1.0, it can adjust -incoming timestamps and buffer content by half and output a segment event -with `rate` of 1.0 and `applied_rate` of 2.0 - -After a segment event, the buffer stream time is calculated with: - - time + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate) -## `segment` -a `Segment` - -# Returns - -the new SEGMENT event. - -Create a new segment-done event. This event is sent by elements that -finish playback of a segment as a result of a segment seek. -## `format` -The format of the position being done -## `position` -The position of the segment being done - -# Returns - -a new `Event` - -Allocate a new select-streams event. - -The select-streams event requests the specified `streams` to be activated. - -The list of `streams` corresponds to the "Stream ID" of each stream to be -activated. Those ID can be obtained via the `Stream` objects present -in `EventType::StreamStart`, `EventType::StreamCollection` or -`MessageType::StreamCollection`. - -Note: The list of `streams` can not be empty. - -Feature: `v1_10` - -## `streams` -the list of streams to -activate - -# Returns - -a new select-streams event or `None` in case of -an error (like an empty streams list). - -Create a new sink-message event. The purpose of the sink-message event is -to instruct a sink to post the message contained in the event synchronized -with the stream. - -`name` is used to store multiple sticky events on one pad. -## `name` -a name for the event -## `msg` -the `Message` to be posted - -# Returns - -a new `Event` - -Create a new step event. The purpose of the step event is to instruct a sink -to skip `amount` (expressed in `format`) of media. It can be used to implement -stepping through the video frame by frame or for doing fast trick modes. - -A rate of <= 0.0 is not allowed. Pause the pipeline, for the effect of rate -= 0.0 or first reverse the direction of playback using a seek event to get -the same effect as rate < 0.0. - -The `flush` flag will clear any pending data in the pipeline before starting -the step operation. - -The `intermediate` flag instructs the pipeline that this step operation is -part of a larger step operation. -## `format` -the format of `amount` -## `amount` -the amount of data to step -## `rate` -the step rate -## `flush` -flushing steps -## `intermediate` -intermediate steps - -# Returns - -a new `Event` - -Create a new STREAM_COLLECTION event. The stream collection event can only -travel downstream synchronized with the buffer flow. - -Source elements, demuxers and other elements that manage collections -of streams and post `StreamCollection` messages on the bus also send -this event downstream on each pad involved in the collection, so that -activation of a new collection can be tracked through the downstream -data flow. - -Feature: `v1_10` - -## `collection` -Active collection for this data flow - -# Returns - -the new STREAM_COLLECTION event. - -Create a new Stream Group Done event. The stream-group-done event can -only travel downstream synchronized with the buffer flow. Elements -that receive the event on a pad should handle it mostly like EOS, -and emit any data or pending buffers that would depend on more data -arriving and unblock, since there won't be any more data. - -This event is followed by EOS at some point in the future, and is -generally used when switching pads - to unblock downstream so that -new pads can be exposed before sending EOS on the existing pads. - -Feature: `v1_10` - -## `group_id` -the group id of the stream group which is ending - -# Returns - -the new stream-group-done event. - -Create a new STREAM_START event. The stream start event can only -travel downstream synchronized with the buffer flow. It is expected -to be the first event that is sent for a new stream. - -Source elements, demuxers and other elements that create new streams -are supposed to send this event as the first event of a new stream. It -should not be sent after a flushing seek or in similar situations -and is used to mark the beginning of a new logical stream. Elements -combining multiple streams must ensure that this event is only forwarded -downstream once and not for every single input stream. - -The `stream_id` should be a unique string that consists of the upstream -stream-id, / as separator and a unique stream-id for this specific -stream. A new stream-id should only be created for a stream if the upstream -stream is split into (potentially) multiple new streams, e.g. in a demuxer, -but not for every single element in the pipeline. -`PadExt::create_stream_id` or `PadExt::create_stream_id_printf` can be -used to create a stream-id. There are no particular semantics for the -stream-id, though it should be deterministic (to support stream matching) -and it might be used to order streams (besides any information conveyed by -stream flags). -## `stream_id` -Identifier for this stream - -# Returns - -the new STREAM_START event. - -Generates a metadata tag event from the given `taglist`. - -The scope of the taglist specifies if the taglist applies to the -complete medium or only to this specific stream. As the tag event -is a sticky event, elements should merge tags received from -upstream with a given scope with their own tags with the same -scope and create a new tag event from it. -## `taglist` -metadata list. The event will take ownership - of the taglist. - -# Returns - -a new `Event` - -Generate a TOC event from the given `toc`. The purpose of the TOC event is to -inform elements that some kind of the TOC was found. -## `toc` -`Toc` structure. -## `updated` -whether `toc` was updated or not. - -# Returns - -a new `Event`. - -Generate a TOC select event with the given `uid`. The purpose of the -TOC select event is to start playback based on the TOC's entry with the -given `uid`. -## `uid` -UID in the TOC to start playback from. - -# Returns - -a new `Event`. - -Parses a segment `self` and copies the `Segment` into the location -given by `segment`. -## `segment` -a pointer to a `Segment` - -Retrieve the accumulated running time offset of the event. - -Events passing through `GstPads` that have a running time -offset set via `PadExt::set_offset` will get their offset -adjusted according to the pad's offset. - -If the event contains any information that related to the -running time, this information will need to be updated -before usage with this offset. - -# Returns - -The event's running time offset - -MT safe. - -Retrieve the sequence number of a event. - -Events have ever-incrementing sequence numbers, which may also be set -explicitly via `Event::set_seqnum`. Sequence numbers are typically used to -indicate that a event corresponds to some other set of events or messages, -for example an EOS event corresponding to a SEEK event. It is considered good -practice to make this correspondence when possible, though it is not -required. - -Note that events and messages share the same sequence number incrementor; -two events or messages will never have the same sequence number unless -that correspondence was made explicitly. - -# Returns - -The event's sequence number. - -MT safe. - -Access the structure of the event. - -# Returns - -The structure of the event. The -structure is still owned by the event, which means that you should not free -it and that the pointer becomes invalid when you free the event. - -MT safe. - -Checks if `self` has the given `name`. This function is usually used to -check the name of a custom event. -## `name` -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. -## `format` -A pointer to store the format in -## `minsize` -A pointer to store the minsize in -## `maxsize` -A pointer to store the maxsize in -## `async_` -A pointer to store the async-flag in - -Get the caps from `self`. The caps remains valid as long as `self` remains -valid. -## `caps` -A pointer to the caps - -Parse the FLUSH_STOP event and retrieve the `reset_time` member. -## `reset_time` -if time should be reset - -Extract timestamp and duration from a new GAP event. -## `timestamp` -location where to store the - start time (pts) of the gap, or `None` -## `duration` -location where to store the duration of - the gap, or `None` - -## `group_id` -address of variable where to store the group id - -# Returns - -`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` -A pointer to store the latency in. - -Parses an event containing protection system specific information and stores -the results in `system_id`, `data` and `origin`. The data stored in `system_id`, -`origin` and `data` are valid until `self` is released. -## `system_id` -pointer to store the UUID -string uniquely identifying a content protection system. -## `data` -pointer to store a `Buffer` -holding protection system specific information. -## `origin` -pointer to store a value that -indicates where the protection information carried by `self` was extracted -from. - -Get the type, proportion, diff and timestamp in the qos event. See -`Event::new_qos` for more information about the different QoS values. - -`timestamp` will be adjusted for any pad offsets of pads it was passing through. -## `type_` -A pointer to store the QoS type in -## `proportion` -A pointer to store the proportion in -## `diff` -A pointer to store the diff in -## `timestamp` -A pointer to store the timestamp in - -Parses a seek `self` and stores the results in the given result locations. -## `rate` -result location for the rate -## `format` -result location for the stream format -## `flags` -result location for the `SeekFlags` -## `start_type` -result location for the `SeekType` of the start position -## `start` -result location for the start position expressed in `format` -## `stop_type` -result location for the `SeekType` of the stop position -## `stop` -result location for the stop position expressed in `format` - -Retrieve the trickmode interval that may have been set on a -seek event with `Event::set_seek_trickmode_interval`. - -Feature: `v1_16` - - -Parses a segment `self` and stores the result in the given `segment` location. -`segment` remains valid only until the `self` is freed. Don't modify the segment -and make a copy if you want to modify it or store it for later use. -## `segment` -a pointer to a `Segment` - -Extracts the position and format from the segment done message. -## `format` -Result location for the format, or `None` -## `position` -Result location for the position, or `None` - -Parse the SELECT_STREAMS event and retrieve the contained streams. - -Feature: `v1_10` - -## `streams` -the streams - -Parse the sink-message event. Unref `msg` after usage. -## `msg` -a pointer to store the `Message` in. - -Parse the step event. -## `format` -a pointer to store the format in -## `amount` -a pointer to store the amount in -## `rate` -a pointer to store the rate in -## `flush` -a pointer to store the flush boolean in -## `intermediate` -a pointer to store the intermediate - boolean in - -Parse a stream-start `self` and extract the `Stream` from it. - -Feature: `v1_10` - -## `stream` -address of variable to store the stream - -Retrieve new `StreamCollection` from STREAM_COLLECTION event `self`. - -Feature: `v1_10` - -## `collection` -pointer to store the collection - -## `flags` -address of variable where to store the stream flags - -Parse a stream-group-done `self` and store the result in the given -`group_id` location. - -Feature: `v1_10` - -## `group_id` -address of variable to store the group id into - -Parse a stream-id `self` and store the result in the given `stream_id` -location. The string stored in `stream_id` must not be modified and will -remain valid only until `self` gets freed. Make a copy if you want to -modify it or store it for later use. -## `stream_id` -pointer to store the stream-id - -Parses a tag `self` and stores the results in the given `taglist` location. -No reference to the taglist will be returned, it remains valid only until -the `self` is freed. Don't modify or free the taglist, make a copy if you -want to modify it or store it for later use. -## `taglist` -pointer to metadata list - -Parse a TOC `self` and store the results in the given `toc` and `updated` locations. -## `toc` -pointer to `Toc` structure. -## `updated` -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. - -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 -same group id but different stream ids. The group id should change -each time the stream is started, resulting in different group ids -each time a file is played for example. - -Use `gst_util_group_id_next` to get a new group id. -## `group_id` -the group id to set - -Set the running time offset of a event. See -`Event::get_running_time_offset` for more information. - -MT safe. -## `offset` -A the new running time offset - -Sets a trickmode interval on a (writable) seek event. Elements -that support TRICKMODE_KEY_UNITS seeks SHOULD use this as the minimal -interval between each frame they may output. - -Feature: `v1_16` - - -Set the sequence number of a event. - -This function might be called by the creator of a event to indicate that the -event relates to other events or messages. See `Event::get_seqnum` for -more information. - -MT safe. -## `seqnum` -A sequence number. - -Set the `stream` on the stream-start `self` - -Feature: `v1_10` - -## `stream` -the stream object to set - -## `flags` -the stream flags to set - -Get a writable version of the structure. - -# Returns - -The structure of the event. The structure -is still owned by the event, which means that you should not free -it and that the pointer becomes invalid when you free the event. -This function checks if `self` is writable and will never return -`None`. - -MT safe. - -`EventType` lists the standard event types that can be sent in a pipeline. - -The custom event types can be used for private messages between elements -that can't be expressed using normal -GStreamer buffer passing semantics. Custom events carry an arbitrary -`Structure`. -Specific custom events are distinguished by the name of the structure. - -unknown event. - -Start a flush operation. This event clears all data - from the pipeline and unblock all streaming threads. - -Stop a flush operation. This event resets the - running-time of the pipeline. - -Event to mark the start of a new stream. Sent before any - other serialized event and only sent at the start of a new stream, - not after flushing seeks. - -`Caps` event. Notify the pad of a new media type. - -A new media segment follows in the dataflow. The - segment events contains information for clipping buffers and - converting buffer timestamps to running-time and - stream-time. - -A new `StreamCollection` is available (Since: 1.10) - -A new set of metadata tags has been found in the stream. - -Notification of buffering requirements. Currently not - used yet. - -An event that sinks turn into a message. Used to - send messages that should be emitted in sync with - rendering. - -Indicates that there is no more data for - the stream group ID in the message. Sent before EOS - in some instances and should be handled mostly the same. (Since: 1.10) - -End-Of-Stream. No more data is to be expected to follow - without either a STREAM_START event, or a FLUSH_STOP and a SEGMENT - event. - -An event which indicates that a new table of contents (TOC) - was found or updated. - -An event which indicates that new or updated - encryption information has been found in the stream. - -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 - rate. - -A request for a new playback position and rate. - -Navigation events are usually used for communicating - user requests, such as mouse or keyboard movements, - to upstream elements. - -Notification of new latency adjustment. Sinks will use - the latency information to adjust their synchronisation. - -A request for stepping through the media. Sinks will usually - execute the step operation. - -A request for upstream renegotiating caps and reconfiguring. - -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 - -Downstream custom event that travels in the - data flow. - -Custom out-of-band downstream event. - -Custom sticky downstream event. - -Custom upstream or downstream event. - In-band when travelling downstream. - -Custom upstream or downstream out-of-band event. - -`EventTypeFlags` indicate the aspects of the different `EventType` -values. You can get the type flags of a `EventType` with the -`EventType::get_flags` function. - -Set if the event can travel upstream. - -Set if the event can travel downstream. - -Set if the event should be serialized with data - flow. - -Set if the event is sticky on the pads. - -Multiple sticky events can be on a pad, each - identified by the event name. - -The result of passing data to a pad. - -Note that the custom return values should not be exposed outside of the -element scope. - -Pre-defined custom success code. - -Pre-defined custom success code (define your - custom success code to this to avoid compiler - warnings). - -Elements can use values starting from - this (and higher) to define custom success - codes. - -Data passing was ok. - -Pad is not linked. - -Pad is flushing. - -Pad is EOS. - -Pad is not negotiated. - -Some (fatal) error occurred. Element generating - this error should post an error message using - GST_ELEMENT_ERROR() with more details. - -This operation is not supported. - -Elements can use values starting from - this (and lower) to define custom error codes. - -Pre-defined custom error code (define your - custom error code to this to avoid compiler - warnings). - -Pre-defined custom error code. - -Standard predefined formats - -undefined format - -the default format of the pad/element. This can be - samples for raw audio, frames/fields for raw video (some, but not all, - elements support this; use [`Time`](Self::Time) if you don't have a good - reason to query for samples/frames) - -bytes - -time in nanoseconds - -buffers (few, if any, elements implement this as of - May 2009) - -percentage of stream (few, if any, elements implement - this as of May 2009) - -GhostPads are useful when organizing pipelines with `Bin` like elements. -The idea here is to create hierarchical element graphs. The bin element -contains a sub-graph. Now one would like to treat the bin-element like any -other `Element`. This is where GhostPads come into play. A GhostPad acts as -a proxy for another pad. Thus the bin can have sink and source ghost-pads -that are associated with sink and source pads of the child elements. - -If the target pad is known at creation time, `GhostPad::new` is the -function to use to get a ghost-pad. Otherwise one can use `GhostPad::new_no_target` -to create the ghost-pad and use `GhostPadExt::set_target` to establish the -association later on. - -Note that GhostPads add overhead to the data processing of a pipeline. - -# Implements - -[`GhostPadExt`](trait@crate::GhostPadExt), [`ProxyPadExt`](trait@crate::ProxyPadExt), [`PadExt`](trait@crate::PadExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`ProxyPadExtManual`](trait@crate::ProxyPadExtManual), [`PadExtManual`](trait@crate::PadExtManual) - -Trait containing all `GhostPad` methods. - -# Implementors - -[`GhostPad`](struct@crate::GhostPad) - -Create a new ghostpad with `target` as the target. The direction will be taken -from the target pad. `target` must be unlinked. - -Will ref the target. -## `name` -the name of the new pad, or `None` to assign a default name -## `target` -the pad to ghost. - -# Returns - -a new `Pad`, or `None` in -case of an error. - -Create a new ghostpad with `target` as the target. The direction will be taken -from the target pad. The template used on the ghostpad will be `template`. - -Will ref the target. -## `name` -the name of the new pad, or `None` to assign a default name. -## `target` -the pad to ghost. -## `templ` -the `PadTemplate` to use on the ghostpad. - -# Returns - -a new `Pad`, or `None` in -case of an error. - -Create a new ghostpad without a target with the given direction. -A target can be set on the ghostpad later with the -`GhostPadExt::set_target` function. - -The created ghostpad will not have a padtemplate. -## `name` -the name of the new pad, or `None` to assign a default name. -## `dir` -the direction of the ghostpad - -# Returns - -a new `Pad`, or `None` in -case of an error. - -Create a new ghostpad based on `templ`, without setting a target. The -direction will be taken from the `templ`. -## `name` -the name of the new pad, or `None` to assign a default name -## `templ` -the `PadTemplate` to create the ghostpad from. - -# Returns - -a new `Pad`, or `None` in -case of an error. - -Invoke the default activate mode function of a ghost pad. -## `pad` -the `Pad` to activate or deactivate. -## `parent` -the parent of `pad` or `None` -## `mode` -the requested activation mode -## `active` -whether the pad should be active or not. - -# Returns - -`true` if the operation was successful. - -Invoke the default activate mode function of a proxy pad that is -owned by a ghost pad. -## `pad` -the `Pad` to activate or deactivate. -## `parent` -the parent of `pad` or `None` -## `mode` -the requested activation mode -## `active` -whether the pad should be active or not. - -# Returns - -`true` if the operation was successful. - -Finish initialization of a newly allocated ghost pad. - -This function is most useful in language bindings and when subclassing -`GhostPad`; plugin and application developers normally will not call this -function. Call this function directly after a call to g_object_new -(GST_TYPE_GHOST_PAD, "direction", `dir`, ..., NULL). - -# Deprecated - -This function is deprecated since 1.18 and does nothing -anymore. - -# Returns - -`true` if the construction succeeds, `false` otherwise. - -Get the target pad of `self`. Unref target pad after usage. - -# Returns - -the target `Pad`, can be -`None` if the ghostpad has no target set. Unref target pad after -usage. - -Set the new target of the ghostpad `self`. Any existing target -is unlinked and links to the new target are established. if `newtarget` is -`None` the target will be cleared. -## `newtarget` -the new pad target - -# Returns - -`true` if the new target could be set. This function - can return `false` when the internal pads could not be linked. - -Library errors are for errors from the library being used by elements -(initializing, finalizing, settings, ...) - -a general error which doesn't fit in any other -category. Make sure you add a custom message to the error call. - -do not use this except as a placeholder for -deciding where to go while developing code. - -used when the library could not be opened. - -used when the library could not be closed. - -used when the library doesn't accept settings. - -used when the library generated an encoding error. - -the number of library error types. - -GstMemory is a lightweight refcounted object that wraps a region of memory. -They are typically used to manage the data of a `Buffer`. - -A GstMemory object has an allocated region of memory of maxsize. The maximum -size does not change during the lifetime of the memory object. The memory -also has an offset and size property that specifies the valid range of memory -in the allocated region. - -Memory is usually created by allocators with a `AllocatorExt::alloc` -method call. When `None` is used as the allocator, the default allocator will -be used. - -New allocators can be registered with `Allocator::register`. -Allocators are identified by name and can be retrieved with -`Allocator::find`. `AllocatorExt::set_default` can be used to change the -default allocator. - -New memory can be created with `Memory::new_wrapped` that wraps the memory -allocated elsewhere. - -Refcounting of the memory block is performed with `gst_memory_ref` and -`gst_memory_unref`. - -The size of the memory can be retrieved and changed with -`Memory::get_sizes` and `Memory::resize` respectively. - -Getting access to the data of the memory is performed with `Memory::map`. -The call will return a pointer to offset bytes into the region of memory. -After the memory access is completed, `Memory::unmap` should be called. - -Memory can be copied with `Memory::copy`, which will return a writable -copy. `Memory::share` will create a new memory block that shares the -memory with an existing memory block at a custom offset and with a custom -size. - -Memory can be efficiently merged when `Memory::is_span` returns `true`. - -Allocate a new memory block that wraps the given `data`. - -The prefix/padding must be filled with 0 if `flags` contains -`MemoryFlags::ZeroPrefixed` and `MemoryFlags::ZeroPadded` respectively. -## `flags` -`MemoryFlags` -## `data` -data to - wrap -## `maxsize` -allocated size of `data` -## `offset` -offset in `data` -## `size` -size of valid data -## `user_data` -user_data -## `notify` -called with `user_data` when the memory is freed - -# Returns - -a new `Memory`. - -Return a copy of `size` bytes from `self` starting from `offset`. This copy is -guaranteed to be writable. `size` can be set to -1 to return a copy -from `offset` to the end of the memory region. -## `offset` -offset to copy from -## `size` -size to copy, or -1 to copy to the end of the memory region - -# Returns - -a new `Memory`. - -Get the current `size`, `offset` and `maxsize` of `self`. -## `offset` -pointer to offset -## `maxsize` -pointer to maxsize - -# Returns - -the current size of `self` - -Initializes a newly allocated `self` with the given parameters. This function -will call `MiniObject::init` with the default memory parameters. -## `flags` -`MemoryFlags` -## `allocator` -the `Allocator` -## `parent` -the parent of `self` -## `maxsize` -the total size of the memory -## `align` -the alignment of the memory -## `offset` -The offset in the memory -## `size` -the size of valid data in the memory - -Check if `self` and mem2 share the memory with a common parent memory object -and that the memory is contiguous. - -If this is the case, the memory of `self` and `mem2` can be merged -efficiently by performing `Memory::share` on the parent object from -the returned `offset`. -## `mem2` -a `Memory` -## `offset` -a pointer to a result offset - -# Returns - -`true` if the memory is contiguous and of a common parent. - -Check if `self` if allocated with an allocator for `mem_type`. -## `mem_type` -a memory type - -# Returns - -`true` if `self` was allocated from an allocator for `mem_type`. - -Create a `Memory` object that is mapped with `flags`. If `self` is mappable -with `flags`, this function returns the mapped `self` directly. Otherwise a -mapped copy of `self` is returned. - -This function takes ownership of old `self` and returns a reference to a new -`Memory`. -## `info` -pointer for info -## `flags` -mapping flags - -# Returns - -a `Memory` object mapped -with `flags` or `None` when a mapping is not possible. - -Fill `info` with the pointer and sizes of the memory in `self` that can be -accessed according to `flags`. - -This function can return `false` for various reasons: -- the memory backed by `self` is not accessible with the given `flags`. -- the memory was already mapped with a different mapping. - -`info` and its contents remain valid for as long as `self` is valid and -until `Memory::unmap` is called. - -For each `Memory::map` call, a corresponding `Memory::unmap` call -should be done. -## `info` -pointer for info -## `flags` -mapping flags - -# Returns - -`true` if the map operation was successful. - -Resize the memory region. `self` should be writable and offset + size should be -less than the maxsize of `self`. - -`MemoryFlags::ZeroPrefixed` and `MemoryFlags::ZeroPadded` will be -cleared when offset or padding is increased respectively. -## `offset` -a new offset -## `size` -a new size - -Return a shared copy of `size` bytes from `self` starting from `offset`. No -memory copy is performed and the memory region is simply shared. The result -is guaranteed to be non-writable. `size` can be set to -1 to return a shared -copy from `offset` to the end of the memory region. -## `offset` -offset to share from -## `size` -size to share, or -1 to share to the end of the memory region - -# Returns - -a new `Memory`. - -Release the memory obtained with `Memory::map` -## `info` -a `MapInfo` - -Flags for wrapped memory. - -memory is readonly. It is not allowed to map the -memory with `MapFlags::Write`. - -memory must not be shared. Copies will have to be -made when this memory needs to be shared between buffers. - -the memory prefix is filled with 0 bytes - -the memory padding is filled with 0 bytes - -the memory is physically contiguous. (Since: 1.2) - -the memory can't be mapped via `Memory::map` without any preconditions. (Since: 1.2) - -first flag that can be used for custom purposes - -Messages are implemented as a subclass of `MiniObject` with a generic -`Structure` as the content. This allows for writing custom messages without -requiring an API change while allowing a wide range of different types -of messages. - -Messages are posted by objects in the pipeline and are passed to the -application using the `Bus`. - -The basic use pattern of posting a message on a `Bus` is as follows: - -```C - gst_bus_post (bus, gst_message_new_eos()); -``` - -A `Element` usually posts messages on the bus provided by the parent -container using `Element::post_message`. - -Create a new application-typed message. GStreamer will never create these -messages; they are a gift from us to you. Enjoy. -## `src` -The object originating the message. -## `structure` -the structure for the message. The message - will take ownership of the structure. - -# Returns - -The new application message. - -MT safe. - -The message is posted when elements completed an ASYNC state change. -`running_time` contains the time of the desired running_time when this -elements goes to PLAYING. A value of `GST_CLOCK_TIME_NONE` for `running_time` -means that the element has no clock interaction and thus doesn't care about -the running_time of the pipeline. -## `src` -The object originating the message. -## `running_time` -the desired running_time - -# Returns - -The new async_done message. - -MT safe. - -This message is posted by elements when they start an ASYNC state change. -## `src` -The object originating the message. - -# Returns - -The new async_start message. - -MT safe. - -Create a new buffering message. This message can be posted by an element that -needs to buffer data before it can continue processing. `percent` should be a -value between 0 and 100. A value of 100 means that the buffering completed. - -When `percent` is < 100 the application should PAUSE a PLAYING pipeline. When -`percent` is 100, the application can set the pipeline (back) to PLAYING. -The application must be prepared to receive BUFFERING messages in the -PREROLLING state and may only set the pipeline to PLAYING after receiving a -message with `percent` set to 100, which can happen after the pipeline -completed prerolling. - -MT safe. -## `src` -The object originating the message. -## `percent` -The buffering percent - -# Returns - -The new buffering message. - -Create a clock lost message. This message is posted whenever the -clock is not valid anymore. - -If this message is posted by the pipeline, the pipeline will -select a new clock again when it goes to PLAYING. It might therefore -be needed to set the pipeline to PAUSED and PLAYING again. -## `src` -The object originating the message. -## `clock` -the clock that was lost - -# Returns - -The new clock lost message. - -MT safe. - -Create a clock provide message. This message is posted whenever an -element is ready to provide a clock or lost its ability to provide -a clock (maybe because it paused or became EOS). - -This message is mainly used internally to manage the clock -selection. -## `src` -The object originating the message. -## `clock` -the clock it provides -## `ready` -`true` if the sender can provide a clock - -# Returns - -the new provide clock message. - -MT safe. - -Create a new custom-typed message. This can be used for anything not -handled by other message-specific functions to pass a message to the -app. The structure field can be `None`. -## `type_` -The `MessageType` to distinguish messages -## `src` -The object originating the message. -## `structure` -the structure for the - message. The message will take ownership of the structure. - -# Returns - -The new message. - -MT safe. - -Creates a new device-added message. The device-added message is produced by -`DeviceProvider` or a `DeviceMonitor`. They announce the appearance -of monitored devices. -## `src` -The `Object` that created the message -## `device` -The new `Device` - -# Returns - -a newly allocated `Message` - -Creates a new device-changed message. The device-changed message is produced -by `DeviceProvider` or a `DeviceMonitor`. They announce that a device -properties has changed and `device` represent the new modified version of `changed_device`. - -Feature: `v1_16` - -## `src` -The `Object` that created the message -## `device` -The newly created device representing `replaced_device` - with its new configuration. - -# Returns - -a newly allocated `Message` - -Creates a new device-removed message. The device-removed message is produced -by `DeviceProvider` or a `DeviceMonitor`. They announce the -disappearance of monitored devices. -## `src` -The `Object` that created the message -## `device` -The removed `Device` - -# Returns - -a newly allocated `Message` - -Create a new duration changed message. This message is posted by elements -that know the duration of a stream when the duration changes. This message -is received by bins and is used to calculate the total duration of a -pipeline. -## `src` -The object originating the message. - -# Returns - -The new duration-changed message. - -MT safe. - -Create a new element-specific message. This is meant as a generic way of -allowing one-way communication from an element to an application, for example -"the firewire cable was unplugged". The format of the message should be -documented in the element's documentation. The structure field can be `None`. -## `src` -The object originating the message. -## `structure` -The structure for the - message. The message will take ownership of the structure. - -# Returns - -The new element message. - -MT safe. - -Create a new eos message. This message is generated and posted in -the sink elements of a GstBin. The bin will only forward the EOS -message to the application if all sinks have posted an EOS message. -## `src` -The object originating the message. - -# Returns - -The new eos message. - -MT safe. - -Create a new error message. The message will copy `error` and -`debug`. This message is posted by element when a fatal event -occurred. The pipeline will probably (partially) stop. The application -receiving this message should stop the pipeline. -## `src` -The object originating the message. -## `error` -The GError for this message. -## `debug` -A debugging string. - -# Returns - -the new error message. - -MT safe. - -Create a new error message. The message will copy `error` and -`debug`. This message is posted by element when a fatal event -occurred. The pipeline will probably (partially) stop. The application -receiving this message should stop the pipeline. - -Feature: `v1_10` - -## `src` -The object originating the message. -## `error` -The GError for this message. -## `debug` -A debugging string. -## `details` -A GstStructure with details - -# Returns - -the new error message. - -This message is posted when an element has a new local `Context`. -## `src` -The object originating the message. -## `context` -the context - -# Returns - -The new have-context message. - -MT safe. - -Create a new info message. The message will make copies of `error` and -`debug`. -## `src` -The object originating the message. -## `error` -The GError for this message. -## `debug` -A debugging string. - -# Returns - -the new info message. - -MT safe. - -Create a new info message. The message will make copies of `error` and -`debug`. - -Feature: `v1_10` - -## `src` -The object originating the message. -## `error` -The GError for this message. -## `debug` -A debugging string. -## `details` -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 -[`crate::EventType::InstantRateSyncTime`] (XXX: @-reference does not belong to Message!) 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. -## `src` -The object originating the message. - -# Returns - -The new latency message. - -MT safe. - -This message is posted when an element needs a specific `Context`. -## `src` -The object originating the message. -## `context_type` -The context type that is needed - -# Returns - -The new need-context message. - -MT safe. - -Create a new clock message. This message is posted whenever the -pipeline selects a new clock for the pipeline. -## `src` -The object originating the message. -## `clock` -the new selected clock - -# Returns - -The new new clock message. - -MT safe. - -Progress messages are posted by elements when they use an asynchronous task -to perform actions triggered by a state change. - -`code` contains a well defined string describing the action. -`text` should contain a user visible string detailing the current action. -## `src` -The object originating the message. -## `type_` -a `ProgressType` -## `code` -a progress code -## `text` -free, user visible text describing the progress - -# Returns - -The new qos message. - - -Feature: `v1_10` - -## `src` -The `Object` whose property changed (may or may not be a `Element`) -## `property_name` -name of the property that changed -## `val` -new property value, or `None` - -# Returns - -a newly allocated `Message` - -A QOS message is posted on the bus whenever an element decides to drop a -buffer because of QoS reasons or whenever it changes its processing strategy -because of QoS reasons (quality adjustments such as processing at lower -accuracy). - -This message can be posted by an element that performs synchronisation against the -clock (live) or it could be dropped by an element that performs QoS because of QOS -events received from a downstream element (!live). - -`running_time`, `stream_time`, `timestamp`, `duration` should be set to the -respective running-time, stream-time, timestamp and duration of the (dropped) -buffer that generated the QoS event. Values can be left to -GST_CLOCK_TIME_NONE when unknown. -## `src` -The object originating the message. -## `live` -if the message was generated by a live element -## `running_time` -the running time of the buffer that generated the message -## `stream_time` -the stream time of the buffer that generated the message -## `timestamp` -the timestamps of the buffer that generated the message -## `duration` -the duration of the buffer that generated the message - -# Returns - -The new qos message. - -MT safe. - -Creates a new redirect message and adds a new entry to it. Redirect messages -are posted when an element detects that the actual data has to be retrieved -from a different location. This is useful if such a redirection cannot be -handled inside a source element, for example when HTTP 302/303 redirects -return a non-HTTP URL. - -The redirect message can hold multiple entries. The first one is added -when the redirect message is created, with the given location, tag_list, -entry_struct arguments. Use `Message::add_redirect_entry` to add more -entries. - -Each entry has a location, a tag list, and a structure. All of these are -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 -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 -bitrate tag. - -The specified location string is copied. However, ownership over the tag -list and structure are transferred to the message. - -Feature: `v1_10` - -## `src` -The `Object` whose property changed (may or may not be a `Element`) -## `location` -location string for the new entry -## `tag_list` -tag list for the new entry -## `entry_struct` -structure for the new entry - -# Returns - -a newly allocated `Message` - -This message can be posted by elements when they want to have their state -changed. A typical use case would be an audio server that wants to pause the -pipeline because a higher priority stream is being played. -## `src` -The object originating the message. -## `state` -The new requested state - -# Returns - -the new request state message. - -MT safe. - -This message is posted when the pipeline running-time should be reset to -`running_time`, like after a flushing seek. -## `src` -The object originating the message. -## `running_time` -the requested running-time - -# Returns - -The new reset_time message. - -MT safe. - -Create a new segment done message. This message is posted by elements that -finish playback of a segment as a result of a segment seek. This message -is received by the application after all elements that posted a segment_start -have posted the segment_done. -## `src` -The object originating the message. -## `format` -The format of the position being done -## `position` -The position of the segment being done - -# Returns - -the new segment done message. - -MT safe. - -Create a new segment message. This message is posted by elements that -start playback of a segment as a result of a segment seek. This message -is not received by the application but is used for maintenance reasons in -container elements. -## `src` -The object originating the message. -## `format` -The format of the position being played -## `position` -The position of the segment being played - -# Returns - -the new segment start message. - -MT safe. - -Create a state change message. This message is posted whenever an element -changed its state. -## `src` -The object originating the message. -## `oldstate` -the previous state -## `newstate` -the new (current) state -## `pending` -the pending (target) state - -# Returns - -the new state change message. - -MT safe. - -Create a state dirty message. This message is posted whenever an element -changed its state asynchronously and is used internally to update the -states of container objects. -## `src` -The object originating the message - -# Returns - -the new state dirty message. - -MT safe. - -This message is posted by elements when they complete a part, when `intermediate` set -to `true`, or a complete step operation. - -`duration` will contain the amount of time (in GST_FORMAT_TIME) of the stepped -`amount` of media in format `format`. -## `src` -The object originating the message. -## `format` -the format of `amount` -## `amount` -the amount of stepped data -## `rate` -the rate of the stepped amount -## `flush` -is this an flushing step -## `intermediate` -is this an intermediate step -## `duration` -the duration of the data -## `eos` -the step caused EOS - -# Returns - -the new step_done message. - -MT safe. - -This message is posted by elements when they accept or activate a new step -event for `amount` in `format`. - -`active` is set to `false` when the element accepted the new step event and has -queued it for execution in the streaming threads. - -`active` is set to `true` when the element has activated the step operation and -is now ready to start executing the step in the streaming thread. After this -message is emitted, the application can queue a new step operation in the -element. -## `src` -The object originating the message. -## `active` -if the step is active or queued -## `format` -the format of `amount` -## `amount` -the amount of stepped data -## `rate` -the rate of the stepped amount -## `flush` -is this an flushing step -## `intermediate` -is this an intermediate step - -# Returns - -The new step_start message. - -MT safe. - -Creates a new stream-collection message. The message is used to announce new -`StreamCollection` - -Feature: `v1_10` - -## `src` -The `Object` that created the message -## `collection` -The `StreamCollection` - -# Returns - -a newly allocated `Message` - -Create a new stream_start message. This message is generated and posted in -the sink elements of a GstBin. The bin will only forward the STREAM_START -message to the application if all sinks have posted an STREAM_START message. -## `src` -The object originating the message. - -# Returns - -The new stream_start message. - -MT safe. - -Create a new stream status message. This message is posted when a streaming -thread is created/destroyed or when the state changed. -## `src` -The object originating the message. -## `type_` -The stream status type. -## `owner` -the owner element of `src`. - -# Returns - -the new stream status message. - -MT safe. - -Creates a new steams-selected message. The message is used to announce -that an array of streams has been selected. This is generally in response -to a `EventType::SelectStreams` event, or when an element (such as decodebin3) -makes an initial selection of streams. - -The message also contains the `StreamCollection` to which the various streams -belong to. - -Users of `Message::new_streams_selected` can add the selected streams with -`Message::streams_selected_add`. - -Feature: `v1_10` - -## `src` -The `Object` that created the message -## `collection` -The `StreamCollection` - -# Returns - -a newly allocated `Message` - -Create a new structure change message. This message is posted when the -structure of a pipeline is in the process of being changed, for example -when pads are linked or unlinked. - -`src` should be the sinkpad that unlinked or linked. -## `src` -The object originating the message. -## `type_` -The change type. -## `owner` -The owner element of `src`. -## `busy` -Whether the structure change is busy. - -# Returns - -the new structure change message. - -MT safe. - -Create a new tag message. The message will take ownership of the tag list. -The message is posted by elements that discovered a new taglist. -## `src` -The object originating the message. -## `tag_list` -the tag list for the message. - -# Returns - -the new tag message. - -MT safe. - -Create a new TOC message. The message is posted by elements -that discovered or updated a TOC. -## `src` -the object originating the message. -## `toc` -`Toc` structure for the message. -## `updated` -whether TOC was updated or not. - -# Returns - -a new TOC message. - -MT safe. - -Create a new warning message. The message will make copies of `error` and -`debug`. -## `src` -The object originating the message. -## `error` -The GError for this message. -## `debug` -A debugging string. - -# Returns - -the new warning message. - -MT safe. - -Create a new warning message. The message will make copies of `error` and -`debug`. - -Feature: `v1_10` - -## `src` -The object originating the message. -## `error` -The GError for this message. -## `debug` -A debugging string. -## `details` -A GstStructure with details - -# Returns - -the new warning message. - -Creates and appends a new entry. - -The specified location string is copied. However, ownership over the tag -list and structure are transferred to the message. - -Feature: `v1_10` - -## `location` -location string for the new entry -## `tag_list` -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` - - -# Returns - -the number of entries stored in the message - -Retrieve the sequence number of a message. - -Messages have ever-incrementing sequence numbers, which may also be set -explicitly via `Message::set_seqnum`. Sequence numbers are typically used -to indicate that a message corresponds to some other set of messages or -events, for example a SEGMENT_DONE message corresponding to a SEEK event. It -is considered good practice to make this correspondence when possible, though -it is not required. - -Note that events and messages share the same sequence number incrementor; -two events or messages will never have the same sequence number unless -that correspondence was made explicitly. - -# Returns - -The message's sequence number. - -MT safe. - -Extracts the object managing the streaming thread from `self`. - -# Returns - -a GValue containing the object that manages the -streaming thread. This object is usually of type GstTask but other types can -be added in the future. The object remains valid as long as `self` is -valid. - -Access the structure of the message. - -# Returns - -The structure of the message. The -structure is still owned by the message, which means that you should not -free it and that the pointer becomes invalid when you free the message. - -MT safe. - -Checks if `self` has the given `name`. This function is usually used to -check the name of a custom message. -## `name` -name to check - -# Returns - -`true` if `name` matches the name of the message structure. - -Extract the running_time from the async_done message. - -MT safe. -## `running_time` -Result location for the running_time or `None` - -Extracts the buffering percent from the GstMessage. see also -`Message::new_buffering`. - -MT safe. -## `percent` -Return location for the percent. - -Extracts the buffering stats values from `self`. -## `mode` -a buffering mode, or `None` -## `avg_in` -the average input rate, or `None` -## `avg_out` -the average output rate, or `None` -## `buffering_left` -amount of buffering time left in - milliseconds, or `None` - -Extracts the lost clock from the GstMessage. -The clock object returned remains valid until the message is freed. - -MT safe. -## `clock` -a pointer to hold the lost clock - -Extracts the clock and ready flag from the GstMessage. -The clock object returned remains valid until the message is freed. - -MT safe. -## `clock` -a pointer to hold a clock - object, or `None` -## `ready` -a pointer to hold the ready flag, or `None` - -Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message. -## `context_type` -the context type, or `None` - -# Returns - -a `gboolean` indicating if the parsing succeeded. - -Parses a device-added message. The device-added message is produced by -`DeviceProvider` or a `DeviceMonitor`. It announces the appearance -of monitored devices. -## `device` -A location where to store a - pointer to the new `Device`, or `None` - -Parses a device-changed message. The device-changed message is produced by -`DeviceProvider` or a `DeviceMonitor`. It announces the -disappearance of monitored devices. * It announce that a device properties has -changed and `device` represents the new modified version of `changed_device`. - -Feature: `v1_16` - -## `device` -A location where to store a - pointer to the updated version of the `Device`, or `None` -## `changed_device` -A location where to store a - pointer to the old version of the `Device`, or `None` - -Parses a device-removed message. The device-removed message is produced by -`DeviceProvider` or a `DeviceMonitor`. It announces the -disappearance of monitored devices. -## `device` -A location where to store a - pointer to the removed `Device`, or `None` - -Extracts the GError and debug string from the GstMessage. The values returned -in the output arguments are copies; the caller must free them when done. - -Typical usage of this function might be: - -```C - ... - switch (GST_MESSAGE_TYPE (msg)) { - case GST_MESSAGE_ERROR: { - GError *err = NULL; - gchar *dbg_info = NULL; - - gst_message_parse_error (msg, &err, &dbg_info); - g_printerr ("ERROR from element %s: %s\n", - GST_OBJECT_NAME (msg->src), err->message); - g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none"); - g_error_free (err); - g_free (dbg_info); - break; - } - ... - } - ... -``` - -MT safe. -## `gerror` -location for the GError -## `debug` -location for the debug message, - or `None` - -Returns the optional details structure, may be NULL if none. -The returned structure must not be freed. - -Feature: `v1_10` - -## `structure` -A pointer to the returned details - -Extract the group from the STREAM_START message. -## `group_id` -Result location for the group id or - `None` - -# Returns - -`true` if the message had a group id set, `false` otherwise - -MT safe. - -Extract the context from the HAVE_CONTEXT message. - -MT safe. -## `context` -Result location for the - context or `None` - -Extracts the GError and debug string from the GstMessage. The values returned -in the output arguments are copies; the caller must free them when done. - -MT safe. -## `gerror` -location for the GError -## `debug` -location for the debug message, - or `None` - -Returns the optional details structure, may be NULL if none -The returned structure must not be freed. - -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. - -MT safe. -## `clock` -a pointer to hold the selected - new clock - -Parses the progress `type_`, `code` and `text`. -## `type_` -location for the type -## `code` -location for the code -## `text` -location for the text - -Parses a property-notify message. These will be posted on the bus only -when set up with `Element::add_property_notify_watch` or -`Element::add_property_deep_notify_watch`. - -Feature: `v1_10` - -## `object` -location where to store a - pointer to the object whose property got changed, or `None` -## `property_name` -return location for - the name of the property that got changed, or `None` -## `property_value` -return location for - the new value of the property that got changed, or `None`. This will - only be set if the property notify watch was told to include the value - when it was set up - -Extract the timestamps and live status from the QoS message. - -The returned values give the running_time, stream_time, timestamp and -duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown -values. - -MT safe. -## `live` -if the message was generated by a live element -## `running_time` -the running time of the buffer that - generated the message -## `stream_time` -the stream time of the buffer that - generated the message -## `timestamp` -the timestamps of the buffer that - generated the message -## `duration` -the duration of the buffer that - generated the message - -Extract the QoS stats representing the history of the current continuous -pipeline playback period. - -When `format` is [`crate::Format::Undefined`] (XXX: @-reference does not belong to Message!) both `dropped` and `processed` are -invalid. Values of -1 for either `processed` or `dropped` mean unknown values. - -MT safe. -## `format` -Units of the 'processed' and 'dropped' fields. - Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). - Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT - (samples). -## `processed` -Total number of units correctly processed - since the last state change to READY or a flushing operation. -## `dropped` -Total number of units dropped since the last - state change to READY or a flushing operation. - -Extract the QoS values that have been calculated/analysed from the QoS data - -MT safe. -## `jitter` -The difference of the running-time against - the deadline. -## `proportion` -Long term prediction of the ideal rate - relative to normal rate to get optimal quality. -## `quality` -An element dependent integer value that - specifies the current quality level of the element. The default - maximum quality is 1000000. - -Parses the location and/or structure from the entry with the given index. -The index must be between 0 and `Message::get_num_redirect_entries` - 1. -Returned pointers are valid for as long as this message exists. - -Feature: `v1_10` - -## `entry_index` -index of the entry to parse -## `location` -return location for - the pointer to the entry's location string, or `None` -## `tag_list` -return location for - the pointer to the entry's tag list, or `None` -## `entry_struct` -return location - for the pointer to the entry's structure, or `None` - -Extract the requested state from the request_state message. - -MT safe. -## `state` -Result location for the requested state or `None` - -Extract the running-time from the RESET_TIME message. - -MT safe. -## `running_time` -Result location for the running_time or - `None` - -Extracts the position and format from the segment done message. - -MT safe. -## `format` -Result location for the format, or `None` -## `position` -Result location for the position, or `None` - -Extracts the position and format from the segment start message. - -MT safe. -## `format` -Result location for the format, or `None` -## `position` -Result location for the position, or `None` - -Extracts the old and new states from the GstMessage. - -Typical usage of this function might be: - -```C - ... - switch (GST_MESSAGE_TYPE (msg)) { - case GST_MESSAGE_STATE_CHANGED: { - GstState old_state, new_state; - - gst_message_parse_state_changed (msg, &old_state, &new_state, NULL); - g_print ("Element %s changed state from %s to %s.\n", - GST_OBJECT_NAME (msg->src), - gst_element_state_get_name (old_state), - gst_element_state_get_name (new_state)); - break; - } - ... - } - ... -``` - -MT safe. -## `oldstate` -the previous state, or `None` -## `newstate` -the new (current) state, or `None` -## `pending` -the pending (target) state, or `None` - -Extract the values the step_done message. - -MT safe. -## `format` -result location for the format -## `amount` -result location for the amount -## `rate` -result location for the rate -## `flush` -result location for the flush flag -## `intermediate` -result location for the intermediate flag -## `duration` -result location for the duration -## `eos` -result location for the EOS flag - -Extract the values from step_start message. - -MT safe. -## `active` -result location for the active flag -## `format` -result location for the format -## `amount` -result location for the amount -## `rate` -result location for the rate -## `flush` -result location for the flush flag -## `intermediate` -result location for the intermediate flag - -Parses a stream-collection message. - -Feature: `v1_10` - -## `collection` -A location where to store a - pointer to the `StreamCollection`, or `None` - -Extracts the stream status type and owner the GstMessage. The returned -owner remains valid for as long as the reference to `self` is valid and -should thus not be unreffed. - -MT safe. -## `type_` -A pointer to hold the status type -## `owner` -The owner element of the message source - -Parses a streams-selected message. - -Feature: `v1_10` - -## `collection` -A location where to store a - pointer to the `StreamCollection`, or `None` - -Extracts the change type and completion status from the GstMessage. - -MT safe. -## `type_` -A pointer to hold the change type -## `owner` -The owner element of the - message source -## `busy` -a pointer to hold whether the change is in - progress or has been completed - -Extracts the tag list from the GstMessage. The tag list returned in the -output argument is a copy; the caller must free it when done. - -Typical usage of this function might be: - -```C - ... - switch (GST_MESSAGE_TYPE (msg)) { - case GST_MESSAGE_TAG: { - GstTagList *tags = NULL; - - gst_message_parse_tag (msg, &tags); - g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src)); - handle_tags (tags); - gst_tag_list_unref (tags); - break; - } - ... - } - ... -``` - -MT safe. -## `tag_list` -return location for the tag-list. - -Extract the TOC from the `Message`. The TOC returned in the -output argument is a copy; the caller must free it with -`gst_toc_unref` when done. - -MT safe. -## `toc` -return location for the TOC. -## `updated` -return location for the updated flag. - -Extracts the GError and debug string from the GstMessage. The values returned -in the output arguments are copies; the caller must free them when done. - -MT safe. -## `gerror` -location for the GError -## `debug` -location for the debug message, - or `None` - -Returns the optional details structure, may be NULL if none -The returned structure must not be freed. - -Feature: `v1_10` - -## `structure` -A pointer to the returned details structure - -Configures the buffering stats values in `self`. -## `mode` -a buffering mode -## `avg_in` -the average input rate -## `avg_out` -the average output rate -## `buffering_left` -amount of buffering time left in milliseconds - -Sets the group id on the stream-start message. - -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 -same group id but different stream ids. The group id should change -each time the stream is started, resulting in different group ids -each time a file is played for example. - -MT safe. -## `group_id` -the group id - -Set the QoS stats representing the history of the current continuous pipeline -playback period. - -When `format` is [`crate::Format::Undefined`] (XXX: @-reference does not belong to Message!) both `dropped` and `processed` are -invalid. Values of -1 for either `processed` or `dropped` mean unknown values. - -MT safe. -## `format` -Units of the 'processed' and 'dropped' fields. Video sinks and video -filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters -will likely use GST_FORMAT_DEFAULT (samples). -## `processed` -Total number of units correctly processed since the last state -change to READY or a flushing operation. -## `dropped` -Total number of units dropped since the last state change to READY -or a flushing operation. - -Set the QoS values that have been calculated/analysed from the QoS data - -MT safe. -## `jitter` -The difference of the running-time against the deadline. -## `proportion` -Long term prediction of the ideal rate relative to normal rate -to get optimal quality. -## `quality` -An element dependent integer value that specifies the current -quality level of the element. The default maximum quality is 1000000. - -Set the sequence number of a message. - -This function might be called by the creator of a message to indicate that -the message relates to other messages or events. See `Message::get_seqnum` -for more information. - -MT safe. -## `seqnum` -A sequence number. - -Configures the object handling the streaming thread. This is usually a -GstTask object but other objects might be added in the future. -## `object` -the object controlling the streaming - -Adds the `stream` to the `self`. - -Feature: `v1_10` - -## `stream` -a `Stream` to add to `self` - -Returns the number of streams contained in the `self`. - -Feature: `v1_10` - - -# Returns - -The number of streams contained within. - -Retrieves the `Stream` with index `index` from the `self`. - -Feature: `v1_10` - -## `idx` -Index of the stream to retrieve - -# Returns - -A `Stream` - -Get a writable version of the structure. - -Feature: `v1_14` - - -# Returns - -The structure of the message. The structure -is still owned by the message, which means that you should not free -it and that the pointer becomes invalid when you free the message. -This function checks if `self` is writable and will never return -`None`. - -MT safe. - -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 -`glib::object::InitiallyUnowned`. It is an abstract class that is not very usable on its own. - -`Object` gives us basic refcounting, parenting functionality and locking. -Most of the functions are just extended for special GStreamer needs and can be -found under the same name in the base class of `Object` which is `glib::object::Object` -(e.g. `glib::object::ObjectExt::ref` becomes `GstObjectExt::ref`). - -Since `Object` derives from `glib::object::InitiallyUnowned`, it also inherits the -floating reference. Be aware that functions such as `GstBinExt::add` and -`ElementExt::add_pad` take ownership of the floating reference. - -In contrast to `glib::object::Object` instances, `Object` adds a name property. The functions -`Object::set_name` and `GstObjectExt::get_name` are used to set/get the name -of the object. - -## controlled properties - -Controlled properties offers a lightweight way to adjust gobject properties -over stream-time. It works by using time-stamped value pairs that are queued -for element-properties. At run-time the elements continuously pull value -changes for the current stream-time. - -What needs to be changed in a `Element`? -Very little - it is just two steps to make a plugin controllable! - - * mark gobject-properties paramspecs that make sense to be controlled, - by GST_PARAM_CONTROLLABLE. - - * when processing data (get, chain, loop function) at the beginning call - gst_object_sync_values(element,timestamp). - This will make the controller update all GObject properties that are - under its control with the current values based on the timestamp. - -What needs to be done in applications? Again it's not a lot to change. - - * create a `ControlSource`. - csource = gst_interpolation_control_source_new (); - g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL); - - * Attach the `ControlSource` on the controller to a property. - gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource)); - - * Set the control values - gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); - gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2); - - * start your pipeline - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`] - -Trait containing all `Object` methods. - -# Implementors - -[`Allocator`](struct@crate::Allocator), [`BufferPool`](struct@crate::BufferPool), [`Bus`](struct@crate::Bus), [`Clock`](struct@crate::Clock), [`ControlBinding`](struct@crate::ControlBinding), [`ControlSource`](struct@crate::ControlSource), [`DeviceMonitor`](struct@crate::DeviceMonitor), [`DeviceProvider`](struct@crate::DeviceProvider), [`Device`](struct@crate::Device), [`Element`](struct@crate::Element), [`Object`](struct@crate::Object), [`PadTemplate`](struct@crate::PadTemplate), [`Pad`](struct@crate::Pad), [`PluginFeature`](struct@crate::PluginFeature), [`Plugin`](struct@crate::Plugin), [`Registry`](struct@crate::Registry), [`StreamCollection`](struct@crate::StreamCollection), [`Stream`](struct@crate::Stream) - -Checks to see if there is any object named `name` in `list`. This function -does not do any locking of any kind. You might want to protect the -provided list with the lock of the owner of the list. This function -will lock each `Object` in the list to compare the name, so be -careful when passing a list with a locked object. -## `list` -a list of `Object` to - check through -## `name` -the name to search for - -# Returns - -`true` if a `Object` named `name` does not appear in `list`, -`false` if it does. - -MT safe. Grabs and releases the LOCK of each object in the list. - -A default deep_notify signal callback for an object. The user data -should contain a pointer to an array of strings that should be excluded -from the notify. The default handler will print the new value of the property -using g_print. - -MT safe. This function grabs and releases `object`'s LOCK for getting its - path string. -## `object` -the `glib::object::Object` that signalled the notify. -## `orig` -a `Object` that initiated the notify. -## `pspec` -a `glib::object::ParamSpec` of the property. -## `excluded_props` - - a set of user-specified properties to exclude or `None` to show - all changes. - -Increase the reference count of `object`, and possibly remove the floating -reference, if `object` has a floating reference. - -In other words, if the object is floating, then this call "assumes ownership" -of the floating reference, converting it to a normal reference by clearing -the floating flag while leaving the reference count unchanged. If the object -is not floating, then this call adds a new normal reference increasing the -reference count by one. - -For more background on "floating references" please see the `glib::object::Object` -documentation. -## `object` -a `Object` to sink - -Atomically modifies a pointer to point to a new object. -The reference count of `oldobj` is decreased and the reference count of -`newobj` is increased. - -Either `newobj` and the value pointed to by `oldobj` may be `None`. -## `oldobj` -pointer to a place of - a `Object` to replace -## `newobj` -a new `Object` - -# Returns - -`true` if `newobj` was different from `oldobj` - -Attach the `ControlBinding` to the object. If there already was a -`ControlBinding` for this property it will be replaced. - -The object's reference count will be incremented, and any floating -reference will be removed (see `Object::ref_sink`) -## `binding` -the `ControlBinding` that should be used - -# Returns - -`false` if the given `binding` has not been setup for this object or -has been setup for a non suitable property, `true` otherwise. - -A default error function that uses `g_printerr` to display the error message -and the optional debug string.. - -The default handler will simply print the error string using g_print. -## `error` -the GError. -## `debug` -an additional debug information string, or `None` - -Gets the corresponding `ControlBinding` for the property. This should be -unreferenced again after use. -## `property_name` -name of the property - -# Returns - -the `ControlBinding` for -`property_name` or `None` if the property is not controlled. - -Obtain the control-rate for this `self`. Audio processing `Element` -objects will use this rate to sub-divide their processing loop and call -`GstObjectExt::sync_values` in between. The length of the processing segment -should be up to `control`-rate nanoseconds. - -If the `self` is not under property control, this will return -`GST_CLOCK_TIME_NONE`. This allows the element to avoid the sub-dividing. - -The control-rate is not expected to change if the element is in -`State::Paused` or `State::Playing`. - -# Returns - -the control rate in nanoseconds - -Gets a number of `GValues` for the given controlled property starting at the -requested time. The array `values` need to hold enough space for `n_values` of -`glib::object::Value`. - -This function is useful if one wants to e.g. draw a graph of the control -curve or apply a control curve sample by sample. -## `property_name` -the name of the property to get -## `timestamp` -the time that should be processed -## `interval` -the time spacing between subsequent values -## `n_values` -the number of values -## `values` -array to put control-values in - -# Returns - -`true` if the given array could be filled, `false` otherwise - -Returns a copy of the name of `self`. -Caller should `g_free` the return value after usage. -For a nameless object, this returns `None`, which you can safely `g_free` -as well. - -Free-function: g_free - -# Returns - -the name of `self`. `g_free` -after usage. - -MT safe. This function grabs and releases `self`'s LOCK. - -Returns the parent of `self`. This function increases the refcount -of the parent object so you should `GstObjectExt::unref` it after usage. - -# Returns - -parent of `self`, this can be - `None` if `self` has no parent. unref after usage. - -MT safe. Grabs and releases `self`'s LOCK. - -Generates a string describing the path of `self` in -the object hierarchy. Only useful (or used) for debugging. - -Free-function: g_free - -# Returns - -a string describing the path of `self`. You must - `g_free` the string after usage. - -MT safe. Grabs and releases the `Object`'s LOCK for all objects - in the hierarchy. - -Gets the value for the given controlled property at the requested time. -## `property_name` -the name of the property to get -## `timestamp` -the time the control-change should be read from - -# Returns - -the GValue of the property at the given time, -or `None` if the property isn't controlled. - -Gets a number of values for the given controlled property starting at the -requested time. The array `values` need to hold enough space for `n_values` of -the same type as the objects property's type. - -This function is useful if one wants to e.g. draw a graph of the control -curve or apply a control curve sample by sample. - -The values are unboxed and ready to be used. The similar function -`Object::get_g_value_array` returns the array as `GValues` and is -better suites for bindings. -## `property_name` -the name of the property to get -## `timestamp` -the time that should be processed -## `interval` -the time spacing between subsequent values -## `n_values` -the number of values -## `values` -array to put control-values in - -# Returns - -`true` if the given array could be filled, `false` otherwise - -Check if the `self` has active controlled properties. - -# Returns - -`true` if the object has active controlled properties - -Check if `self` has an ancestor `ancestor` somewhere up in -the hierarchy. One can e.g. check if a `Element` is inside a `Pipeline`. - -# Deprecated - -Use `GstObjectExt::has_as_ancestor` instead. - -MT safe. Grabs and releases `self`'s locks. -## `ancestor` -a `Object` to check as ancestor - -# Returns - -`true` if `ancestor` is an ancestor of `self`. - -Check if `self` has an ancestor `ancestor` somewhere up in -the hierarchy. One can e.g. check if a `Element` is inside a `Pipeline`. -## `ancestor` -a `Object` to check as ancestor - -# Returns - -`true` if `ancestor` is an ancestor of `self`. - -MT safe. Grabs and releases `self`'s locks. - -Check if `parent` is the parent of `self`. -E.g. a `Element` can check if it owns a given `Pad`. -## `parent` -a `Object` to check as parent - -# Returns - -`false` if either `self` or `parent` is `None`. `true` if `parent` is - the parent of `self`. Otherwise `false`. - -MT safe. Grabs and releases `self`'s locks. - -Increments the reference count on `self`. This function -does not take the lock on `self` because it relies on -atomic refcounting. - -This object returns the input parameter to ease writing -constructs like : - result = gst_object_ref (object->parent); - -# Returns - -A pointer to `self` - -Removes the corresponding `ControlBinding`. If it was the -last ref of the binding, it will be disposed. -## `binding` -the binding - -# Returns - -`true` if the binding could be removed. - -This function is used to disable the control bindings on a property for -some time, i.e. `GstObjectExt::sync_values` will do nothing for the -property. -## `property_name` -property to disable -## `disabled` -boolean that specifies whether to disable the controller -or not. - -This function is used to disable all controlled properties of the `self` for -some time, i.e. `GstObjectExt::sync_values` will do nothing. -## `disabled` -boolean that specifies whether to disable the controller -or not. - -Change the control-rate for this `self`. Audio processing `Element` -objects will use this rate to sub-divide their processing loop and call -`GstObjectExt::sync_values` in between. The length of the processing segment -should be up to `control`-rate nanoseconds. - -The control-rate should not change if the element is in `State::Paused` or -`State::Playing`. -## `control_rate` -the new control-rate in nanoseconds. - -Sets the name of `self`, or gives `self` a guaranteed unique -name (if `name` is `None`). -This function makes a copy of the provided name, so the caller -retains ownership of the name it sent. -## `name` -new name of object - -# Returns - -`true` if the name could be set. Since Objects that have -a parent cannot be renamed, this function returns `false` in those -cases. - -MT safe. This function grabs and releases `self`'s LOCK. - -Sets the parent of `self` to `parent`. The object's reference count will -be incremented, and any floating reference will be removed (see `Object::ref_sink`). -## `parent` -new parent of object - -# Returns - -`true` if `parent` could be set or `false` when `self` -already had a parent or `self` and `parent` are the same. - -MT safe. Grabs and releases `self`'s LOCK. - -Returns a suggestion for timestamps where buffers should be split -to get best controller results. - -# Returns - -Returns the suggested timestamp or `GST_CLOCK_TIME_NONE` -if no control-rate was set. - -Sets the properties of the object, according to the `GstControlSources` that -(maybe) handle them and for the given timestamp. - -If this function fails, it is most likely the application developers fault. -Most probably the control sources are not setup correctly. -## `timestamp` -the time that should be processed - -# Returns - -`true` if the controller values could be applied to the object -properties, `false` otherwise - -Clear the parent of `self`, removing the associated reference. -This function decreases the refcount of `self`. - -MT safe. Grabs and releases `self`'s lock. - -Decrements the reference count on `self`. If reference count hits -zero, destroy `self`. This function does not take the lock -on `self` as it relies on atomic refcounting. - -The unref method should never be called with the LOCK held since -this might deadlock the dispose function. - -The deep notify signal is used to be notified of property changes. It is -typically attached to the toplevel bin to receive notifications from all -the elements contained in that bin. -## `prop_object` -the object that originated the signal -## `prop` -the property that changed - -The parent of the object. Please note, that when changing the 'parent' -property, we don't emit `glib::object::Object::notify` and `Object::deep-notify` -signals due to locking issues. In some cases one can use -`Bin::element-added` or `Bin::element-removed` signals on the parent to -achieve a similar effect. - -The parent of the object. Please note, that when changing the 'parent' -property, we don't emit `glib::object::Object::notify` and `Object::deep-notify` -signals due to locking issues. In some cases one can use -`Bin::element-added` or `Bin::element-removed` signals on the parent to -achieve a similar effect. - -The standard flags that an gstobject may have. - -the object is expected to stay alive even -after `gst_deinit` has been called and so should be ignored by leak -detection tools. (Since: 1.10) - -subclasses can add additional flags starting from this flag - -A `Element` is linked to other elements via "pads", which are extremely -light-weight generic link points. - -Pads have a `PadDirection`, source pads produce data, sink pads consume -data. - -Pads are typically created from a `PadTemplate` with -`Pad::new_from_template` and are then added to a `Element`. This usually -happens when the element is created but it can also happen dynamically based -on the data that the element is processing or based on the pads that the -application requests. - -Pads without pad templates can be created with `Pad::new`, -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 -dataflow on the pads. - -`gst_pad_get_parent` will retrieve the `Element` that owns the pad. - -After two pads are retrieved from an element by `ElementExt::get_static_pad`, -the pads can be linked with `Pad::link`. (For quick links, -you can also use `ElementExt::link`, which will make the obvious -link for you if it's straightforward.). Pads can be unlinked again with -`PadExt::unlink`. `PadExt::get_peer` can be used to check what the pad is -linked to. - -Before dataflow is possible on the pads, they need to be activated with -`PadExt::set_active`. - -`Pad::query` and `Pad::peer_query` can be used to query various -properties of the pad and the stream. - -To send a `Event` on a pad, use `Pad::send_event` and -`Pad::push_event`. Some events will be sticky on the pad, meaning that -after they pass on the pad they can be queried later with -`PadExt::get_sticky_event` and `Pad::sticky_events_foreach`. -`PadExt::get_current_caps` and `PadExt::has_current_caps` are convenience -functions to query the current sticky CAPS event on a pad. - -GstElements will use `Pad::push` and `Pad::pull_range` to push out -or pull in a buffer. - -The dataflow, events and queries that happen on a pad can be monitored with -probes that can be installed with `Pad::add_probe`. `PadExt::is_blocked` -can be used to check if a block probe is installed on the pad. -`PadExt::is_blocking` checks if the blocking probe is currently blocking the -pad. `Pad::remove_probe` is used to remove a previously installed probe -and unblock blocking probes if any. - -Pad have an offset that can be retrieved with `PadExt::get_offset`. This -offset will be applied to the running_time of all data passing over the pad. -`PadExt::set_offset` can be used to change the offset. - -Convenience functions exist to start, pause and stop the task on a pad with -`Pad::start_task`, `PadExt::pause_task` and `PadExt::stop_task` -respectively. - -# Implements - -[`PadExt`](trait@crate::PadExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`PadExtManual`](trait@crate::PadExtManual) - -Trait containing all `Pad` methods. - -# Implementors - -[`Pad`](struct@crate::Pad), [`ProxyPad`](struct@crate::ProxyPad) - -Creates a new pad with the given name in the given direction. -If name is `None`, a guaranteed unique name (across all pads) -will be assigned. -This function makes a copy of the name so you can safely free the name. -## `name` -the name of the new pad. -## `direction` -the `PadDirection` of the pad. - -# Returns - -a new `Pad`. - -MT safe. - -Creates a new pad with the given name from the given static template. -If name is `None`, a guaranteed unique name (across all pads) -will be assigned. -This function makes a copy of the name so you can safely free the name. -## `templ` -the `StaticPadTemplate` to use -## `name` -the name of the pad - -# Returns - -a new `Pad`. - -Creates a new pad with the given name from the given template. -If name is `None`, a guaranteed unique name (across all pads) -will be assigned. -This function makes a copy of the name so you can safely free the name. -## `templ` -the pad template to use -## `name` -the name of the pad - -# Returns - -a new `Pad`. - -Gets a string representing the given pad-link return. -## `ret` -a `PadLinkReturn` to get the name of. - -# Returns - -a static string with the name of the pad-link return. - -Activates or deactivates the given pad in `mode` via dispatching to the -pad's activatemodefunc. For use from within pad activation functions only. - -If you don't know what this is, you probably don't want to call it. -## `mode` -the requested activation mode -## `active` -whether or not the pad should be active. - -# Returns - -`true` if the operation was successful. - -MT safe. - -Be notified of different states of pads. The provided callback is called for -every state that matches `mask`. - -Probes are called in groups: First GST_PAD_PROBE_TYPE_BLOCK probes are -called, then others, then finally GST_PAD_PROBE_TYPE_IDLE. The only -exception here are GST_PAD_PROBE_TYPE_IDLE probes that are called -immediately if the pad is already idle while calling `Pad::add_probe`. -In each of the groups, probes are called in the order in which they were -added. -## `mask` -the probe mask -## `callback` -`GstPadProbeCallback` that will be called with notifications of - the pad state -## `user_data` -user data passed to the callback -## `destroy_data` -`GDestroyNotify` for user_data - -# Returns - -an id or 0 if no probe is pending. The id can be used to remove the -probe with `Pad::remove_probe`. When using GST_PAD_PROBE_TYPE_IDLE it can -happen that the probe can be run immediately and if the probe returns -GST_PAD_PROBE_REMOVE this functions returns 0. - -MT safe. - -Checks if the source pad and the sink pad are compatible so they can be -linked. -## `sinkpad` -the sink `Pad`. - -# Returns - -`true` if the pads can be linked. - -Chain a buffer to `self`. - -The function returns `FlowReturn::Flushing` if the pad was flushing. - -If the buffer type is not acceptable for `self` (as negotiated with a -preceding GST_EVENT_CAPS event), this function returns -`FlowReturn::NotNegotiated`. - -The function proceeds calling the chain function installed on `self` (see -`gst_pad_set_chain_function`) and the return value of that function is -returned to the caller. `FlowReturn::NotSupported` is returned if `self` has no -chain function. - -In all cases, success or failure, the caller loses its reference to `buffer` -after calling this function. -## `buffer` -the `Buffer` to send, return GST_FLOW_ERROR - if not. - -# Returns - -a `FlowReturn` from the pad. - -MT safe. - -Chain a bufferlist to `self`. - -The function returns `FlowReturn::Flushing` if the pad was flushing. - -If `self` was not negotiated properly with a CAPS event, this function -returns `FlowReturn::NotNegotiated`. - -The function proceeds calling the chainlist function installed on `self` (see -`gst_pad_set_chain_list_function`) and the return value of that function is -returned to the caller. `FlowReturn::NotSupported` is returned if `self` has no -chainlist function. - -In all cases, success or failure, the caller loses its reference to `list` -after calling this function. - -MT safe. -## `list` -the `BufferList` to send, return GST_FLOW_ERROR - if not. - -# Returns - -a `FlowReturn` from the pad. - -Check and clear the `PadFlags::NeedReconfigure` flag on `self` and return `true` -if the flag was set. - -# Returns - -`true` is the GST_PAD_FLAG_NEED_RECONFIGURE flag was set on `self`. - -Creates a stream-id for the source `Pad` `self` by combining the -upstream information with the optional `stream_id` of the stream -of `self`. `self` must have a parent `Element` and which must have zero -or one sinkpad. `stream_id` can only be `None` if the parent element -of `self` has only a single source pad. - -This function generates an unique stream-id by getting the upstream -stream-start event stream ID and appending `stream_id` to it. If the -element has no sinkpad it will generate an upstream stream-id by -doing an URI query on the element and in the worst case just uses -a random number. Source elements that don't implement the URI -handler interface should ideally generate a unique, deterministic -stream-id manually instead. - -Since stream IDs are sorted alphabetically, any numbers in the -stream ID should be printed with a fixed number of characters, -preceded by 0's, such as by using the format \%03u instead of \%u. -## `parent` -Parent `Element` of `self` -## `stream_id` -The stream-id - -# Returns - -A stream-id for `self`. `g_free` after usage. - -Creates a stream-id for the source `Pad` `self` by combining the -upstream information with the optional `stream_id` of the stream -of `self`. `self` must have a parent `Element` and which must have zero -or one sinkpad. `stream_id` can only be `None` if the parent element -of `self` has only a single source pad. - -This function generates an unique stream-id by getting the upstream -stream-start event stream ID and appending `stream_id` to it. If the -element has no sinkpad it will generate an upstream stream-id by -doing an URI query on the element and in the worst case just uses -a random number. Source elements that don't implement the URI -handler interface should ideally generate a unique, deterministic -stream-id manually instead. -## `parent` -Parent `Element` of `self` -## `stream_id` -The stream-id - -# Returns - -A stream-id for `self`. `g_free` after usage. - -Creates a stream-id for the source `Pad` `self` by combining the -upstream information with the optional `stream_id` of the stream -of `self`. `self` must have a parent `Element` and which must have zero -or one sinkpad. `stream_id` can only be `None` if the parent element -of `self` has only a single source pad. - -This function generates an unique stream-id by getting the upstream -stream-start event stream ID and appending `stream_id` to it. If the -element has no sinkpad it will generate an upstream stream-id by -doing an URI query on the element and in the worst case just uses -a random number. Source elements that don't implement the URI -handler interface should ideally generate a unique, deterministic -stream-id manually instead. -## `parent` -Parent `Element` of `self` -## `stream_id` -The stream-id -## `var_args` -parameters for the `stream_id` format string - -# Returns - -A stream-id for `self`. `g_free` after usage. - -Invokes the default event handler for the given pad. - -The EOS event will pause the task associated with `self` before it is forwarded -to all internally linked pads, - -The event is sent to all pads internally linked to `self`. This function -takes ownership of `event`. -## `parent` -the parent of `self` or `None` -## `event` -the `Event` to handle. - -# Returns - -`true` if the event was sent successfully. - -Calls `forward` for all internally linked pads of `self`. This function deals with -dynamically changing internal pads and will make sure that the `forward` -function is only called once for each pad. - -When `forward` returns `true`, no further pads will be processed. -## `forward` -a `GstPadForwardFunction` -## `user_data` -user data passed to `forward` - -# Returns - -`true` if one of the dispatcher functions returned `true`. - -Gets the capabilities of the allowed media types that can flow through -`self` and its peer. - -The allowed capabilities is calculated as the intersection of the results of -calling `PadExt::query_caps` on `self` and its peer. The caller owns a reference -on the resulting caps. - -# Returns - -the allowed `Caps` of the - pad link. Unref the caps when you no longer need it. This - function returns `None` when `self` has no peer. - -MT safe. - -Gets the capabilities currently configured on `self` with the last -`EventType::Caps` event. - -# Returns - -the current caps of the pad with -incremented ref-count or `None` when pad has no caps. Unref after usage. - -Gets the direction of the pad. The direction of the pad is -decided at construction time so this function does not take -the LOCK. - -# Returns - -the `PadDirection` of the pad. - -MT safe. - -Gets the private data of a pad. -No locking is performed in this function. - -# Returns - -a `gpointer` to the private data. - -Gets the `FlowReturn` return from the last data passed by this pad. - -Get the offset applied to the running time of `self`. `self` has to be a source -pad. - -# Returns - -the offset. - -Gets the template for `self`. - -# Returns - -the `PadTemplate` from which - this pad was instantiated, or `None` if this pad has no - template. Unref after usage. - -Gets the capabilities for `self`'s template. - -# Returns - -the `Caps` of this pad template. -Unref after usage. - -Gets the parent of `self`, cast to a `Element`. If a `self` has no parent or -its parent is not an element, return `None`. - -# Returns - -the parent of the pad. The -caller has a reference on the parent, so unref when you're finished -with it. - -MT safe. - -Gets the peer of `self`. This function refs the peer pad so -you need to unref it after use. - -# Returns - -the peer `Pad`. Unref after usage. - -MT safe. - -When `self` is flushing this function returns `FlowReturn::Flushing` -immediately and `buffer` is `None`. - -Calls the getrange function of `self`, see `GstPadGetRangeFunction` for a -description of a getrange function. If `self` has no getrange function -installed (see `gst_pad_set_getrange_function`) this function returns -`FlowReturn::NotSupported`. - -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 `buffer` points to a variable that points to a valid `Buffer`, the -buffer will be filled with the result data when this function returns -`FlowReturn::Ok`. If the provided buffer is larger than `size`, only -`size` bytes will be filled in the result buffer and its size will be updated -accordingly. - -Note that less than `size` bytes can be returned in `buffer` when, for example, -an EOS condition is near or when `buffer` is not large enough to hold `size` -bytes. The caller should check the result buffer size to get the result size. - -When this function returns any other result value than `FlowReturn::Ok`, `buffer` -will be unchanged. - -This is a lowlevel function. Usually `Pad::pull_range` is used. -## `offset` -The start offset of the buffer -## `size` -The length of the buffer -## `buffer` -a pointer to hold the `Buffer`, - returns `FlowReturn::Error` if `None`. - -# Returns - -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. -## `event_type` -the `EventType` that should be retrieved. -## `idx` -the index of the event - -# Returns - -a `Event` of type -`event_type` or `None` when no event of `event_type` was on -`self`. Unref after usage. - -Returns the current `Stream` for the `self`, or `None` if none has been -set yet, i.e. the pad has not received a stream-start event yet. - -This is a convenience wrapper around `PadExt::get_sticky_event` and -`Event::parse_stream`. - -Feature: `v1_10` - - -# Returns - -the current `Stream` for `self`, or `None`. - unref the returned stream when no longer needed. - -Returns the current stream-id for the `self`, or `None` if none has been -set yet, i.e. the pad has not received a stream-start event yet. - -This is a convenience wrapper around `PadExt::get_sticky_event` and -`Event::parse_stream_start`. - -The returned stream-id string should be treated as an opaque string, its -contents should not be interpreted. - -# Returns - -a newly-allocated copy of the stream-id for - `self`, or `None`. `g_free` the returned string when no longer - needed. - -Get `self` task state. If no task is currently -set, `TaskState::Stopped` is returned. - -Feature: `v1_12` - - -# Returns - -The current state of `self`'s task. - -Check if `self` has caps set on it with a `EventType::Caps` event. - -# Returns - -`true` when `self` has caps associated with it. - -Query if a pad is active - -# Returns - -`true` if the pad is active. - -MT safe. - -Checks if the pad is blocked or not. This function returns the -last requested state of the pad. It is not certain that the pad -is actually blocking at this point (see `PadExt::is_blocking`). - -# Returns - -`true` if the pad is blocked. - -MT safe. - -Checks if the pad is blocking or not. This is a guaranteed state -of whether the pad is actually blocking on a `Buffer` or a `Event`. - -# Returns - -`true` if the pad is blocking. - -MT safe. - -Checks if a `self` is linked to another pad or not. - -# Returns - -`true` if the pad is linked, `false` otherwise. - -MT safe. - -Gets an iterator for the pads to which the given pad is linked to inside -of the parent element. - -Each `Pad` element yielded by the iterator will have its refcount increased, -so unref after use. - -Free-function: gst_iterator_free - -# Returns - -a new `Iterator` of `Pad` - or `None` when the pad does not have an iterator function - configured. Use `Iterator::free` after usage. - -Iterate the list of pads to which the given pad is linked to inside of -the parent element. -This is the default handler, and thus returns an iterator of all of the -pads inside the parent element with opposite direction. - -The caller must free this iterator after use with `Iterator::free`. -## `parent` -the parent of `self` or `None` - -# Returns - -a `Iterator` of `Pad`, or `None` if `self` -has no parent. Unref each returned pad with `GstObjectExt::unref`. - -Links the source pad and the sink pad. -## `sinkpad` -the sink `Pad` to link. - -# Returns - -A result code indicating if the connection worked or - what went wrong. - -MT Safe. - -Links the source pad and the sink pad. - -This variant of `Pad::link` provides a more granular control on the -checks being done when linking. While providing some considerable speedups -the caller of this method must be aware that wrong usage of those flags -can cause severe issues. Refer to the documentation of `PadLinkCheck` -for more information. - -MT Safe. -## `sinkpad` -the sink `Pad` to link. -## `flags` -the checks to validate when linking - -# Returns - -A result code indicating if the connection worked or - what went wrong. - -Links `self` to `sink`, creating any `GhostPad`'s in between as necessary. - -This is a convenience function to save having to create and add intermediate -`GhostPad`'s as required for linking across `Bin` boundaries. - -If `self` or `sink` pads don't have parent elements or do not share a common -ancestor, the link will fail. - -Feature: `v1_10` - -## `sink` -a `Pad` - -# Returns - -whether the link succeeded. - -Links `self` to `sink`, creating any `GhostPad`'s in between as necessary. - -This is a convenience function to save having to create and add intermediate -`GhostPad`'s as required for linking across `Bin` boundaries. - -If `self` or `sink` pads don't have parent elements or do not share a common -ancestor, the link will fail. - -Calling `PadExt::link_maybe_ghosting_full` with -`flags` == `PadLinkCheck::Default` is the recommended way of linking -pads with safety checks applied. - -Feature: `v1_10` - -## `sink` -a `Pad` -## `flags` -some `PadLinkCheck` flags - -# Returns - -whether the link succeeded. - -Mark a pad for needing reconfiguration. The next call to -`PadExt::check_reconfigure` will return `true` after this call. - -Check the `PadFlags::NeedReconfigure` flag on `self` and return `true` -if the flag was set. - -# Returns - -`true` is the GST_PAD_FLAG_NEED_RECONFIGURE flag is set on `self`. - -Pause the task of `self`. This function will also wait until the -function executed by the task is finished if this function is not -called from the task function. - -# Returns - -a `true` if the task could be paused or `false` when the pad -has no task. - -Performs `Pad::query` on the peer of `self`. - -The caller is responsible for both the allocation and deallocation of -the query structure. -## `query` -the `Query` to perform. - -# Returns - -`true` if the query could be performed. This function returns `false` -if `self` has no peer. - -Check if the peer of `self` accepts `caps`. If `self` has no peer, this function -returns `true`. -## `caps` -a `Caps` to check on the pad - -# Returns - -`true` if the peer of `self` can accept the caps or `self` has no peer. - -Gets the capabilities of the peer connected to this pad. Similar to -`PadExt::query_caps`. - -When called on srcpads `filter` contains the caps that -upstream could produce in the order preferred by upstream. When -called on sinkpads `filter` contains the caps accepted by -downstream in the preferred order. `filter` might be `None` but -if it is not `None` the returned caps will be a subset of `filter`. -## `filter` -a `Caps` filter, or `None`. - -# Returns - -the caps of the peer pad with incremented -ref-count. When there is no peer pad, this function returns `filter` or, -when `filter` is `None`, ANY caps. - -Queries the peer pad of a given sink pad to convert `src_val` in `src_format` -to `dest_format`. -## `src_format` -a `Format` to convert from. -## `src_val` -a value to convert. -## `dest_format` -the `Format` to convert to. -## `dest_val` -a pointer to the result. - -# Returns - -`true` if the query could be performed. - -Queries the peer pad of a given sink pad for the total stream duration. -## `format` -the `Format` requested -## `duration` -a location in which to store the total - duration, or `None`. - -# Returns - -`true` if the query could be performed. - -Queries the peer of a given sink pad for the stream position. -## `format` -the `Format` requested -## `cur` -a location in which to store the current - position, or `None`. - -# Returns - -`true` if the query could be performed. - -Checks if all internally linked pads of `self` accepts the caps in `query` and -returns the intersection of the results. - -This function is useful as a default accept caps query function for an element -that can handle any stream format, but requires caps that are acceptable for -all opposite pads. -## `query` -an ACCEPT_CAPS `Query`. - -# Returns - -`true` if `query` could be executed - -Calls `PadExt::query_caps` for all internally linked pads of `self` and returns -the intersection of the results. - -This function is useful as a default caps query function for an element -that can handle any stream format, but requires all its pads to have -the same caps. Two such elements are tee and adder. -## `query` -a CAPS `Query`. - -# Returns - -`true` if `query` could be executed - -Pulls a `buffer` from the peer pad or fills up a provided buffer. - -This function will first trigger the pad block signal if it was -installed. - -When `self` is not linked `FlowReturn::NotLinked` is returned else this -function returns the result of `Pad::get_range` on the peer pad. -See `Pad::get_range` for a list of return values and for the -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 -returns any other result value, `buffer` will still point to `None`. - -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 -`FlowReturn::Ok`. When this function returns any other result value, -`buffer` will be unchanged. If the provided buffer is larger than `size`, only -`size` bytes will be filled in the result buffer and its size will be updated -accordingly. - -Note that less than `size` bytes can be returned in `buffer` when, for example, -an EOS condition is near or when `buffer` is not large enough to hold `size` -bytes. The caller should check the result buffer size to get the result size. -## `offset` -The start offset of the buffer -## `size` -The length of the buffer -## `buffer` -a pointer to hold the `Buffer`, returns - GST_FLOW_ERROR if `None`. - -# Returns - -a `FlowReturn` from the peer pad. - -MT safe. - -Pushes a buffer to the peer of `self`. - -This function will call installed block probes before triggering any -installed data probes. - -The function proceeds calling `Pad::chain` on the peer pad and returns -the value from that function. If `self` has no peer, `FlowReturn::NotLinked` will -be returned. - -In all cases, success or failure, the caller loses its reference to `buffer` -after calling this function. -## `buffer` -the `Buffer` to push returns GST_FLOW_ERROR - if not. - -# Returns - -a `FlowReturn` from the peer pad. - -MT safe. - -Sends the event to the peer of the given pad. This function is -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` -the `Event` to send to the pad. - -# Returns - -`true` if the event was handled. - -MT safe. - -Pushes a buffer list to the peer of `self`. - -This function will call installed block probes before triggering any -installed data probes. - -The function proceeds calling the chain function on the peer pad and returns -the value from that function. If `self` has no peer, `FlowReturn::NotLinked` will -be returned. If the peer pad does not have any installed chainlist function -every group buffer of the list will be merged into a normal `Buffer` and -chained via `Pad::chain`. - -In all cases, success or failure, the caller loses its reference to `list` -after calling this function. -## `list` -the `BufferList` to push returns GST_FLOW_ERROR - if not. - -# Returns - -a `FlowReturn` from the peer pad. - -MT safe. - -Dispatches a query to a pad. The query should have been allocated by the -caller via one of the type-specific allocation functions. The element that -the pad belongs to is responsible for filling the query with an appropriate -response, which should then be parsed with a type-specific query parsing -function. - -Again, the caller is responsible for both the allocation and deallocation of -the query structure. - -Please also note that some queries might need a running pipeline to work. -## `query` -the `Query` to perform. - -# Returns - -`true` if the query could be performed. - -Check if the given pad accepts the caps. -## `caps` -a `Caps` to check on the pad - -# Returns - -`true` if the pad can accept the caps. - -Gets the capabilities this pad can produce or consume. -Note that this method doesn't necessarily return the caps set by sending a -`Event::new_caps` - use `PadExt::get_current_caps` for that instead. -gst_pad_query_caps returns all possible caps a pad can operate with, using -the pad's CAPS query function, If the query fails, this function will return -`filter`, if not `None`, otherwise ANY. - -When called on sinkpads `filter` contains the caps that -upstream could produce in the order preferred by upstream. When -called on srcpads `filter` contains the caps accepted by -downstream in the preferred order. `filter` might be `None` but -if it is not `None` the returned caps will be a subset of `filter`. - -Note that this function does not return writable `Caps`, use -`gst_caps_make_writable` before modifying the caps. -## `filter` -suggested `Caps`, or `None` - -# Returns - -the caps of the pad with incremented ref-count. - -Queries a pad to convert `src_val` in `src_format` to `dest_format`. -## `src_format` -a `Format` to convert from. -## `src_val` -a value to convert. -## `dest_format` -the `Format` to convert to. -## `dest_val` -a pointer to the result. - -# Returns - -`true` if the query could be performed. - -Invokes the default query handler for the given pad. -The query is sent to all pads internally linked to `self`. Note that -if there are many possible sink pads that are internally linked to -`self`, only one will be sent the query. -Multi-sinkpad elements should implement custom query handlers. -## `parent` -the parent of `self` or `None` -## `query` -the `Query` to handle. - -# Returns - -`true` if the query was performed successfully. - -Queries a pad for the total stream duration. -## `format` -the `Format` requested -## `duration` -a location in which to store the total - duration, or `None`. - -# Returns - -`true` if the query could be performed. - -Queries a pad for the stream position. -## `format` -the `Format` requested -## `cur` -A location in which to store the current position, or `None`. - -# Returns - -`true` if the query could be performed. - -Remove the probe with `id` from `self`. - -MT safe. -## `id` -the probe id to remove - -Sends the event to the pad. This function can be used -by applications to send events in the pipeline. - -If `self` is a source pad, `event` should be an upstream event. If `self` is a -sink pad, `event` should be a downstream event. For example, you would not -send a `EventType::Eos` on a src pad; EOS events only propagate downstream. -Furthermore, some downstream events have to be serialized with data flow, -like EOS, while some can travel out-of-band, like `EventType::FlushStart`. If -the event needs to be serialized with data flow, this function will take the -pad's stream lock while calling its event function. - -To find out whether an event type is upstream, downstream, or downstream and -serialized, see `EventTypeFlags`, `EventType::get_flags`, -`GST_EVENT_IS_UPSTREAM`, `GST_EVENT_IS_DOWNSTREAM`, and -`GST_EVENT_IS_SERIALIZED`. Note that in practice that an application or -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` -the `Event` to send to the pad. - -# Returns - -`true` if the event was handled. - -Sets the given activate function for `self`. The activate function will -dispatch to `PadExt::activate_mode` to perform the actual activation. -Only makes sense to set on sink pads. - -Call this function if your sink pad can start a pull-based task. -## `activate` -the `GstPadActivateFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `activate` will not be used anymore. - -Sets the given activate_mode function for the pad. An activate_mode function -prepares the element for data passing. -## `activatemode` -the `GstPadActivateModeFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `activatemode` will not be used anymore. - -Activates or deactivates the given pad. -Normally called from within core state change functions. - -If `active`, makes sure the pad is active. If it is already active, either in -push or pull mode, just return. Otherwise dispatches to the pad's activate -function to perform the actual activation. - -If not `active`, calls `PadExt::activate_mode` with the pad's current mode -and a `false` argument. -## `active` -whether or not the pad should be active. - -# Returns - -`true` if the operation was successful. - -MT safe. - -Sets the given chain function for the pad. The chain function is called to -process a `Buffer` input buffer. see `GstPadChainFunction` for more details. -## `chain` -the `GstPadChainFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `chain` will not be used anymore. - -Sets the given chain list function for the pad. The chainlist function is -called to process a `BufferList` input buffer list. See -`GstPadChainListFunction` for more details. -## `chainlist` -the `GstPadChainListFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `chainlist` will not be used anymore. - -Set the given private data gpointer on the pad. -This function can only be used by the element that owns the pad. -No locking is performed in this function. -## `priv_` -The private data to attach to the pad. - -Sets the given event handler for the pad. -## `event` -the `GstPadEventFullFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `event` will not be used anymore. - -Sets the given event handler for the pad. -## `event` -the `GstPadEventFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `event` will not be used anymore. - -Sets the given getrange function for the pad. The getrange function is -called to produce a new `Buffer` to start the processing pipeline. see -`GstPadGetRangeFunction` for a description of the getrange function. -## `get` -the `GstPadGetRangeFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `get` will not be used anymore. - -Sets the given internal link iterator function for the pad. -## `iterintlink` -the `GstPadIterIntLinkFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `iterintlink` will not be used anymore. - -Sets the given link function for the pad. It will be called when -the pad is linked with another pad. - -The return value `PadLinkReturn::Ok` should be used when the connection can be -made. - -The return value `PadLinkReturn::Refused` should be used when the connection -cannot be made for some reason. - -If `link` is installed on a source pad, it should call the `GstPadLinkFunction` -of the peer sink pad, if present. -## `link` -the `GstPadLinkFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `link` will not be used anymore. - -Set the offset that will be applied to the running time of `self`. -## `offset` -the offset - -Set the given query function for the pad. -## `query` -the `GstPadQueryFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `query` will not be used anymore. - -Sets the given unlink function for the pad. It will be called -when the pad is unlinked. - -Note that the pad's lock is already held when the unlink -function is called, so most pad functions cannot be called -from within the callback. -## `unlink` -the `GstPadUnlinkFunction` to set. -## `user_data` -user_data passed to `notify` -## `notify` -notify called when `unlink` will not be used anymore. - -Starts a task that repeatedly calls `func` with `user_data`. This function -is mostly used in pad activation functions to start the dataflow. -The `GST_PAD_STREAM_LOCK` of `self` will automatically be acquired -before `func` is called. -## `func` -the task function to call -## `user_data` -user data passed to the task function -## `notify` -called when `user_data` is no longer referenced - -# Returns - -a `true` if the task could be started. - -Iterates all sticky events on `self` and calls `foreach_func` for every -event. If `foreach_func` returns `false` the iteration is immediately stopped. -## `foreach_func` -the `GstPadStickyEventsForeachFunction` that - should be called for every event. -## `user_data` -the optional user data. - -Stop the task of `self`. This function will also make sure that the -function executed by the task will effectively stop if not called -from the GstTaskFunction. - -This function will deadlock if called from the GstTaskFunction of -the task. Use `Task::pause` instead. - -Regardless of whether the pad has a task, the stream lock is acquired and -released so as to ensure that streaming through this pad has finished. - -# Returns - -a `true` if the task could be stopped or `false` on error. - -Store the sticky `event` on `self` -## `event` -a `Event` - -# Returns - -`FlowReturn::Ok` on success, `FlowReturn::Flushing` when the pad -was flushing or `FlowReturn::Eos` when the pad was EOS. - -Unlinks the source pad from the sink pad. Will emit the `Pad::unlinked` -signal on both pads. -## `sinkpad` -the sink `Pad` to unlink. - -# Returns - -`true` if the pads were unlinked. This function returns `false` if -the pads were not linked together. - -MT safe. - -A helper function you can use that sets the FIXED_CAPS flag -This way the default CAPS query will always return the negotiated caps -or in case the pad is not negotiated, the padtemplate caps. - -The negotiated caps are the caps of the last CAPS event that passed on the -pad. Use this function on a pad that, once it negotiated to a CAPS, cannot -be renegotiated to something else. - -Signals that a pad has been linked to the peer pad. -## `peer` -the peer pad that has been connected - -Signals that a pad has been unlinked from the peer pad. -## `peer` -the peer pad that has been disconnected - -The offset that will be applied to the running time of the pad. - -The offset that will be applied to the running time of the pad. - -The direction of a pad. - -direction is unknown. - -the pad is a source pad. - -the pad is a sink pad. - -Pad state flags - -is dataflow on a pad blocked - -is pad flushing - -is pad in EOS state - -is pad currently blocking on a buffer or event - -ensure that there is a parent object before calling - into the pad callbacks. - -the pad should be reconfigured/renegotiated. - The flag has to be unset manually after - reconfiguration happened. - -the pad has pending events - -the pad is using fixed caps. This means that - once the caps are set on the pad, the default caps query function - will only return those caps. - -the default event and query handler will forward - all events and queries to the internally linked pads - instead of discarding them. - -the default query handler will forward - allocation queries to the internally linked pads - instead of discarding them. - -the default query handler will forward - scheduling queries to the internally linked pads - instead of discarding them. - -the default accept-caps handler will check - it the caps intersect the query-caps result instead - of checking for a subset. This is interesting for - parsers that can accept incompletely specified caps. - -the default accept-caps handler will use - the template pad caps instead of query caps to - compare with the accept caps. Use this in combination - with `PadFlags::AcceptIntersect`. (Since: 1.6) - -offset to define more flags - -The amount of checking to be done when linking pads. [`Caps`](Self::Caps) -and [`TemplateCaps`](Self::TemplateCaps) are mutually exclusive. If both are -specified, expensive but safe [`Caps`](Self::Caps) are performed. - -> Only disable some of the checks if you are 100% certain you know the link -> will not fail because of hierarchy/caps compatibility failures. If uncertain, -> use the default checks (`PadLinkCheck::Default`) or the regular methods -> for linking the pads. - -Don't check hierarchy or caps compatibility. - -Check the pads have same parents/grandparents. - Could be omitted if it is already known that the two elements that own the - pads are in the same bin. - -Check if the pads are compatible by using - their template caps. This is much faster than [`Caps`](Self::Caps), but - would be unsafe e.g. if one pad has `GST_CAPS_ANY`. - -Check if the pads are compatible by comparing the - caps returned by `PadExt::query_caps`. - -Disables pushing a reconfigure event when pads are - linked. - -The default checks done when linking - pads (i.e. the ones used by `Pad::link`). - -Result values from gst_pad_link and friends. - -link succeeded - -pads have no common grandparent - -pad was already linked - -pads have wrong direction - -pads do not have common format - -pads cannot cooperate in scheduling - -refused for some reason - -The status of a GstPad. After activating a pad, which usually happens when the -parent element goes from READY to PAUSED, the GstPadMode defines if the -pad operates in push or pull mode. - -Pad will not handle dataflow - -Pad handles dataflow in downstream push mode - -Pad handles dataflow in upstream pull mode - -Indicates when this pad will become available. - -the pad is always available - -the pad will become available depending on the media stream - -the pad is only available on request with - `ElementExt::request_pad`. - -Different return values for the `GstPadProbeCallback`. - -drop data in data probes. For push mode this means that - the data item is not sent downstream. For pull mode, it means that - the data item is not passed upstream. In both cases, no other probes - are called for this item and `FlowReturn::Ok` or `true` is returned to the - caller. - -normal probe return value. This leaves the probe in - place, and defers decisions about dropping or passing data to other - probes, if any. If there are no other probes, the default behaviour - for the probe type applies ('block' for blocking probes, - and 'pass' for non-blocking probes). - -remove this probe. - -pass the data item in the block probe and block on the - next item. - -Data has been handled in the probe and will not be - forwarded further. For events and buffers this is the same behaviour as - `PadProbeReturn::Drop` (except that in this case you need to unref the buffer - or event yourself). For queries it will also return `true` to the caller. - The probe can also modify the `FlowReturn` value by using the - `GST_PAD_PROBE_INFO_FLOW_RETURN`() accessor. - Note that the resulting query must contain valid entries. - Since: 1.6 - -The different probing types that can occur. When either one of -[`Idle`](Self::Idle) or [`Block`](Self::Block) is used, the probe will be a -blocking probe. - -invalid probe type - -probe idle pads and block while the callback is called - -probe and block pads - -probe buffers - -probe buffer lists - -probe downstream events - -probe upstream events - -probe flush events. This probe has to be - explicitly enabled and is not included in the - @[`EventDownstream`](Self::EventDownstream) or - @[`EventUpstream`](Self::EventUpstream) probe types. - -probe downstream queries - -probe upstream queries - -probe push - -probe pull - -probe and block at the next opportunity, at data flow or when idle - -probe downstream data (buffers, buffer lists, and events) - -probe upstream data (events) - -probe upstream and downstream data (buffers, buffer lists, and events) - -probe and block downstream data (buffers, buffer lists, and events) - -probe and block upstream data (events) - -probe upstream and downstream events - -probe upstream and downstream queries - -probe upstream events and queries and downstream buffers, buffer lists, events and queries - -probe push and pull - -Padtemplates describe the possible media types a pad or an elementfactory can -handle. This allows for both inspection of handled types before loading the -element plugin as well as identifying pads on elements that are not yet -created (request or sometimes pads). - -Pad and PadTemplates have `Caps` attached to it to describe the media type -they are capable of dealing with. `PadTemplate::get_caps` or -GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not -possible to modify the caps of a padtemplate after creation. - -PadTemplates have a `PadPresence` property which identifies the lifetime -of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also -the direction of the pad can be retrieved from the `PadTemplate` with -GST_PAD_TEMPLATE_DIRECTION(). - -The GST_PAD_TEMPLATE_NAME_TEMPLATE () is important for GST_PAD_REQUEST pads -because it has to be used as the name in the `ElementExt::get_request_pad` -call to instantiate a pad from this template. - -Padtemplates can be created with `PadTemplate::new` or with -gst_static_pad_template_get (), which creates a `PadTemplate` from a -`StaticPadTemplate` that can be filled with the -convenient GST_STATIC_PAD_TEMPLATE() macro. - -A padtemplate can be used to create a pad (see `Pad::new_from_template` -or gst_pad_new_from_static_template ()) or to add to an element class -(see gst_element_class_add_static_pad_template ()). - -The following code example shows the code to create a pad from a padtemplate. - -```C - GstStaticPadTemplate my_template = - GST_STATIC_PAD_TEMPLATE ( - "sink", // the name of the pad - GST_PAD_SINK, // the direction of the pad - GST_PAD_ALWAYS, // when this pad will be present - GST_STATIC_CAPS ( // the capabilities of the padtemplate - "audio/x-raw, " - "channels = (int) [ 1, 6 ]" - ) - ); - void - my_method (void) - { - GstPad *pad; - pad = gst_pad_new_from_static_template (&my_template, "sink"); - ... - } -``` - -The following example shows you how to add the padtemplate to an -element class, this is usually done in the class_init of the class: - -```C - static void - my_element_class_init (GstMyElementClass *klass) - { - GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass); - - gst_element_class_add_static_pad_template (gstelement_class, &my_template); - } -``` - -# Implements - -[`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`] - -Creates a new pad template with a name according to the given template -and with the given arguments. -## `name_template` -the name template. -## `direction` -the `PadDirection` of the template. -## `presence` -the `PadPresence` of the pad. -## `caps` -a `Caps` set for the template. - -# Returns - -a new `PadTemplate`. - -Converts a `StaticPadTemplate` into a `PadTemplate` with a type. - -Feature: `v1_14` - -## `pad_template` -the static pad template -## `pad_type` -The `glib::Type` of the pad to create - -# Returns - -a new `PadTemplate`. - -Creates a new pad template with a name according to the given template -and with the given arguments. - -Feature: `v1_14` - -## `name_template` -the name template. -## `direction` -the `PadDirection` of the template. -## `presence` -the `PadPresence` of the pad. -## `caps` -a `Caps` set for the template. -## `pad_type` -The `glib::Type` of the pad to create - -# Returns - -a new `PadTemplate`. - -Gets the capabilities of the pad template. - -# Returns - -the `Caps` of the pad template. -Unref after usage. - -See `PadTemplate::set_documentation_caps`. - -Feature: `v1_18` - - -# Returns - -The caps to document. For convenience, this will return - `PadTemplate::get_caps` when no documentation caps were set. - -Emit the pad-created signal for this template when created by this pad. -## `pad` -the `Pad` that created it - -Certain elements will dynamically construct the caps of their -pad templates. In order not to let environment-specific information -into the documentation, element authors should use this method to -expose "stable" caps to the reader. - -Feature: `v1_18` - -## `caps` -the documented capabilities - -This signal is fired when an element creates a pad from this template. -## `pad` -the pad that was created. - -The capabilities of the pad described by the pad template. - -The capabilities of the pad described by the pad template. - -The direction of the pad described by the pad template. - -The direction of the pad described by the pad template. - -The type of the pad described by the pad template. - -Feature: `v1_14` - - -The type of the pad described by the pad template. - -Feature: `v1_14` - - -The name template of the pad template. - -The name template of the pad template. - -When the pad described by the pad template will become available. - -When the pad described by the pad template will become available. - -Opaque structure. - -Allocates a parse context for use with `gst_parse_launch_full` or -`gst_parse_launchv_full`. - -Free-function: gst_parse_context_free - -# Returns - -a newly-allocated parse context. Free - with `ParseContext::free` when no longer needed. - -Copies the `self`. - -Feature: `v1_12_1` - - -# Returns - -A copied `ParseContext` - -Frees a parse context previously allocated with `ParseContext::new`. - -Retrieve missing elements from a previous run of `gst_parse_launch_full` -or `gst_parse_launchv_full`. Will only return results if an error code -of `ParseError::NoSuchElement` was returned. - -# Returns - -a - `None`-terminated array of element factory name strings of missing - elements. Free with `g_strfreev` when no longer needed. - -The different parsing errors that can occur. - -A syntax error occurred. - -The description contained an unknown element - -An element did not have a specified property - -There was an error linking two pads. - -There was an error setting a property - -An empty bin was specified. - -An empty description was specified - -A delayed link did not get resolved. - -Parsing options. - -Do not use any special parsing options. - -Always return `None` when an error occurs - (default behaviour is to return partially constructed bins or elements - in some cases) - -If a bin only has a single element, - just return the element. - -If more than one toplevel element is described - by the pipeline description string, put them in a `Bin` instead of a - `Pipeline`. (Since: 1.10) - -A `Pipeline` is a special `Bin` used as the toplevel container for -the filter graph. The `Pipeline` will manage the selection and -distribution of a global `Clock` as well as provide a `Bus` to the -application. - -`Pipeline::new` is used to create a pipeline. when you are done with -the pipeline, use `GstObjectExt::unref` to free its resources including all -added `Element` objects (if not otherwise referenced). - -Elements are added and removed from the pipeline using the `Bin` -methods like `GstBinExt::add` and `GstBinExt::remove` (see `Bin`). - -Before changing the state of the `Pipeline` (see `Element`) a `Bus` -can be retrieved with `Pipeline::get_bus`. This bus can then be -used to receive `Message` from the elements in the pipeline. - -By default, a `Pipeline` will automatically flush the pending `Bus` -messages when going to the NULL state to ensure that no circular -references exist when no messages are read from the `Bus`. This -behaviour can be changed with `PipelineExt::set_auto_flush_bus`. - -When the `Pipeline` performs the PAUSED to PLAYING state change it will -select a clock for the elements. The clock selection algorithm will by -default select a clock provided by an element that is most upstream -(closest to the source). For live pipelines (ones that return -`StateChangeReturn::NoPreroll` from the `Element::set_state` call) this -will select the clock provided by the live source. For normal pipelines -this will select a clock provided by the sinks (most likely the audio -sink). If no element provides a clock, a default `SystemClock` is used. - -The clock selection can be controlled with the `PipelineExt::use_clock` -method, which will enforce a given clock on the pipeline. With -`PipelineExt::auto_clock` the default clock selection algorithm can be -restored. - -A `Pipeline` maintains a running time for the elements. The running -time is defined as the difference between the current clock time and -the base time. When the pipeline goes to READY or a flushing seek is -performed on it, the running time is reset to 0. When the pipeline is -set from PLAYING to PAUSED, the current clock time is sampled and used to -configure the base time for the elements when the pipeline is set -to PLAYING again. The effect is that the running time (as the difference -between the clock time and the base time) will count how much time was spent -in the PLAYING state. This default behaviour can be changed with the -`ElementExt::set_start_time` method. - -# Implements - -[`PipelineExt`](trait@crate::PipelineExt), [`GstBinExt`](trait@crate::GstBinExt), [`ElementExt`](trait@crate::ElementExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`ChildProxyExt`](trait@crate::ChildProxyExt), [`ElementExtManual`](trait@crate::ElementExtManual), [`ChildProxyExtManual`](trait@crate::ChildProxyExtManual) - -Trait containing all `Pipeline` methods. - -# Implementors - -[`Pipeline`](struct@crate::Pipeline) - -Create a new pipeline with the given name. -## `name` -name of new pipeline - -# Returns - -newly created GstPipeline - -MT safe. - -Let `self` select a clock automatically. This is the default -behaviour. - -Use this function if you previous forced a fixed clock with -`PipelineExt::use_clock` and want to restore the default -pipeline clock selection algorithm. - -MT safe. - -Check if `self` will automatically flush messages when going to -the NULL state. - -# Returns - -whether the pipeline will automatically flush its bus when -going from READY to NULL state or not. - -MT safe. - -Gets the `Bus` of `self`. The bus allows applications to receive -`Message` packets. - -# Returns - -a `Bus`, unref after usage. - -MT safe. - -Gets the current clock used by `self`. Users of object -oriented languages should use `PipelineExt::get_pipeline_clock` -to avoid confusion with `ElementExt::get_clock` which has a different behavior. - -Unlike `ElementExt::get_clock`, this function will always return a -clock, even if the pipeline is not in the PLAYING state. - -# Returns - -a `Clock`, unref after usage. - -Get the configured delay (see `PipelineExt::set_delay`). - -# Returns - -The configured delay. - -MT safe. - -Gets the latency that should be configured on the pipeline. See -`PipelineExt::set_latency`. - -# Returns - -Latency to configure on the pipeline or GST_CLOCK_TIME_NONE - -Gets the current clock used by `self`. - -Unlike `ElementExt::get_clock`, this function will always return a -clock, even if the pipeline is not in the PLAYING state. - -# Returns - -a `Clock`, unref after usage. - -Usually, when a pipeline goes from READY to NULL state, it automatically -flushes all pending messages on the bus, which is done for refcounting -purposes, to break circular references. - -This means that applications that update state using (async) bus messages -(e.g. do certain things when a pipeline goes from PAUSED to READY) might -not get to see messages when the pipeline is shut down, because they might -be flushed before they can be dispatched in the main thread. This behaviour -can be disabled using this function. - -It is important that all messages on the bus are handled when the -automatic flushing is disabled else memory leaks will be introduced. - -MT safe. -## `auto_flush` -whether or not to automatically flush the bus when -the pipeline goes from READY to NULL state - -Set the clock for `self`. The clock will be distributed -to all the elements managed by the pipeline. -## `clock` -the clock to set - -# Returns - -`true` if the clock could be set on the pipeline. `false` if - some element did not accept the clock. - -MT safe. - -Set the expected delay needed for all elements to perform the -PAUSED to PLAYING state change. `delay` will be added to the -base time of the elements so that they wait an additional `delay` -amount of time before starting to process buffers and cannot be -`GST_CLOCK_TIME_NONE`. - -This option is used for tuning purposes and should normally not be -used. - -MT safe. -## `delay` -the delay - -Sets the latency that should be configured on the pipeline. Setting -GST_CLOCK_TIME_NONE will restore the default behaviour of using the minimum -latency from the LATENCY query. Setting this is usually not required and -the pipeline will figure out an appropriate latency automatically. - -Setting a too low latency, especially lower than the minimum latency from -the LATENCY query, will most likely cause the pipeline to fail. -## `latency` -latency to configure - -Force `self` to use the given `clock`. The pipeline will -always use the given clock even if new clock providers are added -to this pipeline. - -If `clock` is `None` all clocking will be disabled which will make -the pipeline run as fast as possible. - -MT safe. -## `clock` -the clock to use - -Whether or not to automatically flush all messages on the -pipeline's bus when going from READY to NULL state. Please see -`PipelineExt::set_auto_flush_bus` for more information on this option. - -Whether or not to automatically flush all messages on the -pipeline's bus when going from READY to NULL state. Please see -`PipelineExt::set_auto_flush_bus` for more information on this option. - -The expected delay needed for elements to spin up to the -PLAYING state expressed in nanoseconds. -see `PipelineExt::set_delay` for more information on this option. - -The expected delay needed for elements to spin up to the -PLAYING state expressed in nanoseconds. -see `PipelineExt::set_delay` for more information on this option. - -Latency to configure on the pipeline. See `PipelineExt::set_latency`. - -Latency to configure on the pipeline. See `PipelineExt::set_latency`. - -Pipeline flags - -this pipeline works with a fixed clock - -offset to define more flags - -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 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`. - -Once you have a handle to a `Plugin` (e.g. from the `Registry`), you -can add any object that subclasses `PluginFeature`. - -Usually plugins are always automatically loaded so you don't need to call -`Plugin::load` explicitly to bring it into memory. There are options to -statically link plugins to an app or even use GStreamer without a plugin -repository in which case `Plugin::load` can be needed to bring the plugin -into memory. - -# Implements - -[`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`] - -Unrefs each member of `list`, then frees the list. -## `list` -list of `Plugin` - -Load the named plugin. Refs the plugin. -## `name` -name of plugin to load - -# Returns - -a reference to a loaded plugin, or -`None` on error. - -Loads the given plugin and refs it. Caller needs to unref after use. -## `filename` -the plugin filename to load - -# Returns - -a reference to the existing loaded GstPlugin, a -reference to the newly-loaded GstPlugin, or `None` if an error occurred. - -Registers a static plugin, ie. a plugin which is private to an application -or library and contained within the application or library (as opposed to -being shipped as a separate module file). - -You must make sure that GStreamer has been initialised (with `gst_init` or -via `gst_init_get_option_group`) before calling this function. -## `major_version` -the major version number of the GStreamer core that the - plugin was compiled for, you can just use GST_VERSION_MAJOR here -## `minor_version` -the minor version number of the GStreamer core that the - plugin was compiled for, you can just use GST_VERSION_MINOR here -## `name` -a unique name of the plugin (ideally prefixed with an application- or - library-specific namespace prefix in order to avoid name conflicts in - case a similar plugin with the same name ever gets added to GStreamer) -## `description` -description of the plugin -## `init_func` -pointer to the init function of this plugin. -## `version` -version string of the plugin -## `license` -effective license of plugin. Must be one of the approved licenses - (see `PluginDesc` above) or the plugin will not be registered. -## `source` -source module plugin belongs to -## `package` -shipped package plugin belongs to -## `origin` -URL to provider of plugin - -# Returns - -`true` if the plugin was registered correctly, otherwise `false`. - -Registers a static plugin, ie. a plugin which is private to an application -or library and contained within the application or library (as opposed to -being shipped as a separate module file) with a `GstPluginInitFullFunc` -which allows user data to be passed to the callback function (useful -for bindings). - -You must make sure that GStreamer has been initialised (with `gst_init` or -via `gst_init_get_option_group`) before calling this function. -## `major_version` -the major version number of the GStreamer core that the - plugin was compiled for, you can just use GST_VERSION_MAJOR here -## `minor_version` -the minor version number of the GStreamer core that the - plugin was compiled for, you can just use GST_VERSION_MINOR here -## `name` -a unique name of the plugin (ideally prefixed with an application- or - library-specific namespace prefix in order to avoid name conflicts in - case a similar plugin with the same name ever gets added to GStreamer) -## `description` -description of the plugin -## `init_full_func` -pointer to the init function with user data - of this plugin. -## `version` -version string of the plugin -## `license` -effective license of plugin. Must be one of the approved licenses - (see `PluginDesc` above) or the plugin will not be registered. -## `source` -source module plugin belongs to -## `package` -shipped package plugin belongs to -## `origin` -URL to provider of plugin -## `user_data` -gpointer to user data - -# Returns - -`true` if the plugin was registered correctly, otherwise `false`. - -Make GStreamer aware of external dependencies which affect the feature -set of this plugin (ie. the elements or typefinders associated with it). - -GStreamer will re-inspect plugins with external dependencies whenever any -of the external dependencies change. This is useful for plugins which wrap -other plugin systems, e.g. a plugin which wraps a plugin-based visualisation -library and makes visualisations available as GStreamer elements, or a -codec loader which exposes elements and/or caps dependent on what external -codec libraries are currently installed. -## `env_vars` -`None`-terminated array of environment variables affecting the - feature set of the plugin (e.g. an environment variable containing - paths where to look for additional modules/plugins of a library), - or `None`. Environment variable names may be followed by a path component - which will be added to the content of the environment variable, e.g. - "HOME/.mystuff/plugins". -## `paths` -`None`-terminated array of directories/paths where dependent files - may be, or `None`. -## `names` -`None`-terminated array of file names (or file name suffixes, - depending on `flags`) to be used in combination with the paths from - `paths` and/or the paths extracted from the environment variables in - `env_vars`, or `None`. -## `flags` -optional flags, or `PluginDependencyFlags::None` - -Make GStreamer aware of external dependencies which affect the feature -set of this plugin (ie. the elements or typefinders associated with it). - -GStreamer will re-inspect plugins with external dependencies whenever any -of the external dependencies change. This is useful for plugins which wrap -other plugin systems, e.g. a plugin which wraps a plugin-based visualisation -library and makes visualisations available as GStreamer elements, or a -codec loader which exposes elements and/or caps dependent on what external -codec libraries are currently installed. - -Convenience wrapper function for `Plugin::add_dependency` which -takes simple strings as arguments instead of string arrays, with multiple -arguments separated by predefined delimiters (see above). -## `env_vars` -one or more environment variables (separated by ':', ';' or ','), - or `None`. Environment variable names may be followed by a path component - which will be added to the content of the environment variable, e.g. - "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH" -## `paths` -one ore more directory paths (separated by ':' or ';' or ','), - or `None`. Example: "/usr/lib/mystuff/plugins" -## `names` -one or more file names or file name suffixes (separated by commas), - or `None` -## `flags` -optional flags, or `PluginDependencyFlags::None` - -Gets the plugin specific data cache. If it is `None` there is no cached data -stored. This is the case when the registry is getting rebuilt. - -# Returns - -The cached data as a -`Structure` or `None`. - -Get the long descriptive name of the plugin - -# Returns - -the long name of the plugin - -get the filename of the plugin - -# Returns - -the filename of the plugin - -get the license of the plugin - -# Returns - -the license of the plugin - -Get the short name of the plugin - -# Returns - -the name of the plugin - -get the URL where the plugin comes from - -# Returns - -the origin of the plugin - -get the package the plugin belongs to. - -# Returns - -the package of the plugin - -Get the release date (and possibly time) in form of a string, if available. - -For normal GStreamer plugin releases this will usually just be a date in -the form of "YYYY-MM-DD", while pre-releases and builds from git may contain -a time component after the date as well, in which case the string will be -formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z"). - -There may be plugins that do not have a valid release date set on them. - -# Returns - -the date string of the plugin, or `None` if not -available. - -get the source module the plugin belongs to. - -# Returns - -the source of the plugin - -get the version of the plugin - -# Returns - -the version of the plugin - -queries if the plugin is loaded into memory - -# Returns - -`true` is loaded, `false` otherwise - -Loads `self`. Note that the *return value* is the loaded plugin; `self` is -untouched. The normal use pattern of this function goes like this: - - -```text -GstPlugin *loaded_plugin; -loaded_plugin = gst_plugin_load (plugin); -// presumably, we're no longer interested in the potentially-unloaded plugin -gst_object_unref (plugin); -plugin = loaded_plugin; -``` - -# Returns - -a reference to a loaded plugin, or -`None` on error. - -Adds plugin specific data to cache. Passes the ownership of the structure to -the `self`. - -The cache is flushed every time the registry is rebuilt. -## `cache_data` -a structure containing the data to cache - - -Ignore enum members when generating - the plugins cache. This is useful if the members of the enum are generated - dynamically, in order not to expose incorrect documentation to the end user. - -Feature: `v1_18` - - -Flags used in connection with `Plugin::add_dependency`. - -no special flags - -recurse into subdirectories - -use paths - argument only if none of the environment variables is set - -interpret - filename argument as filter suffix and check all matching files in - the directory - -interpret - filename argument as filter prefix and check all matching files in - the directory. Since: 1.8. - -interpret - non-absolute paths as relative to the main executable directory. Since - 1.14. - -The plugin loading errors - -The plugin could not be loaded - -The plugin has unresolved dependencies - -The plugin has already be loaded from a different file - -This is a base class for anything that can be added to a `Plugin`. - -This is an Abstract Base Class, you cannot instantiate it. - -# Implements - -[`PluginFeatureExt`](trait@crate::PluginFeatureExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`PluginFeatureExtManual`](trait@crate::PluginFeatureExtManual) - -Trait containing all `PluginFeature` methods. - -# Implementors - -[`DeviceProviderFactory`](struct@crate::DeviceProviderFactory), [`ElementFactory`](struct@crate::ElementFactory), [`PluginFeature`](struct@crate::PluginFeature), [`TypeFindFactory`](struct@crate::TypeFindFactory) - -Copies the list of features. Caller should call [`list_free`](Self::list_free) -when done with the list. -## `list` -list - of `PluginFeature` - -# Returns - -a copy of `list`, - with each feature's reference count incremented. - -Debug the plugin feature names in `list`. -## `list` -a `glib::List` of - plugin features - -Unrefs each member of `list`, then frees the list. -## `list` -list - of `PluginFeature` - -Compares the two given `PluginFeature` instances. This function can be -used as a `GCompareFunc` when sorting by rank and then by name. -## `p1` -a `PluginFeature` -## `p2` -a `PluginFeature` - -# Returns - -negative value if the rank of p1 > the rank of p2 or the ranks are -equal but the name of p1 comes before the name of p2; zero if the rank -and names are equal; positive value if the rank of p1 < the rank of p2 or the -ranks are equal but the name of p2 comes before the name of p1 - -Checks whether the given plugin feature is at least - the required version -## `min_major` -minimum required major version -## `min_minor` -minimum required minor version -## `min_micro` -minimum required micro version - -# Returns - -`true` if the plugin feature has at least - the required version, otherwise `false`. - -Get the plugin that provides this feature. - -# Returns - -the plugin that provides this - feature, or `None`. Unref with `GstObjectExt::unref` when no - longer needed. - -Get the name of the plugin that provides this feature. - -# Returns - -the name of the plugin that provides this - feature, or `None` if the feature is not associated with a - plugin. - -Gets the rank of a plugin feature. - -# Returns - -The rank of the feature - -Loads the plugin containing `self` if it's not already loaded. `self` is -unaffected; use the return value instead. - -Normally this function is used like this: - -```C -GstPluginFeature *loaded_feature; - -loaded_feature = gst_plugin_feature_load (feature); -// presumably, we're no longer interested in the potentially-unloaded feature -gst_object_unref (feature); -feature = loaded_feature; -``` - -# Returns - -a reference to the loaded -feature, or `None` on error - -Specifies a rank for a plugin feature, so that autoplugging uses -the most appropriate feature. -## `rank` -rank value - higher number means more priority rank - -The plugin loading state - -Temporarily loaded plugins - -The plugin won't be scanned (again) - -This interface offers methods to query and manipulate parameter preset sets. -A preset is a bunch of property settings, together with meta data and a name. -The name of a preset serves as key for subsequent method calls to manipulate -single presets. -All instances of one type will share the list of presets. The list is created -on demand, if presets are not used, the list is not created. - -The interface comes with a default implementation that serves most plugins. -Wrapper plugins will override most methods to implement support for the -native preset format of those wrapped plugins. -One method that is useful to be overridden is `Preset::get_property_names`. -With that one can control which properties are saved and in which order. -When implementing support for read-only presets, one should set the vmethods -for `Preset::save_preset` and `Preset::delete_preset` to `None`. -Applications can use `Preset::is_editable` to check for that. - -The default implementation supports presets located in a system directory, -application specific directory and in the users home directory. When getting -a list of presets individual presets are read and overlaid in 1) system, -2) application and 3) user order. Whenever an earlier entry is newer, the -later entries will be updated. Since 1.8 you can also provide extra paths -where to find presets through the GST_PRESET_PATH environment variable. -Presets found in those paths will be considered as "app presets". - -# Implements - -[`PresetExt`](trait@crate::PresetExt) - -Trait containing all `Preset` methods. - -# Implementors - -[`Preset`](struct@crate::Preset) - -Gets the directory for application specific presets if set by the -application. - -# Returns - -the directory or `None`, don't free or modify -the string - -Sets an extra directory as an absolute path that should be considered when -looking for presets. Any presets in the application dir will shadow the -system presets. -## `app_dir` -the application specific preset dir - -# Returns - -`true` for success, `false` if the dir already has been set - -Delete the given preset. -## `name` -preset name to remove - -# Returns - -`true` for success, `false` if e.g. there is no preset with that `name` - -Gets the `value` for an existing meta data `tag`. Meta data `tag` names can be -something like e.g. "comment". Returned values need to be released when done. -## `name` -preset name -## `tag` -meta data item name -## `value` -value - -# Returns - -`true` for success, `false` if e.g. there is no preset with that `name` -or no value for the given `tag` - -Get a copy of preset names as a `None` terminated string array. - -# Returns - - - list with names, use `g_strfreev` after usage. - -Get a the names of the GObject properties that can be used for presets. - -# Returns - -an - array of property names which should be freed with `g_strfreev` after use. - -Check if one can add new presets, change existing ones and remove presets. - -# Returns - -`true` if presets are editable or `false` if they are static - -Load the given preset. -## `name` -preset name to load - -# Returns - -`true` for success, `false` if e.g. there is no preset with that `name` - -Renames a preset. If there is already a preset by the `new_name` it will be -overwritten. -## `old_name` -current preset name -## `new_name` -new preset name - -# Returns - -`true` for success, `false` if e.g. there is no preset with `old_name` - -Save the current object settings as a preset under the given name. If there -is already a preset by this `name` it will be overwritten. -## `name` -preset name to save - -# Returns - -`true` for success, `false` - -Sets a new `value` for an existing meta data item or adds a new item. Meta -data `tag` names can be something like e.g. "comment". Supplying `None` for the -`value` will unset an existing value. -## `name` -preset name -## `tag` -meta data item name -## `value` -new value - -# Returns - -`true` for success, `false` if e.g. there is no preset with that `name` - -The type of a `MessageType::Progress`. The progress messages inform the -application of the status of asynchronous tasks. - -A new task started. - -A task completed and a new one continues. - -A task completed. - -A task was canceled. - -A task caused an error. An error message is also - posted on the bus. - -The `Promise` object implements the container for values that may -be available later. i.e. a Future or a Promise in -. -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`. 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 [`crate::PromiseResult::Expired`] (XXX: @-reference does not belong to Promise!) state set by a call -to `Promise::expire` indicates to the consumer that a value will never -be produced and is intended to be called by a third party that implements -some notion of message handling such as `Bus`. -A callback can also be installed at `Promise` creation for -result changes with `Promise::new_with_change_func`. -The change callback can be used to chain `GstPromises`'s together as in the -following example. - -```C -const GstStructure *reply; -GstPromise *p; -if (gst_promise_wait (promise) != GST_PROMISE_RESULT_REPLIED) - return; // interrupted or expired value -reply = gst_promise_get_reply (promise); -if (error in reply) - return; // propagate error -p = gst_promise_new_with_change_func (another_promise_change_func, user_data, notify); -pass p to promise-using API -``` - -Each `Promise` starts out with a `PromiseResult` of -`PromiseResult::Pending` and only ever transitions once -into one of the other `PromiseResult`'s. - -In order to support multi-threaded code, `Promise::reply`, -`Promise::interrupt` and `Promise::expire` may all be from -different threads with some restrictions and the final result of the promise -is whichever call is made first. There are two restrictions on ordering: - -1. That `Promise::reply` and `Promise::interrupt` cannot be called -after `Promise::expire` -2. That `Promise::reply` and `Promise::interrupt` -cannot be called twice. - -The change function set with `Promise::new_with_change_func` is -called directly from either the `Promise::reply`, -`Promise::interrupt` or `Promise::expire` and can be called -from an arbitrary thread. `Promise` using APIs can restrict this to -a single thread or a subset of threads but that is entirely up to the API -that uses `Promise`. - -Feature: `v1_14` - - -Feature: `v1_14` - - -# Returns - -a new `Promise` - -`func` will be called exactly once when transitioning out of -`PromiseResult::Pending` into any of the other `PromiseResult` -states. - -Feature: `v1_14` - -## `func` -a `GstPromiseChangeFunc` to call -## `user_data` -argument to call `func` with -## `notify` -notification function that `user_data` is no longer needed - -# Returns - -a new `Promise` - -Expire a `self`. This will wake up any waiters with -`PromiseResult::Expired`. Called by a message loop when the parent -message is handled and/or destroyed (possibly unanswered). - -Feature: `v1_14` - - -Retrieve the reply set on `self`. `self` must be in -`PromiseResult::Replied` and the returned structure is owned by `self` - -Feature: `v1_14` - - -# Returns - -The reply set on `self` - -Interrupt waiting for a `self`. This will wake up any waiters with -`PromiseResult::Interrupted`. Called when the consumer does not want -the value produced anymore. - -Feature: `v1_14` - - -Set a reply on `self`. This will wake up any waiters with -`PromiseResult::Replied`. Called by the producer of the value to -indicate success (or failure). - -If `self` has already been interrupted by the consumer, then this reply -is not visible to the consumer. - -Feature: `v1_14` - -## `s` -a `Structure` with the the reply contents - -Wait for `self` to move out of the `PromiseResult::Pending` state. -If `self` is not in `PromiseResult::Pending` then it will return -immediately with the current result. - -Feature: `v1_14` - - -# Returns - -the result of the promise - -The result of a `Promise` - -Initial state. Waiting for transition to any - other state. - -Interrupted by the consumer as it doesn't - want the value anymore. - -A producer marked a reply - -The promise expired (the carrying object - lost all refs) and the promise will never be fulfilled. - -Feature: `v1_14` - - - - -# Implements - -[`ProxyPadExt`](trait@crate::ProxyPadExt), [`PadExt`](trait@crate::PadExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`ProxyPadExtManual`](trait@crate::ProxyPadExtManual), [`PadExtManual`](trait@crate::PadExtManual) - -Trait containing all `ProxyPad` methods. - -# Implementors - -[`GhostPad`](struct@crate::GhostPad), [`ProxyPad`](struct@crate::ProxyPad) - -Invoke the default chain function of the proxy pad. -## `pad` -a sink `Pad`, returns GST_FLOW_ERROR if not. -## `parent` -the parent of `pad` or `None` -## `buffer` -the `Buffer` to send, return GST_FLOW_ERROR - if not. - -# Returns - -a `FlowReturn` from the pad. - -Invoke the default chain list function of the proxy pad. -## `pad` -a sink `Pad`, returns GST_FLOW_ERROR if not. -## `parent` -the parent of `pad` or `None` -## `list` -the `BufferList` to send, return GST_FLOW_ERROR - if not. - -# Returns - -a `FlowReturn` from the pad. - -Invoke the default getrange function of the proxy pad. -## `pad` -a src `Pad`, returns `FlowReturn::Error` if not. -## `parent` -the parent of `pad` -## `offset` -The start offset of the buffer -## `size` -The length of the buffer -## `buffer` -a pointer to hold the `Buffer`, - returns `FlowReturn::Error` if `None`. - -# Returns - -a `FlowReturn` from the pad. - -Invoke the default iterate internal links function of the proxy pad. -## `pad` -the `Pad` to get the internal links of. -## `parent` -the parent of `pad` or `None` - -# Returns - -a `Iterator` of `Pad`, or `None` if `pad` -has no parent. Unref each returned pad with `GstObjectExt::unref`. - -Get the internal pad of `self`. Unref target pad after usage. - -The internal pad of a `GhostPad` is the internally used -pad of opposite direction, which is used to link to the target. - -# Returns - -the target `ProxyPad`, can -be `None`. Unref target pad after usage. - -The different types of QoS events that can be given to the -`Event::new_qos` method. - -The QoS event type that is produced when upstream - elements are producing data too quickly and the element can't keep up - processing the data. Upstream should reduce their production rate. This - type is also used when buffers arrive early or in time. - -The QoS event type that is produced when upstream - elements are producing data too slowly and need to speed up their - production rate. - -The QoS event type that is produced when the - application enabled throttling to limit the data rate. - -Queries can be performed on pads (`Pad::query`) and elements -(`Element::query`). Please note that some queries might need a running -pipeline to work. - -Queries can be created using the gst_query_new_*() functions. -Query values can be set using gst_query_set_*(), and parsed using -gst_query_parse_*() helpers. - -The following example shows how to query the duration of a pipeline: - -```C - GstQuery *query; - gboolean res; - query = gst_query_new_duration (GST_FORMAT_TIME); - res = gst_element_query (pipeline, query); - if (res) { - gint64 duration; - gst_query_parse_duration (query, NULL, &duration); - g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration)); - } else { - g_print ("duration query failed..."); - } - gst_query_unref (query); -``` - -Constructs a new query object for querying if `caps` are accepted. - -Free-function: `gst_query_unref` -## `caps` -a fixed `Caps` - -# Returns - -a new `Query` - -Constructs a new query object for querying the allocation properties. - -Free-function: `gst_query_unref` -## `caps` -the negotiated caps -## `need_pool` -return a pool - -# Returns - -a new `Query` - -Constructs a new query object for querying the bitrate. - -Free-function: `gst_query_unref` - -Feature: `v1_16` - - -# Returns - -a new `Query` - -Constructs a new query object for querying the buffering status of -a stream. - -Free-function: `gst_query_unref` -## `format` -the default `Format` for the new query - -# Returns - -a new `Query` - -Constructs a new query object for querying the caps. - -The CAPS query should return the allowable caps for a pad in the context -of the element's state, its link to other elements, and the devices or files -it has opened. These caps must be a subset of the pad template caps. In the -NULL state with no links, the CAPS query should ideally return the same caps -as the pad template. In rare circumstances, an object property can affect -the caps returned by the CAPS query, but this is discouraged. - -For most filters, the caps returned by CAPS query is directly affected by the -allowed caps on other pads. For demuxers and decoders, the caps returned by -the srcpad's getcaps function is directly related to the stream data. Again, -the CAPS query should return the most specific caps it reasonably can, since this -helps with autoplugging. - -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` -## `filter` -a filter - -# Returns - -a new `Query` - -Constructs a new query object for querying the pipeline-local context. - -Free-function: `gst_query_unref` -## `context_type` -Context type to query - -# Returns - -a new `Query` - -Constructs a new convert query object. Use `gst_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` -## `src_format` -the source `Format` for the new query -## `value` -the value to convert -## `dest_format` -the target `Format` - -# Returns - -a `Query` - -Constructs a new custom query object. Use `gst_query_unref` -when done with it. - -Free-function: `gst_query_unref` -## `type_` -the query type -## `structure` -a structure for the query - -# Returns - -a new `Query` - -Constructs a new query object for querying the drain state. - -Free-function: `gst_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 -total length of the stream. - -Free-function: `gst_query_unref` -## `format` -the `Format` for this duration query - -# Returns - -a new `Query` - -Constructs a new query object for querying formats of -the stream. - -Free-function: `gst_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 -by sinks to compensate for additional latency introduced by elements in the -pipeline. - -Free-function: `gst_query_unref` - -# Returns - -a `Query` - -Constructs a new query stream position query object. Use `gst_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` -## `format` -the default `Format` for the new query - -# Returns - -a new `Query` - -Constructs a new query object for querying the scheduling properties. - -Free-function: `gst_query_unref` - -# Returns - -a new `Query` - -Constructs a new query object for querying seeking properties of -the stream. - -Free-function: `gst_query_unref` -## `format` -the default `Format` for the new query - -# Returns - -a new `Query` - -Constructs a new segment query object. Use `gst_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` -## `format` -the `Format` for the new query - -# Returns - -a new `Query` - -Constructs a new query URI query object. Use `gst_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` - -# Returns - -a new `Query` - -Add `api` with `params` as one of the supported metadata API to `self`. -## `api` -the metadata API -## `params` -API specific parameters - -Add `allocator` and its `params` as a supported memory allocator. -## `allocator` -the memory allocator -## `params` -a `AllocationParams` - -Set the pool parameters in `self`. -## `pool` -the `BufferPool` -## `size` -the buffer size -## `min_buffers` -the min buffers -## `max_buffers` -the max buffers - -Set the buffering-ranges array field in `self`. The current last -start position of the array should be inferior to `start`. -## `start` -start position of the range -## `stop` -stop position of the range - -# Returns - -a `gboolean` indicating if the range was added or not. - -Add `mode` as one of the supported scheduling modes to `self`. -## `mode` -a `PadMode` - -Check if `self` has metadata `api` set. When this function returns `true`, -`index` will contain the index where the requested API and the parameters -can be found. -## `api` -the metadata API -## `index` -the index - -# Returns - -`true` when `api` is in the list of metadata. - -Retrieve the number of values currently stored in the -meta API array of the query's structure. - -# Returns - -the metadata API array size as a `guint`. - -Retrieve the number of values currently stored in the -allocator params array of the query's structure. - -If no memory allocator is specified, the downstream element can handle -the default memory allocator. The first memory allocator in the query -should be generic and allow mapping to system memory, all following -allocators should be ordered by preference with the preferred one first. - -# Returns - -the allocator array size as a `guint`. - -Retrieve the number of values currently stored in the -pool array of the query's structure. - -# Returns - -the pool array size as a `guint`. - -Retrieve the number of values currently stored in the -buffered-ranges array of the query's structure. - -# Returns - -the range array size as a `guint`. - -Retrieve the number of values currently stored in the -scheduling mode array of the query's structure. - -# Returns - -the scheduling mode array size as a `guint`. - -Get the structure of a query. - -# Returns - -the `Structure` of the query. The - structure is still owned by the query and will therefore be freed when the - query is unreffed. - -Check if `self` has scheduling mode set. - -> When checking if upstream supports pull mode, it is usually not -> enough to just check for GST_PAD_MODE_PULL with this function, you -> also want to check whether the scheduling flags returned by -> `Query::parse_scheduling` have the seeking flag set (meaning -> random access is supported, not only sequential pulls). -## `mode` -the scheduling mode - -# Returns - -`true` when `mode` is in the list of scheduling modes. - -Check if `self` has scheduling mode set and `flags` is set in -query scheduling flags. -## `mode` -the scheduling mode -## `flags` -`SchedulingFlags` - -# Returns - -`true` when `mode` is in the list of scheduling modes - and `flags` are compatible with query flags. - -Get the caps from `self`. The caps remains valid as long as `self` remains -valid. -## `caps` -A pointer to the caps - -Parse the result from `self` and store in `result`. -## `result` -location for the result - -Parse an allocation query, writing the requested caps in `caps` and -whether a pool is needed in `need_pool`, if the respective parameters -are non-`None`. - -Pool details can be retrieved using `Query::get_n_allocation_pools` and -`Query::parse_nth_allocation_pool`. -## `caps` -The `Caps` -## `need_pool` -Whether a `BufferPool` is needed - -Get the results of a bitrate query. See also `Query::set_bitrate`. - -Feature: `v1_16` - -## `nominal_bitrate` -The resulting bitrate in bits per second - -Get the percentage of buffered data. This is a value between 0 and 100. -The `busy` indicator is `true` when the buffering is in progress. -## `busy` -if buffering is busy, or `None` -## `percent` -a buffering percent, or `None` - -Parse an available query, writing the format into `format`, and -other results into the passed parameters, if the respective parameters -are non-`None` -## `format` -the format to set for the `segment_start` - and `segment_end` values, or `None` -## `start` -the start to set, or `None` -## `stop` -the stop to set, or `None` -## `estimated_total` -estimated total amount of download - time remaining in milliseconds, or `None` - -Extracts the buffering stats values from `self`. -## `mode` -a buffering mode, or `None` -## `avg_in` -the average input rate, or `None` -## `avg_out` -the average output rat, or `None` -## `buffering_left` -amount of buffering time left in - milliseconds, or `None` - -Get the filter from the caps `self`. The caps remains valid as long as -`self` remains valid. -## `filter` -A pointer to the caps filter - -Get the caps result from `self`. The caps remains valid as long as -`self` remains valid. -## `caps` -A pointer to the caps - -Get the context from the context `self`. The context remains valid as long as -`self` remains valid. -## `context` -A pointer to store the `Context` - -Parse a context type from an existing GST_QUERY_CONTEXT query. -## `context_type` -the context type, or `None` - -# Returns - -a `gboolean` indicating if the parsing succeeded. - -Parse a convert query answer. Any of `src_format`, `src_value`, `dest_format`, -and `dest_value` may be `None`, in which case that value is omitted. -## `src_format` -the storage for the `Format` of the - source value, or `None` -## `src_value` -the storage for the source value, or `None` -## `dest_format` -the storage for the `Format` of the - destination value, or `None` -## `dest_value` -the storage for the destination value, - or `None` - -Parse a duration query answer. Write the format of the duration into `format`, -and the value into `duration`, if the respective variables are non-`None`. -## `format` -the storage for the `Format` of the duration - value, or `None`. -## `duration` -the storage for the total duration, or `None`. - -Parse a latency query answer. -## `live` -storage for live or `None` -## `min_latency` -the storage for the min latency or `None` -## `max_latency` -the storage for the max latency or `None` - -Parse the number of formats in the formats `self`. -## `n_formats` -the number of formats in this query. - -Parse an available query and get the metadata API -at `index` of the metadata API array. -## `index` -position in the metadata API array to read -## `params` -API specific parameters - -# Returns - -a `glib::Type` of the metadata API at `index`. - -Parse an available query and get the allocator and its params -at `index` of the allocator array. -## `index` -position in the allocator array to read -## `allocator` -variable to hold the result -## `params` -parameters for the allocator - -Get the pool parameters in `self`. - -Unref `pool` with `GstObjectExt::unref` when it's not needed any more. -## `index` -index to parse -## `pool` -the `BufferPool` -## `size` -the buffer size -## `min_buffers` -the min buffers -## `max_buffers` -the max buffers - -Parse an available query and get the start and stop values stored -at the `index` of the buffered ranges array. -## `index` -position in the buffered-ranges array to read -## `start` -the start position to set, or `None` -## `stop` -the stop position to set, or `None` - -# Returns - -a `gboolean` indicating if the parsing succeeded. - -Parse the format query and retrieve the `nth` format from it into -`format`. If the list contains less elements than `nth`, `format` will be -set to GST_FORMAT_UNDEFINED. -## `nth` -the nth format to retrieve. -## `format` -a pointer to store the nth format - -Parse an available query and get the scheduling mode -at `index` of the scheduling modes array. -## `index` -position in the scheduling modes array to read - -# Returns - -a `PadMode` of the scheduling mode at `index`. - -Parse a position query, writing the format into `format`, and the position -into `cur`, if the respective parameters are non-`None`. -## `format` -the storage for the `Format` of the - position values (may be `None`) -## `cur` -the storage for the current position (may be `None`) - -Set the scheduling properties. -## `flags` -`SchedulingFlags` -## `minsize` -the suggested minimum size of pull requests -## `maxsize` -the suggested maximum size of pull requests: -## `align` -the suggested alignment of pull requests - -Parse a seeking query, writing the format into `format`, and -other results into the passed parameters, if the respective parameters -are non-`None` -## `format` -the format to set for the `segment_start` - and `segment_end` values, or `None` -## `seekable` -the seekable flag to set, or `None` -## `segment_start` -the segment_start to set, or `None` -## `segment_end` -the segment_end to set, or `None` - -Parse a segment query answer. Any of `rate`, `format`, `start_value`, and -`stop_value` may be `None`, which will cause this value to be omitted. - -See `Query::set_segment` for an explanation of the function arguments. -## `rate` -the storage for the rate of the segment, or `None` -## `format` -the storage for the `Format` of the values, - or `None` -## `start_value` -the storage for the start value, or `None` -## `stop_value` -the storage for the stop value, or `None` - -Parse an URI query, writing the URI into `uri` as a newly -allocated string, if the respective parameters are non-`None`. -Free the string with `g_free` after usage. -## `uri` -the storage for the current URI - (may be `None`) - -Parse an URI query, writing the URI into `uri` as a newly -allocated string, if the respective parameters are non-`None`. -Free the string with `g_free` after usage. -## `uri` -the storage for the redirect URI - (may be `None`) - -Parse an URI query, and set `permanent` to `true` if there is a redirection -and it should be considered permanent. If a redirection is permanent, -applications should update their internal storage of the URI, otherwise -they should make all future requests to the original URI. -## `permanent` -if the URI redirection is permanent - (may be `None`) - -Remove the metadata API at `index` of the metadata API array. -## `index` -position in the metadata API array to remove - -Remove the allocation param at `index` of the allocation param array. -## `index` -position in the allocation param array to remove - -Remove the allocation pool at `index` of the allocation pool array. -## `index` -position in the allocation pool array to remove - -Set `result` as the result for the `self`. -## `result` -the result to set - -Set the results of a bitrate query. The nominal bitrate is the average -bitrate expected over the length of the stream as advertised in file -headers (or similar). - -Feature: `v1_16` - -## `nominal_bitrate` -the nominal bitrate in bits per second - -Set the percentage of buffered data. This is a value between 0 and 100. -The `busy` indicator is `true` when the buffering is in progress. -## `busy` -if buffering is busy -## `percent` -a buffering percent - -Set the available query result fields in `self`. -## `format` -the format to set for the `start` and `stop` values -## `start` -the start to set -## `stop` -the stop to set -## `estimated_total` -estimated total amount of download time remaining in - milliseconds - -Configures the buffering stats values in `self`. -## `mode` -a buffering mode -## `avg_in` -the average input rate -## `avg_out` -the average output rate -## `buffering_left` -amount of buffering time left in milliseconds - -Set the `caps` result in `self`. -## `caps` -A pointer to the caps - -Answer a context query by setting the requested context. -## `context` -the requested `Context` - -Answer a convert query by setting the requested values. -## `src_format` -the source `Format` -## `src_value` -the source value -## `dest_format` -the destination `Format` -## `dest_value` -the destination value - -Answer a duration query by setting the requested value in the given format. -## `format` -the `Format` for the duration -## `duration` -the duration of the stream - -Set the formats query result fields in `self`. The number of formats passed -must be equal to `n_formats`. -## `n_formats` -the number of formats to set. - -Set the formats query result fields in `self`. The number of formats passed -in the `formats` array must be equal to `n_formats`. -## `n_formats` -the number of formats to set. -## `formats` -an array containing `n_formats` - [`crate::Format`] (XXX: @-reference does not belong to Query!) values. - -Answer a latency query by setting the requested values in the given format. -## `live` -if there is a live element upstream -## `min_latency` -the minimal latency of the upstream elements -## `max_latency` -the maximal latency of the upstream elements - -Parse an available query and get the allocator and its params -at `index` of the allocator array. -## `index` -position in the allocator array to set -## `allocator` -new allocator to set -## `params` -parameters for the allocator - -Set the pool parameters in `self`. -## `index` -index to modify -## `pool` -the `BufferPool` -## `size` -the buffer size -## `min_buffers` -the min buffers -## `max_buffers` -the max buffers - -Answer a position query by setting the requested value in the given format. -## `format` -the requested `Format` -## `cur` -the position to set - -Set the scheduling properties. -## `flags` -`SchedulingFlags` -## `minsize` -the suggested minimum size of pull requests -## `maxsize` -the suggested maximum size of pull requests -## `align` -the suggested alignment of pull requests - -Set the seeking query result fields in `self`. -## `format` -the format to set for the `segment_start` and `segment_end` values -## `seekable` -the seekable flag to set -## `segment_start` -the segment_start to set -## `segment_end` -the segment_end to set - -Answer a segment query by setting the requested values. The normal -playback segment of a pipeline is 0 to duration at the default rate of -1.0. If a seek was performed on the pipeline to play a different -segment, this query will return the range specified in the last seek. - -`start_value` and `stop_value` will respectively contain the configured -playback range start and stop values expressed in `format`. -The values are always between 0 and the duration of the media and -`start_value` <= `stop_value`. `rate` will contain the playback rate. For -negative rates, playback will actually happen from `stop_value` to -`start_value`. -## `rate` -the rate of the segment -## `format` -the `Format` of the segment values (`start_value` and `stop_value`) -## `start_value` -the start value -## `stop_value` -the stop value - -Answer a URI query by setting the requested URI. -## `uri` -the URI to set - -Answer a URI query by setting the requested URI redirection. -## `uri` -the URI to set - -Answer a URI query by setting the requested URI redirection -to permanent or not. -## `permanent` -whether the redirect is permanent or not - -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. - -# Returns - -the `Structure` of the query. The structure is - still owned by the query and will therefore be freed when the query - is unreffed. - -Element priority ranks. Defines the order in which the autoplugger (or -similar rank-picking mechanisms, such as e.g. `Element::make_from_uri`) -will choose this element over an alternative one with the same function. - -These constants serve as a rough guidance for defining the rank of a -`PluginFeature`. Any value is valid, including values bigger than -[`Primary`](Self::Primary). - -will be chosen last or not at all - -unlikely to be chosen - -likely to be chosen - -will be chosen first - -One registry holds the metadata of a set of plugins. - -Design:`` - -The `Registry` object is a list of plugins and some functions for dealing -with them. Each `Plugin` is matched 1-1 with a file on disk, and may or may -not be loaded at a given time. - -The primary source, at all times, of plugin information is each plugin file -itself. Thus, if an application wants information about a particular plugin, -or wants to search for a feature that satisfies given criteria, the primary -means of doing so is to load every plugin and look at the resulting -information that is gathered in the default registry. Clearly, this is a time -consuming process, so we cache information in the registry file. The format -and location of the cache file is internal to gstreamer. - -On startup, plugins are searched for in the plugin search path. The following -locations are checked in this order: - -* location from --gst-plugin-path commandline option. -* the GST_PLUGIN_PATH environment variable. -* the GST_PLUGIN_SYSTEM_PATH environment variable. -* default locations (if GST_PLUGIN_SYSTEM_PATH is not set). - Those default locations are: - `$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/` - and `$prefix/libs/gstreamer-$GST_API_VERSION/`. - [$XDG_DATA_HOME](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) defaults to - `$HOME/.local/share`. - -The registry cache file is loaded from -`$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin` -(where $XDG_CACHE_HOME defaults to `$HOME/.cache`) or the file listed in the `GST_REGISTRY` -env var. One reason to change the registry location is for testing. - -For each plugin that is found in the plugin search path, there could be 3 -possibilities for cached information: - - * the cache may not contain information about a given file. - * the cache may have stale information. - * the cache may have current information. - -In the first two cases, the plugin is loaded and the cache updated. In -addition to these cases, the cache may have entries for plugins that are not -relevant to the current process. These are marked as not available to the -current process. If the cache is updated for whatever reason, it is marked -dirty. - -A dirty cache is written out at the end of initialization. Each entry is -checked to make sure the information is minimally valid. If not, the entry is -simply dropped. - -## Implementation notes: - -The "cache" and "registry" are different concepts and can represent -different sets of plugins. For various reasons, at init time, the cache is -stored in the default registry, and plugins not relevant to the current -process are marked with the `PluginFlags::Cached` bit. These plugins are -removed at the end of initialization. - -# Implements - -[`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`] - -By default GStreamer will perform scanning and rebuilding of the -registry file using a helper child process. - -Applications might want to disable this behaviour with the -`Registry::fork_set_enabled` function, in which case new plugins -are scanned (and loaded) into the application process. - -# Returns - -`true` if GStreamer will use the child helper process when -rebuilding the registry. - -Applications might want to disable/enable spawning of a child helper process -when rebuilding the registry. See `Registry::fork_is_enabled` for more -information. -## `enabled` -whether rebuilding the registry can use a temporary child helper process. - -Retrieves the singleton plugin registry. The caller does not own a -reference on the registry, as it is alive as long as GStreamer is -initialized. - -# Returns - -the `Registry`. - -Add the feature to the registry. The feature-added signal will be emitted. - -`feature`'s reference count will be incremented, and any floating -reference will be removed (see `Object::ref_sink`) -## `feature` -the feature to add - -# Returns - -`true` on success. - -MT safe. - -Add the plugin to the registry. The plugin-added signal will be emitted. - -`plugin`'s reference count will be incremented, and any floating -reference will be removed (see `Object::ref_sink`) -## `plugin` -the plugin to add - -# Returns - -`true` on success. - -MT safe. - -Checks whether a plugin feature by the given name exists in -`self` and whether its version is at least the -version required. -## `feature_name` -the name of the feature (e.g. "oggdemux") -## `min_major` -the minimum major version number -## `min_minor` -the minimum minor version number -## `min_micro` -the minimum micro version number - -# Returns - -`true` if the feature could be found and the version is -the same as the required version or newer, and `false` otherwise. - -Runs a filter against all features of the plugins in the registry -and returns a GList with the results. -If the first flag is set, only the first match is -returned (as a list with a single object). -## `filter` -the filter to use -## `first` -only return first match -## `user_data` -user data passed to the filter function - -# Returns - -a `glib::List` of - `PluginFeature`. Use `PluginFeature::list_free` after usage. - -MT safe. - -Find the pluginfeature with the given name and type in the registry. -## `name` -the pluginfeature name to find -## `type_` -the pluginfeature type to find - -# Returns - -the pluginfeature with the - given name and type or `None` if the plugin was not - found. `GstObjectExt::unref` after usage. - -MT safe. - -Find the plugin with the given name in the registry. -The plugin will be reffed; caller is responsible for unreffing. -## `name` -the plugin name to find - -# Returns - -the plugin with the given name - or `None` if the plugin was not found. `GstObjectExt::unref` after - usage. - -MT safe. - -Retrieves a `glib::List` of `PluginFeature` of `type_`. -## `type_` -a `glib::Type`. - -# Returns - -a `glib::List` of - `PluginFeature` of `type_`. Use `PluginFeature::list_free` after use - -MT safe. - -Retrieves a `glib::List` of features of the plugin with name `name`. -## `name` -a plugin name. - -# Returns - -a `glib::List` of - `PluginFeature`. Use `PluginFeature::list_free` after usage. - -Returns the registry's feature list cookie. This changes -every time a feature is added or removed from the registry. - -# Returns - -the feature list cookie. - -Get a copy of all plugins registered in the given registry. The refcount -of each element in the list in incremented. - -# Returns - -a `glib::List` of `Plugin`. - Use `Plugin::list_free` after usage. - -MT safe. - -Look up a plugin in the given registry with the given filename. -If found, plugin is reffed. -## `filename` -the name of the file to look up - -# Returns - -the `Plugin` if found, or - `None` if not. `GstObjectExt::unref` after usage. - -Find a `PluginFeature` with `name` in `self`. -## `name` -a `PluginFeature` name - -# Returns - -a `PluginFeature` with its refcount incremented, - use `GstObjectExt::unref` after usage. - -MT safe. - -Runs a filter against all plugins in the registry and returns a `glib::List` with -the results. If the first flag is set, only the first match is -returned (as a list with a single object). -Every plugin is reffed; use `Plugin::list_free` after use, which -will unref again. -## `filter` -the filter to use -## `first` -only return first match -## `user_data` -user data passed to the filter function - -# Returns - -a `glib::List` of `Plugin`. - Use `Plugin::list_free` after usage. - -MT safe. - -Remove the feature from the registry. - -MT safe. -## `feature` -the feature to remove - -Remove the plugin from the registry. - -MT safe. -## `plugin` -the plugin to remove - -Scan the given path for plugins to add to the registry. The syntax of the -path is specific to the registry. -## `path` -the path to scan - -# Returns - -`true` if registry changed - -Signals that a feature has been added to the registry (possibly -replacing a previously-added one by the same name) -## `feature` -the feature that has been added - -Signals that a plugin has been added to the registry (possibly -replacing a previously-added one by the same name) -## `plugin` -the plugin that has been added - -Resource errors are for any resource used by an element: -memory, files, network connections, process space, ... -They're typically used by source and sink elements. - -a general error which doesn't fit in any other -category. Make sure you add a custom message to the error call. - -do not use this except as a placeholder for -deciding where to go while developing code. - -used when the resource could not be found. - -used when resource is busy. - -used when resource fails to open for reading. - -used when resource fails to open for writing. - -used when resource cannot be opened for -both reading and writing, or either (but unspecified which). - -used when the resource can't be closed. - -used when the resource can't be read from. - -used when the resource can't be written to. - -used when a seek on the resource fails. - -used when a synchronize on the resource fails. - -used when settings can't be manipulated on. - -used when the resource has no space left. - -used when the resource can't be opened - due to missing authorization. - (Since: 1.2.4) - -the number of resource error types. - -A `Sample` is a small object containing data, a type, timing and -extra arbitrary information. - -Create a new `Sample` with the provided details. - -Free-function: gst_sample_unref -## `buffer` -a `Buffer`, or `None` -## `caps` -a `Caps`, or `None` -## `segment` -a `Segment`, or `None` -## `info` -a `Structure`, or `None` - -# Returns - -the new `Sample`. `gst_sample_unref` - after usage. - -Get the buffer associated with `self` - -# Returns - -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`. - -Get the buffer list associated with `self` - -# Returns - -the buffer list of `self` or `None` - when there is no buffer list. The buffer list 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 list with gst_mini_object_ref (). - -Get the caps associated with `self` - -# Returns - -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`. - -Get extra information associated with `self`. - -# Returns - -the extra info of `self`. - The info remains valid as long as `self` is valid. - -Get the segment associated with `self` - -# Returns - -the segment of `self`. - The segment remains valid as long as `self` is valid. - -Set the buffer associated with `self`. `self` must be writable. - -Feature: `v1_16` - -## `buffer` -A `Buffer` - -Set the buffer list associated with `self`. `self` must be writable. -## `buffer_list` -a `BufferList` - -Set the caps associated with `self`. `self` must be writable. - -Feature: `v1_16` - -## `caps` -A `Caps` - -Set the info structure associated with `self`. `self` must be writable, -and `info` must not have a parent set already. - -Feature: `v1_16` - -## `info` -A `Structure` - -Set the segment associated with `self`. `self` must be writable. - -Feature: `v1_16` - -## `segment` -A `Segment` - -The different scheduling flags. - -if seeking is possible - -if sequential access is recommended - -if bandwidth is limited and buffering possible (since 1.2) - -Flags to be used with `Element::seek` or `Event::new_seek`. All flags -can be used together. - -A non flushing seek might take some time to perform as the currently -playing data in the pipeline will not be cleared. - -An accurate seek might be slower for formats that don't have any indexes -or timestamp markers in the stream. Specifying this flag might require a -complete scan of the file in those cases. - -When performing a segment seek: after the playback of the segment completes, -no EOS will be emitted by the element that performed the seek, but a -`MessageType::SegmentDone` message will be posted on the bus by the element. -When this message is posted, it is possible to send a new seek event to -continue playback. With this seek method it is possible to perform seamless -looping or simple linear editing. - -When only changing the playback rate and not the direction, the -`SeekFlags::InstantRateChange` flag can be used for a non-flushing seek -to signal that the rate change should be applied immediately. This requires -special support in the seek handlers (e.g. demuxers) and any elements -synchronizing to the clock, and in general can't work in all cases (for example -UDP streaming where the delivery rate is controlled by a remote server). The -instant-rate-change mode supports changing the trickmode-related GST_SEEK_ flags, -but can't be used in conjunction with other seek flags that affect the new -playback position - as the playback position will not be changing. - -When doing fast forward (rate > 1.0) or fast reverse (rate < -1.0) trickmode -playback, the `SeekFlags::Trickmode` flag can be used to instruct decoders -and demuxers to adjust the playback rate by skipping frames. This can improve -performance and decrease CPU usage because not all frames need to be decoded. - -Beyond that, the `SeekFlags::TrickmodeKeyUnits` flag can be used to -request that decoders skip all frames except key units, and -`SeekFlags::TrickmodeNoAudio` flags can be used to request that audio -decoders do no decoding at all, and simple output silence. - -The `SeekFlags::SnapBefore` flag can be used to snap to the previous -relevant location, and the `SeekFlags::SnapAfter` flag can be used to -select the next relevant location. If `SeekFlags::KeyUnit` is specified, -the relevant location is a keyframe. If both flags are specified, the nearest -of these locations will be selected. If none are specified, the implementation is -free to select whichever it wants. - -The before and after here are in running time, so when playing backwards, -the next location refers to the one that will played in next, and not the -one that is located after in the actual source stream. - -Also see part-seeking.txt in the GStreamer design documentation for more -details on the meaning of these flags and the behaviour expected of -elements that handle them. - -no flag - -flush pipeline - -accurate position is requested, this might - be considerably slower for some formats. - -seek to the nearest keyframe. This might be - faster but less accurate. - -perform a segment seek. - -when doing fast forward or fast reverse playback, allow - elements to skip frames instead of generating all - frames. (Since: 1.6) - -Deprecated backward compatibility flag, replaced - by `SeekFlags::Trickmode` - -go to a location before the requested position, - if `SeekFlags::KeyUnit` this means the keyframe at or before - the requested position the one at or before the seek target. - -go to a location after the requested position, - if `SeekFlags::KeyUnit` this means the keyframe at of after the - requested position. - -go to a position near the requested position, - if `SeekFlags::KeyUnit` this means the keyframe closest - to the requested position, if both keyframes are at an equal - distance, behaves like `SeekFlags::SnapBefore`. - -when doing fast forward or fast reverse - playback, request that elements only decode keyframes - and skip all other content, for formats that have - keyframes. (Since: 1.6) - -when doing fast forward or fast reverse - playback, request that audio decoder elements skip - decoding and output only gap events or silence. (Since: 1.6) - -When doing fast forward or fast reverse - playback, request that elements only decode keyframes and - forward predicted frames and skip all other content (for example - B-Frames), for formats that have keyframes and forward predicted - frames. (Since: 1.18) - -Signals that a rate change should be - applied immediately. Only valid if start/stop position - are GST_CLOCK_TIME_NONE, the playback direction does not change - and the seek is not flushing. (Since: 1.18) - -The different types of seek events. When constructing a seek event with -`Event::new_seek` or when doing gst_segment_do_seek (). - -no change in position is required - -absolute position is requested - -relative position to duration is requested - -This helper structure holds the relevant values for tracking the region of -interest in a media file, called a segment. - -The structure can be used for two purposes: - - * performing seeks (handling seek events) - * tracking playback regions (handling newsegment events) - -The segment is usually configured by the application with a seek event which -is propagated upstream and eventually handled by an element that performs the seek. - -The configured segment is then propagated back downstream with a newsegment event. -This information is then used to clip media to the segment boundaries. - -A segment structure is initialized with `Segment::init`, which takes a `Format` -that will be used as the format of the segment values. The segment will be configured -with a start value of 0 and a stop/duration of -1, which is undefined. The default -rate and applied_rate is 1.0. - -The public duration field contains the duration of the segment. When using -the segment for seeking, the start and time members should normally be left -to their default 0 value. The stop position is left to -1 unless explicitly -configured to a different value after a seek event. - -The current position in the segment should be set by changing the position -member in the structure. - -For elements that perform seeks, the current segment should be updated with the -`Segment::do_seek` and the values from the seek event. This method will update -all the segment fields. The position field will contain the new playback position. -If the start_type was different from GST_SEEK_TYPE_NONE, playback continues from -the position position, possibly with updated flags or rate. - -For elements that want to use `Segment` to track the playback region, -update the segment fields with the information from the newsegment event. -The `Segment::clip` method can be used to check and clip -the media data to the segment boundaries. - -For elements that want to synchronize to the pipeline clock, `Segment::to_running_time` -can be used to convert a timestamp to a value that can be used to synchronize -to the clock. This function takes into account the base as well as -any rate or applied_rate conversions. - -For elements that need to perform operations on media data in stream_time, -`Segment::to_stream_time` can be used to convert a timestamp and the segment -info to stream time (which is always between 0 and the duration of the stream). - -Allocate a new `Segment` structure and initialize it using -`Segment::init`. - -Free-function: gst_segment_free - -# Returns - -a new `Segment`, free with `Segment::free`. - -Clip the given `start` and `stop` values to the segment boundaries given -in `self`. `start` and `stop` are compared and clipped to `self` -start and stop values. - -If the function returns `false`, `start` and `stop` are known to fall -outside of `self` and `clip_start` and `clip_stop` are not updated. - -When the function returns `true`, `clip_start` and `clip_stop` will be -updated. If `clip_start` or `clip_stop` are different from `start` or `stop` -respectively, the region fell partially in the segment. - -Note that when `stop` is -1, `clip_stop` will be set to the end of the -segment. Depending on the use case, this may or may not be what you want. -## `format` -the format of the segment. -## `start` -the start position in the segment -## `stop` -the stop position in the segment -## `clip_start` -the clipped start position in the segment -## `clip_stop` -the clipped stop position in the segment - -# Returns - -`true` if the given `start` and `stop` times fall partially or - completely in `self`, `false` if the values are completely outside - of the segment. - -Create a copy of given `self`. - -Free-function: gst_segment_free - -# Returns - -a new `Segment`, free with `Segment::free`. - -Copy the contents of `self` into `dest`. -## `dest` -a `Segment` - -Update the segment structure with the field values of a seek event (see -`Event::new_seek`). - -After calling this method, the segment field position and time will -contain the requested new position in the segment. The new requested -position in the segment depends on `rate` and `start_type` and `stop_type`. - -For positive `rate`, the new position in the segment is the new `self` -start field when it was updated with a `start_type` different from -`SeekType::None`. If no update was performed on `self` start position -(`SeekType::None`), `start` is ignored and `self` position is -unmodified. - -For negative `rate`, the new position in the segment is the new `self` -stop field when it was updated with a `stop_type` different from -`SeekType::None`. If no stop was previously configured in the segment, the -duration of the segment will be used to update the stop position. -If no update was performed on `self` stop position (`SeekType::None`), -`stop` is ignored and `self` position is unmodified. - -The applied rate of the segment will be set to 1.0 by default. -If the caller can apply a rate change, it should update `self` -rate and applied_rate after calling this function. - -`update` will be set to `true` if a seek should be performed to the segment -position field. This field can be `false` if, for example, only the `rate` -has been changed but not the playback position. -## `rate` -the rate of the segment. -## `format` -the format of the segment. -## `flags` -the segment flags for the segment -## `start_type` -the seek method -## `start` -the seek start value -## `stop_type` -the seek method -## `stop` -the seek stop value -## `update` -boolean holding whether position was updated. - -# Returns - -`true` if the seek could be performed. - -Free the allocated segment `self`. - -The start/position fields are set to 0 and the stop/duration -fields are set to -1 (unknown). The default rate of 1.0 and no -flags are set. - -Initialize `self` to its default values. -## `format` -the format of the segment. - -Checks for two segments being equal. Equality here is defined -as perfect equality, including floating point values. -## `s1` -a `Segment` structure. - -# Returns - -`true` if the segments are equal, `false` otherwise. - -Adjust the values in `self` so that `offset` is applied to all -future running-time calculations. -## `format` -the format of the segment. -## `offset` -the offset to apply in the segment - -# Returns - -`true` if the segment could be updated successfully. If `false` is -returned, `offset` is not in `self`. - -Convert `running_time` into a position in the segment so that -`Segment::to_running_time` with that position returns `running_time`. -## `format` -the format of the segment. -## `running_time` -the running_time in the segment - -# Returns - -the position in the segment for `running_time`. This function returns --1 when `running_time` is -1 or when it is not inside `self`. - -Translate `running_time` to the segment position using the currently configured -segment. Compared to `Segment::position_from_running_time` this function can -return negative segment position. - -This function is typically used by elements that need to synchronize buffers -against the clock or each other. - -`running_time` can be any value and the result of this function for values -outside of the segment is extrapolated. - -When 1 is returned, `running_time` resulted in a positive position returned -in `position`. - -When this function returns -1, the returned `position` was < 0, and the value -in the position variable should be negated to get the real negative segment -position. -## `format` -the format of the segment. -## `running_time` -the running-time -## `position` -the resulting position in the segment - -# Returns - -a 1 or -1 on success, 0 on failure. - -Convert `stream_time` into a position in the segment so that -`Segment::to_stream_time` with that position returns `stream_time`. -## `format` -the format of the segment. -## `stream_time` -the stream_time in the segment - -# Returns - -the position in the segment for `stream_time`. This function returns --1 when `stream_time` is -1 or when it is not inside `self`. - -Translate `stream_time` to the segment position using the currently configured -segment. Compared to `Segment::position_from_stream_time` this function can -return negative segment position. - -This function is typically used by elements that need to synchronize buffers -against the clock or each other. - -`stream_time` can be any value and the result of this function for values outside -of the segment is extrapolated. - -When 1 is returned, `stream_time` resulted in a positive position returned -in `position`. - -When this function returns -1, the returned `position` should be negated -to get the real negative segment position. -## `format` -the format of the segment. -## `stream_time` -the stream-time -## `position` -the resulting position in the segment - -# Returns - -a 1 or -1 on success, 0 on failure. - -Adjust the start/stop and base values of `self` such that the next valid -buffer will be one with `running_time`. -## `format` -the format of the segment. -## `running_time` -the running_time in the segment - -# Returns - -`true` if the segment could be updated successfully. If `false` is -returned, `running_time` is -1 or not in `self`. - -Convert `running_time` into a position in the segment so that -`Segment::to_running_time` with that position returns `running_time`. - -# Deprecated - -Use `Segment::position_from_running_time` instead. -## `format` -the format of the segment. -## `running_time` -the running_time in the segment - -# Returns - -the position in the segment for `running_time`. This function returns --1 when `running_time` is -1 or when it is not inside `self`. - -Translate `position` to the total running time using the currently configured -segment. Position is a value between `self` start and stop time. - -This function is typically used by elements that need to synchronize to the -global clock in a pipeline. The running time is a constantly increasing value -starting from 0. When `Segment::init` is called, this value will reset to -0. - -This function returns -1 if the position is outside of `self` start and stop. -## `format` -the format of the segment. -## `position` -the position in the segment - -# Returns - -the position as the total running time or -1 when an invalid position -was given. - -Translate `position` to the total running time using the currently configured -segment. Compared to `Segment::to_running_time` this function can return -negative running-time. - -This function is typically used by elements that need to synchronize buffers -against the clock or each other. - -`position` can be any value and the result of this function for values outside -of the segment is extrapolated. - -When 1 is returned, `position` resulted in a positive running-time returned -in `running_time`. - -When this function returns -1, the returned `running_time` should be negated -to get the real negative running time. -## `format` -the format of the segment. -## `position` -the position in the segment -## `running_time` -result running-time - -# Returns - -a 1 or -1 on success, 0 on failure. - -Translate `position` to stream time using the currently configured -segment. The `position` value must be between `self` start and -stop value. - -This function is typically used by elements that need to operate on -the stream time of the buffers it receives, such as effect plugins. -In those use cases, `position` is typically the buffer timestamp or -clock time that one wants to convert to the stream time. -The stream time is always between 0 and the total duration of the -media stream. -## `format` -the format of the segment. -## `position` -the position in the segment - -# Returns - -the position in stream_time or -1 when an invalid position -was given. - -Translate `position` to the total stream time using the currently configured -segment. Compared to `Segment::to_stream_time` this function can return -negative stream-time. - -This function is typically used by elements that need to synchronize buffers -against the clock or each other. - -`position` can be any value and the result of this function for values outside -of the segment is extrapolated. - -When 1 is returned, `position` resulted in a positive stream-time returned -in `stream_time`. - -When this function returns -1, the returned `stream_time` should be negated -to get the real negative stream time. -## `format` -the format of the segment. -## `position` -the position in the segment -## `stream_time` -result stream-time - -# Returns - -a 1 or -1 on success, 0 on failure. - -Flags for the GstSegment structure. Currently mapped to the corresponding -values of the seek flags. - -no flags - -reset the pipeline running_time to the segment - running_time - -perform skip playback (Since: 1.6) - -Deprecated backward compatibility flag, replaced - by [`Trickmode`](Self::Trickmode) - -send SEGMENT_DONE instead of EOS - -Decode only keyframes, where - possible (Since: 1.6) - -Decode only keyframes or forward - predicted frames, where possible (Since: 1.18) - -Do not decode any audio, where - possible (Since: 1.6) - - -Try to retrieve the minimum information - available, which may be none on some platforms - (Since: 1.18) - -Try to retrieve as much information as possible, - including source information when getting the - stack trace - -Feature: `v1_12` - - -The possible states an element can be in. States can be changed using -`Element::set_state` and checked using `Element::get_state`. - -no pending state. - -the NULL state or initial state of an element. - -the element is ready to go to PAUSED. - -the element is PAUSED, it is ready to accept and - process data. Sink elements however only accept one - buffer and then block. - -the element is PLAYING, the `Clock` is running and - the data is flowing. - -These are the different state changes an element goes through. -`State::Null` ⇒ `State::Playing` is called an upwards state change -and `State::Playing` ⇒ `State::Null` a downwards state change. - -state change from NULL to READY. - * The element must check if the resources it needs are available. Device - sinks and -sources typically try to probe the device to constrain their - caps. - * The element opens the device (in case feature need to be probed). - -state change from READY to PAUSED. - * The element pads are activated in order to receive data in PAUSED. - Streaming threads are started. - * Some elements might need to return `StateChangeReturn::Async` and complete - the state change when they have enough information. It is a requirement - for sinks to return `StateChangeReturn::Async` and complete the state change - when they receive the first buffer or `EventType::Eos` (preroll). - Sinks also block the dataflow when in PAUSED. - * A pipeline resets the running_time to 0. - * Live sources return `StateChangeReturn::NoPreroll` and don't generate data. - -state change from PAUSED to PLAYING. - * Most elements ignore this state change. - * The pipeline selects a `Clock` and distributes this to all the children - before setting them to PLAYING. This means that it is only allowed to - synchronize on the `Clock` in the PLAYING state. - * The pipeline uses the `Clock` and the running_time to calculate the - base_time. The base_time is distributed to all children when performing - the state change. - * Sink elements stop blocking on the preroll buffer or event and start - rendering the data. - * Sinks can post `MessageType::Eos` in the PLAYING state. It is not allowed - to post `MessageType::Eos` when not in the PLAYING state. - * While streaming in PAUSED or PLAYING elements can create and remove - sometimes pads. - * Live sources start generating data and return `StateChangeReturn::Success`. - -state change from PLAYING to PAUSED. - * Most elements ignore this state change. - * The pipeline calculates the running_time based on the last selected - `Clock` and the base_time. It stores this information to continue - playback when going back to the PLAYING state. - * Sinks unblock any `Clock` wait calls. - * When a sink does not have a pending buffer to play, it returns - `StateChangeReturn::Async` from this state change and completes the state - change when it receives a new buffer or an `EventType::Eos`. - * Any queued `MessageType::Eos` items are removed since they will be reposted - when going back to the PLAYING state. The EOS messages are queued in - `Bin` containers. - * Live sources stop generating data and return `StateChangeReturn::NoPreroll`. - -state change from PAUSED to READY. - * Sinks unblock any waits in the preroll. - * Elements unblock any waits on devices - * Chain or get_range functions return `FlowReturn::Flushing`. - * The element pads are deactivated so that streaming becomes impossible and - all streaming threads are stopped. - * The sink forgets all negotiated formats - * Elements remove all sometimes pads - -state change from READY to NULL. - * Elements close devices - * Elements reset any internal state. - -state change from NULL to NULL. (Since: 1.14) - -state change from READY to READY, -This might happen when going to PAUSED asynchronously failed, in that case -elements should make sure they are in a proper, coherent READY state. (Since: 1.14) - -state change from PAUSED to PAUSED. -This might happen when elements were in PLAYING state and 'lost state', -they should make sure to go back to real 'PAUSED' state (prerolling for example). (Since: 1.14) - -state change from PLAYING to PLAYING. (Since: 1.14) - -The possible return values from a state change function such as -`Element::set_state`. Only [`Failure`](Self::Failure) is a real failure. - -the state change failed - -the state change succeeded - -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`). - -A `Stream` does not care about data changes (such as decoding, encoding, -parsing,...) as long as the underlying data flow corresponds to the same -high-level flow (ex: a certain audio track). - -A `Stream` contains all the information pertinent to a stream, such as -stream-id, tags, caps, type, ... - -Elements can subclass a `Stream` for internal usage (to contain information -pertinent to streams of data). - -Feature: `v1_10` - -# Implements - -[`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`] - -Create a new `Stream` for the given `stream_id`, `caps`, `type_` -and `flags` - -Feature: `v1_10` - -## `stream_id` -the id for the new stream. If `None`, -a new one will be automatically generated -## `caps` -the `Caps` of the stream -## `type_` -the `StreamType` of the stream -## `flags` -the `StreamFlags` of the stream - -# Returns - -The new `Stream` - -Retrieve the caps for `self`, if any - -Feature: `v1_10` - - -# Returns - -The `Caps` for `self` - -Retrieve the current stream flags for `self` - -Feature: `v1_10` - - -# Returns - -The `StreamFlags` for `self` - -Returns the stream ID of `self`. - -Feature: `v1_10` - - -# Returns - -the stream ID of `self`. Only valid -during the lifetime of `self`. - -Retrieve the stream type for `self` - -Feature: `v1_10` - - -# Returns - -The `StreamType` for `self` - -Retrieve the tags for `self`, if any - -Feature: `v1_10` - - -# Returns - -The `TagList` for `self` - -Set the caps for the `Stream` - -Feature: `v1_10` - -## `caps` -a `Caps` - -Set the `flags` for the `self`. - -Feature: `v1_10` - -## `flags` -the flags to set on `self` - -Set the stream type of `self` - -Feature: `v1_10` - -## `stream_type` -the type to set on `self` - -Set the tags for the `Stream` - -Feature: `v1_10` - -## `tags` -a `TagList` - -The `Caps` of the `Stream`. - -The `Caps` of the `Stream`. - -The unique identifier of the `Stream`. Can only be set at construction -time. - -The unique identifier of the `Stream`. Can only be set at construction -time. - -The `StreamType` of the `Stream`. Can only be set at construction time. - -The `StreamType` of the `Stream`. Can only be set at construction time. - -The `TagList` of the `Stream`. - -The `TagList` of the `Stream`. - -A collection of `Stream` that are available. - -A `StreamCollection` will be provided by elements that can make those -streams available. Applications can use the collection to show the user -what streams are available by using `StreamCollection::get_stream`() - -Once posted, a `StreamCollection` is immutable. Updates are made by sending -a new `StreamCollection` message, which may or may not share some of -the `Stream` objects from the collection it replaces. The receiver can check -the sender of a stream collection message to know which collection is -obsoleted. - -Several elements in a pipeline can provide `StreamCollection`. - -Applications can activate streams from a collection by using the -`EventType::SelectStreams` event on a pipeline, bin or element. - -Feature: `v1_10` - -# Implements - -[`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`] - -Create a new `StreamCollection`. - -Feature: `v1_10` - -## `upstream_id` -The stream id of the parent stream - -# Returns - -The new `StreamCollection`. - -Add the given `stream` to the `self`. - -Feature: `v1_10` - -## `stream` -the `Stream` to add - -# Returns - -`true` if the `stream` was properly added, else `false` - -Get the number of streams this collection contains - -Feature: `v1_10` - - -# Returns - -The number of streams that `self` contains - -Retrieve the `Stream` with index `index` from the collection. - -The caller should not modify the returned `Stream` - -Feature: `v1_10` - -## `index` -Index of the stream to retrieve - -# Returns - -A `Stream` - -Returns the upstream id of the `self`. - -Feature: `v1_10` - - -# Returns - -The upstream id - -Stream errors are for anything related to the stream being processed: -format errors, media type errors, ... -They're typically used by decoders, demuxers, converters, ... - -a general error which doesn't fit in any other -category. Make sure you add a custom message to the error call. - -do not use this except as a placeholder for -deciding where to go while developing code. - -use this when you do not want to implement -this functionality yet. - -used when the element doesn't know the -stream's type. - -used when the element doesn't handle this type -of stream. - -used when there's no codec to handle the -stream's type. - -used when decoding fails. - -used when encoding fails. - -used when demuxing fails. - -used when muxing fails. - -used when the stream is of the wrong format -(for example, wrong caps). - -used when the stream is encrypted and can't be -decrypted because this is not supported by the element. - -used when the stream is encrypted and -can't be decrypted because no suitable key is available. - -the number of stream error types. - - -This stream has no special attributes - -This stream is a sparse stream (e.g. a subtitle - stream), data may flow only in irregular intervals with large gaps in - between. - -This stream should be selected by default. This - flag may be used by demuxers to signal that a stream should be selected - by default in a playback scenario. - -This stream should not be selected by default. - This flag may be used by demuxers to signal that a stream should not - be selected by default in a playback scenario, but only if explicitly - selected by the user (e.g. an audio track for the hard of hearing or - a director's commentary track). - -The type of a `MessageType::StreamStatus`. The stream status messages inform the -application of new streaming threads and their status. - -A new thread need to be created. - -a thread entered its loop function - -a thread left its loop function - -a thread is destroyed - -a thread is started - -a thread is paused - -a thread is stopped - -`StreamType` describes a high level classification set for -flows of data in `Stream` objects. - -Note that this is a flag, and therefore users should not assume it -will be a single value. Do not use the equality operator for checking -whether a stream is of a certain type. - -The stream is of unknown (unclassified) type. - -The stream is of audio data - -The stream carries video data - -The stream is a muxed container type - -The stream contains subtitle / subpicture data. - -Feature: `v1_10` - - -A `Structure` is a collection of key/value pairs. The keys are expressed as -GQuarks and the values can be of any GType. - -In addition to the key/value pairs, a `Structure` also has a name. The name -starts with a letter and can be filled by letters, numbers and any of -"/-_.:". - -`Structure` is used by various GStreamer subsystems to store information in -a flexible and extensible way. A `Structure` does not have a refcount -because it usually is part of a higher level object such as `Caps`, -`Message`, `Event`, `Query`. It provides a means to enforce mutability -using the refcount of the parent with the `Structure::set_parent_refcount` -method. - -A `Structure` can be created with `Structure::new_empty` or -`Structure::new`, which both take a name and an optional set of key/value -pairs along with the types of the values. - -Field values can be changed with `Structure::set_value` or -`Structure::set`. - -Field values can be retrieved with `Structure::get_value` or the more -convenient gst_structure_get_*() functions. - -Fields can be removed with `Structure::remove_field` or -`Structure::remove_fields`. - -Strings in structures must be ASCII or UTF-8 encoded. Other encodings are not -allowed. Strings may be `None` however. - -## The serialization format - -GstStructure serialization format serialize the GstStructure name, -keys/GType/values in a comma separated list with the structure name as first -field without value followed by separated key/value pairs in the form -`key=value`, for example: - -``` -a-structure, key=value -```` - -The values type will be inferred if not explicitly specified with the -`(GTypeName)value` syntax, for example the following struct will have one -field called 'is-string' which has the string 'true' as a value: - -``` -a-struct, field-is-string=(string)true, field-is-boolean=true -``` - -*Note*: without specifying `(string), `field-is-string` type would have been -inferred as boolean. - -*Note*: we specified `(string)` as a type even if `gchararray` is the actual -GType name as for convenience some well known types have been aliased or -abbreviated. - -To avoid specifying the type, you can give some hints to the "type system". -For example to specify a value as a double, you should add a decimal (ie. `1` -is an `int` while `1.0` is a `double`). - -*Note*: when a structure is serialized with `Structure::to_string`, all -values are explicitly typed. - -Some types have special delimiters: - -- [GstValueArray](GST_TYPE_ARRAY) are inside curly brackets (`{` and `}`). - For example `a-structure, array={1, 2, 3}` -- Ranges are inside brackets (`[` and `]`). For example `a-structure, - range=[1, 6, 2]` 1 being the min value, 6 the maximum and 2 the step. To - specify a `GST_TYPE_INT64_RANGE` you need to explicitly specify it like: - `a-structure, a-int64-range=(gint64) [1, 5]` -- [GstValueList](GST_TYPE_LIST) are inside "less and greater than" (`<` and - `>`). For example `a-structure, list=<1, 2, 3> - -Structures are delimited either by a null character `\0` or a semicolumn `;` -the latter allowing to store multiple structures in the same string (see -#GstCaps). - -Quotes are used as "default" delimiters and can be used around any types that -don't use other delimiters (for example `a-struct, i=(int)"1"`). They are use -to allow adding spaces or special characters (such as delimiters, -semicolumns, etc..) inside strings and you can use backslashes `\` to escape -characters inside them, for example: - -``` -a-struct, special="\"{[(;)]}\" can be used inside quotes" -``` - -They also allow for nested structure, such as: - -``` -a-struct, nested=(GstStructure)"nested-struct, nested=true" -``` - -> *Note*: Be aware that the current #GstCaps / #GstStructure serialization -> into string has limited support for nested #GstCaps / #GstStructure fields. -> It can only support one level of nesting. Using more levels will lead to -> unexpected behavior when using serialization features, such as -> gst_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. -Variable arguments should be passed as field name, field type, -and value. Last variable argument should be `None`. - -Free-function: gst_structure_free -## `name` -name of new structure -## `firstfield` -name of first field to set - -# Returns - -a new `Structure` - -Creates a new, empty `Structure` with the given `name`. - -See `Structure::set_name` for constraints on the `name` parameter. - -Free-function: gst_structure_free -## `name` -name of new structure - -# Returns - -a new, empty `Structure` - -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. - -The current implementation of serialization will lead to unexpected results -when there are nested `Caps` / `Structure` deeper than one level. - -Free-function: gst_structure_free -## `string` -a string representation of a `Structure` - -# 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 as a GQuark, followed by -fieldname quark, GType, argument(s) "triplets" in the same format as -`Structure::id_set`. Basically a convenience wrapper around -`Structure::new_id_empty` and `Structure::id_set`. - -The last variable argument must be `None` (or 0). - -Free-function: gst_structure_free -## `name_quark` -name of new structure -## `field_quark` -the GQuark for the name of the field to set - -# Returns - -a new `Structure` - -Creates a new, empty `Structure` with the given name as a GQuark. - -Free-function: gst_structure_free -## `quark` -name of new structure - -# Returns - -a new, empty `Structure` - -Creates a new `Structure` with the given `name`. Structure fields -are set according to the varargs in a manner similar to -`Structure::new`. - -See `Structure::set_name` for constraints on the `name` parameter. - -Free-function: gst_structure_free -## `name` -name of new structure -## `firstfield` -name of first field to set -## `varargs` -variable argument list - -# Returns - -a new `Structure` - -Tries intersecting `self` and `struct2` and reports whether the result -would not be empty. -## `struct2` -a `Structure` - -# Returns - -`true` if intersection would not be empty - -Duplicates a `Structure` and all its fields and values. - -Free-function: gst_structure_free - -# Returns - -a new `Structure`. - -Calls the provided function once for each field in the `Structure`. In -contrast to `Structure::foreach`, the function may modify the fields. -In contrast to `Structure::map_in_place`, the field is removed from -the structure if `false` is returned from the function. -The structure must be mutable. -## `func` -a function to call for each field -## `user_data` -private data - -Fixate all values in `self` using `gst_value_fixate`. -`self` will be modified in-place and should be writable. - -Fixates a `Structure` by changing the given field with its fixated value. -## `field_name` -a field in `self` - -# Returns - -`true` if the structure field could be fixated - -Fixates a `Structure` by changing the given `field_name` field to the given -`target` boolean if that field is not fixed yet. -## `field_name` -a field in `self` -## `target` -the target value of the fixation - -# Returns - -`true` if the structure could be fixated - -Fixates a `Structure` by changing the given field to the nearest -double to `target` that is a subset of the existing field. -## `field_name` -a field in `self` -## `target` -the target value of the fixation - -# Returns - -`true` if the structure could be fixated - -Fixates a `Structure` by changing the given field to the nearest -fraction to `target_numerator`/`target_denominator` that is a subset -of the existing field. -## `field_name` -a field in `self` -## `target_numerator` -The numerator of the target value of the fixation -## `target_denominator` -The denominator of the target value of the fixation - -# Returns - -`true` if the structure could be fixated - -Fixates a `Structure` by changing the given field to the nearest -integer to `target` that is a subset of the existing field. -## `field_name` -a field in `self` -## `target` -the target value of the fixation - -# Returns - -`true` if the structure could be fixated - -Fixates a `Structure` by changing the given `field_name` field to the given -`target` string if that field is not fixed yet. -## `field_name` -a field in `self` -## `target` -the target value of the fixation - -# Returns - -`true` if the structure could be fixated - -Calls the provided function once for each field in the `Structure`. The -function must not modify the fields. Also see `Structure::map_in_place` -and `Structure::filter_and_map_in_place`. -## `func` -a function to call for each field -## `user_data` -private data - -# Returns - -`true` if the supplied function returns `true` For each of the fields, -`false` otherwise. - -Frees a `Structure` and all its fields and values. The structure must not -have a parent when this function is called. - -Parses the variable arguments and reads fields from `self` accordingly. -Variable arguments should be in the form field name, field type -(as a GType), pointer(s) to a variable(s) to hold the return value(s). -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 -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` -the name of the first field to read - -# Returns - -`false` if there was a problem reading any of the fields (e.g. - because the field requested did not exist, or was of a type other - than the type specified), otherwise `true`. - -This is useful in language bindings where unknown `glib::object::Value` types are not -supported. This function will convert the `GST_TYPE_ARRAY` into a newly -allocated `glib::object::ValueArray` and return it through `array`. Be aware that this is -slower then getting the `glib::object::Value` directly. - -Feature: `v1_12` - -## `fieldname` -the name of a field -## `array` -a pointer to a `glib::object::ValueArray` - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a `GST_TYPE_ARRAY`, -this function returns `false`. - -Sets the boolean pointed to by `value` corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. -## `fieldname` -the name of a field -## `value` -a pointer to a `gboolean` to set - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a boolean, this -function returns `false`. - -Sets the clock time pointed to by `value` corresponding to the clock time -of the given field. Caller is responsible for making sure the field exists -and has the correct type. -## `fieldname` -the name of a field -## `value` -a pointer to a `ClockTime` to set - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a `ClockTime`, this -function returns `false`. - -Sets the date pointed to by `value` corresponding to the date of the -given field. Caller is responsible for making sure the field exists -and has the correct type. - -On success `value` will point to a newly-allocated copy of the date which -should be freed with `glib::Date::free` when no longer needed (note: this is -inconsistent with e.g. `Structure::get_string` which doesn't return a -copy of the string). -## `fieldname` -the name of a field -## `value` -a pointer to a `glib::Date` to set - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a data, this function -returns `false`. - -Sets the datetime pointed to by `value` corresponding to the datetime of the -given field. Caller is responsible for making sure the field exists -and has the correct type. - -On success `value` will point to a reference of the datetime which -should be unreffed with `DateTime::unref` when no longer needed -(note: this is inconsistent with e.g. `Structure::get_string` -which doesn't return a copy of the string). -## `fieldname` -the name of a field -## `value` -a pointer to a `DateTime` to set - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a data, this function -returns `false`. - -Sets the double pointed to by `value` corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. -## `fieldname` -the name of a field -## `value` -a pointer to a gdouble to set - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a double, this -function returns `false`. - -Sets the int pointed to by `value` corresponding to the value of the -given field. Caller is responsible for making sure the field exists, -has the correct type and that the enumtype is correct. -## `fieldname` -the name of a field -## `enumtype` -the enum type of a field -## `value` -a pointer to an int to set - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain an enum of the given -type, this function returns `false`. - -Finds the field with the given name, and returns the type of the -value it contains. If the field is not found, G_TYPE_INVALID is -returned. -## `fieldname` -the name of the field - -# Returns - -the `glib::object::Value` of the field - -Read the GstFlagSet flags and mask out of the structure into the -provided pointers. -## `fieldname` -the name of a field -## `value_flags` -a pointer to a guint for the flags field -## `value_mask` -a pointer to a guint for the mask field - -# Returns - -`true` if the values could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a GstFlagSet, this -function returns `false`. - -Sets the integers pointed to by `value_numerator` and `value_denominator` -corresponding to the value of the given field. Caller is responsible -for making sure the field exists and has the correct type. -## `fieldname` -the name of a field -## `value_numerator` -a pointer to an int to set -## `value_denominator` -a pointer to an int to set - -# Returns - -`true` if the values could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a GstFraction, this -function returns `false`. - -Sets the int pointed to by `value` corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. -## `fieldname` -the name of a field -## `value` -a pointer to an int to set - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain an int, this function -returns `false`. - -Sets the `gint64` pointed to by `value` corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. -## `fieldname` -the name of a field -## `value` -a pointer to a `gint64` to set - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a `gint64`, this function -returns `false`. - -This is useful in language bindings where unknown `glib::object::Value` types are not -supported. This function will convert the `GST_TYPE_LIST` into a newly -allocated GValueArray and return it through `array`. Be aware that this is -slower then getting the `glib::object::Value` directly. - -Feature: `v1_12` - -## `fieldname` -the name of a field -## `array` -a pointer to a `glib::object::ValueArray` - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a `GST_TYPE_LIST`, this -function returns `false`. - -Get the name of `self` as a string. - -# Returns - -the name of the structure. - -Get the name of `self` as a GQuark. - -# Returns - -the quark representing the name of the structure. - -Finds the field corresponding to `fieldname`, and returns the string -contained in the field's value. Caller is responsible for making -sure the field exists and has the correct type. - -The string should not be modified, and remains valid until the next -call to a gst_structure_*() function with the given structure. -## `fieldname` -the name of a field - -# Returns - -a pointer to the string or `None` when the -field did not exist or did not contain a string. - -Sets the uint pointed to by `value` corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. -## `fieldname` -the name of a field -## `value` -a pointer to a uint to set - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a uint, this function -returns `false`. - -Sets the `guint64` pointed to by `value` corresponding to the value of the -given field. Caller is responsible for making sure the field exists -and has the correct type. -## `fieldname` -the name of a field -## `value` -a pointer to a `guint64` to set - -# Returns - -`true` if the value could be set correctly. If there was no field -with `fieldname` or the existing field did not contain a `guint64`, this function -returns `false`. - -Parses the variable arguments and reads fields from `self` accordingly. -valist-variant of `Structure::get`. Look at the documentation of -`Structure::get` for more details. -## `first_fieldname` -the name of the first field to read -## `args` -variable arguments - -# Returns - -`true`, or `false` if there was a problem reading any of the fields - -Get the value of the field with name `fieldname`. -## `fieldname` -the name of the field to get - -# Returns - -the `glib::object::Value` corresponding to the field with the given -name. - -Check if `self` contains a field named `fieldname`. -## `fieldname` -the name of a field - -# Returns - -`true` if the structure contains a field with the given name - -Check if `self` contains a field named `fieldname` and with GType `type_`. -## `fieldname` -the name of a field -## `type_` -the type of a value - -# Returns - -`true` if the structure contains a field with the given name and type - -Checks if the structure has the given name -## `name` -structure name to check for - -# Returns - -`true` if `name` matches the name of the structure. - -Parses the variable arguments and reads fields from `self` accordingly. -Variable arguments should be in the form field id quark, field type -(as a GType), pointer(s) to a variable(s) to hold the return value(s). -The last variable argument should be `None` (technically it should be a -0 quark, but we require `None` so compilers that support it can check for -the `None` terminator and warn if it's not there). - -This function is just like `Structure::get` only that it is slightly -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 -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` -the quark of the first field to read - -# Returns - -`false` if there was a problem reading any of the fields (e.g. - because the field requested did not exist, or was of a type other - than the type specified), otherwise `true`. - -Parses the variable arguments and reads fields from `self` accordingly. -valist-variant of `Structure::id_get`. Look at the documentation of -`Structure::id_get` for more details. -## `first_field_id` -the quark of the first field to read -## `args` -variable arguments - -# Returns - -`true`, or `false` if there was a problem reading any of the fields - -Get the value of the field with GQuark `field`. -## `field` -the `glib::Quark` of the field to get - -# Returns - -the `glib::object::Value` corresponding to the field with the given -name identifier. - -Check if `self` contains a field named `field`. -## `field` -`glib::Quark` of the field name - -# Returns - -`true` if the structure contains a field with the given name - -Check if `self` contains a field named `field` and with GType `type_`. -## `field` -`glib::Quark` of the field name -## `type_` -the type of a value - -# Returns - -`true` if the structure contains a field with the given name and type - -Identical to gst_structure_set, except that field names are -passed using the GQuark for the field name. This allows more efficient -setting of the structure if the caller already knows the associated -quark values. -The last variable argument must be `None`. -## `fieldname` -the GQuark for the name of the field to set - -va_list form of `Structure::id_set`. -## `fieldname` -the name of the field to set -## `varargs` -variable arguments - -Sets the field with the given GQuark `field` to `value`. If the field -does not exist, it is created. If the field exists, the previous -value is replaced and freed. -## `field` -a `glib::Quark` representing a field -## `value` -the new value of the field - -Sets the field with the given GQuark `field` to `value`. If the field -does not exist, it is created. If the field exists, the previous -value is replaced and freed. -## `field` -a `glib::Quark` representing a field -## `value` -the new value of the field - -Intersects `self` and `struct2` and returns the intersection. -## `struct2` -a `Structure` - -# Returns - -Intersection of `self` and `struct2` - -Tests if the two `Structure` are equal. -## `structure2` -a `Structure`. - -# Returns - -`true` if the two structures have the same name and field. - -Checks if `self` is a subset of `superset`, i.e. has the same -structure name and for all fields that are existing in `superset`, -`self` has a value that is a subset of the value in `superset`. -## `superset` -a potentially greater `Structure` - -# Returns - -`true` if `self` is a subset of `superset` - -Calls the provided function once for each field in the `Structure`. In -contrast to `Structure::foreach`, the function may modify but not delete the -fields. The structure must be mutable. -## `func` -a function to call for each field -## `user_data` -private data - -# Returns - -`true` if the supplied function returns `true` For each of the fields, -`false` otherwise. - -Get the number of fields in the structure. - -# Returns - -the number of fields in the structure - -Get the name of the given field number, counting from 0 onwards. -## `index` -the index to get the name of - -# Returns - -the name of the given field number - -Removes all fields in a GstStructure. - -Removes the field with the given name. If the field with the given -name does not exist, the structure is unchanged. -## `fieldname` -the name of the field to remove - -Removes the fields with the given names. If a field does not exist, the -argument is ignored. -## `fieldname` -the name of the field to remove - -va_list form of `Structure::remove_fields`. -## `fieldname` -the name of the field to remove -## `varargs` -`None`-terminated list of more fieldnames to remove - -Parses the variable arguments and sets fields accordingly. Fields that -weren't already part of the structure are added as needed. -Variable arguments should be in the form field name, field type -(as a GType), value(s). The last variable argument should be `None`. -## `fieldname` -the name of the field to set - -This is useful in language bindings where unknown GValue types are not -supported. This function will convert a `array` to `GST_TYPE_ARRAY` and set -the field specified by `fieldname`. Be aware that this is slower then using -`GST_TYPE_ARRAY` in a `glib::object::Value` directly. - -Feature: `v1_12` - -## `fieldname` -the name of a field -## `array` -a pointer to a `glib::object::ValueArray` - -This is useful in language bindings where unknown GValue types are not -supported. This function will convert a `array` to `GST_TYPE_LIST` and set -the field specified by `fieldname`. Be aware that this is slower then using -`GST_TYPE_LIST` in a `glib::object::Value` directly. - -Feature: `v1_12` - -## `fieldname` -the name of a field -## `array` -a pointer to a `glib::object::ValueArray` - -Sets the name of the structure to the given `name`. The string -provided is copied before being used. It must not be empty, start with a -letter and can be followed by letters, numbers and any of "/-_.:". -## `name` -the new name of the structure - -Sets the parent_refcount field of `Structure`. This field is used to -determine whether a structure is mutable or not. This function should only be -called by code implementing parent objects of `Structure`, as described in -the MT Refcounting section of the design documents. -## `refcount` -a pointer to the parent's refcount - -# Returns - -`true` if the parent refcount could be set. - -va_list form of `Structure::set`. -## `fieldname` -the name of the field to set -## `varargs` -variable arguments - -Sets the field with the given name `field` to `value`. If the field -does not exist, it is created. If the field exists, the previous -value is replaced and freed. -## `fieldname` -the name of the field to set -## `value` -the new value of the field - -Sets the field with the given name `field` to `value`. If the field -does not exist, it is created. If the field exists, the previous -value is replaced and freed. The function will take ownership of `value`. -## `fieldname` -the name of the field to set -## `value` -the new value of the field - -Converts `self` to a human-readable string representation. - -For debugging purposes its easier to do something like this: - -```C -GST_LOG ("structure is %" GST_PTR_FORMAT, structure); -``` -This prints the structure in human readable form. - -The current implementation of serialization will lead to unexpected results -when there are nested `Caps` / `Structure` deeper than one level. - -Free-function: g_free - -# Returns - -a pointer to string allocated by `g_malloc`. - `g_free` after usage. - -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. - -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 - -`true` if `newstr` was different from `oldstr_ptr` - -The type of a `MessageType::StructureChange`. - -Pad linking is starting or done. - -Pad unlinking is starting or done. - -The GStreamer core provides a GstSystemClock based on the system time. -Asynchronous callbacks are scheduled from an internal thread. - -Clock implementors are encouraged to subclass this systemclock as it -implements the async notification. - -Subclasses can however override all of the important methods for sync and -async notifications to implement their own callback methods or blocking -wait operations. - -# Implements - -[`SystemClockExt`](trait@crate::SystemClockExt), [`ClockExt`](trait@crate::ClockExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`ClockExtManual`](trait@crate::ClockExtManual) - -Trait containing all `SystemClock` methods. - -# Implementors - -[`SystemClock`](struct@crate::SystemClock) - -Get a handle to the default system clock. The refcount of the -clock will be increased so you need to unref the clock after -usage. - -# Returns - -the default clock. - -MT safe. - -Sets the default system clock that can be obtained with -`SystemClock::obtain`. - -This is mostly used for testing and debugging purposes when you -want to have control over the time reported by the default system -clock. - -MT safe. -## `new_clock` -a `Clock` - -Extra tag flags used when registering tags. - -undefined flag - -tag is meta data - -tag is encoded - -tag is decoded - -number of tag flags - -List of tags and values used to describe media metadata. - -Strings in structures must be ASCII or UTF-8 encoded. Other encodings are -not allowed. Strings must not be empty or `None`. - -Creates a new taglist and appends the values for the given tags. It expects -tag-value pairs like `TagList::add`, and a `None` terminator after the -last pair. The type of the values is implicit and is documented in the API -reference, but can also be queried at runtime with `gst_tag_get_type`. It -is an error to pass a value of a type not matching the tag type into this -function. The tag list will make copies of any arguments passed -(e.g. strings, buffers). - -After creation you might also want to set a `TagScope` on the returned -taglist to signal if the contained tags are global or stream tags. By -default stream scope is assumes. See `TagList::set_scope`. - -Free-function: gst_tag_list_unref -## `tag` -tag - -# Returns - -a new `TagList`. Free with `gst_tag_list_unref` - when no longer needed. - -Creates a new empty GstTagList. - -Free-function: gst_tag_list_unref - -# Returns - -An empty tag list - -Deserializes a tag list. -## `str` -a string created with `TagList::to_string` - -# Returns - -a new `TagList`, or `None` in case of an -error. - -Just like `TagList::new`, only that it takes a va_list argument. -Useful mostly for language bindings. - -Free-function: gst_tag_list_unref -## `var_args` -tag / value pairs to set - -# Returns - -a new `TagList`. Free with `gst_tag_list_unref` - when no longer needed. - -Sets the values for the given tags using the specified mode. -## `mode` -the mode to use -## `tag` -tag - -Sets the values for the given tags using the specified mode. -## `mode` -the mode to use -## `tag` -tag -## `var_args` -tag / value pairs to set - -Sets the GValues for the given tags using the specified mode. -## `mode` -the mode to use -## `tag` -tag -## `var_args` -tag / GValue pairs to set - -Sets the GValue for a given tag using the specified mode. -## `mode` -the mode to use -## `tag` -tag -## `value` -GValue for this tag - -Sets the GValues for the given tags using the specified mode. -## `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 `gst_tag_list_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 `gst_tag_list_ref`. - -When you are finished with the taglist, call `gst_tag_list_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. -## `func` -function to be called for each tag -## `user_data` -user specified data - -Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. -## `tag` -tag to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Gets the value that is at the given index for the given tag in the given -list. -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Copies the first date for the given tag in the taglist into the variable -pointed to by `value`. Free the date with `glib::Date::free` when it is no longer -needed. - -Free-function: g_date_free -## `tag` -tag to read out -## `value` -address of a GDate pointer - variable to store the result into - -# Returns - -`true`, if a date was copied, `false` if the tag didn't exist in the - given list or if it was `None`. - -Gets the date that is at the given index for the given tag in the given -list and copies it into the variable pointed to by `value`. Free the date -with `glib::Date::free` when it is no longer needed. - -Free-function: g_date_free -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list or if it was `None`. - -Copies the first datetime for the given tag in the taglist into the variable -pointed to by `value`. Unref the date with `DateTime::unref` when -it is no longer needed. - -Free-function: gst_date_time_unref -## `tag` -tag to read out -## `value` -address of a `DateTime` - pointer variable to store the result into - -# Returns - -`true`, if a datetime was copied, `false` if the tag didn't exist in - the given list or if it was `None`. - -Gets the datetime that is at the given index for the given tag in the given -list and copies it into the variable pointed to by `value`. Unref the datetime -with `DateTime::unref` when it is no longer needed. - -Free-function: gst_date_time_unref -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list or if it was `None`. - -Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. -## `tag` -tag to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Gets the value that is at the given index for the given tag in the given -list. -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. -## `tag` -tag to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Gets the value that is at the given index for the given tag in the given -list. -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. -## `tag` -tag to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. -## `tag` -tag to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Gets the value that is at the given index for the given tag in the given -list. -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Gets the value that is at the given index for the given tag in the given -list. -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. -## `tag` -tag to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Gets the value that is at the given index for the given tag in the given -list. -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -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 -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`. - -Free-function: gst_sample_unref -## `tag` -tag to read out -## `sample` -address of a GstSample - pointer variable to store the result into - -# Returns - -`true`, if a sample was returned, `false` if the tag didn't exist in - the given list or if it was `None`. - -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 -buffer from the sample using `Sample::get_buffer` and the associated -caps (if any) with `Sample::get_caps`. - -Free-function: gst_sample_unref -## `tag` -tag to read out -## `index` -number of entry to read out -## `sample` -address of a GstSample - pointer variable to store the result into - -# Returns - -`true`, if a sample was copied, `false` if the tag didn't exist in the - given list or if it was `None`. - -Gets the scope of `self`. - -# Returns - -The scope of `self` - -Copies the contents for the given tag into the value, possibly merging -multiple values into one if multiple values are associated with the tag. - -Use gst_tag_list_get_string_index (list, tag, 0, value) if you want -to retrieve the first string associated with this tag unmodified. - -The resulting string in `value` will be in UTF-8 encoding and should be -freed by the caller using g_free when no longer needed. The -returned string is also guaranteed to be non-`None` and non-empty. - -Free-function: g_free -## `tag` -tag to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Gets the value that is at the given index for the given tag in the given -list. - -The resulting string in `value` will be in UTF-8 encoding and should be -freed by the caller using g_free when no longer needed. The -returned string is also guaranteed to be non-`None` and non-empty. - -Free-function: g_free -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Checks how many value are stored in this tag list for the given tag. -## `tag` -the tag to query - -# Returns - -The number of tags stored - -Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. -## `tag` -tag to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Copies the contents for the given tag into the value, merging multiple values -into one if multiple values are associated with the tag. -## `tag` -tag to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Gets the value that is at the given index for the given tag in the given -list. -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Gets the value that is at the given index for the given tag in the given -list. -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -Gets the value that is at the given index for the given tag in the given -list. -## `tag` -tag to read out -## `index` -number of entry to read out - -# Returns - -The GValue for the specified - entry or `None` if the tag wasn't available or the tag - doesn't have as many entries - -Inserts the tags of the `from` list into the first list using the given mode. -## `from` -list to merge from -## `mode` -the mode to use - -Checks if the given taglist is empty. - -# Returns - -`true` if the taglist is empty, otherwise `false`. - -Checks if the two given taglists are equal. -## `list2` -a `TagList`. - -# Returns - -`true` if the taglists are equal, otherwise `false` - -Merges the two given lists into a new list. If one of the lists is `None`, a -copy of the other is returned. If both lists are `None`, `None` is returned. - -Free-function: gst_tag_list_unref -## `list2` -second list to merge -## `mode` -the mode to use - -# Returns - -the new list - -Get the number of tags in `self`. - -# Returns - -The number of tags in `self`. - -Get the name of the tag in `self` at `index`. -## `index` -the index - -# Returns - -The name of the tag at `index`. - -Peeks at the value that is at the given index for the given tag in the given -list. - -The resulting string in `value` will be in UTF-8 encoding and doesn't need -to be freed by the caller. The returned string is also guaranteed to -be non-`None` and non-empty. -## `tag` -tag to read out -## `index` -number of entry to read out -## `value` -location for the result - -# Returns - -`true`, if a value was set, `false` if the tag didn't exist in the - given list. - -Removes the given tag from the taglist. -## `tag` -tag to remove - -Sets the scope of `self` to `scope`. By default the scope -of a taglist is stream scope. -## `scope` -new scope for `self` - -Serializes a tag list to a string. - -# Returns - -a newly-allocated string, or `None` in case of - an error. The string must be freed with `g_free` when no longer - needed. - -Copies the contents for the given tag into the value, -merging multiple values into one if multiple values are associated -with the tag. -You must `glib::object::Value::unset` the value after use. -## `dest` -uninitialized `glib::object::Value` to copy into -## `list` -list to get the tag from -## `tag` -tag to read out - -# Returns - -`true`, if a value was copied, `false` if the tag didn't exist in the - given list. - -The different tag merging modes are basically replace, overwrite and append, -but they can be seen from two directions. Given two taglists: (A) the tags -already in the element and (B) the ones that are supplied to the element ( -e.g. via `TagSetter::merge_tags` / `TagSetter::add_tags` or a -`EventType::Tag`), how are these tags merged? -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 | 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 - -replace all tags (clear list and append) - -replace tags - -append tags - -prepend tags - -keep existing tags - -keep all existing tags - -the number of merge modes - -GstTagScope specifies if a taglist applies to the complete -medium or only to one single stream. - -tags specific to this single stream - -global tags for the complete medium - -Element interface that allows setting of media metadata. - -Elements that support changing a stream's metadata will implement this -interface. Examples of such elements are 'vorbisenc', 'theoraenc' and -'id3v2mux'. - -If you just want to retrieve metadata in your application then all you -need to do is watch for tag messages on your pipeline's bus. This -interface is only for setting metadata, not for extracting it. To set tags -from the application, find tagsetter elements and set tags using e.g. -`TagSetter::merge_tags` or `TagSetter::add_tags`. Also consider -setting the `TagMergeMode` that is used for tag events that arrive at the -tagsetter element (default mode is to keep existing tags). -The application should do that before the element goes to `State::Paused`. - -Elements implementing the `TagSetter` interface often have to merge -any tags received from upstream and the tags set by the application via -the interface. This can be done like this: - - -```C -GstTagMergeMode merge_mode; -const GstTagList *application_tags; -const GstTagList *event_tags; -GstTagSetter *tagsetter; -GstTagList *result; - -tagsetter = GST_TAG_SETTER (element); - -merge_mode = gst_tag_setter_get_tag_merge_mode (tagsetter); -application_tags = gst_tag_setter_get_tag_list (tagsetter); -event_tags = (const GstTagList *) element->event_tags; - -GST_LOG_OBJECT (tagsetter, "merging tags, merge mode = %d", merge_mode); -GST_LOG_OBJECT (tagsetter, "event tags: %" GST_PTR_FORMAT, event_tags); -GST_LOG_OBJECT (tagsetter, "set tags: %" GST_PTR_FORMAT, application_tags); - -result = gst_tag_list_merge (application_tags, event_tags, merge_mode); - -GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result); -``` - -# Implements - -[`TagSetterExt`](trait@crate::TagSetterExt), [`ElementExt`](trait@crate::ElementExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`TagSetterExtManual`](trait@crate::TagSetterExtManual), [`ElementExtManual`](trait@crate::ElementExtManual) - -Trait containing all `TagSetter` methods. - -# Implementors - -[`TagSetter`](struct@crate::TagSetter) - -Adds the given tag / value pairs on the setter using the given merge mode. -The list must be terminated with `None`. -## `mode` -the mode to use -## `tag` -tag to set -## `var_args` -tag / value pairs to set - -Adds the given tag / GValue pairs on the setter using the given merge mode. -The list must be terminated with `None`. -## `mode` -the mode to use -## `tag` -tag to set -## `var_args` -tag / GValue pairs to set - -Adds the given tag / GValue pair on the setter using the given merge mode. -## `mode` -the mode to use -## `tag` -tag to set -## `value` -GValue to set for the tag - -Adds the given tag / GValue pairs on the setter using the given merge mode. -The list must be terminated with `None`. -## `mode` -the mode to use -## `tag` -tag to set - -Adds the given tag / value pairs on the setter using the given merge mode. -The list must be terminated with `None`. -## `mode` -the mode to use -## `tag` -tag to set - -Returns the current list of tags the setter uses. The list should not be -modified or freed. - -This function is not thread-safe. - -# Returns - -a current snapshot of the - taglist used in the setter or `None` if none is used. - -Queries the mode by which tags inside the setter are overwritten by tags -from events - -# Returns - -the merge mode used inside the element. - -Merges the given list into the setter's list using the given mode. -## `list` -a tag list to merge from -## `mode` -the mode to merge with - -Reset the internal taglist. Elements should call this from within the -state-change handler. - -Sets the given merge mode that is used for adding tags from events to tags -specified by this interface. The default is `TagMergeMode::Keep`, which keeps -the tags set with this interface and discards tags from events. -## `mode` -The mode with which tags are added - -The different states a task can be in - -the task is started and running - -the task is stopped - -the task is paused - -`Toc` functions are used to create/free `Toc` and `TocEntry` structures. -Also they are used to convert `Toc` into `Structure` and vice versa. - -`Toc` lets you to inform other elements in pipeline or application that playing -source has some kind of table of contents (TOC). These may be chapters, editions, -angles or other types. For example: DVD chapters, Matroska chapters or cue sheet -TOC. Such TOC will be useful for applications to display instead of just a -playlist. - -Using TOC is very easy. Firstly, create `Toc` structure which represents root -contents of the source. You can also attach TOC-specific tags to it. Then fill -it with `TocEntry` entries by appending them to the `Toc` using -`Toc::append_entry`, and appending subentries to a `TocEntry` using -`TocEntry::append_sub_entry`. - -Note that root level of the TOC can contain only either editions or chapters. You -should not mix them together at the same level. Otherwise you will get serialization -/deserialization errors. Make sure that no one of the entries has negative start and - stop values. - -Use `Event::new_toc` to create a new TOC `Event`, and `Event::parse_toc` to -parse received TOC event. Use `Event::new_toc_select` to create a new TOC select `Event`, -and `Event::parse_toc_select` to parse received TOC select event. The same rule for -the `Message`: `Message::new_toc` to create new TOC `Message`, and -`Message::parse_toc` to parse received TOC message. - -TOCs can have global scope or current scope. Global scope TOCs contain -all entries that can possibly be selected using a toc select event, and -are what an application is usually interested in. TOCs with current scope -only contain the parts of the TOC relevant to the currently selected/playing -stream; the current scope TOC is used by downstream elements such as muxers -to write correct TOC entries when transcoding files, for example. When -playing a DVD, the global TOC would contain a hierarchy of all titles, -chapters and angles, for example, while the current TOC would only contain -the chapters for the currently playing title if playback of a specific -title was requested. - -Applications and plugins should not rely on TOCs having a certain kind of -structure, but should allow for different alternatives. For example, a -simple CUE sheet embedded in a file may be presented as a flat list of -track entries, or could have a top-level edition node (or some other -alternative type entry) with track entries underneath that node; or even -multiple top-level edition nodes (or some other alternative type entries) -each with track entries underneath, in case the source file has extracted -a track listing from different sources). - -Create a new `Toc` structure. -## `scope` -scope of this TOC - -# Returns - -newly allocated `Toc` structure, free it - with `gst_toc_unref`. - -Appends the `TocEntry` `entry` to `self`. -## `entry` -A `TocEntry` - -Find `TocEntry` with given `uid` in the `self`. -## `uid` -UID to find `TocEntry` with. - -# Returns - -`TocEntry` with specified -`uid` from the `self`, or `None` if not found. - -Gets the list of `TocEntry` of `self`. - -# Returns - -A `glib::List` of `TocEntry` for `entry` - - -# Returns - -scope of `self` - -Gets the tags for `self`. - -# Returns - -A `TagList` for `entry` - -Merge `tags` into the existing tags of `self` using `mode`. -## `tags` -A `TagList` or `None` -## `mode` -A `TagMergeMode` - -Set a `TagList` with tags for the complete `self`. -## `tags` -A `TagList` or `None` - - -Create new `TocEntry` structure. -## `type_` -entry type. -## `uid` -unique ID (UID) in the whole TOC. - -# Returns - -newly allocated `TocEntry` structure, free it with `gst_toc_entry_unref`. - -Appends the `TocEntry` `subentry` to `self`. -## `subentry` -A `TocEntry` - - -# Returns - -`self`'s entry type - -Get `loop_type` and `repeat_count` values from the `self` and write them into -appropriate storages. Loops are e.g. used by sampled instruments. GStreamer -is not automatically applying the loop. The application can process this -meta data and use it e.g. to send a seek-event to loop a section. -## `loop_type` -the storage for the loop_type - value, leave `None` if not need. -## `repeat_count` -the storage for the repeat_count - value, leave `None` if not need. - -# Returns - -`true` if all non-`None` storage pointers were filled with appropriate -values, `false` otherwise. - -Gets the parent `TocEntry` of `self`. - -# Returns - -The parent `TocEntry` of `self` - -Get `start` and `stop` values from the `self` and write them into appropriate -storages. -## `start` -the storage for the start value, leave - `None` if not need. -## `stop` -the storage for the stop value, leave - `None` if not need. - -# Returns - -`true` if all non-`None` storage pointers were filled with appropriate -values, `false` otherwise. - -Gets the sub-entries of `self`. - -# Returns - -A `glib::List` of `TocEntry` of `self` - -Gets the tags for `self`. - -# Returns - -A `TagList` for `self` - -Gets the parent `Toc` of `self`. - -# Returns - -The parent `Toc` of `self` - -Gets the UID of `self`. - -# Returns - -The UID of `self` - - -# Returns - -`true` if `self`'s type is an alternative type, otherwise `false` - - -# Returns - -`true` if `self`'s type is a sequence type, otherwise `false` - -Merge `tags` into the existing tags of `self` using `mode`. -## `tags` -A `TagList` or `None` -## `mode` -A `TagMergeMode` - -Set `loop_type` and `repeat_count` values for the `self`. -## `loop_type` -loop_type value to set. -## `repeat_count` -repeat_count value to set. - -Set `start` and `stop` values for the `self`. -## `start` -start value to set. -## `stop` -stop value to set. - -Set a `TagList` with tags for the complete `self`. -## `tags` -A `TagList` or `None` - -The different types of TOC entries (see `TocEntry`). - -There are two types of TOC entries: alternatives or parts in a sequence. - -entry is an angle (i.e. an alternative) - -entry is a version (i.e. alternative) - -entry is an edition (i.e. alternative) - -invalid entry type value - -entry is a title (i.e. a part of a sequence) - -entry is a track (i.e. a part of a sequence) - -entry is a chapter (i.e. a part of a sequence) - -How a `TocEntry` should be repeated. By default, entries are played a -single time. - -single forward playback - -repeat forward - -repeat backward - -repeat forward and backward - -The scope of a TOC. - -global TOC representing all selectable options - (this is what applications are usually interested in) - -TOC for the currently active/selected stream - (this is a TOC representing the current stream from start to EOS, - and is what a TOC writer / muxer is usually interested in; it will - usually be a subset of the global TOC, e.g. just the chapters of - the current title, or the chapters selected for playback from the - current title) - -Element interface that allows setting of the TOC. - -Elements that support some kind of chapters or editions (or tracks like in -the FLAC cue sheet) will implement this interface. - -If you just want to retrieve the TOC in your application then all you -need to do is watch for TOC messages on your pipeline's bus (or you can -perform TOC query). This interface is only for setting TOC data, not for -extracting it. To set TOC from the application, find proper tocsetter element -and set TOC using `TocSetter::set_toc`. - -Elements implementing the `TocSetter` interface can extend existing TOC -by getting extend UID for that (you can use `Toc::find_entry` to retrieve it) -with any TOC entries received from downstream. - -# Implements - -[`TocSetterExt`](trait@crate::TocSetterExt), [`ElementExt`](trait@crate::ElementExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`ElementExtManual`](trait@crate::ElementExtManual) - -Trait containing all `TocSetter` methods. - -# Implementors - -[`TocSetter`](struct@crate::TocSetter) - -Return current TOC the setter uses. The TOC should not be -modified without making it writable first. - -# Returns - -TOC set, or `None`. Unref with - `gst_toc_unref` when no longer needed - -Reset the internal TOC. Elements should call this from within the -state-change handler. - -Set the given TOC on the setter. Previously set TOC will be -unreffed before setting a new one. -## `toc` -a `Toc` to set. - -These functions allow querying information about registered typefind -functions. How to create and register these functions is described in -the section -"Writing typefind functions"``. - -The following example shows how to write a very simple typefinder that -identifies the given data. You can get quite a bit more complicated than -that though. - -```C - typedef struct { - guint8 *data; - guint size; - guint probability; - GstCaps *data; - } MyTypeFind; - static void - my_peek (gpointer data, gint64 offset, guint size) - { - MyTypeFind *find = (MyTypeFind *) data; - if (offset >= 0 && offset + size <= find->size) { - return find->data + offset; - } - return NULL; - } - static void - my_suggest (gpointer data, guint probability, GstCaps *caps) - { - MyTypeFind *find = (MyTypeFind *) data; - if (probability > find->probability) { - find->probability = probability; - gst_caps_replace (&find->caps, caps); - } - } - static GstCaps * - find_type (guint8 *data, guint size) - { - GList *walk, *type_list; - MyTypeFind find = {data, size, 0, NULL}; - GstTypeFind gst_find = {my_peek, my_suggest, &find, }; - walk = type_list = gst_type_find_factory_get_list (); - while (walk) { - GstTypeFindFactory *factory = GST_TYPE_FIND_FACTORY (walk->data); - walk = g_list_next (walk) - gst_type_find_factory_call_function (factory, &gst_find); - } - g_list_free (type_list); - return find.caps; - }; -``` - -# Implements - -[`PluginFeatureExt`](trait@crate::PluginFeatureExt), [`GstObjectExt`](trait@crate::GstObjectExt), [`trait@glib::object::ObjectExt`], [`PluginFeatureExtManual`](trait@crate::PluginFeatureExtManual) - -Gets the list of all registered typefind factories. You must free the -list using `PluginFeature::list_free`. - -The returned factories are sorted by highest rank first, and then by -factory name. - -Free-function: gst_plugin_feature_list_free - -# Returns - -the list of all - registered `TypeFindFactory`. - -Calls the `GstTypeFindFunction` associated with this factory. -## `find` -a properly setup `TypeFind` entry. The get_data - and suggest_type members must be set. - -Gets the `Caps` associated with a typefind factory. - -# Returns - -the `Caps` associated with this factory - -Gets the extensions associated with a `TypeFindFactory`. The returned -array should not be changed. If you need to change stuff in it, you should -copy it using `g_strdupv`. This function may return `None` to indicate -a 0-length list. - -# Returns - - - a `None`-terminated array of extensions associated with this factory - -Check whether the factory has a typefind function. Typefind factories -without typefind functions are a last-effort fallback mechanism to -e.g. assume a certain media type based on the file extension. - -# Returns - -`true` if the factory has a typefind functions set, otherwise `false` - -The probability of the typefind function. Higher values have more certainty -in doing a reliable typefind. - -type undetected. - -unlikely typefind. - -possible type detected. - -likely a type was detected. - -nearly certain that a type was detected. - -very certain a type was detected. - -Different URI-related errors that can occur. - -The protocol is not supported - -There was a problem with the URI - -Could not set or change the URI because the - URI handler was in a state where that is not possible or not permitted - -There was a problem with the entity that - the URI references - -The `URIHandler` is an interface that is implemented by Source and Sink -`Element` to unify handling of URI. - -An application can use the following functions to quickly get an element -that handles the given URI for reading or writing -(`Element::make_from_uri`). - -Source and Sink plugins should implement this interface when possible. - -# Implements - -[`URIHandlerExt`](trait@crate::URIHandlerExt) - -Trait containing all `URIHandler` methods. - -# Implementors - -[`URIHandler`](struct@crate::URIHandler) - -Gets the list of protocols supported by `self`. This list may not be -modified. - -# Returns - -the - supported protocols. Returns `None` if the `self` isn't - implemented properly, or the `self` doesn't support any - protocols. - -Gets the currently handled URI. - -# Returns - -the URI currently handled by - the `self`. Returns `None` if there are no URI currently - handled. The returned string must be freed with `g_free` when no - longer needed. - -Gets the type of the given URI handler - -# Returns - -the `URIType` of the URI handler. -Returns `URIType::Unknown` if the `self` isn't implemented correctly. - -Tries to set the URI of the given handler. -## `uri` -URI to set - -# Returns - -`true` if the URI was set successfully, else `false`. - -The different types of URI direction. - -The URI direction is unknown - -The URI is a consumer. - -The URI is a producer. diff --git a/docs/src/lib.rs b/docs/src/lib.rs deleted file mode 100644 index d05301bbe..000000000 --- a/docs/src/lib.rs +++ /dev/null @@ -1,88 +0,0 @@ -use std::io; -use std::path::Path; -use stripper_lib::{loop_over_files, parse_cmts, regenerate_comments, strip_comments}; - -#[derive(Clone, Copy, Debug)] -pub enum Library { - GstWebRTC, - GstVideo, - GstSdp, - GstRtspServer, - GstRtsp, - GstRtp, - GstPlayer, - GstNet, - GstGL, - GES, - GstCheck, - GstPbutils, - GstBase, - GstAudio, - GstApp, - Gst, - GstController, -} - -fn docs(lib: Library) -> &'static str { - match lib { - Library::GstWebRTC => include_str!("../gstreamer-webrtc/docs.md"), - Library::GstVideo => include_str!("../gstreamer-video/docs.md"), - Library::GstSdp => include_str!("../gstreamer-sdp/docs.md"), - Library::GstRtspServer => include_str!("../gstreamer-rtsp-server/docs.md"), - Library::GstRtsp => include_str!("../gstreamer-rtsp/docs.md"), - Library::GstRtp => include_str!("../gstreamer-rtp/docs.md"), - Library::GstPlayer => include_str!("../gstreamer-player/docs.md"), - Library::GstNet => include_str!("../gstreamer-net/docs.md"), - Library::GstGL => include_str!("../gstreamer-gl/docs.md"), - Library::GES => include_str!("../gstreamer-editing-services/docs.md"), - Library::GstCheck => include_str!("../gstreamer-check/docs.md"), - Library::GstPbutils => include_str!("../gstreamer-pbutils/docs.md"), - Library::GstBase => include_str!("../gstreamer-base/docs.md"), - Library::GstAudio => include_str!("../gstreamer-audio/docs.md"), - Library::GstApp => include_str!("../gstreamer-app/docs.md"), - Library::Gst => include_str!("../gstreamer/docs.md"), - Library::GstController => include_str!("../gstreamer-controller/docs.md"), - } -} - -fn vendor_docs(_lib: Library) -> Option<&'static str> { - None -} - -/// Embeds the docs. -/// -/// `path` is the root directory to process. -/// -/// `ignores` is the list of files to skip (relative to `path`). -pub fn embed>(library: Library, path: P, ignores: &[&str]) { - let docs = docs(library); - do_embed(docs, path.as_ref(), ignores); - - if let Some(docs) = vendor_docs(library) { - do_embed(docs, path.as_ref(), ignores); - } -} - -fn do_embed(docs: &str, path: &Path, ignores: &[&str]) { - let mut infos = parse_cmts(docs.lines(), true); - loop_over_files( - path, - &mut |w, s| regenerate_comments(w, s, &mut infos, true, true), - &ignores, - false, - ); -} - -/// Remove any doc comments. -/// -/// `path` is the root directory to process. -/// -/// `ignores` is the list of files to skip (relative to `path`). -pub fn purge>(path: P, ignores: &[&str]) { - loop_over_files( - path.as_ref(), - &mut |w, s| strip_comments(w, s, &mut io::sink(), true), - &ignores, - false, - ); -} diff --git a/gstreamer-app/Cargo.toml b/gstreamer-app/Cargo.toml index 77d6efeae..ab2e15e69 100644 --- a/gstreamer-app/Cargo.toml +++ b/gstreamer-app/Cargo.toml @@ -24,9 +24,6 @@ gst = { package = "gstreamer", path = "../gstreamer" } gst-base = { package = "gstreamer-base", path = "../gstreamer-base" } once_cell = "1.0" -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [dev-dependencies] futures-util = { version = "0.3", features = ["sink"] } futures-executor = "0.3" @@ -39,9 +36,7 @@ v1_14 = ["gst/v1_14", "gst-base/v1_14", "ffi/v1_14", "v1_12"] v1_16 = ["gst/v1_16", "gst-base/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "gst-base/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "gst-base/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox", "gst-base/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-audio/Cargo.toml b/gstreamer-audio/Cargo.toml index 097ad4ce6..6d09dbf14 100644 --- a/gstreamer-audio/Cargo.toml +++ b/gstreamer-audio/Cargo.toml @@ -24,9 +24,6 @@ gst-base = { package = "gstreamer-base", path = "../gstreamer-base" } array-init = "2.0" once_cell = "1.0" -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [dev-dependencies] itertools = "0.10" @@ -38,9 +35,7 @@ v1_14 = ["gst/v1_14", "gst-base/v1_14", "ffi/v1_14", "v1_12"] v1_16 = ["gst/v1_16", "gst-base/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "gst-base/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "gst-base/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox", "gst-base/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-base/Cargo.toml b/gstreamer-base/Cargo.toml index c07ff3e21..ea28d408d 100644 --- a/gstreamer-base/Cargo.toml +++ b/gstreamer-base/Cargo.toml @@ -21,9 +21,6 @@ ffi = { package = "gstreamer-base-sys", path = "sys", features = ["v1_8"] } glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../gstreamer" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] v1_10 = ["gst/v1_10", "ffi/v1_10"] @@ -34,9 +31,7 @@ v1_14_1 = ["gst/v1_14", "ffi/v1_14_1", "v1_14"] v1_16 = ["gst/v1_16", "ffi/v1_16", "v1_14_1"] v1_18 = ["gst/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-check/Cargo.toml b/gstreamer-check/Cargo.toml index 143e2d9ad..2d16b482b 100644 --- a/gstreamer-check/Cargo.toml +++ b/gstreamer-check/Cargo.toml @@ -19,9 +19,6 @@ ffi = { package = "gstreamer-check-sys", path = "sys", features = ["v1_8"] } glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../gstreamer" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] v1_10 = ["gst/v1_10", "ffi/v1_10"] @@ -30,9 +27,7 @@ v1_14 = ["gst/v1_14", "ffi/v1_14", "v1_12"] v1_16 = ["gst/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-controller/Cargo.toml b/gstreamer-controller/Cargo.toml index 51eee40a0..16c7a7817 100644 --- a/gstreamer-controller/Cargo.toml +++ b/gstreamer-controller/Cargo.toml @@ -20,9 +20,6 @@ ffi = { package = "gstreamer-controller-sys", path = "sys", features = ["v1_8"] glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../gstreamer" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] v1_10 = ["gst/v1_10", "ffi/v1_10"] @@ -31,9 +28,7 @@ v1_14 = ["gst/v1_14", "ffi/v1_14", "v1_12"] v1_16 = ["gst/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-editing-services/Cargo.toml b/gstreamer-editing-services/Cargo.toml index 6356f0b37..0436e3142 100644 --- a/gstreamer-editing-services/Cargo.toml +++ b/gstreamer-editing-services/Cargo.toml @@ -23,9 +23,6 @@ gst = { package = "gstreamer", path = "../gstreamer" } gst-base = { package = "gstreamer-base", path = "../gstreamer-base" } gst-pbutils = { package = "gstreamer-pbutils", path = "../gstreamer-pbutils" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] v1_10 = ["gst/v1_10", "gst-base/v1_10", "gst-pbutils/v1_10", "ffi/v1_10"] v1_12 = ["gst/v1_12", "gst-base/v1_12", "gst-pbutils/v1_12", "ffi/v1_12", "v1_10"] @@ -33,9 +30,7 @@ v1_14 = ["gst/v1_14", "gst-base/v1_14", "gst-pbutils/v1_14", "ffi/v1_14", "v1_12 v1_16 = ["gst/v1_16", "gst-base/v1_16", "gst-pbutils/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "gst-base/v1_18", "gst-pbutils/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "gst-base/v1_20", "gst-pbutils/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gio/dox", "gst/dox", "gst-base/dox", "gst-pbutils/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-gl/Cargo.toml b/gstreamer-gl/Cargo.toml index e18650e9c..a26ac0647 100644 --- a/gstreamer-gl/Cargo.toml +++ b/gstreamer-gl/Cargo.toml @@ -27,17 +27,12 @@ gst = { package = "gstreamer", path = "../gstreamer", features = ["v1_14"] } gst-base = { package = "gstreamer-base", path = "../gstreamer-base", features = ["v1_14"] } gst-video = { package = "gstreamer-video", path = "../gstreamer-video", features = ["v1_14"] } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox", "gst-base/dox", "gst-video/dox"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] v1_16 = ["gst/v1_16", "gst-base/v1_16", "gst-video/v1_16", "ffi/v1_16"] v1_18 = ["gst/v1_18", "gst-base/v1_18", "gst-video/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "gst-base/v1_20", "gst-video/v1_20", "ffi/v1_20", "v1_18"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-gl/egl/Cargo.toml b/gstreamer-gl/egl/Cargo.toml index 49d4653b0..0fdba7ac4 100644 --- a/gstreamer-gl/egl/Cargo.toml +++ b/gstreamer-gl/egl/Cargo.toml @@ -24,16 +24,11 @@ glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../../gstreamer", features = ["v1_14"] } gst-gl = { package = "gstreamer-gl", path = "../" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../../docs", optional = true } - [features] default = [] dox = ["v1_18", "ffi/dox", "glib/dox", "gst/dox", "gst-gl/dox"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] v1_16 = ["gst/v1_16", "gst-gl/v1_16", "ffi/v1_16"] v1_18 = ["gst/v1_18", "gst-gl/v1_18", "ffi/v1_18", "v1_16"] [package.metadata.docs.rs] -features = ["embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-gl/wayland/Cargo.toml b/gstreamer-gl/wayland/Cargo.toml index 288b2ad0e..ea2382338 100644 --- a/gstreamer-gl/wayland/Cargo.toml +++ b/gstreamer-gl/wayland/Cargo.toml @@ -24,16 +24,11 @@ glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../../gstreamer", features = ["v1_14"] } gst-gl = { package = "gstreamer-gl", path = "../" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../../docs", optional = true } - [features] default = [] dox = ["v1_18", "ffi/dox", "glib/dox", "gst/dox", "gst-gl/dox"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] v1_16 = ["gst/v1_16", "gst-gl/v1_16", "ffi/v1_16"] v1_18 = ["gst/v1_18", "gst-gl/v1_18", "ffi/v1_18", "v1_16"] [package.metadata.docs.rs] -features = ["embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-gl/x11/Cargo.toml b/gstreamer-gl/x11/Cargo.toml index ca6343d0f..6c7f7bb0d 100644 --- a/gstreamer-gl/x11/Cargo.toml +++ b/gstreamer-gl/x11/Cargo.toml @@ -24,16 +24,11 @@ glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../../gstreamer", features = ["v1_14"] } gst-gl = { package = "gstreamer-gl", path = "../" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../../docs", optional = true } - [features] default = [] dox = ["v1_18", "ffi/dox", "glib/dox", "gst/dox", "gst-gl/dox"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] v1_16 = ["gst/v1_16", "gst-gl/v1_16", "ffi/v1_16"] v1_18 = ["gst/v1_18", "gst-gl/v1_18", "ffi/v1_18", "v1_16"] [package.metadata.docs.rs] -features = ["embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-net/Cargo.toml b/gstreamer-net/Cargo.toml index 348ee21ca..5422e91be 100644 --- a/gstreamer-net/Cargo.toml +++ b/gstreamer-net/Cargo.toml @@ -19,9 +19,6 @@ glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../gstreamer" } gio = { git = "https://github.com/gtk-rs/gtk-rs" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] v1_10 = ["gst/v1_10", "ffi/v1_10"] @@ -30,9 +27,7 @@ v1_14 = ["gst/v1_14", "ffi/v1_14", "v1_12"] v1_16 = ["gst/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gio/dox", "gst/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-pbutils/Cargo.toml b/gstreamer-pbutils/Cargo.toml index e2b04069d..7c2d7baeb 100644 --- a/gstreamer-pbutils/Cargo.toml +++ b/gstreamer-pbutils/Cargo.toml @@ -21,9 +21,6 @@ glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../gstreamer" } thiserror = "1.0" -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] v1_10 = ["gst/v1_10", "ffi/v1_10"] @@ -32,9 +29,7 @@ v1_14 = ["gst/v1_14", "ffi/v1_14", "v1_12"] v1_16 = ["gst/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-player/Cargo.toml b/gstreamer-player/Cargo.toml index 302df4b02..f2cc4c1cc 100644 --- a/gstreamer-player/Cargo.toml +++ b/gstreamer-player/Cargo.toml @@ -22,18 +22,13 @@ gst = { package = "gstreamer", path = "../gstreamer", features = ["v1_12"] } gst-video = { package = "gstreamer-video", path = "../gstreamer-video", features = ["v1_12"] } once_cell = "1.0" -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] v1_14 = ["gst/v1_14", "gst-video/v1_14", "ffi/v1_14"] v1_16 = ["gst/v1_16", "gst-video/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "gst-video/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "gst-video/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox", "gst-video/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-rtp/Cargo.toml b/gstreamer-rtp/Cargo.toml index 789a9024a..fa7878218 100644 --- a/gstreamer-rtp/Cargo.toml +++ b/gstreamer-rtp/Cargo.toml @@ -20,9 +20,6 @@ ffi = { package = "gstreamer-rtp-sys", path = "sys", features = ["v1_8"] } glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../gstreamer" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] v1_10 = ["gst/v1_10", "ffi/v1_10"] @@ -31,9 +28,7 @@ v1_14 = ["gst/v1_14", "ffi/v1_14", "v1_12"] v1_16 = ["gst/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-rtsp-server/Cargo.toml b/gstreamer-rtsp-server/Cargo.toml index f66bef640..79e81637d 100644 --- a/gstreamer-rtsp-server/Cargo.toml +++ b/gstreamer-rtsp-server/Cargo.toml @@ -25,9 +25,6 @@ gst-sdp = { package = "gstreamer-sdp", path = "../gstreamer-sdp" } gst-rtsp = { package = "gstreamer-rtsp", path = "../gstreamer-rtsp" } gst-net = { package = "gstreamer-net", path = "../gstreamer-net" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] v1_10 = ["gst/v1_10", "gst-sdp/v1_10", "gst-rtsp/v1_10", "gst-net/v1_10", "ffi/v1_10"] @@ -36,9 +33,7 @@ v1_14 = ["gst/v1_14", "gst-sdp/v1_14", "gst-rtsp/v1_14", "gst-net/v1_14", "ffi/v v1_16 = ["gst/v1_16", "gst-sdp/v1_16", "gst-rtsp/v1_16", "gst-net/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "gst-sdp/v1_18", "gst-rtsp/v1_18", "gst-net/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "gst-sdp/v1_20", "gst-rtsp/v1_20", "gst-net/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gio/dox", "gst/dox", "gst-sdp/dox", "gst-rtsp/dox", "gst-net/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-rtsp/Cargo.toml b/gstreamer-rtsp/Cargo.toml index 764701505..97cfa3b86 100644 --- a/gstreamer-rtsp/Cargo.toml +++ b/gstreamer-rtsp/Cargo.toml @@ -21,9 +21,6 @@ glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../gstreamer" } gst-sdp = { package = "gstreamer-sdp", path = "../gstreamer-sdp" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] v1_10 = ["gst/v1_10", "gst-sdp/v1_10", "ffi/v1_10"] @@ -32,9 +29,7 @@ v1_14 = ["gst/v1_14", "gst-sdp/v1_14", "ffi/v1_14", "v1_12"] v1_16 = ["gst/v1_16", "gst-sdp/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "gst-sdp/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "gst-sdp/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox", "gst-sdp/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-sdp/Cargo.toml b/gstreamer-sdp/Cargo.toml index 4bfc2cdef..ab10e484c 100644 --- a/gstreamer-sdp/Cargo.toml +++ b/gstreamer-sdp/Cargo.toml @@ -18,9 +18,6 @@ ffi = { package = "gstreamer-sdp-sys", path = "sys", features = ["v1_8"] } glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../gstreamer" } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] v1_8_1 = ["ffi/v1_8_1"] @@ -30,9 +27,7 @@ v1_14 = ["gst/v1_14", "ffi/v1_14", "v1_12"] v1_16 = ["gst/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-video/Cargo.toml b/gstreamer-video/Cargo.toml index f517a5fd2..239ec438e 100644 --- a/gstreamer-video/Cargo.toml +++ b/gstreamer-video/Cargo.toml @@ -24,9 +24,6 @@ gst-base = { package = "gstreamer-base", path = "../gstreamer-base" } once_cell = "1.0" futures-channel = "0.3" -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [dev-dependencies] itertools = "0.10" @@ -38,9 +35,7 @@ v1_14 = ["gst/v1_14", "gst-base/v1_14", "ffi/v1_14", "v1_12"] v1_16 = ["gst/v1_16", "gst-base/v1_16", "ffi/v1_16", "v1_14"] v1_18 = ["gst/v1_18", "gst-base/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "gst-base/v1_20", "ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox", "gst-base/dox"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer-webrtc/Cargo.toml b/gstreamer-webrtc/Cargo.toml index da3786d8f..f16daa516 100644 --- a/gstreamer-webrtc/Cargo.toml +++ b/gstreamer-webrtc/Cargo.toml @@ -20,13 +20,8 @@ glib = { git = "https://github.com/gtk-rs/gtk-rs" } gst = { package = "gstreamer", path = "../gstreamer", features = ["v1_14"] } gst-sdp = { package = "gstreamer-sdp", path = "../gstreamer-sdp", features = ["v1_14"] } -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [features] default = [] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "gst/dox", "gst-sdp/dox"] v1_14_1 = ["ffi/v1_14_1"] v1_16 = ["gst/v1_16", "gst-sdp/v1_16", "ffi/v1_16", "v1_14_1"] @@ -34,4 +29,4 @@ v1_18 = ["gst/v1_18", "gst-sdp/v1_18", "ffi/v1_18", "v1_16"] v1_20 = ["gst/v1_20", "gst-sdp/v1_20", "ffi/v1_20", "v1_18"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"] diff --git a/gstreamer/Cargo.toml b/gstreamer/Cargo.toml index 6847f894e..bfeec3d84 100644 --- a/gstreamer/Cargo.toml +++ b/gstreamer/Cargo.toml @@ -32,9 +32,6 @@ paste = "1.0" pretty-hex = "0.2" thiserror = "1" -[build-dependencies] -gstreamer-rs-lgpl-docs = { path = "../docs", optional = true } - [dev-dependencies] ron = "0.6" serde_json = "1.0" @@ -49,10 +46,8 @@ v1_14 = ["ffi/v1_14", "v1_12_1"] v1_16 = ["ffi/v1_16", "v1_14"] v1_18 = ["ffi/v1_18", "v1_16"] v1_20 = ["ffi/v1_20", "v1_18"] -embed-lgpl-docs = ["gstreamer-rs-lgpl-docs"] -purge-lgpl-docs = ["gstreamer-rs-lgpl-docs"] dox = ["v1_20", "ffi/dox", "glib/dox", "ser_de"] ser_de = ["num-rational/serde", "serde", "serde_bytes", "serde/derive"] [package.metadata.docs.rs] -features = ["dox", "embed-lgpl-docs"] +features = ["dox"]