gdk_pixbuf/auto/pixbuf.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
6use crate::{ffi, Colorspace, InterpType, PixbufFormat, PixbufRotation};
7use glib::{prelude::*, translate::*};
8
9glib::wrapper! {
10 /// A pixel buffer.
11 ///
12 /// [`Pixbuf`][crate::Pixbuf] contains information about an image's pixel data,
13 /// its color space, bits per sample, width and height, and the
14 /// rowstride (the number of bytes between the start of one row
15 /// and the start of the next).
16 ///
17 /// ## Creating new [`Pixbuf`][crate::Pixbuf]
18 ///
19 /// The most basic way to create a pixbuf is to wrap an existing pixel
20 /// buffer with a [`Pixbuf`][crate::Pixbuf] instance. You can use the
21 /// [`ctor@GdkPixbuf.Pixbuf.new_from_data`] function to do this.
22 ///
23 /// Every time you create a new [`Pixbuf`][crate::Pixbuf] instance for some data, you
24 /// will need to specify the destroy notification function that will be
25 /// called when the data buffer needs to be freed; this will happen when
26 /// a [`Pixbuf`][crate::Pixbuf] is finalized by the reference counting functions. If
27 /// you have a chunk of static data compiled into your application, you
28 /// can pass in `NULL` as the destroy notification function so that the
29 /// data will not be freed.
30 ///
31 /// The [`ctor@GdkPixbuf.Pixbuf.new`] constructor function can be used
32 /// as a convenience to create a pixbuf with an empty buffer; this is
33 /// equivalent to allocating a data buffer using `malloc()` and then
34 /// wrapping it with `gdk_pixbuf_new_from_data()`. The `gdk_pixbuf_new()`
35 /// function will compute an optimal rowstride so that rendering can be
36 /// performed with an efficient algorithm.
37 ///
38 /// You can also copy an existing pixbuf with the `Pixbuf::copy()`
39 /// function. This is not the same as just acquiring a reference to
40 /// the old pixbuf instance: the copy function will actually duplicate
41 /// the pixel data in memory and create a new [`Pixbuf`][crate::Pixbuf] instance
42 /// for it.
43 ///
44 /// ## Reference counting
45 ///
46 /// [`Pixbuf`][crate::Pixbuf] structures are reference counted. This means that an
47 /// application can share a single pixbuf among many parts of the
48 /// code. When a piece of the program needs to use a pixbuf, it should
49 /// acquire a reference to it by calling `g_object_ref()`; when it no
50 /// longer needs the pixbuf, it should release the reference it acquired
51 /// by calling `g_object_unref()`. The resources associated with a
52 /// [`Pixbuf`][crate::Pixbuf] will be freed when its reference count drops to zero.
53 /// Newly-created [`Pixbuf`][crate::Pixbuf] instances start with a reference count
54 /// of one.
55 ///
56 /// ## Image Data
57 ///
58 /// Image data in a pixbuf is stored in memory in an uncompressed,
59 /// packed format. Rows in the image are stored top to bottom, and
60 /// in each row pixels are stored from left to right.
61 ///
62 /// There may be padding at the end of a row.
63 ///
64 /// The "rowstride" value of a pixbuf, as returned by [`method@GdkPixbuf.Pixbuf.get_rowstride`],
65 /// indicates the number of bytes between rows.
66 ///
67 /// **NOTE**: If you are copying raw pixbuf data with `memcpy()` note that the
68 /// last row in the pixbuf may not be as wide as the full rowstride, but rather
69 /// just as wide as the pixel data needs to be; that is: it is unsafe to do
70 /// `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf. Use
71 /// `GdkPixbuf::Pixbuf::copy()` instead, or compute the width in bytes of the
72 /// last row as:
73 ///
74 /// **⚠️ The following code is in c ⚠️**
75 ///
76 /// ```c
77 /// last_row = width * ((n_channels * bits_per_sample + 7) / 8);
78 /// ```
79 ///
80 /// The same rule applies when iterating over each row of a [`Pixbuf`][crate::Pixbuf] pixels
81 /// array.
82 ///
83 /// The following code illustrates a simple `put_pixel()`
84 /// function for RGB pixbufs with 8 bits per channel with an alpha
85 /// channel.
86 ///
87 /// **⚠️ The following code is in c ⚠️**
88 ///
89 /// ```c
90 /// static void
91 /// put_pixel (GdkPixbuf *pixbuf,
92 /// int x,
93 /// int y,
94 /// guchar red,
95 /// guchar green,
96 /// guchar blue,
97 /// guchar alpha)
98 /// {
99 /// int n_channels = gdk_pixbuf_get_n_channels (pixbuf);
100 ///
101 /// // Ensure that the pixbuf is valid
102 /// g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
103 /// g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
104 /// g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
105 /// g_assert (n_channels == 4);
106 ///
107 /// int width = gdk_pixbuf_get_width (pixbuf);
108 /// int height = gdk_pixbuf_get_height (pixbuf);
109 ///
110 /// // Ensure that the coordinates are in a valid range
111 /// g_assert (x >= 0 && x < width);
112 /// g_assert (y >= 0 && y < height);
113 ///
114 /// int rowstride = gdk_pixbuf_get_rowstride (pixbuf);
115 ///
116 /// // The pixel buffer in the GdkPixbuf instance
117 /// guchar *pixels = gdk_pixbuf_get_pixels (pixbuf);
118 ///
119 /// // The pixel we wish to modify
120 /// guchar *p = pixels + y * rowstride + x * n_channels;
121 /// p[0] = red;
122 /// p[1] = green;
123 /// p[2] = blue;
124 /// p[3] = alpha;
125 /// }
126 /// ```
127 ///
128 /// ## Loading images
129 ///
130 /// The `GdkPixBuf` class provides a simple mechanism for loading
131 /// an image from a file in synchronous and asynchronous fashion.
132 ///
133 /// For GUI applications, it is recommended to use the asynchronous
134 /// stream API to avoid blocking the control flow of the application.
135 ///
136 /// Additionally, [`Pixbuf`][crate::Pixbuf] provides the [`PixbufLoader`][crate::PixbufLoader]`]
137 /// API for progressive image loading.
138 ///
139 /// ## Saving images
140 ///
141 /// The [`Pixbuf`][crate::Pixbuf] class provides methods for saving image data in
142 /// a number of file formats. The formatted data can be written to a
143 /// file or to a memory buffer. [`Pixbuf`][crate::Pixbuf] can also call a user-defined
144 /// callback on the data, which allows to e.g. write the image
145 /// to a socket or store it in a database.
146 ///
147 /// ## Properties
148 ///
149 ///
150 /// #### `bits-per-sample`
151 /// The number of bits per sample.
152 ///
153 /// Currently only 8 bit per sample are supported.
154 ///
155 /// Readable | Writeable | Construct Only
156 ///
157 ///
158 /// #### `colorspace`
159 /// The color space of the pixbuf.
160 ///
161 /// Currently, only `GDK_COLORSPACE_RGB` is supported.
162 ///
163 /// Readable | Writeable | Construct Only
164 ///
165 ///
166 /// #### `has-alpha`
167 /// Whether the pixbuf has an alpha channel.
168 ///
169 /// Readable | Writeable | Construct Only
170 ///
171 ///
172 /// #### `height`
173 /// The number of rows of the pixbuf.
174 ///
175 /// Readable | Writeable | Construct Only
176 ///
177 ///
178 /// #### `n-channels`
179 /// The number of samples per pixel.
180 ///
181 /// Currently, only 3 or 4 samples per pixel are supported.
182 ///
183 /// Readable | Writeable | Construct Only
184 ///
185 ///
186 /// #### `pixel-bytes`
187 /// Readable | Writeable | Construct Only
188 ///
189 ///
190 /// #### `pixels`
191 /// A pointer to the pixel data of the pixbuf.
192 ///
193 /// Readable | Writeable | Construct Only
194 ///
195 ///
196 /// #### `rowstride`
197 /// The number of bytes between the start of a row and
198 /// the start of the next row.
199 ///
200 /// This number must (obviously) be at least as large as the
201 /// width of the pixbuf.
202 ///
203 /// Readable | Writeable | Construct Only
204 ///
205 ///
206 /// #### `width`
207 /// The number of columns of the pixbuf.
208 ///
209 /// Readable | Writeable | Construct Only
210 ///
211 /// # Implements
212 ///
213 /// [`trait@gio::prelude::IconExt`], [`trait@gio::prelude::LoadableIconExt`]
214 #[doc(alias = "GdkPixbuf")]
215 pub struct Pixbuf(Object<ffi::GdkPixbuf>) @implements gio::Icon, gio::LoadableIcon;
216
217 match fn {
218 type_ => || ffi::gdk_pixbuf_get_type(),
219 }
220}
221
222impl Pixbuf {
223 /// Creates a new [`Pixbuf`][crate::Pixbuf] structure and allocates a buffer for it.
224 ///
225 /// If the allocation of the buffer failed, this function will return `NULL`.
226 ///
227 /// The buffer has an optimal rowstride. Note that the buffer is not cleared;
228 /// you will have to fill it completely yourself.
229 /// ## `colorspace`
230 /// Color space for image
231 /// ## `has_alpha`
232 /// Whether the image should have transparency information
233 /// ## `bits_per_sample`
234 /// Number of bits per color sample
235 /// ## `width`
236 /// Width of image in pixels, must be > 0
237 /// ## `height`
238 /// Height of image in pixels, must be > 0
239 ///
240 /// # Returns
241 ///
242 /// A newly-created pixel buffer
243 #[doc(alias = "gdk_pixbuf_new")]
244 pub fn new(
245 colorspace: Colorspace,
246 has_alpha: bool,
247 bits_per_sample: i32,
248 width: i32,
249 height: i32,
250 ) -> Option<Pixbuf> {
251 unsafe {
252 from_glib_full(ffi::gdk_pixbuf_new(
253 colorspace.into_glib(),
254 has_alpha.into_glib(),
255 bits_per_sample,
256 width,
257 height,
258 ))
259 }
260 }
261
262 /// Creates a new #GdkPixbuf out of in-memory readonly image data.
263 ///
264 /// Currently only RGB images with 8 bits per sample are supported.
265 ///
266 /// This is the `GBytes` variant of gdk_pixbuf_new_from_data(), useful
267 /// for language bindings.
268 /// ## `data`
269 /// Image data in 8-bit/sample packed format inside a #GBytes
270 /// ## `colorspace`
271 /// Colorspace for the image data
272 /// ## `has_alpha`
273 /// Whether the data has an opacity channel
274 /// ## `bits_per_sample`
275 /// Number of bits per sample
276 /// ## `width`
277 /// Width of the image in pixels, must be > 0
278 /// ## `height`
279 /// Height of the image in pixels, must be > 0
280 /// ## `rowstride`
281 /// Distance in bytes between row starts
282 ///
283 /// # Returns
284 ///
285 /// A newly-created pixbuf
286 #[doc(alias = "gdk_pixbuf_new_from_bytes")]
287 #[doc(alias = "new_from_bytes")]
288 pub fn from_bytes(
289 data: &glib::Bytes,
290 colorspace: Colorspace,
291 has_alpha: bool,
292 bits_per_sample: i32,
293 width: i32,
294 height: i32,
295 rowstride: i32,
296 ) -> Pixbuf {
297 unsafe {
298 from_glib_full(ffi::gdk_pixbuf_new_from_bytes(
299 data.to_glib_none().0,
300 colorspace.into_glib(),
301 has_alpha.into_glib(),
302 bits_per_sample,
303 width,
304 height,
305 rowstride,
306 ))
307 }
308 }
309
310 //#[doc(alias = "gdk_pixbuf_new_from_data")]
311 //#[doc(alias = "new_from_data")]
312 //pub fn from_data(data: &[u8], colorspace: Colorspace, has_alpha: bool, bits_per_sample: i32, width: i32, height: i32, rowstride: i32, destroy_fn: Option<Box_<dyn FnOnce(&Vec<u8>) + 'static>>) -> Pixbuf {
313 // unsafe { TODO: call ffi:gdk_pixbuf_new_from_data() }
314 //}
315
316 /// Creates a new pixbuf by loading an image from a file.
317 ///
318 /// The file format is detected automatically.
319 ///
320 /// If `NULL` is returned, then @error will be set. Possible errors are:
321 ///
322 /// - the file could not be opened
323 /// - there is no loader for the file's format
324 /// - there is not enough memory to allocate the image buffer
325 /// - the image buffer contains invalid data
326 ///
327 /// The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`.
328 /// ## `filename`
329 /// Name of file to load, in the GLib file
330 /// name encoding
331 ///
332 /// # Returns
333 ///
334 /// A newly-created pixbuf
335 #[doc(alias = "gdk_pixbuf_new_from_file")]
336 #[doc(alias = "new_from_file")]
337 pub fn from_file(filename: impl AsRef<std::path::Path>) -> Result<Pixbuf, glib::Error> {
338 unsafe {
339 let mut error = std::ptr::null_mut();
340 let ret = ffi::gdk_pixbuf_new_from_file(filename.as_ref().to_glib_none().0, &mut error);
341 if error.is_null() {
342 Ok(from_glib_full(ret))
343 } else {
344 Err(from_glib_full(error))
345 }
346 }
347 }
348
349 /// Creates a new pixbuf by loading an image from a file.
350 ///
351 /// The file format is detected automatically.
352 ///
353 /// If `NULL` is returned, then @error will be set. Possible errors are:
354 ///
355 /// - the file could not be opened
356 /// - there is no loader for the file's format
357 /// - there is not enough memory to allocate the image buffer
358 /// - the image buffer contains invalid data
359 ///
360 /// The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`.
361 ///
362 /// The image will be scaled to fit in the requested size, optionally preserving
363 /// the image's aspect ratio.
364 ///
365 /// When preserving the aspect ratio, a `width` of -1 will cause the image
366 /// to be scaled to the exact given height, and a `height` of -1 will cause
367 /// the image to be scaled to the exact given width. When not preserving
368 /// aspect ratio, a `width` or `height` of -1 means to not scale the image
369 /// at all in that dimension. Negative values for `width` and `height` are
370 /// allowed since 2.8.
371 /// ## `filename`
372 /// Name of file to load, in the GLib file
373 /// name encoding
374 /// ## `width`
375 /// The width the image should have or -1 to not constrain the width
376 /// ## `height`
377 /// The height the image should have or -1 to not constrain the height
378 /// ## `preserve_aspect_ratio`
379 /// `TRUE` to preserve the image's aspect ratio
380 ///
381 /// # Returns
382 ///
383 /// A newly-created pixbuf
384 #[doc(alias = "gdk_pixbuf_new_from_file_at_scale")]
385 #[doc(alias = "new_from_file_at_scale")]
386 pub fn from_file_at_scale(
387 filename: impl AsRef<std::path::Path>,
388 width: i32,
389 height: i32,
390 preserve_aspect_ratio: bool,
391 ) -> Result<Pixbuf, glib::Error> {
392 unsafe {
393 let mut error = std::ptr::null_mut();
394 let ret = ffi::gdk_pixbuf_new_from_file_at_scale(
395 filename.as_ref().to_glib_none().0,
396 width,
397 height,
398 preserve_aspect_ratio.into_glib(),
399 &mut error,
400 );
401 if error.is_null() {
402 Ok(from_glib_full(ret))
403 } else {
404 Err(from_glib_full(error))
405 }
406 }
407 }
408
409 /// Creates a new pixbuf by loading an image from a file.
410 ///
411 /// The file format is detected automatically.
412 ///
413 /// If `NULL` is returned, then @error will be set. Possible errors are:
414 ///
415 /// - the file could not be opened
416 /// - there is no loader for the file's format
417 /// - there is not enough memory to allocate the image buffer
418 /// - the image buffer contains invalid data
419 ///
420 /// The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`.
421 ///
422 /// The image will be scaled to fit in the requested size, preserving
423 /// the image's aspect ratio. Note that the returned pixbuf may be smaller
424 /// than `width` x `height`, if the aspect ratio requires it. To load
425 /// and image at the requested size, regardless of aspect ratio, use
426 /// [`from_file_at_scale()`][Self::from_file_at_scale()].
427 /// ## `filename`
428 /// Name of file to load, in the GLib file
429 /// name encoding
430 /// ## `width`
431 /// The width the image should have or -1 to not constrain the width
432 /// ## `height`
433 /// The height the image should have or -1 to not constrain the height
434 ///
435 /// # Returns
436 ///
437 /// A newly-created pixbuf
438 #[doc(alias = "gdk_pixbuf_new_from_file_at_size")]
439 #[doc(alias = "new_from_file_at_size")]
440 pub fn from_file_at_size(
441 filename: impl AsRef<std::path::Path>,
442 width: i32,
443 height: i32,
444 ) -> Result<Pixbuf, glib::Error> {
445 unsafe {
446 let mut error = std::ptr::null_mut();
447 let ret = ffi::gdk_pixbuf_new_from_file_at_size(
448 filename.as_ref().to_glib_none().0,
449 width,
450 height,
451 &mut error,
452 );
453 if error.is_null() {
454 Ok(from_glib_full(ret))
455 } else {
456 Err(from_glib_full(error))
457 }
458 }
459 }
460
461 /// Creates a new pixbuf by loading an image from an resource.
462 ///
463 /// The file format is detected automatically. If `NULL` is returned, then
464 /// @error will be set.
465 /// ## `resource_path`
466 /// the path of the resource file
467 ///
468 /// # Returns
469 ///
470 /// A newly-created pixbuf
471 #[doc(alias = "gdk_pixbuf_new_from_resource")]
472 #[doc(alias = "new_from_resource")]
473 pub fn from_resource(resource_path: &str) -> Result<Pixbuf, glib::Error> {
474 unsafe {
475 let mut error = std::ptr::null_mut();
476 let ret = ffi::gdk_pixbuf_new_from_resource(resource_path.to_glib_none().0, &mut error);
477 if error.is_null() {
478 Ok(from_glib_full(ret))
479 } else {
480 Err(from_glib_full(error))
481 }
482 }
483 }
484
485 /// Creates a new pixbuf by loading an image from an resource.
486 ///
487 /// The file format is detected automatically. If `NULL` is returned, then
488 /// @error will be set.
489 ///
490 /// The image will be scaled to fit in the requested size, optionally
491 /// preserving the image's aspect ratio. When preserving the aspect ratio,
492 /// a @width of -1 will cause the image to be scaled to the exact given
493 /// height, and a @height of -1 will cause the image to be scaled to the
494 /// exact given width. When not preserving aspect ratio, a @width or
495 /// @height of -1 means to not scale the image at all in that dimension.
496 ///
497 /// The stream is not closed.
498 /// ## `resource_path`
499 /// the path of the resource file
500 /// ## `width`
501 /// The width the image should have or -1 to not constrain the width
502 /// ## `height`
503 /// The height the image should have or -1 to not constrain the height
504 /// ## `preserve_aspect_ratio`
505 /// `TRUE` to preserve the image's aspect ratio
506 ///
507 /// # Returns
508 ///
509 /// A newly-created pixbuf
510 #[doc(alias = "gdk_pixbuf_new_from_resource_at_scale")]
511 #[doc(alias = "new_from_resource_at_scale")]
512 pub fn from_resource_at_scale(
513 resource_path: &str,
514 width: i32,
515 height: i32,
516 preserve_aspect_ratio: bool,
517 ) -> Result<Pixbuf, glib::Error> {
518 unsafe {
519 let mut error = std::ptr::null_mut();
520 let ret = ffi::gdk_pixbuf_new_from_resource_at_scale(
521 resource_path.to_glib_none().0,
522 width,
523 height,
524 preserve_aspect_ratio.into_glib(),
525 &mut error,
526 );
527 if error.is_null() {
528 Ok(from_glib_full(ret))
529 } else {
530 Err(from_glib_full(error))
531 }
532 }
533 }
534
535 /// Creates a new pixbuf by loading an image from an input stream.
536 ///
537 /// The file format is detected automatically.
538 ///
539 /// If `NULL` is returned, then `error` will be set.
540 ///
541 /// The `cancellable` can be used to abort the operation from another thread.
542 /// If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be
543 /// returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and
544 /// `G_IO_ERROR` domains.
545 ///
546 /// The stream is not closed.
547 /// ## `stream`
548 /// a `GInputStream` to load the pixbuf from
549 /// ## `cancellable`
550 /// optional `GCancellable` object, `NULL` to ignore
551 ///
552 /// # Returns
553 ///
554 /// A newly-created pixbuf
555 #[doc(alias = "gdk_pixbuf_new_from_stream")]
556 #[doc(alias = "new_from_stream")]
557 pub fn from_stream(
558 stream: &impl IsA<gio::InputStream>,
559 cancellable: Option<&impl IsA<gio::Cancellable>>,
560 ) -> Result<Pixbuf, glib::Error> {
561 unsafe {
562 let mut error = std::ptr::null_mut();
563 let ret = ffi::gdk_pixbuf_new_from_stream(
564 stream.as_ref().to_glib_none().0,
565 cancellable.map(|p| p.as_ref()).to_glib_none().0,
566 &mut error,
567 );
568 if error.is_null() {
569 Ok(from_glib_full(ret))
570 } else {
571 Err(from_glib_full(error))
572 }
573 }
574 }
575
576 /// Creates a new pixbuf by loading an image from an input stream.
577 ///
578 /// The file format is detected automatically. If `NULL` is returned, then
579 /// @error will be set. The @cancellable can be used to abort the operation
580 /// from another thread. If the operation was cancelled, the error
581 /// `G_IO_ERROR_CANCELLED` will be returned. Other possible errors are in
582 /// the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains.
583 ///
584 /// The image will be scaled to fit in the requested size, optionally
585 /// preserving the image's aspect ratio.
586 ///
587 /// When preserving the aspect ratio, a `width` of -1 will cause the image to be
588 /// scaled to the exact given height, and a `height` of -1 will cause the image
589 /// to be scaled to the exact given width. If both `width` and `height` are
590 /// given, this function will behave as if the smaller of the two values
591 /// is passed as -1.
592 ///
593 /// When not preserving aspect ratio, a `width` or `height` of -1 means to not
594 /// scale the image at all in that dimension.
595 ///
596 /// The stream is not closed.
597 /// ## `stream`
598 /// a `GInputStream` to load the pixbuf from
599 /// ## `width`
600 /// The width the image should have or -1 to not constrain the width
601 /// ## `height`
602 /// The height the image should have or -1 to not constrain the height
603 /// ## `preserve_aspect_ratio`
604 /// `TRUE` to preserve the image's aspect ratio
605 /// ## `cancellable`
606 /// optional `GCancellable` object, `NULL` to ignore
607 ///
608 /// # Returns
609 ///
610 /// A newly-created pixbuf
611 #[doc(alias = "gdk_pixbuf_new_from_stream_at_scale")]
612 #[doc(alias = "new_from_stream_at_scale")]
613 pub fn from_stream_at_scale(
614 stream: &impl IsA<gio::InputStream>,
615 width: i32,
616 height: i32,
617 preserve_aspect_ratio: bool,
618 cancellable: Option<&impl IsA<gio::Cancellable>>,
619 ) -> Result<Pixbuf, glib::Error> {
620 unsafe {
621 let mut error = std::ptr::null_mut();
622 let ret = ffi::gdk_pixbuf_new_from_stream_at_scale(
623 stream.as_ref().to_glib_none().0,
624 width,
625 height,
626 preserve_aspect_ratio.into_glib(),
627 cancellable.map(|p| p.as_ref()).to_glib_none().0,
628 &mut error,
629 );
630 if error.is_null() {
631 Ok(from_glib_full(ret))
632 } else {
633 Err(from_glib_full(error))
634 }
635 }
636 }
637
638 /// Creates a new pixbuf by parsing XPM data in memory.
639 ///
640 /// This data is commonly the result of including an XPM file into a
641 /// program's C source.
642 ///
643 /// # Deprecated since 2.44
644 ///
645 /// Use [`from_stream()`][Self::from_stream()] with
646 /// a `Gio::MemoryInputStream`, making sure to handle errors in
647 /// case the XPM format loader is not available
648 /// ## `data`
649 /// Pointer to inline XPM data.
650 ///
651 /// # Returns
652 ///
653 /// A newly-created pixbuf
654 #[cfg_attr(feature = "v2_44", deprecated = "Since 2.44")]
655 #[allow(deprecated)]
656 #[doc(alias = "gdk_pixbuf_new_from_xpm_data")]
657 #[doc(alias = "new_from_xpm_data")]
658 pub fn from_xpm_data(data: &[&str]) -> Result<Pixbuf, glib::BoolError> {
659 unsafe {
660 Option::<_>::from_glib_full(ffi::gdk_pixbuf_new_from_xpm_data(data.to_glib_none().0))
661 .ok_or_else(|| glib::bool_error!("Invalid XPM data"))
662 }
663 }
664
665 /// Takes an existing pixbuf and adds an alpha channel to it.
666 ///
667 /// If the existing pixbuf already had an alpha channel, the channel
668 /// values are copied from the original; otherwise, the alpha channel
669 /// is initialized to 255 (full opacity).
670 ///
671 /// If `substitute_color` is `TRUE`, then the color specified by the
672 /// (`r`, `g`, `b`) arguments will be assigned zero opacity. That is,
673 /// if you pass `(255, 255, 255)` for the substitute color, all white
674 /// pixels will become fully transparent.
675 ///
676 /// If `substitute_color` is `FALSE`, then the (`r`, `g`, `b`) arguments
677 /// will be ignored.
678 /// ## `substitute_color`
679 /// Whether to set a color to zero opacity.
680 /// ## `r`
681 /// Red value to substitute.
682 /// ## `g`
683 /// Green value to substitute.
684 /// ## `b`
685 /// Blue value to substitute.
686 ///
687 /// # Returns
688 ///
689 /// A newly-created pixbuf
690 #[doc(alias = "gdk_pixbuf_add_alpha")]
691 pub fn add_alpha(
692 &self,
693 substitute_color: bool,
694 r: u8,
695 g: u8,
696 b: u8,
697 ) -> Result<Pixbuf, glib::BoolError> {
698 unsafe {
699 Option::<_>::from_glib_full(ffi::gdk_pixbuf_add_alpha(
700 self.to_glib_none().0,
701 substitute_color.into_glib(),
702 r,
703 g,
704 b,
705 ))
706 .ok_or_else(|| glib::bool_error!("Failed to add alpha channel"))
707 }
708 }
709
710 /// Takes an existing pixbuf and checks for the presence of an
711 /// associated "orientation" option.
712 ///
713 /// The orientation option may be provided by the JPEG loader (which
714 /// reads the exif orientation tag) or the TIFF loader (which reads
715 /// the TIFF orientation tag, and compensates it for the partial
716 /// transforms performed by libtiff).
717 ///
718 /// If an orientation option/tag is present, the appropriate transform
719 /// will be performed so that the pixbuf is oriented correctly.
720 ///
721 /// # Returns
722 ///
723 /// A newly-created pixbuf
724 #[doc(alias = "gdk_pixbuf_apply_embedded_orientation")]
725 #[must_use]
726 pub fn apply_embedded_orientation(&self) -> Option<Pixbuf> {
727 unsafe {
728 from_glib_full(ffi::gdk_pixbuf_apply_embedded_orientation(
729 self.to_glib_none().0,
730 ))
731 }
732 }
733
734 /// Creates a transformation of the source image @self by scaling by
735 /// @scale_x and @scale_y then translating by @offset_x and @offset_y.
736 ///
737 /// This gives an image in the coordinates of the destination pixbuf.
738 /// The rectangle (@dest_x, @dest_y, @dest_width, @dest_height)
739 /// is then alpha blended onto the corresponding rectangle of the
740 /// original destination image.
741 ///
742 /// When the destination rectangle contains parts not in the source
743 /// image, the data at the edges of the source image is replicated
744 /// to infinity.
745 ///
746 /// 
747 /// ## `dest`
748 /// the #GdkPixbuf into which to render the results
749 /// ## `dest_x`
750 /// the left coordinate for region to render
751 /// ## `dest_y`
752 /// the top coordinate for region to render
753 /// ## `dest_width`
754 /// the width of the region to render
755 /// ## `dest_height`
756 /// the height of the region to render
757 /// ## `offset_x`
758 /// the offset in the X direction (currently rounded to an integer)
759 /// ## `offset_y`
760 /// the offset in the Y direction (currently rounded to an integer)
761 /// ## `scale_x`
762 /// the scale factor in the X direction
763 /// ## `scale_y`
764 /// the scale factor in the Y direction
765 /// ## `interp_type`
766 /// the interpolation type for the transformation.
767 /// ## `overall_alpha`
768 /// overall alpha for source image (0..255)
769 #[doc(alias = "gdk_pixbuf_composite")]
770 pub fn composite(
771 &self,
772 dest: &Pixbuf,
773 dest_x: i32,
774 dest_y: i32,
775 dest_width: i32,
776 dest_height: i32,
777 offset_x: f64,
778 offset_y: f64,
779 scale_x: f64,
780 scale_y: f64,
781 interp_type: InterpType,
782 overall_alpha: i32,
783 ) {
784 unsafe {
785 ffi::gdk_pixbuf_composite(
786 self.to_glib_none().0,
787 dest.to_glib_none().0,
788 dest_x,
789 dest_y,
790 dest_width,
791 dest_height,
792 offset_x,
793 offset_y,
794 scale_x,
795 scale_y,
796 interp_type.into_glib(),
797 overall_alpha,
798 );
799 }
800 }
801
802 /// Creates a transformation of the source image @self by scaling by
803 /// @scale_x and @scale_y then translating by @offset_x and @offset_y,
804 /// then alpha blends the rectangle (@dest_x ,@dest_y, @dest_width,
805 /// @dest_height) of the resulting image with a checkboard of the
806 /// colors @color1 and @color2 and renders it onto the destination
807 /// image.
808 ///
809 /// If the source image has no alpha channel, and @overall_alpha is 255, a fast
810 /// path is used which omits the alpha blending and just performs the scaling.
811 ///
812 /// See gdk_pixbuf_composite_color_simple() for a simpler variant of this
813 /// function suitable for many tasks.
814 /// ## `dest`
815 /// the #GdkPixbuf into which to render the results
816 /// ## `dest_x`
817 /// the left coordinate for region to render
818 /// ## `dest_y`
819 /// the top coordinate for region to render
820 /// ## `dest_width`
821 /// the width of the region to render
822 /// ## `dest_height`
823 /// the height of the region to render
824 /// ## `offset_x`
825 /// the offset in the X direction (currently rounded to an integer)
826 /// ## `offset_y`
827 /// the offset in the Y direction (currently rounded to an integer)
828 /// ## `scale_x`
829 /// the scale factor in the X direction
830 /// ## `scale_y`
831 /// the scale factor in the Y direction
832 /// ## `interp_type`
833 /// the interpolation type for the transformation.
834 /// ## `overall_alpha`
835 /// overall alpha for source image (0..255)
836 /// ## `check_x`
837 /// the X offset for the checkboard (origin of checkboard is at -@check_x, -@check_y)
838 /// ## `check_y`
839 /// the Y offset for the checkboard
840 /// ## `check_size`
841 /// the size of checks in the checkboard (must be a power of two)
842 /// ## `color1`
843 /// the color of check at upper left
844 /// ## `color2`
845 /// the color of the other check
846 #[doc(alias = "gdk_pixbuf_composite_color")]
847 pub fn composite_color(
848 &self,
849 dest: &Pixbuf,
850 dest_x: i32,
851 dest_y: i32,
852 dest_width: i32,
853 dest_height: i32,
854 offset_x: f64,
855 offset_y: f64,
856 scale_x: f64,
857 scale_y: f64,
858 interp_type: InterpType,
859 overall_alpha: i32,
860 check_x: i32,
861 check_y: i32,
862 check_size: i32,
863 color1: u32,
864 color2: u32,
865 ) {
866 unsafe {
867 ffi::gdk_pixbuf_composite_color(
868 self.to_glib_none().0,
869 dest.to_glib_none().0,
870 dest_x,
871 dest_y,
872 dest_width,
873 dest_height,
874 offset_x,
875 offset_y,
876 scale_x,
877 scale_y,
878 interp_type.into_glib(),
879 overall_alpha,
880 check_x,
881 check_y,
882 check_size,
883 color1,
884 color2,
885 );
886 }
887 }
888
889 /// Creates a new pixbuf by scaling `src` to `dest_width` x `dest_height`
890 /// and alpha blending the result with a checkboard of colors `color1`
891 /// and `color2`.
892 /// ## `dest_width`
893 /// the width of destination image
894 /// ## `dest_height`
895 /// the height of destination image
896 /// ## `interp_type`
897 /// the interpolation type for the transformation.
898 /// ## `overall_alpha`
899 /// overall alpha for source image (0..255)
900 /// ## `check_size`
901 /// the size of checks in the checkboard (must be a power of two)
902 /// ## `color1`
903 /// the color of check at upper left
904 /// ## `color2`
905 /// the color of the other check
906 ///
907 /// # Returns
908 ///
909 /// the new pixbuf
910 #[doc(alias = "gdk_pixbuf_composite_color_simple")]
911 #[must_use]
912 pub fn composite_color_simple(
913 &self,
914 dest_width: i32,
915 dest_height: i32,
916 interp_type: InterpType,
917 overall_alpha: i32,
918 check_size: i32,
919 color1: u32,
920 color2: u32,
921 ) -> Option<Pixbuf> {
922 unsafe {
923 from_glib_full(ffi::gdk_pixbuf_composite_color_simple(
924 self.to_glib_none().0,
925 dest_width,
926 dest_height,
927 interp_type.into_glib(),
928 overall_alpha,
929 check_size,
930 color1,
931 color2,
932 ))
933 }
934 }
935
936 #[doc(alias = "gdk_pixbuf_copy")]
937 #[must_use]
938 pub fn copy(&self) -> Option<Pixbuf> {
939 unsafe { from_glib_full(ffi::gdk_pixbuf_copy(self.to_glib_none().0)) }
940 }
941
942 /// Copies a rectangular area from `src_pixbuf` to `dest_pixbuf`.
943 ///
944 /// Conversion of pixbuf formats is done automatically.
945 ///
946 /// If the source rectangle overlaps the destination rectangle on the
947 /// same pixbuf, it will be overwritten during the copy operation.
948 /// Therefore, you can not use this function to scroll a pixbuf.
949 /// ## `src_x`
950 /// Source X coordinate within @self.
951 /// ## `src_y`
952 /// Source Y coordinate within @self.
953 /// ## `width`
954 /// Width of the area to copy.
955 /// ## `height`
956 /// Height of the area to copy.
957 /// ## `dest_pixbuf`
958 /// Destination pixbuf.
959 /// ## `dest_x`
960 /// X coordinate within @dest_pixbuf.
961 /// ## `dest_y`
962 /// Y coordinate within @dest_pixbuf.
963 #[doc(alias = "gdk_pixbuf_copy_area")]
964 pub fn copy_area(
965 &self,
966 src_x: i32,
967 src_y: i32,
968 width: i32,
969 height: i32,
970 dest_pixbuf: &Pixbuf,
971 dest_x: i32,
972 dest_y: i32,
973 ) {
974 unsafe {
975 ffi::gdk_pixbuf_copy_area(
976 self.to_glib_none().0,
977 src_x,
978 src_y,
979 width,
980 height,
981 dest_pixbuf.to_glib_none().0,
982 dest_x,
983 dest_y,
984 );
985 }
986 }
987
988 /// Copies the key/value pair options attached to a [`Pixbuf`][crate::Pixbuf] to another
989 /// [`Pixbuf`][crate::Pixbuf].
990 ///
991 /// This is useful to keep original metadata after having manipulated
992 /// a file. However be careful to remove metadata which you've already
993 /// applied, such as the "orientation" option after rotating the image.
994 /// ## `dest_pixbuf`
995 /// the destination pixbuf
996 ///
997 /// # Returns
998 ///
999 /// `TRUE` on success.
1000 #[doc(alias = "gdk_pixbuf_copy_options")]
1001 pub fn copy_options(&self, dest_pixbuf: &Pixbuf) -> bool {
1002 unsafe {
1003 from_glib(ffi::gdk_pixbuf_copy_options(
1004 self.to_glib_none().0,
1005 dest_pixbuf.to_glib_none().0,
1006 ))
1007 }
1008 }
1009
1010 /// Clears a pixbuf to the given RGBA value, converting the RGBA value into
1011 /// the pixbuf's pixel format.
1012 ///
1013 /// The alpha component will be ignored if the pixbuf doesn't have an alpha
1014 /// channel.
1015 /// ## `pixel`
1016 /// RGBA pixel to used to clear (`0xffffffff` is opaque white,
1017 /// `0x00000000` transparent black)
1018 #[doc(alias = "gdk_pixbuf_fill")]
1019 pub fn fill(&self, pixel: u32) {
1020 unsafe {
1021 ffi::gdk_pixbuf_fill(self.to_glib_none().0, pixel);
1022 }
1023 }
1024
1025 /// Flips a pixbuf horizontally or vertically and returns the
1026 /// result in a new pixbuf.
1027 /// ## `horizontal`
1028 /// `TRUE` to flip horizontally, `FALSE` to flip vertically
1029 ///
1030 /// # Returns
1031 ///
1032 /// the new pixbuf
1033 #[doc(alias = "gdk_pixbuf_flip")]
1034 #[must_use]
1035 pub fn flip(&self, horizontal: bool) -> Option<Pixbuf> {
1036 unsafe {
1037 from_glib_full(ffi::gdk_pixbuf_flip(
1038 self.to_glib_none().0,
1039 horizontal.into_glib(),
1040 ))
1041 }
1042 }
1043
1044 /// Queries the number of bits per color sample in a pixbuf.
1045 ///
1046 /// # Returns
1047 ///
1048 /// Number of bits per color sample.
1049 #[doc(alias = "gdk_pixbuf_get_bits_per_sample")]
1050 #[doc(alias = "get_bits_per_sample")]
1051 #[doc(alias = "bits-per-sample")]
1052 pub fn bits_per_sample(&self) -> i32 {
1053 unsafe { ffi::gdk_pixbuf_get_bits_per_sample(self.to_glib_none().0) }
1054 }
1055
1056 /// Returns the length of the pixel data, in bytes.
1057 ///
1058 /// # Returns
1059 ///
1060 /// The length of the pixel data.
1061 #[doc(alias = "gdk_pixbuf_get_byte_length")]
1062 #[doc(alias = "get_byte_length")]
1063 pub fn byte_length(&self) -> usize {
1064 unsafe { ffi::gdk_pixbuf_get_byte_length(self.to_glib_none().0) }
1065 }
1066
1067 /// Queries the color space of a pixbuf.
1068 ///
1069 /// # Returns
1070 ///
1071 /// Color space.
1072 #[doc(alias = "gdk_pixbuf_get_colorspace")]
1073 #[doc(alias = "get_colorspace")]
1074 pub fn colorspace(&self) -> Colorspace {
1075 unsafe { from_glib(ffi::gdk_pixbuf_get_colorspace(self.to_glib_none().0)) }
1076 }
1077
1078 /// Queries whether a pixbuf has an alpha channel (opacity information).
1079 ///
1080 /// # Returns
1081 ///
1082 /// `TRUE` if it has an alpha channel, `FALSE` otherwise.
1083 #[doc(alias = "gdk_pixbuf_get_has_alpha")]
1084 #[doc(alias = "get_has_alpha")]
1085 #[doc(alias = "has-alpha")]
1086 pub fn has_alpha(&self) -> bool {
1087 unsafe { from_glib(ffi::gdk_pixbuf_get_has_alpha(self.to_glib_none().0)) }
1088 }
1089
1090 /// Queries the height of a pixbuf.
1091 ///
1092 /// # Returns
1093 ///
1094 /// Height in pixels.
1095 #[doc(alias = "gdk_pixbuf_get_height")]
1096 #[doc(alias = "get_height")]
1097 pub fn height(&self) -> i32 {
1098 unsafe { ffi::gdk_pixbuf_get_height(self.to_glib_none().0) }
1099 }
1100
1101 /// Queries the number of channels of a pixbuf.
1102 ///
1103 /// # Returns
1104 ///
1105 /// Number of channels.
1106 #[doc(alias = "gdk_pixbuf_get_n_channels")]
1107 #[doc(alias = "get_n_channels")]
1108 #[doc(alias = "n-channels")]
1109 pub fn n_channels(&self) -> i32 {
1110 unsafe { ffi::gdk_pixbuf_get_n_channels(self.to_glib_none().0) }
1111 }
1112
1113 /// Looks up @key in the list of options that may have been attached to the
1114 /// @self when it was loaded, or that may have been attached by another
1115 /// function using gdk_pixbuf_set_option().
1116 ///
1117 /// For instance, the ANI loader provides "Title" and "Artist" options.
1118 /// The ICO, XBM, and XPM loaders provide "x_hot" and "y_hot" hot-spot
1119 /// options for cursor definitions. The PNG loader provides the tEXt ancillary
1120 /// chunk key/value pairs as options. Since 2.12, the TIFF and JPEG loaders
1121 /// return an "orientation" option string that corresponds to the embedded
1122 /// TIFF/Exif orientation tag (if present). Since 2.32, the TIFF loader sets
1123 /// the "multipage" option string to "yes" when a multi-page TIFF is loaded.
1124 /// Since 2.32 the JPEG and PNG loaders set "x-dpi" and "y-dpi" if the file
1125 /// contains image density information in dots per inch.
1126 /// Since 2.36.6, the JPEG loader sets the "comment" option with the comment
1127 /// EXIF tag.
1128 /// ## `key`
1129 /// a nul-terminated string.
1130 ///
1131 /// # Returns
1132 ///
1133 /// the value associated with `key`
1134 #[doc(alias = "gdk_pixbuf_get_option")]
1135 #[doc(alias = "get_option")]
1136 pub fn option(&self, key: &str) -> Option<glib::GString> {
1137 unsafe {
1138 from_glib_none(ffi::gdk_pixbuf_get_option(
1139 self.to_glib_none().0,
1140 key.to_glib_none().0,
1141 ))
1142 }
1143 }
1144
1145 //#[doc(alias = "gdk_pixbuf_get_options")]
1146 //#[doc(alias = "get_options")]
1147 //pub fn options(&self) -> /*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 } {
1148 // unsafe { TODO: call ffi:gdk_pixbuf_get_options() }
1149 //}
1150
1151 /// Queries the rowstride of a pixbuf, which is the number of bytes between
1152 /// the start of a row and the start of the next row.
1153 ///
1154 /// # Returns
1155 ///
1156 /// Distance between row starts.
1157 #[doc(alias = "gdk_pixbuf_get_rowstride")]
1158 #[doc(alias = "get_rowstride")]
1159 pub fn rowstride(&self) -> i32 {
1160 unsafe { ffi::gdk_pixbuf_get_rowstride(self.to_glib_none().0) }
1161 }
1162
1163 /// Queries the width of a pixbuf.
1164 ///
1165 /// # Returns
1166 ///
1167 /// Width in pixels.
1168 #[doc(alias = "gdk_pixbuf_get_width")]
1169 #[doc(alias = "get_width")]
1170 pub fn width(&self) -> i32 {
1171 unsafe { ffi::gdk_pixbuf_get_width(self.to_glib_none().0) }
1172 }
1173
1174 /// Creates a new pixbuf which represents a sub-region of `src_pixbuf`.
1175 ///
1176 /// The new pixbuf shares its pixels with the original pixbuf, so
1177 /// writing to one affects both. The new pixbuf holds a reference to
1178 /// `src_pixbuf`, so `src_pixbuf` will not be finalized until the new
1179 /// pixbuf is finalized.
1180 ///
1181 /// Note that if `src_pixbuf` is read-only, this function will force it
1182 /// to be mutable.
1183 /// ## `src_x`
1184 /// X coord in @self
1185 /// ## `src_y`
1186 /// Y coord in @self
1187 /// ## `width`
1188 /// width of region in @self
1189 /// ## `height`
1190 /// height of region in @self
1191 ///
1192 /// # Returns
1193 ///
1194 /// a new pixbuf
1195 #[doc(alias = "gdk_pixbuf_new_subpixbuf")]
1196 #[must_use]
1197 pub fn new_subpixbuf(&self, src_x: i32, src_y: i32, width: i32, height: i32) -> Pixbuf {
1198 unsafe {
1199 from_glib_full(ffi::gdk_pixbuf_new_subpixbuf(
1200 self.to_glib_none().0,
1201 src_x,
1202 src_y,
1203 width,
1204 height,
1205 ))
1206 }
1207 }
1208
1209 /// Provides a #GBytes buffer containing the raw pixel data; the data
1210 /// must not be modified.
1211 ///
1212 /// This function allows skipping the implicit copy that must be made
1213 /// if gdk_pixbuf_get_pixels() is called on a read-only pixbuf.
1214 ///
1215 /// # Returns
1216 ///
1217 /// A new reference to a read-only copy of
1218 /// the pixel data. Note that for mutable pixbufs, this function will
1219 /// incur a one-time copy of the pixel data for conversion into the
1220 /// returned #GBytes.
1221 #[doc(alias = "gdk_pixbuf_read_pixel_bytes")]
1222 pub fn read_pixel_bytes(&self) -> glib::Bytes {
1223 unsafe { from_glib_full(ffi::gdk_pixbuf_read_pixel_bytes(self.to_glib_none().0)) }
1224 }
1225
1226 /// Removes the key/value pair option attached to a [`Pixbuf`][crate::Pixbuf].
1227 /// ## `key`
1228 /// a nul-terminated string representing the key to remove.
1229 ///
1230 /// # Returns
1231 ///
1232 /// `TRUE` if an option was removed, `FALSE` if not.
1233 #[doc(alias = "gdk_pixbuf_remove_option")]
1234 pub fn remove_option(&self, key: &str) -> bool {
1235 unsafe {
1236 from_glib(ffi::gdk_pixbuf_remove_option(
1237 self.to_glib_none().0,
1238 key.to_glib_none().0,
1239 ))
1240 }
1241 }
1242
1243 /// Rotates a pixbuf by a multiple of 90 degrees, and returns the
1244 /// result in a new pixbuf.
1245 ///
1246 /// If `angle` is 0, this function will return a copy of `src`.
1247 /// ## `angle`
1248 /// the angle to rotate by
1249 ///
1250 /// # Returns
1251 ///
1252 /// the new pixbuf
1253 #[doc(alias = "gdk_pixbuf_rotate_simple")]
1254 #[must_use]
1255 pub fn rotate_simple(&self, angle: PixbufRotation) -> Option<Pixbuf> {
1256 unsafe {
1257 from_glib_full(ffi::gdk_pixbuf_rotate_simple(
1258 self.to_glib_none().0,
1259 angle.into_glib(),
1260 ))
1261 }
1262 }
1263
1264 /// Modifies saturation and optionally pixelates `src`, placing the result in
1265 /// `dest`.
1266 ///
1267 /// The `src` and `dest` pixbufs must have the same image format, size, and
1268 /// rowstride.
1269 ///
1270 /// The `src` and `dest` arguments may be the same pixbuf with no ill effects.
1271 ///
1272 /// If `saturation` is 1.0 then saturation is not changed. If it's less than 1.0,
1273 /// saturation is reduced (the image turns toward grayscale); if greater than
1274 /// 1.0, saturation is increased (the image gets more vivid colors).
1275 ///
1276 /// If `pixelate` is `TRUE`, then pixels are faded in a checkerboard pattern to
1277 /// create a pixelated image.
1278 /// ## `dest`
1279 /// place to write modified version of @self
1280 /// ## `saturation`
1281 /// saturation factor
1282 /// ## `pixelate`
1283 /// whether to pixelate
1284 #[doc(alias = "gdk_pixbuf_saturate_and_pixelate")]
1285 pub fn saturate_and_pixelate(&self, dest: &Pixbuf, saturation: f32, pixelate: bool) {
1286 unsafe {
1287 ffi::gdk_pixbuf_saturate_and_pixelate(
1288 self.to_glib_none().0,
1289 dest.to_glib_none().0,
1290 saturation,
1291 pixelate.into_glib(),
1292 );
1293 }
1294 }
1295
1296 //#[doc(alias = "gdk_pixbuf_save")]
1297 //pub fn save(&self, filename: impl AsRef<std::path::Path>, type_: &str, error: Option<&mut glib::Error>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> bool {
1298 // unsafe { TODO: call ffi:gdk_pixbuf_save() }
1299 //}
1300
1301 //#[doc(alias = "gdk_pixbuf_save_to_buffer")]
1302 //pub fn save_to_buffer(&self, type_: &str, error: &mut glib::Error, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> Option<Vec<u8>> {
1303 // unsafe { TODO: call ffi:gdk_pixbuf_save_to_buffer() }
1304 //}
1305
1306 //#[doc(alias = "gdk_pixbuf_save_to_callback")]
1307 //pub fn save_to_callback<P: FnMut(&Vec<u8>, usize, &glib::Error) -> bool>(&self, save_func: P, type_: &str, error: Option<&mut glib::Error>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> bool {
1308 // unsafe { TODO: call ffi:gdk_pixbuf_save_to_callback() }
1309 //}
1310
1311 //#[doc(alias = "gdk_pixbuf_save_to_callbackv")]
1312 //pub fn save_to_callbackv<P: FnMut(&Vec<u8>, usize, &glib::Error) -> bool>(&self, save_func: P, type_: &str, option_keys: &[&str], option_values: &[&str]) -> Result<(), glib::Error> {
1313 // unsafe { TODO: call ffi:gdk_pixbuf_save_to_callbackv() }
1314 //}
1315
1316 //#[doc(alias = "gdk_pixbuf_save_to_stream")]
1317 //pub fn save_to_stream(&self, stream: &impl IsA<gio::OutputStream>, type_: &str, cancellable: Option<&impl IsA<gio::Cancellable>>, error: Option<&mut glib::Error>, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> bool {
1318 // unsafe { TODO: call ffi:gdk_pixbuf_save_to_stream() }
1319 //}
1320
1321 //#[doc(alias = "gdk_pixbuf_save_to_stream_async")]
1322 //pub fn save_to_stream_async<P: FnOnce(Result<(), glib::Error>) + 'static>(&self, stream: &impl IsA<gio::OutputStream>, type_: &str, cancellable: Option<&impl IsA<gio::Cancellable>>, callback: P, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
1323 // unsafe { TODO: call ffi:gdk_pixbuf_save_to_stream_async() }
1324 //}
1325
1326 /// Creates a transformation of the source image @self by scaling by
1327 /// @scale_x and @scale_y then translating by @offset_x and @offset_y,
1328 /// then renders the rectangle (@dest_x, @dest_y, @dest_width,
1329 /// @dest_height) of the resulting image onto the destination image
1330 /// replacing the previous contents.
1331 ///
1332 /// Try to use gdk_pixbuf_scale_simple() first; this function is
1333 /// the industrial-strength power tool you can fall back to, if
1334 /// gdk_pixbuf_scale_simple() isn't powerful enough.
1335 ///
1336 /// If the source rectangle overlaps the destination rectangle on the
1337 /// same pixbuf, it will be overwritten during the scaling which
1338 /// results in rendering artifacts.
1339 /// ## `dest`
1340 /// the #GdkPixbuf into which to render the results
1341 /// ## `dest_x`
1342 /// the left coordinate for region to render
1343 /// ## `dest_y`
1344 /// the top coordinate for region to render
1345 /// ## `dest_width`
1346 /// the width of the region to render
1347 /// ## `dest_height`
1348 /// the height of the region to render
1349 /// ## `offset_x`
1350 /// the offset in the X direction (currently rounded to an integer)
1351 /// ## `offset_y`
1352 /// the offset in the Y direction (currently rounded to an integer)
1353 /// ## `scale_x`
1354 /// the scale factor in the X direction
1355 /// ## `scale_y`
1356 /// the scale factor in the Y direction
1357 /// ## `interp_type`
1358 /// the interpolation type for the transformation.
1359 #[doc(alias = "gdk_pixbuf_scale")]
1360 pub fn scale(
1361 &self,
1362 dest: &Pixbuf,
1363 dest_x: i32,
1364 dest_y: i32,
1365 dest_width: i32,
1366 dest_height: i32,
1367 offset_x: f64,
1368 offset_y: f64,
1369 scale_x: f64,
1370 scale_y: f64,
1371 interp_type: InterpType,
1372 ) {
1373 unsafe {
1374 ffi::gdk_pixbuf_scale(
1375 self.to_glib_none().0,
1376 dest.to_glib_none().0,
1377 dest_x,
1378 dest_y,
1379 dest_width,
1380 dest_height,
1381 offset_x,
1382 offset_y,
1383 scale_x,
1384 scale_y,
1385 interp_type.into_glib(),
1386 );
1387 }
1388 }
1389
1390 /// Create a new pixbuf containing a copy of `src` scaled to
1391 /// `dest_width` x `dest_height`.
1392 ///
1393 /// This function leaves `src` unaffected.
1394 ///
1395 /// The `interp_type` should be `GDK_INTERP_NEAREST` if you want maximum
1396 /// speed (but when scaling down `GDK_INTERP_NEAREST` is usually unusably
1397 /// ugly). The default `interp_type` should be `GDK_INTERP_BILINEAR` which
1398 /// offers reasonable quality and speed.
1399 ///
1400 /// You can scale a sub-portion of `src` by creating a sub-pixbuf
1401 /// pointing into `src`; see [`new_subpixbuf()`][Self::new_subpixbuf()].
1402 ///
1403 /// If `dest_width` and `dest_height` are equal to the width and height of
1404 /// `src`, this function will return an unscaled copy of `src`.
1405 ///
1406 /// For more complicated scaling/alpha blending see [`scale()`][Self::scale()]
1407 /// and [`composite()`][Self::composite()].
1408 /// ## `dest_width`
1409 /// the width of destination image
1410 /// ## `dest_height`
1411 /// the height of destination image
1412 /// ## `interp_type`
1413 /// the interpolation type for the transformation.
1414 ///
1415 /// # Returns
1416 ///
1417 /// the new pixbuf
1418 #[doc(alias = "gdk_pixbuf_scale_simple")]
1419 #[must_use]
1420 pub fn scale_simple(
1421 &self,
1422 dest_width: i32,
1423 dest_height: i32,
1424 interp_type: InterpType,
1425 ) -> Option<Pixbuf> {
1426 unsafe {
1427 from_glib_full(ffi::gdk_pixbuf_scale_simple(
1428 self.to_glib_none().0,
1429 dest_width,
1430 dest_height,
1431 interp_type.into_glib(),
1432 ))
1433 }
1434 }
1435
1436 /// Attaches a key/value pair as an option to a [`Pixbuf`][crate::Pixbuf].
1437 ///
1438 /// If `key` already exists in the list of options attached to the `pixbuf`,
1439 /// the new value is ignored and `FALSE` is returned.
1440 /// ## `key`
1441 /// a nul-terminated string.
1442 /// ## `value`
1443 /// a nul-terminated string.
1444 ///
1445 /// # Returns
1446 ///
1447 /// `TRUE` on success
1448 #[doc(alias = "gdk_pixbuf_set_option")]
1449 pub fn set_option(&self, key: &str, value: &str) -> bool {
1450 unsafe {
1451 from_glib(ffi::gdk_pixbuf_set_option(
1452 self.to_glib_none().0,
1453 key.to_glib_none().0,
1454 value.to_glib_none().0,
1455 ))
1456 }
1457 }
1458
1459 #[doc(alias = "pixel-bytes")]
1460 pub fn pixel_bytes(&self) -> Option<glib::Bytes> {
1461 ObjectExt::property(self, "pixel-bytes")
1462 }
1463
1464 /// Calculates the rowstride that an image created with those values would
1465 /// have.
1466 ///
1467 /// This function is useful for front-ends and backends that want to check
1468 /// image values without needing to create a [`Pixbuf`][crate::Pixbuf].
1469 /// ## `colorspace`
1470 /// Color space for image
1471 /// ## `has_alpha`
1472 /// Whether the image should have transparency information
1473 /// ## `bits_per_sample`
1474 /// Number of bits per color sample
1475 /// ## `width`
1476 /// Width of image in pixels, must be > 0
1477 /// ## `height`
1478 /// Height of image in pixels, must be > 0
1479 ///
1480 /// # Returns
1481 ///
1482 /// the rowstride for the given values, or -1 in case of error.
1483 #[doc(alias = "gdk_pixbuf_calculate_rowstride")]
1484 pub fn calculate_rowstride(
1485 colorspace: Colorspace,
1486 has_alpha: bool,
1487 bits_per_sample: i32,
1488 width: i32,
1489 height: i32,
1490 ) -> i32 {
1491 unsafe {
1492 ffi::gdk_pixbuf_calculate_rowstride(
1493 colorspace.into_glib(),
1494 has_alpha.into_glib(),
1495 bits_per_sample,
1496 width,
1497 height,
1498 )
1499 }
1500 }
1501
1502 /// Obtains the available information about the image formats supported
1503 /// by GdkPixbuf.
1504 ///
1505 /// # Returns
1506 ///
1507 /// A list of
1508 /// support image formats.
1509 #[doc(alias = "gdk_pixbuf_get_formats")]
1510 #[doc(alias = "get_formats")]
1511 pub fn formats() -> Vec<PixbufFormat> {
1512 unsafe { FromGlibPtrContainer::from_glib_container(ffi::gdk_pixbuf_get_formats()) }
1513 }
1514
1515 /// Initalizes the gdk-pixbuf loader modules referenced by the `loaders.cache`
1516 /// file present inside that directory.
1517 ///
1518 /// This is to be used by applications that want to ship certain loaders
1519 /// in a different location from the system ones.
1520 ///
1521 /// This is needed when the OS or runtime ships a minimal number of loaders
1522 /// so as to reduce the potential attack surface of carefully crafted image
1523 /// files, especially for uncommon file types. Applications that require
1524 /// broader image file types coverage, such as image viewers, would be
1525 /// expected to ship the gdk-pixbuf modules in a separate location, bundled
1526 /// with the application in a separate directory from the OS or runtime-
1527 /// provided modules.
1528 /// ## `path`
1529 /// Path to directory where the `loaders.cache` is installed
1530 #[cfg(feature = "v2_40")]
1531 #[cfg_attr(docsrs, doc(cfg(feature = "v2_40")))]
1532 #[doc(alias = "gdk_pixbuf_init_modules")]
1533 pub fn init_modules(path: &str) -> Result<(), glib::Error> {
1534 unsafe {
1535 let mut error = std::ptr::null_mut();
1536 let is_ok = ffi::gdk_pixbuf_init_modules(path.to_glib_none().0, &mut error);
1537 debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
1538 if error.is_null() {
1539 Ok(())
1540 } else {
1541 Err(from_glib_full(error))
1542 }
1543 }
1544 }
1545}