gsk4/auto/

render_node.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::{RenderNodeType, ffi};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// The basic block in a scene graph to be rendered using [`Renderer`][crate::Renderer].
    ///
    /// Each node has a parent, except the top-level node; each node may have
    /// children nodes.
    ///
    /// Each node has an associated drawing surface, which has the size of
    /// the rectangle set when creating it.
    ///
    /// Render nodes are meant to be transient; once they have been associated
    /// to a [`Renderer`][crate::Renderer] it's safe to release any reference you have on
    /// them. All [`RenderNode`][crate::RenderNode]s are immutable, you can only specify their
    /// properties during construction.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    #[doc(alias = "GskRenderNode")]
    pub struct RenderNode(Shared<ffi::GskRenderNode>);

    match fn {
        ref => |ptr| ffi::gsk_render_node_ref(ptr),
        unref => |ptr| ffi::gsk_render_node_unref(ptr),
    }
}

impl StaticType for RenderNode {
    fn static_type() -> glib::Type {
        unsafe { from_glib(ffi::gsk_render_node_get_type()) }
    }
}

impl RenderNode {
    pub const NONE: Option<&'static RenderNode> = None;

    /// Draws the contents of a render node on a cairo context.
    ///
    /// Typically, you'll use this function to implement fallback rendering
    /// of render nodes on an intermediate Cairo context, instead of using
    /// the drawing context associated to a [`gdk::Surface`][crate::gdk::Surface]'s rendering buffer.
    ///
    /// For advanced nodes that cannot be supported using Cairo, in particular
    /// for nodes doing 3D operations, this function may fail.
    /// ## `cr`
    /// cairo context to draw to
    #[doc(alias = "gsk_render_node_draw")]
    pub fn draw(&self, cr: &cairo::Context) {
        unsafe {
            ffi::gsk_render_node_draw(
                self.as_ref().to_glib_none().0,
                mut_override(cr.to_glib_none().0),
            );
        }
    }

    /// Retrieves the boundaries of the @self.
    ///
    /// The node will not draw outside of its boundaries.
    ///
    /// # Returns
    ///
    ///
    /// ## `bounds`
    /// return location for the boundaries
    #[doc(alias = "gsk_render_node_get_bounds")]
    #[doc(alias = "get_bounds")]
    pub fn bounds(&self) -> graphene::Rect {
        unsafe {
            let mut bounds = graphene::Rect::uninitialized();
            ffi::gsk_render_node_get_bounds(
                self.as_ref().to_glib_none().0,
                bounds.to_glib_none_mut().0,
            );
            bounds
        }
    }

    /// Gets a list of all children nodes of the rendernode.
    ///
    /// Keep in mind that for various rendernodes, their children have different
    /// semantics, like the mask vs the source of a mask node. If you care about
    /// thse semantics, don't use this function, use the specific getters instead.
    ///
    /// # Returns
    ///
    /// The children
    #[cfg(feature = "v4_22")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_22")))]
    #[doc(alias = "gsk_render_node_get_children")]
    #[doc(alias = "get_children")]
    pub fn children(&self) -> Vec<RenderNode> {
        unsafe {
            let mut n_children = std::mem::MaybeUninit::uninit();
            let ret = FromGlibContainer::from_glib_none_num(
                ffi::gsk_render_node_get_children(
                    self.as_ref().to_glib_none().0,
                    n_children.as_mut_ptr(),
                ),
                n_children.assume_init() as _,
            );
            ret
        }
    }

    /// Returns the type of the render node.
    ///
    /// # Returns
    ///
    /// the type of @self
    #[doc(alias = "gsk_render_node_get_node_type")]
    #[doc(alias = "get_node_type")]
    pub fn node_type(&self) -> RenderNodeType {
        unsafe {
            from_glib(ffi::gsk_render_node_get_node_type(const_override(
                self.as_ref().to_glib_none().0,
            )))
        }
    }

    /// Gets an opaque rectangle inside the node that GTK can determine to
    /// be fully opaque.
    ///
    /// There is no guarantee that this is indeed the largest opaque rectangle or
    /// that regions outside the rectangle are not opaque. This function is a best
    /// effort with that goal.
    ///
    /// The rectangle will be fully contained in the bounds of the node.
    ///
    /// # Returns
    ///
    /// true if part or all of the rendernode is opaque, false if no
    ///   opaque region could be found.
    ///
    /// ## `out_opaque`
    /// return location for the opaque rect
    #[cfg(feature = "v4_16")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
    #[doc(alias = "gsk_render_node_get_opaque_rect")]
    #[doc(alias = "get_opaque_rect")]
    pub fn opaque_rect(&self) -> Option<graphene::Rect> {
        unsafe {
            let mut out_opaque = graphene::Rect::uninitialized();
            let ret = from_glib(ffi::gsk_render_node_get_opaque_rect(
                self.as_ref().to_glib_none().0,
                out_opaque.to_glib_none_mut().0,
            ));
            if ret { Some(out_opaque) } else { None }
        }
    }

    /// Serializes the @self for later deserialization via
    /// gsk_render_node_deserialize(). No guarantees are made about the format
    /// used other than that the same version of GTK will be able to deserialize
    /// the result of a call to gsk_render_node_serialize() and
    /// gsk_render_node_deserialize() will correctly reject files it cannot open
    /// that were created with previous versions of GTK.
    ///
    /// The intended use of this functions is testing, benchmarking and debugging.
    /// The format is not meant as a permanent storage format.
    ///
    /// # Returns
    ///
    /// a `GBytes` representing the node.
    #[doc(alias = "gsk_render_node_serialize")]
    pub fn serialize(&self) -> glib::Bytes {
        unsafe {
            from_glib_full(ffi::gsk_render_node_serialize(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// This function is equivalent to calling [`serialize()`][Self::serialize()]
    /// followed by `file_set_contents()`.
    ///
    /// See those two functions for details on the arguments.
    ///
    /// It is mostly intended for use inside a debugger to quickly dump a render
    /// node to a file for later inspection.
    /// ## `filename`
    /// the file to save it to
    ///
    /// # Returns
    ///
    /// true if saving was successful
    #[doc(alias = "gsk_render_node_write_to_file")]
    pub fn write_to_file(&self, filename: impl AsRef<std::path::Path>) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::gsk_render_node_write_to_file(
                self.as_ref().to_glib_none().0,
                filename.as_ref().to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}