Volund Documentation

Technical documentation for the Volund Vulkan library.

---

Contents

Core Documentation

• ../CLAUDE.md - Project overview, build system, architecture, coding style
• ../plan.md - Implementation roadmap and module breakdown
• ../coding_style.md - Detailed C++17 coding conventions

Troubleshooting & Best Practices

• troubleshooting-vulkan-leaks.md - Complete case study of fixing 7 Vulkan object leaks

  • Investigation methodology
  • Root cause analysis for each leak type
  • Step-by-step solutions
  • Debugging tools and techniques
  • Testing strategies

• resource-lifecycle-patterns.md - Quick reference for proper resource management

  • Move-only RAII templates
  • Static resource patterns
  • Allocation tracking patterns
  • Destruction order guidelines
  • Code review checklist

---

Quick Links by Topic

When You Need To...

Fix a memory leak: → Start with troubleshooting-vulkan-leaks.md - Section "Troubleshooting Checklist"

Implement a new resource type: → See resource-lifecycle-patterns.md - Section "Move-Only RAII Resource Template"

Add a static/global resource: → See resource-lifecycle-patterns.md - Section "Static Resource Pattern"

Understand the codebase architecture: → See ../CLAUDE.md - Section "Architecture"

Follow coding style: → See ../coding_style.md

Implement a new module: → See ../plan.md - Section "Module Implementation Order"

---

Recent Issues & Solutions

2026-01-08: Vulkan Object Leaks Fixed

Problem: 7 Vulkan objects leaking (4 VkSampler, 1 VkDescriptorSetLayout, 2 VkDeviceMemory)

Root causes:

1. Static sampler presets outliving Context
2. Incomplete move semantics in Shader class
3. Untracked dedicated memory allocations

Solution: See full case study in troubleshooting-vulkan-leaks.md

Files modified:

• volund/context.hpp - Added sampler preset cleanup registration
• volund/resources.hpp - Rewrote sampler presets with non-owning wrappers
• volund/src/shader.cpp - Fixed move operations to transfer emptySetLayout_
• volund/detail/pool.hpp - Added isDedicated flag to PoolBlock
• volund/detail/block_allocator.hpp - Track dedicated allocations

Result: ✓ All leaks fixed, validation passes

---

Testing

Run Tests with Validation

mako build test1
./.build/bin/test1

Validation layers enabled by default in test1. Any leaks will be reported.

Debug Build

# Clean build with full debug info
mako clean
mako build test1

# Run with GDB
gdb ./.build/bin/test1

Check for Leaks

# Should output nothing if no leaks
./.build/bin/test1 2>&1 | grep "VULKAN ERROR"

# CPU-side memory leak detection
valgrind --leak-check=full ./.build/bin/test1

---

Contributing Documentation

When adding new documentation:

1. Use Markdown with clear headings and code blocks
2. Include code examples showing both wrong ❌ and correct ✓ patterns
3. Cross-reference related documents
4. Update this README with links to new docs
5. Add to "Recent Issues" if documenting a fix

Documentation Style

• Tutorials: Step-by-step, beginner-friendly
• Reference: Detailed, comprehensive, for looking up specifics
• Troubleshooting: Problem-solution format with debugging steps
• Case studies: Real issues with investigation → solution narrative

---

Additional Resources

External Links

• Vulkan Specification
• Vulkan-Hpp Documentation
• Vulkan Validation Layers
• RenderDoc (Debugging)

Internal References

• Source code: volund/ - Header-mostly library implementation
• Tests: tests/test1/ - Basic functionality and leak testing
• Build: Makofile - Build configuration

---

Document Status

Document	Status	Last Updated
troubleshooting-vulkan-leaks.md	✓ Complete	2026-01-08
resource-lifecycle-patterns.md	✓ Complete	2026-01-08
README.md	✓ Current	2026-01-08

---

For project overview and architecture, see ../CLAUDE.md