issue-1031: Small changes, documentation, comments

Author: KirmesBude

crates/bevy_render/src/lib.rs

@@ -209,10 +209,7 @@ impl Plugin for RenderPlugin {
                 .label(RenderSystem::VisibleEntities)
                 .after(TransformSystem::TransformPropagate),
         )
-        .add_system_to_stage(
-            CoreStage::PostUpdate,
-            window_icon_changed.system(), /* TODO: label? */
-        )
+        .add_system_to_stage(CoreStage::PostUpdate, window_icon_changed.system())
         .add_system_to_stage(
             RenderStage::RenderResource,
             shader::shader_update_system.system(),
@@ -274,8 +271,8 @@ fn window_icon_changed(
                     if let Some(handle_path) = asset_server.get_handle_path(o.get()) {
                         if handle_path.path() != path {
                             o.insert(asset_server.load(path.clone()));
-                        }
-                    }
+                        } /* else we are still attempting to load the initial asset */
+                    } /* else the path from the asset is not available yet */
                 }
                 Entry::Vacant(v) => {
                     v.insert(asset_server.load(path.clone()));
@@ -290,9 +287,7 @@ fn window_icon_changed(
                 LoadState::Loaded => {
                     let texture = textures.get(handle).unwrap(); /* Safe to unwrap here, because loadstate==loaded is checked */
 
-                    /* TODO: Not actually sure if we need to check the error here
-                    Whatever Texture gives us might be fine */
-                    let window_icon_bytes = WindowIconBytes::new(
+                    let window_icon_bytes = WindowIconBytes::from_rgba(
                         texture.data.clone(),
                         texture.size.width,
                         texture.size.height,

crates/bevy_window/src/window.rs

@@ -91,13 +91,18 @@ impl WindowResizeConstraints {
     }
 }
 
+/// Generic icon buffer for a window.
+/// Replicates the struct from winit.
+///
+/// Only allows rgba images.
 #[derive(Debug, Clone)]
 pub struct WindowIconBytes {
     bytes: Vec<u8>,
     width: u32,
     height: u32,
 }
 
+/// Errors that occur while constructing window icons.
 #[derive(Error, Debug)]
 pub enum WindowIconBytesError {
     #[error("32bpp RGBA image buffer expected, but {bytes_length} is not divisible by 4")]
@@ -109,6 +114,10 @@ pub enum WindowIconBytesError {
     },
 }
 
+/// The icon on a window.
+/// The path buffer in the `Path` variant will be passed to the asset server and will automatically trigger the call to the window backend.
+///
+/// Make sure that the source image is reasonably sized. Refer to winit's `set_window_icon` function.
 #[derive(Debug, Clone)]
 pub enum WindowIcon {
     Path(PathBuf),
@@ -131,7 +140,14 @@ impl From<WindowIconBytes> for WindowIcon {
 }
 
 impl WindowIconBytes {
-    pub fn new(bytes: Vec<u8>, width: u32, height: u32) -> Result<Self, WindowIconBytesError> {
+    /// Create a window icon from a rgba image.
+    ///
+    /// Returns a `WindowIconBytesError` if `bytes` do not add up to a rgba image or the size does not match the specified width and height.
+    pub fn from_rgba(
+        bytes: Vec<u8>,
+        width: u32,
+        height: u32,
+    ) -> Result<Self, WindowIconBytesError> {
         let pixel_count = (width * height) as usize;
         let pixel_bytes_length = pixel_count * 4;
         let bytes_length = bytes.len();
@@ -152,14 +168,17 @@ impl WindowIconBytes {
         }
     }
 
+    /// Bytes of the rgba icon.
     pub fn bytes(&self) -> &[u8] {
         &self.bytes
     }
 
+    /// Width of the icon.
     pub fn width(&self) -> u32 {
         self.width
     }
 
+    /// Height if the icon.
     pub fn height(&self) -> u32 {
         self.height
     }
@@ -200,9 +219,9 @@ pub struct Window {
     cursor_position: Option<Vec2>,
     focused: bool,
     mode: WindowMode,
+    icon: Option<WindowIcon>,
     #[cfg(target_arch = "wasm32")]
     pub canvas: Option<String>,
-    icon: Option<WindowIcon>,
     command_queue: Vec<WindowCommand>,
 }
 

crates/bevy_winit/src/lib.rs

@@ -163,7 +163,7 @@ fn change_window(world: &mut World) {
                 bevy_window::WindowCommand::SetIcon { window_icon_bytes } => {
                     let window = winit_windows.get_window(id).unwrap();
 
-                    /* Failures should already be covered in WindowIconBytes constructor */
+                    /* Winit errors are replicated in the WindowIconBytes constructor, so it is safe to ignore here */
                     window.set_window_icon(
                         Icon::from_rgba(
                             window_icon_bytes.bytes().to_vec(),

crates/bevy_winit/src/winit_windows.rs

@@ -149,7 +149,7 @@ impl WinitWindows {
         );
 
         if let Some(icon_path) = &window_descriptor.icon_path {
-            window.set_icon(icon_path); /* This will queue up SetWindowIcon until the asset has loaded */
+            window.set_icon(icon_path); /* This will queue up loading the asset and subsequently set the window icon */
         }
 
         window

examples/window/window_settings.rs

@@ -36,11 +36,13 @@ fn toggle_cursor(input: Res<Input<KeyCode>>, mut windows: ResMut<Windows>) {
     }
 }
 
+/// This system toggles the windows' icon (on/off) when I is pressed
 fn toggle_icon(input: Res<Input<KeyCode>>, mut windows: ResMut<Windows>) {
     let window = windows.get_primary_mut().unwrap();
     if input.just_pressed(KeyCode::I) {
         match window.icon() {
             None => {
+                /* Alternatively you can construct a "buffer-based" WindowIcon and bypass the asset server */
                 window.set_icon("android-res/mipmap-mdpi/ic_launcher.png");
             }
             _ => window.clear_icon(),