From e62558dde4ac5084f87f78e334c8bc9779c5b9d9 Mon Sep 17 00:00:00 2001 From: Marijn Suijten Date: Sun, 18 Apr 2021 21:33:54 +0200 Subject: [PATCH] Remove `docs/` crate and references to it The `lgpl-docs` crate and all precompiled (easy to get outdated!) docmentation files are removed in favour of being generated at runtime by the improved generator, both during local development as well as in the CI. --- Cargo.toml | 1 - deny.toml | 4 - docs/Cargo.toml | 15 - docs/gstreamer-app/docs.md | 792 -- docs/gstreamer-audio/docs.md | 1539 -- docs/gstreamer-base/docs.md | 2585 ---- docs/gstreamer-check/docs.md | 1356 -- docs/gstreamer-controller/docs.md | 339 - docs/gstreamer-editing-services/docs.md | 5177 ------- docs/gstreamer-gl/docs.md | 2203 --- docs/gstreamer-gl/egl/docs.md | 37 - docs/gstreamer-gl/wayland/docs.md | 25 - docs/gstreamer-gl/x11/docs.md | 25 - docs/gstreamer-net/docs.md | 140 - docs/gstreamer-pbutils/docs.md | 949 -- docs/gstreamer-player/docs.md | 742 - docs/gstreamer-rtp/docs.md | 199 - docs/gstreamer-rtsp-server/docs.md | 3356 ----- docs/gstreamer-rtsp/docs.md | 258 - docs/gstreamer-sdp/docs.md | 1 - docs/gstreamer-video/docs.md | 2856 ---- docs/gstreamer-webrtc/docs.md | 332 - docs/gstreamer/docs.md | 16449 ---------------------- docs/src/lib.rs | 88 - gstreamer-app/Cargo.toml | 7 +- gstreamer-audio/Cargo.toml | 7 +- gstreamer-base/Cargo.toml | 7 +- gstreamer-check/Cargo.toml | 7 +- gstreamer-controller/Cargo.toml | 7 +- gstreamer-editing-services/Cargo.toml | 7 +- gstreamer-gl/Cargo.toml | 7 +- gstreamer-gl/egl/Cargo.toml | 7 +- gstreamer-gl/wayland/Cargo.toml | 7 +- gstreamer-gl/x11/Cargo.toml | 7 +- gstreamer-net/Cargo.toml | 7 +- gstreamer-pbutils/Cargo.toml | 7 +- gstreamer-player/Cargo.toml | 7 +- gstreamer-rtp/Cargo.toml | 7 +- gstreamer-rtsp-server/Cargo.toml | 7 +- gstreamer-rtsp/Cargo.toml | 7 +- gstreamer-sdp/Cargo.toml | 7 +- gstreamer-video/Cargo.toml | 7 +- gstreamer-webrtc/Cargo.toml | 7 +- gstreamer/Cargo.toml | 7 +- 44 files changed, 20 insertions(+), 39588 deletions(-) delete mode 100644 docs/Cargo.toml delete mode 100644 docs/gstreamer-app/docs.md delete mode 100644 docs/gstreamer-audio/docs.md delete mode 100644 docs/gstreamer-base/docs.md delete mode 100644 docs/gstreamer-check/docs.md delete mode 100644 docs/gstreamer-controller/docs.md delete mode 100644 docs/gstreamer-editing-services/docs.md delete mode 100644 docs/gstreamer-gl/docs.md delete mode 100644 docs/gstreamer-gl/egl/docs.md delete mode 100644 docs/gstreamer-gl/wayland/docs.md delete mode 100644 docs/gstreamer-gl/x11/docs.md delete mode 100644 docs/gstreamer-net/docs.md delete mode 100644 docs/gstreamer-pbutils/docs.md delete mode 100644 docs/gstreamer-player/docs.md delete mode 100644 docs/gstreamer-rtp/docs.md delete mode 100644 docs/gstreamer-rtsp-server/docs.md delete mode 100644 docs/gstreamer-rtsp/docs.md delete mode 100644 docs/gstreamer-sdp/docs.md delete mode 100644 docs/gstreamer-video/docs.md delete mode 100644 docs/gstreamer-webrtc/docs.md delete mode 100644 docs/gstreamer/docs.md delete mode 100644 docs/src/lib.rs 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"]