From a8e22b5316042df63049e0146bbacf7d36eb9a67 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Mon, 1 Jun 2020 12:12:38 -0700 Subject: [PATCH 01/34] add example to `Image` widget The idea is to work toward a more robust image widget. Documentation is just the first step. --- druid/src/widget/image.rs | 38 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 7205f10b72..58e837046c 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -26,7 +26,37 @@ use crate::{ PaintCtx, Rect, RenderContext, Size, UpdateCtx, Widget, }; -/// A widget that renders an Image +/// A widget that renders an Image. Contains data about how to fill given space and +/// interpolate pixels. +/// Configuration options are provided via the builder pattern. +/// +/// Note: interpolation can lead to blurry images or artifacts and so is not +/// recommended for things like icons; instead consider using +/// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) and +/// enabling the `svg` feature with `cargo`. +/// +/// (See also: +/// [`druid::widget::ImageData`], +/// [`druid::widget::FillStrat`], +/// [`druid::piet::InterpolationMode`] +/// ) +/// +/// # Example +/// +/// Create an image widget and configure it using builder methods. +/// ``` +/// use druid::{ +/// widget::{Image, ImageData, FillStrat}, +/// piet::InterpolationMode, +/// }; +/// +/// let image_data = ImageData::empty(); +/// let image_widget = Image::new(image_data) +/// // set fill strategy +/// .fill_mode(FillStrat::Fill) +/// // set interpolation mode +/// .interpolation_mode(InterpolationMode::NearestNeighbor); +/// ``` pub struct Image { image_data: ImageData, fill: FillStrat, @@ -36,7 +66,10 @@ pub struct Image { impl Image { /// Create an image drawing widget from `ImageData`. /// - /// The Image will scale to fit its box constraints. + /// By default, the Image will scale to fit its box constraints + /// ([`druid::widget::FillStrat::Fill`]) + /// and will be scaled bilinearly + /// ([`druid::piet::InterpolationMode::Bilinear`]) pub fn new(image_data: ImageData) -> Self { Image { image_data, @@ -108,6 +141,7 @@ impl Widget for Image { } /// Stored Image data. +/// Contains raw bytes, dimensions, and [format data](../piet/enum.ImageFormat.html) #[derive(Clone)] pub struct ImageData { pixels: Vec, From 8b0e298af78c905d4efef82d188981f38871f67b Mon Sep 17 00:00:00 2001 From: covercash2 Date: Mon, 1 Jun 2020 19:00:33 -0700 Subject: [PATCH 02/34] export `Image` and `ImageData` By reducing the scope of the "image" feature, we can expose the bare-bones image widget API and better document the "image" feature. --- druid/src/widget/image.rs | 56 +++++++++++++++++++++------------------ druid/src/widget/mod.rs | 4 --- 2 files changed, 30 insertions(+), 30 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 58e837046c..0c0b65b90e 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -15,10 +15,6 @@ //! An Image widget. //! Please consider using SVG and the SVG wideget as it scales much better. -use std::convert::AsRef; -use std::error::Error; -use std::path::Path; - use crate::{ piet::{ImageFormat, InterpolationMode}, widget::common::FillStrat, @@ -161,6 +157,34 @@ impl ImageData { } } + /// Get the size in pixels of the contained image. + fn get_size(&self) -> Size { + Size::new(self.x_pixels as f64, self.y_pixels as f64) + } + + /// Convert ImageData into Piet draw instructions. + fn to_piet(&self, offset_matrix: Affine, ctx: &mut PaintCtx, interpolation: InterpolationMode) { + ctx.with_save(|ctx| { + ctx.transform(offset_matrix); + let size = self.get_size(); + let im = ctx + .make_image( + size.width as usize, + size.height as usize, + &self.pixels, + self.format, + ) + .unwrap(); + ctx.draw_image(&im, size.to_rect(), interpolation); + }) + } +} + +#[cfg(feature = "image")] +use std::{convert::AsRef, error::Error, path::Path}; +#[cfg(feature = "image")] +#[cfg_attr(docsrs, doc(cfg(feature = "image")))] +impl ImageData { /// Load an image from a DynamicImage from the image crate pub fn from_dynamic_image(image_data: image::DynamicImage) -> ImageData { if has_alpha_channel(&image_data) { @@ -207,30 +231,10 @@ impl ImageData { let image_data = image::open(path).map_err(|e| e)?; Ok(ImageData::from_dynamic_image(image_data)) } - - /// Get the size in pixels of the contained image. - fn get_size(&self) -> Size { - Size::new(self.x_pixels as f64, self.y_pixels as f64) - } - - /// Convert ImageData into Piet draw instructions. - fn to_piet(&self, offset_matrix: Affine, ctx: &mut PaintCtx, interpolation: InterpolationMode) { - ctx.with_save(|ctx| { - ctx.transform(offset_matrix); - let size = self.get_size(); - let im = ctx - .make_image( - size.width as usize, - size.height as usize, - &self.pixels, - self.format, - ) - .unwrap(); - ctx.draw_image(&im, size.to_rect(), interpolation); - }) - } } +#[cfg(feature = "image")] +#[cfg_attr(docsrs, doc(cfg(feature = "image")))] fn has_alpha_channel(image: &image::DynamicImage) -> bool { use image::ColorType::*; match image.color() { diff --git a/druid/src/widget/mod.rs b/druid/src/widget/mod.rs index ce5c9aa7ec..fa597da9fb 100644 --- a/druid/src/widget/mod.rs +++ b/druid/src/widget/mod.rs @@ -25,8 +25,6 @@ mod either; mod env_scope; mod flex; mod identity_wrapper; -#[cfg(feature = "image")] -#[cfg_attr(docsrs, doc(cfg(feature = "image")))] mod image; mod invalidation; mod label; @@ -51,8 +49,6 @@ mod view_switcher; mod widget; mod widget_ext; -#[cfg(feature = "image")] -#[cfg_attr(docsrs, doc(cfg(feature = "image")))] pub use self::image::{Image, ImageData}; pub use align::Align; pub use button::Button; From 282e438bab8b1e0bb5875c3bd033f5e883f20c47 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Mon, 1 Jun 2020 21:38:17 -0700 Subject: [PATCH 03/34] add not about "image" feature This should make the feature more discoverable and make it clearer why it is optional. --- druid/src/widget/image.rs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 0c0b65b90e..8f8adffd0e 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -31,6 +31,16 @@ use crate::{ /// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) and /// enabling the `svg` feature with `cargo`. /// +/// `druid` does not support loading image data by default. +/// However, there is an optional dependency on the `image` crate +/// that makes loading simple. This feature can be enabled with cargo. +/// For example, in `Cargo.toml`: +/// ```no_compile +/// [dependencies.druid] +/// version = "0.6.0" +/// features = ["image"] +/// ``` +/// /// (See also: /// [`druid::widget::ImageData`], /// [`druid::widget::FillStrat`], @@ -138,6 +148,17 @@ impl Widget for Image { /// Stored Image data. /// Contains raw bytes, dimensions, and [format data](../piet/enum.ImageFormat.html) +/// +/// By default druid does not parse image metadata. +/// However, druid supports an optional dependency on the `image` crate, +/// which allows reading image metadata and other kinds of image data manipulation. +/// These features are enabled with "image" feature. For example, in `Cargo.toml`: +/// ```no_compile +/// [dependencies.druid] +/// version = "0.6.0" +/// features = ["image"] +/// ``` +/// #[derive(Clone)] pub struct ImageData { pixels: Vec, From b3ebd022c53957c339208f967ef64588de16141c Mon Sep 17 00:00:00 2001 From: covercash2 Date: Mon, 1 Jun 2020 21:56:32 -0700 Subject: [PATCH 04/34] minor doc edits --- druid/src/widget/image.rs | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 8f8adffd0e..c6fbbf72d1 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -28,8 +28,8 @@ use crate::{ /// /// Note: interpolation can lead to blurry images or artifacts and so is not /// recommended for things like icons; instead consider using -/// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) and -/// enabling the `svg` feature with `cargo`. +/// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) +/// and enabling the `svg` feature with `cargo`. /// /// `druid` does not support loading image data by default. /// However, there is an optional dependency on the `image` crate @@ -42,14 +42,14 @@ use crate::{ /// ``` /// /// (See also: -/// [`druid::widget::ImageData`], -/// [`druid::widget::FillStrat`], -/// [`druid::piet::InterpolationMode`] +/// [`ImageData`], +/// [`FillStrat`], +/// [`InterpolationMode`] /// ) /// /// # Example /// -/// Create an image widget and configure it using builder methods. +/// Create an image widget and configure it using builder methods /// ``` /// use druid::{ /// widget::{Image, ImageData, FillStrat}, @@ -73,9 +73,9 @@ impl Image { /// Create an image drawing widget from `ImageData`. /// /// By default, the Image will scale to fit its box constraints - /// ([`druid::widget::FillStrat::Fill`]) + /// ([`FillStrat::Fill`]) /// and will be scaled bilinearly - /// ([`druid::piet::InterpolationMode::Bilinear`]) + /// ([`InterpolationMode::Bilinear`]) pub fn new(image_data: ImageData) -> Self { Image { image_data, @@ -90,7 +90,7 @@ impl Image { self } - /// Modify the widget's `FillStrat`. + /// Modify the widget's [`FillStrat`]. pub fn set_fill_mode(&mut self, newfil: FillStrat) { self.fill = newfil; } @@ -101,7 +101,7 @@ impl Image { self } - /// Modify the widget's `InterpolationMode`. + /// Modify the widget's [`InterpolationMode`]. pub fn set_interpolation_mode(&mut self, interpolation: InterpolationMode) { self.interpolation = interpolation; } @@ -149,9 +149,9 @@ impl Widget for Image { /// Stored Image data. /// Contains raw bytes, dimensions, and [format data](../piet/enum.ImageFormat.html) /// -/// By default druid does not parse image metadata. -/// However, druid supports an optional dependency on the `image` crate, -/// which allows reading image metadata and other kinds of image data manipulation. +/// By default `druid` does not parse image metadata. +/// However, `druid` supports an optional dependency on the `image` crate, +/// which allows reading image metadata and some kinds of image data manipulation. /// These features are enabled with "image" feature. For example, in `Cargo.toml`: /// ```no_compile /// [dependencies.druid] From c5db4380eddc495c3af15ec68fb2bc28bb159083 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Wed, 3 Jun 2020 22:12:22 -0700 Subject: [PATCH 05/34] remove image feature reminder --- druid/src/widget/image.rs | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 20672d8e07..842257ae82 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -34,16 +34,6 @@ use crate::{ /// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) /// and enabling the `svg` feature with `cargo`. /// -/// `druid` does not support loading image data by default. -/// However, there is an optional dependency on the `image` crate -/// that makes loading simple. This feature can be enabled with cargo. -/// For example, in `Cargo.toml`: -/// ```no_compile -/// [dependencies.druid] -/// version = "0.6.0" -/// features = ["image"] -/// ``` -/// /// (See also: /// [`ImageData`], /// [`FillStrat`], @@ -151,17 +141,6 @@ impl Widget for Image { /// Stored Image data. /// Contains raw bytes, dimensions, and [format data](../piet/enum.ImageFormat.html) -/// -/// By default `druid` does not parse image metadata. -/// However, `druid` supports an optional dependency on the `image` crate, -/// which allows reading image metadata and some kinds of image data manipulation. -/// These features are enabled with "image" feature. For example, in `Cargo.toml`: -/// ```no_compile -/// [dependencies.druid] -/// version = "0.6.0" -/// features = ["image"] -/// ``` -/// #[derive(Clone)] pub struct ImageData { pixels: Vec, From b4f26ea1f0d929096b3b2e2af396744a1d48a6ca Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 13:09:25 -0700 Subject: [PATCH 06/34] minor doc edits --- druid/src/widget/image.rs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 842257ae82..6f5f64f256 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -25,12 +25,13 @@ use crate::{ PaintCtx, Rect, RenderContext, Size, UpdateCtx, Widget, }; -/// A widget that renders an Image. Contains data about how to fill given space and -/// interpolate pixels. +/// A widget that renders a bitmap Image. +/// +/// Contains data about how to fill given space and interpolate pixels. /// Configuration options are provided via the builder pattern. /// /// Note: interpolation can lead to blurry images or artifacts and so is not -/// recommended for things like icons; instead consider using +/// recommended for things like icons. Instead consider using /// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) /// and enabling the `svg` feature with `cargo`. /// @@ -139,8 +140,9 @@ impl Widget for Image { } } -/// Stored Image data. -/// Contains raw bytes, dimensions, and [format data](../piet/enum.ImageFormat.html) +/// Owned Image data. +/// +/// Contains raw bytes, dimensions, and image format ([`ImageFormat`]) #[derive(Clone)] pub struct ImageData { pixels: Vec, From 13982dee9546aee686f31a0ec92c8574d066e506 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 13:11:32 -0700 Subject: [PATCH 07/34] add example --- druid/src/widget/image.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 6f5f64f256..6ef4fb458b 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -57,6 +57,20 @@ use crate::{ /// // set interpolation mode /// .interpolation_mode(InterpolationMode::NearestNeighbor); /// ``` +/// Create an image widget and configure it using setters +/// ``` +/// use druid::{ +/// widget::{Image, ImageData, FillStrat}, +/// piet::InterpolationMode, +/// }; +/// +/// let image_data = ImageData::empty(); +/// let mut image_widget = Image::new(image_data); +/// // set fill strategy +/// image_widget.set_fill_mode(FillStrat::FitWidth); +/// // set interpolation mode +/// image_widget.set_interpolation_mode(InterpolationMode::NearestNeighbor); +/// ``` pub struct Image { image_data: ImageData, fill: FillStrat, From 7939d361bd6ed88005ca1a32f2eda0b854ea324d Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 14:22:54 -0700 Subject: [PATCH 08/34] added note about image feature --- druid/src/widget/image.rs | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 6ef4fb458b..47969e164c 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -30,7 +30,7 @@ use crate::{ /// Contains data about how to fill given space and interpolate pixels. /// Configuration options are provided via the builder pattern. /// -/// Note: interpolation can lead to blurry images or artifacts and so is not +/// Note: interpolation can lead to blurry or pixelated images and so is not /// recommended for things like icons. Instead consider using /// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) /// and enabling the `svg` feature with `cargo`. @@ -154,9 +154,14 @@ impl Widget for Image { } } -/// Owned Image data. +/// Loaded image data. +/// +/// By default, Druid does not parse image data. +/// Hoever, [enabling the `image` feature](../index.html#optional-features) +/// provides several +/// methods by which you can load image files. /// -/// Contains raw bytes, dimensions, and image format ([`ImageFormat`]) +/// Contains raw bytes, dimensions, and image format ([`druid::piet::ImageFormat`]). #[derive(Clone)] pub struct ImageData { pixels: Vec, From c05e4c760233a185e8434c5c63d8fc936b3e86ad Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 14:36:33 -0700 Subject: [PATCH 09/34] update changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 26cd8a9057..953a9e4869 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,7 @@ You can find its changes [documented below](#060---2020-06-01). ### Docs +- Added documentation for the `druid::Image` widget. ([#1018] by [@covercash2]) - Fixed a link in `druid::command` documentation. ([#1008] by [@covercash2]) ### Examples @@ -319,6 +320,7 @@ Last release without a changelog :( [#1008]: https://github.com/xi-editor/druid/pull/1008 [#1011]: https://github.com/xi-editor/druid/pull/1011 [#1013]: https://github.com/xi-editor/druid/pull/1013 +[#1018]: https://github.com/xi-editor/druid/pull/1018 [Unreleased]: https://github.com/xi-editor/druid/compare/v0.6.0...master [0.6.0]: https://github.com/xi-editor/druid/compare/v0.5.0...v0.6.0 From dda5f59652be939b03f0b710b1ed6127551d537d Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 14:38:52 -0700 Subject: [PATCH 10/34] rustfmt --- druid/src/widget/image.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 47969e164c..b05ccf8faa 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -160,7 +160,7 @@ impl Widget for Image { /// Hoever, [enabling the `image` feature](../index.html#optional-features) /// provides several /// methods by which you can load image files. -/// +/// /// Contains raw bytes, dimensions, and image format ([`druid::piet::ImageFormat`]). #[derive(Clone)] pub struct ImageData { From 929e63973fcf0eeb63c697612b4cba9f728f28f2 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 21:47:18 -0700 Subject: [PATCH 11/34] fix typo --- druid/src/widget/image.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index b05ccf8faa..a83b994187 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -157,7 +157,7 @@ impl Widget for Image { /// Loaded image data. /// /// By default, Druid does not parse image data. -/// Hoever, [enabling the `image` feature](../index.html#optional-features) +/// However, [enabling the `image` feature](../index.html#optional-features) /// provides several /// methods by which you can load image files. /// From 09cefc54b35df555cc495b05afead8589f20b31d Mon Sep 17 00:00:00 2001 From: covercash2 Date: Fri, 5 Jun 2020 18:40:19 -0700 Subject: [PATCH 12/34] simplify changelog entry --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 953a9e4869..16bac74a27 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,7 +25,7 @@ You can find its changes [documented below](#060---2020-06-01). ### Docs -- Added documentation for the `druid::Image` widget. ([#1018] by [@covercash2]) +- Added documentation for the `Image` widget. ([#1018] by [@covercash2]) - Fixed a link in `druid::command` documentation. ([#1008] by [@covercash2]) ### Examples From 2478f9936bdd6fd3bc8e8537d9b35768f5e1ab35 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Sat, 6 Jun 2020 16:55:15 -0700 Subject: [PATCH 13/34] fix links --- druid/src/widget/image.rs | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index a83b994187..11c386a870 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -32,8 +32,7 @@ use crate::{ /// /// Note: interpolation can lead to blurry or pixelated images and so is not /// recommended for things like icons. Instead consider using -/// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) -/// and enabling the `svg` feature with `cargo`. +/// [SVG files] and enabling the `svg` feature with `cargo`. /// /// (See also: /// [`ImageData`], @@ -71,6 +70,8 @@ use crate::{ /// // set interpolation mode /// image_widget.set_interpolation_mode(InterpolationMode::NearestNeighbor); /// ``` +/// +/// [SVG files]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics pub struct Image { image_data: ImageData, fill: FillStrat, @@ -157,11 +158,14 @@ impl Widget for Image { /// Loaded image data. /// /// By default, Druid does not parse image data. -/// However, [enabling the `image` feature](../index.html#optional-features) +/// However, enabling [the `image` feature] /// provides several /// methods by which you can load image files. /// -/// Contains raw bytes, dimensions, and image format ([`druid::piet::ImageFormat`]). +/// Contains raw bytes, dimensions, and image format ([`piet::ImageFormat`]). +/// +/// [the `image` feature]: ../index.html#optional-features +/// [`piet::ImageFormat`]: druid::piet::ImageFormat #[derive(Clone)] pub struct ImageData { pixels: Vec, From 0466a127140385856d9679ba6bd5954be424449d Mon Sep 17 00:00:00 2001 From: covercash2 Date: Sat, 6 Jun 2020 18:01:43 -0700 Subject: [PATCH 14/34] clarify note about interpolation --- druid/src/widget/image.rs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 11c386a870..4927e806b0 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -30,9 +30,9 @@ use crate::{ /// Contains data about how to fill given space and interpolate pixels. /// Configuration options are provided via the builder pattern. /// -/// Note: interpolation can lead to blurry or pixelated images and so is not -/// recommended for things like icons. Instead consider using -/// [SVG files] and enabling the `svg` feature with `cargo`. +/// Note: when [scaling a bitmap image], interpolation can lead to blurry +/// or pixelated images and so is not recommended for things like icons. +/// Instead consider using [SVG files] and enabling the `svg` feature with `cargo`. /// /// (See also: /// [`ImageData`], @@ -71,6 +71,7 @@ use crate::{ /// image_widget.set_interpolation_mode(InterpolationMode::NearestNeighbor); /// ``` /// +/// [scaling a bitmap image]: https://en.wikipedia.org/wiki/Image_scaling /// [SVG files]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics pub struct Image { image_data: ImageData, From c6e9a2a1b8622456497c80468764fdc31ace5a32 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Sat, 6 Jun 2020 18:09:05 -0700 Subject: [PATCH 15/34] minor doc edits --- druid/src/widget/image.rs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 4927e806b0..9c232e7468 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -27,7 +27,7 @@ use crate::{ /// A widget that renders a bitmap Image. /// -/// Contains data about how to fill given space and interpolate pixels. +/// Contains data about how to fill the given space and interpolate pixels. /// Configuration options are provided via the builder pattern. /// /// Note: when [scaling a bitmap image], interpolation can lead to blurry @@ -51,10 +51,10 @@ use crate::{ /// /// let image_data = ImageData::empty(); /// let image_widget = Image::new(image_data) -/// // set fill strategy +/// // set the fill strategy /// .fill_mode(FillStrat::Fill) -/// // set interpolation mode -/// .interpolation_mode(InterpolationMode::NearestNeighbor); +/// // set the interpolation mode +/// .interpolation_mode(InterpolationMode::Bilinear); /// ``` /// Create an image widget and configure it using setters /// ``` @@ -65,10 +65,10 @@ use crate::{ /// /// let image_data = ImageData::empty(); /// let mut image_widget = Image::new(image_data); -/// // set fill strategy +/// // set the fill strategy /// image_widget.set_fill_mode(FillStrat::FitWidth); -/// // set interpolation mode -/// image_widget.set_interpolation_mode(InterpolationMode::NearestNeighbor); +/// // set the interpolation mode +/// image_widget.set_interpolation_mode(InterpolationMode::Bilinear); /// ``` /// /// [scaling a bitmap image]: https://en.wikipedia.org/wiki/Image_scaling @@ -156,7 +156,7 @@ impl Widget for Image { } } -/// Loaded image data. +/// Processed image data. /// /// By default, Druid does not parse image data. /// However, enabling [the `image` feature] From 5f9bdd30bed54ba223cad34711022faac8b001f4 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Fri, 12 Jun 2020 17:39:39 -0700 Subject: [PATCH 16/34] clarify note about interpolation --- druid/src/widget/image.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 9c232e7468..7a1efd3d13 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -30,7 +30,8 @@ use crate::{ /// Contains data about how to fill the given space and interpolate pixels. /// Configuration options are provided via the builder pattern. /// -/// Note: when [scaling a bitmap image], interpolation can lead to blurry +/// Note: when [scaling a bitmap image], such as supporting multiple +/// screen sizes and resolutions, interpolation can lead to blurry /// or pixelated images and so is not recommended for things like icons. /// Instead consider using [SVG files] and enabling the `svg` feature with `cargo`. /// From 7ce624c3e665abe1954463c497a50bd76886fa0b Mon Sep 17 00:00:00 2001 From: covercash2 Date: Sat, 13 Jun 2020 12:15:52 -0700 Subject: [PATCH 17/34] added link to internal docs --- druid/src/widget/image.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 7a1efd3d13..e8db39ccd2 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -72,7 +72,7 @@ use crate::{ /// image_widget.set_interpolation_mode(InterpolationMode::Bilinear); /// ``` /// -/// [scaling a bitmap image]: https://en.wikipedia.org/wiki/Image_scaling +/// [scaling a bitmap image]: ../struct.Scale.html#pixels-and-display-points /// [SVG files]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics pub struct Image { image_data: ImageData, From 8ae701b05aab374c2bb86482925205440c54408b Mon Sep 17 00:00:00 2001 From: covercash2 Date: Mon, 1 Jun 2020 12:12:38 -0700 Subject: [PATCH 18/34] add example to `Image` widget The idea is to work toward a more robust image widget. Documentation is just the first step. --- druid/src/widget/image.rs | 38 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 105a24fd17..2a0fe2ecce 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -25,7 +25,37 @@ use crate::{ PaintCtx, Rect, RenderContext, Size, UpdateCtx, Widget, }; -/// A widget that renders an Image +/// A widget that renders an Image. Contains data about how to fill given space and +/// interpolate pixels. +/// Configuration options are provided via the builder pattern. +/// +/// Note: interpolation can lead to blurry images or artifacts and so is not +/// recommended for things like icons; instead consider using +/// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) and +/// enabling the `svg` feature with `cargo`. +/// +/// (See also: +/// [`druid::widget::ImageData`], +/// [`druid::widget::FillStrat`], +/// [`druid::piet::InterpolationMode`] +/// ) +/// +/// # Example +/// +/// Create an image widget and configure it using builder methods. +/// ``` +/// use druid::{ +/// widget::{Image, ImageData, FillStrat}, +/// piet::InterpolationMode, +/// }; +/// +/// let image_data = ImageData::empty(); +/// let image_widget = Image::new(image_data) +/// // set fill strategy +/// .fill_mode(FillStrat::Fill) +/// // set interpolation mode +/// .interpolation_mode(InterpolationMode::NearestNeighbor); +/// ``` pub struct Image { image_data: ImageData, fill: FillStrat, @@ -35,7 +65,10 @@ pub struct Image { impl Image { /// Create an image drawing widget from `ImageData`. /// - /// The Image will scale to fit its box constraints. + /// By default, the Image will scale to fit its box constraints + /// ([`druid::widget::FillStrat::Fill`]) + /// and will be scaled bilinearly + /// ([`druid::piet::InterpolationMode::Bilinear`]) pub fn new(image_data: ImageData) -> Self { Image { image_data, @@ -107,6 +140,7 @@ impl Widget for Image { } /// Stored Image data. +/// Contains raw bytes, dimensions, and [format data](../piet/enum.ImageFormat.html) #[derive(Clone)] pub struct ImageData { pixels: Vec, From 40a384b694c779879a3fd075544bd29e029e4924 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Mon, 1 Jun 2020 21:38:17 -0700 Subject: [PATCH 19/34] add not about "image" feature This should make the feature more discoverable and make it clearer why it is optional. --- druid/src/widget/image.rs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 2a0fe2ecce..42b89e7084 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -34,6 +34,16 @@ use crate::{ /// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) and /// enabling the `svg` feature with `cargo`. /// +/// `druid` does not support loading image data by default. +/// However, there is an optional dependency on the `image` crate +/// that makes loading simple. This feature can be enabled with cargo. +/// For example, in `Cargo.toml`: +/// ```no_compile +/// [dependencies.druid] +/// version = "0.6.0" +/// features = ["image"] +/// ``` +/// /// (See also: /// [`druid::widget::ImageData`], /// [`druid::widget::FillStrat`], @@ -141,6 +151,17 @@ impl Widget for Image { /// Stored Image data. /// Contains raw bytes, dimensions, and [format data](../piet/enum.ImageFormat.html) +/// +/// By default druid does not parse image metadata. +/// However, druid supports an optional dependency on the `image` crate, +/// which allows reading image metadata and other kinds of image data manipulation. +/// These features are enabled with "image" feature. For example, in `Cargo.toml`: +/// ```no_compile +/// [dependencies.druid] +/// version = "0.6.0" +/// features = ["image"] +/// ``` +/// #[derive(Clone)] pub struct ImageData { pixels: Vec, From 8233389a2c354f29717ece06d9a922066ac418c1 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Mon, 1 Jun 2020 21:56:32 -0700 Subject: [PATCH 20/34] minor doc edits --- druid/src/widget/image.rs | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 42b89e7084..20672d8e07 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -31,8 +31,8 @@ use crate::{ /// /// Note: interpolation can lead to blurry images or artifacts and so is not /// recommended for things like icons; instead consider using -/// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) and -/// enabling the `svg` feature with `cargo`. +/// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) +/// and enabling the `svg` feature with `cargo`. /// /// `druid` does not support loading image data by default. /// However, there is an optional dependency on the `image` crate @@ -45,14 +45,14 @@ use crate::{ /// ``` /// /// (See also: -/// [`druid::widget::ImageData`], -/// [`druid::widget::FillStrat`], -/// [`druid::piet::InterpolationMode`] +/// [`ImageData`], +/// [`FillStrat`], +/// [`InterpolationMode`] /// ) /// /// # Example /// -/// Create an image widget and configure it using builder methods. +/// Create an image widget and configure it using builder methods /// ``` /// use druid::{ /// widget::{Image, ImageData, FillStrat}, @@ -76,9 +76,9 @@ impl Image { /// Create an image drawing widget from `ImageData`. /// /// By default, the Image will scale to fit its box constraints - /// ([`druid::widget::FillStrat::Fill`]) + /// ([`FillStrat::Fill`]) /// and will be scaled bilinearly - /// ([`druid::piet::InterpolationMode::Bilinear`]) + /// ([`InterpolationMode::Bilinear`]) pub fn new(image_data: ImageData) -> Self { Image { image_data, @@ -93,7 +93,7 @@ impl Image { self } - /// Modify the widget's `FillStrat`. + /// Modify the widget's [`FillStrat`]. pub fn set_fill_mode(&mut self, newfil: FillStrat) { self.fill = newfil; } @@ -104,7 +104,7 @@ impl Image { self } - /// Modify the widget's `InterpolationMode`. + /// Modify the widget's [`InterpolationMode`]. pub fn set_interpolation_mode(&mut self, interpolation: InterpolationMode) { self.interpolation = interpolation; } @@ -152,9 +152,9 @@ impl Widget for Image { /// Stored Image data. /// Contains raw bytes, dimensions, and [format data](../piet/enum.ImageFormat.html) /// -/// By default druid does not parse image metadata. -/// However, druid supports an optional dependency on the `image` crate, -/// which allows reading image metadata and other kinds of image data manipulation. +/// By default `druid` does not parse image metadata. +/// However, `druid` supports an optional dependency on the `image` crate, +/// which allows reading image metadata and some kinds of image data manipulation. /// These features are enabled with "image" feature. For example, in `Cargo.toml`: /// ```no_compile /// [dependencies.druid] From 9c424d947168206baa0faa0d35746e4293b69522 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Wed, 3 Jun 2020 22:12:22 -0700 Subject: [PATCH 21/34] remove image feature reminder --- druid/src/widget/image.rs | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 20672d8e07..842257ae82 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -34,16 +34,6 @@ use crate::{ /// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) /// and enabling the `svg` feature with `cargo`. /// -/// `druid` does not support loading image data by default. -/// However, there is an optional dependency on the `image` crate -/// that makes loading simple. This feature can be enabled with cargo. -/// For example, in `Cargo.toml`: -/// ```no_compile -/// [dependencies.druid] -/// version = "0.6.0" -/// features = ["image"] -/// ``` -/// /// (See also: /// [`ImageData`], /// [`FillStrat`], @@ -151,17 +141,6 @@ impl Widget for Image { /// Stored Image data. /// Contains raw bytes, dimensions, and [format data](../piet/enum.ImageFormat.html) -/// -/// By default `druid` does not parse image metadata. -/// However, `druid` supports an optional dependency on the `image` crate, -/// which allows reading image metadata and some kinds of image data manipulation. -/// These features are enabled with "image" feature. For example, in `Cargo.toml`: -/// ```no_compile -/// [dependencies.druid] -/// version = "0.6.0" -/// features = ["image"] -/// ``` -/// #[derive(Clone)] pub struct ImageData { pixels: Vec, From d8bb2af0ede91aa8d1199db0d50dbfe8dbf8d320 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 13:09:25 -0700 Subject: [PATCH 22/34] minor doc edits --- druid/src/widget/image.rs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 842257ae82..6f5f64f256 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -25,12 +25,13 @@ use crate::{ PaintCtx, Rect, RenderContext, Size, UpdateCtx, Widget, }; -/// A widget that renders an Image. Contains data about how to fill given space and -/// interpolate pixels. +/// A widget that renders a bitmap Image. +/// +/// Contains data about how to fill given space and interpolate pixels. /// Configuration options are provided via the builder pattern. /// /// Note: interpolation can lead to blurry images or artifacts and so is not -/// recommended for things like icons; instead consider using +/// recommended for things like icons. Instead consider using /// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) /// and enabling the `svg` feature with `cargo`. /// @@ -139,8 +140,9 @@ impl Widget for Image { } } -/// Stored Image data. -/// Contains raw bytes, dimensions, and [format data](../piet/enum.ImageFormat.html) +/// Owned Image data. +/// +/// Contains raw bytes, dimensions, and image format ([`ImageFormat`]) #[derive(Clone)] pub struct ImageData { pixels: Vec, From 95a37d00e79863ca7b6c64ce45af47287939abe7 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 13:11:32 -0700 Subject: [PATCH 23/34] add example --- druid/src/widget/image.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 6f5f64f256..6ef4fb458b 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -57,6 +57,20 @@ use crate::{ /// // set interpolation mode /// .interpolation_mode(InterpolationMode::NearestNeighbor); /// ``` +/// Create an image widget and configure it using setters +/// ``` +/// use druid::{ +/// widget::{Image, ImageData, FillStrat}, +/// piet::InterpolationMode, +/// }; +/// +/// let image_data = ImageData::empty(); +/// let mut image_widget = Image::new(image_data); +/// // set fill strategy +/// image_widget.set_fill_mode(FillStrat::FitWidth); +/// // set interpolation mode +/// image_widget.set_interpolation_mode(InterpolationMode::NearestNeighbor); +/// ``` pub struct Image { image_data: ImageData, fill: FillStrat, From fd7bbf403801bf9488f6399499092b1e8e99ff35 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 14:22:54 -0700 Subject: [PATCH 24/34] added note about image feature --- druid/src/widget/image.rs | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 6ef4fb458b..47969e164c 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -30,7 +30,7 @@ use crate::{ /// Contains data about how to fill given space and interpolate pixels. /// Configuration options are provided via the builder pattern. /// -/// Note: interpolation can lead to blurry images or artifacts and so is not +/// Note: interpolation can lead to blurry or pixelated images and so is not /// recommended for things like icons. Instead consider using /// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) /// and enabling the `svg` feature with `cargo`. @@ -154,9 +154,14 @@ impl Widget for Image { } } -/// Owned Image data. +/// Loaded image data. +/// +/// By default, Druid does not parse image data. +/// Hoever, [enabling the `image` feature](../index.html#optional-features) +/// provides several +/// methods by which you can load image files. /// -/// Contains raw bytes, dimensions, and image format ([`ImageFormat`]) +/// Contains raw bytes, dimensions, and image format ([`druid::piet::ImageFormat`]). #[derive(Clone)] pub struct ImageData { pixels: Vec, From a262ba57fd85c1693e1a00a154e68784922cc403 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 14:36:33 -0700 Subject: [PATCH 25/34] update changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 37e311ffc5..73607e3fcd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,7 @@ You can find its changes [documented below](#060---2020-06-01). ### Docs +- Added documentation for the `druid::Image` widget. ([#1018] by [@covercash2]) - Fixed a link in `druid::command` documentation. ([#1008] by [@covercash2]) ### Examples @@ -322,6 +323,7 @@ Last release without a changelog :( [#1008]: https://github.com/xi-editor/druid/pull/1008 [#1011]: https://github.com/xi-editor/druid/pull/1011 [#1013]: https://github.com/xi-editor/druid/pull/1013 +[#1018]: https://github.com/xi-editor/druid/pull/1018 [Unreleased]: https://github.com/xi-editor/druid/compare/v0.6.0...master [0.6.0]: https://github.com/xi-editor/druid/compare/v0.5.0...v0.6.0 From ae67f6b30befe0474c7969e1706f543b5923a864 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 14:38:52 -0700 Subject: [PATCH 26/34] rustfmt --- druid/src/widget/image.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 47969e164c..b05ccf8faa 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -160,7 +160,7 @@ impl Widget for Image { /// Hoever, [enabling the `image` feature](../index.html#optional-features) /// provides several /// methods by which you can load image files. -/// +/// /// Contains raw bytes, dimensions, and image format ([`druid::piet::ImageFormat`]). #[derive(Clone)] pub struct ImageData { From 5cb9577e9ce2f8a4d9163d4fdb7eb22d6b961bd7 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 4 Jun 2020 21:47:18 -0700 Subject: [PATCH 27/34] fix typo --- druid/src/widget/image.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index b05ccf8faa..a83b994187 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -157,7 +157,7 @@ impl Widget for Image { /// Loaded image data. /// /// By default, Druid does not parse image data. -/// Hoever, [enabling the `image` feature](../index.html#optional-features) +/// However, [enabling the `image` feature](../index.html#optional-features) /// provides several /// methods by which you can load image files. /// From 037e3e8745260e6a0c2cabc9e5ef6e95ab8431ac Mon Sep 17 00:00:00 2001 From: covercash2 Date: Fri, 5 Jun 2020 18:40:19 -0700 Subject: [PATCH 28/34] simplify changelog entry --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 73607e3fcd..25c79b0505 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,7 +27,7 @@ You can find its changes [documented below](#060---2020-06-01). ### Docs -- Added documentation for the `druid::Image` widget. ([#1018] by [@covercash2]) +- Added documentation for the `Image` widget. ([#1018] by [@covercash2]) - Fixed a link in `druid::command` documentation. ([#1008] by [@covercash2]) ### Examples From b79a175967e30cb6de1f24ffab580ff66f592b06 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Sat, 6 Jun 2020 16:55:15 -0700 Subject: [PATCH 29/34] fix links --- druid/src/widget/image.rs | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index a83b994187..11c386a870 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -32,8 +32,7 @@ use crate::{ /// /// Note: interpolation can lead to blurry or pixelated images and so is not /// recommended for things like icons. Instead consider using -/// [SVG files](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) -/// and enabling the `svg` feature with `cargo`. +/// [SVG files] and enabling the `svg` feature with `cargo`. /// /// (See also: /// [`ImageData`], @@ -71,6 +70,8 @@ use crate::{ /// // set interpolation mode /// image_widget.set_interpolation_mode(InterpolationMode::NearestNeighbor); /// ``` +/// +/// [SVG files]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics pub struct Image { image_data: ImageData, fill: FillStrat, @@ -157,11 +158,14 @@ impl Widget for Image { /// Loaded image data. /// /// By default, Druid does not parse image data. -/// However, [enabling the `image` feature](../index.html#optional-features) +/// However, enabling [the `image` feature] /// provides several /// methods by which you can load image files. /// -/// Contains raw bytes, dimensions, and image format ([`druid::piet::ImageFormat`]). +/// Contains raw bytes, dimensions, and image format ([`piet::ImageFormat`]). +/// +/// [the `image` feature]: ../index.html#optional-features +/// [`piet::ImageFormat`]: druid::piet::ImageFormat #[derive(Clone)] pub struct ImageData { pixels: Vec, From 7f9b9230d4e190af845495ed52faf3d6b702f73f Mon Sep 17 00:00:00 2001 From: covercash2 Date: Sat, 6 Jun 2020 18:01:43 -0700 Subject: [PATCH 30/34] clarify note about interpolation --- druid/src/widget/image.rs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 11c386a870..4927e806b0 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -30,9 +30,9 @@ use crate::{ /// Contains data about how to fill given space and interpolate pixels. /// Configuration options are provided via the builder pattern. /// -/// Note: interpolation can lead to blurry or pixelated images and so is not -/// recommended for things like icons. Instead consider using -/// [SVG files] and enabling the `svg` feature with `cargo`. +/// Note: when [scaling a bitmap image], interpolation can lead to blurry +/// or pixelated images and so is not recommended for things like icons. +/// Instead consider using [SVG files] and enabling the `svg` feature with `cargo`. /// /// (See also: /// [`ImageData`], @@ -71,6 +71,7 @@ use crate::{ /// image_widget.set_interpolation_mode(InterpolationMode::NearestNeighbor); /// ``` /// +/// [scaling a bitmap image]: https://en.wikipedia.org/wiki/Image_scaling /// [SVG files]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics pub struct Image { image_data: ImageData, From 978cfd468935e7257a6d2b9177dea65fd0c1db9f Mon Sep 17 00:00:00 2001 From: covercash2 Date: Sat, 6 Jun 2020 18:09:05 -0700 Subject: [PATCH 31/34] minor doc edits --- druid/src/widget/image.rs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 4927e806b0..9c232e7468 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -27,7 +27,7 @@ use crate::{ /// A widget that renders a bitmap Image. /// -/// Contains data about how to fill given space and interpolate pixels. +/// Contains data about how to fill the given space and interpolate pixels. /// Configuration options are provided via the builder pattern. /// /// Note: when [scaling a bitmap image], interpolation can lead to blurry @@ -51,10 +51,10 @@ use crate::{ /// /// let image_data = ImageData::empty(); /// let image_widget = Image::new(image_data) -/// // set fill strategy +/// // set the fill strategy /// .fill_mode(FillStrat::Fill) -/// // set interpolation mode -/// .interpolation_mode(InterpolationMode::NearestNeighbor); +/// // set the interpolation mode +/// .interpolation_mode(InterpolationMode::Bilinear); /// ``` /// Create an image widget and configure it using setters /// ``` @@ -65,10 +65,10 @@ use crate::{ /// /// let image_data = ImageData::empty(); /// let mut image_widget = Image::new(image_data); -/// // set fill strategy +/// // set the fill strategy /// image_widget.set_fill_mode(FillStrat::FitWidth); -/// // set interpolation mode -/// image_widget.set_interpolation_mode(InterpolationMode::NearestNeighbor); +/// // set the interpolation mode +/// image_widget.set_interpolation_mode(InterpolationMode::Bilinear); /// ``` /// /// [scaling a bitmap image]: https://en.wikipedia.org/wiki/Image_scaling @@ -156,7 +156,7 @@ impl Widget for Image { } } -/// Loaded image data. +/// Processed image data. /// /// By default, Druid does not parse image data. /// However, enabling [the `image` feature] From 21e92a7c7a2a66bfa30a02786ac16ae05cdd4452 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Fri, 12 Jun 2020 17:39:39 -0700 Subject: [PATCH 32/34] clarify note about interpolation --- druid/src/widget/image.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 9c232e7468..7a1efd3d13 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -30,7 +30,8 @@ use crate::{ /// Contains data about how to fill the given space and interpolate pixels. /// Configuration options are provided via the builder pattern. /// -/// Note: when [scaling a bitmap image], interpolation can lead to blurry +/// Note: when [scaling a bitmap image], such as supporting multiple +/// screen sizes and resolutions, interpolation can lead to blurry /// or pixelated images and so is not recommended for things like icons. /// Instead consider using [SVG files] and enabling the `svg` feature with `cargo`. /// From f26a35465a7eccf11f11b0d8f4b88350aa46dcb0 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Sat, 13 Jun 2020 12:15:52 -0700 Subject: [PATCH 33/34] added link to internal docs --- druid/src/widget/image.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index 7a1efd3d13..e8db39ccd2 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -72,7 +72,7 @@ use crate::{ /// image_widget.set_interpolation_mode(InterpolationMode::Bilinear); /// ``` /// -/// [scaling a bitmap image]: https://en.wikipedia.org/wiki/Image_scaling +/// [scaling a bitmap image]: ../struct.Scale.html#pixels-and-display-points /// [SVG files]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics pub struct Image { image_data: ImageData, From a202bf8ea34b70897b727cc386fbb9e91cb93226 Mon Sep 17 00:00:00 2001 From: covercash2 Date: Thu, 18 Jun 2020 11:21:35 -0700 Subject: [PATCH 34/34] Links now work on stable --- druid/src/widget/image.rs | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/druid/src/widget/image.rs b/druid/src/widget/image.rs index e8db39ccd2..6307a85d59 100644 --- a/druid/src/widget/image.rs +++ b/druid/src/widget/image.rs @@ -74,6 +74,9 @@ use crate::{ /// /// [scaling a bitmap image]: ../struct.Scale.html#pixels-and-display-points /// [SVG files]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics +/// [`ImageData`]: struct.ImageData.html +/// [`FillStrat`]: ../widget/enum.FillStrat.html +/// [`InterpolationMode`]: ../piet/enum.InterpolationMode.html pub struct Image { image_data: ImageData, fill: FillStrat, @@ -87,6 +90,9 @@ impl Image { /// ([`FillStrat::Fill`]) /// and will be scaled bilinearly /// ([`InterpolationMode::Bilinear`]) + /// + /// [`FillStrat::Fill`]: ../widget/enum.FillStrat.html#variant.Fill + /// [`InterpolationMode::Bilinear`]: ../piet/enum.InterpolationMode.html#variant.Bilinear pub fn new(image_data: ImageData) -> Self { Image { image_data, @@ -101,7 +107,7 @@ impl Image { self } - /// Modify the widget's [`FillStrat`]. + /// Modify the widget's fill strategy. pub fn set_fill_mode(&mut self, newfil: FillStrat) { self.fill = newfil; } @@ -112,7 +118,7 @@ impl Image { self } - /// Modify the widget's [`InterpolationMode`]. + /// Modify the widget's interpolation mode. pub fn set_interpolation_mode(&mut self, interpolation: InterpolationMode) { self.interpolation = interpolation; } @@ -167,7 +173,7 @@ impl Widget for Image { /// Contains raw bytes, dimensions, and image format ([`piet::ImageFormat`]). /// /// [the `image` feature]: ../index.html#optional-features -/// [`piet::ImageFormat`]: druid::piet::ImageFormat +/// [`piet::ImageFormat`]: ../piet/enum.ImageFormat.html #[derive(Clone)] pub struct ImageData { pixels: Vec,