gstreamer_base/auto/

adapter.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// from gst-gir-files (https://gitlab.freedesktop.org/gstreamer/gir-files-rs.git)
// DO NOT EDIT

use crate::ffi;
use glib::translate::*;

glib::wrapper! {
    /// 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 [`new()`][Self::new()]. It can be freed again with
    /// `g_object_unref()`.
    ///
    /// The theory of operation is like this: All buffers received are put
    /// into the adapter using [`push()`][Self::push()] and the data is then read back
    /// in chunks of the desired size using `gst_adapter_map()`/`gst_adapter_unmap()`
    /// and/or `gst_adapter_copy()`. After the data has been processed, it is freed
    /// using `gst_adapter_unmap()`.
    ///
    /// Other methods such as `gst_adapter_take()` and `gst_adapter_take_buffer()`
    /// combine `gst_adapter_map()` and `gst_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:
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```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`][crate::Adapter]
    /// is the libvisual element.
    ///
    /// An element using [`Adapter`][crate::Adapter] in its sink pad chain function should ensure that
    /// when the FLUSH_STOP event is received, that any queued data is cleared using
    /// [`clear()`][Self::clear()]. Data should also be cleared or processed on EOS and
    /// when changing state from [`gst::State::Paused`][crate::gst::State::Paused] to [`gst::State::Ready`][crate::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 [`prev_pts()`][Self::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
    /// [`prev_pts_at_offset()`][Self::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 [`prev_offset()`][Self::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
    /// [`pts_at_discont()`][Self::pts_at_discont()], [`dts_at_discont()`][Self::dts_at_discont()] and
    /// [`offset_at_discont()`][Self::offset_at_discont()]. The number of bytes that were consumed
    /// since then can be queried with [`distance_from_discont()`][Self::distance_from_discont()].
    ///
    /// A last thing to note is that while [`Adapter`][crate::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 [`available_fast()`][Self::available_fast()] are provided to help
    /// speed up such cases should you want to. To avoid repeated memory allocations,
    /// `gst_adapter_copy()` can be used to copy data into a (statically allocated)
    /// user provided buffer.
    ///
    /// [`Adapter`][crate::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`][crate::Adapter] is inside one pad's chain function, in which case access is
    /// serialized via the pad's STREAM_LOCK.
    ///
    /// Note that [`push()`][Self::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::ObjectExt`]
    #[doc(alias = "GstAdapter")]
    pub struct Adapter(Object<ffi::GstAdapter, ffi::GstAdapterClass>);

    match fn {
        type_ => || ffi::gst_adapter_get_type(),
    }
}

impl Adapter {
    /// Creates a new [`Adapter`][crate::Adapter]. Free with `g_object_unref()`.
    ///
    /// # Returns
    ///
    /// a new [`Adapter`][crate::Adapter]
    #[doc(alias = "gst_adapter_new")]
    pub fn new() -> Adapter {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gst_adapter_new()) }
    }

    /// Gets the maximum amount of bytes available, that is it returns the maximum
    /// value that can be supplied to `gst_adapter_map()` without that function
    /// returning [`None`].
    ///
    /// Calling `gst_adapter_map()` with the amount of bytes returned by this function
    /// may require expensive operations (like copying the data into a temporary
    /// buffer) in some cases.
    ///
    /// # Returns
    ///
    /// number of bytes available in `self`
    #[doc(alias = "gst_adapter_available")]
    pub fn available(&self) -> usize {
        unsafe { ffi::gst_adapter_available(self.to_glib_none().0) }
    }

    /// Gets the maximum number of bytes that can be retrieved in a single map
    /// operation without merging buffers.
    ///
    /// Calling `gst_adapter_map()` with the amount of bytes returned by this function
    /// will never require any expensive operations (like copying the data into a
    /// temporary buffer).
    ///
    /// # Returns
    ///
    /// number of bytes that are available in `self` without expensive
    /// operations
    #[doc(alias = "gst_adapter_available_fast")]
    pub fn available_fast(&self) -> usize {
        unsafe { ffi::gst_adapter_available_fast(self.to_glib_none().0) }
    }

    /// Removes all buffers from `self`.
    #[doc(alias = "gst_adapter_clear")]
    pub fn clear(&self) {
        unsafe {
            ffi::gst_adapter_clear(self.to_glib_none().0);
        }
    }

    /// Get the distance in bytes since the last buffer with the
    /// [`gst::BufferFlags::DISCONT`][crate::gst::BufferFlags::DISCONT] flag.
    ///
    /// The distance will be reset to 0 for all buffers with
    /// [`gst::BufferFlags::DISCONT`][crate::gst::BufferFlags::DISCONT] on them, and then calculated for all other
    /// following buffers based on their size.
    ///
    /// # Returns
    ///
    /// The offset. Can be `GST_BUFFER_OFFSET_NONE`.
    #[doc(alias = "gst_adapter_distance_from_discont")]
    pub fn distance_from_discont(&self) -> u64 {
        unsafe { ffi::gst_adapter_distance_from_discont(self.to_glib_none().0) }
    }

    /// Get the DTS that was on the last buffer with the GST_BUFFER_FLAG_DISCONT
    /// flag, or GST_CLOCK_TIME_NONE.
    ///
    /// # Returns
    ///
    /// The DTS at the last discont or GST_CLOCK_TIME_NONE.
    #[doc(alias = "gst_adapter_dts_at_discont")]
    pub fn dts_at_discont(&self) -> Option<gst::ClockTime> {
        unsafe { from_glib(ffi::gst_adapter_dts_at_discont(self.to_glib_none().0)) }
    }

    /// Get the offset that was on the last buffer with the GST_BUFFER_FLAG_DISCONT
    /// flag, or GST_BUFFER_OFFSET_NONE.
    ///
    /// # Returns
    ///
    /// The offset at the last discont or GST_BUFFER_OFFSET_NONE.
    #[doc(alias = "gst_adapter_offset_at_discont")]
    pub fn offset_at_discont(&self) -> u64 {
        unsafe { ffi::gst_adapter_offset_at_discont(self.to_glib_none().0) }
    }

    /// 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 added to the adapter, the dts
    /// and distance returned are GST_CLOCK_TIME_NONE and 0 respectively.
    ///
    /// # Returns
    ///
    /// The previously seen dts.
    ///
    /// ## `distance`
    /// pointer to location for distance, or [`None`]
    #[doc(alias = "gst_adapter_prev_dts")]
    pub fn prev_dts(&self) -> (Option<gst::ClockTime>, u64) {
        unsafe {
            let mut distance = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gst_adapter_prev_dts(
                self.to_glib_none().0,
                distance.as_mut_ptr(),
            ));
            (ret, distance.assume_init())
        }
    }

    /// 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 added to 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
    ///
    /// # Returns
    ///
    /// The previously seen dts at given offset.
    ///
    /// ## `distance`
    /// pointer to location for distance, or [`None`]
    #[doc(alias = "gst_adapter_prev_dts_at_offset")]
    pub fn prev_dts_at_offset(&self, offset: usize) -> (Option<gst::ClockTime>, u64) {
        unsafe {
            let mut distance = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gst_adapter_prev_dts_at_offset(
                self.to_glib_none().0,
                offset,
                distance.as_mut_ptr(),
            ));
            (ret, distance.assume_init())
        }
    }

    /// 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 added to the adapter, the offset
    /// and distance returned are GST_BUFFER_OFFSET_NONE and 0 respectively.
    ///
    /// # Returns
    ///
    /// The previous seen offset.
    ///
    /// ## `distance`
    /// pointer to a location for distance, or [`None`]
    #[doc(alias = "gst_adapter_prev_offset")]
    pub fn prev_offset(&self) -> (u64, u64) {
        unsafe {
            let mut distance = std::mem::MaybeUninit::uninit();
            let ret = ffi::gst_adapter_prev_offset(self.to_glib_none().0, distance.as_mut_ptr());
            (ret, distance.assume_init())
        }
    }

    /// 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 added to the adapter, the pts
    /// and distance returned are GST_CLOCK_TIME_NONE and 0 respectively.
    ///
    /// # Returns
    ///
    /// The previously seen pts.
    ///
    /// ## `distance`
    /// pointer to location for distance, or [`None`]
    #[doc(alias = "gst_adapter_prev_pts")]
    pub fn prev_pts(&self) -> (Option<gst::ClockTime>, u64) {
        unsafe {
            let mut distance = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gst_adapter_prev_pts(
                self.to_glib_none().0,
                distance.as_mut_ptr(),
            ));
            (ret, distance.assume_init())
        }
    }

    /// 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 added to 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
    ///
    /// # Returns
    ///
    /// The previously seen pts at given offset.
    ///
    /// ## `distance`
    /// pointer to location for distance, or [`None`]
    #[doc(alias = "gst_adapter_prev_pts_at_offset")]
    pub fn prev_pts_at_offset(&self, offset: usize) -> (Option<gst::ClockTime>, u64) {
        unsafe {
            let mut distance = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gst_adapter_prev_pts_at_offset(
                self.to_glib_none().0,
                offset,
                distance.as_mut_ptr(),
            ));
            (ret, distance.assume_init())
        }
    }

    /// Get the PTS that was on the last buffer with the GST_BUFFER_FLAG_DISCONT
    /// flag, or GST_CLOCK_TIME_NONE.
    ///
    /// # Returns
    ///
    /// The PTS at the last discont or GST_CLOCK_TIME_NONE.
    #[doc(alias = "gst_adapter_pts_at_discont")]
    pub fn pts_at_discont(&self) -> Option<gst::ClockTime> {
        unsafe { from_glib(ffi::gst_adapter_pts_at_discont(self.to_glib_none().0)) }
    }
}

impl Default for Adapter {
    fn default() -> Self {
        Self::new()
    }
}