Add progress update rate flag

Author: j-miet

PixelRay/Output/Progress/ProgressReporter.cs

@@ -3,18 +3,24 @@ namespace PixelRay.Output.Progress;
 /// <summary>
 /// Handles rendering progress updates via a callback function
 /// </summary>
-public class ProgressReporter(int frame, int total, Action<RenderProgress> callback)
+/// <param name="updateRate">How many pixels to read before sending progress update. Default is 500, internal lower
+/// bound is 100: values below this and probably even a bit above it will cause a lot of flickering in progress 
+/// prints. If updateRate >= total, progress will only update once from 0% to 100%
+/// Any value < 100 will default to 500 except 0 which sets updateRate = total
+/// </param>
+public class ProgressReporter(int frame, int total, Action<RenderProgress> callback, int updateRate = 500)
 {
     private int _done;
     private readonly int _total = total;
+    private readonly int _updateRate = updateRate == 0 ? total : updateRate >= 100 ? updateRate : 500;
     private readonly Action<RenderProgress> _callback = callback;
 
     public void Increment(int step = 1)
     {
         int done = Interlocked.Add(ref _done, step);
 
         // throttle updates (important for console performance)
-        if (done % 500 == 0 || done == _total)
+        if (done % _updateRate == 0 || done == _total)
         {
             _callback(new RenderProgress(
                 frame,

PixelRay/Program.cs

@@ -19,6 +19,7 @@ public static void Main(string[] args)
         values.Add("produceGif", "");
         values.Add("preview", "");
         values.Add("debug", "");
+        values.Add("progressUpdateRate", "");
 
         // parse CLI args and update config dictionary values
         try
@@ -160,6 +161,22 @@ public static void Main(string[] args)
                     }
                     break;
 
+                case "-u" or "--updaterate":
+                    try
+                    {
+                        if (args[i + 1] is not null)
+                        {
+                            values["progressUpdateRate"] = args[i + 1];
+                            i++;
+                        }
+                    }
+                    catch (IndexOutOfRangeException)
+                    {
+                        Console.WriteLine("Usage: -u <updateRateInPixels>");
+                        return;
+                    }
+                    break;
+
                 default:
                     Console.WriteLine($"Unsupported arg: {val}");
                     return;
@@ -203,6 +220,14 @@ public static void Main(string[] args)
         };
 
         FrameBuffer buffer;
+        int progressUpdateRate = 500;
+
+        // update bar progress rate: how many pixels to read between update prints
+        if (values["progressUpdateRate"] != "")
+        {
+            if (int.TryParse(values["progressUpdateRate"], out int updateRate))
+                progressUpdateRate = updateRate;
+        }
 
         // Lua script animations
         if (values["script"] != "")
@@ -250,7 +275,8 @@ public static void Main(string[] args)
             {
                 lua.Update(frame);
 
-                buffer = renderer.Render(scene, scene.Camera, settings.Threading, upScaleFactor, debug, frame);
+                buffer = renderer.Render(scene, scene.Camera, settings.Threading, upScaleFactor, debug, frame,
+                                         progressUpdateRate);
 
                 ImageWriter.WritePNG($"{frameOutputDir}{Path.DirectorySeparatorChar}frame-{frame}.png", buffer);
             }
@@ -262,7 +288,8 @@ public static void Main(string[] args)
             return;
         }
 
-        buffer = renderer.Render(scene, scene.Camera, settings.Threading, upScaleFactor, debug);
+        buffer = renderer.Render(scene, scene.Camera, settings.Threading, upScaleFactor, debug,
+                                 updateRate: progressUpdateRate);
 
         string outputPath = values["output"];
         string imageFormat = values["outputFormat"];

PixelRay/Rendering/Renderer.cs

@@ -38,17 +38,21 @@ public class Renderer(
     /// <summary>
     /// Render a scene through camera and return pixel buffer of rendered image.
     /// </summary>
+    /// <param name="threading">Toggle multithreading</param>
     /// <param name="upScale">Image upscaling factor using nearest-neighbor scaling</param>
     /// <param name="mode">What debug mode is used. Pass value as any DebugMode enum, which are: <br/>
     /// None, Normals, DepthHeat, ObjectId 
     /// </param>
+    /// <param name="frame">Current frame. Should only pass value >= 0 when creating a script animation</param>
+    /// <param name="updateRate">Amount of pixels to render before sending progress updates. Default is 500</param>
     public FrameBuffer Render(
         Scene scene,
         Camera camera,
         bool threading = true,
         int upScale = 1,
         DebugMode mode = DebugMode.None,
-        int frame = -1
+        int frame = -1,
+        int updateRate = 500
     )
     {
         int scaledW = upScale * _width;
@@ -61,7 +65,8 @@ public FrameBuffer Render(
         var reporter = new ProgressReporter(
             frame,
             _width * _height,
-            consoleBar.Update
+            consoleBar.Update,
+            updateRate
         );
 
         for (int y = 0; y < _height; y++)

README.md

@@ -107,6 +107,13 @@ Both the frame directory and output gif are created inside `<scripFilePath>` pat
     - both the output frames and produced gif are created inside the script location e.g. 
     `<luaScriptPath>/frames/` and `<luaScriptPath>/outputGif.gif`
 
+- `-u <updateRate>` or `--updaterate <updateRate>`
+
+    Changes progress bar update interval: how many pixels to render (from base resolution) before sending update print.
+    - default value is 500
+    - updateRate < 100 defaults to 500 (except 0): terminal can start to flickers with too fast updates. Even values above 100 will likely cause issues so adjust this accordingly.
+    - 0 is a special value: it sets updateRate=base_width*base_height, meaning there will only be a single update from 0% to 100%
+
 - `--debug <mode>`
 
     Renders image based on selected debug mode. These are: