gstreamer/
lib.rs

1// Take a look at the license at the top of the repository in the LICENSE file.
2
3#![cfg_attr(docsrs, feature(doc_cfg))]
4#![allow(clippy::missing_safety_doc)]
5#![allow(clippy::manual_range_contains)]
6#![allow(clippy::manual_c_str_literals)]
7#![doc = include_str!("../README.md")]
8
9// Re-exported for the subclass gst_plugin_define! macro
10pub use glib;
11pub use gstreamer_sys as ffi;
12pub use paste;
13
14#[doc(hidden)]
15pub static INITIALIZED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
16
17#[cold]
18#[inline(never)]
19#[track_caller]
20pub fn assert_initialized() {
21    #[allow(unused_unsafe)]
22    if unsafe { ffi::gst_is_initialized() } != glib::ffi::GTRUE {
23        panic!("GStreamer has not been initialized. Call `gst::init` first.");
24    } else {
25        crate::INITIALIZED.store(true, std::sync::atomic::Ordering::SeqCst);
26    }
27}
28
29macro_rules! assert_initialized_main_thread {
30    () => {
31        if !crate::INITIALIZED.load(std::sync::atomic::Ordering::SeqCst) {
32            $crate::assert_initialized();
33        }
34    };
35}
36
37macro_rules! skip_assert_initialized {
38    () => {};
39}
40
41#[allow(clippy::needless_borrow)]
42#[allow(clippy::let_unit_value)]
43#[allow(unused_imports)]
44mod auto;
45pub use crate::auto::*;
46
47#[macro_use]
48#[cfg(feature = "serde")]
49mod serde_macros;
50
51#[macro_use]
52pub mod log;
53#[cfg(feature = "v1_28")]
54#[cfg_attr(docsrs, doc(cfg(feature = "v1_28")))]
55pub mod log_context;
56#[cfg(feature = "log")]
57pub use crate::log::DebugCategoryLogger;
58pub use crate::log::{
59    DebugCategory, DebugLogFunction, DebugLogger, DebugMessage, LoggedObject, CAT_BUFFER,
60    CAT_BUFFER_LIST, CAT_BUS, CAT_CALL_TRACE, CAT_CAPS, CAT_CLOCK, CAT_CONTEXT, CAT_DEFAULT,
61    CAT_ELEMENT_PADS, CAT_ERROR_SYSTEM, CAT_EVENT, CAT_GST_INIT, CAT_LOCKING, CAT_MEMORY,
62    CAT_MESSAGE, CAT_META, CAT_NEGOTIATION, CAT_PADS, CAT_PARAMS, CAT_PARENTAGE, CAT_PERFORMANCE,
63    CAT_PIPELINE, CAT_PLUGIN_INFO, CAT_PLUGIN_LOADING, CAT_PROBE, CAT_PROPERTIES, CAT_QOS,
64    CAT_REFCOUNTING, CAT_REGISTRY, CAT_RUST, CAT_SCHEDULING, CAT_SIGNAL, CAT_STATES,
65};
66
67#[cfg(feature = "v1_28")]
68#[cfg_attr(docsrs, doc(cfg(feature = "v1_28")))]
69pub use crate::log_context::{LogContext, LogContextBuilder};
70
71#[cfg(target_os = "macos")]
72mod macos;
73#[cfg(target_os = "macos")]
74pub use crate::macos::*;
75
76#[macro_use]
77mod error;
78pub use crate::error::*;
79
80#[macro_use]
81pub mod miniobject;
82pub use miniobject::{MiniObject, MiniObjectRef};
83
84#[macro_use]
85mod value;
86pub use crate::value::{
87    Array, ArrayRef, Bitmask, Fraction, FractionRange, IntRange, List, ListRef,
88};
89#[cfg(feature = "serde")]
90#[macro_use]
91mod value_serde;
92
93#[macro_use]
94mod id_str;
95pub use crate::id_str::IdStr;
96
97#[cfg(feature = "serde")]
98mod flag_serde;
99
100pub mod message;
101pub use crate::message::{Message, MessageErrorDomain, MessageRef, MessageView, MessageViewMut};
102
103pub mod structure;
104pub use crate::structure::{Structure, StructureRef};
105#[cfg(feature = "serde")]
106mod structure_serde;
107
108pub mod caps;
109pub use crate::caps::{Caps, CapsFilterMapAction, CapsRef};
110mod caps_features;
111#[cfg(feature = "serde")]
112mod caps_serde;
113pub use crate::caps_features::{
114    CapsFeatures, CapsFeaturesRef, CAPS_FEATURES_MEMORY_SYSTEM_MEMORY,
115    CAPS_FEATURE_MEMORY_SYSTEM_MEMORY,
116};
117#[cfg(feature = "serde")]
118mod caps_features_serde;
119
120pub mod tags;
121pub use crate::tags::{
122    tag_exists, tag_get_description, tag_get_flag, tag_get_nick, tag_get_type, Tag, TagList,
123    TagListRef,
124};
125#[cfg(feature = "serde")]
126mod tags_serde;
127
128#[macro_use]
129pub mod meta;
130#[cfg(feature = "v1_16")]
131#[cfg_attr(docsrs, doc(cfg(feature = "v1_16")))]
132pub use crate::meta::MetaSeqnum;
133pub use crate::meta::{
134    Meta, MetaAPI, MetaAPIExt, MetaRef, MetaRefMut, ParentBufferMeta, ProtectionMeta,
135    ReferenceTimestampMeta,
136};
137pub mod buffer;
138pub use crate::buffer::{
139    Buffer, BufferMap, BufferRef, MappedBuffer, BUFFER_COPY_ALL, BUFFER_COPY_METADATA,
140};
141mod buffer_cursor;
142pub use crate::buffer_cursor::{BufferCursor, BufferRefCursor};
143pub mod memory;
144mod memory_wrapped;
145#[cfg(feature = "v1_26")]
146#[cfg_attr(docsrs, doc(cfg(feature = "v1_26")))]
147pub use crate::memory::MemoryRefTrace;
148pub use crate::memory::{MappedMemory, Memory, MemoryMap, MemoryRef};
149#[cfg(feature = "serde")]
150mod buffer_serde;
151pub mod slice;
152
153pub mod sample;
154pub use crate::sample::{Sample, SampleRef};
155#[cfg(feature = "serde")]
156mod sample_serde;
157
158pub mod bufferlist;
159pub use crate::bufferlist::{BufferList, BufferListRef};
160#[cfg(feature = "serde")]
161mod bufferlist_serde;
162
163pub mod query;
164pub use crate::query::{Query, QueryRef, QueryView, QueryViewMut};
165pub mod event;
166pub use crate::event::{Event, EventRef, EventView, EventViewMut, GroupId, Seqnum};
167pub mod context;
168pub use crate::context::{Context, ContextRef};
169mod rank;
170pub use crate::rank::Rank;
171mod static_caps;
172pub use crate::static_caps::*;
173mod static_pad_template;
174pub use crate::static_pad_template::*;
175
176pub mod promise;
177pub use promise::{Promise, PromiseError};
178
179pub mod bus;
180mod element;
181pub mod element_factory;
182
183mod bin;
184pub use bin::BinBuilder;
185
186mod pipeline;
187pub use pipeline::PipelineBuilder;
188
189mod allocation_params;
190pub use self::allocation_params::AllocationParams;
191mod allocator;
192
193mod element_factory_type;
194pub use element_factory_type::*;
195
196mod tracer;
197mod tracer_factory;
198
199// OS dependent Bus extensions (also import the other platform mod for doc)
200#[cfg(any(unix, docsrs))]
201mod bus_unix;
202#[cfg(any(windows, docsrs))]
203mod bus_windows;
204
205mod child_proxy;
206mod date_time;
207#[cfg(feature = "serde")]
208mod date_time_serde;
209mod device_monitor;
210mod device_provider;
211mod device_provider_factory;
212mod enums;
213mod ghost_pad;
214pub mod gobject;
215mod iterator;
216mod object;
217mod pad;
218pub use pad::{
219    EventForeachAction, PadBuilder, PadGetRangeSuccess, PadProbeData, PadProbeId, PadProbeInfo,
220    StreamLock,
221};
222mod control_binding;
223mod control_source;
224mod parse_context;
225mod proxy_pad;
226mod registry;
227mod tag_setter;
228pub mod task;
229pub use task::{TaskLock, TaskLockGuard};
230mod task_pool;
231pub use self::iterator::{Iterator, IteratorError, IteratorImpl, StdIterator};
232pub use crate::{
233    device_monitor::DeviceMonitorFilterId,
234    element::{
235        ElementMessageType, NotifyWatchId, ELEMENT_METADATA_AUTHOR, ELEMENT_METADATA_DESCRIPTION,
236        ELEMENT_METADATA_DOC_URI, ELEMENT_METADATA_ICON_NAME, ELEMENT_METADATA_KLASS,
237        ELEMENT_METADATA_LONGNAME,
238    },
239    enums::{
240        ClockError, ClockSuccess, FlowError, FlowReturn, FlowSuccess, MessageType, PadLinkError,
241        PadLinkReturn, PadLinkSuccess, StateChangeError, StateChangeSuccess, TagError,
242    },
243    parse_context::ParseContext,
244    task_pool::{TaskHandle, TaskPoolTaskHandle},
245};
246mod plugin_feature;
247
248mod plugin;
249pub mod stream;
250pub mod stream_collection;
251
252mod typefind;
253pub use crate::typefind::*;
254mod typefind_factory;
255
256pub mod format;
257pub use crate::format::{ClockTime, GenericFormattedValue, GenericSignedFormattedValue, Signed};
258
259mod segment;
260pub use crate::segment::*;
261#[cfg(feature = "serde")]
262mod segment_serde;
263
264pub mod toc;
265pub use crate::toc::{Toc, TocEntry, TocEntryRef, TocRef};
266#[cfg(feature = "serde")]
267mod toc_serde;
268
269mod clock;
270pub use crate::clock::{AtomicClockReturn, ClockId, PeriodicClockId, SingleShotClockId};
271
272mod buffer_pool;
273pub use crate::buffer_pool::{BufferPoolAcquireParams, BufferPoolConfig, BufferPoolConfigRef};
274
275mod pad_template;
276pub use pad_template::PadTemplateBuilder;
277
278pub mod param_spec;
279pub use crate::param_spec::{ParamSpecArray, ParamSpecFraction};
280
281mod functions;
282pub use crate::functions::*;
283
284mod utils;
285pub use crate::utils::ObjectLockGuard;
286
287pub mod parse;
288
289#[cfg(feature = "v1_18")]
290mod gtype;
291
292use std::ptr;
293
294#[doc(alias = "gst_init_check")]
295pub fn init() -> Result<(), glib::Error> {
296    unsafe {
297        use glib::translate::*;
298
299        let mut error = ptr::null_mut();
300        if from_glib(ffi::gst_init_check(
301            ptr::null_mut(),
302            ptr::null_mut(),
303            &mut error,
304        )) {
305            crate::INITIALIZED.store(true, std::sync::atomic::Ordering::SeqCst);
306            Ok(())
307        } else {
308            Err(from_glib_full(error))
309        }
310    }
311}
312
313// rustdoc-stripper-ignore-next
314/// Deinitialize GStreamer
315///
316/// # Safety
317///
318/// This must only be called once during the lifetime of the process, once no GStreamer threads
319/// are running anymore and all GStreamer resources are released.
320pub unsafe fn deinit() {
321    crate::INITIALIZED.store(false, std::sync::atomic::Ordering::SeqCst);
322    ffi::gst_deinit();
323}
324
325pub const PARAM_FLAG_CONTROLLABLE: glib::ParamFlags = glib::ParamFlags::USER_1;
326pub const PARAM_FLAG_MUTABLE_READY: glib::ParamFlags = glib::ParamFlags::USER_2;
327pub const PARAM_FLAG_MUTABLE_PAUSED: glib::ParamFlags = glib::ParamFlags::USER_3;
328pub const PARAM_FLAG_MUTABLE_PLAYING: glib::ParamFlags = glib::ParamFlags::USER_4;
329#[cfg(feature = "v1_18")]
330pub const PARAM_FLAG_DOC_SHOW_DEFAULT: glib::ParamFlags = glib::ParamFlags::USER_5;
331#[cfg(feature = "v1_18")]
332pub const PARAM_FLAG_CONDITIONALLY_AVAILABLE: glib::ParamFlags = glib::ParamFlags::USER_6;
333
334// Re-export all the traits in a prelude module, so that applications
335// can always "use gst::prelude::*" without getting conflicts
336pub mod prelude {
337    #[doc(hidden)]
338    pub use glib::prelude::*;
339    pub use muldiv::MulDiv;
340    pub use opt_ops::prelude::*;
341
342    // OS dependent Bus extensions (also import the other platform trait for doc)
343    #[cfg(any(unix, docsrs))]
344    pub use crate::bus_unix::UnixBusExtManual;
345    #[cfg(any(windows, docsrs))]
346    pub use crate::bus_windows::WindowsBusExtManual;
347    #[cfg(feature = "v1_18")]
348    pub use crate::gtype::PluginApiExt;
349    pub use crate::{
350        auto::traits::*,
351        bin::GstBinExtManual,
352        buffer_pool::BufferPoolExtManual,
353        child_proxy::ChildProxyExtManual,
354        clock::ClockExtManual,
355        control_binding::ControlBindingExtManual,
356        control_source::ControlSourceExtManual,
357        device_monitor::DeviceMonitorExtManual,
358        device_provider::{DeviceProviderClassExt, DeviceProviderExtManual},
359        element::{ElementClassExt, ElementExtManual},
360        format::prelude::*,
361        gobject::GObjectExtManualGst,
362        log::DebugLogger,
363        memory::MemoryType,
364        message::MessageErrorDomain,
365        meta::{MetaAPI, MetaAPIExt, MetaTag},
366        miniobject::IsMiniObject,
367        object::GstObjectExtManual,
368        pad::PadExtManual,
369        param_spec::GstParamSpecBuilderExt,
370        pipeline::GstPipelineExtManual,
371        plugin_feature::PluginFeatureExtManual,
372        slice::ByteSliceExt,
373        tag_setter::TagSetterExtManual,
374        tags::{CustomTag, Tag},
375        task_pool::{TaskHandle, TaskPoolExtManual},
376        typefind::TypeFindImpl,
377        utils::Displayable,
378        value::GstValueExt,
379    };
380}
381
382#[macro_use]
383pub mod subclass;