gdk4/auto/
texture.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#![allow(deprecated)]
5
6#[cfg(feature = "v4_16")]
7#[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
8use crate::ColorState;
9#[cfg(feature = "v4_10")]
10#[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
11use crate::MemoryFormat;
12use crate::{ffi, Paintable};
13use glib::{prelude::*, translate::*};
14
15glib::wrapper! {
16    /// Refers to pixel data in various forms.
17    ///
18    /// It is primarily meant for pixel data that will not change over
19    /// multiple frames, and will be used for a long time.
20    ///
21    /// There are various ways to create [`Texture`][crate::Texture] objects from a
22    /// [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf], or from bytes stored in memory, a file, or a
23    /// `Gio::Resource`.
24    ///
25    /// The ownership of the pixel data is transferred to the [`Texture`][crate::Texture]
26    /// instance; you can only make a copy of it, via [`TextureExtManual::download()`][crate::prelude::TextureExtManual::download()].
27    ///
28    /// [`Texture`][crate::Texture] is an immutable object: That means you cannot change
29    /// anything about it other than increasing the reference count via
30    /// `GObject::Object::ref()`, and consequently, it is a threadsafe object.
31    ///
32    /// GDK provides a number of threadsafe texture loading functions:
33    /// [`from_resource()`][Self::from_resource()],
34    /// [`from_bytes()`][Self::from_bytes()],
35    /// [`from_file()`][Self::from_file()],
36    /// [`from_filename()`][Self::from_filename()],
37    /// [`for_pixbuf()`][Self::for_pixbuf()]. Note that these are meant for loading
38    /// icons and resources that are shipped with the toolkit or application. It
39    /// is recommended that you use a dedicated image loading framework such as
40    /// [glycin](https://lib.rs/crates/glycin), if you need to load untrusted image
41    /// data.
42    ///
43    /// This is an Abstract Base Class, you cannot instantiate it.
44    ///
45    /// ## Properties
46    ///
47    ///
48    /// #### `color-state`
49    ///  The color state of the texture.
50    ///
51    /// Readable | Writeable | Construct Only
52    ///
53    ///
54    /// #### `height`
55    ///  The height of the texture, in pixels.
56    ///
57    /// Readable | Writeable | Construct Only
58    ///
59    ///
60    /// #### `width`
61    ///  The width of the texture, in pixels.
62    ///
63    /// Readable | Writeable | Construct Only
64    ///
65    /// # Implements
66    ///
67    /// [`TextureExt`][trait@crate::prelude::TextureExt], [`PaintableExt`][trait@crate::prelude::PaintableExt], [`trait@gio::prelude::IconExt`], [`trait@gio::prelude::LoadableIconExt`], [`TextureExtManual`][trait@crate::prelude::TextureExtManual]
68    #[doc(alias = "GdkTexture")]
69    pub struct Texture(Object<ffi::GdkTexture, ffi::GdkTextureClass>) @implements Paintable, gio::Icon, gio::LoadableIcon;
70
71    match fn {
72        type_ => || ffi::gdk_texture_get_type(),
73    }
74}
75
76impl Texture {
77    pub const NONE: Option<&'static Texture> = None;
78
79    /// Creates a new texture object representing the [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf].
80    ///
81    /// This function is threadsafe, so that you can e.g. use GTask
82    /// and `Gio::Task::run_in_thread()` to avoid blocking the main
83    /// thread while loading a big image.
84    ///
85    /// # Deprecated since 4.20
86    ///
87    /// Use e.g. libglycin, which can load many image
88    ///   formats into a [`Texture`][crate::Texture]
89    /// ## `pixbuf`
90    /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf]
91    ///
92    /// # Returns
93    ///
94    /// a new [`Texture`][crate::Texture]
95    #[cfg_attr(feature = "v4_20", deprecated = "Since 4.20")]
96    #[allow(deprecated)]
97    #[doc(alias = "gdk_texture_new_for_pixbuf")]
98    #[doc(alias = "new_for_pixbuf")]
99    pub fn for_pixbuf(pixbuf: &gdk_pixbuf::Pixbuf) -> Texture {
100        assert_initialized_main_thread!();
101        unsafe { from_glib_full(ffi::gdk_texture_new_for_pixbuf(pixbuf.to_glib_none().0)) }
102    }
103
104    /// Creates a new texture by loading an image from memory,
105    ///
106    /// The file format is detected automatically. The supported formats
107    /// are PNG, JPEG and TIFF, though more formats might be available.
108    ///
109    /// If `NULL` is returned, then @error will be set.
110    ///
111    /// This function is threadsafe, so that you can e.g. use GTask
112    /// and `Gio::Task::run_in_thread()` to avoid blocking the main thread
113    /// while loading a big image.
114    ///
115    /// ::: warning
116    ///     Note that this function should not be used with untrusted data.
117    ///     Use a proper image loading framework such as libglycin, which can
118    ///     load many image formats into a [`Texture`][crate::Texture].
119    /// ## `bytes`
120    /// a `GBytes` containing the data to load
121    ///
122    /// # Returns
123    ///
124    /// A newly-created [`Texture`][crate::Texture]
125    #[cfg(feature = "v4_6")]
126    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
127    #[doc(alias = "gdk_texture_new_from_bytes")]
128    #[doc(alias = "new_from_bytes")]
129    pub fn from_bytes(bytes: &glib::Bytes) -> Result<Texture, glib::Error> {
130        assert_initialized_main_thread!();
131        unsafe {
132            let mut error = std::ptr::null_mut();
133            let ret = ffi::gdk_texture_new_from_bytes(bytes.to_glib_none().0, &mut error);
134            if error.is_null() {
135                Ok(from_glib_full(ret))
136            } else {
137                Err(from_glib_full(error))
138            }
139        }
140    }
141
142    /// Creates a new texture by loading an image from a file.
143    ///
144    /// The file format is detected automatically. The supported formats
145    /// are PNG, JPEG and TIFF, though more formats might be available.
146    ///
147    /// If `NULL` is returned, then @error will be set.
148    ///
149    /// This function is threadsafe, so that you can e.g. use GTask
150    /// and `Gio::Task::run_in_thread()` to avoid blocking the main thread
151    /// while loading a big image.
152    ///
153    /// ::: warning
154    ///     Note that this function should not be used with untrusted data.
155    ///     Use a proper image loading framework such as libglycin, which can
156    ///     load many image formats into a [`Texture`][crate::Texture].
157    /// ## `file`
158    /// `GFile` to load
159    ///
160    /// # Returns
161    ///
162    /// A newly-created [`Texture`][crate::Texture]
163    #[doc(alias = "gdk_texture_new_from_file")]
164    #[doc(alias = "new_from_file")]
165    pub fn from_file(file: &impl IsA<gio::File>) -> Result<Texture, glib::Error> {
166        assert_initialized_main_thread!();
167        unsafe {
168            let mut error = std::ptr::null_mut();
169            let ret = ffi::gdk_texture_new_from_file(file.as_ref().to_glib_none().0, &mut error);
170            if error.is_null() {
171                Ok(from_glib_full(ret))
172            } else {
173                Err(from_glib_full(error))
174            }
175        }
176    }
177
178    /// Creates a new texture by loading an image from a file.
179    ///
180    /// The file format is detected automatically. The supported formats
181    /// are PNG, JPEG and TIFF, though more formats might be available.
182    ///
183    /// If `NULL` is returned, then @error will be set.
184    ///
185    /// This function is threadsafe, so that you can e.g. use GTask
186    /// and `Gio::Task::run_in_thread()` to avoid blocking the main thread
187    /// while loading a big image.
188    ///
189    /// ::: warning
190    ///     Note that this function should not be used with untrusted data.
191    ///     Use a proper image loading framework such as libglycin, which can
192    ///     load many image formats into a [`Texture`][crate::Texture].
193    /// ## `path`
194    /// the filename to load
195    ///
196    /// # Returns
197    ///
198    /// A newly-created [`Texture`][crate::Texture]
199    #[cfg(feature = "v4_6")]
200    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
201    #[doc(alias = "gdk_texture_new_from_filename")]
202    #[doc(alias = "new_from_filename")]
203    pub fn from_filename(path: impl AsRef<std::path::Path>) -> Result<Texture, glib::Error> {
204        assert_initialized_main_thread!();
205        unsafe {
206            let mut error = std::ptr::null_mut();
207            let ret =
208                ffi::gdk_texture_new_from_filename(path.as_ref().to_glib_none().0, &mut error);
209            if error.is_null() {
210                Ok(from_glib_full(ret))
211            } else {
212                Err(from_glib_full(error))
213            }
214        }
215    }
216
217    /// Creates a new texture by loading an image from a resource.
218    ///
219    /// The file format is detected automatically. The supported formats
220    /// are PNG, JPEG and TIFF, though more formats might be available.
221    ///
222    /// It is a fatal error if @resource_path does not specify a valid
223    /// image resource and the program will abort if that happens.
224    /// If you are unsure about the validity of a resource, use
225    /// [`from_file()`][Self::from_file()] to load it.
226    ///
227    /// This function is threadsafe, so that you can e.g. use GTask
228    /// and `Gio::Task::run_in_thread()` to avoid blocking the main thread
229    /// while loading a big image.
230    /// ## `resource_path`
231    /// the path of the resource file
232    ///
233    /// # Returns
234    ///
235    /// A newly-created [`Texture`][crate::Texture]
236    #[doc(alias = "gdk_texture_new_from_resource")]
237    #[doc(alias = "new_from_resource")]
238    pub fn from_resource(resource_path: &str) -> Texture {
239        assert_initialized_main_thread!();
240        unsafe {
241            from_glib_full(ffi::gdk_texture_new_from_resource(
242                resource_path.to_glib_none().0,
243            ))
244        }
245    }
246}
247
248unsafe impl Send for Texture {}
249unsafe impl Sync for Texture {}
250
251/// Trait containing all [`struct@Texture`] methods.
252///
253/// # Implementors
254///
255/// [`DmabufTexture`][struct@crate::DmabufTexture], [`GLTexture`][struct@crate::GLTexture], [`MemoryTexture`][struct@crate::MemoryTexture], [`Texture`][struct@crate::Texture]
256pub trait TextureExt: IsA<Texture> + 'static {
257    /// Returns the color state associated with the texture.
258    ///
259    /// # Returns
260    ///
261    /// the color state of the [`Texture`][crate::Texture]
262    #[cfg(feature = "v4_16")]
263    #[cfg_attr(docsrs, doc(cfg(feature = "v4_16")))]
264    #[doc(alias = "gdk_texture_get_color_state")]
265    #[doc(alias = "get_color_state")]
266    #[doc(alias = "color-state")]
267    fn color_state(&self) -> ColorState {
268        unsafe {
269            from_glib_none(ffi::gdk_texture_get_color_state(
270                self.as_ref().to_glib_none().0,
271            ))
272        }
273    }
274
275    /// Gets the memory format most closely associated with the data of
276    /// the texture.
277    ///
278    /// Note that it may not be an exact match for texture data
279    /// stored on the GPU or with compression.
280    ///
281    /// The format can give an indication about the bit depth and opacity
282    /// of the texture and is useful to determine the best format for
283    /// downloading the texture.
284    ///
285    /// # Returns
286    ///
287    /// the preferred format for the texture's data
288    #[cfg(feature = "v4_10")]
289    #[cfg_attr(docsrs, doc(cfg(feature = "v4_10")))]
290    #[doc(alias = "gdk_texture_get_format")]
291    #[doc(alias = "get_format")]
292    fn format(&self) -> MemoryFormat {
293        unsafe { from_glib(ffi::gdk_texture_get_format(self.as_ref().to_glib_none().0)) }
294    }
295
296    /// Returns the height of the @self, in pixels.
297    ///
298    /// # Returns
299    ///
300    /// the height of the [`Texture`][crate::Texture]
301    #[doc(alias = "gdk_texture_get_height")]
302    #[doc(alias = "get_height")]
303    fn height(&self) -> i32 {
304        unsafe { ffi::gdk_texture_get_height(self.as_ref().to_glib_none().0) }
305    }
306
307    /// Returns the width of @self, in pixels.
308    ///
309    /// # Returns
310    ///
311    /// the width of the [`Texture`][crate::Texture]
312    #[doc(alias = "gdk_texture_get_width")]
313    #[doc(alias = "get_width")]
314    fn width(&self) -> i32 {
315        unsafe { ffi::gdk_texture_get_width(self.as_ref().to_glib_none().0) }
316    }
317
318    /// Store the given @self to the @filename as a PNG file.
319    ///
320    /// This is a utility function intended for debugging and testing.
321    /// If you want more control over formats, proper error handling or
322    /// want to store to a [`gio::File`][crate::gio::File] or other location, you might
323    /// want to use [`save_to_png_bytes()`][Self::save_to_png_bytes()] or look into
324    /// the libglycin library.
325    /// ## `filename`
326    /// the filename to store to
327    ///
328    /// # Returns
329    ///
330    /// [`true`] if saving succeeded, [`false`] on failure.
331    #[doc(alias = "gdk_texture_save_to_png")]
332    fn save_to_png(
333        &self,
334        filename: impl AsRef<std::path::Path>,
335    ) -> Result<(), glib::error::BoolError> {
336        unsafe {
337            glib::result_from_gboolean!(
338                ffi::gdk_texture_save_to_png(
339                    self.as_ref().to_glib_none().0,
340                    filename.as_ref().to_glib_none().0
341                ),
342                "Failed to save the texture as png"
343            )
344        }
345    }
346
347    /// Store the given @self in memory as a PNG file.
348    ///
349    /// Use [`Texture::from_bytes()`][crate::Texture::from_bytes()] to read it back.
350    ///
351    /// If you want to serialize a texture, this is a convenient and
352    /// portable way to do that.
353    ///
354    /// If you need more control over the generated image, such as
355    /// attaching metadata, you should look into an image handling
356    /// library such as the libglycin library.
357    ///
358    /// If you are dealing with high dynamic range float data, you
359    /// might also want to consider [`save_to_tiff_bytes()`][Self::save_to_tiff_bytes()]
360    /// instead.
361    ///
362    /// # Returns
363    ///
364    /// a newly allocated `GBytes` containing PNG data
365    #[cfg(feature = "v4_6")]
366    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
367    #[doc(alias = "gdk_texture_save_to_png_bytes")]
368    fn save_to_png_bytes(&self) -> glib::Bytes {
369        unsafe {
370            from_glib_full(ffi::gdk_texture_save_to_png_bytes(
371                self.as_ref().to_glib_none().0,
372            ))
373        }
374    }
375
376    /// Store the given @self to the @filename as a TIFF file.
377    ///
378    /// GTK will attempt to store data without loss.
379    /// ## `filename`
380    /// the filename to store to
381    ///
382    /// # Returns
383    ///
384    /// [`true`] if saving succeeded, [`false`] on failure.
385    #[cfg(feature = "v4_6")]
386    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
387    #[doc(alias = "gdk_texture_save_to_tiff")]
388    fn save_to_tiff(
389        &self,
390        filename: impl AsRef<std::path::Path>,
391    ) -> Result<(), glib::error::BoolError> {
392        unsafe {
393            glib::result_from_gboolean!(
394                ffi::gdk_texture_save_to_tiff(
395                    self.as_ref().to_glib_none().0,
396                    filename.as_ref().to_glib_none().0
397                ),
398                "Failed to save the texture as tiff"
399            )
400        }
401    }
402
403    /// Store the given @self in memory as a TIFF file.
404    ///
405    /// Use [`Texture::from_bytes()`][crate::Texture::from_bytes()] to read it back.
406    ///
407    /// This function is intended to store a representation of the
408    /// texture's data that is as accurate as possible. This is
409    /// particularly relevant when working with high dynamic range
410    /// images and floating-point texture data.
411    ///
412    /// If that is not your concern and you are interested in a
413    /// smaller size and a more portable format, you might want to
414    /// use [`save_to_png_bytes()`][Self::save_to_png_bytes()].
415    ///
416    /// # Returns
417    ///
418    /// a newly allocated `GBytes` containing TIFF data
419    #[cfg(feature = "v4_6")]
420    #[cfg_attr(docsrs, doc(cfg(feature = "v4_6")))]
421    #[doc(alias = "gdk_texture_save_to_tiff_bytes")]
422    fn save_to_tiff_bytes(&self) -> glib::Bytes {
423        unsafe {
424            from_glib_full(ffi::gdk_texture_save_to_tiff_bytes(
425                self.as_ref().to_glib_none().0,
426            ))
427        }
428    }
429}
430
431impl<O: IsA<Texture>> TextureExt for O {}