gdk4/auto/

frame_clock.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi, FrameClockPhase, FrameTimings};
use glib::{
    object::ObjectType as _,
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// Tells the application when to update and repaint a surface.
    ///
    /// This may be synced to the vertical refresh rate of the monitor, for example.
    /// Even when the frame clock uses a simple timer rather than a hardware-based
    /// vertical sync, the frame clock helps because it ensures everything paints at
    /// the same time (reducing the total number of frames).
    ///
    /// The frame clock can also automatically stop painting when it knows the frames
    /// will not be visible, or scale back animation framerates.
    ///
    /// [`FrameClock`][crate::FrameClock] is designed to be compatible with an OpenGL-based implementation
    /// or with mozRequestAnimationFrame in Firefox, for example.
    ///
    /// A frame clock is idle until someone requests a frame with
    /// [`request_phase()`][Self::request_phase()]. At some later point that makes sense
    /// for the synchronization being implemented, the clock will process a frame and
    /// emit signals for each phase that has been requested. (See the signals of the
    /// [`FrameClock`][crate::FrameClock] class for documentation of the phases.
    /// [`FrameClockPhase::UPDATE`][crate::FrameClockPhase::UPDATE] and the [`update`][struct@crate::FrameClock#update] signal
    /// are most interesting for application writers, and are used to update the
    /// animations, using the frame time given by [`frame_time()`][Self::frame_time()].
    ///
    /// The frame time is reported in microseconds and generally in the same
    /// timescale as g_get_monotonic_time(), however, it is not the same
    /// as g_get_monotonic_time(). The frame time does not advance during
    /// the time a frame is being painted, and outside of a frame, an attempt
    /// is made so that all calls to [`frame_time()`][Self::frame_time()] that
    /// are called at a “similar” time get the same value. This means that
    /// if different animations are timed by looking at the difference in
    /// time between an initial value from [`frame_time()`][Self::frame_time()]
    /// and the value inside the [`update`][struct@crate::FrameClock#update] signal of the clock,
    /// they will stay exactly synchronized.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Signals
    ///
    ///
    /// #### `after-paint`
    ///  This signal ends processing of the frame.
    ///
    /// Applications should generally not handle this signal.
    ///
    ///
    ///
    ///
    /// #### `before-paint`
    ///  Begins processing of the frame.
    ///
    /// Applications should generally not handle this signal.
    ///
    ///
    ///
    ///
    /// #### `flush-events`
    ///  Used to flush pending motion events that are being batched up and
    /// compressed together.
    ///
    /// Applications should not handle this signal.
    ///
    ///
    ///
    ///
    /// #### `layout`
    ///  Emitted as the second step of toolkit and application processing
    /// of the frame.
    ///
    /// Any work to update sizes and positions of application elements
    /// should be performed. GTK normally handles this internally.
    ///
    ///
    ///
    ///
    /// #### `paint`
    ///  Emitted as the third step of toolkit and application processing
    /// of the frame.
    ///
    /// The frame is repainted. GDK normally handles this internally and
    /// emits [`render`][struct@crate::Surface#render] signals which are turned into
    /// [GtkWidget::snapshot](../gtk4/signal.Widget.snapshot.html) signals
    /// by GTK.
    ///
    ///
    ///
    ///
    /// #### `resume-events`
    ///  Emitted after processing of the frame is finished.
    ///
    /// This signal is handled internally by GTK to resume normal
    /// event processing. Applications should not handle this signal.
    ///
    ///
    ///
    ///
    /// #### `update`
    ///  Emitted as the first step of toolkit and application processing
    /// of the frame.
    ///
    /// Animations should be updated using [`FrameClock::frame_time()`][crate::FrameClock::frame_time()].
    /// Applications can connect directly to this signal, or use
    /// [gtk_widget_add_tick_callback()](../gtk4/method.Widget.add_tick_callback.html)
    /// as a more convenient interface.
    ///
    ///
    #[doc(alias = "GdkFrameClock")]
    pub struct FrameClock(Object<ffi::GdkFrameClock, ffi::GdkFrameClockClass>);

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

impl FrameClock {
    /// Starts updates for an animation.
    ///
    /// Until a matching call to [`end_updating()`][Self::end_updating()] is made,
    /// the frame clock will continually request a new frame with the
    /// [`FrameClockPhase::UPDATE`][crate::FrameClockPhase::UPDATE] phase. This function may be called multiple
    /// times and frames will be requested until gdk_frame_clock_end_updating()
    /// is called the same number of times.
    #[doc(alias = "gdk_frame_clock_begin_updating")]
    pub fn begin_updating(&self) {
        unsafe {
            ffi::gdk_frame_clock_begin_updating(self.to_glib_none().0);
        }
    }

    /// Stops updates for an animation.
    ///
    /// See the documentation for [`begin_updating()`][Self::begin_updating()].
    #[doc(alias = "gdk_frame_clock_end_updating")]
    pub fn end_updating(&self) {
        unsafe {
            ffi::gdk_frame_clock_end_updating(self.to_glib_none().0);
        }
    }

    /// Gets the frame timings for the current frame.
    ///
    /// # Returns
    ///
    /// the [`FrameTimings`][crate::FrameTimings] for the
    ///   frame currently being processed, or even no frame is being
    ///   processed, for the previous frame. Before any frames have been
    ///   processed, returns [`None`].
    #[doc(alias = "gdk_frame_clock_get_current_timings")]
    #[doc(alias = "get_current_timings")]
    pub fn current_timings(&self) -> Option<FrameTimings> {
        unsafe {
            from_glib_none(ffi::gdk_frame_clock_get_current_timings(
                self.to_glib_none().0,
            ))
        }
    }

    /// Calculates the current frames-per-second, based on the
    /// frame timings of @self.
    ///
    /// # Returns
    ///
    /// the current fps, as a `double`
    #[doc(alias = "gdk_frame_clock_get_fps")]
    #[doc(alias = "get_fps")]
    pub fn fps(&self) -> f64 {
        unsafe { ffi::gdk_frame_clock_get_fps(self.to_glib_none().0) }
    }

    /// [`FrameClock`][crate::FrameClock] maintains a 64-bit counter that increments for
    /// each frame drawn.
    ///
    /// # Returns
    ///
    /// inside frame processing, the value of the frame counter
    ///   for the current frame. Outside of frame processing, the frame
    ///   counter for the last frame.
    #[doc(alias = "gdk_frame_clock_get_frame_counter")]
    #[doc(alias = "get_frame_counter")]
    pub fn frame_counter(&self) -> i64 {
        unsafe { ffi::gdk_frame_clock_get_frame_counter(self.to_glib_none().0) }
    }

    /// Gets the time that should currently be used for animations.
    ///
    /// Inside the processing of a frame, it’s the time used to compute the
    /// animation position of everything in a frame. Outside of a frame, it's
    /// the time of the conceptual “previous frame,” which may be either
    /// the actual previous frame time, or if that’s too old, an updated
    /// time.
    ///
    /// # Returns
    ///
    /// a timestamp in microseconds, in the timescale of
    ///  of g_get_monotonic_time().
    #[doc(alias = "gdk_frame_clock_get_frame_time")]
    #[doc(alias = "get_frame_time")]
    pub fn frame_time(&self) -> i64 {
        unsafe { ffi::gdk_frame_clock_get_frame_time(self.to_glib_none().0) }
    }

    /// Returns the frame counter for the oldest frame available in history.
    ///
    /// [`FrameClock`][crate::FrameClock] internally keeps a history of [`FrameTimings`][crate::FrameTimings]
    /// objects for recent frames that can be retrieved with
    /// [`timings()`][Self::timings()]. The set of stored frames
    /// is the set from the counter values given by
    /// [`history_start()`][Self::history_start()] and
    /// [`frame_counter()`][Self::frame_counter()], inclusive.
    ///
    /// # Returns
    ///
    /// the frame counter value for the oldest frame
    ///  that is available in the internal frame history of the
    ///  [`FrameClock`][crate::FrameClock]
    #[doc(alias = "gdk_frame_clock_get_history_start")]
    #[doc(alias = "get_history_start")]
    pub fn history_start(&self) -> i64 {
        unsafe { ffi::gdk_frame_clock_get_history_start(self.to_glib_none().0) }
    }

    /// Predicts a presentation time, based on history.
    ///
    /// Using the frame history stored in the frame clock, finds the last
    /// known presentation time and refresh interval, and assuming that
    /// presentation times are separated by the refresh interval,
    /// predicts a presentation time that is a multiple of the refresh
    /// interval after the last presentation time, and later than @base_time.
    /// ## `base_time`
    /// base time for determining a presentaton time
    ///
    /// # Returns
    ///
    ///
    /// ## `refresh_interval_return`
    /// a location to store the
    ///   determined refresh interval, or [`None`]. A default refresh interval of
    ///   1/60th of a second will be stored if no history is present.
    ///
    /// ## `presentation_time_return`
    /// a location to store the next
    ///   candidate presentation time after the given base time.
    ///   0 will be will be stored if no history is present.
    #[doc(alias = "gdk_frame_clock_get_refresh_info")]
    #[doc(alias = "get_refresh_info")]
    pub fn refresh_info(&self, base_time: i64) -> (i64, i64) {
        unsafe {
            let mut refresh_interval_return = std::mem::MaybeUninit::uninit();
            let mut presentation_time_return = std::mem::MaybeUninit::uninit();
            ffi::gdk_frame_clock_get_refresh_info(
                self.to_glib_none().0,
                base_time,
                refresh_interval_return.as_mut_ptr(),
                presentation_time_return.as_mut_ptr(),
            );
            (
                refresh_interval_return.assume_init(),
                presentation_time_return.assume_init(),
            )
        }
    }

    /// Retrieves a [`FrameTimings`][crate::FrameTimings] object holding timing information
    /// for the current frame or a recent frame.
    ///
    /// The [`FrameTimings`][crate::FrameTimings] object may not yet be complete: see
    /// [`FrameTimings::is_complete()`][crate::FrameTimings::is_complete()] and
    /// [`history_start()`][Self::history_start()].
    /// ## `frame_counter`
    /// the frame counter value identifying the frame to
    ///  be received
    ///
    /// # Returns
    ///
    /// the [`FrameTimings`][crate::FrameTimings] object
    ///   for the specified frame, or [`None`] if it is not available
    #[doc(alias = "gdk_frame_clock_get_timings")]
    #[doc(alias = "get_timings")]
    pub fn timings(&self, frame_counter: i64) -> Option<FrameTimings> {
        unsafe {
            from_glib_none(ffi::gdk_frame_clock_get_timings(
                self.to_glib_none().0,
                frame_counter,
            ))
        }
    }

    /// Asks the frame clock to run a particular phase.
    ///
    /// The signal corresponding the requested phase will be emitted the next
    /// time the frame clock processes. Multiple calls to
    /// gdk_frame_clock_request_phase() will be combined together
    /// and only one frame processed. If you are displaying animated
    /// content and want to continually request the
    /// [`FrameClockPhase::UPDATE`][crate::FrameClockPhase::UPDATE] phase for a period of time,
    /// you should use [`begin_updating()`][Self::begin_updating()] instead,
    /// since this allows GTK to adjust system parameters to get maximally
    /// smooth animations.
    /// ## `phase`
    /// the phase that is requested
    #[doc(alias = "gdk_frame_clock_request_phase")]
    pub fn request_phase(&self, phase: FrameClockPhase) {
        unsafe {
            ffi::gdk_frame_clock_request_phase(self.to_glib_none().0, phase.into_glib());
        }
    }

    /// This signal ends processing of the frame.
    ///
    /// Applications should generally not handle this signal.
    #[doc(alias = "after-paint")]
    pub fn connect_after_paint<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn after_paint_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"after-paint".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    after_paint_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Begins processing of the frame.
    ///
    /// Applications should generally not handle this signal.
    #[doc(alias = "before-paint")]
    pub fn connect_before_paint<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn before_paint_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"before-paint".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    before_paint_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Used to flush pending motion events that are being batched up and
    /// compressed together.
    ///
    /// Applications should not handle this signal.
    #[doc(alias = "flush-events")]
    pub fn connect_flush_events<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn flush_events_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"flush-events".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    flush_events_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted as the second step of toolkit and application processing
    /// of the frame.
    ///
    /// Any work to update sizes and positions of application elements
    /// should be performed. GTK normally handles this internally.
    #[doc(alias = "layout")]
    pub fn connect_layout<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn layout_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"layout".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    layout_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted as the third step of toolkit and application processing
    /// of the frame.
    ///
    /// The frame is repainted. GDK normally handles this internally and
    /// emits [`render`][struct@crate::Surface#render] signals which are turned into
    /// [GtkWidget::snapshot](../gtk4/signal.Widget.snapshot.html) signals
    /// by GTK.
    #[doc(alias = "paint")]
    pub fn connect_paint<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn paint_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"paint".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    paint_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted after processing of the frame is finished.
    ///
    /// This signal is handled internally by GTK to resume normal
    /// event processing. Applications should not handle this signal.
    #[doc(alias = "resume-events")]
    pub fn connect_resume_events<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn resume_events_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"resume-events".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    resume_events_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    /// Emitted as the first step of toolkit and application processing
    /// of the frame.
    ///
    /// Animations should be updated using [`frame_time()`][Self::frame_time()].
    /// Applications can connect directly to this signal, or use
    /// [gtk_widget_add_tick_callback()](../gtk4/method.Widget.add_tick_callback.html)
    /// as a more convenient interface.
    #[doc(alias = "update")]
    pub fn connect_update<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn update_trampoline<F: Fn(&FrameClock) + 'static>(
            this: *mut ffi::GdkFrameClock,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"update".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    update_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}