From e8a399571028408650ce2778a956c7f2a7facb16 Mon Sep 17 00:00:00 2001
From: Richard Acayan <mailingradian@gmail.com>
Date: Fri, 20 Sep 2024 21:23:06 -0400
Subject: [PATCH] wayland: buffer: add comments to outline some non-trivial
 functions

---
 src/wayland/buffer.rs | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/src/wayland/buffer.rs b/src/wayland/buffer.rs
index 3cf52aa..197ccae 100644
--- a/src/wayland/buffer.rs
+++ b/src/wayland/buffer.rs
@@ -95,6 +95,11 @@ impl<T: Dispatch<WlShmPool, u32>
         })
     }
 
+    /*
+     * Commit a pending resize operation on buffer. The caller is responsible
+     * for checking if the buffer is used, allowing the check to be skipped when
+     * releasing the buffer.
+     */
     fn commit_resize(&mut self)
     {
         if self.resizing {
@@ -106,6 +111,11 @@ impl<T: Dispatch<WlShmPool, u32>
         }
     }
 
+    /*
+     * Begin a resize operation. The shared memory object gets expanded if the
+     * new size can't fit. The operation will be completed when the buffer is
+     * not used.
+     */
     pub fn resize(&mut self, width: i32, height: i32) -> Result<(), Error>
     {
         if width <= 0 || height <= 0 {
@@ -116,7 +126,6 @@ impl<T: Dispatch<WlShmPool, u32>
         if self.capacity < width * height * 4 {
             self.capacity = width * height * 4;
 
-            // Failure is a bug in the above check or the capacity calculation.
             let filelen = self.capacity as u64;
             self.file.set_len(filelen)?;
 
@@ -136,12 +145,21 @@ impl<T: Dispatch<WlShmPool, u32>
         Ok(())
     }
 
+    /*
+     * Get the contents of the buffer. After rendering, the buffer is the
+     * program's only copy of the rendered image. The contents of this buffer
+     * can be written to the unused buffer in double-buffering.
+     */
     pub fn image(&self) -> ImgRef<BGRA<u8>>
     {
         let ptr = self.map.as_ref().as_bgra();
         ImgRef::new(ptr, self.width as usize, self.height as usize)
     }
 
+    /*
+     * Consume a buffer to be drawn to and optionally used by a surface. If the
+     * OSK is hidden, do not attach the surface.
+     */
     pub fn consume(&mut self, surface: Option<&WlSurface>) -> Option<ImgRefMut<BGRA<u8>>>
     {
         if self.used {
@@ -161,12 +179,22 @@ impl<T: Dispatch<WlShmPool, u32>
         Some(img)
     }
 
+    /*
+     * Allow the buffer to be drawn to again and commit any pending resizes.
+     * When a double-buffered surface is resized, the used and unused buffer
+     * both need to resize eventually.
+     */
     pub fn release(&mut self)
     {
         self.used = false;
         self.commit_resize();
     }
 
+    /*
+     * Write an image to the buffer for the next consumption. This is used in
+     * double-buffering to ensure both buffers have up-to-date contents without
+     * redrawing every time.
+     */
     pub fn writeback(&mut self, src: &ImgRef<BGRA<u8>>, x: usize, y: usize)
     {
         if self.used {