From cc148ca895d8b11a5e98d098a4a56cecf60165c9 Mon Sep 17 00:00:00 2001
From: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
Date: Sun, 22 May 2022 17:32:38 +0200
Subject: [PATCH] Add texture filters to changelogs and improve docs

---
 CHANGELOG.md             |  1 +
 egui_extras/CHANGELOG.md |  1 +
 egui_extras/src/image.rs | 58 ++++++++++++++++++++--------------------
 epaint/src/textures.rs   | 11 +++++++-
 4 files changed, 41 insertions(+), 30 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f1d666c7..590ece1a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@ NOTE: [`epaint`](epaint/CHANGELOG.md), [`eframe`](eframe/CHANGELOG.md), [`egui-w
 * Optimized painting of filled circles (e.g. for scatter plots) by 10x or more ([#1616](https://github.com/emilk/egui/pull/1616)).
 * Added opt-in feature `deadlock_detection` to detect double-lock of mutexes on the same thread ([#1619](https://github.com/emilk/egui/pull/1619)).
 * Added `InputState::stable_dt`: a more stable estimate for the delta-time in reactive mode ([#1625](https://github.com/emilk/egui/pull/1625)).
+* You can now specify a texture filter for your textures ([#1636](https://github.com/emilk/egui/pull/1636)).
 
 ### Fixed 🐛
 * Fixed `ImageButton`'s changing background padding on hover ([#1595](https://github.com/emilk/egui/pull/1595)).
diff --git a/egui_extras/CHANGELOG.md b/egui_extras/CHANGELOG.md
index a68ed8b2..81db4ecc 100644
--- a/egui_extras/CHANGELOG.md
+++ b/egui_extras/CHANGELOG.md
@@ -3,6 +3,7 @@ All notable changes to the `egui_extras` integration will be noted in this file.
 
 
 ## Unreleased
+* You can now specify a texture filter for `RetainedImage` ([#1636](https://github.com/emilk/egui/pull/1636)).
 
 
 ## 0.18.0 - 2022-04-30
diff --git a/egui_extras/src/image.rs b/egui_extras/src/image.rs
index 807ed98b..03d950db 100644
--- a/egui_extras/src/image.rs
+++ b/egui_extras/src/image.rs
@@ -26,35 +26,6 @@ impl RetainedImage {
         }
     }
 
-    /// Set the texture filter to use for the image.
-    ///
-    /// **Note:** If the texture has already been uploaded to the GPU, this will require
-    /// re-uploading the texture with the updated filter.
-    ///
-    /// # Example
-    /// ```rust
-    /// # use egui_extras::RetainedImage;
-    /// # use egui::{Color32, epaint::{ColorImage, textures::TextureFilter}};
-    /// # let pixels = vec![Color32::BLACK];
-    /// # let color_image = ColorImage {
-    /// #   size: [1, 1],
-    /// #   pixels,
-    /// # };
-    /// #
-    /// // Upload a pixel art image without it getting blurry when resized
-    /// let image = RetainedImage::from_color_image("my_image", color_image)
-    ///     .with_texture_filter(TextureFilter::Nearest);
-    /// ```
-    pub fn with_texture_filter(mut self, filter: TextureFilter) -> Self {
-        self.filter = filter;
-
-        // If the texture has already been uploaded, this will force it to be re-uploaded with the
-        // updated filter.
-        *self.texture.lock() = None;
-
-        self
-    }
-
     /// Load a (non-svg) image.
     ///
     /// Requires the "image" feature. You must also opt-in to the image formats you need
@@ -94,6 +65,35 @@ impl RetainedImage {
         Self::from_svg_bytes(debug_name, svg_str.as_bytes())
     }
 
+    /// Set the texture filter to use for the image.
+    ///
+    /// **Note:** If the texture has already been uploaded to the GPU, this will require
+    /// re-uploading the texture with the updated filter.
+    ///
+    /// # Example
+    /// ```rust
+    /// # use egui_extras::RetainedImage;
+    /// # use egui::{Color32, epaint::{ColorImage, textures::TextureFilter}};
+    /// # let pixels = vec![Color32::BLACK];
+    /// # let color_image = ColorImage {
+    /// #   size: [1, 1],
+    /// #   pixels,
+    /// # };
+    /// #
+    /// // Upload a pixel art image without it getting blurry when resized
+    /// let image = RetainedImage::from_color_image("my_image", color_image)
+    ///     .with_texture_filter(TextureFilter::Nearest);
+    /// ```
+    pub fn with_texture_filter(mut self, filter: TextureFilter) -> Self {
+        self.filter = filter;
+
+        // If the texture has already been uploaded, this will force it to be re-uploaded with the
+        // updated filter.
+        *self.texture.lock() = None;
+
+        self
+    }
+
     /// The size of the image data (number of pixels wide/high).
     pub fn size(&self) -> [usize; 2] {
         self.size
diff --git a/epaint/src/textures.rs b/epaint/src/textures.rs
index de1b08a0..c7d7bd47 100644
--- a/epaint/src/textures.rs
+++ b/epaint/src/textures.rs
@@ -136,11 +136,20 @@ pub struct TextureMeta {
     pub filter: TextureFilter,
 }
 
+/// How the texture texels are filtered.
 #[derive(Copy, Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
 pub enum TextureFilter {
-    Linear,
+    /// Show the nearest pixel value.
+    ///
+    /// When zooming in you will get sharp, square pixels/texels.
+    /// When zooming out you will get a very crisp (and aliased) look.
     Nearest,
+
+    /// Linearly interpolate the nearest neighbors, creating a smoother look when zooming in and out.
+    ///
+    /// This is the default.
+    Linear,
 }
 
 impl Default for TextureFilter {