SDL3CPlusPlus/docs/test_error_handling.md

Error Handling Improvements - Summary

Problem Statement

The application was crashing with a "see-through window" and no user feedback about what went wrong. The process would be killed (exit code 137 - SIGKILL) without any diagnostic information.

Changes Made

1. SDL Initialization Error Dialogs (sdl3_app_core.cpp)

• Added ShowErrorDialog() helper function to display visual error messages via SDL_ShowSimpleMessageBox
• Wrapped SDL initialization calls with try-catch blocks that show error dialogs:
  • SDL_Init: Shows which subsystem failed to initialize
  • SDL_Vulkan_LoadLibrary: Warns user to check Vulkan driver installation
  • SDL_CreateWindow: Provides window creation error details

Example error message:

Title: "Vulkan Library Load Failed"
Message: "Failed to load Vulkan library. Make sure Vulkan drivers are installed.

Error: SDL_Vulkan_LoadLibrary failed: ..."

2. Vulkan Validation with Detailed Feedback (sdl3_app_device.cpp)

Instance Creation

• Lists all required Vulkan extensions when creation fails
• Provides hints about common causes (missing drivers, incompatible GPU)

Physical Device Selection

• Enumerates all detected GPUs with their names
• Marks each as [SELECTED] or [UNSUITABLE]
• Explains required features:
  • Graphics queue support
  • Present queue support
  • Swapchain extension (VK_KHR_swapchain)
  • Adequate swapchain formats and present modes

Example error message:

Failed to find a suitable GPU.

Found 2 GPU(s), but none meet the requirements.
GPU 0: Intel HD Graphics 620 [UNSUITABLE]
GPU 1: NVIDIA GeForce GTX 1050 [UNSUITABLE]

Required features:
- Graphics queue support
- Present queue support
- Swapchain extension support (VK_KHR_swapchain)
- Adequate swapchain formats and present modes

Device Extension Support

• Logs all missing required extensions to stderr
• Helps identify driver or GPU capability issues

3. Resource Existence Validation (sdl3_app_core.cpp, sdl3_app_pipeline.cpp)

Enhanced ReadFile() Function

Now validates before attempting to read:

• ✅ File exists at the specified path
• ✅ Path points to a regular file (not a directory)
• ✅ File is not empty
• ✅ File has read permissions

Example error messages:

File not found: /path/to/shader.vert

Please ensure the file exists at this location.

Failed to open file: /path/to/file.txt

The file exists but cannot be opened. Check file permissions.

Shader File Validation

• Checks both vertex and fragment shader files exist before loading
• Provides the shader key to help identify which pipeline failed
• Suggests checking that shader sources are present in the correct directory

Example error message:

Vertex shader not found: shaders/missing.vert

Shader key: default

Please ensure shader source files are present in the shaders directory.

4. Structured Vulkan Initialization (sdl3_app_core.cpp)

The InitVulkan() function now wraps each stage in try-catch blocks with specific error dialogs:

1. Instance Creation → "Vulkan Instance Creation Failed"
2. Surface Creation → "Vulkan Surface Creation Failed"
3. GPU Selection → "GPU Selection Failed"
4. Logical Device → "Logical Device Creation Failed"
5. Resource Setup → "Vulkan Resource Setup Failed"
   • Swapchain, GUI renderer, image views, render pass
   • Scene data, graphics pipeline, framebuffers
   • Command pool, vertex/index buffers, command buffers, sync objects

Each failure shows a message box with the error details before rethrowing.

5. Main Function Error Handling (main.cpp)

• Catches all exceptions at the top level
• Displays error via SDL_ShowSimpleMessageBox for visual feedback
• Also logs to stderr for console/log file capture
• Returns EXIT_FAILURE with clear error indication

Benefits

1. Visual Feedback ✨

Before: Silent crash with transparent window
After: Clear error dialog explaining what went wrong

2. Actionable Messages 🔧

Errors now include:

• What failed (e.g., "GPU Selection Failed")
• Why it might have failed (e.g., "Missing Vulkan drivers")
• What to check (e.g., "Ensure shader files are compiled")

3. Debugging Aid 🐛

Detailed information helps diagnose issues:

• List of detected GPUs and their suitability
• Required vs available extensions
• Full file paths for missing resources

4. Early Validation ⚡

Resources are validated before use:

• No more cryptic segfaults from missing files
• Fails fast with clear error messages
• Reduces time to identify and fix issues

5. No Silent Failures 📢

All error paths now provide feedback:

• Console output (stderr)
• Visual message boxes (SDL)
• Proper exit codes

Testing the Improvements

Test Case 1: Missing Lua Script

cd build/Release
sed -i 's/cube_logic.lua/nonexistent_file.lua/' config/test_bad_config.json
./sdl3_app --json-file-in ./config/test_bad_config.json

Expected Result:

ERROR: Lua script not found at /path/to/nonexistent_file.lua

Plus a message box with the same error.

Test Case 2: Missing Shader File

cd build/Release
sed -i 's/return {default = variant}/return {default = {vertex = "shaders\/missing.vert", fragment = "shaders\/missing.frag"}}/' ../scripts/gui_demo.lua
./sdl3_app --json-file-in ./config/gui_runtime.json

Expected Result: Message box showing:

Vertex shader not found: shaders/missing.vert

Shader key: default

Please ensure shader files are compiled and present in the shaders directory.

Restore scripts/gui_demo.lua after the test run.

Test Case 3: Normal Operation

cd build/Release
./sdl3_app --json-file-in ./config/seed_runtime.json

Expected Result: Application runs normally. If any errors occur during initialization, they will be caught and displayed with helpful context instead of causing a silent crash.

Files Modified

1. src/app/sdl3_app_core.cpp

   • Added ShowErrorDialog() function
   • Enhanced ReadFile() with validation
   • Added error handling to InitSDL() and InitVulkan()

2. src/app/sdl3_app_device.cpp

   • Enhanced error messages in CreateInstance()
   • Improved GPU enumeration in PickPhysicalDevice()
   • Added missing extension logging in CheckDeviceExtensionSupport()

3. src/app/sdl3_app_pipeline.cpp

   • Added shader file existence validation in CreateGraphicsPipeline()

4. src/main.cpp

   • Added SDL message box display for all caught exceptions

Recommendations

1. Enable Tracing: Use the --trace flag to get detailed execution logs:

   ./sdl3_app --json-file-in config/seed_runtime.json --trace
   

2. Check Logs: If the app crashes, check:

   • Console output (stderr)
   • System logs: journalctl -xe or dmesg (on Linux)
   • Application return code: echo $?

3. Verify Environment:

   • Vulkan drivers installed: vulkaninfo
   • GPU compatibility: vkcube (if available)
   • Required extensions available

4. Config Validation: The app now catches config errors early. Use --dump-json to verify your configuration:

   ./sdl3_app --json-file-in config/seed_runtime.json --dump-json
   

Conclusion

The application now provides comprehensive error feedback instead of failing silently with a "see-through window". Every potential failure point has been wrapped with validation and clear error messages, making it much easier to diagnose and fix issues.