Add progressive SDL2 rendering with real-time quality improvements

pmudry · pmudry · commit cd710bbbf01d · 2025-11-04T23:30:42.000+01:00
- Implement renderPixelsSDLProgressive() method in camera.h
- Display rendering progress through sample stages: 1, 4, 16, 64, 256, 1024
- Add interactive SDL window with live image updates
- Support ESC key and window close to stop at current quality
- Add rendering method option 3 for progressive display
- Include SDL2 headers conditionally when available
- Add comprehensive documentation in PROGRESSIVE_SDL_RENDERING.md
- Feature allows quick preview and interactive quality control
diff --git a/explanations/PROGRESSIVE_SDL_RENDERING.md b/explanations/PROGRESSIVE_SDL_RENDERING.md
@@ -0,0 +1,188 @@
+# Progressive SDL Rendering Feature
+
+## Overview
+
+This branch adds an interactive SDL2-based progressive rendering mode to the raytracer. This feature allows you to see your render in real-time as it progressively improves in quality through multiple sample stages.
+
+## What is Progressive Rendering?
+
+Progressive rendering displays the image while it's being rendered, starting with low quality (few samples per pixel) and gradually increasing quality. This allows you to:
+
+- **Preview quickly**: See your scene in seconds with low sample counts
+- **Stop early**: If the preview looks wrong, you can stop and adjust parameters
+- **Watch progress**: See the image quality improve in real-time
+- **Interactive experience**: Get visual feedback during the rendering process
+
+## Features
+
+### Sample Stages
+
+The progressive rendering goes through multiple quality stages:
+- **Stage 1**: 1 sample per pixel (very fast, noisy preview)
+- **Stage 2**: 4 samples per pixel (quick preview with less noise)
+- **Stage 3**: 16 samples per pixel (decent quality)
+- **Stage 4**: 64 samples per pixel (good quality)
+- **Stage 5**: 256 samples per pixel (high quality)
+- **Stage 6**: 1024 samples per pixel (final quality)
+
+Each stage is displayed immediately in the SDL window, so you can see the quality progression.
+
+### Interactive Controls
+
+- **ESC key**: Stop rendering at the current quality level
+- **Close window**: Stop rendering at the current quality level
+- **Wait**: Let it complete all stages for the highest quality
+- **After completion**: Press any key or close window to save and continue
+
+## How to Use
+
+### Prerequisites
+
+Make sure SDL2 is installed on your system:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install libsdl2-dev
+
+# macOS
+brew install sdl2
+
+# Windows
+# Download from https://www.libsdl.org/download-2.0.php
+```
+
+### Building
+
+The feature is automatically compiled if SDL2 is detected:
+
+```bash
+cd build
+cmake .. --fresh
+make -j12
+```
+
+If SDL2 is found, you'll see:
+```
+-- SDL2 found and linked for real-time display
+```
+
+### Running
+
+When you run the raytracer, you'll see a new rendering option:
+
+```bash
+./302_raytracer -r 1080 -s 1024
+```
+
+The menu will show:
+```
+Choose rendering method:
+	0. CPU sequential
+	1. CPU parallel
+	2. CUDA GPU (default)
+	3. CUDA GPU with progressive SDL display
+Enter choice (0, 1, 2, or 3): 
+```
+
+Select option **3** for progressive SDL rendering.
+
+### Example Usage
+
+```bash
+# Progressive render at 1080p
+echo 3 | ./302_raytracer -r 1080
+
+# Progressive render at 4K
+echo 3 | ./302_raytracer -r 2160
+
+# Progressive render at 720p with custom samples
+echo 3 | ./302_raytracer -r 720 -s 512
+```
+
+## Technical Details
+
+### Implementation
+
+The progressive rendering feature is implemented in `camera.h`:
+- **Method**: `renderPixelsSDLProgressive()`
+- **Conditional compilation**: Only available when `SDL2_FOUND` is defined
+- **Backend**: Uses CUDA for each rendering stage (fast GPU rendering)
+- **Display**: Updates SDL texture after each stage completion
+
+### Rendering Flow
+
+1. Initialize SDL window, renderer, and texture
+2. For each sample stage:
+   - Render with CUDA at current sample count
+   - Update SDL texture with the new image data
+   - Display in the window
+   - Check for user interruption (ESC or window close)
+3. Wait for user to acknowledge completion
+4. Clean up SDL resources
+5. Return final image for saving
+
+### Customization
+
+You can customize the sample stages in `main.cc`:
+
+```cpp
+// Default stages
+c.renderPixelsSDLProgressive(localImage, {1, 4, 16, 64, 256, 1024});
+
+// Custom stages - more granular
+c.renderPixelsSDLProgressive(localImage, {1, 2, 4, 8, 16, 32, 64, 128, 256});
+
+// Quick preview stages
+c.renderPixelsSDLProgressive(localImage, {1, 4, 16});
+```
+
+## Performance Considerations
+
+- **GPU Required**: Uses CUDA for rendering each stage, so a CUDA-capable GPU is required
+- **Memory**: Keeps one full-resolution image buffer per stage
+- **Display overhead**: Minimal - SDL texture updates are fast
+- **Total time**: Roughly equivalent to rendering with the highest sample count directly
+
+## Benefits Over Standard Rendering
+
+1. **Immediate feedback**: See your scene within seconds
+2. **Error detection**: Catch scene setup mistakes early
+3. **Quality control**: Stop when quality is sufficient for your needs
+4. **Visual satisfaction**: Watch the rendering improve in real-time
+5. **Flexibility**: Adjust quality vs. speed tradeoff interactively
+
+## Troubleshooting
+
+### SDL2 Not Found
+
+If option 3 doesn't appear:
+- SDL2 is not installed or not found by CMake
+- Reinstall SDL2 and run `cmake .. --fresh` in the build directory
+
+### Window Doesn't Appear
+
+- Check that you're not in a headless environment
+- Verify SDL2 is properly linked: `ldd ./302_raytracer | grep SDL`
+
+### Slow Performance
+
+- Progressive rendering uses CUDA, ensure your GPU drivers are up to date
+- Each stage requires a complete render at that sample count
+- For slower GPUs, consider using fewer or lower sample stages
+
+## Future Enhancements
+
+Potential improvements for this feature:
+- Adjustable sample stages via command-line arguments
+- Real-time statistics overlay (FPS, rays/sec, current stage)
+- Pause/resume functionality
+- Save intermediate stages
+- Tile-based progressive rendering for huge resolutions
+- Multi-GPU support for faster stage completion
+
+## Code References
+
+- **Main implementation**: `src/302_raytracer/camera.h` - `renderPixelsSDLProgressive()`
+- **Menu integration**: `src/302_raytracer/main.cc` - rendering method selection
+- **CMake configuration**: `CMakeLists.txt` - SDL2 detection and linking
+- **CUDA backend**: `src/302_raytracer/camera_cuda.cu` - `renderPixelsCUDA()`
diff --git a/src/302_raytracer/camera.h b/src/302_raytracer/camera.h
@@ -19,6 +19,10 @@
 #include <thread>
 #include <vector>
 
+#ifdef SDL2_FOUND
+#include <SDL.h>
+#endif
+
 #pragma once
 
 class Camera
@@ -187,6 +191,143 @@ class Camera
       cout << "CUDA rendering completed in " << timeStr(duration) << endl;
    }
 
+#ifdef SDL2_FOUND
+   /**
+    * @brief Renders progressively with SDL2 window display showing incremental quality improvements
+    * 
+    * This method displays the image in an SDL window while rendering with increasing sample rates.
+    * It starts with low sample counts for quick preview and progressively increases quality.
+    * User can close the window at any time or wait for the final quality render.
+    * 
+    * @param image The final image buffer to store the highest quality render
+    * @param sample_stages Vector of sample counts for progressive rendering (e.g., {1, 4, 16, 64, 256})
+    */
+   void renderPixelsSDLProgressive(vector<unsigned char> &image, const vector<int> &sample_stages = {1, 4, 16, 64, 256})
+   {
+      // Initialize SDL
+      if (SDL_Init(SDL_INIT_VIDEO) < 0)
+      {
+         cerr << "SDL initialization failed: " << SDL_GetError() << endl;
+         return;
+      }
+
+      // Create window
+      SDL_Window *window = SDL_CreateWindow("Ray Tracer - Progressive Rendering", SDL_WINDOWPOS_CENTERED,
+                                             SDL_WINDOWPOS_CENTERED, image_width, image_height, SDL_WINDOW_SHOWN);
+      if (!window)
+      {
+         cerr << "Window creation failed: " << SDL_GetError() << endl;
+         SDL_Quit();
+         return;
+      }
+
+      // Create renderer
+      SDL_Renderer *renderer = SDL_CreateRenderer(window, -1, SDL_RENDERER_ACCELERATED);
+      if (!renderer)
+      {
+         cerr << "Renderer creation failed: " << SDL_GetError() << endl;
+         SDL_DestroyWindow(window);
+         SDL_Quit();
+         return;
+      }
+
+      // Create texture for displaying the image
+      SDL_Texture *texture = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_RGB24, SDL_TEXTUREACCESS_STREAMING,
+                                                image_width, image_height);
+      if (!texture)
+      {
+         cerr << "Texture creation failed: " << SDL_GetError() << endl;
+         SDL_DestroyRenderer(renderer);
+         SDL_DestroyWindow(window);
+         SDL_Quit();
+         return;
+      }
+
+      cout << "\n=== Progressive SDL Rendering ===" << endl;
+      cout << "Close window or press ESC to stop at current quality\n" << endl;
+
+      bool running = true;
+      SDL_Event event;
+      vector<unsigned char> stage_image(image_width * image_height * image_channels);
+
+      auto total_start = std::chrono::high_resolution_clock::now();
+
+      // Progressive rendering through sample stages
+      for (size_t stage = 0; stage < sample_stages.size() && running; stage++)
+      {
+         int current_samples = sample_stages[stage];
+         int original_samples = samples_per_pixel;
+         samples_per_pixel = current_samples;
+
+         cout << "Rendering stage " << (stage + 1) << "/" << sample_stages.size() << " with " << current_samples
+              << " samples per pixel..." << flush;
+
+         auto stage_start = std::chrono::high_resolution_clock::now();
+
+         // Render with CUDA for this stage
+         unsigned long long cuda_ray_count =
+             ::renderPixelsCUDA(stage_image.data(), image_width, image_height, camera_center.x(), camera_center.y(),
+                                camera_center.z(), pixel00_loc.x(), pixel00_loc.y(), pixel00_loc.z(), pixel_delta_u.x(),
+                                pixel_delta_u.y(), pixel_delta_u.z(), pixel_delta_v.x(), pixel_delta_v.y(),
+                                pixel_delta_v.z(), current_samples, max_depth);
+
+         n_rays.fetch_add(cuda_ray_count, std::memory_order_relaxed);
+
+         auto stage_end = std::chrono::high_resolution_clock::now();
+         cout << " completed in " << timeStr(stage_end - stage_start) << endl;
+
+         // Update SDL texture and display
+         SDL_UpdateTexture(texture, nullptr, stage_image.data(), image_width * image_channels);
+         SDL_RenderClear(renderer);
+         SDL_RenderCopy(renderer, texture, nullptr, nullptr);
+         SDL_RenderPresent(renderer);
+
+         // Copy to final image buffer
+         image = stage_image;
+
+         // Check for SDL events (window close, ESC key, etc.)
+         while (SDL_PollEvent(&event))
+         {
+            if (event.type == SDL_QUIT || (event.type == SDL_KEYDOWN && event.key.keysym.sym == SDLK_ESCAPE))
+            {
+               running = false;
+               cout << "\nRendering stopped by user at stage " << (stage + 1) << "/" << sample_stages.size() << endl;
+               break;
+            }
+         }
+
+         samples_per_pixel = original_samples;
+      }
+
+      auto total_end = std::chrono::high_resolution_clock::now();
+      cout << "\nTotal progressive rendering time: " << timeStr(total_end - total_start) << endl;
+
+      if (running)
+      {
+         cout << "Press any key or close window to continue..." << endl;
+         // Wait for user to close window or press a key
+         while (running)
+         {
+            while (SDL_PollEvent(&event))
+            {
+               if (event.type == SDL_QUIT || event.type == SDL_KEYDOWN)
+               {
+                  running = false;
+                  break;
+               }
+            }
+            SDL_Delay(100);
+         }
+      }
+
+      // Cleanup
+      SDL_DestroyTexture(texture);
+      SDL_DestroyRenderer(renderer);
+      SDL_DestroyWindow(window);
+      SDL_Quit();
+   }
+#endif // SDL2_FOUND
+
  private:
    Point3 camera_center; // Camera center
    Point3 pixel00_loc;   // Location of pixel 0, 0
diff --git a/src/302_raytracer/main.cc b/src/302_raytracer/main.cc
@@ -179,7 +179,14 @@ int main(int argc, char *argv[])
    cout << "\t0. CPU sequential" << endl;
    cout << "\t1. CPU parallel" << endl;
    cout << "\t2. CUDA GPU (default)" << endl;
-   cout << "Enter choice (0, 1, or 2): ";
+#ifdef SDL2_FOUND
+   cout << "\t3. CUDA GPU with progressive SDL display" << endl;
+#endif
+   cout << "Enter choice (0, 1, 2" 
+#ifdef SDL2_FOUND
+        << ", or 3"
+#endif
+        << "): ";
 
    int choice = 2; // Default to CUDA
    string input;
@@ -202,6 +209,12 @@ int main(int argc, char *argv[])
       cout << "Using CPU parallel rendering..." << endl;
       c.renderPixelsParallel(scene, localImage);
       break;
+#ifdef SDL2_FOUND
+   case 3:
+      cout << "Using CUDA GPU with progressive SDL display..." << endl;
+      c.renderPixelsSDLProgressive(localImage, {1, 4, 16, 64, 256, 1024});
+      break;
+#endif
    default:
       cout << "Using CUDA GPU rendering..." << endl;
       c.renderPixelsCUDA(localImage);
