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](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.