Implement comprehensive error handling and feedback for SDL and Vulkan initialization

2026-04-24 13:44:58 +00:00 · 2026-01-03 22:43:02 +00:00
parent 3021780e7c
commit 070992935c
5 changed files with 383 additions and 26 deletions
--- a/docs/test_error_handling.md
+++ b/docs/test_error_handling.md
@@ -0,0 +1,229 @@
+# 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](src/app/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](src/app/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](src/app/sdl3_app_core.cpp), [sdl3_app_pipeline.cpp](src/app/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.spv
+
+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 shaders are compiled and in the correct directory
+
+**Example error message**:
+```
+Vertex shader not found: shaders/cube.vert.spv
+
+Shader key: default
+
+Please ensure shader files are compiled and present in the shaders directory.
+```
+
+### 4. Structured Vulkan Initialization ([sdl3_app_core.cpp](src/app/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](src/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
+```bash
+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
+```bash
+cd build/Release
+mv shaders/cube.vert.spv shaders/cube.vert.spv.backup
+./sdl3_app --json-file-in ./config/seed_runtime.json
+```
+
+**Expected Result**:
+Message box showing:
+```
+Vertex shader not found: shaders/cube.vert.spv
+
+Shader key: default
+
+Please ensure shader files are compiled and present in the shaders directory.
+```
+
+### Test Case 3: Normal Operation
+```bash
+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](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](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](src/app/sdl3_app_pipeline.cpp)**
+   - Added shader file existence validation in `CreateGraphicsPipeline()`
+
+4. **[src/main.cpp](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:
+   ```bash
+   ./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:
+   ```bash
+   ./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.
+