From: Aaron Taylor <ataylor@subgeniuskitty.com>
Date: Sat, 10 Jul 2021 22:53:16 +0000 (-0700)
Subject: Minor cleanup of helper functions in NEDsim.
X-Git-Url: http://git.subgeniuskitty.com/screensavers/.git/commitdiff_plain/280460e645422e4469fc5c74c21bd381bd4e3aa2

Minor cleanup of helper functions in NEDsim.
---

diff --git a/hacks/NEDsim/NEDsim.c b/hacks/NEDsim/NEDsim.c
index e40d839..c6c7c3d 100644
--- a/hacks/NEDsim/NEDsim.c
+++ b/hacks/NEDsim/NEDsim.c
@@ -186,7 +186,7 @@ static struct color_scheme color_list[] = {
 /* Helper Functions                                                           */
 /* -------------------------------------------------------------------------- */
 
-// TODO: Explain
+// Set foreground color for the current graphics context.
 static void
 set_color(struct NEDsim * nedsim, struct color_rgb * color)
 {
@@ -203,9 +203,8 @@ set_color(struct NEDsim * nedsim, struct color_rgb * color)
     XSetForeground(nedsim->dpy, nedsim->gc, temp.pixel);
 }
 
-// TODO: Explain
 // TODO: Make this a lot faster.
-// Input: size in 'cells', and sets font to fill that size, minus border and padding room.
+// Set font size to fill 'size' cells vertically, minus space for border and padding.
 static void
 set_font_size(struct NEDsim * nedsim, int size)
 {
@@ -259,8 +258,9 @@ set_font_size(struct NEDsim * nedsim, int size)
     nedsim->current_font = font_full_name;
 }
 
-// TODO: Explain
-// TODO: Explain that this returns result in pixels so we can track fractional cell usage.
+// Unlike most functions in this program that input/output in units of 'cells',
+// this function uses units of 'pixels' so the caller can track fractional cell
+// usage (e.g. for centering the text).
 static void
 get_text_size(struct NEDsim * nedsim, const char * text, int * x_size, int * y_size)
 {
@@ -272,13 +272,14 @@ get_text_size(struct NEDsim * nedsim, const char * text, int * x_size, int * y_s
     *y_size = overall.ascent - overall.descent;
 }
 
-// TODO: Explain
-// TODO: Note that this might leave the foreground color changed.
-// Argument coordinates are in 'cells', not pixels.
+// When specifying the rectangular area to draw, all coordinates and sizes are
+// in units of 'cells'.  Also, be aware that this function alters the
+// foreground color.
 static void
 draw_rect_area(struct NEDsim * nedsim, size_t x_origin, size_t y_origin, size_t x_size, size_t y_size,
                Bool bord_top, Bool bord_bottom, Bool bord_left, Bool bord_right)
 {
+    // First fill in the rectangular area...
     x_origin *= nedsim->cell_size;
     x_origin += nedsim->origin_x_offset;
     y_origin *= nedsim->cell_size;
@@ -287,25 +288,29 @@ draw_rect_area(struct NEDsim * nedsim, size_t x_origin, size_t y_origin, size_t
     y_size *= nedsim->cell_size;
     XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc, x_origin, y_origin, x_size, y_size);
 
+    // ...then give it a border, if requested.
     set_color(nedsim, &color_list[nedsim->color_index].border);
     if (bord_top) {
-        XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc, x_origin, y_origin, x_size, nedsim->border_size);
+        XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc,
+                x_origin, y_origin, x_size, nedsim->border_size);
     }
     if (bord_bottom) {
-        XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc, x_origin, (y_origin + y_size - nedsim->border_size), x_size, nedsim->border_size);
+        XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc,
+                x_origin, (y_origin + y_size - nedsim->border_size), x_size, nedsim->border_size);
     }
     if (bord_left) {
-        XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc, x_origin, y_origin, nedsim->border_size, y_size);
+        XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc,
+                x_origin, y_origin, nedsim->border_size, y_size);
     }
     if (bord_right) {
-        XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc, (x_origin + x_size - nedsim->border_size), y_origin, nedsim->border_size, y_size);
+        XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc,
+                (x_origin + x_size - nedsim->border_size), y_origin, nedsim->border_size, y_size);
     }
 }
 
-// TODO: Explain
-// Arguments are in units of 'cells', not pixels.
-// Will leave foreground color changed.
-// Draws filled circle with upper left corner at x,y.
+// Draws filled circle in a square area with upper left corner at x,y.  When
+// specifying the location and size to draw, all values are in units of
+// 'cells'.  Also, be aware that this function alters the foreground color.
 static void
 draw_circular_area(struct NEDsim * nedsim, size_t x, size_t y, double diameter)
 {
@@ -333,7 +338,8 @@ draw_circular_area(struct NEDsim * nedsim, size_t x, size_t y, double diameter)
     XFillArc(nedsim->dpy, nedsim->panel, nedsim->gc, x, y, diameter, diameter, 0, 360*64);
 }
 
-// TODO: Explain
+// Draws the panel itself. Not the lights/labels/etc, but the flat sheet of
+// metal that is the front panel.
 static void
 draw_panel(struct NEDsim * nedsim)
 {
@@ -404,7 +410,7 @@ draw_panel(struct NEDsim * nedsim)
     );
 }
 
-// TODO: Explain
+// Draw the "NED" and "subgeniuskitty.com" logos on the front panel.
 static void
 draw_logo(struct NEDsim * nedsim)
 {
@@ -433,7 +439,7 @@ draw_logo(struct NEDsim * nedsim)
             ((LOGO_Y_OFFSET+LOGO_NAME_HEIGHT+LOGO_WEBSITE_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), "subgeniuskitty.com", 18);
 }
 
-// TODO: Explain
+// Draw the HALT indicator area on the front panel.
 static void
 draw_halt(struct NEDsim * nedsim)
 {
@@ -453,7 +459,9 @@ draw_halt(struct NEDsim * nedsim)
             ((HALT_Y_OFFSET+HALT_LIGHT_HEIGHT+HALT_LABEL_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), "HALT", 4);
 }
 
-// TODO: Explain
+// Draw the 32 lights corresponding to 'word' at coordinates ('x','y').
+// Note that this function ONLY draws the lights and is used each frame for
+// updating the panel. To draw the wordline area itself, use draw_wordline().
 static void
 draw_wordline_lights(struct NEDsim * nedsim, uint32_t word, int x, int y)
 {
@@ -467,7 +475,10 @@ draw_wordline_lights(struct NEDsim * nedsim, uint32_t word, int x, int y)
     }
 }
 
-// TODO: Explain
+// Draw a single 32-bit NED word line at coordinates ('x','y').
+// Note that this draws a wordline with value 0. To update with a specific
+// value, call draw_wordline_lights() after drawing the wordline area at least
+// once.
 static void
 draw_wordline(struct NEDsim * nedsim, int x, int y)
 {
@@ -487,7 +498,7 @@ draw_wordline(struct NEDsim * nedsim, int x, int y)
     draw_wordline_lights(nedsim, 0, x, y);
 }
 
-// TODO: Explain
+// Draw the Program Counter area (but don't populate it yet).
 static void
 draw_pc(struct NEDsim * nedsim)
 {
@@ -506,7 +517,7 @@ draw_pc(struct NEDsim * nedsim)
             ((PC_Y_OFFSET+PC_LABEL_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), "PC", 2);
 }
 
-// TODO: Explain
+// Draw the Stack Counter area (but don't populate it yet).
 static void
 draw_sc(struct NEDsim * nedsim)
 {
@@ -526,7 +537,7 @@ draw_sc(struct NEDsim * nedsim)
             ((SC_Y_OFFSET+SC_LABEL_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), "SC", 2);
 }
 
-// TODO: Explain
+// Draw areas for the two PSW flags, 'Z'ero and 'N'egative.
 static void
 draw_psw(struct NEDsim * nedsim)
 {
@@ -558,7 +569,7 @@ draw_psw(struct NEDsim * nedsim)
             ((PSW_Y_OFFSET+PSW_LABEL_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), "Z", 1);
 }
 
-// TODO: Explain
+// Draw the stack area (but don't populate it yet).
 static void
 draw_stack(struct NEDsim * nedsim)
 {
@@ -578,7 +589,7 @@ draw_stack(struct NEDsim * nedsim)
             ((STACK_Y_OFFSET+STACK_LABEL_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), "Stack Size:", 11);
 }
 
-// TODO: Explain
+// Draw the heap area (but don't populate it yet).
 static void
 draw_heap(struct NEDsim * nedsim)
 {
@@ -610,7 +621,9 @@ draw_heap(struct NEDsim * nedsim)
             ((HEAP_Y_OFFSET+HEAP_LABEL_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), address, strlen(address));
 }
 
-// TODO: Explain
+// After the static front panel has been drawn at least once, this function
+// updates all the dynamic parts of the panel (lights + text values) and is
+// called every frame.
 static void
 update_display(struct NEDsim * nedsim)
 {