strafehud: add some more documentation to the code

diff --git a/qcsrc/client/hud/panel/strafehud/draw.qc b/qcsrc/client/hud/panel/strafehud/draw.qc
index 5cc9191042773b1e9257883b320c996d88fd21d8..526677cd7d18ee579708e4868f3fdf6ce78d5cac 100644 (file)
--- a/qcsrc/client/hud/panel/strafehud/draw.qc
+++ b/qcsrc/client/hud/panel/strafehud/draw.qc
@@ -2,7 +2,9 @@
 
 #include <client/draw.qh>
 
-// functions to make hud elements align perfectly in the hud area
+// draw the strafe-o-meter bar
+// aligns HUD elements perfectly in the hud area
+// also deals with wrapping around on edges, different HUD styles, etc
 void StrafeHUD_DrawStrafeHUD(float startangle, float offsetangle, vector color, float alpha, int type, int gradientType, bool projectWidth, float range)
 {
        float offset = StrafeHUD_AngleToOffset(startangle % 360, range);

diff --git a/qcsrc/client/hud/panel/strafehud/extra.qc b/qcsrc/client/hud/panel/strafehud/extra.qc
index 7651e7157a443a175effb617f8cabc9b23e4b422..99283ed6be52cb4e067f46105fcc7e099b6b4c20 100644 (file)
--- a/qcsrc/client/hud/panel/strafehud/extra.qc
+++ b/qcsrc/client/hud/panel/strafehud/extra.qc
@@ -18,6 +18,8 @@
 #define SLICKDETECT_STEPS_EPSILON 0.00001
 
 // slick detector
+// scans for slick in every direction downwards from the player's feet
+// may cause performance issues on slower machines
 float StrafeHUD_DrawSlickDetector(entity e, bool onslick)
 {
        float slickdetector_height = bound(0, autocvar_hud_panel_strafehud_slickdetector_height, 1);
@@ -121,7 +123,7 @@ float StrafeHUD_DrawVerticalAngle(entity e, float text_offset_bottom)
        return 0;
 }
 
-// strafe sonar
+// strafe sonar for audible feedback when strafing
 void StrafeHUD_Sonar(float strafe_ratio, string sonarsound)
 {
        static float sonar_time = 0;
@@ -151,6 +153,7 @@ void StrafeHUD_Sonar(float strafe_ratio, string sonarsound)
        }
 }
 
+// update and precache the sonar sound and store the proper sound path
 string StrafeHUD_UpdateSonarSound()
 {
        string newsound = autocvar_hud_panel_strafehud_sonar_audio;
@@ -228,7 +231,8 @@ float StrafeHUD_DrawJumpHeight(entity e, bool onground, bool swimming, float tex
        return 0;
 }
 
-// strafe efficiency
+// strafe efficiency, percentage of how far away the current angle is from the optimal angle
+// the percentage changes linearly with angular distance
 float StrafeHUD_DrawStrafeEfficiency(float strafe_ratio, float text_offset_top)
 {
        {

diff --git a/qcsrc/client/hud/panel/strafehud/util.qc b/qcsrc/client/hud/panel/strafehud/util.qc
index c02e18516ce1f85b84e2ee822cef1503aec26765..efd9d7b5bb3538bfeab68c4ccad210e3731b7827 100644 (file)
--- a/qcsrc/client/hud/panel/strafehud/util.qc
+++ b/qcsrc/client/hud/panel/strafehud/util.qc
@@ -4,16 +4,19 @@
 #include <common/physics/player.qh>
 #include <common/physics/movetypes/movetypes.qh>
 
+// convert a strafe angle into a HUD width value
 float StrafeHUD_AngleToWidth(float angle, float range)
 {
        return angle / range * panel_size.x;
 }
 
+// convert a strafe angle into a centered HUD offset value
 float StrafeHUD_AngleToOffset(float angle, float range)
 {
        return StrafeHUD_AngleToWidth(angle, range) + panel_size.x / 2;
 }
 
+// turn a ratio into a projected ratio based on the total angular distance
 float StrafeHUD_Project(float ratio, float range, bool reverse)
 {
        range *= DEG2RAD / 2;
@@ -50,6 +53,7 @@ float StrafeHUD_Project(float ratio, float range, bool reverse)
        return ratio;
 }
 
+// project a centered HUD offset value
 float StrafeHUD_ProjectOffset(float offset, float range, bool reverse)
 {
        if(autocvar_hud_panel_strafehud_projection == STRAFEHUD_PROJECTION_LINEAR)
@@ -61,6 +65,7 @@ float StrafeHUD_ProjectOffset(float offset, float range, bool reverse)
        return offset;
 }
 
+// project a HUD width value
 float StrafeHUD_ProjectWidth(float offset, float width, float range)
 {
        if(autocvar_hud_panel_strafehud_projection == STRAFEHUD_PROJECTION_LINEAR)
@@ -117,7 +122,7 @@ float StrafeHUD_DetermineWaterLevel(entity e)
        return new_waterlevel;
 }
 
-// determine frametime
+// determine frametime, to avoid jitter, average the frametime in case client prediction is used
 float StrafeHUD_DetermineFrameTime()
 {
        static float dt_update = 0;
@@ -132,8 +137,13 @@ float StrafeHUD_DetermineFrameTime()
                        dt_client /= 2; // does not ensure frames are smaller than 50 ms, just splits large frames in half, matches server behaviour
 
                // calculate average frametime
-               dt_sum += dt_client * dt_client;
-               dt_time += dt_client;
+               // calculated using a weighted arithmetic mean, where the weighting is equal to the frametime itself
+               // for example, given a 1 ms frame and a 9 ms frame we have:
+               //   a total time of 10 ms
+               //   a weighted sum of 1 ms * 1 ms + 9 ms * 9 ms = 82 ms^2
+               //   the final result is 82 ms^2 / 10 ms = 8.2 ms
+               dt_sum += dt_client * dt_client; // weighted sum of all frametimes (mean numerator)
+               dt_time += dt_client; // time spent averaging (mean denominator)
 
                if(((time - dt_update) > autocvar_hud_panel_strafehud_fps_update) || (dt_update == 0))
                {
@@ -151,7 +161,7 @@ float StrafeHUD_DetermineFrameTime()
        return dt;
 }
 
-// determine player wishdir
+// determine player wishdir, non-local player movement is limited to 45 degree steps
 float StrafeHUD_DetermineWishAngle(vector movement, int keys, bool islocal)
 {
        float wishangle;
@@ -247,6 +257,8 @@ float StrafeHUD_DetermineHudAngle(float absolute_wishangle, float absolute_overt
        // limit strafe-meter angle to values suitable for the current projection mode
        switch(autocvar_hud_panel_strafehud_projection)
        {
+               // those limits are a little less than the maximal FOV the game allows
+               // however, they suffice for all realistic use cases
                case STRAFEHUD_PROJECTION_PERSPECTIVE:
                        hudangle = min(hudangle, 170);
                        break;
@@ -280,7 +292,9 @@ float StrafeHUD_DetermineDirection(float angle, float wishangle, float antiflick
        }
 }
 
-// try to ignore if track_canjump is enabled, does not work in spectator mode if spectated player uses +jetpack or cl_movement_track_canjump
+// determine whether the player holds the jump key
+// try to ignore if track_canjump is enabled
+// does not work in spectator mode if the spectated player uses +jetpack or cl_movement_track_canjump
 bool StrafeHUD_DetermineJumpHeld(entity e, int keys, bool islocal)
 {
        if(islocal)
@@ -297,6 +311,7 @@ bool StrafeHUD_DetermineJumpHeld(entity e, int keys, bool islocal)
        return false;
 }
 
+// mix two colors based on a ratio
 vector StrafeHUD_MixColors(vector color1, vector color2, float ratio)
 {
        if(ratio <= 0) return color1;