i_slint_core/graphics/
image.rs

1// Copyright © SixtyFPS GmbH <info@slint.dev>
2// SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-Royalty-free-2.0 OR LicenseRef-Slint-Software-3.0
3
4/*!
5This module contains image decoding and caching related types for the run-time library.
6*/
7
8use crate::lengths::{PhysicalPx, ScaleFactor};
9use crate::slice::Slice;
10#[allow(unused)]
11use crate::{SharedString, SharedVector};
12
13use super::{IntRect, IntSize};
14use crate::items::{ImageFit, ImageHorizontalAlignment, ImageTiling, ImageVerticalAlignment};
15
16#[cfg(feature = "image-decoders")]
17pub mod cache;
18#[cfg(target_arch = "wasm32")]
19mod htmlimage;
20#[cfg(feature = "svg")]
21mod svg;
22
23#[allow(missing_docs)]
24#[cfg_attr(not(feature = "ffi"), i_slint_core_macros::remove_extern)]
25#[vtable::vtable]
26#[repr(C)]
27pub struct OpaqueImageVTable {
28    drop_in_place: extern "C" fn(VRefMut<OpaqueImageVTable>) -> Layout,
29    dealloc: extern "C" fn(&OpaqueImageVTable, ptr: *mut u8, layout: Layout),
30    /// Returns the image size
31    size: extern "C" fn(VRef<OpaqueImageVTable>) -> IntSize,
32    /// Returns a cache key
33    cache_key: extern "C" fn(VRef<OpaqueImageVTable>) -> ImageCacheKey,
34}
35
36#[cfg(feature = "svg")]
37OpaqueImageVTable_static! {
38    /// VTable for RC wrapped SVG helper struct.
39    pub static PARSED_SVG_VT for svg::ParsedSVG
40}
41
42#[cfg(target_arch = "wasm32")]
43OpaqueImageVTable_static! {
44    /// VTable for RC wrapped HtmlImage helper struct.
45    pub static HTML_IMAGE_VT for htmlimage::HTMLImage
46}
47
48OpaqueImageVTable_static! {
49    /// VTable for RC wrapped SVG helper struct.
50    pub static NINE_SLICE_VT for NineSliceImage
51}
52
53/// SharedPixelBuffer is a container for storing image data as pixels. It is
54/// internally reference counted and cheap to clone.
55///
56/// You can construct a new empty shared pixel buffer with [`SharedPixelBuffer::new`],
57/// or you can clone it from an existing contiguous buffer that you might already have, using
58/// [`SharedPixelBuffer::clone_from_slice`].
59///
60/// See the documentation for [`Image`] for examples how to use this type to integrate
61/// Slint with external rendering functions.
62#[derive(Debug, Clone)]
63#[repr(C)]
64pub struct SharedPixelBuffer<Pixel> {
65    width: u32,
66    height: u32,
67    pub(crate) data: SharedVector<Pixel>,
68}
69
70impl<Pixel> SharedPixelBuffer<Pixel> {
71    /// Returns the width of the image in pixels.
72    pub fn width(&self) -> u32 {
73        self.width
74    }
75
76    /// Returns the height of the image in pixels.
77    pub fn height(&self) -> u32 {
78        self.height
79    }
80
81    /// Returns the size of the image in pixels.
82    pub fn size(&self) -> IntSize {
83        [self.width, self.height].into()
84    }
85}
86
87impl<Pixel: Clone> SharedPixelBuffer<Pixel> {
88    /// Return a mutable slice to the pixel data. If the SharedPixelBuffer was shared, this will make a copy of the buffer.
89    pub fn make_mut_slice(&mut self) -> &mut [Pixel] {
90        self.data.make_mut_slice()
91    }
92}
93
94impl<Pixel: Clone + rgb::Pod> SharedPixelBuffer<Pixel>
95where
96    [Pixel]: rgb::ComponentBytes<u8>,
97{
98    /// Returns the pixels interpreted as raw bytes.
99    pub fn as_bytes(&self) -> &[u8] {
100        use rgb::ComponentBytes;
101        self.data.as_slice().as_bytes()
102    }
103
104    /// Returns the pixels interpreted as raw bytes.
105    pub fn make_mut_bytes(&mut self) -> &mut [u8] {
106        use rgb::ComponentBytes;
107        self.data.make_mut_slice().as_bytes_mut()
108    }
109}
110
111impl<Pixel> SharedPixelBuffer<Pixel> {
112    /// Return a slice to the pixel data.
113    pub fn as_slice(&self) -> &[Pixel] {
114        self.data.as_slice()
115    }
116}
117
118impl<Pixel: Clone + Default> SharedPixelBuffer<Pixel> {
119    /// Creates a new SharedPixelBuffer with the given width and height. Each pixel will be initialized with the value
120    /// that [`Default::default()`] returns for the Pixel type.
121    pub fn new(width: u32, height: u32) -> Self {
122        Self {
123            width,
124            height,
125            data: core::iter::repeat(Pixel::default())
126                .take(width as usize * height as usize)
127                .collect(),
128        }
129    }
130}
131
132impl<Pixel: Clone> SharedPixelBuffer<Pixel> {
133    /// Creates a new SharedPixelBuffer by cloning and converting pixels from an existing
134    /// slice. This function is useful when another crate was used to allocate an image
135    /// and you would like to convert it for use in Slint.
136    pub fn clone_from_slice<SourcePixelType>(
137        pixel_slice: &[SourcePixelType],
138        width: u32,
139        height: u32,
140    ) -> Self
141    where
142        [SourcePixelType]: rgb::AsPixels<Pixel>,
143    {
144        use rgb::AsPixels;
145        Self { width, height, data: pixel_slice.as_pixels().into() }
146    }
147}
148
149/// Convenience alias for a pixel with three color channels (red, green and blue), each
150/// encoded as u8.
151pub type Rgb8Pixel = rgb::RGB8;
152/// Convenience alias for a pixel with four color channels (red, green, blue and alpha), each
153/// encoded as u8.
154pub type Rgba8Pixel = rgb::RGBA8;
155
156/// SharedImageBuffer is a container for images that are stored in CPU accessible memory.
157///
158/// The SharedImageBuffer's variants represent the different common formats for encoding
159/// images in pixels.
160#[derive(Clone, Debug)]
161#[repr(C)]
162/// TODO: Make this non_exhaustive before making the type public!
163pub enum SharedImageBuffer {
164    /// This variant holds the data for an image where each pixel has three color channels (red, green,
165    /// and blue) and each channel is encoded as unsigned byte.
166    RGB8(SharedPixelBuffer<Rgb8Pixel>),
167    /// This variant holds the data for an image where each pixel has four color channels (red, green,
168    /// blue and alpha) and each channel is encoded as unsigned byte.
169    RGBA8(SharedPixelBuffer<Rgba8Pixel>),
170    /// This variant holds the data for an image where each pixel has four color channels (red, green,
171    /// blue and alpha) and each channel is encoded as unsigned byte. In contrast to [`Self::RGBA8`],
172    /// this variant assumes that the alpha channel is also already multiplied to each red, green and blue
173    /// component of each pixel.
174    /// Only construct this format if you know that your pixels are encoded this way. It is more efficient
175    /// for rendering.
176    RGBA8Premultiplied(SharedPixelBuffer<Rgba8Pixel>),
177}
178
179impl SharedImageBuffer {
180    /// Returns the width of the image in pixels.
181    #[inline]
182    pub fn width(&self) -> u32 {
183        match self {
184            Self::RGB8(buffer) => buffer.width(),
185            Self::RGBA8(buffer) => buffer.width(),
186            Self::RGBA8Premultiplied(buffer) => buffer.width(),
187        }
188    }
189
190    /// Returns the height of the image in pixels.
191    #[inline]
192    pub fn height(&self) -> u32 {
193        match self {
194            Self::RGB8(buffer) => buffer.height(),
195            Self::RGBA8(buffer) => buffer.height(),
196            Self::RGBA8Premultiplied(buffer) => buffer.height(),
197        }
198    }
199
200    /// Returns the size of the image in pixels.
201    #[inline]
202    pub fn size(&self) -> IntSize {
203        match self {
204            Self::RGB8(buffer) => buffer.size(),
205            Self::RGBA8(buffer) => buffer.size(),
206            Self::RGBA8Premultiplied(buffer) => buffer.size(),
207        }
208    }
209}
210
211impl PartialEq for SharedImageBuffer {
212    fn eq(&self, other: &Self) -> bool {
213        match self {
214            Self::RGB8(lhs_buffer) => {
215                matches!(other, Self::RGB8(rhs_buffer) if lhs_buffer.data.as_ptr().eq(&rhs_buffer.data.as_ptr()))
216            }
217            Self::RGBA8(lhs_buffer) => {
218                matches!(other, Self::RGBA8(rhs_buffer) if lhs_buffer.data.as_ptr().eq(&rhs_buffer.data.as_ptr()))
219            }
220            Self::RGBA8Premultiplied(lhs_buffer) => {
221                matches!(other, Self::RGBA8Premultiplied(rhs_buffer) if lhs_buffer.data.as_ptr().eq(&rhs_buffer.data.as_ptr()))
222            }
223        }
224    }
225}
226
227#[repr(u8)]
228#[derive(Clone, PartialEq, Debug, Copy)]
229/// The pixel format used for textures.
230pub enum TexturePixelFormat {
231    /// red, green, blue. 24bits.
232    Rgb,
233    /// Red, green, blue, alpha. 32bits.
234    Rgba,
235    /// Red, green, blue, alpha. 32bits. The color are premultiplied by alpha
236    RgbaPremultiplied,
237    /// Alpha map. 8bits. Each pixel is an alpha value. The color is specified separately.
238    AlphaMap,
239    /// Distance field. 8bit interpreted as i8.
240    /// The range is such that i8::MIN corresponds to 3 pixels outside of the shape,
241    /// and i8::MAX corresponds to 3 pixels inside the shape.
242    /// The array must be width * height +1 bytes long. (the extra bit is read but never used)
243    SignedDistanceField,
244}
245
246impl TexturePixelFormat {
247    /// The number of bytes in a pixel
248    pub fn bpp(self) -> usize {
249        match self {
250            TexturePixelFormat::Rgb => 3,
251            TexturePixelFormat::Rgba => 4,
252            TexturePixelFormat::RgbaPremultiplied => 4,
253            TexturePixelFormat::AlphaMap => 1,
254            TexturePixelFormat::SignedDistanceField => 1,
255        }
256    }
257}
258
259#[repr(C)]
260#[derive(Clone, PartialEq, Debug)]
261/// Some raw pixel data which is typically stored in the binary
262pub struct StaticTexture {
263    /// The position and size of the texture within the image
264    pub rect: IntRect,
265    /// The pixel format of this texture
266    pub format: TexturePixelFormat,
267    /// The color, for the alpha map ones
268    pub color: crate::Color,
269    /// index in the data array
270    pub index: usize,
271}
272
273/// A texture is stored in read-only memory and may be composed of sub-textures.
274#[repr(C)]
275#[derive(Clone, PartialEq, Debug)]
276pub struct StaticTextures {
277    /// The total size of the image (this might not be the size of the full image
278    /// as some transparent part are not part of any texture)
279    pub size: IntSize,
280    /// The size of the image before the compiler applied any scaling
281    pub original_size: IntSize,
282    /// The pixel data referenced by the textures
283    pub data: Slice<'static, u8>,
284    /// The list of textures
285    pub textures: Slice<'static, StaticTexture>,
286}
287
288/// A struct that provides a path as a string as well as the last modification
289/// time of the file it points to.
290#[derive(PartialEq, Eq, Debug, Hash, Clone)]
291#[repr(C)]
292#[cfg(feature = "std")]
293pub struct CachedPath {
294    path: SharedString,
295    /// SystemTime since UNIX_EPOC as secs
296    last_modified: u32,
297}
298
299#[cfg(feature = "std")]
300impl CachedPath {
301    fn new<P: AsRef<std::path::Path>>(path: P) -> Self {
302        let path_str = path.as_ref().to_string_lossy().as_ref().into();
303        let timestamp = std::fs::metadata(path)
304            .and_then(|md| md.modified())
305            .unwrap_or(std::time::UNIX_EPOCH)
306            .duration_since(std::time::UNIX_EPOCH)
307            .map(|t| t.as_secs() as u32)
308            .unwrap_or_default();
309        Self { path: path_str, last_modified: timestamp }
310    }
311}
312
313/// ImageCacheKey encapsulates the different ways of indexing images in the
314/// cache of decoded images.
315#[derive(PartialEq, Eq, Debug, Hash, Clone)]
316#[repr(u8)]
317pub enum ImageCacheKey {
318    /// This variant indicates that no image cache key can be created for the image.
319    /// For example this is the case for programmatically created images.
320    Invalid = 0,
321    #[cfg(feature = "std")]
322    /// The image is identified by its path on the file system and the last modification time stamp.
323    Path(CachedPath) = 1,
324    /// The image is identified by a URL.
325    #[cfg(target_arch = "wasm32")]
326    URL(SharedString) = 2,
327    /// The image is identified by the static address of its encoded data.
328    EmbeddedData(usize) = 3,
329}
330
331impl ImageCacheKey {
332    /// Returns a new cache key if decoded image data can be stored in image cache for
333    /// the given ImageInner.
334    pub fn new(resource: &ImageInner) -> Option<Self> {
335        let key = match resource {
336            ImageInner::None => return None,
337            ImageInner::EmbeddedImage { cache_key, .. } => cache_key.clone(),
338            ImageInner::StaticTextures(textures) => {
339                Self::from_embedded_image_data(textures.data.as_slice())
340            }
341            #[cfg(feature = "svg")]
342            ImageInner::Svg(parsed_svg) => parsed_svg.cache_key(),
343            #[cfg(target_arch = "wasm32")]
344            ImageInner::HTMLImage(htmlimage) => Self::URL(htmlimage.source().into()),
345            ImageInner::BackendStorage(x) => vtable::VRc::borrow(x).cache_key(),
346            #[cfg(not(target_arch = "wasm32"))]
347            ImageInner::BorrowedOpenGLTexture(..) => return None,
348            ImageInner::NineSlice(nine) => vtable::VRc::borrow(nine).cache_key(),
349            #[cfg(any(feature = "unstable-wgpu-26", feature = "unstable-wgpu-27"))]
350            ImageInner::WGPUTexture(..) => return None,
351        };
352        if matches!(key, ImageCacheKey::Invalid) {
353            None
354        } else {
355            Some(key)
356        }
357    }
358
359    /// Returns a cache key for static embedded image data.
360    pub fn from_embedded_image_data(data: &'static [u8]) -> Self {
361        Self::EmbeddedData(data.as_ptr() as usize)
362    }
363}
364
365/// Represent a nine-slice image with the base image and the 4 borders
366pub struct NineSliceImage(pub ImageInner, pub [u16; 4]);
367
368impl NineSliceImage {
369    /// return the backing Image
370    pub fn image(&self) -> Image {
371        Image(self.0.clone())
372    }
373}
374
375impl OpaqueImage for NineSliceImage {
376    fn size(&self) -> IntSize {
377        self.0.size()
378    }
379    fn cache_key(&self) -> ImageCacheKey {
380        ImageCacheKey::new(&self.0).unwrap_or(ImageCacheKey::Invalid)
381    }
382}
383
384/// Represents a `wgpu::Texture` for each version of WGPU we support.
385#[cfg(any(feature = "unstable-wgpu-26", feature = "unstable-wgpu-27"))]
386#[derive(Clone, Debug)]
387pub enum WGPUTexture {
388    /// A texture for WGPU version 26.
389    #[cfg(feature = "unstable-wgpu-26")]
390    WGPU26Texture(wgpu_26::Texture),
391    /// A texture for WGPU version 27.
392    #[cfg(feature = "unstable-wgpu-27")]
393    WGPU27Texture(wgpu_27::Texture),
394}
395
396#[cfg(any(feature = "unstable-wgpu-26", feature = "unstable-wgpu-27"))]
397impl OpaqueImage for WGPUTexture {
398    fn size(&self) -> IntSize {
399        match self {
400            #[cfg(feature = "unstable-wgpu-26")]
401            Self::WGPU26Texture(texture) => {
402                let size = texture.size();
403                (size.width, size.height).into()
404            }
405            #[cfg(feature = "unstable-wgpu-27")]
406            Self::WGPU27Texture(texture) => {
407                let size = texture.size();
408                (size.width, size.height).into()
409            }
410        }
411    }
412    fn cache_key(&self) -> ImageCacheKey {
413        ImageCacheKey::Invalid
414    }
415}
416
417/// A resource is a reference to binary data, for example images. They can be accessible on the file
418/// system or embedded in the resulting binary. Or they might be URLs to a web server and a downloaded
419/// is necessary before they can be used.
420/// cbindgen:prefix-with-name
421#[derive(Clone, Debug, Default)]
422#[repr(u8)]
423#[allow(missing_docs)]
424pub enum ImageInner {
425    /// A resource that does not represent any data.
426    #[default]
427    None = 0,
428    EmbeddedImage {
429        cache_key: ImageCacheKey,
430        buffer: SharedImageBuffer,
431    } = 1,
432    #[cfg(feature = "svg")]
433    Svg(vtable::VRc<OpaqueImageVTable, svg::ParsedSVG>) = 2,
434    StaticTextures(&'static StaticTextures) = 3,
435    #[cfg(target_arch = "wasm32")]
436    HTMLImage(vtable::VRc<OpaqueImageVTable, htmlimage::HTMLImage>) = 4,
437    BackendStorage(vtable::VRc<OpaqueImageVTable>) = 5,
438    #[cfg(not(target_arch = "wasm32"))]
439    BorrowedOpenGLTexture(BorrowedOpenGLTexture) = 6,
440    NineSlice(vtable::VRc<OpaqueImageVTable, NineSliceImage>) = 7,
441    #[cfg(any(feature = "unstable-wgpu-26", feature = "unstable-wgpu-27"))]
442    WGPUTexture(WGPUTexture) = 8,
443}
444
445impl ImageInner {
446    /// Return or render the image into a buffer
447    ///
448    /// `target_size_for_scalable_source` is the size to use if the image is scalable.
449    /// (when unspecified, will default to the intrinsic size of the image)
450    ///
451    /// Returns None if the image can't be rendered in a buffer or if the image is empty
452    pub fn render_to_buffer(
453        &self,
454        _target_size_for_scalable_source: Option<euclid::Size2D<u32, PhysicalPx>>,
455    ) -> Option<SharedImageBuffer> {
456        match self {
457            ImageInner::EmbeddedImage { buffer, .. } => Some(buffer.clone()),
458            #[cfg(feature = "svg")]
459            ImageInner::Svg(svg) => match svg.render(_target_size_for_scalable_source) {
460                Ok(b) => Some(b),
461                // Ignore error when rendering a 0x0 image, that's just an empty image
462                Err(resvg::usvg::Error::InvalidSize) => None,
463                Err(err) => {
464                    std::eprintln!("Error rendering SVG: {err}");
465                    None
466                }
467            },
468            ImageInner::StaticTextures(ts) => {
469                let mut buffer =
470                    SharedPixelBuffer::<Rgba8Pixel>::new(ts.size.width, ts.size.height);
471                let stride = buffer.width() as usize;
472                let slice = buffer.make_mut_slice();
473                for t in ts.textures.iter() {
474                    let rect = t.rect.to_usize();
475                    for y in 0..rect.height() {
476                        let slice = &mut slice[(rect.min_y() + y) * stride..][rect.x_range()];
477                        let source = &ts.data[t.index + y * rect.width() * t.format.bpp()..];
478                        match t.format {
479                            TexturePixelFormat::Rgb => {
480                                let mut iter = source.chunks_exact(3).map(|p| Rgba8Pixel {
481                                    r: p[0],
482                                    g: p[1],
483                                    b: p[2],
484                                    a: 255,
485                                });
486                                slice.fill_with(|| iter.next().unwrap());
487                            }
488                            TexturePixelFormat::RgbaPremultiplied => {
489                                let mut iter = source.chunks_exact(4).map(|p| Rgba8Pixel {
490                                    r: p[0],
491                                    g: p[1],
492                                    b: p[2],
493                                    a: p[3],
494                                });
495                                slice.fill_with(|| iter.next().unwrap());
496                            }
497                            TexturePixelFormat::Rgba => {
498                                let mut iter = source.chunks_exact(4).map(|p| {
499                                    let a = p[3];
500                                    Rgba8Pixel {
501                                        r: (p[0] as u16 * a as u16 / 255) as u8,
502                                        g: (p[1] as u16 * a as u16 / 255) as u8,
503                                        b: (p[2] as u16 * a as u16 / 255) as u8,
504                                        a,
505                                    }
506                                });
507                                slice.fill_with(|| iter.next().unwrap());
508                            }
509                            TexturePixelFormat::AlphaMap => {
510                                let col = t.color.to_argb_u8();
511                                let mut iter = source.iter().map(|p| {
512                                    let a = *p as u32 * col.alpha as u32;
513                                    Rgba8Pixel {
514                                        r: (col.red as u32 * a / (255 * 255)) as u8,
515                                        g: (col.green as u32 * a / (255 * 255)) as u8,
516                                        b: (col.blue as u32 * a / (255 * 255)) as u8,
517                                        a: (a / 255) as u8,
518                                    }
519                                });
520                                slice.fill_with(|| iter.next().unwrap());
521                            }
522                            TexturePixelFormat::SignedDistanceField => {
523                                todo!("converting from a signed distance field to an image")
524                            }
525                        };
526                    }
527                }
528                Some(SharedImageBuffer::RGBA8Premultiplied(buffer))
529            }
530            ImageInner::NineSlice(nine) => nine.0.render_to_buffer(None),
531            _ => None,
532        }
533    }
534
535    /// Returns true if the image is an SVG (either backed by resvg or HTML image wrapper).
536    pub fn is_svg(&self) -> bool {
537        match self {
538            #[cfg(feature = "svg")]
539            Self::Svg(_) => true,
540            #[cfg(target_arch = "wasm32")]
541            Self::HTMLImage(html_image) => html_image.is_svg(),
542            _ => false,
543        }
544    }
545
546    /// Return the image size
547    pub fn size(&self) -> IntSize {
548        match self {
549            ImageInner::None => Default::default(),
550            ImageInner::EmbeddedImage { buffer, .. } => buffer.size(),
551            ImageInner::StaticTextures(StaticTextures { original_size, .. }) => *original_size,
552            #[cfg(feature = "svg")]
553            ImageInner::Svg(svg) => svg.size(),
554            #[cfg(target_arch = "wasm32")]
555            ImageInner::HTMLImage(htmlimage) => htmlimage.size().unwrap_or_default(),
556            ImageInner::BackendStorage(x) => vtable::VRc::borrow(x).size(),
557            #[cfg(not(target_arch = "wasm32"))]
558            ImageInner::BorrowedOpenGLTexture(BorrowedOpenGLTexture { size, .. }) => *size,
559            ImageInner::NineSlice(nine) => nine.0.size(),
560            #[cfg(any(feature = "unstable-wgpu-26", feature = "unstable-wgpu-27"))]
561            ImageInner::WGPUTexture(texture) => texture.size(),
562        }
563    }
564}
565
566impl PartialEq for ImageInner {
567    fn eq(&self, other: &Self) -> bool {
568        match (self, other) {
569            (
570                Self::EmbeddedImage { cache_key: l_cache_key, buffer: l_buffer },
571                Self::EmbeddedImage { cache_key: r_cache_key, buffer: r_buffer },
572            ) => l_cache_key == r_cache_key && l_buffer == r_buffer,
573            #[cfg(feature = "svg")]
574            (Self::Svg(l0), Self::Svg(r0)) => vtable::VRc::ptr_eq(l0, r0),
575            (Self::StaticTextures(l0), Self::StaticTextures(r0)) => l0 == r0,
576            #[cfg(target_arch = "wasm32")]
577            (Self::HTMLImage(l0), Self::HTMLImage(r0)) => vtable::VRc::ptr_eq(l0, r0),
578            (Self::BackendStorage(l0), Self::BackendStorage(r0)) => vtable::VRc::ptr_eq(l0, r0),
579            #[cfg(not(target_arch = "wasm32"))]
580            (Self::BorrowedOpenGLTexture(l0), Self::BorrowedOpenGLTexture(r0)) => l0 == r0,
581            (Self::NineSlice(l), Self::NineSlice(r)) => l.0 == r.0 && l.1 == r.1,
582            _ => false,
583        }
584    }
585}
586
587impl<'a> From<&'a Image> for &'a ImageInner {
588    fn from(other: &'a Image) -> Self {
589        &other.0
590    }
591}
592
593/// Error generated if an image cannot be loaded for any reasons.
594#[derive(Default, Debug, PartialEq)]
595pub struct LoadImageError(());
596
597impl core::fmt::Display for LoadImageError {
598    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
599        f.write_str("The image cannot be loaded")
600    }
601}
602
603#[cfg(feature = "std")]
604impl std::error::Error for LoadImageError {}
605
606/// An image type that can be displayed by the Image element. You can construct
607/// Image objects from a path to an image file on disk, using [`Self::load_from_path`].
608///
609/// Another typical use-case is to render the image content with Rust code.
610/// For this it's most efficient to create a new SharedPixelBuffer with the known dimensions
611/// and pass the mutable slice to your rendering function. Afterwards you can create an
612/// Image.
613///
614/// The following example creates a 320x200 RGB pixel buffer and calls an external
615/// low_level_render() function to draw a shape into it. Finally the result is
616/// stored in an Image with [`Self::from_rgb8()`]:
617/// ```
618/// # use i_slint_core::graphics::{SharedPixelBuffer, Image, Rgb8Pixel};
619///
620/// fn low_level_render(width: u32, height: u32, buffer: &mut [u8]) {
621///     // render beautiful circle or other shapes here
622/// }
623///
624/// let mut pixel_buffer = SharedPixelBuffer::<Rgb8Pixel>::new(320, 200);
625///
626/// low_level_render(pixel_buffer.width(), pixel_buffer.height(),
627///                  pixel_buffer.make_mut_bytes());
628///
629/// let image = Image::from_rgb8(pixel_buffer);
630/// ```
631///
632/// Another use-case is to import existing image data into Slint, by
633/// creating a new Image through cloning of another image type.
634///
635/// The following example uses the popular [image crate](https://docs.rs/image/) to
636/// load a `.png` file from disk, apply brightening filter on it and then import
637/// it into an [`Image`]:
638/// ```no_run
639/// # use i_slint_core::graphics::{SharedPixelBuffer, Image, Rgba8Pixel};
640/// let mut cat_image = image::open("cat.png").expect("Error loading cat image").into_rgba8();
641///
642/// image::imageops::colorops::brighten_in_place(&mut cat_image, 20);
643///
644/// let buffer = SharedPixelBuffer::<Rgba8Pixel>::clone_from_slice(
645///     cat_image.as_raw(),
646///     cat_image.width(),
647///     cat_image.height(),
648/// );
649/// let image = Image::from_rgba8(buffer);
650/// ```
651///
652/// A popular software (CPU) rendering library in Rust is tiny-skia. The following example shows
653/// how to use tiny-skia to render into a [`SharedPixelBuffer`]:
654/// ```
655/// # use i_slint_core::graphics::{SharedPixelBuffer, Image, Rgba8Pixel};
656/// let mut pixel_buffer = SharedPixelBuffer::<Rgba8Pixel>::new(640, 480);
657/// let width = pixel_buffer.width();
658/// let height = pixel_buffer.height();
659/// let mut pixmap = tiny_skia::PixmapMut::from_bytes(
660///     pixel_buffer.make_mut_bytes(), width, height
661/// ).unwrap();
662/// pixmap.fill(tiny_skia::Color::TRANSPARENT);
663///
664/// let circle = tiny_skia::PathBuilder::from_circle(320., 240., 150.).unwrap();
665///
666/// let mut paint = tiny_skia::Paint::default();
667/// paint.shader = tiny_skia::LinearGradient::new(
668///     tiny_skia::Point::from_xy(100.0, 100.0),
669///     tiny_skia::Point::from_xy(400.0, 400.0),
670///     vec![
671///         tiny_skia::GradientStop::new(0.0, tiny_skia::Color::from_rgba8(50, 127, 150, 200)),
672///         tiny_skia::GradientStop::new(1.0, tiny_skia::Color::from_rgba8(220, 140, 75, 180)),
673///     ],
674///     tiny_skia::SpreadMode::Pad,
675///     tiny_skia::Transform::identity(),
676/// ).unwrap();
677///
678/// pixmap.fill_path(&circle, &paint, tiny_skia::FillRule::Winding, Default::default(), None);
679///
680/// let image = Image::from_rgba8_premultiplied(pixel_buffer);
681/// ```
682///
683/// ### Sending Image to a thread
684///
685/// `Image` is not [`Send`], because it uses internal cache that are local to the Slint thread.
686/// If you want to create image data in a thread and send that to slint, construct the
687/// [`SharedPixelBuffer`] in a thread, and send that to Slint's UI thread.
688///
689/// ```rust,no_run
690/// # use i_slint_core::graphics::{SharedPixelBuffer, Image, Rgba8Pixel};
691/// std::thread::spawn(move || {
692///     let mut pixel_buffer = SharedPixelBuffer::<Rgba8Pixel>::new(640, 480);
693///     // ... fill the pixel_buffer with data as shown in the previous example ...
694///     slint::invoke_from_event_loop(move || {
695///         // this will run in the Slint's UI thread
696///         let image = Image::from_rgba8_premultiplied(pixel_buffer);
697///         // ... use the image, eg:
698///         // my_ui_handle.upgrade().unwrap().set_image(image);
699///     });
700/// });
701/// ```
702#[repr(transparent)]
703#[derive(Default, Clone, Debug, PartialEq, derive_more::From)]
704pub struct Image(pub(crate) ImageInner);
705
706impl Image {
707    #[cfg(feature = "image-decoders")]
708    /// Load an Image from a path to a file containing an image.
709    ///
710    /// Supported formats are SVG, PNG and JPEG.
711    /// Enable support for additional formats supported by the [`image` crate](https://crates.io/crates/image) (
712    /// AVIF, BMP, DDS, Farbfeld, GIF, HDR, ICO, JPEG, EXR, PNG, PNM, QOI, TGA, TIFF, WebP)
713    /// by enabling the `image-default-formats` cargo feature.
714    pub fn load_from_path(path: &std::path::Path) -> Result<Self, LoadImageError> {
715        self::cache::IMAGE_CACHE.with(|global_cache| {
716            let path: SharedString = path.to_str().ok_or(LoadImageError(()))?.into();
717            global_cache.borrow_mut().load_image_from_path(&path).ok_or(LoadImageError(()))
718        })
719    }
720
721    /// Creates a new Image from the specified shared pixel buffer, where each pixel has three color
722    /// channels (red, green and blue) encoded as u8.
723    pub fn from_rgb8(buffer: SharedPixelBuffer<Rgb8Pixel>) -> Self {
724        Image(ImageInner::EmbeddedImage {
725            cache_key: ImageCacheKey::Invalid,
726            buffer: SharedImageBuffer::RGB8(buffer),
727        })
728    }
729
730    /// Creates a new Image from the specified shared pixel buffer, where each pixel has four color
731    /// channels (red, green, blue and alpha) encoded as u8.
732    pub fn from_rgba8(buffer: SharedPixelBuffer<Rgba8Pixel>) -> Self {
733        Image(ImageInner::EmbeddedImage {
734            cache_key: ImageCacheKey::Invalid,
735            buffer: SharedImageBuffer::RGBA8(buffer),
736        })
737    }
738
739    /// Creates a new Image from the specified shared pixel buffer, where each pixel has four color
740    /// channels (red, green, blue and alpha) encoded as u8 and, in contrast to [`Self::from_rgba8`],
741    /// the alpha channel is also assumed to be multiplied to the red, green and blue channels.
742    ///
743    /// Only construct an Image with this function if you know that your pixels are encoded this way.
744    pub fn from_rgba8_premultiplied(buffer: SharedPixelBuffer<Rgba8Pixel>) -> Self {
745        Image(ImageInner::EmbeddedImage {
746            cache_key: ImageCacheKey::Invalid,
747            buffer: SharedImageBuffer::RGBA8Premultiplied(buffer),
748        })
749    }
750
751    /// Returns the pixel buffer for the Image if available in RGB format without alpha.
752    /// Returns None if the pixels cannot be obtained, for example when the image was created from borrowed OpenGL textures.
753    pub fn to_rgb8(&self) -> Option<SharedPixelBuffer<Rgb8Pixel>> {
754        self.0.render_to_buffer(None).and_then(|image| match image {
755            SharedImageBuffer::RGB8(buffer) => Some(buffer),
756            _ => None,
757        })
758    }
759
760    /// Returns the pixel buffer for the Image if available in RGBA format.
761    /// Returns None if the pixels cannot be obtained, for example when the image was created from borrowed OpenGL textures.
762    pub fn to_rgba8(&self) -> Option<SharedPixelBuffer<Rgba8Pixel>> {
763        self.0.render_to_buffer(None).map(|image| match image {
764            SharedImageBuffer::RGB8(buffer) => SharedPixelBuffer::<Rgba8Pixel> {
765                width: buffer.width,
766                height: buffer.height,
767                data: buffer.data.into_iter().map(Into::into).collect(),
768            },
769            SharedImageBuffer::RGBA8(buffer) => buffer,
770            SharedImageBuffer::RGBA8Premultiplied(buffer) => SharedPixelBuffer::<Rgba8Pixel> {
771                width: buffer.width,
772                height: buffer.height,
773                data: buffer
774                    .data
775                    .into_iter()
776                    .map(|rgba_premul| {
777                        if rgba_premul.a == 0 {
778                            Rgba8Pixel::new(0, 0, 0, 0)
779                        } else {
780                            let af = rgba_premul.a as f32 / 255.0;
781                            Rgba8Pixel {
782                                r: (rgba_premul.r as f32 * 255. / af) as u8,
783                                g: (rgba_premul.g as f32 * 255. / af) as u8,
784                                b: (rgba_premul.b as f32 * 255. / af) as u8,
785                                a: rgba_premul.a,
786                            }
787                        }
788                    })
789                    .collect(),
790            },
791        })
792    }
793
794    /// Returns the pixel buffer for the Image if available in RGBA format, with the alpha channel pre-multiplied
795    /// to the red, green, and blue channels.
796    /// Returns None if the pixels cannot be obtained, for example when the image was created from borrowed OpenGL textures.
797    pub fn to_rgba8_premultiplied(&self) -> Option<SharedPixelBuffer<Rgba8Pixel>> {
798        self.0.render_to_buffer(None).map(|image| match image {
799            SharedImageBuffer::RGB8(buffer) => SharedPixelBuffer::<Rgba8Pixel> {
800                width: buffer.width,
801                height: buffer.height,
802                data: buffer.data.into_iter().map(Into::into).collect(),
803            },
804            SharedImageBuffer::RGBA8(buffer) => SharedPixelBuffer::<Rgba8Pixel> {
805                width: buffer.width,
806                height: buffer.height,
807                data: buffer
808                    .data
809                    .into_iter()
810                    .map(|rgba| {
811                        if rgba.a == 255 {
812                            rgba
813                        } else {
814                            let af = rgba.a as f32 / 255.0;
815                            Rgba8Pixel {
816                                r: (rgba.r as f32 * af / 255.) as u8,
817                                g: (rgba.g as f32 * af / 255.) as u8,
818                                b: (rgba.b as f32 * af / 255.) as u8,
819                                a: rgba.a,
820                            }
821                        }
822                    })
823                    .collect(),
824            },
825            SharedImageBuffer::RGBA8Premultiplied(buffer) => buffer,
826        })
827    }
828
829    /// Returns the [WGPU](http://wgpu.rs) 26.x texture that this image wraps; returns None if the image does not
830    /// hold such a previously wrapped texture.
831    ///
832    /// *Note*: This function is behind a feature flag and may be removed or changed in future minor releases,
833    ///         as new major WGPU releases become available.
834    #[cfg(feature = "unstable-wgpu-26")]
835    pub fn to_wgpu_26_texture(&self) -> Option<wgpu_26::Texture> {
836        match &self.0 {
837            ImageInner::WGPUTexture(WGPUTexture::WGPU26Texture(texture)) => Some(texture.clone()),
838            _ => None,
839        }
840    }
841
842    /// Returns the [WGPU](http://wgpu.rs) 27.x texture that this image wraps; returns None if the image does not
843    /// hold such a previously wrapped texture.
844    ///
845    /// *Note*: This function is behind a feature flag and may be removed or changed in future minor releases,
846    ///         as new major WGPU releases become available.
847    #[cfg(feature = "unstable-wgpu-27")]
848    pub fn to_wgpu_27_texture(&self) -> Option<wgpu_27::Texture> {
849        match &self.0 {
850            ImageInner::WGPUTexture(WGPUTexture::WGPU27Texture(texture)) => Some(texture.clone()),
851            _ => None,
852        }
853    }
854
855    /// Creates a new Image from an existing OpenGL texture. The texture remains borrowed by Slint
856    /// for the duration of being used for rendering, such as when assigned as source property to
857    /// an `Image` element. It's the application's responsibility to delete the texture when it is
858    /// not used anymore.
859    ///
860    /// The texture must be bindable against the `GL_TEXTURE_2D` target, have `GL_RGBA` as format
861    /// for the pixel data.
862    ///
863    /// When Slint renders the texture, it assumes that the origin of the texture is at the top-left.
864    /// This is different from the default OpenGL coordinate system.
865    ///
866    /// # Safety
867    ///
868    /// This function is unsafe because invalid texture ids may lead to undefined behavior in OpenGL
869    /// drivers. A valid texture id is one that was created by the same OpenGL context that is
870    /// current during any of the invocations of the callback set on [`Window::set_rendering_notifier()`](crate::api::Window::set_rendering_notifier).
871    /// OpenGL contexts between instances of [`slint::Window`](crate::api::Window) are not sharing resources. Consequently
872    /// [`slint::Image`](Self) objects created from borrowed OpenGL textures cannot be shared between
873    /// different windows.
874    #[allow(unsafe_code)]
875    #[cfg(not(target_arch = "wasm32"))]
876    #[deprecated(since = "1.2.0", note = "Use BorrowedOpenGLTextureBuilder")]
877    pub unsafe fn from_borrowed_gl_2d_rgba_texture(
878        texture_id: core::num::NonZeroU32,
879        size: IntSize,
880    ) -> Self {
881        BorrowedOpenGLTextureBuilder::new_gl_2d_rgba_texture(texture_id, size).build()
882    }
883
884    /// Creates a new Image from the specified buffer, which contains SVG raw data.
885    #[cfg(feature = "svg")]
886    pub fn load_from_svg_data(buffer: &[u8]) -> Result<Self, LoadImageError> {
887        let cache_key = ImageCacheKey::Invalid;
888        Ok(Image(ImageInner::Svg(vtable::VRc::new(
889            svg::load_from_data(buffer, cache_key).map_err(|_| LoadImageError(()))?,
890        ))))
891    }
892
893    /// Sets the nine-slice edges of the image.
894    ///
895    /// [Nine-slice scaling](https://en.wikipedia.org/wiki/9-slice_scaling) is a method for scaling
896    /// images in such a way that the corners are not distorted.
897    /// The arguments define the pixel sizes of the edges that cut the image into 9 slices.
898    pub fn set_nine_slice_edges(&mut self, top: u16, right: u16, bottom: u16, left: u16) {
899        if top == 0 && left == 0 && right == 0 && bottom == 0 {
900            if let ImageInner::NineSlice(n) = &self.0 {
901                self.0 = n.0.clone();
902            }
903        } else {
904            let array = [top, right, bottom, left];
905            let inner = if let ImageInner::NineSlice(n) = &mut self.0 {
906                n.0.clone()
907            } else {
908                self.0.clone()
909            };
910            self.0 = ImageInner::NineSlice(vtable::VRc::new(NineSliceImage(inner, array)));
911        }
912    }
913
914    /// Returns the size of the Image in pixels.
915    pub fn size(&self) -> IntSize {
916        self.0.size()
917    }
918
919    #[cfg(feature = "std")]
920    /// Returns the path of the image on disk, if it was constructed via [`Self::load_from_path`].
921    ///
922    /// For example:
923    /// ```
924    /// # use std::path::Path;
925    /// # use i_slint_core::graphics::*;
926    /// let path_buf = Path::new(env!("CARGO_MANIFEST_DIR"))
927    ///     .join("../../demos/printerdemo/ui/images/cat.jpg");
928    /// let image = Image::load_from_path(&path_buf).unwrap();
929    /// assert_eq!(image.path(), Some(path_buf.as_path()));
930    /// ```
931    pub fn path(&self) -> Option<&std::path::Path> {
932        match &self.0 {
933            ImageInner::EmbeddedImage {
934                cache_key: ImageCacheKey::Path(CachedPath { path, .. }),
935                ..
936            } => Some(std::path::Path::new(path.as_str())),
937            ImageInner::NineSlice(nine) => match &nine.0 {
938                ImageInner::EmbeddedImage {
939                    cache_key: ImageCacheKey::Path(CachedPath { path, .. }),
940                    ..
941                } => Some(std::path::Path::new(path.as_str())),
942                _ => None,
943            },
944            _ => None,
945        }
946    }
947}
948
949/// This enum describes the origin to use when rendering a borrowed OpenGL texture.
950/// Use this with [`BorrowedOpenGLTextureBuilder::origin`].
951#[derive(Copy, Clone, Debug, PartialEq, Default)]
952#[repr(u8)]
953#[non_exhaustive]
954pub enum BorrowedOpenGLTextureOrigin {
955    /// The top-left of the texture is the top-left of the texture drawn on the screen.
956    #[default]
957    TopLeft,
958    /// The bottom-left of the texture is the top-left of the texture draw on the screen,
959    /// flipping it vertically.
960    BottomLeft,
961}
962
963/// Factory to create [`slint::Image`](crate::graphics::Image) from an existing OpenGL texture.
964///
965/// Methods can be chained on it in order to configure it.
966///
967///  * `origin`: Change the texture's origin when rendering (default: TopLeft).
968///
969/// Complete the builder by calling [`Self::build()`] to create a [`slint::Image`](crate::graphics::Image):
970///
971/// ```
972/// # use i_slint_core::graphics::{BorrowedOpenGLTextureBuilder, Image, IntSize, BorrowedOpenGLTextureOrigin};
973/// # let texture_id = core::num::NonZeroU32::new(1).unwrap();
974/// # let size = IntSize::new(100, 100);
975/// let builder = unsafe { BorrowedOpenGLTextureBuilder::new_gl_2d_rgba_texture(texture_id, size) }
976///              .origin(BorrowedOpenGLTextureOrigin::TopLeft);
977///
978/// let image: slint::Image = builder.build();
979/// ```
980#[cfg(not(target_arch = "wasm32"))]
981pub struct BorrowedOpenGLTextureBuilder(BorrowedOpenGLTexture);
982
983#[cfg(not(target_arch = "wasm32"))]
984impl BorrowedOpenGLTextureBuilder {
985    /// Generates the base configuration for a borrowed OpenGL texture.
986    ///
987    /// The texture must be bindable against the `GL_TEXTURE_2D` target, have `GL_RGBA` as format
988    /// for the pixel data.
989    ///
990    /// By default, when Slint renders the texture, it assumes that the origin of the texture is at the top-left.
991    /// This is different from the default OpenGL coordinate system. Use the `mirror_vertically` function
992    /// to reconfigure this.
993    ///
994    /// # Safety
995    ///
996    /// This function is unsafe because invalid texture ids may lead to undefined behavior in OpenGL
997    /// drivers. A valid texture id is one that was created by the same OpenGL context that is
998    /// current during any of the invocations of the callback set on [`Window::set_rendering_notifier()`](crate::api::Window::set_rendering_notifier).
999    /// OpenGL contexts between instances of [`slint::Window`](crate::api::Window) are not sharing resources. Consequently
1000    /// [`slint::Image`](Self) objects created from borrowed OpenGL textures cannot be shared between
1001    /// different windows.
1002    #[allow(unsafe_code)]
1003    pub unsafe fn new_gl_2d_rgba_texture(texture_id: core::num::NonZeroU32, size: IntSize) -> Self {
1004        Self(BorrowedOpenGLTexture { texture_id, size, origin: Default::default() })
1005    }
1006
1007    /// Configures the texture to be rendered vertically mirrored.
1008    pub fn origin(mut self, origin: BorrowedOpenGLTextureOrigin) -> Self {
1009        self.0.origin = origin;
1010        self
1011    }
1012
1013    /// Completes the process of building a slint::Image that holds a borrowed OpenGL texture.
1014    pub fn build(self) -> Image {
1015        Image(ImageInner::BorrowedOpenGLTexture(self.0))
1016    }
1017}
1018
1019/// Load an image from an image embedded in the binary.
1020/// This is called by the generated code.
1021#[cfg(feature = "image-decoders")]
1022pub fn load_image_from_embedded_data(data: Slice<'static, u8>, format: Slice<'_, u8>) -> Image {
1023    self::cache::IMAGE_CACHE.with(|global_cache| {
1024        global_cache.borrow_mut().load_image_from_embedded_data(data, format).unwrap_or_default()
1025    })
1026}
1027
1028#[test]
1029fn test_image_size_from_buffer_without_backend() {
1030    {
1031        assert_eq!(Image::default().size(), Default::default());
1032        assert!(Image::default().to_rgb8().is_none());
1033        assert!(Image::default().to_rgba8().is_none());
1034        assert!(Image::default().to_rgba8_premultiplied().is_none());
1035    }
1036    {
1037        let buffer = SharedPixelBuffer::<Rgb8Pixel>::new(320, 200);
1038        let image = Image::from_rgb8(buffer.clone());
1039        assert_eq!(image.size(), [320, 200].into());
1040        assert_eq!(image.to_rgb8().as_ref().map(|b| b.as_slice()), Some(buffer.as_slice()));
1041    }
1042}
1043
1044#[cfg(feature = "svg")]
1045#[test]
1046fn test_image_size_from_svg() {
1047    let simple_svg = r#"<svg width="320" height="200" xmlns="http://www.w3.org/2000/svg"></svg>"#;
1048    let image = Image::load_from_svg_data(simple_svg.as_bytes()).unwrap();
1049    assert_eq!(image.size(), [320, 200].into());
1050    assert_eq!(image.to_rgba8().unwrap().size(), image.size());
1051}
1052
1053#[cfg(feature = "svg")]
1054#[test]
1055fn test_image_invalid_svg() {
1056    let invalid_svg = r#"AaBbCcDd"#;
1057    let result = Image::load_from_svg_data(invalid_svg.as_bytes());
1058    assert!(result.is_err());
1059}
1060
1061/// The result of the fit function
1062#[derive(Debug)]
1063pub struct FitResult {
1064    /// The clip rect in the source image (in source image coordinate)
1065    pub clip_rect: IntRect,
1066    /// The scale to apply to go from the source to the target horizontally
1067    pub source_to_target_x: f32,
1068    /// The scale to apply to go from the source to the target vertically
1069    pub source_to_target_y: f32,
1070    /// The size of the target
1071    pub size: euclid::Size2D<f32, PhysicalPx>,
1072    /// The offset in the target in which we draw the image
1073    pub offset: euclid::Point2D<f32, PhysicalPx>,
1074    /// When Some, it means the image should be tiled instead of stretched to the target
1075    /// but still scaled with the source_to_target_x and source_to_target_y factor
1076    /// The point is the coordinate within the image's clip_rect of the pixel at the offset
1077    pub tiled: Option<euclid::default::Point2D<u32>>,
1078}
1079
1080impl FitResult {
1081    fn adjust_for_tiling(
1082        self,
1083        ratio: f32,
1084        alignment: (ImageHorizontalAlignment, ImageVerticalAlignment),
1085        tiling: (ImageTiling, ImageTiling),
1086    ) -> Self {
1087        let mut r = self;
1088        let mut tiled = euclid::Point2D::default();
1089        let target = r.size;
1090        let o = r.clip_rect.size.cast::<f32>();
1091        match tiling.0 {
1092            ImageTiling::None => {
1093                r.size.width = o.width * r.source_to_target_x;
1094                if (o.width as f32) > target.width / r.source_to_target_x {
1095                    let diff = (o.width as f32 - target.width / r.source_to_target_x) as i32;
1096                    r.clip_rect.size.width -= diff;
1097                    r.clip_rect.origin.x += match alignment.0 {
1098                        ImageHorizontalAlignment::Center => diff / 2,
1099                        ImageHorizontalAlignment::Left => 0,
1100                        ImageHorizontalAlignment::Right => diff,
1101                    };
1102                    r.size.width = target.width;
1103                } else if (o.width as f32) < target.width / r.source_to_target_x {
1104                    r.offset.x += match alignment.0 {
1105                        ImageHorizontalAlignment::Center => {
1106                            (target.width - o.width as f32 * r.source_to_target_x) / 2.
1107                        }
1108                        ImageHorizontalAlignment::Left => 0.,
1109                        ImageHorizontalAlignment::Right => {
1110                            target.width - o.width as f32 * r.source_to_target_x
1111                        }
1112                    };
1113                }
1114            }
1115            ImageTiling::Repeat => {
1116                tiled.x = match alignment.0 {
1117                    ImageHorizontalAlignment::Left => 0,
1118                    ImageHorizontalAlignment::Center => {
1119                        ((o.width - target.width / ratio) / 2.).rem_euclid(o.width) as u32
1120                    }
1121                    ImageHorizontalAlignment::Right => {
1122                        (-target.width / ratio).rem_euclid(o.width) as u32
1123                    }
1124                };
1125                r.source_to_target_x = ratio;
1126            }
1127            ImageTiling::Round => {
1128                if target.width / ratio <= o.width * 1.5 {
1129                    r.source_to_target_x = target.width / o.width;
1130                } else {
1131                    let mut rem = (target.width / ratio).rem_euclid(o.width);
1132                    if rem > o.width / 2. {
1133                        rem -= o.width;
1134                    }
1135                    r.source_to_target_x = ratio * target.width / (target.width - rem * ratio);
1136                }
1137            }
1138        }
1139
1140        match tiling.1 {
1141            ImageTiling::None => {
1142                r.size.height = o.height * r.source_to_target_y;
1143                if (o.height as f32) > target.height / r.source_to_target_y {
1144                    let diff = (o.height as f32 - target.height / r.source_to_target_y) as i32;
1145                    r.clip_rect.size.height -= diff;
1146                    r.clip_rect.origin.y += match alignment.1 {
1147                        ImageVerticalAlignment::Center => diff / 2,
1148                        ImageVerticalAlignment::Top => 0,
1149                        ImageVerticalAlignment::Bottom => diff,
1150                    };
1151                    r.size.height = target.height;
1152                } else if (o.height as f32) < target.height / r.source_to_target_y {
1153                    r.offset.y += match alignment.1 {
1154                        ImageVerticalAlignment::Center => {
1155                            (target.height - o.height as f32 * r.source_to_target_y) / 2.
1156                        }
1157                        ImageVerticalAlignment::Top => 0.,
1158                        ImageVerticalAlignment::Bottom => {
1159                            target.height - o.height as f32 * r.source_to_target_y
1160                        }
1161                    };
1162                }
1163            }
1164            ImageTiling::Repeat => {
1165                tiled.y = match alignment.1 {
1166                    ImageVerticalAlignment::Top => 0,
1167                    ImageVerticalAlignment::Center => {
1168                        ((o.height - target.height / ratio) / 2.).rem_euclid(o.height) as u32
1169                    }
1170                    ImageVerticalAlignment::Bottom => {
1171                        (-target.height / ratio).rem_euclid(o.height) as u32
1172                    }
1173                };
1174                r.source_to_target_y = ratio;
1175            }
1176            ImageTiling::Round => {
1177                if target.height / ratio <= o.height * 1.5 {
1178                    r.source_to_target_y = target.height / o.height;
1179                } else {
1180                    let mut rem = (target.height / ratio).rem_euclid(o.height);
1181                    if rem > o.height / 2. {
1182                        rem -= o.height;
1183                    }
1184                    r.source_to_target_y = ratio * target.height / (target.height - rem * ratio);
1185                }
1186            }
1187        }
1188        let has_tiling = tiling != (ImageTiling::None, ImageTiling::None);
1189        r.tiled = has_tiling.then_some(tiled);
1190        r
1191    }
1192}
1193
1194#[cfg(not(feature = "std"))]
1195trait RemEuclid {
1196    fn rem_euclid(self, b: f32) -> f32;
1197}
1198#[cfg(not(feature = "std"))]
1199impl RemEuclid for f32 {
1200    fn rem_euclid(self, b: f32) -> f32 {
1201        return num_traits::Euclid::rem_euclid(&self, &b);
1202    }
1203}
1204
1205/// Return an FitResult that can be used to render an image in a buffer that matches a given ImageFit
1206pub fn fit(
1207    image_fit: ImageFit,
1208    target: euclid::Size2D<f32, PhysicalPx>,
1209    source_rect: IntRect,
1210    scale_factor: ScaleFactor,
1211    alignment: (ImageHorizontalAlignment, ImageVerticalAlignment),
1212    tiling: (ImageTiling, ImageTiling),
1213) -> FitResult {
1214    let has_tiling = tiling != (ImageTiling::None, ImageTiling::None);
1215    let o = source_rect.size.cast::<f32>();
1216    let ratio = match image_fit {
1217        // If there is any tiling, we ignore image_fit
1218        _ if has_tiling => scale_factor.get(),
1219        ImageFit::Fill => {
1220            return FitResult {
1221                clip_rect: source_rect,
1222                source_to_target_x: target.width / o.width,
1223                source_to_target_y: target.height / o.height,
1224                size: target,
1225                offset: Default::default(),
1226                tiled: None,
1227            }
1228        }
1229        ImageFit::Preserve => scale_factor.get(),
1230        ImageFit::Contain => f32::min(target.width / o.width, target.height / o.height),
1231        ImageFit::Cover => f32::max(target.width / o.width, target.height / o.height),
1232    };
1233
1234    FitResult {
1235        clip_rect: source_rect,
1236        source_to_target_x: ratio,
1237        source_to_target_y: ratio,
1238        size: target,
1239        offset: euclid::Point2D::default(),
1240        tiled: None,
1241    }
1242    .adjust_for_tiling(ratio, alignment, tiling)
1243}
1244
1245/// Generate an iterator of  [`FitResult`] for each slice of a nine-slice border image
1246pub fn fit9slice(
1247    source_rect: IntSize,
1248    [t, r, b, l]: [u16; 4],
1249    target: euclid::Size2D<f32, PhysicalPx>,
1250    scale_factor: ScaleFactor,
1251    alignment: (ImageHorizontalAlignment, ImageVerticalAlignment),
1252    tiling: (ImageTiling, ImageTiling),
1253) -> impl Iterator<Item = FitResult> {
1254    let fit_to = |clip_rect: euclid::default::Rect<u16>, target: euclid::Rect<f32, PhysicalPx>| {
1255        (!clip_rect.is_empty() && !target.is_empty()).then(|| {
1256            FitResult {
1257                clip_rect: clip_rect.cast(),
1258                source_to_target_x: target.width() / clip_rect.width() as f32,
1259                source_to_target_y: target.height() / clip_rect.height() as f32,
1260                size: target.size,
1261                offset: target.origin,
1262                tiled: None,
1263            }
1264            .adjust_for_tiling(scale_factor.get(), alignment, tiling)
1265        })
1266    };
1267    use euclid::rect;
1268    let sf = |x| scale_factor.get() * x as f32;
1269    let source = source_rect.cast::<u16>();
1270    if t + b > source.height || l + r > source.width {
1271        [None, None, None, None, None, None, None, None, None]
1272    } else {
1273        [
1274            fit_to(rect(0, 0, l, t), rect(0., 0., sf(l), sf(t))),
1275            fit_to(
1276                rect(l, 0, source.width - l - r, t),
1277                rect(sf(l), 0., target.width - sf(l) - sf(r), sf(t)),
1278            ),
1279            fit_to(rect(source.width - r, 0, r, t), rect(target.width - sf(r), 0., sf(r), sf(t))),
1280            fit_to(
1281                rect(0, t, l, source.height - t - b),
1282                rect(0., sf(t), sf(l), target.height - sf(t) - sf(b)),
1283            ),
1284            fit_to(
1285                rect(l, t, source.width - l - r, source.height - t - b),
1286                rect(sf(l), sf(t), target.width - sf(l) - sf(r), target.height - sf(t) - sf(b)),
1287            ),
1288            fit_to(
1289                rect(source.width - r, t, r, source.height - t - b),
1290                rect(target.width - sf(r), sf(t), sf(r), target.height - sf(t) - sf(b)),
1291            ),
1292            fit_to(rect(0, source.height - b, l, b), rect(0., target.height - sf(b), sf(l), sf(b))),
1293            fit_to(
1294                rect(l, source.height - b, source.width - l - r, b),
1295                rect(sf(l), target.height - sf(b), target.width - sf(l) - sf(r), sf(b)),
1296            ),
1297            fit_to(
1298                rect(source.width - r, source.height - b, r, b),
1299                rect(target.width - sf(r), target.height - sf(b), sf(r), sf(b)),
1300            ),
1301        ]
1302    }
1303    .into_iter()
1304    .flatten()
1305}
1306
1307#[cfg(feature = "ffi")]
1308pub(crate) mod ffi {
1309    #![allow(unsafe_code)]
1310
1311    use super::*;
1312
1313    // Expand Rgb8Pixel so that cbindgen can see it. (is in fact rgb::RGB<u8>)
1314    /// Represents an RGB pixel.
1315    #[cfg(cbindgen)]
1316    #[repr(C)]
1317    struct Rgb8Pixel {
1318        /// red value (between 0 and 255)
1319        r: u8,
1320        /// green value (between 0 and 255)
1321        g: u8,
1322        /// blue value (between 0 and 255)
1323        b: u8,
1324    }
1325
1326    // Expand Rgba8Pixel so that cbindgen can see it. (is in fact rgb::RGBA<u8>)
1327    /// Represents an RGBA pixel.
1328    #[cfg(cbindgen)]
1329    #[repr(C)]
1330    struct Rgba8Pixel {
1331        /// red value (between 0 and 255)
1332        r: u8,
1333        /// green value (between 0 and 255)
1334        g: u8,
1335        /// blue value (between 0 and 255)
1336        b: u8,
1337        /// alpha value (between 0 and 255)
1338        a: u8,
1339    }
1340
1341    #[cfg(feature = "image-decoders")]
1342    #[unsafe(no_mangle)]
1343    pub unsafe extern "C" fn slint_image_load_from_path(path: &SharedString, image: *mut Image) {
1344        core::ptr::write(
1345            image,
1346            Image::load_from_path(std::path::Path::new(path.as_str())).unwrap_or(Image::default()),
1347        )
1348    }
1349
1350    #[cfg(feature = "std")]
1351    #[unsafe(no_mangle)]
1352    pub unsafe extern "C" fn slint_image_load_from_embedded_data(
1353        data: Slice<'static, u8>,
1354        format: Slice<'static, u8>,
1355        image: *mut Image,
1356    ) {
1357        core::ptr::write(image, super::load_image_from_embedded_data(data, format));
1358    }
1359
1360    #[unsafe(no_mangle)]
1361    pub unsafe extern "C" fn slint_image_size(image: &Image) -> IntSize {
1362        image.size()
1363    }
1364
1365    #[unsafe(no_mangle)]
1366    pub extern "C" fn slint_image_path(image: &Image) -> Option<&SharedString> {
1367        match &image.0 {
1368            ImageInner::EmbeddedImage { cache_key, .. } => match cache_key {
1369                #[cfg(feature = "std")]
1370                ImageCacheKey::Path(CachedPath { path, .. }) => Some(path),
1371                _ => None,
1372            },
1373            ImageInner::NineSlice(nine) => match &nine.0 {
1374                ImageInner::EmbeddedImage { cache_key, .. } => match cache_key {
1375                    #[cfg(feature = "std")]
1376                    ImageCacheKey::Path(CachedPath { path, .. }) => Some(path),
1377                    _ => None,
1378                },
1379                _ => None,
1380            },
1381            _ => None,
1382        }
1383    }
1384
1385    #[unsafe(no_mangle)]
1386    pub unsafe extern "C" fn slint_image_from_embedded_textures(
1387        textures: &'static StaticTextures,
1388        image: *mut Image,
1389    ) {
1390        core::ptr::write(image, Image::from(ImageInner::StaticTextures(textures)));
1391    }
1392
1393    #[unsafe(no_mangle)]
1394    pub unsafe extern "C" fn slint_image_compare_equal(image1: &Image, image2: &Image) -> bool {
1395        image1.eq(image2)
1396    }
1397
1398    /// Call [`Image::set_nine_slice_edges`]
1399    #[unsafe(no_mangle)]
1400    pub extern "C" fn slint_image_set_nine_slice_edges(
1401        image: &mut Image,
1402        top: u16,
1403        right: u16,
1404        bottom: u16,
1405        left: u16,
1406    ) {
1407        image.set_nine_slice_edges(top, right, bottom, left);
1408    }
1409
1410    #[unsafe(no_mangle)]
1411    pub extern "C" fn slint_image_to_rgb8(
1412        image: &Image,
1413        data: &mut SharedVector<Rgb8Pixel>,
1414        width: &mut u32,
1415        height: &mut u32,
1416    ) -> bool {
1417        image.to_rgb8().is_some_and(|pixel_buffer| {
1418            *data = pixel_buffer.data.clone();
1419            *width = pixel_buffer.width();
1420            *height = pixel_buffer.height();
1421            true
1422        })
1423    }
1424
1425    #[unsafe(no_mangle)]
1426    pub extern "C" fn slint_image_to_rgba8(
1427        image: &Image,
1428        data: &mut SharedVector<Rgba8Pixel>,
1429        width: &mut u32,
1430        height: &mut u32,
1431    ) -> bool {
1432        image.to_rgba8().is_some_and(|pixel_buffer| {
1433            *data = pixel_buffer.data.clone();
1434            *width = pixel_buffer.width();
1435            *height = pixel_buffer.height();
1436            true
1437        })
1438    }
1439
1440    #[unsafe(no_mangle)]
1441    pub extern "C" fn slint_image_to_rgba8_premultiplied(
1442        image: &Image,
1443        data: &mut SharedVector<Rgba8Pixel>,
1444        width: &mut u32,
1445        height: &mut u32,
1446    ) -> bool {
1447        image.to_rgba8_premultiplied().is_some_and(|pixel_buffer| {
1448            *data = pixel_buffer.data.clone();
1449            *width = pixel_buffer.width();
1450            *height = pixel_buffer.height();
1451            true
1452        })
1453    }
1454}
1455
1456/// This structure contains fields to identify and render an OpenGL texture that Slint borrows from the application code.
1457/// Use this to embed a native OpenGL texture into a Slint scene.
1458///
1459/// The ownership of the texture remains with the application. It is the application's responsibility to delete the texture
1460/// when it is not used anymore.
1461///
1462/// Note that only 2D RGBA textures are supported.
1463#[derive(Clone, Debug, PartialEq)]
1464#[non_exhaustive]
1465#[cfg(not(target_arch = "wasm32"))]
1466#[repr(C)]
1467pub struct BorrowedOpenGLTexture {
1468    /// The id or name of the texture, as created by [`glGenTextures`](https://registry.khronos.org/OpenGL-Refpages/gl4/html/glGenTextures.xhtml).
1469    pub texture_id: core::num::NonZeroU32,
1470    /// The size of the texture in pixels.
1471    pub size: IntSize,
1472    /// Origin of the texture when rendering.
1473    pub origin: BorrowedOpenGLTextureOrigin,
1474}
i_slint_core/graphics/image.rs

i_slint_core/graphics/
image.rs
