gdk4/auto/

texture.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

#[cfg(feature = "v4_16")]
#[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
use crate::ColorState;
#[cfg(feature = "v4_10")]
#[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
use crate::MemoryFormat;
use crate::{ffi, Paintable};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// Refers to pixel data in various forms.
    ///
    /// It is primarily meant for pixel data that will not change over
    /// multiple frames, and will be used for a long time.
    ///
    /// There are various ways to create [`Texture`][crate::Texture] objects from a
    /// [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf], or from bytes stored in memory, a file, or a
    /// `Gio::Resource`.
    ///
    /// The ownership of the pixel data is transferred to the [`Texture`][crate::Texture]
    /// instance; you can only make a copy of it, via [`TextureExtManual::download()`][crate::prelude::TextureExtManual::download()].
    ///
    /// [`Texture`][crate::Texture] is an immutable object: That means you cannot change
    /// anything about it other than increasing the reference count via
    /// `GObject::Object::ref()`, and consequently, it is a threadsafe object.
    ///
    /// GDK provides a number of threadsafe texture loading functions:
    /// [`from_resource()`][Self::from_resource()],
    /// [`from_bytes()`][Self::from_bytes()],
    /// [`from_file()`][Self::from_file()],
    /// [`from_filename()`][Self::from_filename()],
    /// [`for_pixbuf()`][Self::for_pixbuf()]. Note that these are meant for loading
    /// icons and resources that are shipped with the toolkit or application. It
    /// is recommended that you use a dedicated image loading framework such as
    /// [glycin](https://lib.rs/crates/glycin), if you need to load untrusted image
    /// data.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `color-state`
    ///  The color state of the texture.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `height`
    ///  The height of the texture, in pixels.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `width`
    ///  The width of the texture, in pixels.
    ///
    /// Readable | Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`TextureExt`][trait@crate::prelude::TextureExt], [`PaintableExt`][trait@crate::prelude::PaintableExt], [`trait@gio::prelude::IconExt`], [`trait@gio::prelude::LoadableIconExt`], [`TextureExtManual`][trait@crate::prelude::TextureExtManual]
    #[doc(alias = "GdkTexture")]
    pub struct Texture(Object<ffi::GdkTexture, ffi::GdkTextureClass>) @implements Paintable, gio::Icon, gio::LoadableIcon;

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

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

    /// Creates a new texture object representing the [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf].
    ///
    /// This function is threadsafe, so that you can e.g. use GTask
    /// and `Gio::Task::run_in_thread()` to avoid blocking the main thread
    /// while loading a big image.
    /// ## `pixbuf`
    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf]
    ///
    /// # Returns
    ///
    /// a new [`Texture`][crate::Texture]
    #[doc(alias = "gdk_texture_new_for_pixbuf")]
    #[doc(alias = "new_for_pixbuf")]
    pub fn for_pixbuf(pixbuf: &gdk_pixbuf::Pixbuf) -> Texture {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gdk_texture_new_for_pixbuf(pixbuf.to_glib_none().0)) }
    }

    /// Creates a new texture by loading an image from memory,
    ///
    /// The file format is detected automatically. The supported formats
    /// are PNG, JPEG and TIFF, though more formats might be available.
    ///
    /// If [`None`] is returned, then @error will be set.
    ///
    /// This function is threadsafe, so that you can e.g. use GTask
    /// and `Gio::Task::run_in_thread()` to avoid blocking the main thread
    /// while loading a big image.
    /// ## `bytes`
    /// a `GBytes` containing the data to load
    ///
    /// # Returns
    ///
    /// A newly-created [`Texture`][crate::Texture]
    #[cfg(feature = "v4_6")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
    #[doc(alias = "gdk_texture_new_from_bytes")]
    #[doc(alias = "new_from_bytes")]
    pub fn from_bytes(bytes: &glib::Bytes) -> Result<Texture, glib::Error> {
        assert_initialized_main_thread!();
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gdk_texture_new_from_bytes(bytes.to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Creates a new texture by loading an image from a file.
    ///
    /// The file format is detected automatically. The supported formats
    /// are PNG, JPEG and TIFF, though more formats might be available.
    ///
    /// If [`None`] is returned, then @error will be set.
    ///
    /// This function is threadsafe, so that you can e.g. use GTask
    /// and `Gio::Task::run_in_thread()` to avoid blocking the main thread
    /// while loading a big image.
    /// ## `file`
    /// `GFile` to load
    ///
    /// # Returns
    ///
    /// A newly-created [`Texture`][crate::Texture]
    #[doc(alias = "gdk_texture_new_from_file")]
    #[doc(alias = "new_from_file")]
    pub fn from_file(file: &impl IsA<gio::File>) -> Result<Texture, glib::Error> {
        assert_initialized_main_thread!();
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::gdk_texture_new_from_file(file.as_ref().to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Creates a new texture by loading an image from a file.
    ///
    /// The file format is detected automatically. The supported formats
    /// are PNG, JPEG and TIFF, though more formats might be available.
    ///
    /// If [`None`] is returned, then @error will be set.
    ///
    /// This function is threadsafe, so that you can e.g. use GTask
    /// and `Gio::Task::run_in_thread()` to avoid blocking the main thread
    /// while loading a big image.
    /// ## `path`
    /// the filename to load
    ///
    /// # Returns
    ///
    /// A newly-created [`Texture`][crate::Texture]
    #[cfg(feature = "v4_6")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
    #[doc(alias = "gdk_texture_new_from_filename")]
    #[doc(alias = "new_from_filename")]
    pub fn from_filename(path: impl AsRef<std::path::Path>) -> Result<Texture, glib::Error> {
        assert_initialized_main_thread!();
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret =
                ffi::gdk_texture_new_from_filename(path.as_ref().to_glib_none().0, &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Creates a new texture by loading an image from a resource.
    ///
    /// The file format is detected automatically. The supported formats
    /// are PNG and JPEG, though more formats might be available.
    ///
    /// It is a fatal error if @resource_path does not specify a valid
    /// image resource and the program will abort if that happens.
    /// If you are unsure about the validity of a resource, use
    /// [`from_file()`][Self::from_file()] to load it.
    ///
    /// This function is threadsafe, so that you can e.g. use GTask
    /// and `Gio::Task::run_in_thread()` to avoid blocking the main thread
    /// while loading a big image.
    /// ## `resource_path`
    /// the path of the resource file
    ///
    /// # Returns
    ///
    /// A newly-created [`Texture`][crate::Texture]
    #[doc(alias = "gdk_texture_new_from_resource")]
    #[doc(alias = "new_from_resource")]
    pub fn from_resource(resource_path: &str) -> Texture {
        assert_initialized_main_thread!();
        unsafe {
            from_glib_full(ffi::gdk_texture_new_from_resource(
                resource_path.to_glib_none().0,
            ))
        }
    }
}

unsafe impl Send for Texture {}
unsafe impl Sync for Texture {}

/// Trait containing all [`struct@Texture`] methods.
///
/// # Implementors
///
/// [`DmabufTexture`][struct@crate::DmabufTexture], [`GLTexture`][struct@crate::GLTexture], [`MemoryTexture`][struct@crate::MemoryTexture], [`Texture`][struct@crate::Texture]
pub trait TextureExt: IsA<Texture> + 'static {
    /// Returns the color state associated with the texture.
    ///
    /// # Returns
    ///
    /// the color state of the [`Texture`][crate::Texture]
    #[cfg(feature = "v4_16")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
    #[doc(alias = "gdk_texture_get_color_state")]
    #[doc(alias = "get_color_state")]
    #[doc(alias = "color-state")]
    fn color_state(&self) -> ColorState {
        unsafe {
            from_glib_none(ffi::gdk_texture_get_color_state(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the memory format most closely associated with the data of
    /// the texture.
    ///
    /// Note that it may not be an exact match for texture data
    /// stored on the GPU or with compression.
    ///
    /// The format can give an indication about the bit depth and opacity
    /// of the texture and is useful to determine the best format for
    /// downloading the texture.
    ///
    /// # Returns
    ///
    /// the preferred format for the texture's data
    #[cfg(feature = "v4_10")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
    #[doc(alias = "gdk_texture_get_format")]
    #[doc(alias = "get_format")]
    fn format(&self) -> MemoryFormat {
        unsafe { from_glib(ffi::gdk_texture_get_format(self.as_ref().to_glib_none().0)) }
    }

    /// Returns the height of the @self, in pixels.
    ///
    /// # Returns
    ///
    /// the height of the [`Texture`][crate::Texture]
    #[doc(alias = "gdk_texture_get_height")]
    #[doc(alias = "get_height")]
    fn height(&self) -> i32 {
        unsafe { ffi::gdk_texture_get_height(self.as_ref().to_glib_none().0) }
    }

    /// Returns the width of @self, in pixels.
    ///
    /// # Returns
    ///
    /// the width of the [`Texture`][crate::Texture]
    #[doc(alias = "gdk_texture_get_width")]
    #[doc(alias = "get_width")]
    fn width(&self) -> i32 {
        unsafe { ffi::gdk_texture_get_width(self.as_ref().to_glib_none().0) }
    }

    /// Store the given @self to the @filename as a PNG file.
    ///
    /// This is a utility function intended for debugging and testing.
    /// If you want more control over formats, proper error handling or
    /// want to store to a [`gio::File`][crate::gio::File] or other location, you might want to
    /// use [`save_to_png_bytes()`][Self::save_to_png_bytes()] or look into the
    /// gdk-pixbuf library.
    /// ## `filename`
    /// the filename to store to
    ///
    /// # Returns
    ///
    /// [`true`] if saving succeeded, [`false`] on failure.
    #[doc(alias = "gdk_texture_save_to_png")]
    fn save_to_png(
        &self,
        filename: impl AsRef<std::path::Path>,
    ) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gdk_texture_save_to_png(
                    self.as_ref().to_glib_none().0,
                    filename.as_ref().to_glib_none().0
                ),
                "Failed to save the texture as png"
            )
        }
    }

    /// Store the given @self in memory as a PNG file.
    ///
    /// Use [`Texture::from_bytes()`][crate::Texture::from_bytes()] to read it back.
    ///
    /// If you want to serialize a texture, this is a convenient and
    /// portable way to do that.
    ///
    /// If you need more control over the generated image, such as
    /// attaching metadata, you should look into an image handling
    /// library such as the gdk-pixbuf library.
    ///
    /// If you are dealing with high dynamic range float data, you
    /// might also want to consider [`save_to_tiff_bytes()`][Self::save_to_tiff_bytes()]
    /// instead.
    ///
    /// # Returns
    ///
    /// a newly allocated `GBytes` containing PNG data
    #[cfg(feature = "v4_6")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
    #[doc(alias = "gdk_texture_save_to_png_bytes")]
    fn save_to_png_bytes(&self) -> glib::Bytes {
        unsafe {
            from_glib_full(ffi::gdk_texture_save_to_png_bytes(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Store the given @self to the @filename as a TIFF file.
    ///
    /// GTK will attempt to store data without loss.
    /// ## `filename`
    /// the filename to store to
    ///
    /// # Returns
    ///
    /// [`true`] if saving succeeded, [`false`] on failure.
    #[cfg(feature = "v4_6")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
    #[doc(alias = "gdk_texture_save_to_tiff")]
    fn save_to_tiff(
        &self,
        filename: impl AsRef<std::path::Path>,
    ) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gdk_texture_save_to_tiff(
                    self.as_ref().to_glib_none().0,
                    filename.as_ref().to_glib_none().0
                ),
                "Failed to save the texture as tiff"
            )
        }
    }

    /// Store the given @self in memory as a TIFF file.
    ///
    /// Use [`Texture::from_bytes()`][crate::Texture::from_bytes()] to read it back.
    ///
    /// This function is intended to store a representation of the
    /// texture's data that is as accurate as possible. This is
    /// particularly relevant when working with high dynamic range
    /// images and floating-point texture data.
    ///
    /// If that is not your concern and you are interested in a
    /// smaller size and a more portable format, you might want to
    /// use [`save_to_png_bytes()`][Self::save_to_png_bytes()].
    ///
    /// # Returns
    ///
    /// a newly allocated `GBytes` containing TIFF data
    #[cfg(feature = "v4_6")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
    #[doc(alias = "gdk_texture_save_to_tiff_bytes")]
    fn save_to_tiff_bytes(&self) -> glib::Bytes {
        unsafe {
            from_glib_full(ffi::gdk_texture_save_to_tiff_bytes(
                self.as_ref().to_glib_none().0,
            ))
        }
    }
}

impl<O: IsA<Texture>> TextureExt for O {}