forked from mirrors/gstreamer-rs
gst/format: module doc
This commit is contained in:
François Laignel
parent
e2fe1d6371
commit
bff1354b74
2 changed files with 403 additions and 1 deletions
|
|
@ -9,7 +9,7 @@ use super::{FormattedValue, SpecificFormattedValue};
|
|||
/// This trait is auto-implemented based on [`FormattedValue`]s additional traits
|
||||
/// such as [`SpecificFormattedValue`].
|
||||
///
|
||||
/// # Example:
|
||||
/// # Example
|
||||
///
|
||||
/// Consider the following function:
|
||||
///
|
||||
|
|
|
|||
|
|
@ -1,5 +1,407 @@
|
|||
// Take a look at the license at the top of the repository in the LICENSE file.
|
||||
|
||||
// rustdoc-stripper-ignore-next
|
||||
//! This modules gathers GStreamer's formatted value concepts together.
|
||||
//!
|
||||
//! GStreamer uses formatted values to differentiate value units in some APIs.
|
||||
//! In C this is done by qualifying an integer value by a companion enum
|
||||
//! [`GstFormat`]. In Rust, most APIs can use a specific type for each format.
|
||||
//! Each format type embeds the actual value using the new type pattern.
|
||||
//!
|
||||
//! # Specific Formatted Values
|
||||
//!
|
||||
//! Examples of specific formatted values include [`ClockTime`], [`Buffers`], etc.
|
||||
//! These types represent both the quantity and the unit making it possible for Rust
|
||||
//! to perform runtime and, to a certain extent, compile time invariants enforcement.
|
||||
//!
|
||||
//! Specific formatted values are also guaranteed to always represent a valid value.
|
||||
//! For instance:
|
||||
//!
|
||||
//! - [`Percent`] only allows values in the range [0, 1_000_000].
|
||||
//! - [`ClockTime`] can use all `u64` values except `u64::MAX` which is reserved by
|
||||
//! the C constant `GST_CLOCK_TIME_NONE`.
|
||||
//!
|
||||
//! ## Examples
|
||||
//!
|
||||
//! ### Querying the pipeline for a time position
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::ElementExtManual;
|
||||
//! # gst::init();
|
||||
//! # let pipeline = gst::Pipeline::new(None);
|
||||
//! let res = pipeline.query_position::<gst::ClockTime>();
|
||||
//! ```
|
||||
//!
|
||||
//! ## Seeking to a specific time position
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::ElementExtManual;
|
||||
//! # gst::init();
|
||||
//! # let pipeline = gst::Pipeline::new(None);
|
||||
//! # let seek_flags = gst::SeekFlags::FLUSH | gst::SeekFlags::KEY_UNIT;
|
||||
//! let seek_pos = gst::ClockTime::from_seconds(10);
|
||||
//! let res = pipeline.seek_simple(seek_flags, seek_pos);
|
||||
//! ```
|
||||
//!
|
||||
//! ### Downcasting a `Segment` for specific formatted value use
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::FormattedValue;
|
||||
//! # gst::init();
|
||||
//! # let segment = gst::FormattedSegment::<gst::ClockTime>::new().upcast();
|
||||
//! // Downcasting the generic `segment` for `gst::ClockTime` use.
|
||||
//! let time_segment = segment.downcast_ref::<gst::ClockTime>().expect("time segment");
|
||||
//! // Setters and getters conform to `gst::ClockTime`.
|
||||
//! // This is enforced at compilation time.
|
||||
//! let start = time_segment.start();
|
||||
//! assert_eq!(start.format(), gst::Format::Time);
|
||||
//! ```
|
||||
//!
|
||||
//! ### Displaying a formatted value
|
||||
//!
|
||||
//! Formatted values implement the [`Display`] trait which allows getting
|
||||
//! human readable representations.
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::Displayable;
|
||||
//! let time = gst::ClockTime::from_nseconds(45_834_908_569_837);
|
||||
//!
|
||||
//! assert_eq!(format!("{}", time), "12:43:54.908569837");
|
||||
//! assert_eq!(format!("{:.0}", time), "12:43:54");
|
||||
//! ```
|
||||
//!
|
||||
//! ## Some operations available on specific formatted values
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! let cur_pos = gst::ClockTime::ZERO;
|
||||
//!
|
||||
//! // All four arithmetic operations can be used:
|
||||
//! let fwd = cur_pos + 2 * gst::ClockTime::SECOND / 3 - gst::ClockTime::MSECOND;
|
||||
//!
|
||||
//! // Examples of operations which make sure not to overflow:
|
||||
//! let bwd = cur_pos.saturating_sub(2 * gst::ClockTime::SECOND);
|
||||
//! let further = cur_pos.checked_mul(2).expect("Overflowed");
|
||||
//!
|
||||
//! // Specific formatted values can be compared:
|
||||
//! assert!(fwd > bwd);
|
||||
//! assert_ne!(fwd, cur_pos);
|
||||
//!
|
||||
//! # fn next() -> gst::ClockTime { gst::ClockTime::ZERO };
|
||||
//! // Use `gst::ClockTime::MAX` for the maximum valid value:
|
||||
//! let mut min_pos = gst::ClockTime::MAX;
|
||||
//! for _ in 0..4 {
|
||||
//! min_pos = min_pos.min(next());
|
||||
//! }
|
||||
//!
|
||||
//! // And `gst::ClockTime::ZERO` for the minimum value:
|
||||
//! let mut max_pos = gst::ClockTime::ZERO;
|
||||
//! for _ in 0..4 {
|
||||
//! max_pos = max_pos.max(next());
|
||||
//! }
|
||||
//!
|
||||
//! // Specific formatted values implement the `MulDiv` trait:
|
||||
//! # use gst::prelude::MulDiv;
|
||||
//! # let (samples, rate) = (1024u64, 48000u64);
|
||||
//! let duration = samples
|
||||
//! .mul_div_round(*gst::ClockTime::SECOND, rate)
|
||||
//! .map(gst::ClockTime::from_nseconds);
|
||||
//! ```
|
||||
//!
|
||||
//! ## Types in operations
|
||||
//!
|
||||
//! Additions and substractions are available with the specific formatted value type
|
||||
//! as both left and right hand side operands.
|
||||
//!
|
||||
//! On the other hand, multiplications are only available with plain integers.
|
||||
//! This is because multiplying a `ClockTime` by a `ClockTime` would result in
|
||||
//! `ClockTime²`, whereas a `u64 * ClockTime` (or `ClockTime * u64`) still
|
||||
//! results in `ClockTime`.
|
||||
//!
|
||||
//! Divisions are available with both the specific formatted value and plain
|
||||
//! integers as right hand side operands. The difference is that
|
||||
//! `ClockTime / ClockTime` results in `u64` and `ClockTime / u64` results in
|
||||
//! `ClockTime`.
|
||||
//!
|
||||
//! # Optional specific formatted values
|
||||
//!
|
||||
//! Optional specific formatted values are represented as a standard Rust
|
||||
//! `Option<F>`. This departs from the C APIs which uses a sentinel that must
|
||||
//! be checked in order to figure out whether the value is defined.
|
||||
//!
|
||||
//! Besides giving access to the usual `Option` features, this ensures the APIs
|
||||
//! enforce mandatory or optional variants whenever possible.
|
||||
//!
|
||||
//! Note: for each specific formatted value `F`, the constant `F::NONE` is defined
|
||||
//! as a shortcut for `Option::<F>::None`. For `gst::ClockTime`, this constant is
|
||||
//! equivalent to the C constant `GST_CLOCK_TIME_NONE`.
|
||||
//!
|
||||
//! ## Examples
|
||||
//!
|
||||
//! ### Building a seek `Event` with undefined `stop` time
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # gst::init();
|
||||
//! # let seek_flags = gst::SeekFlags::FLUSH | gst::SeekFlags::KEY_UNIT;
|
||||
//! let seek_evt = gst::event::Seek::new(
|
||||
//! 1.0f64,
|
||||
//! seek_flags,
|
||||
//! gst::SeekType::Set,
|
||||
//! 10 * gst::ClockTime::SECOND, // start at 10s
|
||||
//! gst::SeekType::Set,
|
||||
//! gst::ClockTime::NONE, // stop is undefined
|
||||
//! );
|
||||
//! ```
|
||||
//!
|
||||
//! ### Displaying an optional formatted value
|
||||
//!
|
||||
//! Optional formatted values can take advantage of the [`Display`] implementation
|
||||
//! of the base specific formatted value. We have to workaround the [orphan rule]
|
||||
//! that forbids the implementation of [`Display`] for `Option<FormattedValue>`
|
||||
//! though. This is why displaying an optional formatted value necessitates calling
|
||||
//! [`display()`].
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::Displayable;
|
||||
//! let opt_time = Some(45_834_908_569_837 * gst::ClockTime::NSECOND);
|
||||
//!
|
||||
//! assert_eq!(format!("{}", opt_time.display()), "12:43:54.908569837");
|
||||
//! assert_eq!(format!("{:.0}", opt_time.display()), "12:43:54");
|
||||
//! assert_eq!(format!("{:.0}", gst::ClockTime::NONE.display()), "--:--:--");
|
||||
//! ```
|
||||
//!
|
||||
//! ### Some operations available on optional formatted values
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::*;
|
||||
//! let pts = Some(gst::ClockTime::ZERO);
|
||||
//! assert!(pts.is_some());
|
||||
//!
|
||||
//! // All four arithmetic operations can be used. Ex.:
|
||||
//! let fwd = pts.opt_add(2 * gst::ClockTime::SECOND);
|
||||
//! // `pts` is defined, so `fwd` will contain the addition result in `Some`,
|
||||
//! assert!(fwd.is_some());
|
||||
//! // otherwise `fwd` would be `None`.
|
||||
//!
|
||||
//! // Examples of operations which make sure not to overflow:
|
||||
//! let bwd = pts.opt_saturating_sub(2 * gst::ClockTime::SECOND);
|
||||
//! let further = pts.opt_checked_mul(2).expect("Overflowed");
|
||||
//!
|
||||
//! // Optional specific formatted values can be compared:
|
||||
//! assert_eq!(fwd.opt_gt(bwd), Some(true));
|
||||
//! assert_ne!(fwd, pts);
|
||||
//! assert_eq!(fwd.opt_min(bwd), bwd);
|
||||
//!
|
||||
//! // Optional specific formatted values operations also apply to non-optional values:
|
||||
//! assert_eq!(fwd.opt_lt(gst::ClockTime::SECOND), Some(false));
|
||||
//! assert_eq!(gst::ClockTime::SECOND.opt_lt(fwd), Some(true));
|
||||
//!
|
||||
//! // Comparing a defined values to an undefined value results in `None`:
|
||||
//! assert_eq!(bwd.opt_gt(gst::ClockTime::NONE), None);
|
||||
//! assert_eq!(gst::ClockTime::ZERO.opt_lt(gst::ClockTime::NONE), None);
|
||||
//! ```
|
||||
//!
|
||||
//! # Signed formatted values
|
||||
//!
|
||||
//! Some APIs can return a signed formatted value. See [`Segment::to_running_time_full`]
|
||||
//! for an example. In Rust, we use the [`Signed`] enum wrapper around the actual
|
||||
//! formatted value.
|
||||
//!
|
||||
//! For each signed specific formatted value `F`, the constants `F::MIN_SIGNED` and
|
||||
//! `F::MAX_SIGNED` represent the minimum and maximum signed values for `F`.
|
||||
//!
|
||||
//! ## Examples
|
||||
//!
|
||||
//! ### Handling a signed formatted value
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # gst::init();
|
||||
//! # let segment = gst::FormattedSegment::<gst::ClockTime>::new();
|
||||
//! use gst::Signed::*;
|
||||
//! match segment.to_running_time_full(2 * gst::ClockTime::SECOND) {
|
||||
//! Some(Positive(pos_rtime)) => println!("positive rtime {}", pos_rtime),
|
||||
//! Some(Negative(pos_rtime)) => println!("negative rtime {}", pos_rtime),
|
||||
//! None => println!("undefined rtime"),
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ### Converting a formatted value into a signed formatted value
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::UnsignedIntoSigned;
|
||||
//! let pos = gst::ClockTime::SECOND;
|
||||
//!
|
||||
//! let positive_one_sec = pos.into_positive();
|
||||
//! assert!(positive_one_sec.is_positive());
|
||||
//!
|
||||
//! let negative_one_sec = pos.into_negative();
|
||||
//! assert!(negative_one_sec.is_negative());
|
||||
//! ```
|
||||
//!
|
||||
//! ### Handling one sign only
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::UnsignedIntoSigned;
|
||||
//! # struct NegativeError;
|
||||
//! let p_one_sec = gst::ClockTime::SECOND.into_positive();
|
||||
//!
|
||||
//! let one_sec = p_one_sec.positive().expect("positive");
|
||||
//! let one_sec_or_zero = p_one_sec.positive().unwrap_or(gst::ClockTime::ZERO);
|
||||
//!
|
||||
//! let one_sec_or_err = p_one_sec.positive_or(NegativeError);
|
||||
//! let one_sec_or_else_err = p_one_sec.positive_or_else(|value| {
|
||||
//! println!("{} is negative", value);
|
||||
//! NegativeError
|
||||
//! });
|
||||
//! ```
|
||||
//!
|
||||
//! ### Displaying a signed formatted value
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::Displayable;
|
||||
//! # gst::init();
|
||||
//! # let mut segment = gst::FormattedSegment::<gst::ClockTime>::new();
|
||||
//! # segment.set_start(10 * gst::ClockTime::SECOND);
|
||||
//! let start = segment.start().unwrap();
|
||||
//! assert_eq!(format!("{:.0}", start), "0:00:10");
|
||||
//!
|
||||
//! let p_rtime = segment.to_running_time_full(20 * gst::ClockTime::SECOND);
|
||||
//! // Use `display()` with optional signed values.
|
||||
//! assert_eq!(format!("{:.0}", p_rtime.display()), "+0:00:10");
|
||||
//!
|
||||
//! let p_rtime = segment.to_running_time_full(gst::ClockTime::ZERO);
|
||||
//! assert_eq!(format!("{:.0}", p_rtime.display()), "-0:00:10");
|
||||
//!
|
||||
//! let p_rtime = segment.to_running_time_full(gst::ClockTime::NONE);
|
||||
//! assert_eq!(format!("{:.0}", p_rtime.display()), "--:--:--");
|
||||
//! ```
|
||||
//!
|
||||
//! ## Some operations available for signed formatted values
|
||||
//!
|
||||
//! All the operations available for formatted values can be used with
|
||||
//! signed formatted values.
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::UnsignedIntoSigned;
|
||||
//! let p_one_sec = gst::ClockTime::SECOND.into_positive();
|
||||
//! let p_two_sec = (2 * gst::ClockTime::SECOND).into_positive();
|
||||
//! let n_one_sec = gst::ClockTime::SECOND.into_negative();
|
||||
//!
|
||||
//! assert_eq!(p_one_sec + p_one_sec, p_two_sec);
|
||||
//! assert_eq!(p_two_sec - p_one_sec, p_one_sec);
|
||||
//! assert_eq!(gst::ClockTime::ZERO - p_one_sec, n_one_sec);
|
||||
//! assert_eq!(p_one_sec * 2u64, p_two_sec);
|
||||
//! assert_eq!(n_one_sec * -1i64, p_one_sec);
|
||||
//! assert_eq!(p_two_sec / 2u64, p_one_sec);
|
||||
//! assert_eq!(p_two_sec / p_one_sec, 2);
|
||||
//!
|
||||
//! // Examples of operations which make sure not to overflow:
|
||||
//! assert_eq!(p_one_sec.saturating_sub(p_two_sec), n_one_sec);
|
||||
//! assert_eq!(p_one_sec.checked_mul(2), Some(p_two_sec));
|
||||
//!
|
||||
//! // Signed formatted values can be compared:
|
||||
//! assert!(p_one_sec > n_one_sec);
|
||||
//!
|
||||
//! # fn next() -> gst::Signed<gst::ClockTime> { gst::ClockTime::ZERO.into_positive() };
|
||||
//! // Use `gst::ClockTime::MAX_SIGNED` for the maximum valid signed value:
|
||||
//! let mut min_signed_pos = gst::ClockTime::MAX_SIGNED;
|
||||
//! for _ in 0..4 {
|
||||
//! min_signed_pos = min_signed_pos.min(next());
|
||||
//! }
|
||||
//!
|
||||
//! // And `gst::ClockTime::MIN_SIGNED` for the minimum valid signed value:
|
||||
//! let mut max_signed_pos = gst::ClockTime::MIN_SIGNED;
|
||||
//! for _ in 0..4 {
|
||||
//! max_signed_pos = max_signed_pos.max(next());
|
||||
//! }
|
||||
//!
|
||||
//! // Signed formatted values implement the `MulDiv` trait:
|
||||
//! # use gst::prelude::MulDiv;
|
||||
//! # let rate = 48000u64;
|
||||
//! let samples = gst::format::Default(1024).into_negative();
|
||||
//! let duration = samples
|
||||
//! .mul_div_round(*gst::ClockTime::SECOND, rate)
|
||||
//! .map(|signed_default| {
|
||||
//! let signed_u64 = signed_default.into_inner_signed();
|
||||
//! gst::Signed::<gst::ClockTime>::from_nseconds(signed_u64)
|
||||
//! })
|
||||
//! .unwrap();
|
||||
//! assert!(duration.is_negative());
|
||||
//! ```
|
||||
//!
|
||||
//! ### Some operations available for optional signed formatted values
|
||||
//!
|
||||
//! All the operations available for optional formatted values can be used
|
||||
//! with signed formatted values.
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::*;
|
||||
//! let p_one_sec = gst::ClockTime::SECOND.into_positive();
|
||||
//! let p_two_sec = (2 * gst::ClockTime::SECOND).into_positive();
|
||||
//! let n_one_sec = gst::ClockTime::SECOND.into_negative();
|
||||
//!
|
||||
//! // Signed `ClockTime` addition with optional and non-optional operands.
|
||||
//! assert_eq!(Some(p_one_sec).opt_add(p_one_sec), Some(p_two_sec));
|
||||
//! assert_eq!(p_two_sec.opt_add(Some(n_one_sec)), Some(p_one_sec));
|
||||
//!
|
||||
//! // This can also be used with unsigned formatted values.
|
||||
//! assert_eq!(Some(p_one_sec).opt_add(gst::ClockTime::SECOND), Some(p_two_sec));
|
||||
//!
|
||||
//! // Etc...
|
||||
//! ```
|
||||
//!
|
||||
//! # Generic Formatted Values
|
||||
//!
|
||||
//! Sometimes, generic code can't assume a specific format will be used. For such
|
||||
//! use cases, the [`GenericFormattedValue`] enum makes it possible to select
|
||||
//! the appropriate behaviour at runtime.
|
||||
//!
|
||||
//! Most variants embed an optional specific formatted value.
|
||||
//!
|
||||
//! ## Example
|
||||
//!
|
||||
//! ### Generic handling of the position from a `SegmentDone` event
|
||||
//!
|
||||
//! ```
|
||||
//! # use gstreamer as gst;
|
||||
//! # use gst::prelude::{Displayable, ElementExtManual};
|
||||
//! # gst::init();
|
||||
//! # let event = gst::event::SegmentDone::new(gst::format::Buffers(512));
|
||||
//! if let gst::EventView::SegmentDone(seg_done_evt) = event.view() {
|
||||
//! use gst::GenericFormattedValue::*;
|
||||
//! match seg_done_evt.get() {
|
||||
//! Buffers(buffers) => println!("Segment done @ {}", buffers.display()),
|
||||
//! Bytes(bytes) => println!("Segment done @ {}", bytes.display()),
|
||||
//! Time(time) => println!("Segment done @ {}", time.display()),
|
||||
//! other => println!("Unexpected format for Segment done position {other:?}"),
|
||||
//! }
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! [`GstFormat`]: https://gstreamer.freedesktop.org/documentation/gstreamer/gstformat.html?gi-language=c
|
||||
//! [`ClockTime`]: struct.ClockTime.html
|
||||
//! [`Buffers`]: struct.Buffers.html
|
||||
//! [`Percent`]: struct.Percent.html
|
||||
//! [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
|
||||
//! [`display()`]: ../prelude/trait.Displayable.html
|
||||
//! [orphan rule]: https://doc.rust-lang.org/book/ch10-02-traits.html?highlight=orphan#implementing-a-trait-on-a-type
|
||||
//! [`Segment::to_running_time_full`]: ../struct.FormattedSegment.html#method.to_running_time_full
|
||||
//! [`Signed`]: enum.Signed.html
|
||||
//! [`GenericFormattedValue`]: generic/enum.GenericFormattedValue.html
|
||||
|
||||
use thiserror::Error;
|
||||
|
||||
#[macro_use]
|
||||
|
|
|
|||
Loading…
Reference in a new issue