gstreamer/auto/
pipeline.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// from gst-gir-files (https://gitlab.freedesktop.org/gstreamer/gir-files-rs.git)
4// DO NOT EDIT
5
6use crate::{ffi, Bin, ChildProxy, Clock, ClockTime, Element, Object};
7use glib::{
8    prelude::*,
9    signal::{connect_raw, SignalHandlerId},
10    translate::*,
11};
12use std::boxed::Box as Box_;
13
14glib::wrapper! {
15    /// A [`Pipeline`][crate::Pipeline] is a special [`Bin`][crate::Bin] used as the toplevel container for
16    /// the filter graph. The [`Pipeline`][crate::Pipeline] will manage the selection and
17    /// distribution of a global [`Clock`][crate::Clock] as well as provide a [`Bus`][crate::Bus] to the
18    /// application.
19    ///
20    /// [`new()`][Self::new()] is used to create a pipeline. when you are done with
21    /// the pipeline, use `gst_object_unref()` to free its resources including all
22    /// added [`Element`][crate::Element] objects (if not otherwise referenced).
23    ///
24    /// Elements are added and removed from the pipeline using the [`Bin`][crate::Bin]
25    /// methods like [`GstBinExt::add()`][crate::prelude::GstBinExt::add()] and [`GstBinExt::remove()`][crate::prelude::GstBinExt::remove()] (see [`Bin`][crate::Bin]).
26    ///
27    /// Before changing the state of the [`Pipeline`][crate::Pipeline] (see [`Element`][crate::Element]) a [`Bus`][crate::Bus]
28    /// should be retrieved with `gst_pipeline_get_bus()`. This [`Bus`][crate::Bus] should then
29    /// be used to receive [`Message`][crate::Message] from the elements in the pipeline. Listening
30    /// to the [`Bus`][crate::Bus] is necessary for retrieving error messages from the
31    /// [`Pipeline`][crate::Pipeline] and otherwise the [`Pipeline`][crate::Pipeline] might stop without any
32    /// indication, why. Furthermore, the [`Pipeline`][crate::Pipeline] posts messages even if
33    /// nobody listens on the [`Bus`][crate::Bus], which will pile up and use up memory.
34    ///
35    /// By default, a [`Pipeline`][crate::Pipeline] will automatically flush the pending [`Bus`][crate::Bus]
36    /// messages when going to the NULL state to ensure that no circular
37    /// references exist when no messages are read from the [`Bus`][crate::Bus]. This
38    /// behaviour can be changed with [`PipelineExt::set_auto_flush_bus()`][crate::prelude::PipelineExt::set_auto_flush_bus()].
39    ///
40    /// When the [`Pipeline`][crate::Pipeline] performs the PAUSED to PLAYING state change it will
41    /// select a clock for the elements. The clock selection algorithm will by
42    /// default select a clock provided by an element that is most upstream
43    /// (closest to the source). For live pipelines (ones that return
44    /// [`StateChangeReturn::NoPreroll`][crate::StateChangeReturn::NoPreroll] from the [`ElementExt::set_state()`][crate::prelude::ElementExt::set_state()] call) this
45    /// will select the clock provided by the live source. For normal pipelines
46    /// this will select a clock provided by the sinks (most likely the audio
47    /// sink). If no element provides a clock, a default [`SystemClock`][crate::SystemClock] is used.
48    ///
49    /// The clock selection can be controlled with the [`PipelineExt::use_clock()`][crate::prelude::PipelineExt::use_clock()]
50    /// method, which will enforce a given clock on the pipeline. With
51    /// [`PipelineExt::auto_clock()`][crate::prelude::PipelineExt::auto_clock()] the default clock selection algorithm can be
52    /// restored.
53    ///
54    /// A [`Pipeline`][crate::Pipeline] maintains a running time for the elements. The running
55    /// time is defined as the difference between the current clock time and
56    /// the base time. When the pipeline goes to READY or a flushing seek is
57    /// performed on it, the running time is reset to 0. When the pipeline is
58    /// set from PLAYING to PAUSED, the current clock time is sampled and used to
59    /// configure the base time for the elements when the pipeline is set
60    /// to PLAYING again. The effect is that the running time (as the difference
61    /// between the clock time and the base time) will count how much time was spent
62    /// in the PLAYING state. This default behaviour can be changed with the
63    /// [`ElementExt::set_start_time()`][crate::prelude::ElementExt::set_start_time()] method.
64    ///
65    /// ## Properties
66    ///
67    ///
68    /// #### `auto-flush-bus`
69    ///  Whether or not to automatically flush all messages on the
70    /// pipeline's bus when going from READY to NULL state. Please see
71    /// [`PipelineExt::set_auto_flush_bus()`][crate::prelude::PipelineExt::set_auto_flush_bus()] for more information on this option.
72    ///
73    /// Readable | Writeable
74    ///
75    ///
76    /// #### `delay`
77    ///  The expected delay needed for elements to spin up to the
78    /// PLAYING state expressed in nanoseconds.
79    /// see [`PipelineExt::set_delay()`][crate::prelude::PipelineExt::set_delay()] for more information on this option.
80    ///
81    /// Readable | Writeable
82    ///
83    ///
84    /// #### `latency`
85    ///  Latency to configure on the pipeline. See [`PipelineExt::set_latency()`][crate::prelude::PipelineExt::set_latency()].
86    ///
87    /// Readable | Writeable
88    /// <details><summary><h4>Bin</h4></summary>
89    ///
90    ///
91    /// #### `async-handling`
92    ///  If set to [`true`], the bin will handle asynchronous state changes.
93    /// This should be used only if the bin subclass is modifying the state
94    /// of its children on its own.
95    ///
96    /// Readable | Writeable
97    ///
98    ///
99    /// #### `message-forward`
100    ///  Forward all children messages, even those that would normally be filtered by
101    /// the bin. This can be interesting when one wants to be notified of the EOS
102    /// state of individual elements, for example.
103    ///
104    /// The messages are converted to an ELEMENT message with the bin as the
105    /// source. The structure of the message is named `GstBinForwarded` and contains
106    /// a field named `message` that contains the original forwarded [`Message`][crate::Message].
107    ///
108    /// Readable | Writeable
109    /// </details>
110    /// <details><summary><h4>Object</h4></summary>
111    ///
112    ///
113    /// #### `name`
114    ///  Readable | Writeable | Construct
115    ///
116    ///
117    /// #### `parent`
118    ///  The parent of the object. Please note, that when changing the 'parent'
119    /// property, we don't emit [`notify`][struct@crate::glib::Object#notify] and [`deep-notify`][struct@crate::Object#deep-notify]
120    /// signals due to locking issues. In some cases one can use
121    /// [`element-added`][struct@crate::Bin#element-added] or [`element-removed`][struct@crate::Bin#element-removed] signals on the parent to
122    /// achieve a similar effect.
123    ///
124    /// Readable | Writeable
125    /// </details>
126    ///
127    /// # Implements
128    ///
129    /// [`PipelineExt`][trait@crate::prelude::PipelineExt], [`GstBinExt`][trait@crate::prelude::GstBinExt], [`ElementExt`][trait@crate::prelude::ElementExt], [`GstObjectExt`][trait@crate::prelude::GstObjectExt], [`trait@glib::ObjectExt`], [`ChildProxyExt`][trait@crate::prelude::ChildProxyExt], [`ElementExtManual`][trait@crate::prelude::ElementExtManual], [`ChildProxyExtManual`][trait@crate::prelude::ChildProxyExtManual]
130    #[doc(alias = "GstPipeline")]
131    pub struct Pipeline(Object<ffi::GstPipeline, ffi::GstPipelineClass>) @extends Bin, Element, Object, @implements ChildProxy;
132
133    match fn {
134        type_ => || ffi::gst_pipeline_get_type(),
135    }
136}
137
138impl Pipeline {
139    pub const NONE: Option<&'static Pipeline> = None;
140}
141
142unsafe impl Send for Pipeline {}
143unsafe impl Sync for Pipeline {}
144
145mod sealed {
146    pub trait Sealed {}
147    impl<T: super::IsA<super::Pipeline>> Sealed for T {}
148}
149
150/// Trait containing all [`struct@Pipeline`] methods.
151///
152/// # Implementors
153///
154/// [`Pipeline`][struct@crate::Pipeline]
155pub trait PipelineExt: IsA<Pipeline> + sealed::Sealed + 'static {
156    /// Let `self` select a clock automatically. This is the default
157    /// behaviour.
158    ///
159    /// Use this function if you previous forced a fixed clock with
160    /// [`use_clock()`][Self::use_clock()] and want to restore the default
161    /// pipeline clock selection algorithm.
162    ///
163    /// MT safe.
164    #[doc(alias = "gst_pipeline_auto_clock")]
165    fn auto_clock(&self) {
166        unsafe {
167            ffi::gst_pipeline_auto_clock(self.as_ref().to_glib_none().0);
168        }
169    }
170
171    /// Check if `self` will automatically flush messages when going to
172    /// the NULL state.
173    ///
174    /// # Returns
175    ///
176    /// whether the pipeline will automatically flush its bus when
177    /// going from READY to NULL state or not.
178    ///
179    /// MT safe.
180    #[doc(alias = "gst_pipeline_get_auto_flush_bus")]
181    #[doc(alias = "get_auto_flush_bus")]
182    #[doc(alias = "auto-flush-bus")]
183    fn is_auto_flush_bus(&self) -> bool {
184        unsafe {
185            from_glib(ffi::gst_pipeline_get_auto_flush_bus(
186                self.as_ref().to_glib_none().0,
187            ))
188        }
189    }
190
191    /// Return the configured latency on `self`.
192    ///
193    /// # Returns
194    ///
195    /// `self` configured latency, or `GST_CLOCK_TIME_NONE` if none has been configured
196    /// because `self` did not reach the PLAYING state yet.
197    ///
198    /// MT safe.
199    #[cfg(feature = "v1_24")]
200    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
201    #[doc(alias = "gst_pipeline_get_configured_latency")]
202    #[doc(alias = "get_configured_latency")]
203    fn configured_latency(&self) -> Option<ClockTime> {
204        unsafe {
205            from_glib(ffi::gst_pipeline_get_configured_latency(
206                self.as_ref().to_glib_none().0,
207            ))
208        }
209    }
210
211    /// Get the configured delay (see [`set_delay()`][Self::set_delay()]).
212    ///
213    /// # Returns
214    ///
215    /// The configured delay.
216    ///
217    /// MT safe.
218    #[doc(alias = "gst_pipeline_get_delay")]
219    #[doc(alias = "get_delay")]
220    fn delay(&self) -> ClockTime {
221        unsafe {
222            try_from_glib(ffi::gst_pipeline_get_delay(self.as_ref().to_glib_none().0))
223                .expect("mandatory glib value is None")
224        }
225    }
226
227    /// Gets the latency that should be configured on the pipeline. See
228    /// [`set_latency()`][Self::set_latency()].
229    ///
230    /// # Returns
231    ///
232    /// Latency to configure on the pipeline or GST_CLOCK_TIME_NONE
233    #[doc(alias = "gst_pipeline_get_latency")]
234    #[doc(alias = "get_latency")]
235    fn latency(&self) -> Option<ClockTime> {
236        unsafe {
237            from_glib(ffi::gst_pipeline_get_latency(
238                self.as_ref().to_glib_none().0,
239            ))
240        }
241    }
242
243    /// Gets the current clock used by `self`.
244    ///
245    /// Unlike [`ElementExt::clock()`][crate::prelude::ElementExt::clock()], this function will always return a
246    /// clock, even if the pipeline is not in the PLAYING state.
247    ///
248    /// # Returns
249    ///
250    /// a [`Clock`][crate::Clock], unref after usage.
251    #[doc(alias = "gst_pipeline_get_pipeline_clock")]
252    #[doc(alias = "get_pipeline_clock")]
253    fn pipeline_clock(&self) -> Clock {
254        unsafe {
255            from_glib_full(ffi::gst_pipeline_get_pipeline_clock(
256                self.as_ref().to_glib_none().0,
257            ))
258        }
259    }
260
261    /// Check if `self` is live.
262    ///
263    /// # Returns
264    ///
265    /// [`true`] if `self` is live, [`false`] if not or if it did not reach the PAUSED state yet.
266    ///
267    /// MT safe.
268    #[cfg(feature = "v1_24")]
269    #[cfg_attr(docsrs, doc(cfg(feature = "v1_24")))]
270    #[doc(alias = "gst_pipeline_is_live")]
271    fn is_live(&self) -> bool {
272        unsafe { from_glib(ffi::gst_pipeline_is_live(self.as_ref().to_glib_none().0)) }
273    }
274
275    /// Usually, when a pipeline goes from READY to NULL state, it automatically
276    /// flushes all pending messages on the bus, which is done for refcounting
277    /// purposes, to break circular references.
278    ///
279    /// This means that applications that update state using (async) bus messages
280    /// (e.g. do certain things when a pipeline goes from PAUSED to READY) might
281    /// not get to see messages when the pipeline is shut down, because they might
282    /// be flushed before they can be dispatched in the main thread. This behaviour
283    /// can be disabled using this function.
284    ///
285    /// It is important that all messages on the bus are handled when the
286    /// automatic flushing is disabled else memory leaks will be introduced.
287    ///
288    /// MT safe.
289    /// ## `auto_flush`
290    /// whether or not to automatically flush the bus when
291    /// the pipeline goes from READY to NULL state
292    #[doc(alias = "gst_pipeline_set_auto_flush_bus")]
293    #[doc(alias = "auto-flush-bus")]
294    fn set_auto_flush_bus(&self, auto_flush: bool) {
295        unsafe {
296            ffi::gst_pipeline_set_auto_flush_bus(
297                self.as_ref().to_glib_none().0,
298                auto_flush.into_glib(),
299            );
300        }
301    }
302
303    /// Set the expected delay needed for all elements to perform the
304    /// PAUSED to PLAYING state change. `delay` will be added to the
305    /// base time of the elements so that they wait an additional `delay`
306    /// amount of time before starting to process buffers and cannot be
307    /// `GST_CLOCK_TIME_NONE`.
308    ///
309    /// This option is used for tuning purposes and should normally not be
310    /// used.
311    ///
312    /// MT safe.
313    /// ## `delay`
314    /// the delay
315    #[doc(alias = "gst_pipeline_set_delay")]
316    #[doc(alias = "delay")]
317    fn set_delay(&self, delay: ClockTime) {
318        unsafe {
319            ffi::gst_pipeline_set_delay(self.as_ref().to_glib_none().0, delay.into_glib());
320        }
321    }
322
323    /// Sets the latency that should be configured on the pipeline. Setting
324    /// GST_CLOCK_TIME_NONE will restore the default behaviour of using the minimum
325    /// latency from the LATENCY query. Setting this is usually not required and
326    /// the pipeline will figure out an appropriate latency automatically.
327    ///
328    /// Setting a too low latency, especially lower than the minimum latency from
329    /// the LATENCY query, will most likely cause the pipeline to fail.
330    /// ## `latency`
331    /// latency to configure
332    #[doc(alias = "gst_pipeline_set_latency")]
333    #[doc(alias = "latency")]
334    fn set_latency(&self, latency: impl Into<Option<ClockTime>>) {
335        unsafe {
336            ffi::gst_pipeline_set_latency(
337                self.as_ref().to_glib_none().0,
338                latency.into().into_glib(),
339            );
340        }
341    }
342
343    /// Force `self` to use the given `clock`. The pipeline will
344    /// always use the given clock even if new clock providers are added
345    /// to this pipeline.
346    ///
347    /// If `clock` is [`None`] all clocking will be disabled which will make
348    /// the pipeline run as fast as possible.
349    ///
350    /// MT safe.
351    /// ## `clock`
352    /// the clock to use
353    #[doc(alias = "gst_pipeline_use_clock")]
354    fn use_clock(&self, clock: Option<&impl IsA<Clock>>) {
355        unsafe {
356            ffi::gst_pipeline_use_clock(
357                self.as_ref().to_glib_none().0,
358                clock.map(|p| p.as_ref()).to_glib_none().0,
359            );
360        }
361    }
362
363    #[doc(alias = "auto-flush-bus")]
364    fn connect_auto_flush_bus_notify<F: Fn(&Self) + Send + Sync + 'static>(
365        &self,
366        f: F,
367    ) -> SignalHandlerId {
368        unsafe extern "C" fn notify_auto_flush_bus_trampoline<
369            P: IsA<Pipeline>,
370            F: Fn(&P) + Send + Sync + 'static,
371        >(
372            this: *mut ffi::GstPipeline,
373            _param_spec: glib::ffi::gpointer,
374            f: glib::ffi::gpointer,
375        ) {
376            let f: &F = &*(f as *const F);
377            f(Pipeline::from_glib_borrow(this).unsafe_cast_ref())
378        }
379        unsafe {
380            let f: Box_<F> = Box_::new(f);
381            connect_raw(
382                self.as_ptr() as *mut _,
383                b"notify::auto-flush-bus\0".as_ptr() as *const _,
384                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
385                    notify_auto_flush_bus_trampoline::<Self, F> as *const (),
386                )),
387                Box_::into_raw(f),
388            )
389        }
390    }
391
392    #[doc(alias = "delay")]
393    fn connect_delay_notify<F: Fn(&Self) + Send + Sync + 'static>(&self, f: F) -> SignalHandlerId {
394        unsafe extern "C" fn notify_delay_trampoline<
395            P: IsA<Pipeline>,
396            F: Fn(&P) + Send + Sync + 'static,
397        >(
398            this: *mut ffi::GstPipeline,
399            _param_spec: glib::ffi::gpointer,
400            f: glib::ffi::gpointer,
401        ) {
402            let f: &F = &*(f as *const F);
403            f(Pipeline::from_glib_borrow(this).unsafe_cast_ref())
404        }
405        unsafe {
406            let f: Box_<F> = Box_::new(f);
407            connect_raw(
408                self.as_ptr() as *mut _,
409                b"notify::delay\0".as_ptr() as *const _,
410                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
411                    notify_delay_trampoline::<Self, F> as *const (),
412                )),
413                Box_::into_raw(f),
414            )
415        }
416    }
417
418    #[doc(alias = "latency")]
419    fn connect_latency_notify<F: Fn(&Self) + Send + Sync + 'static>(
420        &self,
421        f: F,
422    ) -> SignalHandlerId {
423        unsafe extern "C" fn notify_latency_trampoline<
424            P: IsA<Pipeline>,
425            F: Fn(&P) + Send + Sync + 'static,
426        >(
427            this: *mut ffi::GstPipeline,
428            _param_spec: glib::ffi::gpointer,
429            f: glib::ffi::gpointer,
430        ) {
431            let f: &F = &*(f as *const F);
432            f(Pipeline::from_glib_borrow(this).unsafe_cast_ref())
433        }
434        unsafe {
435            let f: Box_<F> = Box_::new(f);
436            connect_raw(
437                self.as_ptr() as *mut _,
438                b"notify::latency\0".as_ptr() as *const _,
439                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
440                    notify_latency_trampoline::<Self, F> as *const (),
441                )),
442                Box_::into_raw(f),
443            )
444        }
445    }
446}
447
448impl<O: IsA<Pipeline>> PipelineExt for O {}