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 {}