Problem

The ocean wave simulation was failing at runtime with critical Vulkan descriptor binding validation errors:

Uniforms supplied for set (0):
Set: 0 Binding: 0 Type: Image Writable: Y Length: 1
are not the same format as required by the pipeline shader. Pipeline shader requires:
Set: 0 Binding: 0 Type: Image Writable: N Length: 1

Root Cause: Both spectrum_compute (writeonly) and spectrum_modulate (readonly) shaders were sharing the same descriptor set binding (set=0, binding=0) with conflicting access patterns, violating Vulkan's strict descriptor validation rules.

Solution

Implemented a comprehensive three-phase fix addressing multiple validation issues:

🔧 Phase 1: Format Consistency

• Fixed shader format mismatch: spectrum_compute.glsl rgba16f → rgba32f
• Ensured consistency with texture creation (DATA_FORMAT_R32G32B32A32_SFLOAT)
• Removed restrict qualifier from readonly image in spectrum_modulate.glsl

🔧 Phase 2: Descriptor Binding Resolution

• Created separate descriptor sets for conflicting access patterns:
  • spectrum_write_set: for spectrum_compute (writeonly access)
  • spectrum_read_set: for spectrum_modulate (readonly access)
• Updated pipeline creation to use appropriate descriptor sets for each shader
• Maintained efficient resource usage by sharing the same texture resource

🔧 Phase 3: Proper GPU Synchronization

• Added compute barrier (compute_list_add_barrier()) between spectrum write and read operations
• Ensures write completion before read access begins in the GPU pipeline
• Prevents race conditions in the compute pipeline

📚 Additional Improvements

• Enhanced RenderingContext: Added create_texture_descriptor() helper function
• Comprehensive documentation: Added detailed CLAUDE.md for future development
• Preserved scientific accuracy: All oceanographic algorithms remain intact

Technical Impact

✅ Resolves all compute shader validation errors
✅ Maintains scientific accuracy of FFT-based ocean wave simulation
✅ Preserves GPU performance characteristics
✅ Follows Vulkan/Godot best practices for descriptor management
✅ Enables proper debugging and development workflow

Test Results

• ✅ Ocean simulation runs without validation errors
• ✅ Wave generation pipeline executes correctly
• ✅ FFT compute shaders process successfully
• ✅ Real-time parameter adjustment works via ImGui
• ✅ Multiple wave cascades render properly

Files Changed

• assets/shaders/compute/spectrum_compute.glsl - Format consistency fix
• assets/shaders/compute/spectrum_modulate.glsl - Readonly image declaration fix
• assets/water/wave_generator.gd - Descriptor binding and synchronization fixes
• assets/render_context.gd - Helper function for texture descriptors
• CLAUDE.md - Comprehensive project documentation

Scientific Preservation

The fix maintains the sophisticated oceanographic modeling:

• JONSWAP spectrum wave generation
• Hasselmann directional spreading
• FFT-based displacement calculation
• Real-time wave parameter control
• Multiple cascade layering

The ocean simulation now runs correctly with proper GPU resource synchronization while preserving all the advanced oceanographic science that makes this implementation unique.