From 9e55978ad8b8da90bb30407047b399e9c430c070 Mon Sep 17 00:00:00 2001
From: Jacob Palecki <JacobPalecki@gmail.com>
Date: Tue, 28 Jul 2020 14:54:31 -0700
Subject: More comments and light refactoring

---
 common/rawaccel.hpp | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 grapher/Form1.cs    |  4 ++--
 wrapper/wrapper.cpp |  2 +-
 wrapper/wrapper.hpp |  2 +-
 4 files changed, 61 insertions(+), 7 deletions(-)

diff --git a/common/rawaccel.hpp b/common/rawaccel.hpp
index 9d4b5e3..2b45c06 100644
--- a/common/rawaccel.hpp
+++ b/common/rawaccel.hpp
@@ -9,11 +9,20 @@
 
 namespace rawaccel {
 
+    /// <summary> Enum to hold acceleration implementation types (i.e. types of curves.) </summary>
     enum class mode { noaccel, linear, classic, natural, logarithmic, sigmoid, power };
 
+    /// <summary> Struct to hold vector rotation details. </summary>
     struct rotator {
+
+        /// <summary> Rotational vector, which points in the direction of the post-rotation positive y axis. </summary>
         vec2d rot_vec = { 1, 0 };
 
+        /// <summary>
+        /// Rotates given input vector according to struct's rotational vector.
+        /// </summary>
+        /// <param name="input">Input vector to be rotated</param>
+        /// <returns>2d vector of rotated input.</returns>
         inline vec2d operator()(const vec2d& input) const {
             return {
                 input.x * rot_vec.x - input.y * rot_vec.y,
@@ -29,10 +38,16 @@ namespace rawaccel {
         rotator() = default;
     };
 
+    /// <summary> Struct to hold clamp (min and max) details for acceleration application </summary>
     struct accel_scale_clamp {
         double lo = 0;
         double hi = 9;
 
+        /// <summary>
+        /// Clamps given input to min at lo, max at hi.
+        /// </summary>
+        /// <param name="scale">Double to be clamped</param>
+        /// <returns>Clamped input as double</returns>
         inline double operator()(double scale) const {
             return clampsd(scale, lo, hi);
         }
@@ -54,6 +69,7 @@ namespace rawaccel {
         accel_scale_clamp() = default;
     };
 
+// Error throwing calls std libraries which are unavailable in kernel mode.
 #ifdef _KERNEL_MODE
     void error(const char*) {}
 #else
@@ -62,6 +78,7 @@ namespace rawaccel {
 
     using milliseconds = double;
 
+    /// <summary> Struct to hold arguments for an acceleration function. </summary>
     struct args_t {
         mode accel_mode = mode::noaccel;
         milliseconds time_min = 0.4;
@@ -74,7 +91,7 @@ namespace rawaccel {
     };
 
     /// <summary>
-    /// Struct to hold acceleration implementation details.
+    /// Struct to hold acceleration curve implementation details.
     /// </summary>
     /// <typeparam name="T">Type of acceleration.</typeparam>
     template <typename T>
@@ -216,8 +233,8 @@ namespace rawaccel {
         { k++; }
 
         double accelerate(double speed) {
-            //f(x) = (mx)^k - 1
-            // The subtraction of 1 is with later addition of 1 in mind, 
+            // f(x) = (mx)^k - 1
+            // The subtraction of 1 occurs with later addition of 1 in mind, 
             // so that the input vector is directly multiplied by (mx)^k (if unweighted)
             return (offset > 0 && speed < 1) ? 0 : pow(speed * b, k) - 1;
         }
@@ -238,8 +255,10 @@ namespace rawaccel {
         void verify(args_t args) {}
     };
     
+    /// <summary> Tagged union to hold all accel implementations and allow "polymorphism" via a visitor call. </summary>
     using accel_implementation_t = tagged_union<accel_linear, accel_classic, accel_natural, accel_logarithmic, accel_sigmoid, accel_power, accel_noaccel>;
 
+    /// <summary> Struct for holding acceleration application details. </summary>
     struct accel_function {
 
         /*
@@ -247,14 +266,19 @@ namespace rawaccel {
         the user's mouse polling interval, though it should
         not matter if the system is stable.
         */
+        /// <summary> The minimum time period for one mouse movement. </summary>
         milliseconds time_min = 0.4;
 
         /// <summary> The offset past which acceleration is applied. </summary>
         double speed_offset = 0;
 
+        /// <summary> The acceleration implementation (i.e. curve) </summary>
         accel_implementation_t accel;
 
+        /// <summary> The weight of acceleration applied in {x, y} dimensions. </summary>
         vec2d weight = { 1, 1 };
+
+        /// <summary> The object which sets a min and max for the acceleration scale. </summary>
         vec2<accel_scale_clamp> clamp;
 
         accel_function(args_t args) {
@@ -273,6 +297,8 @@ namespace rawaccel {
 				case mode::power: accel = accel_power(args);
             }
 
+            // Verification is performed by the accel_implementation object
+            // and therefore must occur after the object has been instantiated
             verify(args);
 
             time_min = args.time_min;
@@ -282,14 +308,29 @@ namespace rawaccel {
             clamp.y = accel_scale_clamp(args.cap.y);
         }
 
+        /// <summary>
+        /// Applies mouse acceleration to a given speed, via visitor function to accel_implementation_t
+        /// </summary>
+        /// <param name="speed">Speed from which to determine acceleration</param>
+        /// <returns>Acceleration as a ratio magnitudes, as a double</returns>
         double apply(double speed) const {
             return accel.visit([=](auto accel_t) { return accel_t.accelerate(speed); });
         }
 
+        /// <summary>
+        /// Verifies acceleration arguments, via visitor function to accel_implementation_t
+        /// </summary>
+        /// <param name="args">Arguments to be verified</param>
         void verify(args_t args) const {
             return accel.visit([=](auto accel_t) { accel_t.verify(args); });
         }
 
+        /// <summary>
+        /// Applies weighted acceleration to given input for given time period.
+        /// </summary>
+        /// <param name="input">2d vector of {x, y} mouse movement to be accelerated</param>
+        /// <param name="time">Time period over which input movement was accumulated</param>
+        /// <returns></returns>
         inline vec2d operator()(const vec2d& input, milliseconds time) const {
             double mag = sqrtsd(input.x * input.x + input.y * input.y);
             double time_clamped = clampsd(time, time_min, 100);
@@ -309,6 +350,7 @@ namespace rawaccel {
         accel_function() = default;
     };
 
+    /// <summary> Struct to hold variables and methods for modifying mouse input </summary>
     struct mouse_modifier {
         bool apply_rotate = false;
         bool apply_accel = false;
@@ -330,6 +372,12 @@ namespace rawaccel {
             sensitivity = sens;
         }
 
+        /// <summary>
+        /// Applies modification without acceleration. Rotation is the only
+        /// modification currently implemented.
+        /// </summary>
+        /// <param name="input">Input to be modified.</param>
+        /// <returns>2d vector of modified input.</returns>
         inline vec2d modify(vec2d input)
         {
             if (apply_rotate)
@@ -340,6 +388,12 @@ namespace rawaccel {
             return input;
         }
 
+        /// <summary>
+        /// Applies modification, including acceleration.
+        /// </summary>
+        /// <param name="input">Input to be modified</param>
+        /// <param name="time">Time period for determining acceleration.</param>
+        /// <returns>2d vector with modified input.</returns>
         inline vec2d modify(vec2d input, milliseconds time)
         {
             return accel_fn(modify(input), time);
diff --git a/grapher/Form1.cs b/grapher/Form1.cs
index 1915b01..4165b0f 100644
--- a/grapher/Form1.cs
+++ b/grapher/Form1.cs
@@ -15,14 +15,14 @@ namespace grapher
         public RawAcceleration()
         {
             InitializeComponent();
-            var managedAccel = new ManagedAccel(6, 0, 1, 0.025, 0);
+            var managedAccel = new ManagedAccel(6, 0, 1.333, 0.05, 0);
             var orderedPoints = new SortedDictionary<double, double>();
 
             for (int i = 0; i < 100; i++)
             {
                 for (int j = 0; j <= i; j++)
                 {
-                    var output = managedAccel.Accelerate(i, j, 1, 6);
+                    var output = managedAccel.Accelerate(i, j, 1);
 
                     var inMagnitude = Magnitude(i,j);
                     var outMagnitude = Magnitude(output.Item1, output.Item2);
diff --git a/wrapper/wrapper.cpp b/wrapper/wrapper.cpp
index 2c004e4..1adafba 100644
--- a/wrapper/wrapper.cpp
+++ b/wrapper/wrapper.cpp
@@ -5,7 +5,7 @@
 using namespace rawaccel;
 using namespace System;
 
-Tuple<double, double>^ ManagedAccel::Accelerate(int x, int y, double time, double mode)
+Tuple<double, double>^ ManagedAccel::Accelerate(int x, int y, double time)
 {
 	vec2d input_vec2d = {x, y};
 	vec2d output = (*accel_instance)(input_vec2d, (milliseconds)time);
diff --git a/wrapper/wrapper.hpp b/wrapper/wrapper.hpp
index e9bbf2e..0307b4c 100644
--- a/wrapper/wrapper.hpp
+++ b/wrapper/wrapper.hpp
@@ -48,5 +48,5 @@ public:
         return accel_instance;
     }
 
-    Tuple<double, double>^ Accelerate(int x, int y, double time, double mode);
+    Tuple<double, double>^ Accelerate(int x, int y, double time);
 };
\ No newline at end of file
-- 
cgit v1.2.3