// 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 glib::translate::*;
use glib::ObjectExt;
use std::mem;

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 [`Self::new()`]. It can be freed again with
    /// [`crate::glib::object::ObjectExt::unref()`].
    ///
    /// The theory of operation is like this: All buffers received are put
    /// into the adapter using [`Self::push()`] and the data is then read back
    /// in chunks of the desired size using [`Self::map()`]/[`Self::unmap()`]
    /// and/or [`Self::copy()`]. After the data has been processed, it is freed
    /// using [`Self::unmap()`].
    ///
    /// Other methods such as [`Self::take()`] and [`Self::take_buffer()`]
    /// combine [`Self::map()`] and [`Self::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:
    ///
    /// ```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 [`crate::Adapter`]
    /// is the libvisual element.
    ///
    /// An element using [`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
    /// [`Self::clear()`]. Data should also be cleared or processed on EOS and
    /// when changing state from [`crate::gst::State::Paused`] to [`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 [`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
    /// [`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 [`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
    /// [`Self::pts_at_discont()`], [`Self::dts_at_discont()`] and
    /// [`Self::offset_at_discont()`]. The number of bytes that were consumed
    /// since then can be queried with [`Self::distance_from_discont()`].
    ///
    /// A last thing to note is that while [`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 [`Self::available_fast()`] are provided to help
    /// speed up such cases should you want to. To avoid repeated memory allocations,
    /// [`Self::copy()`] can be used to copy data into a (statically allocated)
    /// user provided buffer.
    ///
    /// [`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 [`crate::Adapter`] is inside one pad's chain function, in which case access is
    /// serialized via the pad's STREAM_LOCK.
    ///
    /// Note that [`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::object::ObjectExt`]
    pub struct Adapter(Object<ffi::GstAdapter, ffi::GstAdapterClass>);

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

impl Adapter {
    /// Creates a new [`crate::Adapter`]. Free with [`crate::glib::object::ObjectExt::unref()`].
    ///
    /// # Returns
    ///
    /// a new [`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 [`Self::map()`] without that function
    /// returning [`None`].
    ///
    /// # 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 are immediately available without
    /// requiring 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
    /// [`crate::gst::BufferFlags::Discont`] flag.
    ///
    /// The distance will be reset to 0 for all buffers with
    /// [`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`.
    #[cfg(any(feature = "v1_10", feature = "dox"))]
    #[cfg_attr(feature = "dox", doc(cfg(feature = "v1_10")))]
    #[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.
    #[cfg(any(feature = "v1_10", feature = "dox"))]
    #[cfg_attr(feature = "dox", doc(cfg(feature = "v1_10")))]
    #[doc(alias = "gst_adapter_dts_at_discont")]
    pub fn dts_at_discont(&self) -> 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.
    #[cfg(any(feature = "v1_10", feature = "dox"))]
    #[cfg_attr(feature = "dox", doc(cfg(feature = "v1_10")))]
    #[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 removed from the adapter, the dts
    /// and distance returned are GST_CLOCK_TIME_NONE and 0 respectively.
    /// ## `distance`
    /// pointer to location for distance, or [`None`]
    ///
    /// # Returns
    ///
    /// The previously seen dts.
    #[doc(alias = "gst_adapter_prev_dts")]
    pub fn prev_dts(&self) -> (gst::ClockTime, u64) {
        unsafe {
            let mut distance = mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gst_adapter_prev_dts(
                self.to_glib_none().0,
                distance.as_mut_ptr(),
            ));
            let distance = distance.assume_init();
            (ret, distance)
        }
    }

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

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

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

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

    /// 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.
    #[cfg(any(feature = "v1_10", feature = "dox"))]
    #[cfg_attr(feature = "dox", doc(cfg(feature = "v1_10")))]
    #[doc(alias = "gst_adapter_pts_at_discont")]
    pub fn pts_at_discont(&self) -> 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()
    }
}

unsafe impl glib::SendUnique for Adapter {
    fn is_unique(&self) -> bool {
        self.ref_count() == 1
    }
}