# shdrlib Documentation
Welcome to the shdrlib documentation! This guide will help you navigate the available resources.
## 📖 Documentation Structure
```
docs/
├── README.md (you are here)
├── INDEX.md (complete documentation index)
├── getting-started/ # New user guides
│ ├── installation.md
│ ├── quickstart.md
│ ├── vulkan-basics.md
│ ├── choosing-a-tier.md
│ ├── troubleshooting.md
│ └── faq.md
├── guides/ # In-depth tier guides
│ ├── ez-tier-guide.md
│ ├── ex-tier-guide.md
│ ├── core-tier-guide.md
│ └── migration-guide.md
├── architecture/ # Design documentation
│ ├── overview.md
│ ├── three-tier-design.md
│ ├── zero-cost-abstractions.md
│ └── safety-guarantees.md
├── api/ # API reference
│ ├── core/
│ ├── ex/
│ └── ez/
└── examples/ # Annotated examples
├── ez-examples.md
├── ex-examples.md
└── core-examples.md
```
## 🚀 Quick Navigation
### I'm new to shdrlib
1. Read [QUICKSTART.md](../QUICKSTART.md) in the root directory
2. Follow [Getting Started → Installation](getting-started/installation.md)
3. Try the [Quick Start Tutorial](getting-started/quickstart.md)
4. Learn [How to Choose a Tier](getting-started/choosing-a-tier.md)
### I want to build something
1. **Prototyping/Learning?** → [EZ Tier Guide](guides/ez-tier-guide.md)
2. **Production app?** → [EX Tier Guide](guides/ex-tier-guide.md)
3. **Custom framework?** → [CORE Tier Guide](guides/core-tier-guide.md)
### I need specific information
- **API Reference** → Run `cargo doc --open` or see [api/](api/)
- **Examples** → See [examples/](examples/) or `demos/` directory
- **Architecture** → See [architecture/](architecture/)
- **Troubleshooting** → See [getting-started/troubleshooting.md](getting-started/troubleshooting.md)
### I want to contribute
- Read [CONTRIBUTING.md](../CONTRIBUTING.md)
- Check [Architecture Overview](architecture/overview.md)
- See [Development Guidelines](../CONTRIBUTING.md#development-workflow)
## 📚 Documentation by Topic
### Getting Started
- [Installation](getting-started/installation.md) - Set up your environment
- [Quick Start](getting-started/quickstart.md) - Your first triangle in 5 minutes
- [Vulkan Basics](getting-started/vulkan-basics.md) - Essential Vulkan concepts
- [Choosing a Tier](getting-started/choosing-a-tier.md) - Which abstraction level?
- [FAQ](getting-started/faq.md) - Common questions answered
- [Troubleshooting](getting-started/troubleshooting.md) - Fix common issues
### User Guides
- [EZ Tier Guide](guides/ez-tier-guide.md) 📋 - High-level API for rapid development
- [EX Tier Guide](guides/ex-tier-guide.md) 📋 - Production-ready explicit control
- [CORE Tier Guide](guides/core-tier-guide.md) 📋 - Low-level Vulkan wrappers
- [Migration Guide](guides/migration-guide.md) 📋 - Moving between tiers
### Architecture & Design
- [Overview](architecture/overview.md) 📋 - Project philosophy and goals
- [Three-Tier Design](architecture/three-tier-design.md) 📋 - Why three tiers?
- [Zero-Cost Abstractions](architecture/zero-cost-abstractions.md) 📋 - Performance details
- [Safety Guarantees](architecture/safety-guarantees.md) 📋 - Memory safety explained
### API Reference
- [CORE API](api/core/) 📋 - Low-level Vulkan wrappers
- [EX API](api/ex/) 📋 - Ergonomic managers and helpers
- [EZ API](api/ez/) 📋 - High-level renderer
### Examples & Tutorials
- [EZ Examples](examples/ez-examples.md) 📋 - Learning and prototyping
- [EX Examples](examples/ex-examples.md) 📋 - Production patterns
- [CORE Examples](examples/core-examples.md) 📋 - Advanced usage
## 🎯 Common Tasks
### Rendering a Triangle
- **EZ:** [Quick Start → EZ Tier](getting-started/quickstart.md#ez-tier-your-first-triangle-in-30-lines)
- **EX:** [Quick Start → EX Tier](getting-started/quickstart.md#ex-tier-production-ready-in-100-lines)
- **CORE:** [Quick Start → CORE Tier](getting-started/quickstart.md#core-tier-maximum-control)
### Working with Buffers
- **EZ:** See demos in `demos/ez/03_buffers_demo.rs`
- **EX:** See demos in `demos/ex/` (coming soon)
- **CORE:** See demos in `demos/core/` (coming soon)
### Loading Textures
- **EZ:** See demos in `demos/ez/` (coming soon)
- **EX:** See demos in `demos/ex/03_textured_quad.rs`
- **CORE:** See demos in `demos/core/` (coming soon)
### Compute Shaders
- **EZ:** See `demos/ez/02_compute_multiply.rs`
- **EX:** See `demos/ex/02_compute_100_mul.rs`
- **CORE:** See `demos/core/02_compute_shader.rs`
## 🔍 Search Tips
1. **Use the Index:** See [INDEX.md](INDEX.md) for a complete documentation map
2. **Search in your editor:** Use Ctrl+F to search within files
3. **Check examples first:** Often the quickest way to learn - see `demos/` directory
4. **Run `cargo doc --open`:** For detailed API documentation
5. **Check the demos:** Working code in `demos/ez/`, `demos/ex/`, and `demos/core/`
## 📝 Documentation Conventions
Throughout the documentation, you'll see these indicators:
- ✅ **Complete** - Fully implemented and documented
- 📋 **Planned** - File structure exists, content coming soon
- 🚧 **In Progress** - Currently being worked on
- ⚠️ **Important** - Pay attention to this
- 💡 **Tip** - Helpful suggestion
- 🔥 **Performance** - Performance-related note
- ⭐ **Recommended** - Suggested approach
## 🤝 Contributing to Documentation
Found a typo? Want to improve an explanation? We welcome documentation contributions!
1. Read [CONTRIBUTING.md](../CONTRIBUTING.md)
2. Follow the [Documentation Guidelines](../CONTRIBUTING.md#documentation-guidelines)
3. Submit a pull request with `[DOCS]` prefix
## 📞 Getting Help
Can't find what you're looking for?
- Check the [FAQ](getting-started/faq.md)
- Read [Troubleshooting](getting-started/troubleshooting.md)
- Open a [GitHub Discussion](https://github.com/paulburnettjones-wq/shdrlib/discussions)
- Check existing [GitHub Issues](https://github.com/paulburnettjones-wq/shdrlib/issues)
---
**Happy rendering!** 🚀