gsk4/

render_replay.rs

// Take a look at the license at the top of the repository in the LICENSE file.

use crate::{ffi, RenderNode};
use glib::{prelude::*, translate::*};
use std::boxed::Box as Box_;

/// A facility to replay a [`RenderNode`][crate::RenderNode] and its children, potentially
/// modifying them.
///
/// This is a utility tool to walk a rendernode tree. The most powerful way
/// is to provide a function via [`set_node_filter()`][Self::set_node_filter()]
/// to filter each individual node and then run
/// [`filter_node()`][Self::filter_node()] on the nodes you want to filter.
///
/// An easier method exists to just walk the node tree and extract information
/// without any modifications. If you want to do that, the functions
/// [`set_node_foreach()`][Self::set_node_foreach()] exists. You can also call
/// [`foreach_node()`][Self::foreach_node()] to run that function. Note that
/// the previously mentioned complex functionality will still be invoked if you
/// have set up a function for it, but its result will not be returned.
///
/// Here is an example that combines both approaches to print the whole tree:
///
/// **⚠️ The following code is in c ⚠️**
///
/// ```c
/// #include <gtk/gtk.h>
///
/// static GskRenderNode *
/// print_nodes (GskRenderReplay *replay,
///              GskRenderNode   *node,
///              gpointer         user_data)
/// {
///   int *depth = user_data;
///   GskRenderNode *result;
///
///   g_print ("%*s%s\n", 2 * *depth, "", g_type_name_from_instance ((GTypeInstance *) node));
///
///   *depth += 1;
///   result = gsk_render_replay_default (replay, node);
///   *depth -= 1;
///
///   return result;
/// }
///
/// int
/// main (int argc, char *argv[])
/// {
///   GFile *file;
///   GBytes *bytes;
///   GskRenderNode *node;
///   GskRenderReplay *replay;
///   int depth = 0;
///
///   gtk_init ();
///
///   if (argc < 2)
///     {
///       g_print ("usage: %s NODEFILE\n", argv[0]);
///       return 0;
///     }
///
///   file = g_file_new_for_commandline_arg (argv[1]);
///   bytes = g_file_load_bytes (file, NULL, NULL, NULL);
///   g_object_unref (file);
///   if (bytes == NULL)
///     return 1;
///
///   node = gsk_render_node_deserialize (bytes, NULL, NULL);
///   g_bytes_unref (bytes);
///   if (node == NULL)
///     return 1;
///
///   replay = gsk_render_replay_new ();
///   gsk_render_replay_set_node_filter (replay, print_nodes, &depth, NULL);
///   gsk_render_node_foreach_node (replay, node);
///   gsk_render_node_unref (node);
///
///   return 0;
/// }
/// ```
#[repr(C)]
#[doc(alias = "GskRenderReplay")]
pub struct RenderReplay(std::ptr::NonNull<ffi::GskRenderReplay>);

impl Drop for RenderReplay {
    fn drop(&mut self) {
        unsafe {
            ffi::gsk_render_replay_free(self.0.as_ptr());
        }
    }
}

impl RenderReplay {
    /// Replays the node using the default method.
    ///
    /// The default method calls [`filter_node()`][Self::filter_node()]
    /// on all its child nodes and the filter functions for all its
    /// proeprties. If none of them are changed, it returns the passed
    /// in node. Otherwise it constructs a new node with the changed
    /// children and properties.
    ///
    /// It may not be possible to construct a new node when any of the
    /// callbacks return NULL. In that case, this function will return
    /// NULL, too.
    /// ## `node`
    /// the node to replay
    ///
    /// # Returns
    ///
    /// The replayed node
    #[doc(alias = "gsk_render_replay_default")]
    #[allow(clippy::should_implement_trait)]
    pub fn default(&self, node: impl AsRef<RenderNode>) -> Option<RenderNode> {
        unsafe {
            from_glib_full(ffi::gsk_render_replay_default(
                self.0.as_ptr(),
                node.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Filters a font using the current filter function.
    /// ## `font`
    /// The font to filter
    ///
    /// # Returns
    ///
    /// the filtered font
    #[doc(alias = "gsk_render_replay_filter_font")]
    pub fn filter_font(&self, font: &impl IsA<pango::Font>) -> pango::Font {
        unsafe {
            from_glib_full(ffi::gsk_render_replay_filter_font(
                self.0.as_ptr(),
                font.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Replays a node using the replay's filter function.
    ///
    /// After the replay the node may be unchanged, or it may be
    /// removed, which will result in [`None`] being returned.
    ///
    /// This function calls the registered callback in the following order:
    ///
    /// 1. If a foreach function is set, it is called first. If it returns
    ///    false, this function immediately exits and returns the passed
    ///    in node.
    ///
    /// 2. If a node filter is set, it is called and its result is returned.
    ///
    /// 3. [`default()`][Self::default()] is called and its result is
    ///    returned.
    /// ## `node`
    /// the node to replay
    ///
    /// # Returns
    ///
    /// The replayed node
    #[doc(alias = "gsk_render_replay_filter_node")]
    pub fn filter_node(&self, node: impl AsRef<RenderNode>) -> Option<RenderNode> {
        unsafe {
            from_glib_full(ffi::gsk_render_replay_filter_node(
                self.0.as_ptr(),
                node.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Filters a texture using the current filter function.
    /// ## `texture`
    /// The texture to filter
    ///
    /// # Returns
    ///
    /// the filtered texture
    #[doc(alias = "gsk_render_replay_filter_texture")]
    pub fn filter_texture(&self, texture: &impl IsA<gdk::Texture>) -> gdk::Texture {
        unsafe {
            from_glib_full(ffi::gsk_render_replay_filter_texture(
                self.0.as_ptr(),
                texture.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Calls the filter and foreach functions for each node.
    ///
    /// This function calls [`filter_node()`][Self::filter_node()] internally,
    /// but discards the result assuming no changes were made.
    /// ## `node`
    /// the node to replay
    #[doc(alias = "gsk_render_replay_foreach_node")]
    pub fn foreach_node(&self, node: impl AsRef<RenderNode>) {
        unsafe {
            ffi::gsk_render_replay_foreach_node(self.0.as_ptr(), node.as_ref().to_glib_none().0);
        }
    }

    /// Sets a filter function to be called by [`default()`][Self::default()]
    /// for nodes that contain fonts.
    ///
    /// You can call `GskRenderReplay::filter_font()` to filter
    /// a font yourself.
    /// ## `filter`
    /// the font filter function
    #[doc(alias = "gsk_render_replay_set_font_filter")]
    pub fn set_font_filter<P: Fn(&RenderReplay, &pango::Font) -> pango::Font + 'static>(
        &mut self,
        filter: P,
    ) {
        let filter_data: Box_<P> = Box_::new(filter);
        unsafe extern "C" fn filter_func<
            P: Fn(&RenderReplay, &pango::Font) -> pango::Font + 'static,
        >(
            replay: *mut ffi::GskRenderReplay,
            font: *mut pango::ffi::PangoFont,
            user_data: glib::ffi::gpointer,
        ) -> *mut pango::ffi::PangoFont {
            let replay = RenderReplay(std::ptr::NonNull::new_unchecked(replay));
            let font = from_glib_borrow(font);
            let callback = &*(user_data as *mut P);
            (*callback)(&replay, &font).into_glib_ptr()
        }
        let filter = Some(filter_func::<P> as _);
        unsafe extern "C" fn user_destroy_func<
            P: Fn(&RenderReplay, &pango::Font) -> pango::Font + 'static,
        >(
            data: glib::ffi::gpointer,
        ) {
            let _callback = Box_::from_raw(data as *mut P);
        }
        let destroy_call3 = Some(user_destroy_func::<P> as _);
        let super_callback0: Box_<P> = filter_data;
        unsafe {
            ffi::gsk_render_replay_set_font_filter(
                self.0.as_mut(),
                filter,
                Box_::into_raw(super_callback0) as *mut _,
                destroy_call3,
            );
        }
    }

    #[doc(alias = "gsk_render_replay_set_font_filter")]
    #[doc(alias = "set_font_filter")]
    pub fn unset_font_filter(&mut self) {
        unsafe {
            ffi::gsk_render_replay_set_font_filter(
                self.0.as_mut(),
                None,
                std::ptr::null_mut(),
                None,
            )
        }
    }

    /// Sets the function to use as a node filter.
    ///
    /// This is the most complex function to use for replaying nodes.
    /// It can either:
    ///
    /// * keep the node and just return it unchanged
    ///
    /// * create a replacement node and return that
    ///
    /// * discard the node by returning [`None`]
    ///
    /// * call [`default()`][Self::default()] to have the default handler
    ///   run for this node, which calls your function on its children
    /// ## `filter`
    /// The function to call to replay nodes
    #[doc(alias = "gsk_render_replay_set_node_filter")]
    pub fn set_node_filter<P: Fn(&RenderReplay, &RenderNode) -> Option<RenderNode> + 'static>(
        &mut self,
        filter: P,
    ) {
        let filter_data: Box_<P> = Box_::new(filter);
        unsafe extern "C" fn filter_func<
            P: Fn(&RenderReplay, &RenderNode) -> Option<RenderNode> + 'static,
        >(
            replay: *mut ffi::GskRenderReplay,
            node: *mut ffi::GskRenderNode,
            user_data: glib::ffi::gpointer,
        ) -> *mut ffi::GskRenderNode {
            let replay = RenderReplay(std::ptr::NonNull::new_unchecked(replay));
            let node = from_glib_borrow(node);
            let callback = &*(user_data as *mut P);
            (*callback)(&replay, &node).into_glib_ptr()
        }
        let filter = Some(filter_func::<P> as _);
        unsafe extern "C" fn user_destroy_func<
            P: Fn(&RenderReplay, &RenderNode) -> Option<RenderNode> + 'static,
        >(
            data: glib::ffi::gpointer,
        ) {
            let _callback = Box_::from_raw(data as *mut P);
        }
        let destroy_call3 = Some(user_destroy_func::<P> as _);
        let super_callback0: Box_<P> = filter_data;
        unsafe {
            ffi::gsk_render_replay_set_node_filter(
                self.0.as_mut(),
                filter,
                Box_::into_raw(super_callback0) as *mut _,
                destroy_call3,
            );
        }
    }

    #[doc(alias = "gsk_render_replay_set_node_filter")]
    #[doc(alias = "set_node_filter")]
    pub fn unset_node_filter(&mut self) {
        unsafe {
            ffi::gsk_render_replay_set_node_filter(
                self.0.as_mut(),
                None,
                std::ptr::null_mut(),
                None,
            )
        }
    }

    /// Sets the function to call for every node.
    ///
    /// This function is called before the node filter, so if it returns
    /// FALSE, the node filter will never be called.
    /// ## `foreach`
    /// the function to call for all nodes
    #[doc(alias = "gsk_render_replay_set_node_foreach")]
    pub fn set_node_foreach<P: Fn(&RenderReplay, &RenderNode) -> glib::ControlFlow + 'static>(
        &mut self,
        foreach: P,
    ) {
        let foreach_data: Box_<P> = Box_::new(foreach);
        unsafe extern "C" fn foreach_func<
            P: Fn(&RenderReplay, &RenderNode) -> glib::ControlFlow + 'static,
        >(
            replay: *mut ffi::GskRenderReplay,
            node: *mut ffi::GskRenderNode,
            user_data: glib::ffi::gpointer,
        ) -> glib::ffi::gboolean {
            let replay = RenderReplay(std::ptr::NonNull::new_unchecked(replay));
            let node = from_glib_borrow(node);
            let callback = &*(user_data as *mut P);
            (*callback)(&replay, &node).into_glib()
        }
        let foreach = Some(foreach_func::<P> as _);
        unsafe extern "C" fn user_destroy_func<
            P: Fn(&RenderReplay, &RenderNode) -> glib::ControlFlow + 'static,
        >(
            data: glib::ffi::gpointer,
        ) {
            let _callback = Box_::from_raw(data as *mut P);
        }
        let destroy_call3 = Some(user_destroy_func::<P> as _);
        let super_callback0: Box_<P> = foreach_data;
        unsafe {
            ffi::gsk_render_replay_set_node_foreach(
                self.0.as_mut(),
                foreach,
                Box_::into_raw(super_callback0) as *mut _,
                destroy_call3,
            );
        }
    }

    #[doc(alias = "gsk_render_replay_set_node_foreach")]
    #[doc(alias = "set_node_foreach")]
    pub fn unset_foreach_node(&mut self) {
        unsafe {
            ffi::gsk_render_replay_set_node_foreach(
                self.0.as_mut(),
                None,
                std::ptr::null_mut(),
                None,
            )
        }
    }

    /// Sets a filter function to be called by [`default()`][Self::default()]
    /// for nodes that contain textures.
    ///
    /// You can call `GskRenderReplay::filter_texture()` to filter
    /// a texture yourself.
    /// ## `filter`
    /// the texture filter function
    #[doc(alias = "gsk_render_replay_set_texture_filter")]
    pub fn set_texture_filter<P: Fn(&RenderReplay, &gdk::Texture) -> gdk::Texture + 'static>(
        &mut self,
        filter: P,
    ) {
        let filter_data: Box_<P> = Box_::new(filter);
        unsafe extern "C" fn filter_func<
            P: Fn(&RenderReplay, &gdk::Texture) -> gdk::Texture + 'static,
        >(
            replay: *mut ffi::GskRenderReplay,
            texture: *mut gdk::ffi::GdkTexture,
            user_data: glib::ffi::gpointer,
        ) -> *mut gdk::ffi::GdkTexture {
            let replay = RenderReplay(std::ptr::NonNull::new_unchecked(replay));
            let texture = from_glib_borrow(texture);
            let callback = &*(user_data as *mut P);
            (*callback)(&replay, &texture).into_glib_ptr()
        }
        let filter = Some(filter_func::<P> as _);
        unsafe extern "C" fn user_destroy_func<
            P: Fn(&RenderReplay, &gdk::Texture) -> gdk::Texture + 'static,
        >(
            data: glib::ffi::gpointer,
        ) {
            let _callback = Box_::from_raw(data as *mut P);
        }
        let destroy_call3 = Some(user_destroy_func::<P> as _);
        let super_callback0: Box_<P> = filter_data;
        unsafe {
            ffi::gsk_render_replay_set_texture_filter(
                self.0.as_mut(),
                filter,
                Box_::into_raw(super_callback0) as *mut _,
                destroy_call3,
            );
        }
    }

    #[doc(alias = "gsk_render_replay_set_texture_filter")]
    #[doc(alias = "set_texture_filter")]
    pub fn unset_texture_filter(&mut self) {
        unsafe {
            ffi::gsk_render_replay_set_texture_filter(
                self.0.as_mut(),
                None,
                std::ptr::null_mut(),
                None,
            )
        }
    }

    /// Creates a new replay object to replay nodes.
    ///
    /// # Returns
    ///
    /// A new replay object to replay nodes
    #[doc(alias = "gsk_render_replay_new")]
    pub fn new() -> RenderReplay {
        assert_initialized_main_thread!();
        unsafe {
            RenderReplay(std::ptr::NonNull::new_unchecked(
                ffi::gsk_render_replay_new(),
            ))
        }
    }
}

#[cfg(feature = "v4_22")]
#[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
impl Default for RenderReplay {
    fn default() -> Self {
        Self::new()
    }
}