gdk4/auto/
texture.rs

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

gdk4/auto/
texture.rs
