From c1906215ba455113fc7c24ad3d89f21b76782b62 Mon Sep 17 00:00:00 2001
From: Andrew Meadows <andrew@highfidelity.io>
Date: Wed, 20 Dec 2017 11:36:51 -0800
Subject: [PATCH] add comments

---
 interface/src/LODManager.cpp | 28 +++++++++++++++++++++-------
 interface/src/LODManager.h   |  2 +-
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/interface/src/LODManager.cpp b/interface/src/LODManager.cpp
index 714cc31f13..9e6fabd439 100644
--- a/interface/src/LODManager.cpp
+++ b/interface/src/LODManager.cpp
@@ -19,10 +19,6 @@
 
 #include "LODManager.h"
 
-const uint64_t LOD_AUTO_ADJUST_PERIOD = 500 * USECS_PER_MSEC;
-const float LOD_AUTO_ADJUST_DECREMENT_FACTOR = 0.8f;
-const float LOD_AUTO_ADJUST_INCREMENT_FACTOR = 1.2f;
-
 
 Setting::Handle<float> desktopLODDecreaseFPS("desktopLODDecreaseFPS", DEFAULT_DESKTOP_LOD_DOWN_FPS);
 Setting::Handle<float> hmdLODDecreaseFPS("hmdLODDecreaseFPS", DEFAULT_HMD_LOD_DOWN_FPS);
@@ -44,10 +40,28 @@ float LODManager::getLODIncreaseFPS() {
     return getDesktopLODIncreaseFPS();
 }
 
-void LODManager::autoAdjustLOD(float renderTime, float deltaTimeSec) {
+// We use a "time-weighted running average" of the renderTime and compare it against min/max thresholds
+// to determine if we should adjust the level of detail (LOD).
+//
+// A time-weighted running average has a timescale which determines how fast the average tracks the measured
+// value in real-time.  Given a step-function in the mesured value, and assuming measurements happen
+// faster than the runningAverage is computed, the error between the value and its runningAverage will be
+// reduced by 1/e every timescale of real-time that passes.
+const float LOD_ADJUST_RUNNING_AVG_TIMESCALE = 0.1f; // sec
+//
+// Assuming the measured value is affected by logic invoked by the runningAverage bumping up against its
+// thresholds, we expect the adjustment to introduce a step-function.  We want the runningAverage settle
+// to the new value BEFORE we test it aginst its thresholds again.  Hence we test on a period that is a few
+// multiples of the running average timescale:
+const uint64_t LOD_AUTO_ADJUST_PERIOD = 5 * (uint64_t)(LOD_ADJUST_RUNNING_AVG_TIMESCALE * (float)USECS_PER_MSEC); // usec
+
+const float LOD_AUTO_ADJUST_DECREMENT_FACTOR = 0.8f;
+const float LOD_AUTO_ADJUST_INCREMENT_FACTOR = 1.2f;
+
+void LODManager::autoAdjustLOD(float renderTime, float realTimeDelta) {
     // compute time-weighted running average renderTime
-    const float LOD_ADJUST_TIMESCALE = 0.1f; // sec
-    float blend = (deltaTimeSec < LOD_ADJUST_TIMESCALE) ? deltaTimeSec / LOD_ADJUST_TIMESCALE : 1.0f;
+    // Note: we MUST clamp the blend to 1.0 for stability
+    float blend = (realTimeDelta < LOD_ADJUST_RUNNING_AVG_TIMESCALE) ? realTimeDelta / LOD_ADJUST_RUNNING_AVG_TIMESCALE : 1.0f;
     _avgRenderTime = (1.0f - blend) * _avgRenderTime + blend * renderTime; // msec
     if (!_automaticLODAdjust) {
         // early exit
diff --git a/interface/src/LODManager.h b/interface/src/LODManager.h
index 374f6a2e73..cf38342db0 100644
--- a/interface/src/LODManager.h
+++ b/interface/src/LODManager.h
@@ -62,7 +62,7 @@ public:
     Q_INVOKABLE float getLODIncreaseFPS();
     
     static bool shouldRender(const RenderArgs* args, const AABox& bounds);
-    void autoAdjustLOD(float renderTime, float deltaTimeSec);
+    void autoAdjustLOD(float renderTime, float realTimeDelta);
     
     void loadSettings();
     void saveSettings();