# Frequently Asked Questions
Common questions about shdrlib answered.
## General Questions
### What is shdrlib?
shdrlib is a three-tiered Vulkan rendering framework written in pure Rust. It provides three levels of abstraction (CORE, EX, EZ) so you can choose between maximum control and ease of use.
### Is shdrlib a game engine?
**No.** shdrlib is a backend rendering library focused on shader compilation and Vulkan rendering. It does NOT provide:
- Windowing or input handling (use winit, sdl2, etc.)
- Entity component systems
- Physics engines
- Audio systems
- Asset pipelines
It DOES provide:
- Vulkan rendering abstractions
- Pure Rust shader compilation
- Buffer and texture management
- Pipeline creation
- Command recording
### What makes shdrlib different?
1. **Three-tier architecture** - Choose your abstraction level
2. **Pure Rust** - No external build tools (naga for shaders)
3. **Zero-cost abstractions** - All tiers compile to identical code
4. **Progressive disclosure** - Drop to lower tiers anytime
5. **Memory safe** - Rust's ownership prevents common bugs
### Which tier should I use?
- **Learning Vulkan?** → Start with EZ tier
- **Building an app/game?** → Use EX tier (recommended)
- **Building a framework/engine?** → Use CORE tier
- **Not sure?** → Start with EZ, drop to EX when you need more control
### Can I mix tiers in one project?
**Yes!** That's the point. Start with EZ for prototyping, use EX for production code, and drop to CORE for specific optimizations. All tiers interoperate seamlessly.
---
## Installation & Setup
### What Rust version do I need?
Rust 1.82+ (Edition 2024). Check with `rustc --version`.
Update if needed: `rustup update stable`
### Do I need the Vulkan SDK?
**For running:** Only the Vulkan runtime (drivers provide this)
**For development:** Yes, for validation layers (helps catch errors)
Install from: https://vulkan.lunarg.com/
### Why do I get "Vulkan loader not found"?
Your system doesn't have the Vulkan runtime installed.
**Fix:**
- Install graphics drivers (NVIDIA, AMD, Intel)
- Install Vulkan SDK
- On Linux: `sudo apt install libvulkan1`
### Can I use shdrlib without a GPU?
Yes, with software renderers like SwiftShader, but it will be slow. Most development needs a real GPU with Vulkan 1.3 support.
---
## Shader Compilation
### Do I need external tools to compile shaders?
**No!** shdrlib uses naga for pure Rust GLSL→SPIR-V compilation. No need for:
- glslc / glslangValidator
- Python
- CMake / Ninja
- Visual Studio
Just write GLSL, shdrlib compiles it.
### What shader languages are supported?
Currently: **GLSL only** (via naga)
SPIR-V binary can be used directly with CORE tier.
Future: WGSL, HLSL support planned.
### Can I load pre-compiled SPIR-V?
Yes! Use `Shader::from_spirv()` in CORE tier:
```rust
let spirv = std::fs::read("shader.spv")?;
let shader = Shader::from_spirv(&device, &spirv, ShaderStage::Vertex)?;
```
### Why do I get "shader compilation failed"?
Common causes:
1. **Syntax error** - Check GLSL syntax
2. **Unsupported feature** - naga doesn't support all GLSL extensions
3. **Version mismatch** - Use `#version 450` or `#version 460`
Enable detailed error messages in debug builds.
---
## Performance
### Does EZ/EX tier have overhead?
**No!** Heavy use of `#[inline]` means all abstractions compile away. EZ and EX tier code generates identical assembly to CORE tier code.
This is verified through aggressive inlining and zero-cost abstractions.
### Should I worry about performance?
Not at the abstraction level. Worry about:
- GPU work (shaders, bandwidth)
- CPU-GPU synchronization
- Memory allocation patterns
- Command buffer recording
The tier you choose doesn't affect these.
### When should I drop to CORE tier?
When you need:
- Absolute control over Vulkan calls
- Custom memory allocation strategies
- Non-standard pipeline configurations
- Integration with existing Vulkan code
For 99% of apps, EX tier is fast enough.
---
## Development
### How do I debug rendering issues?
1. **Enable validation layers** (automatic in debug builds)
2. **Check error messages** - shdrlib provides detailed errors
3. **Use RenderDoc** - Capture and inspect frames
4. **Try simpler code** - Start with EZ tier examples
5. **Check Vulkan setup** - Run `vkcube` to verify drivers
### Can I use shdrlib with an existing Vulkan app?
Yes! Use CORE tier which provides minimal wrappers. You can mix shdrlib objects with raw `ash` / Vulkan code.
Example:
```rust
// Create device with shdrlib
let device = shdrlib::core::Device::new(...)?;
// Use raw Vulkan handle
let raw_handle = device.handle();
unsafe {
raw_handle.device_wait_idle()?;
}
```
### Does shdrlib support multi-threading?
**CORE tier:** You manage thread safety
**EX/EZ tier:** Use `Arc<Device>` for safe sharing
Vulkan itself requires external synchronization. shdrlib doesn't add additional restrictions.
### How do I handle window resizing?
shdrlib doesn't manage windows. You handle resize in your windowing code (winit, etc.), then recreate swapchain and render targets.
Example pattern:
```rust
// In your resize handler
let new_swapchain = /* recreate */;
let new_render_target = /* recreate with new size */;
```
---
## Errors & Troubleshooting
### "No suitable physical device found"
**Causes:**
- No GPU with Vulkan 1.3 support
- Outdated drivers
- Vulkan runtime not installed
**Fixes:**
- Update graphics drivers
- Install Vulkan SDK
- Check `vulkaninfo` output
### "Out of memory" errors
**Causes:**
- Creating too many resources
- Memory leaks (holding onto dropped resources)
- GPU running out of VRAM
**Fixes:**
- Destroy unused resources
- Use smaller textures/buffers
- Check resource lifecycle
### "Validation errors" in debug builds
**Good!** Validation layers are catching bugs. Read the message carefully:
- It tells you what's wrong
- It suggests fixes
- It's helping you before the bug becomes a crash
Fix the underlying issue, don't disable validation.
### Compilation is slow
**Causes:**
- Debug builds include validation
- Large projects take time
**Fixes:**
- Use `--release` for benchmarking
- Use `cargo build` (not `cargo clean && cargo build`)
- Enable incremental compilation (default)
---
## Features
### Does shdrlib support ray tracing?
Not yet (v0.1). Planned for future releases.
### Can I use compute shaders?
Yes! All three tiers support compute shaders.
**EZ:**
```rust
let compute = renderer.quick_compute(COMPUTE_GLSL)?;
renderer.dispatch_compute(compute, 256, 1, 1)?;
```
**EX:** PipelineBuilder supports compute
**CORE:** Full manual control
### What about tessellation/geometry shaders?
CORE tier supports them (Vulkan pass-through).
EX tier has partial support.
EZ tier: planned for v0.2.
### Does it support dynamic rendering?
Yes! shdrlib uses Vulkan 1.3 dynamic rendering (no render passes needed).
### What about swapchain management?
**CORE:** Full manual control via `Swapchain` type
**EX:** RuntimeManager handles basics
**EZ:** Automatic management
---
## Platform-Specific
### Does it work on macOS?
Yes, via MoltenVK (Vulkan on Metal). Some limitations:
- Validation may be less detailed
- Some Vulkan features unavailable
- Requires macOS 10.15+
### Linux: which drivers work?
- ✅ Mesa (Intel, AMD open-source)
- ✅ NVIDIA proprietary
- ✅ AMD proprietary (AMDGPU-PRO)
All support Vulkan 1.3 in recent versions.
### Windows: MSVC vs GNU toolchain?
Both work! Use whichever you prefer.
---
## Contributing
### How can I contribute?
See [CONTRIBUTING.md](../../CONTRIBUTING.md). We need:
- Documentation improvements
- Bug fixes
- Example programs
- Test coverage
### I found a bug. What should I do?
1. Check if it's already reported
2. Create minimal reproduction case
3. Open GitHub Issue with:
- Your OS and Rust version
- Minimal code to reproduce
- Expected vs actual behavior
- Error messages
### Can I add features?
Yes! Please open an issue first to discuss the design. Make sure it fits the tier philosophy:
- **CORE:** Minimal wrappers only
- **EX:** Explicit configuration
- **EZ:** Smart defaults
---
## Roadmap
### When is v1.0?
When the API stabilizes (v0.3-0.4 target). We're currently at v0.1.
### What's coming in v0.2?
- Performance benchmarks
- More EZ tier helpers
- Texture loading from files
- Additional examples
See [CHANGELOG.md](../../CHANGELOG.md) for details.
### Will there be breaking changes?
Yes, until v1.0. We'll follow semantic versioning:
- v0.x → breaking changes allowed
- v1.x → API stable, only additions
---
## Still have questions?
- 📖 Read the [Guides](../guides/)
- 🎨 Check the [Examples](../../demos/)
- 🐛 See [Troubleshooting](troubleshooting.md)
- 💬 Open a [GitHub Discussion](https://github.com/paulburnettjones-wq/shdrlib/discussions)
- 🔍 Search [GitHub Issues](https://github.com/paulburnettjones-wq/shdrlib/issues)
---
**Last Updated:** October 30, 2025