DOCS: Added proper documentation to filters(.h, .c)

src/filters.c

@@ -1,10 +1,8 @@
-
-
-#include <stdlib.h>
-
-// #include "utils.h"
 #include "image/filters.h"
 
+#include <stdio.h>
+#include <stdlib.h>
+
 unsigned int
 u32_put_alpha(const unsigned int clr, const unsigned char alpha)
 {
@@ -30,6 +28,13 @@ u32_grayscale(const unsigned int clr)
 	unsigned int red = DECODE_R(clr);
 	unsigned int green = DECODE_G(clr);
 	unsigned int blue = DECODE_B(clr);
+	/*
+	 * WHY: The colors use the REC 601 Standard: Lamens terms they are
+	 * weighed in how the human eye percieves color. So green is the largest
+	 * because we are more sensitive to green and least to blue.
+	 * The Shift_8 is to divide 256 to bring the color value back into range
+	 of 0 - 255
+	 */
 	unsigned int gray =
 	    ((red * 77) + (green * 150) + (blue * 29)) >> SHIFT_8;
 
@@ -49,7 +54,6 @@ u32_step(const unsigned int clr, const unsigned char max)
 unsigned int
 u32_brighten(const unsigned int clr, const float factor)
 {
-	unsigned int alpha = (clr & BYTE_A);
 	unsigned int red = CLAMP_MAX(DECODE_R(clr) * factor);
 	unsigned int green = CLAMP_MAX(DECODE_G(clr) * factor);
 	unsigned int blue = CLAMP_MAX(DECODE_B(clr) * factor);
@@ -67,8 +71,14 @@ u32_mix(const unsigned int clr_a, const unsigned int clr_b)
 }
 
 unsigned int
-u32_lerp(const unsigned clr_a, const unsigned int clr_b, const float ratio)
+u32_lerp(const unsigned int clr_a, const unsigned int clr_b, const float ratio)
 {
+	/*
+	 * A more powerful mix using floating points to more precisely and
+	 * smoothly mix colors from 2 pixels. Doesn't really work on PPM images
+	 * because they are whole number pixels. So jpeg are better because the
+	 * numbers result in floating point colors.
+	 * */
 	unsigned char blue =
 	    ((DECODE_B(clr_a) * (1 - ratio)) + ((DECODE_B(clr_b) * ratio)));
 	unsigned char green =
@@ -104,11 +114,41 @@ u32_rotl(const unsigned int clr, const int n)
 {
 	if (n > 8)
 	{
-		return 0;
+		printf(
+		    "ERROR: %i is greater than 8 results in black "
+		    "pixels, please use values less than 8\n",
+		    n);
+		exit(10);
 	}
 	unsigned int red = DECODE_R(clr);
 	unsigned int green = DECODE_G(clr);
 	unsigned int blue = DECODE_B(clr);
+	/*
+	 * Rotates the color channels. Essentially it moves bits left a certain
+	 * n and then wraps if it leaves the left to the right.
+	 *
+	 * If you input 1 to n and have:
+	 * 0 0 0 0 0 0 0 1 # 1
+	 *
+	 * You will get:
+	 * 0 0 0 0 0 0 1 0 # 2
+	 *
+	 * But this gets complex with larger numbers:
+	 * 0 1 0 1 1 1 0 0 # 4 + 8 + 16 + 64 = 92
+	 *
+	 * Rotating by 2 will wrap and give:
+	 * 0 1 1 1 0 0 0 1 # 1 + 16 + 32 + 64 = 113
+	 *
+	 * This creates a pixelated looking image of random colors while still
+	 * holding the original image's structure under. Almost a distored,
+	 * broken tv look.
+	 *
+	 * N has a max of 8 because any number after 8 results in the bits
+	 * shifting negatively due to the wrapping math, which cant happen and
+	 * just makes the pixels black. If the number is 8 it just results in
+	 * the pixels being the same as they are just rotated back to their
+	 * original spot.
+	 * */
 	red = ((red << n) | (red >> (SHIFT_8 - n))) & BYTE;
 	green = ((green << n) | (green >> (SHIFT_8 - n))) & BYTE;
 	blue = ((blue << n) | (blue >> (SHIFT_8 - n))) & BYTE;
@@ -136,6 +176,19 @@ u32_avg_gb(const unsigned int clr)
 	return ENCODE_RGB(red, green, blue);
 }
 
+/**
+ * @brief Blurs column at (x,y) using -radius to radius
+ * @details Starts at the top extreme and moves to the bottom extreme,
+ * taking the pixel and adding each channel. Because each channel is separated
+ * into their own ints, it adds each int together and at the end divides each
+ * channel back below 256 and converts back to one int.
+ * @param[in] src Pointer to buffer image.
+ * @param[in] x Location in the image buffer for column of original pixel
+ * @param[in] y Location in the image buffer for row of original pixel
+ * @param[in] img Pointer to PPM container
+ * @param[in] radius The value to find -extreme and +extreme to add to pixel
+ * @return unsigned int Packed color with new alpha channel.
+ */
 unsigned int
 blur_col(const unsigned int* src, const int x, const int y, const PPM* img,
 	 const int radius)
@@ -152,13 +205,30 @@ blur_col(const unsigned int* src, const int x, const int y, const PPM* img,
 		}
 	}
 
+	// WHY: takes the count (cnt) of pixels from column and divides the
+	// point (pt) by (cnt) to get back below 256 and then converted back
+	// into an int from a long
 	if (cnt > 0)
 	{
 		return u64to_u32(pt, cnt);
 	}
+
 	return src[y * img->width + x];
 }
 
+/**
+ * @brief Blurs column at (x,y) using -radius to radius
+ * @details Starts at the left extreme and moves to the right extreme taking the
+ * pixel and adding each channel. Because each channel is separated into their
+ * own ints, it adds each int together and at the end divides each channel back
+ * below 256 and converts back to one int.
+ * @param[in] src Pointer to buffer image.
+ * @param[in] x Location in the image buffer for column of original pixel
+ * @param[in] y Location in the image buffer for row of original pixel
+ * @param[in] img Pointer to PPM container
+ * @param[in] radius The value to find -extreme and +extreme to add to pixel
+ * @return unsigned int Packed color with new alpha channel.
+ */
 unsigned int
 blur_row(const unsigned int* src, const int x, const int y, const PPM* img,
 	 const int radius)
@@ -175,6 +245,9 @@ blur_row(const unsigned int* src, const int x, const int y, const PPM* img,
 		}
 	}
 
+	// WHY: takes the count (cnt) of pixels from row and divides the
+	// point (pt) by (cnt) to get back below 256 and then converted back
+	// into an int from a long
 	if (cnt > 0)
 	{
 		return u64to_u32(pt, cnt);