Address comments re workload

Use a calibration factor that is only updated when the workload is >0.
Improve docs and comments.

apps/OboeTester/docs/AutomatedTesting.md

@@ -59,13 +59,14 @@ For example:
 
 There are two required parameters for all tests:
 
-    --es test {latency, glitch, data_paths, input, output}
+    --es test {latency, glitch, data_paths, input, output, cpu_load}
             The "latency" test will perform a Round Trip Latency test.
             It will request EXCLUSIVE mode for minimal latency.
             The "glitch" test will perform a single Glitch test.
             The "data_paths" test will verify input and output streams in many possible configurations.
             The "input" test will open and start an input stream.
             The "output" test will open and start an output stream.
+            The "cpu_load" test will run the CPU LOAD activity.
 
     --es file {name of resulting file}
 
@@ -125,12 +126,18 @@ These parameters were used with the "data_paths" test prior to v2.5.11.
 
     --ez use_input_devices  {"true", 1, "false", 0}  // Whether to test various input devices.
     --ez use_output_devices {"true", 1, "false", 0}  // Whether to test various output devices.
-    --ez use_all_output_channel_masks {"true", 1, "false", 0}  // Whether to test all output channel masks. Default is false
+    --ez use_all_output_channel_masks {"true", 1, "false", 0}  // Whether to test all output channel masks. Default is false.
 
 There are some optional parameters for just the "output" test:
 
     --es signal_type        {sine, sawtooth, freq_sweep, pitch_sweep, white_noise} // type of sound to play, default is sine
 
+There are some optional parameters for just the "cpu_load" test:
+
+    --ez use_adpf         {true, false} // if true, use work boost from performance hints. Default is false.
+    --ez use_workload     {true, false} // if true and using ADPF then report workload changes. Default is false.
+    --ez scroll_graphics  {true, false} // if true then continually update the power scope. Default is false.
+
 For example, a complete command for a "latency" test might be:
 
     adb shell am start -n com.mobileer.oboetester/.MainActivity \

include/oboe/AudioStream.h

@@ -543,14 +543,23 @@ class AudioStream : public AudioStreamBase {
     }
 
     /**
-     * If you have called setPerformanceHintEnabled(true) then you can give
-     * the performance manager more information about your workload.
+     * Use this to give the performance manager more information about your workload.
      * You can call this at the beginning of the callback when you figure
      * out what your workload will be.
      *
+     * Call this if (1) you have called setPerformanceHintEnabled(true), and
+     * (2) you have a varying workload, and
+     * (3) you hear glitches when your workload suddenly increases.
+     *
+     * This might happen when you go from a single note to a big chord on a synthesizer.
+     *
      * The workload can be in your own units. If you are synthesizing music
      * then the workload could be the number of active voices.
      * If your app is a game then it could be the number of sound effects.
+     * The units are arbitrary. They just have to be proportional to
+     * the estimated computational load. For example, if some of your voices take 20%
+     * more computation than a basic voice then assign 6 units to the complex voice
+     * and 5 units to the basic voice.
      *
      * The performance hint code can use this as an advance warning that the callback duration
      * will probably increase. Rather than wait for the long duration and possibly under-run,

src/common/AdpfWrapper.cpp

@@ -120,22 +120,22 @@ void AdpfWrapper::onEndCallback(double durationScaler) {
         int64_t actualDurationNanos = endCallbackNanos - mBeginCallbackNanos;
         int64_t scaledDurationNanos = static_cast<int64_t>(actualDurationNanos * durationScaler);
         reportActualDuration(scaledDurationNanos);
-        mPreviousDuration = scaledDurationNanos;
+        // When the workload is non-zero, update the conversion factor from workload
+        // units to nanoseconds duration.
+        if (mPreviousWorkload > 0) {
+            mNanosPerWorkloadUnit = ((double) scaledDurationNanos) / mPreviousWorkload;
+        }
     }
 }
 
 void AdpfWrapper::reportWorkload(int32_t appWorkload) {
     if (isOpen()) {
         // Compare with previous workload. If we think we will need more
-        // time to render the callback then warn ADPF as early as possible.
-        if (appWorkload > mPreviousWorkload
-                && mPreviousWorkload > 0
-                && mPreviousDuration > 0) {
-            int64_t predictedDuration = appWorkload * mPreviousDuration / mPreviousWorkload;
+        // time to render the callback then warn ADPF as soon as possible.
+        if (appWorkload > mPreviousWorkload && mNanosPerWorkloadUnit > 0.0) {
+            int64_t predictedDuration = (int64_t) (appWorkload * mNanosPerWorkloadUnit);
             reportActualDuration(predictedDuration);
-
         }
         mPreviousWorkload = appWorkload;
     }
-
 }

src/common/AdpfWrapper.h

@@ -83,7 +83,7 @@ class AdpfWrapper {
     int64_t                  mBeginCallbackNanos = 0;
     static bool              sUseAlternativeHack;
     int32_t                  mPreviousWorkload = 0;
-    int32_t                  mPreviousDuration = 0;
+    double                   mNanosPerWorkloadUnit = 0.0;
 };
 
 #endif //SYNTHMARK_ADPF_WRAPPER_H