From 1df81509df924f5028dd16d922e0cc9b401f72dd Mon Sep 17 00:00:00 2001
From: Joakim Hulthe <joakim@hulthe.net>
Date: Sun, 15 Jun 2025 12:52:13 +0200
Subject: [PATCH] Add some comments to the handwriting code

---
 src/painting.rs | 31 +++++++++++++++++++++++--------
 1 file changed, 23 insertions(+), 8 deletions(-)

diff --git a/src/painting.rs b/src/painting.rs
index 1ce4b32..8c02732 100644
--- a/src/painting.rs
+++ b/src/painting.rs
@@ -219,8 +219,8 @@ impl Handwriting {
             self.height = self.desired_height;
         }
 
-        let size = Vec2::new(ui.available_width(), self.height);
-        let (response, painter) = ui.allocate_painter(size, Sense::drag());
+        let desired_size = Vec2::new(ui.available_width(), self.height);
+        let (response, painter) = ui.allocate_painter(desired_size, Sense::drag());
 
         let mut response = response
             //.on_hover_cursor(CursorIcon::Crosshair)
@@ -229,16 +229,23 @@ impl Handwriting {
 
         let size = response.rect.size();
 
+        // Calculate matrices that convert between screen-space and image-space.
+        // - image-space: 0,0 is the top-left of the texture.
+        // - screen-space: 0,0 is the top-left of the window.
+        // Both spaces use the same logical points, not pixels.
         let to_screen =
             emath::RectTransform::from_to(Rect::from_min_size(Pos2::ZERO, size), response.rect);
         let from_screen = to_screen.inverse();
 
-        let is_drawing = response.interact_pointer_pos().is_some();
+        // Was the user in the process of drawing a stroke last frame?
         let was_drawing = !self.current_stroke.is_empty();
 
+        // Is the user in the process of drawing a stroke now?
+        let is_drawing = response.interact_pointer_pos().is_some();
+
         if !is_drawing {
-            // commit current line
             if was_drawing {
+                // commit current line
                 self.commit_current_line(hw_response);
                 response.mark_changed();
             }
@@ -251,6 +258,8 @@ impl Handwriting {
                 .map(|p| p.y + HANDWRITING_BOTTOM_PADDING)
                 .fold(HANDWRITING_MIN_HEIGHT, |max, y| max.max(y));
 
+            // Change the height of the handwriting item.
+            // We don't do this mid-stroke, only when the user e.g. lifts the pen.
             if self.desired_height != lines_max_y {
                 self.desired_height = lines_max_y;
                 response.mark_changed();
@@ -285,6 +294,7 @@ impl Handwriting {
                 .collect::<Vec<_>>()
             });
 
+            // Process input events and turn them into strokes
             for event in events {
                 let last_canvas_pos = self.current_stroke.last();
 
@@ -371,6 +381,7 @@ impl Handwriting {
             }
         }
 
+        // Draw the horizontal ruled lines
         (1..)
             .map(|n| n as f32 * HANDWRITING_LINE_SPACING)
             .take_while(|&y| y < size.y)
@@ -383,9 +394,12 @@ impl Handwriting {
                 painter.add(shape);
             });
 
+        // Get the dimensions of the image
         let mesh_rect = response
             .rect
             .with_max_y(response.rect.min.y + self.desired_height);
+
+        // These are the values that, if changed, would require the mesh to be re-rendered.
         let new_context = MeshContext {
             ui_theme: ui.ctx().theme(),
             pixels_per_point: ui.pixels_per_point(),
@@ -393,24 +407,25 @@ impl Handwriting {
             stroke: style.stroke,
         };
 
+        // Figure out if we need to re-rasterize the mesh.
         if Some(&new_context) != self.last_mesh_ctx.as_ref() {
             self.refresh_texture = true;
         }
 
         if self.refresh_texture {
-            // rasterize the entire texture from scratch
+            // ...if we do, rasterize the entire texture from scratch
             self.refresh_texture(style, new_context, ui);
             self.unblitted_lines.clear();
         } else if !self.unblitted_lines.is_empty() {
-            // only rasterize the new lines onto the existing texture
+            // ...if we don't, we can get away with  only rasterizing the *new* lines onto the
+            // existing texture.
             for [from, to] in std::mem::take(&mut self.unblitted_lines) {
                 self.draw_line_to_texture(from, to, &new_context, ui);
             }
             self.unblitted_lines.clear();
         }
 
-        //painter.add(self.mesh.clone());
-
+        // Draw the texture
         if let Some(texture) = &self.texture {
             let texture = SizedTexture::new(texture.id(), texture.size_vec2());
             let shape = RectShape {