gsk4/auto/renderer.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, RenderNode};
6use glib::{
7 prelude::*,
8 signal::{connect_raw, SignalHandlerId},
9 translate::*,
10};
11use std::boxed::Box as Box_;
12
13glib::wrapper! {
14 /// Renders a scene graph defined via a tree of [`RenderNode`][crate::RenderNode] instances.
15 ///
16 /// Typically you will use a [`Renderer`][crate::Renderer] instance to repeatedly call
17 /// [`GskRendererExt::render()`][crate::prelude::GskRendererExt::render()] to update the contents of its associated
18 /// [`gdk::Surface`][crate::gdk::Surface].
19 ///
20 /// It is necessary to realize a [`Renderer`][crate::Renderer] instance using
21 /// [`GskRendererExt::realize()`][crate::prelude::GskRendererExt::realize()] before calling [`GskRendererExt::render()`][crate::prelude::GskRendererExt::render()],
22 /// in order to create the appropriate windowing system resources needed
23 /// to render the scene.
24 ///
25 /// This is an Abstract Base Class, you cannot instantiate it.
26 ///
27 /// ## Properties
28 ///
29 ///
30 /// #### `realized`
31 /// Whether the renderer has been associated with a surface or draw context.
32 ///
33 /// Readable
34 ///
35 ///
36 /// #### `surface`
37 /// The surface associated with renderer.
38 ///
39 /// Readable
40 ///
41 /// # Implements
42 ///
43 /// [`GskRendererExt`][trait@crate::prelude::GskRendererExt]
44 #[doc(alias = "GskRenderer")]
45 pub struct Renderer(Object<ffi::GskRenderer, ffi::GskRendererClass>);
46
47 match fn {
48 type_ => || ffi::gsk_renderer_get_type(),
49 }
50}
51
52impl Renderer {
53 pub const NONE: Option<&'static Renderer> = None;
54
55 /// Creates an appropriate [`Renderer`][crate::Renderer] instance for the given surface.
56 ///
57 /// If the `GSK_RENDERER` environment variable is set, GSK will
58 /// try that renderer first, before trying the backend-specific
59 /// default. The ultimate fallback is the cairo renderer.
60 ///
61 /// The renderer will be realized before it is returned.
62 /// ## `surface`
63 /// a surface
64 ///
65 /// # Returns
66 ///
67 /// the realized renderer
68 #[doc(alias = "gsk_renderer_new_for_surface")]
69 #[doc(alias = "new_for_surface")]
70 pub fn for_surface(surface: &gdk::Surface) -> Option<Renderer> {
71 assert_initialized_main_thread!();
72 unsafe { from_glib_full(ffi::gsk_renderer_new_for_surface(surface.to_glib_none().0)) }
73 }
74}
75
76/// Trait containing all [`struct@Renderer`] methods.
77///
78/// # Implementors
79///
80/// [`BroadwayRenderer`][struct@crate::BroadwayRenderer], [`CairoRenderer`][struct@crate::CairoRenderer], [`GLRenderer`][struct@crate::GLRenderer], [`NglRenderer`][struct@crate::NglRenderer], [`Renderer`][struct@crate::Renderer], [`VulkanRenderer`][struct@crate::VulkanRenderer]
81pub trait GskRendererExt: IsA<Renderer> + 'static {
82 /// Retrieves the surface that the renderer is associated with.
83 ///
84 /// If the renderer has not been realized yet, `NULL` will be returned.
85 ///
86 /// # Returns
87 ///
88 /// the surface
89 #[doc(alias = "gsk_renderer_get_surface")]
90 #[doc(alias = "get_surface")]
91 fn surface(&self) -> Option<gdk::Surface> {
92 unsafe {
93 from_glib_none(ffi::gsk_renderer_get_surface(
94 self.as_ref().to_glib_none().0,
95 ))
96 }
97 }
98
99 /// Checks whether the renderer is realized or not.
100 ///
101 /// # Returns
102 ///
103 /// true if the renderer was realized, false otherwise
104 #[doc(alias = "gsk_renderer_is_realized")]
105 #[doc(alias = "realized")]
106 fn is_realized(&self) -> bool {
107 unsafe {
108 from_glib(ffi::gsk_renderer_is_realized(
109 self.as_ref().to_glib_none().0,
110 ))
111 }
112 }
113
114 /// Creates the resources needed by the renderer.
115 ///
116 /// Since GTK 4.6, the surface may be `NULL`, which allows using
117 /// renderers without having to create a surface. Since GTK 4.14,
118 /// it is recommended to use [`realize_for_display()`][Self::realize_for_display()]
119 /// for this case.
120 ///
121 /// Note that it is mandatory to call [`unrealize()`][Self::unrealize()]
122 /// before destroying the renderer.
123 /// ## `surface`
124 /// the surface that renderer will be used on
125 ///
126 /// # Returns
127 ///
128 /// whether the renderer was successfully realized
129 #[doc(alias = "gsk_renderer_realize")]
130 fn realize(&self, surface: Option<&gdk::Surface>) -> Result<(), glib::Error> {
131 unsafe {
132 let mut error = std::ptr::null_mut();
133 let is_ok = ffi::gsk_renderer_realize(
134 self.as_ref().to_glib_none().0,
135 surface.to_glib_none().0,
136 &mut error,
137 );
138 debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
139 if error.is_null() {
140 Ok(())
141 } else {
142 Err(from_glib_full(error))
143 }
144 }
145 }
146
147 /// Creates the resources needed by the renderer.
148 ///
149 /// Note that it is mandatory to call [`unrealize()`][Self::unrealize()]
150 /// before destroying the renderer.
151 /// ## `display`
152 /// the display that the renderer will be used on
153 ///
154 /// # Returns
155 ///
156 /// whether the renderer was successfully realized
157 #[cfg(feature = "v4_14")]
158 #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
159 #[doc(alias = "gsk_renderer_realize_for_display")]
160 fn realize_for_display(&self, display: &gdk::Display) -> Result<(), glib::Error> {
161 unsafe {
162 let mut error = std::ptr::null_mut();
163 let is_ok = ffi::gsk_renderer_realize_for_display(
164 self.as_ref().to_glib_none().0,
165 display.to_glib_none().0,
166 &mut error,
167 );
168 debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
169 if error.is_null() {
170 Ok(())
171 } else {
172 Err(from_glib_full(error))
173 }
174 }
175 }
176
177 /// Renders the scene graph, described by a tree of [`RenderNode`][crate::RenderNode] instances
178 /// to the renderer's surface, ensuring that the given region gets redrawn.
179 ///
180 /// If the renderer has no associated surface, this function does nothing.
181 ///
182 /// Renderers must ensure that changes of the contents given by the @root
183 /// node as well as the area given by @region are redrawn. They are however
184 /// free to not redraw any pixel outside of @region if they can guarantee that
185 /// it didn't change.
186 ///
187 /// The renderer will acquire a reference on the [`RenderNode`][crate::RenderNode] tree while
188 /// the rendering is in progress.
189 /// ## `root`
190 /// the render node to render
191 /// ## `region`
192 /// the [`cairo::Region`][crate::cairo::Region] that must be redrawn or `NULL`
193 /// for the whole surface
194 #[doc(alias = "gsk_renderer_render")]
195 fn render(&self, root: impl AsRef<RenderNode>, region: Option<&cairo::Region>) {
196 unsafe {
197 ffi::gsk_renderer_render(
198 self.as_ref().to_glib_none().0,
199 root.as_ref().to_glib_none().0,
200 region.to_glib_none().0,
201 );
202 }
203 }
204
205 /// Renders a scene graph, described by a tree of [`RenderNode`][crate::RenderNode] instances,
206 /// to a texture.
207 ///
208 /// The renderer will acquire a reference on the [`RenderNode`][crate::RenderNode] tree while
209 /// the rendering is in progress.
210 ///
211 /// If you want to apply any transformations to @root, you should put it into a
212 /// transform node and pass that node instead.
213 /// ## `root`
214 /// the render node to render
215 /// ## `viewport`
216 /// the section to draw or `NULL` to use @root's bounds
217 ///
218 /// # Returns
219 ///
220 /// a texture with the rendered contents of @root
221 #[doc(alias = "gsk_renderer_render_texture")]
222 fn render_texture(
223 &self,
224 root: impl AsRef<RenderNode>,
225 viewport: Option<&graphene::Rect>,
226 ) -> gdk::Texture {
227 unsafe {
228 from_glib_full(ffi::gsk_renderer_render_texture(
229 self.as_ref().to_glib_none().0,
230 root.as_ref().to_glib_none().0,
231 viewport.to_glib_none().0,
232 ))
233 }
234 }
235
236 /// Releases all the resources created by [`realize()`][Self::realize()].
237 #[doc(alias = "gsk_renderer_unrealize")]
238 fn unrealize(&self) {
239 unsafe {
240 ffi::gsk_renderer_unrealize(self.as_ref().to_glib_none().0);
241 }
242 }
243
244 #[doc(alias = "realized")]
245 fn connect_realized_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
246 unsafe extern "C" fn notify_realized_trampoline<P: IsA<Renderer>, F: Fn(&P) + 'static>(
247 this: *mut ffi::GskRenderer,
248 _param_spec: glib::ffi::gpointer,
249 f: glib::ffi::gpointer,
250 ) {
251 let f: &F = &*(f as *const F);
252 f(Renderer::from_glib_borrow(this).unsafe_cast_ref())
253 }
254 unsafe {
255 let f: Box_<F> = Box_::new(f);
256 connect_raw(
257 self.as_ptr() as *mut _,
258 c"notify::realized".as_ptr() as *const _,
259 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
260 notify_realized_trampoline::<Self, F> as *const (),
261 )),
262 Box_::into_raw(f),
263 )
264 }
265 }
266
267 #[doc(alias = "surface")]
268 fn connect_surface_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
269 unsafe extern "C" fn notify_surface_trampoline<P: IsA<Renderer>, F: Fn(&P) + 'static>(
270 this: *mut ffi::GskRenderer,
271 _param_spec: glib::ffi::gpointer,
272 f: glib::ffi::gpointer,
273 ) {
274 let f: &F = &*(f as *const F);
275 f(Renderer::from_glib_borrow(this).unsafe_cast_ref())
276 }
277 unsafe {
278 let f: Box_<F> = Box_::new(f);
279 connect_raw(
280 self.as_ptr() as *mut _,
281 c"notify::surface".as_ptr() as *const _,
282 Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
283 notify_surface_trampoline::<Self, F> as *const (),
284 )),
285 Box_::into_raw(f),
286 )
287 }
288 }
289}
290
291impl<O: IsA<Renderer>> GskRendererExt for O {}