From 1bd33cac31e12fee9382774c5d64934a5c5bb881 Mon Sep 17 00:00:00 2001
From: sark <sarkahn@gmail.com>
Date: Sun, 26 Jun 2022 02:26:29 +0000
Subject: [PATCH] Default image sampler doc fix (#5047)

# Objective

Attempt to more clearly document `ImageSettings` and setting a default sampler for new images, as per #5046

## Changelog

- Moved ImageSettings into image.rs, image::* is already exported. Makes it simpler for linking docs.
- Renamed "DefaultImageSampler" to "RenderDefaultImageSampler". Not a great name, but more consistent with other render resources.
- Added/updated related docs
---
 crates/bevy_render/src/texture/image.rs | 47 +++++++++++++++++++++----
 crates/bevy_render/src/texture/mod.rs   | 28 ---------------
 2 files changed, 41 insertions(+), 34 deletions(-)

diff --git a/crates/bevy_render/src/texture/image.rs b/crates/bevy_render/src/texture/image.rs
index bec554b1f6b57..cf191c270cc6d 100644
--- a/crates/bevy_render/src/texture/image.rs
+++ b/crates/bevy_render/src/texture/image.rs
@@ -108,16 +108,18 @@ pub struct Image {
     pub data: Vec<u8>,
     // TODO: this nesting makes accessing Image metadata verbose. Either flatten out descriptor or add accessors
     pub texture_descriptor: wgpu::TextureDescriptor<'static>,
+    /// The [`ImageSampler`] to use during rendering.
     pub sampler_descriptor: ImageSampler,
 }
 
-/// Used in `Image`, this determines what image sampler to use when rendering. The default setting,
-/// [`ImageSampler::Default`], will result in reading the sampler set in the [`DefaultImageSampler`]
-/// resource - the global default sampler - at runtime. Setting this to [`ImageSampler::Descriptor`]
-/// will override the global default descriptor for this [`Image`].
+/// Used in [`Image`], this determines what image sampler to use when rendering. The default setting,
+/// [`ImageSampler::Default`], will read the sampler from the [`ImageSettings`] resource at runtime.
+/// Setting this to [`ImageSampler::Descriptor`] will override the global default descriptor for this [`Image`].
 #[derive(Debug, Clone)]
 pub enum ImageSampler {
+    /// Default image sampler, derived from the [`ImageSettings`] resource.
     Default,
+    /// Custom sampler for this image which will override global default.
     Descriptor(wgpu::SamplerDescriptor<'static>),
 }
 impl Default for ImageSampler {
@@ -146,8 +148,41 @@ impl ImageSampler {
     }
 }
 
-/// Resource used as the global default image sampler for [`Image`]s with their `sampler_descriptor`
-/// set to [`ImageSampler::Default`].
+/// Global resource for [`Image`] settings.
+///
+/// Can be set via `insert_resource` during app initialization to change the default settings.
+pub struct ImageSettings {
+    /// The default image sampler to use when [`ImageSampler`] is set to `Default`.
+    pub default_sampler: wgpu::SamplerDescriptor<'static>,
+}
+
+impl Default for ImageSettings {
+    fn default() -> Self {
+        ImageSettings::default_linear()
+    }
+}
+
+impl ImageSettings {
+    /// Creates image settings with linear sampling by default.
+    pub fn default_linear() -> ImageSettings {
+        ImageSettings {
+            default_sampler: ImageSampler::linear_descriptor(),
+        }
+    }
+
+    /// Creates image settings with nearest sampling by default.
+    pub fn default_nearest() -> ImageSettings {
+        ImageSettings {
+            default_sampler: ImageSampler::nearest_descriptor(),
+        }
+    }
+}
+
+/// A rendering resource for the default image sampler which is set during renderer
+/// intialization.
+///
+/// The [`ImageSettings`] resource can be set during app initialization to change the default
+/// image sampler.
 #[derive(Debug, Clone, Deref, DerefMut)]
 pub struct DefaultImageSampler(pub(crate) Sampler);
 
diff --git a/crates/bevy_render/src/texture/mod.rs b/crates/bevy_render/src/texture/mod.rs
index 1ca625d1a2cfc..5b34210df6a5b 100644
--- a/crates/bevy_render/src/texture/mod.rs
+++ b/crates/bevy_render/src/texture/mod.rs
@@ -82,34 +82,6 @@ impl Plugin for ImagePlugin {
     }
 }
 
-/// [`ImagePlugin`] settings.
-pub struct ImageSettings {
-    /// The default image sampler to use when [`ImageSampler`] is set to `Default`.
-    pub default_sampler: wgpu::SamplerDescriptor<'static>,
-}
-
-impl Default for ImageSettings {
-    fn default() -> Self {
-        ImageSettings::default_linear()
-    }
-}
-
-impl ImageSettings {
-    /// Creates image settings with default linear sampling.
-    pub fn default_linear() -> ImageSettings {
-        ImageSettings {
-            default_sampler: ImageSampler::linear_descriptor(),
-        }
-    }
-
-    /// Creates image settings with default nearest sampling.
-    pub fn default_nearest() -> ImageSettings {
-        ImageSettings {
-            default_sampler: ImageSampler::nearest_descriptor(),
-        }
-    }
-}
-
 pub trait BevyDefault {
     fn bevy_default() -> Self;
 }