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 {}