gsk4/auto/

renderer.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, RenderNode};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// A class that renders a scene graph defined via a tree of
    /// [`RenderNode`][crate::RenderNode] instances.
    ///
    /// Typically you will use a [`Renderer`][crate::Renderer] instance to repeatedly call
    /// [`GskRendererExt::render()`][crate::prelude::GskRendererExt::render()] to update the contents of its associated
    /// [`gdk::Surface`][crate::gdk::Surface].
    ///
    /// It is necessary to realize a [`Renderer`][crate::Renderer] instance using
    /// [`GskRendererExt::realize()`][crate::prelude::GskRendererExt::realize()] before calling [`GskRendererExt::render()`][crate::prelude::GskRendererExt::render()],
    /// in order to create the appropriate windowing system resources needed
    /// to render the scene.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `realized`
    ///  Whether the renderer has been associated with a surface or draw context.
    ///
    /// Readable
    ///
    ///
    /// #### `surface`
    ///  The surface associated with renderer.
    ///
    /// Readable
    ///
    /// # Implements
    ///
    /// [`GskRendererExt`][trait@crate::prelude::GskRendererExt]
    #[doc(alias = "GskRenderer")]
    pub struct Renderer(Object<ffi::GskRenderer, ffi::GskRendererClass>);

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

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

    /// Creates an appropriate [`Renderer`][crate::Renderer] instance for the given surface.
    ///
    /// If the `GSK_RENDERER` environment variable is set, GSK will
    /// try that renderer first, before trying the backend-specific
    /// default. The ultimate fallback is the cairo renderer.
    ///
    /// The renderer will be realized before it is returned.
    /// ## `surface`
    /// a surface
    ///
    /// # Returns
    ///
    /// the realized renderer
    #[doc(alias = "gsk_renderer_new_for_surface")]
    #[doc(alias = "new_for_surface")]
    pub fn for_surface(surface: &gdk::Surface) -> Option<Renderer> {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gsk_renderer_new_for_surface(surface.to_glib_none().0)) }
    }
}

/// Trait containing all [`struct@Renderer`] methods.
///
/// # Implementors
///
/// [`BroadwayRenderer`][struct@crate::BroadwayRenderer], [`CairoRenderer`][struct@crate::CairoRenderer], [`GLRenderer`][struct@crate::GLRenderer], [`NglRenderer`][struct@crate::NglRenderer], [`Renderer`][struct@crate::Renderer], [`VulkanRenderer`][struct@crate::VulkanRenderer]
pub trait GskRendererExt: IsA<Renderer> + 'static {
    /// Retrieves the surface that the renderer is associated with.
    ///
    /// If the renderer has not been realized yet, `NULL` will be returned.
    ///
    /// # Returns
    ///
    /// the surface
    #[doc(alias = "gsk_renderer_get_surface")]
    #[doc(alias = "get_surface")]
    fn surface(&self) -> Option<gdk::Surface> {
        unsafe {
            from_glib_none(ffi::gsk_renderer_get_surface(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Checks whether the renderer is realized or not.
    ///
    /// # Returns
    ///
    /// true if the renderer was realized, false otherwise
    #[doc(alias = "gsk_renderer_is_realized")]
    #[doc(alias = "realized")]
    fn is_realized(&self) -> bool {
        unsafe {
            from_glib(ffi::gsk_renderer_is_realized(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Creates the resources needed by the renderer.
    ///
    /// Since GTK 4.6, the surface may be `NULL`, which allows using
    /// renderers without having to create a surface. Since GTK 4.14,
    /// it is recommended to use [`realize_for_display()`][Self::realize_for_display()]
    /// for this case.
    ///
    /// Note that it is mandatory to call [`unrealize()`][Self::unrealize()]
    /// before destroying the renderer.
    /// ## `surface`
    /// the surface that renderer will be used on
    ///
    /// # Returns
    ///
    /// whether the renderer was successfully realized
    #[doc(alias = "gsk_renderer_realize")]
    fn realize(&self, surface: Option<&gdk::Surface>) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::gsk_renderer_realize(
                self.as_ref().to_glib_none().0,
                surface.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))
            }
        }
    }

    /// Creates the resources needed by the renderer.
    ///
    /// Note that it is mandatory to call [`unrealize()`][Self::unrealize()]
    /// before destroying the renderer.
    /// ## `display`
    /// the display that the renderer will be used on
    ///
    /// # Returns
    ///
    /// whether the renderer was successfully realized
    #[cfg(feature = "v4_14")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
    #[doc(alias = "gsk_renderer_realize_for_display")]
    fn realize_for_display(&self, display: &gdk::Display) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::gsk_renderer_realize_for_display(
                self.as_ref().to_glib_none().0,
                display.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))
            }
        }
    }

    /// Renders the scene graph, described by a tree of [`RenderNode`][crate::RenderNode] instances
    /// to the renderer's surface, ensuring that the given region gets redrawn.
    ///
    /// If the renderer has no associated surface, this function does nothing.
    ///
    /// Renderers must ensure that changes of the contents given by the @root
    /// node as well as the area given by @region are redrawn. They are however
    /// free to not redraw any pixel outside of @region if they can guarantee that
    /// it didn't change.
    ///
    /// The renderer will acquire a reference on the [`RenderNode`][crate::RenderNode] tree while
    /// the rendering is in progress.
    /// ## `root`
    /// the render node to render
    /// ## `region`
    /// the [`cairo::Region`][crate::cairo::Region] that must be redrawn or `NULL`
    ///   for the whole surface
    #[doc(alias = "gsk_renderer_render")]
    fn render(&self, root: impl AsRef<RenderNode>, region: Option<&cairo::Region>) {
        unsafe {
            ffi::gsk_renderer_render(
                self.as_ref().to_glib_none().0,
                root.as_ref().to_glib_none().0,
                region.to_glib_none().0,
            );
        }
    }

    /// Renders a scene graph, described by a tree of [`RenderNode`][crate::RenderNode] instances,
    /// to a texture.
    ///
    /// The renderer will acquire a reference on the [`RenderNode`][crate::RenderNode] tree while
    /// the rendering is in progress.
    ///
    /// If you want to apply any transformations to @root, you should put it into a
    /// transform node and pass that node instead.
    /// ## `root`
    /// the render node to render
    /// ## `viewport`
    /// the section to draw or `NULL` to use @root's bounds
    ///
    /// # Returns
    ///
    /// a texture with the rendered contents of @root
    #[doc(alias = "gsk_renderer_render_texture")]
    fn render_texture(
        &self,
        root: impl AsRef<RenderNode>,
        viewport: Option<&graphene::Rect>,
    ) -> gdk::Texture {
        unsafe {
            from_glib_full(ffi::gsk_renderer_render_texture(
                self.as_ref().to_glib_none().0,
                root.as_ref().to_glib_none().0,
                viewport.to_glib_none().0,
            ))
        }
    }

    /// Releases all the resources created by [`realize()`][Self::realize()].
    #[doc(alias = "gsk_renderer_unrealize")]
    fn unrealize(&self) {
        unsafe {
            ffi::gsk_renderer_unrealize(self.as_ref().to_glib_none().0);
        }
    }

    #[doc(alias = "realized")]
    fn connect_realized_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_realized_trampoline<P: IsA<Renderer>, F: Fn(&P) + 'static>(
            this: *mut ffi::GskRenderer,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Renderer::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::realized".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_realized_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "surface")]
    fn connect_surface_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_surface_trampoline<P: IsA<Renderer>, F: Fn(&P) + 'static>(
            this: *mut ffi::GskRenderer,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(Renderer::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::surface".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_surface_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<Renderer>> GskRendererExt for O {}