Minor cleanup of helper functions in NEDsim.

[screensavers] / hacks / NEDsim / NEDsim.c

diff --git a/hacks/NEDsim/NEDsim.c b/hacks/NEDsim/NEDsim.c
index 89a2090..c6c7c3d 100644 (file)
--- a/hacks/NEDsim/NEDsim.c
+++ b/hacks/NEDsim/NEDsim.c
@@ -4,6 +4,66 @@
 #include "screenhack.h"
 #include "simulator.h"
 
 #include "screenhack.h"
 #include "simulator.h"
 

+/* -------------------------------------------------------------------------- */
+/* Front Panel Layout                                                         */
+/* -------------------------------------------------------------------------- */
+
+// All of these values are in units of 'cells', not 'pixels'. Where applicable,
+// coordinates refer to the upper-left corner of a cell. See the files
+// `layout_reference.*` for details.
+
+#define OVERALL_WIDTH_IN_CELLS      70
+#define HEADER_HEIGHT_IN_CELLS      14
+#define FOOTER_HEIGHT_IN_CELLS      2
+
+#define LOGO_X_OFFSET               2
+#define LOGO_Y_OFFSET               2
+#define LOGO_WIDTH                  20
+#define LOGO_NAME_HEIGHT            6
+#define LOGO_WEBSITE_HEIGHT         2
+
+#define HALT_X_OFFSET               26
+#define HALT_Y_OFFSET               2
+#define HALT_WIDTH                  6
+#define HALT_LIGHT_HEIGHT           6
+#define HALT_LABEL_HEIGHT           2
+
+#define WORDLINE_BITS_PER_STRIPE    4
+#define WORDLINE_WIDTH              32
+#define WORDLINE_HEIGHT             1
+
+#define PC_X_OFFSET                 36
+#define PC_Y_OFFSET                 7
+#define PC_WIDTH                    32
+#define PC_LABEL_HEIGHT             2
+#define PC_LIGHT_HEIGHT             1
+
+#define SC_X_OFFSET                 42
+#define SC_Y_OFFSET                 2
+#define SC_WIDTH                    5
+#define SC_LABEL_HEIGHT             2
+#define SC_LIGHT_HEIGHT             1
+
+#define PSW_N_X_OFFSET              51
+#define PSW_Z_X_OFFSET              58
+#define PSW_Y_OFFSET                2
+#define PSW_LABEL_WIDTH             3
+#define PSW_LABEL_HEIGHT            2
+#define PSW_LIGHT_WIDTH             1
+#define PSW_LIGHT_HEIGHT            1
+
+#define STACK_X_OFFSET              2
+#define STACK_Y_OFFSET              12
+#define STACK_WIDTH                 32
+#define STACK_LABEL_HEIGHT          2
+#define STACK_LIGHT_HEIGHT          1
+
+#define HEAP_X_OFFSET               36
+#define HEAP_Y_OFFSET               12
+#define HEAP_WIDTH                  32
+#define HEAP_LABEL_HEIGHT           2
+#define HEAP_LIGHT_HEIGHT           1
+

 /* -------------------------------------------------------------------------- */
 /* Data Structures                                                            */
 /* -------------------------------------------------------------------------- */
 /* -------------------------------------------------------------------------- */
 /* Data Structures                                                            */
 /* -------------------------------------------------------------------------- */


@@ -126,7 +186,7 @@ static struct color_scheme color_list[] = {
 /* Helper Functions                                                           */
 /* -------------------------------------------------------------------------- */
 
 /* Helper Functions                                                           */
 /* -------------------------------------------------------------------------- */
 

-// TODO: Explain
+// Set foreground color for the current graphics context.

 static void
 set_color(struct NEDsim * nedsim, struct color_rgb * color)
 {
 static void
 set_color(struct NEDsim * nedsim, struct color_rgb * color)
 {


@@ -143,9 +203,8 @@ set_color(struct NEDsim * nedsim, struct color_rgb * color)
     XSetForeground(nedsim->dpy, nedsim->gc, temp.pixel);
 }
 
     XSetForeground(nedsim->dpy, nedsim->gc, temp.pixel);
 }
 

-// TODO: Explain

 // TODO: Make this a lot faster.
 // 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)
 {
 static void
 set_font_size(struct NEDsim * nedsim, int size)
 {


@@ -199,8 +258,9 @@ set_font_size(struct NEDsim * nedsim, int size)
     nedsim->current_font = font_full_name;
 }
 
     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)
 {
 static void
 get_text_size(struct NEDsim * nedsim, const char * text, int * x_size, int * y_size)
 {


@@ -212,13 +272,14 @@ get_text_size(struct NEDsim * nedsim, const char * text, int * x_size, int * y_s
     *y_size = overall.ascent - overall.descent;
 }
 
     *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)
 {
 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;
     x_origin *= nedsim->cell_size;
     x_origin += nedsim->origin_x_offset;
     y_origin *= nedsim->cell_size;


@@ -227,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);
 
     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) {
     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) {
     }
     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) {
     }
     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) {
     }
     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)
 {
 static void
 draw_circular_area(struct NEDsim * nedsim, size_t x, size_t y, double diameter)
 {


@@ -273,15 +338,11 @@ 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);
 }
 
     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)
 {
 static void
 draw_panel(struct NEDsim * nedsim)
 {

-// TODO: Collect all relevant #defines somewhere.
-#define OVERALL_WIDTH_IN_CELLS 70 
-#define HEADER_HEIGHT_IN_CELLS 14
-#define FOOTER_HEIGHT_IN_CELLS 2
-

     // Draw background color over entire window.
     set_color(nedsim, &color_list[nedsim->color_index].panel_bg);
     XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc, 0, 0, nedsim->dpy_width, nedsim->dpy_height);
     // Draw background color over entire window.
     set_color(nedsim, &color_list[nedsim->color_index].panel_bg);
     XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc, 0, 0, nedsim->dpy_width, nedsim->dpy_height);


@@ -349,16 +410,10 @@ 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)
 {
 static void
 draw_logo(struct NEDsim * nedsim)
 {

-#define LOGO_X_OFFSET       2
-#define LOGO_Y_OFFSET       2
-#define LOGO_WIDTH          20
-#define LOGO_NAME_HEIGHT    6
-#define LOGO_WEBSITE_HEIGHT 2
-

     // First draw the two colored boxes that comprise the logo area.
     set_color(nedsim, &color_list[nedsim->color_index].primary);
     draw_rect_area(nedsim, LOGO_X_OFFSET, LOGO_Y_OFFSET, LOGO_WIDTH, LOGO_NAME_HEIGHT, True, True, False, False);
     // First draw the two colored boxes that comprise the logo area.
     set_color(nedsim, &color_list[nedsim->color_index].primary);
     draw_rect_area(nedsim, LOGO_X_OFFSET, LOGO_Y_OFFSET, LOGO_WIDTH, LOGO_NAME_HEIGHT, True, True, False, False);


@@ -384,16 +439,10 @@ 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);
 }
 
             ((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)
 {
 static void
 draw_halt(struct NEDsim * nedsim)
 {

-#define HALT_X_OFFSET     26
-#define HALT_Y_OFFSET     2
-#define HALT_WIDTH        6
-#define HALT_LIGHT_HEIGHT 6
-#define HALT_LABEL_HEIGHT 2
-

     // First draw the two colored boxes that comprise the halt area.
     set_color(nedsim, &color_list[nedsim->color_index].tertiary);
     draw_rect_area(nedsim, HALT_X_OFFSET, HALT_Y_OFFSET, HALT_WIDTH, HALT_LIGHT_HEIGHT, True, True, False, False);
     // First draw the two colored boxes that comprise the halt area.
     set_color(nedsim, &color_list[nedsim->color_index].tertiary);
     draw_rect_area(nedsim, HALT_X_OFFSET, HALT_Y_OFFSET, HALT_WIDTH, HALT_LIGHT_HEIGHT, True, True, False, False);


@@ -410,14 +459,12 @@ 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);
 }
 
             ((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)
 {
 static void
 draw_wordline_lights(struct NEDsim * nedsim, uint32_t word, int x, int y)
 {

-#define WORDLINE_BITS_PER_STRIPE 4
-#define WORDLINE_WIDTH           32
-#define WORDLINE_HEIGHT          1
-

     for (int i = 0; i < WORDLINE_WIDTH; i++) {
         if (word & (1<<(WORDLINE_WIDTH-1-i))) {
             set_color(nedsim, &color_list[nedsim->color_index].light_on);
     for (int i = 0; i < WORDLINE_WIDTH; i++) {
         if (word & (1<<(WORDLINE_WIDTH-1-i))) {
             set_color(nedsim, &color_list[nedsim->color_index].light_on);


@@ -428,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)
 {
 static void
 draw_wordline(struct NEDsim * nedsim, int x, int y)
 {


@@ -448,17 +498,10 @@ draw_wordline(struct NEDsim * nedsim, int x, int y)
     draw_wordline_lights(nedsim, 0, x, 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)
 {
 static void
 draw_pc(struct NEDsim * nedsim)
 {

-// TODO: Note that all #defines use units of 'cells', not 'pixels', etc.
-#define PC_X_OFFSET     36
-#define PC_Y_OFFSET     7
-#define PC_WIDTH        32
-#define PC_LABEL_HEIGHT 2
-#define PC_LIGHT_HEIGHT 1
-

     // First draw the two colored boxes that comprise the PC area.
     set_color(nedsim, &color_list[nedsim->color_index].tertiary);
     draw_rect_area(nedsim, PC_X_OFFSET, PC_Y_OFFSET, PC_WIDTH, PC_LABEL_HEIGHT, True, True, False, False);
     // First draw the two colored boxes that comprise the PC area.
     set_color(nedsim, &color_list[nedsim->color_index].tertiary);
     draw_rect_area(nedsim, PC_X_OFFSET, PC_Y_OFFSET, PC_WIDTH, PC_LABEL_HEIGHT, True, True, False, False);


@@ -474,16 +517,10 @@ draw_pc(struct NEDsim * nedsim)
             ((PC_Y_OFFSET+PC_LABEL_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), "PC", 2);
 }
 
             ((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)
 {
 static void
 draw_sc(struct NEDsim * nedsim)
 {

-#define SC_X_OFFSET     42
-#define SC_Y_OFFSET     2
-#define SC_WIDTH        5
-#define SC_LABEL_HEIGHT 2
-#define SC_LIGHT_HEIGHT 1
-

     // First draw the two colored boxes that comprise the SC area.
     set_color(nedsim, &color_list[nedsim->color_index].secondary);
     draw_rect_area(nedsim, SC_X_OFFSET, SC_Y_OFFSET, SC_WIDTH, SC_LABEL_HEIGHT, True, True, False, False);
     // First draw the two colored boxes that comprise the SC area.
     set_color(nedsim, &color_list[nedsim->color_index].secondary);
     draw_rect_area(nedsim, SC_X_OFFSET, SC_Y_OFFSET, SC_WIDTH, SC_LABEL_HEIGHT, True, True, False, False);


@@ -500,18 +537,10 @@ draw_sc(struct NEDsim * nedsim)
             ((SC_Y_OFFSET+SC_LABEL_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), "SC", 2);
 }
 
             ((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)
 {
 static void
 draw_psw(struct NEDsim * nedsim)
 {

-#define PSW_N_X_OFFSET   51
-#define PSW_Z_X_OFFSET   58
-#define PSW_Y_OFFSET     2
-#define PSW_LABEL_WIDTH  3
-#define PSW_LABEL_HEIGHT 2
-#define PSW_LIGHT_WIDTH  1
-#define PSW_LIGHT_HEIGHT 1
-

     // First draw the four colored boxes that comprise the two PSW areas.
     set_color(nedsim, &color_list[nedsim->color_index].secondary);
     draw_rect_area(nedsim, PSW_N_X_OFFSET, PSW_Y_OFFSET, PSW_LABEL_WIDTH, PSW_LABEL_HEIGHT, True, True, False, False);
     // First draw the four colored boxes that comprise the two PSW areas.
     set_color(nedsim, &color_list[nedsim->color_index].secondary);
     draw_rect_area(nedsim, PSW_N_X_OFFSET, PSW_Y_OFFSET, PSW_LABEL_WIDTH, PSW_LABEL_HEIGHT, True, True, False, False);


@@ -540,16 +569,10 @@ draw_psw(struct NEDsim * nedsim)
             ((PSW_Y_OFFSET+PSW_LABEL_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), "Z", 1);
 }
 
             ((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)
 {
 static void
 draw_stack(struct NEDsim * nedsim)
 {

-#define STACK_X_OFFSET     2
-#define STACK_Y_OFFSET     12
-#define STACK_WIDTH        32
-#define STACK_LABEL_HEIGHT 2
-#define STACK_LIGHT_HEIGHT 1
-

     // First draw the two colored boxes that comprise the stack area.
     set_color(nedsim, &color_list[nedsim->color_index].tertiary);
     draw_rect_area(nedsim, STACK_X_OFFSET, STACK_Y_OFFSET, STACK_WIDTH, STACK_LABEL_HEIGHT, True, True, False, False);
     // First draw the two colored boxes that comprise the stack area.
     set_color(nedsim, &color_list[nedsim->color_index].tertiary);
     draw_rect_area(nedsim, STACK_X_OFFSET, STACK_Y_OFFSET, STACK_WIDTH, STACK_LABEL_HEIGHT, True, True, False, False);


@@ -566,15 +589,10 @@ draw_stack(struct NEDsim * nedsim)
             ((STACK_Y_OFFSET+STACK_LABEL_HEIGHT) * nedsim->cell_size + nedsim->origin_y_offset - local_y_offset), "Stack Size:", 11);
 }
 
             ((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)
 {
 static void
 draw_heap(struct NEDsim * nedsim)
 {

-#define HEAP_X_OFFSET     36
-#define HEAP_Y_OFFSET     12
-#define HEAP_WIDTH        32
-#define HEAP_LABEL_HEIGHT 2
-#define HEAP_LIGHT_HEIGHT 1

 // TODO: What should I do about this define? I would like to be able to specify the address so I can do things like display the code itself if nothign interesting happens in RAM.
 #define HEAP_START_ADDRESS 0x20000000
 
 // TODO: What should I do about this define? I would like to be able to specify the address so I can do things like display the code itself if nothign interesting happens in RAM.
 #define HEAP_START_ADDRESS 0x20000000
 


@@ -603,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));
 }
 
             ((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)
 {
 static void
 update_display(struct NEDsim * nedsim)
 {


@@ -705,9 +725,11 @@ NEDsim_free(Display * dpy, Window win, void * closure)
 static void *
 NEDsim_init(Display * dpy, Window win)
 {
 static void *
 NEDsim_init(Display * dpy, Window win)
 {

+    // =========================================================================
+    //  Basic Setup
+    // =========================================================================
+

     struct NEDsim * nedsim;
     struct NEDsim * nedsim;

-    XGCValues gcv;
-    XWindowAttributes xgwa;

 
     nedsim = calloc(1, sizeof(*nedsim));
     if (!nedsim) {
 
     nedsim = calloc(1, sizeof(*nedsim));
     if (!nedsim) {


@@ -718,16 +740,25 @@ NEDsim_init(Display * dpy, Window win)
     nedsim->dpy = dpy;
     nedsim->win = win;
 
     nedsim->dpy = dpy;
     nedsim->win = win;
 

+    XGCValues gcv;
+    nedsim->gc = XCreateGC(nedsim->dpy, nedsim->win, GCForeground, &gcv);
+
+    XWindowAttributes xgwa;

     XGetWindowAttributes(nedsim->dpy, nedsim->win, &xgwa);
     nedsim->dpy_width = xgwa.width;
     nedsim->dpy_height = xgwa.height;
 
     XGetWindowAttributes(nedsim->dpy, nedsim->win, &xgwa);
     nedsim->dpy_width = xgwa.width;
     nedsim->dpy_height = xgwa.height;
 

-    // TODO: Explain that this is the delay between each clock cycle of the simulated NED CPU.
+    nedsim->panel = XCreatePixmap(nedsim->dpy, nedsim->win, nedsim->dpy_width, nedsim->dpy_height, xgwa.depth);
+
+    // =========================================================================
+    //  Process User Requests
+    // =========================================================================
+

     nedsim->delay = get_integer_resource(nedsim->dpy, "delay", "Integer");
     nedsim->delay *= 1000; /* Turn milliseconds into microseconds. */
 
     nedsim->delay = get_integer_resource(nedsim->dpy, "delay", "Integer");
     nedsim->delay *= 1000; /* Turn milliseconds into microseconds. */
 

-    // Load the program file specified by the user or, if none is specified,
-    // randomly select one of the included programs.
+    // If the user did not supply a program for execution, randomly select one
+    // of the included programs.

     char * input_file = get_string_resource(nedsim->dpy, "binary", "String");
     if (input_file == NULL) {
         // TODO: Need to include some default programs and randomly select one to load into RAM.
     char * input_file = get_string_resource(nedsim->dpy, "binary", "String");
     if (input_file == NULL) {
         // TODO: Need to include some default programs and randomly select one to load into RAM.


@@ -736,11 +767,7 @@ NEDsim_init(Display * dpy, Window win)
         nedsim->nedstate = init_simulator(input_file);
     }
 
         nedsim->nedstate = init_simulator(input_file);
     }
 

-    nedsim->gc = XCreateGC(nedsim->dpy, nedsim->win, GCForeground, &gcv);
-    nedsim->panel = XCreatePixmap(nedsim->dpy, nedsim->win, nedsim->dpy_width, nedsim->dpy_height, xgwa.depth);
-
-    // If the user specified a color, use it. Otherwise, select at random from
-    // the available color schemes.
+    // If the user did not select a color scheme, select one randomly.

     nedsim->color_index = get_integer_resource(nedsim->dpy, "color", "Integer");
     if (nedsim->color_index == -1) {
         nedsim->color_index = random() % sizeof(color_list)/sizeof(color_list[0]);
     nedsim->color_index = get_integer_resource(nedsim->dpy, "color", "Integer");
     if (nedsim->color_index == -1) {
         nedsim->color_index = random() % sizeof(color_list)/sizeof(color_list[0]);


@@ -749,34 +776,50 @@ NEDsim_init(Display * dpy, Window win)
         nedsim->color_index = 0;
     }
 
         nedsim->color_index = 0;
     }
 

-// TODO: Save the GIMP reference diagram somewhere, along with notes about the size/spacing, and that each cell is 10 pixels across in the reference image.
+    // =========================================================================
+    //  Scale Panel To Screen
+    // =========================================================================

 
 

-    nedsim->cell_size = nedsim->dpy_width / OVERALL_WIDTH_IN_CELLS ; // make panel as wide as it can be while keeping every cell an integer pixel size.
-    // TODO: What is my minimum cell_size? Below that, I should simply paint the window red and print an error in the console. Perform that check here, right after setting cell_size.
-    //       For now, we'll just make it 10 pixels?
+    // We desire to make the panel as wide as possible while also making the
+    // cell size an integer pixel size.
+    nedsim->cell_size = nedsim->dpy_width / OVERALL_WIDTH_IN_CELLS;
+    // Cell sizes below about 10 pixels result in unreadable fonts. For now,
+    // we'll use that as our cutoff. It also works well with a 1:10 border:cell
+    // ratio.

     if (nedsim->cell_size < 10) {
         nedsim->suitable_display = False;
         return nedsim;
     }
     if (nedsim->cell_size < 10) {
         nedsim->suitable_display = False;
         return nedsim;
     }

-    nedsim->origin_x_offset = (nedsim->dpy_width - (nedsim->cell_size * OVERALL_WIDTH_IN_CELLS)) / 2; // center panel horizontally
-
-    // Determine how many rows for the stack and heap displays. Make it the largest power of two that fits on the display.
-    int available_space_for_data_rows = nedsim->dpy_height - (nedsim->cell_size * (HEADER_HEIGHT_IN_CELLS + FOOTER_HEIGHT_IN_CELLS));
+    // Center the panel horizontally.
+    nedsim->origin_x_offset = (nedsim->dpy_width -
+            (nedsim->cell_size * OVERALL_WIDTH_IN_CELLS)) / 2;
+
+    // The stack and heap displays are variable height. Size them to fit the
+    // display window.
+    int available_space_for_data_rows = nedsim->dpy_height -
+            (nedsim->cell_size * (HEADER_HEIGHT_IN_CELLS + FOOTER_HEIGHT_IN_CELLS));

     for (int i = 0; ; i++) {
         if ((nedsim->cell_size * (1 << i)) > available_space_for_data_rows) {
             nedsim->num_data_rows = (1 << --i);
             break;
         }
     }
     for (int i = 0; ; i++) {
         if ((nedsim->cell_size * (1 << i)) > available_space_for_data_rows) {
             nedsim->num_data_rows = (1 << --i);
             break;
         }
     }

+    // Enforce a minimum vertical size, though '4' is arbitrary.

     if (nedsim->num_data_rows < 4) {
         nedsim->suitable_display = False;
         return nedsim;
     }
     if (nedsim->num_data_rows < 4) {
         nedsim->suitable_display = False;
         return nedsim;
     }

-    nedsim->origin_y_offset = (nedsim->dpy_height - (nedsim->cell_size * (HEADER_HEIGHT_IN_CELLS + nedsim->num_data_rows + FOOTER_HEIGHT_IN_CELLS))) / 2; // center panel vertically
+    // Center the panel vertically.
+    nedsim->origin_y_offset = (nedsim->dpy_height -
+            (nedsim->cell_size * (HEADER_HEIGHT_IN_CELLS + nedsim->num_data_rows + FOOTER_HEIGHT_IN_CELLS))) / 2;

 
     // Scale border relative to cell_size in a 1:10 relationship.
     nedsim->border_size = nedsim->cell_size / 10;
 
 
     // Scale border relative to cell_size in a 1:10 relationship.
     nedsim->border_size = nedsim->cell_size / 10;
 

+    // =========================================================================
+    //  Draw Initial Panel
+    // =========================================================================
+

     draw_panel(nedsim);
     draw_logo(nedsim);
     draw_halt(nedsim);
     draw_panel(nedsim);
     draw_logo(nedsim);
     draw_halt(nedsim);


@@ -796,6 +839,7 @@ NEDsim_draw(Display * dpy, Window win, void * closure)
 {
     struct NEDsim * nedsim = closure;
 
 {
     struct NEDsim * nedsim = closure;
 

+    // Update the panel display buffer.

     if (nedsim->suitable_display) {
         nedsim->nedstate = run_simulator(nedsim->nedstate);
         update_display(nedsim);
     if (nedsim->suitable_display) {
         nedsim->nedstate = run_simulator(nedsim->nedstate);
         update_display(nedsim);


@@ -804,6 +848,7 @@ NEDsim_draw(Display * dpy, Window win, void * closure)
         XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc, 0, 0, nedsim->dpy_width, nedsim->dpy_height);
     }
 
         XFillRectangle(nedsim->dpy, nedsim->panel, nedsim->gc, 0, 0, nedsim->dpy_width, nedsim->dpy_height);
     }
 

+    // Copy panel buffer to display window.

     XCopyArea(nedsim->dpy, nedsim->panel, nedsim->win, nedsim->gc, 0, 0, nedsim->dpy_width, nedsim->dpy_height, 0, 0);
 
     return nedsim->delay;
     XCopyArea(nedsim->dpy, nedsim->panel, nedsim->win, nedsim->gc, 0, 0, nedsim->dpy_width, nedsim->dpy_height, 0, 0);
 
     return nedsim->delay;


@@ -813,10 +858,13 @@ static void
 NEDsim_reshape(Display * dpy, Window win, void * closure, unsigned int w, unsigned int h)
 {
     struct NEDsim * nedsim = closure;
 NEDsim_reshape(Display * dpy, Window win, void * closure, unsigned int w, unsigned int h)
 {
     struct NEDsim * nedsim = closure;

+
+    // Only re-initialize the display if it changed size.

     XWindowAttributes xgwa;
     XGetWindowAttributes(nedsim->dpy, nedsim->win, &xgwa);
     XWindowAttributes xgwa;
     XGetWindowAttributes(nedsim->dpy, nedsim->win, &xgwa);

-    /* Only restart the simulation if the window changed size.                */

     if (nedsim->dpy_width != xgwa.width || nedsim->dpy_height != xgwa.height) {
     if (nedsim->dpy_width != xgwa.width || nedsim->dpy_height != xgwa.height) {

+        // Although we are re-initializing the display, we wish to retain the
+        // in-progress NED simulation. Thus, we retain the NEDstate pointer.

         struct NEDstate * original_nedstate = nedsim->nedstate;
         nedsim->nedstate = NULL;
         NEDsim_free(dpy, win, nedsim);
         struct NEDstate * original_nedstate = nedsim->nedstate;
         nedsim->nedstate = NULL;
         NEDsim_free(dpy, win, nedsim);