gdk4/

dmabuf_texture_builder.rs

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

use glib::{prelude::*, translate::*};

#[cfg(feature = "v4_16")]
use crate::ColorState;
use crate::{ffi, Display, DmabufTextureBuilder, Texture};

impl DmabufTextureBuilder {
    /// Sets the color state for the texture.
    ///
    /// By default, the colorstate is `NULL`. In that case, GTK will choose the
    /// correct colorstate based on the format.
    /// If you don't know what colorstates are, this is probably the right thing.
    /// ## `color_state`
    /// a [`ColorState`][crate::ColorState] or `NULL` to unset the colorstate.
    #[cfg(feature = "v4_16")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
    #[doc(alias = "gdk_dmabuf_texture_builder_set_color_state")]
    #[doc(alias = "color-state")]
    pub fn set_color_state(self, color_state: Option<&ColorState>) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_color_state(
                self.to_glib_none().0,
                color_state.to_glib_none().0,
            );
        }

        self
    }

    /// Sets the display that this texture builder is
    /// associated with.
    ///
    /// The display is used to determine the supported
    /// dma-buf formats.
    /// ## `display`
    /// the display
    #[doc(alias = "gdk_dmabuf_texture_builder_set_display")]
    #[doc(alias = "display")]
    pub fn set_display(self, display: &impl IsA<Display>) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_display(
                self.to_glib_none().0,
                display.as_ref().to_glib_none().0,
            );
        }

        self
    }

    // rustdoc-stripper-ignore-next
    /// # Safety
    ///
    /// The caller must ensure that `fd` says valid for at least as long as the texture, e.g. by
    /// using `build_with_release_func()` to get notified when `fd` is not used anymore.
    // rustdoc-stripper-ignore-next-stop
    /// Sets the file descriptor for a plane.
    /// ## `plane`
    /// the plane to set the fd for
    /// ## `fd`
    /// the file descriptor
    #[doc(alias = "gdk_dmabuf_texture_builder_set_fd")]
    pub unsafe fn set_fd(self, plane: u32, fd: std::os::fd::RawFd) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_fd(self.to_glib_none().0, plane, fd);
        }

        self
    }

    /// Gets the file descriptor for a plane.
    /// ## `plane`
    /// the plane to get the fd for
    ///
    /// # Returns
    ///
    /// the file descriptor
    #[doc(alias = "gdk_dmabuf_texture_builder_get_fd")]
    #[doc(alias = "get_fd")]
    pub fn fd(&self, plane: u32) -> Option<std::os::fd::BorrowedFd<'_>> {
        unsafe {
            let fd = ffi::gdk_dmabuf_texture_builder_get_fd(self.to_glib_none().0, plane);

            if fd == -1 {
                None
            } else {
                Some(std::os::fd::BorrowedFd::borrow_raw(fd))
            }
        }
    }

    /// Sets the format of the texture.
    ///
    /// The format is specified as a fourcc code.
    ///
    /// The format must be set before calling [`build()`][Self::build()].
    /// ## `fourcc`
    /// the texture's format or 0 to unset
    #[doc(alias = "gdk_dmabuf_texture_builder_set_fourcc")]
    #[doc(alias = "fourcc")]
    pub fn set_fourcc(self, fourcc: u32) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_fourcc(self.to_glib_none().0, fourcc);
        }

        self
    }

    /// Sets the height of the texture.
    ///
    /// The height must be set before calling [`build()`][Self::build()].
    /// ## `height`
    /// the texture's height or 0 to unset
    #[doc(alias = "gdk_dmabuf_texture_builder_set_height")]
    #[doc(alias = "height")]
    pub fn set_height(self, height: u32) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_height(self.to_glib_none().0, height);
        }

        self
    }

    /// Sets the modifier.
    /// ## `modifier`
    /// the modifier value
    #[doc(alias = "gdk_dmabuf_texture_builder_set_modifier")]
    #[doc(alias = "modifier")]
    pub fn set_modifier(self, modifier: u64) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_modifier(self.to_glib_none().0, modifier);
        }

        self
    }

    /// Sets the number of planes of the texture.
    /// ## `n_planes`
    /// the number of planes
    #[doc(alias = "gdk_dmabuf_texture_builder_set_n_planes")]
    #[doc(alias = "n-planes")]
    pub fn set_n_planes(self, n_planes: u32) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_n_planes(self.to_glib_none().0, n_planes);
        }

        self
    }

    /// Sets the offset for a plane.
    /// ## `plane`
    /// the plane to set the offset for
    /// ## `offset`
    /// the offset value
    #[doc(alias = "gdk_dmabuf_texture_builder_set_offset")]
    pub fn set_offset(self, plane: u32, offset: u32) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_offset(self.to_glib_none().0, plane, offset);
        }

        self
    }

    /// Sets whether the data is premultiplied.
    ///
    /// Unless otherwise specified, all formats including alpha channels are assumed
    /// to be premultiplied.
    /// ## `premultiplied`
    /// whether the data is premultiplied
    #[doc(alias = "gdk_dmabuf_texture_builder_set_premultiplied")]
    #[doc(alias = "premultiplied")]
    pub fn set_premultiplied(self, premultiplied: bool) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_premultiplied(
                self.to_glib_none().0,
                premultiplied.into_glib(),
            );
        }

        self
    }

    /// Sets the stride for a plane.
    ///
    /// The stride must be set for all planes before calling [`build()`][Self::build()].
    /// ## `plane`
    /// the plane to set the stride for
    /// ## `stride`
    /// the stride value
    #[doc(alias = "gdk_dmabuf_texture_builder_set_stride")]
    pub fn set_stride(self, plane: u32, stride: u32) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_stride(self.to_glib_none().0, plane, stride);
        }

        self
    }

    /// Sets the region to be updated by this texture. Together with
    /// [`update-texture`][struct@crate::DmabufTextureBuilder#update-texture] this describes an
    /// update of a previous texture.
    ///
    /// When rendering animations of large textures, it is possible that
    /// consecutive textures are only updating contents in parts of the texture.
    /// It is then possible to describe this update via these two properties,
    /// so that GTK can avoid rerendering parts that did not change.
    ///
    /// An example would be a screen recording where only the mouse pointer moves.
    /// ## `region`
    /// the region to update
    #[doc(alias = "gdk_dmabuf_texture_builder_set_update_region")]
    #[doc(alias = "update-region")]
    pub fn set_update_region(self, region: Option<&cairo::Region>) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_update_region(
                self.to_glib_none().0,
                mut_override(region.to_glib_none().0),
            );
        }

        self
    }

    /// Sets the texture to be updated by this texture. See
    /// [`set_update_region()`][Self::set_update_region()] for an explanation.
    /// ## `texture`
    /// the texture to update
    #[doc(alias = "gdk_dmabuf_texture_builder_set_update_texture")]
    #[doc(alias = "update-texture")]
    pub fn set_update_texture(self, texture: Option<&impl IsA<Texture>>) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_update_texture(
                self.to_glib_none().0,
                texture.map(|p| p.as_ref()).to_glib_none().0,
            );
        }

        self
    }

    /// Sets the width of the texture.
    ///
    /// The width must be set before calling [`build()`][Self::build()].
    /// ## `width`
    /// The texture's width or 0 to unset
    #[doc(alias = "gdk_dmabuf_texture_builder_set_width")]
    #[doc(alias = "width")]
    pub fn set_width(self, width: u32) -> Self {
        unsafe {
            ffi::gdk_dmabuf_texture_builder_set_width(self.to_glib_none().0, width);
        }

        self
    }

    /// Builds a new [`Texture`][crate::Texture] with the values set up in the builder.
    ///
    /// It is a programming error to call this function if any mandatory property has not been set.
    ///
    /// Not all formats defined in the `drm_fourcc.h` header are supported. You can use
    /// [`DisplayExt::dmabuf_formats()`][crate::prelude::DisplayExt::dmabuf_formats()] to get a list of supported formats. If the
    /// format is not supported by GTK, [`None`] will be returned and @error will be set.
    ///
    /// The `destroy` function gets called when the returned texture gets released.
    ///
    /// It is the responsibility of the caller to keep the file descriptors for the planes
    /// open until the created texture is no longer used, and close them afterwards (possibly
    /// using the @destroy notify).
    ///
    /// It is possible to call this function multiple times to create multiple textures,
    /// possibly with changing properties in between.
    ///
    /// # Returns
    ///
    /// a newly built [`Texture`][crate::Texture] or `NULL`
    ///   if the format is not supported
    #[doc(alias = "gdk_dmabuf_texture_builder_build")]
    #[must_use = "The builder must be built to be used"]
    #[allow(clippy::missing_safety_doc)]
    pub unsafe fn build(self) -> Result<Texture, glib::Error> {
        let mut error = std::ptr::null_mut();

        let result = ffi::gdk_dmabuf_texture_builder_build(
            self.to_glib_none().0,
            None,
            std::ptr::null_mut(),
            &mut error,
        );
        if error.is_null() {
            if result.is_null() {
                Err(glib::Error::new(
                    crate::DmabufError::UnsupportedFormat,
                    "Unsupported format",
                ))
            } else {
                Ok(from_glib_full(result))
            }
        } else {
            Err(from_glib_full(error))
        }
    }

    #[doc(alias = "gdk_dmabuf_texture_builder_build")]
    #[must_use = "The builder must be built to be used"]
    #[allow(clippy::missing_safety_doc)]
    pub unsafe fn build_with_release_func<F: FnOnce() + Send + 'static>(
        self,
        release_func: F,
    ) -> Result<Texture, glib::Error> {
        let mut error = std::ptr::null_mut();
        unsafe extern "C" fn destroy_closure<F: FnOnce() + Send + 'static>(
            func: glib::ffi::gpointer,
        ) {
            let released_func = Box::<F>::from_raw(func as *mut _);
            released_func();
        }
        let released_func = Box::new(release_func);
        let result = ffi::gdk_dmabuf_texture_builder_build(
            self.to_glib_none().0,
            Some(destroy_closure::<F>),
            Box::into_raw(released_func) as glib::ffi::gpointer,
            &mut error,
        );
        if error.is_null() {
            if result.is_null() {
                Err(glib::Error::new(
                    crate::DmabufError::UnsupportedFormat,
                    "Unsupported format",
                ))
            } else {
                Ok(from_glib_full(result))
            }
        } else {
            Err(from_glib_full(error))
        }
    }
}