gsk4/auto/
render_node.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, RenderNodeType};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// [`RenderNode`][crate::RenderNode] is the basic block in a scene graph to be
10    /// rendered using [`Renderer`][crate::Renderer].
11    ///
12    /// Each node has a parent, except the top-level node; each node may have
13    /// children nodes.
14    ///
15    /// Each node has an associated drawing surface, which has the size of
16    /// the rectangle set when creating it.
17    ///
18    /// Render nodes are meant to be transient; once they have been associated
19    /// to a [`Renderer`][crate::Renderer] it's safe to release any reference you have on
20    /// them. All [`RenderNode`][crate::RenderNode]s are immutable, you can only specify their
21    /// properties during construction.
22    ///
23    /// This is an Abstract Base Class, you cannot instantiate it.
24    #[doc(alias = "GskRenderNode")]
25    pub struct RenderNode(Shared<ffi::GskRenderNode>);
26
27    match fn {
28        ref => |ptr| ffi::gsk_render_node_ref(ptr),
29        unref => |ptr| ffi::gsk_render_node_unref(ptr),
30    }
31}
32
33impl StaticType for RenderNode {
34    fn static_type() -> glib::Type {
35        unsafe { from_glib(ffi::gsk_render_node_get_type()) }
36    }
37}
38
39impl RenderNode {
40    pub const NONE: Option<&'static RenderNode> = None;
41
42    /// Draws the contents of a render node on a cairo context.
43    ///
44    /// Typically, you'll use this function to implement fallback rendering
45    /// of render nodes on an intermediate Cairo context, instead of using
46    /// the drawing context associated to a [`gdk::Surface`][crate::gdk::Surface]'s rendering buffer.
47    ///
48    /// For advanced nodes that cannot be supported using Cairo, in particular
49    /// for nodes doing 3D operations, this function may fail.
50    /// ## `cr`
51    /// cairo context to draw to
52    #[doc(alias = "gsk_render_node_draw")]
53    pub fn draw(&self, cr: &cairo::Context) {
54        unsafe {
55            ffi::gsk_render_node_draw(
56                self.as_ref().to_glib_none().0,
57                mut_override(cr.to_glib_none().0),
58            );
59        }
60    }
61
62    /// Retrieves the boundaries of the @self.
63    ///
64    /// The node will not draw outside of its boundaries.
65    ///
66    /// # Returns
67    ///
68    ///
69    /// ## `bounds`
70    /// return location for the boundaries
71    #[doc(alias = "gsk_render_node_get_bounds")]
72    #[doc(alias = "get_bounds")]
73    pub fn bounds(&self) -> graphene::Rect {
74        unsafe {
75            let mut bounds = graphene::Rect::uninitialized();
76            ffi::gsk_render_node_get_bounds(
77                self.as_ref().to_glib_none().0,
78                bounds.to_glib_none_mut().0,
79            );
80            bounds
81        }
82    }
83
84    /// Returns the type of the render node.
85    ///
86    /// # Returns
87    ///
88    /// the type of @self
89    #[doc(alias = "gsk_render_node_get_node_type")]
90    #[doc(alias = "get_node_type")]
91    pub fn node_type(&self) -> RenderNodeType {
92        unsafe {
93            from_glib(ffi::gsk_render_node_get_node_type(const_override(
94                self.as_ref().to_glib_none().0,
95            )))
96        }
97    }
98
99    /// Gets an opaque rectangle inside the node that GTK can determine to
100    /// be fully opaque.
101    ///
102    /// There is no guarantee that this is indeed the largest opaque rectangle or
103    /// that regions outside the rectangle are not opaque. This function is a best
104    /// effort with that goal.
105    ///
106    /// The rectangle will be fully contained in the bounds of the node.
107    ///
108    /// # Returns
109    ///
110    /// true if part or all of the rendernode is opaque, false if no
111    ///   opaque region could be found.
112    ///
113    /// ## `out_opaque`
114    /// return location for the opaque rect
115    #[cfg(feature = "v4_16")]
116    #[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
117    #[doc(alias = "gsk_render_node_get_opaque_rect")]
118    #[doc(alias = "get_opaque_rect")]
119    pub fn opaque_rect(&self) -> Option<graphene::Rect> {
120        unsafe {
121            let mut out_opaque = graphene::Rect::uninitialized();
122            let ret = from_glib(ffi::gsk_render_node_get_opaque_rect(
123                self.as_ref().to_glib_none().0,
124                out_opaque.to_glib_none_mut().0,
125            ));
126            if ret {
127                Some(out_opaque)
128            } else {
129                None
130            }
131        }
132    }
133
134    /// Serializes the @self for later deserialization via
135    /// gsk_render_node_deserialize(). No guarantees are made about the format
136    /// used other than that the same version of GTK will be able to deserialize
137    /// the result of a call to gsk_render_node_serialize() and
138    /// gsk_render_node_deserialize() will correctly reject files it cannot open
139    /// that were created with previous versions of GTK.
140    ///
141    /// The intended use of this functions is testing, benchmarking and debugging.
142    /// The format is not meant as a permanent storage format.
143    ///
144    /// # Returns
145    ///
146    /// a `GBytes` representing the node.
147    #[doc(alias = "gsk_render_node_serialize")]
148    pub fn serialize(&self) -> glib::Bytes {
149        unsafe {
150            from_glib_full(ffi::gsk_render_node_serialize(
151                self.as_ref().to_glib_none().0,
152            ))
153        }
154    }
155
156    /// This function is equivalent to calling [`serialize()`][Self::serialize()]
157    /// followed by `file_set_contents()`.
158    ///
159    /// See those two functions for details on the arguments.
160    ///
161    /// It is mostly intended for use inside a debugger to quickly dump a render
162    /// node to a file for later inspection.
163    /// ## `filename`
164    /// the file to save it to
165    ///
166    /// # Returns
167    ///
168    /// true if saving was successful
169    #[doc(alias = "gsk_render_node_write_to_file")]
170    pub fn write_to_file(&self, filename: impl AsRef<std::path::Path>) -> Result<(), glib::Error> {
171        unsafe {
172            let mut error = std::ptr::null_mut();
173            let is_ok = ffi::gsk_render_node_write_to_file(
174                self.as_ref().to_glib_none().0,
175                filename.as_ref().to_glib_none().0,
176                &mut error,
177            );
178            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
179            if error.is_null() {
180                Ok(())
181            } else {
182                Err(from_glib_full(error))
183            }
184        }
185    }
186}