Merge pull request #1219 from Alch-Emi/image-modes

ContentFit support for images

7 files changed, 318 insertions, 57 deletions

diff --git a/core/src/content_fit.rs b/core/src/content_fit.rs
new file mode 100644
index 00000000..6bbedc7a
--- /dev/null
+++ b/core/src/content_fit.rs
@@ -0,0 +1,119 @@
+//! Control the fit of some content (like an image) within a space.
+use crate::Size;
+
+/// The strategy used to fit the contents of a widget to its bounding box.
+///
+/// Each variant of this enum is a strategy that can be applied for resolving
+/// differences in aspect ratio and size between the image being displayed and
+/// the space its being displayed in.
+///
+/// For an interactive demonstration of these properties as they are implemented
+/// in CSS, see [Mozilla's docs][1], or run the `tour` example
+///
+/// [1]: https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit
+#[derive(Debug, Hash, Clone, Copy, PartialEq, Eq)]
+pub enum ContentFit {
+    /// Scale as big as it can be without needing to crop or hide parts.
+    ///
+    /// The image will be scaled (preserving aspect ratio) so that it just fits
+    /// within the window.  This won't distort the image or crop/hide any edges,
+    /// but if the image doesn't fit perfectly, there may be whitespace on the
+    /// top/bottom or left/right.
+    ///
+    /// This is a great fit for when you need to display an image without losing
+    /// any part of it, particularly when the image itself is the focus of the
+    /// screen.
+    Contain,
+
+    /// Scale the image to cover all of the bounding box, cropping if needed.
+    ///
+    /// This doesn't distort the image, and it ensures that the widget's area is
+    /// completely covered, but it might crop off a bit of the edges of the
+    /// widget, particularly when there is a big difference between the aspect
+    /// ratio of the widget and the aspect ratio of the image.
+    ///
+    /// This is best for when you're using an image as a background, or to fill
+    /// space, and any details of the image around the edge aren't too
+    /// important.
+    Cover,
+
+    /// Distort the image so the widget is 100% covered without cropping.
+    ///
+    /// This stretches the image to fit the widget, without any whitespace or
+    /// cropping. However, because of the stretch, the image may look distorted
+    /// or elongated, particularly when there's a mismatch of aspect ratios.
+    Fill,
+
+    /// Don't resize or scale the image at all.
+    ///
+    /// This will not apply any transformations to the provided image, but also
+    /// means that unless you do the math yourself, the widget's area will not
+    /// be completely covered, or the image might be cropped.
+    ///
+    /// This is best for when you've sized the image yourself.
+    None,
+
+    /// Scale the image down if it's too big for the space, but never scale it
+    /// up.
+    ///
+    /// This works much like [`Contain`](Self::Contain), except that if the
+    /// image would have been scaled up, it keeps its original resolution to
+    /// avoid the bluring that accompanies upscaling images.
+    ScaleDown,
+}
+
+impl ContentFit {
+    /// Attempt to apply the given fit for a content size within some bounds.
+    ///
+    /// The returned value is the recommended scaled size of the content.
+    pub fn fit(&self, content: Size, bounds: Size) -> Size {
+        let content_ar = content.width / content.height;
+        let bounds_ar = bounds.width / bounds.height;
+
+        match self {
+            Self::Contain => {
+                if bounds_ar > content_ar {
+                    Size {
+                        width: content.width * bounds.height / content.height,
+                        ..bounds
+                    }
+                } else {
+                    Size {
+                        height: content.height * bounds.width / content.width,
+                        ..bounds
+                    }
+                }
+            }
+            Self::Cover => {
+                if bounds_ar < content_ar {
+                    Size {
+                        width: content.width * bounds.height / content.height,
+                        ..bounds
+                    }
+                } else {
+                    Size {
+                        height: content.height * bounds.width / content.width,
+                        ..bounds
+                    }
+                }
+            }
+            Self::Fill => bounds,
+            Self::None => content,
+            Self::ScaleDown => {
+                if bounds_ar > content_ar && bounds.height < content.height {
+                    Size {
+                        width: content.width * bounds.height / content.height,
+                        ..bounds
+                    }
+                } else if bounds.width < content.width {
+                    Size {
+                        height: content.height * bounds.width / content.width,
+                        ..bounds
+                    }
+                } else {
+                    content
+                }
+            }
+        }
+    }
+}
diff --git a/core/src/lib.rs b/core/src/lib.rs
index 2a4e6158..3eb9f659 100644
--- a/core/src/lib.rs
+++ b/core/src/lib.rs
@@ -21,6 +21,7 @@ pub mod time;
 
 mod background;
 mod color;
+mod content_fit;
 mod font;
 mod length;
 mod padding;
@@ -32,6 +33,7 @@ mod vector;
 pub use alignment::Alignment;
 pub use background::Background;
 pub use color::Color;
+pub use content_fit::ContentFit;
 pub use font::Font;
 pub use length::Length;
 pub use padding::Padding;
diff --git a/examples/tour/src/main.rs b/examples/tour/src/main.rs
index d4b41310..e199c88c 100644
--- a/examples/tour/src/main.rs
+++ b/examples/tour/src/main.rs
@@ -1,7 +1,7 @@
 use iced::{
     alignment, button, scrollable, slider, text_input, Button, Checkbox, Color,
-    Column, Container, Element, Image, Length, Radio, Row, Sandbox, Scrollable,
-    Settings, Slider, Space, Text, TextInput, Toggler,
+    Column, Container, ContentFit, Element, Image, Length, Radio, Row, Sandbox,
+    Scrollable, Settings, Slider, Space, Text, TextInput, Toggler,
 };
 
 pub fn main() -> iced::Result {
@@ -139,7 +139,8 @@ impl Steps {
                     can_continue: false,
                 },
                 Step::Image {
-                    width: 300,
+                    height: 200,
+                    current_fit: ContentFit::Contain,
                     slider: slider::State::new(),
                 },
                 Step::Scrollable,
@@ -213,8 +214,9 @@ enum Step {
         can_continue: bool,
     },
     Image {
-        width: u16,
+        height: u16,
         slider: slider::State,
+        current_fit: ContentFit,
     },
     Scrollable,
     TextInput {
@@ -234,7 +236,8 @@ pub enum StepMessage {
     TextSizeChanged(u16),
     TextColorChanged(Color),
     LanguageSelected(Language),
-    ImageWidthChanged(u16),
+    ImageHeightChanged(u16),
+    ImageFitSelected(ContentFit),
     InputChanged(String),
     ToggleSecureInput(bool),
     DebugToggled(bool),
@@ -279,9 +282,14 @@ impl<'a> Step {
                     *spacing = new_spacing;
                 }
             }
-            StepMessage::ImageWidthChanged(new_width) => {
-                if let Step::Image { width, .. } = self {
-                    *width = new_width;
+            StepMessage::ImageHeightChanged(new_height) => {
+                if let Step::Image { height, .. } = self {
+                    *height = new_height;
+                }
+            }
+            StepMessage::ImageFitSelected(fit) => {
+                if let Step::Image { current_fit, .. } = self {
+                    *current_fit = fit;
                 }
             }
             StepMessage::InputChanged(new_value) => {
@@ -346,7 +354,11 @@ impl<'a> Step {
                 color_sliders,
                 color,
             } => Self::text(size_slider, *size, color_sliders, *color),
-            Step::Image { width, slider } => Self::image(*width, slider),
+            Step::Image {
+                height,
+                slider,
+                current_fit,
+            } => Self::image(*height, slider, *current_fit),
             Step::RowsAndColumns {
                 layout,
                 spacing_slider,
@@ -574,23 +586,44 @@ impl<'a> Step {
     }
 
     fn image(
-        width: u16,
+        height: u16,
         slider: &'a mut slider::State,
+        current_fit: ContentFit,
     ) -> Column<'a, StepMessage> {
+        const FIT_MODES: [(ContentFit, &str); 3] = [
+            (ContentFit::Contain, "Contain"),
+            (ContentFit::Cover, "Cover"),
+            (ContentFit::Fill, "Fill"),
+        ];
+
+        let mode_selector = FIT_MODES.iter().fold(
+            Column::new().padding(10).spacing(20),
+            |choices, (mode, name)| {
+                choices.push(Radio::new(
+                    *mode,
+                    *name,
+                    Some(current_fit),
+                    StepMessage::ImageFitSelected,
+                ))
+            },
+        );
+
         Self::container("Image")
-            .push(Text::new("An image that tries to keep its aspect ratio."))
-            .push(ferris(width))
+            .push(Text::new("Pictures of things in all shapes and sizes!"))
+            .push(ferris(height, current_fit))
             .push(Slider::new(
                 slider,
-                100..=500,
-                width,
-                StepMessage::ImageWidthChanged,
+                50..=500,
+                height,
+                StepMessage::ImageHeightChanged,
             ))
             .push(
-                Text::new(format!("Width: {} px", width.to_string()))
+                Text::new(format!("Height: {} px", height))
                     .width(Length::Fill)
                     .horizontal_alignment(alignment::Horizontal::Center),
             )
+            .push(Text::new("Pick a content fit strategy:"))
+            .push(mode_selector)
     }
 
     fn scrollable() -> Column<'a, StepMessage> {
@@ -613,7 +646,7 @@ impl<'a> Step {
                     .horizontal_alignment(alignment::Horizontal::Center),
             )
             .push(Column::new().height(Length::Units(4096)))
-            .push(ferris(300))
+            .push(ferris(200, ContentFit::Contain))
             .push(
                 Text::new("You made it!")
                     .width(Length::Fill)
@@ -699,7 +732,10 @@ impl<'a> Step {
     }
 }
 
-fn ferris<'a>(width: u16) -> Container<'a, StepMessage> {
+fn ferris<'a>(
+    height: u16,
+    content_fit: ContentFit,
+) -> Container<'a, StepMessage> {
     Container::new(
         // This should go away once we unify resource loading on native
         // platforms
@@ -708,10 +744,11 @@ fn ferris<'a>(width: u16) -> Container<'a, StepMessage> {
         } else {
             Image::new(format!(
                 "{}/images/ferris.png",
-                env!("CARGO_MANIFEST_DIR")
+                env!("CARGO_MANIFEST_DIR"),
             ))
         }
-        .width(Length::Units(width)),
+        .height(Length::Units(height))
+        .content_fit(content_fit),
     )
     .width(Length::Fill)
     .center_x()
@@ -783,7 +820,8 @@ pub enum Layout {
 }
 
 mod style {
-    use iced::{button, Background, Color, Vector};
+    use iced::button;
+    use iced::{Background, Color, Vector};
 
     pub enum Button {
         Primary,
diff --git a/native/src/lib.rs b/native/src/lib.rs
index 6d98f7d1..5c9c24c9 100644
--- a/native/src/lib.rs
+++ b/native/src/lib.rs
@@ -71,8 +71,8 @@ mod debug;
 pub use iced_core::alignment;
 pub use iced_core::time;
 pub use iced_core::{
-    Alignment, Background, Color, Font, Length, Padding, Point, Rectangle,
-    Size, Vector,
+    Alignment, Background, Color, ContentFit, Font, Length, Padding, Point,
+    Rectangle, Size, Vector,
 };
 pub use iced_futures::{executor, futures};
 
diff --git a/native/src/widget/image.rs b/native/src/widget/image.rs
index b8fb662e..83c24ee5 100644
--- a/native/src/widget/image.rs
+++ b/native/src/widget/image.rs
@@ -5,7 +5,10 @@ pub use viewer::Viewer;
 use crate::image;
 use crate::layout;
 use crate::renderer;
-use crate::{Element, Hasher, Layout, Length, Point, Rectangle, Size, Widget};
+use crate::{
+    ContentFit, Element, Hasher, Layout, Length, Point, Rectangle, Size,
+    Vector, Widget,
+};
 
 use std::hash::Hash;
 
@@ -26,6 +29,7 @@ pub struct Image<Handle> {
     handle: Handle,
     width: Length,
     height: Length,
+    content_fit: ContentFit,
 }
 
 impl<Handle> Image<Handle> {
@@ -35,6 +39,7 @@ impl<Handle> Image<Handle> {
             handle: handle.into(),
             width: Length::Shrink,
             height: Length::Shrink,
+            content_fit: ContentFit::Contain,
         }
     }
 
@@ -49,6 +54,16 @@ impl<Handle> Image<Handle> {
         self.height = height;
         self
     }
+
+    /// Sets the [`ContentFit`] of the [`Image`].
+    ///
+    /// Defaults to [`ContentFit::Contain`]
+    pub fn content_fit(self, content_fit: ContentFit) -> Self {
+        Self {
+            content_fit,
+            ..self
+        }
+    }
 }
 
 impl<Message, Renderer, Handle> Widget<Message, Renderer> for Image<Handle>
@@ -69,24 +84,32 @@ where
         renderer: &Renderer,
         limits: &layout::Limits,
     ) -> layout::Node {
+        // The raw w/h of the underlying image
         let (width, height) = renderer.dimensions(&self.handle);
+        let image_size = Size::new(width as f32, height as f32);
 
-        let aspect_ratio = width as f32 / height as f32;
-
-        let mut size = limits
+        // The size to be available to the widget prior to `Shrink`ing
+        let raw_size = limits
             .width(self.width)
             .height(self.height)
-            .resolve(Size::new(width as f32, height as f32));
-
-        let viewport_aspect_ratio = size.width / size.height;
-
-        if viewport_aspect_ratio > aspect_ratio {
-            size.width = width as f32 * size.height / height as f32;
-        } else {
-            size.height = height as f32 * size.width / width as f32;
-        }
-
-        layout::Node::new(size)
+            .resolve(image_size);
+
+        // The uncropped size of the image when fit to the bounds above
+        let full_size = self.content_fit.fit(image_size, raw_size);
+
+        // Shrink the widget to fit the resized image, if requested
+        let final_size = Size {
+            width: match self.width {
+                Length::Shrink => f32::min(raw_size.width, full_size.width),
+                _ => raw_size.width,
+            },
+            height: match self.height {
+                Length::Shrink => f32::min(raw_size.height, full_size.height),
+                _ => raw_size.height,
+            },
+        };
+
+        layout::Node::new(final_size)
     }
 
     fn draw(
@@ -97,7 +120,34 @@ where
         _cursor_position: Point,
         _viewport: &Rectangle,
     ) {
-        renderer.draw(self.handle.clone(), layout.bounds());
+        let (width, height) = renderer.dimensions(&self.handle);
+        let image_size = Size::new(width as f32, height as f32);
+
+        let bounds = layout.bounds();
+        let adjusted_fit = self.content_fit.fit(image_size, bounds.size());
+
+        let render = |renderer: &mut Renderer| {
+            let offset = Vector::new(
+                (bounds.width - adjusted_fit.width).max(0.0) / 2.0,
+                (bounds.height - adjusted_fit.height).max(0.0) / 2.0,
+            );
+
+            let drawing_bounds = Rectangle {
+                width: adjusted_fit.width,
+                height: adjusted_fit.height,
+                ..bounds
+            };
+
+            renderer.draw(self.handle.clone(), drawing_bounds + offset)
+        };
+
+        if adjusted_fit.width > bounds.width
+            || adjusted_fit.height > bounds.height
+        {
+            renderer.with_layer(bounds, render);
+        } else {
+            render(renderer)
+        }
     }
 
     fn hash_layout(&self, state: &mut Hasher) {
@@ -107,6 +157,7 @@ where
         self.handle.hash(state);
         self.width.hash(state);
         self.height.hash(state);
+        self.content_fit.hash(state);
     }
 }
 
diff --git a/native/src/widget/svg.rs b/native/src/widget/svg.rs
index f212dfcb..22aac331 100644
--- a/native/src/widget/svg.rs
+++ b/native/src/widget/svg.rs
@@ -2,7 +2,10 @@
 use crate::layout;
 use crate::renderer;
 use crate::svg::{self, Handle};
-use crate::{Element, Hasher, Layout, Length, Point, Rectangle, Size, Widget};
+use crate::{
+    ContentFit, Element, Hasher, Layout, Length, Point, Rectangle, Size,
+    Vector, Widget,
+};
 
 use std::hash::Hash;
 use std::path::PathBuf;
@@ -18,6 +21,7 @@ pub struct Svg {
     handle: Handle,
     width: Length,
     height: Length,
+    content_fit: ContentFit,
 }
 
 impl Svg {
@@ -27,6 +31,7 @@ impl Svg {
             handle: handle.into(),
             width: Length::Fill,
             height: Length::Shrink,
+            content_fit: ContentFit::Contain,
         }
     }
 
@@ -47,6 +52,16 @@ impl Svg {
         self.height = height;
         self
     }
+
+    /// Sets the [`ContentFit`] of the [`Svg`].
+    ///
+    /// Defaults to [`ContentFit::Contain`]
+    pub fn content_fit(self, content_fit: ContentFit) -> Self {
+        Self {
+            content_fit,
+            ..self
+        }
+    }
 }
 
 impl<Message, Renderer> Widget<Message, Renderer> for Svg
@@ -66,24 +81,32 @@ where
         renderer: &Renderer,
         limits: &layout::Limits,
     ) -> layout::Node {
+        // The raw w/h of the underlying image
         let (width, height) = renderer.dimensions(&self.handle);
+        let image_size = Size::new(width as f32, height as f32);
 
-        let aspect_ratio = width as f32 / height as f32;
-
-        let mut size = limits
+        // The size to be available to the widget prior to `Shrink`ing
+        let raw_size = limits
             .width(self.width)
             .height(self.height)
-            .resolve(Size::new(width as f32, height as f32));
-
-        let viewport_aspect_ratio = size.width / size.height;
-
-        if viewport_aspect_ratio > aspect_ratio {
-            size.width = width as f32 * size.height / height as f32;
-        } else {
-            size.height = height as f32 * size.width / width as f32;
-        }
-
-        layout::Node::new(size)
+            .resolve(image_size);
+
+        // The uncropped size of the image when fit to the bounds above
+        let full_size = self.content_fit.fit(image_size, raw_size);
+
+        // Shrink the widget to fit the resized image, if requested
+        let final_size = Size {
+            width: match self.width {
+                Length::Shrink => f32::min(raw_size.width, full_size.width),
+                _ => raw_size.width,
+            },
+            height: match self.height {
+                Length::Shrink => f32::min(raw_size.height, full_size.height),
+                _ => raw_size.height,
+            },
+        };
+
+        layout::Node::new(final_size)
     }
 
     fn draw(
@@ -94,7 +117,34 @@ where
         _cursor_position: Point,
         _viewport: &Rectangle,
     ) {
-        renderer.draw(self.handle.clone(), layout.bounds())
+        let (width, height) = renderer.dimensions(&self.handle);
+        let image_size = Size::new(width as f32, height as f32);
+
+        let bounds = layout.bounds();
+        let adjusted_fit = self.content_fit.fit(image_size, bounds.size());
+
+        let render = |renderer: &mut Renderer| {
+            let offset = Vector::new(
+                (bounds.width - adjusted_fit.width).max(0.0) / 2.0,
+                (bounds.height - adjusted_fit.height).max(0.0) / 2.0,
+            );
+
+            let drawing_bounds = Rectangle {
+                width: adjusted_fit.width,
+                height: adjusted_fit.height,
+                ..bounds
+            };
+
+            renderer.draw(self.handle.clone(), drawing_bounds + offset)
+        };
+
+        if adjusted_fit.width > bounds.width
+            || adjusted_fit.height > bounds.height
+        {
+            renderer.with_layer(bounds, render);
+        } else {
+            render(renderer)
+        }
     }
 
     fn hash_layout(&self, state: &mut Hasher) {
@@ -103,6 +153,7 @@ where
         self.handle.hash(state);
         self.width.hash(state);
         self.height.hash(state);
+        self.content_fit.hash(state);
     }
 }
 
diff --git a/src/lib.rs b/src/lib.rs
index c8047d7f..b34bb72c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -221,6 +221,6 @@ pub use settings::Settings;
 pub use runtime::alignment;
 pub use runtime::futures;
 pub use runtime::{
-    Alignment, Background, Color, Command, Font, Length, Point, Rectangle,
-    Size, Subscription, Vector,
+    Alignment, Background, Color, Command, ContentFit, Font, Length, Point,
+    Rectangle, Size, Subscription, Vector,
 };