From 61ae161ba8beb80d28d824584be81e76d8c7718e Mon Sep 17 00:00:00 2001
From: "Damon V. Caskey" <dc@caskeys.com>
Date: Mon, 19 Mar 2018 17:20:27 -0400
Subject: [PATCH] Readability improvements and added commenting to loadsprite2.

---
 engine/openbor.c | 49 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 39 insertions(+), 10 deletions(-)

diff --git a/engine/openbor.c b/engine/openbor.c
index 4c01180cd..346b24241 100644
--- a/engine/openbor.c
+++ b/engine/openbor.c
@@ -4641,36 +4641,65 @@ s_sprite *loadsprite2(char *filename, int *width, int *height)
     size_t size;
     s_bitmap *bitmap = NULL;
     s_sprite *sprite = NULL;
-    int clipl, clipr, clipt, clipb;
-
+    int clip_left;
+    int clip_right;
+    int clip_top;
+    int clip_bottom;
+
+    // Load raw bitmap (image) file from pack. If this
+    // fails, then we return NULL.
     bitmap = loadbitmap(filename, packfile, pixelformat);
+
     if(!bitmap)
     {
         return NULL;
-    }
+    }
+
+    // Apply width and height adjustments, if any.
     if(width)
     {
         *width = bitmap->width;
     }
+
     if(height)
     {
         *height = bitmap->height;
-    }
-    clipbitmap(bitmap, &clipl, &clipr, &clipt, &clipb);
-    size = fakey_encodesprite(bitmap);
+    }
+
+    // Trim empty pixels from the bitmap to save memory.
+    // We will pass the arguments by reference - they will
+    // be modified by the clipping function to tell us
+    // exactly how much trim work on each axis was done.
+    clipbitmap(bitmap, &clip_left, &clip_right, &clip_top, &clip_bottom);
+
+    // Get size of trimmed bitmap and allocate memory for
+    // use as a sprite. If this fails, then free the memory
+    // bitmap occupies, and return NULL.
+    size = fakey_encodesprite(bitmap);
     sprite = (s_sprite *)malloc(size);
+
     if(!sprite)
     {
         freebitmap(bitmap);
         return NULL;
     }
-    encodesprite(-clipl, -clipt, bitmap, sprite);
-    sprite->offsetx = clipl;
-    sprite->offsety = clipt;
+
+    // Transpose bitmap to a sprite, using the memory
+    // we allocated for it above. The trim arguments
+    // from our trimming function will be used as an
+    // offset. We'll also store/ the bitmap's trimmed
+    // dimensions for later use.
+    encodesprite(-clip_left, -clip_top, bitmap, sprite);
+    sprite->offsetx = clip_left;
+    sprite->offsety = clip_top;
     sprite->srcwidth = bitmap->width;
     sprite->srcheight = bitmap->height;
+
+    // Delete the raw bitmap, we don't need it
+    // any more.
     freebitmap(bitmap);
-
+
+    // Return encoded sprite.
     return sprite;
 }