# Vulkan Basics
**Essential Vulkan concepts for shdrlib users.**
## Core Concepts
### Instance
Entry point to Vulkan. One per application.
```rust
// CORE
let instance = Instance::new(&InstanceCreateInfo::default())?;
// EX/EZ - handled automatically
```
### Physical Device (GPU)
Your graphics card. Choose based on features.
```rust
// CORE
let gpus = instance.enumerate_physical_devices()?;
// EX - automatic selection
// EZ - automatic selection
```
### Logical Device
Interface to GPU. Create queues and resources.
```rust
// CORE
let device = Device::new(&instance, gpu, &DeviceCreateInfo::default())?;
// EX/EZ - handled automatically
```
### Queue
Submit work to GPU. Types: graphics, compute, transfer.
```rust
// CORE
let queue = Queue::get(&device, family_index, 0);
queue.submit(&device, command_buffers, ...)?;
// EX - via RuntimeManager
// EZ - automatic
```
---
## Resources
### Buffers
Linear memory for vertices, indices, uniforms.
```rust
// CORE
let buffer = Buffer::new(&device, size, usage, memory_properties)?;
// EX
let buffer = create_vertex_buffer(&device, &vertices)?;
// EZ
let buffer = renderer.create_vertex_buffer(&vertices)?;
```
**Types:**
- **Vertex** - Vertex data
- **Index** - Index data
- **Uniform** - Small, frequently updated data
- **Storage** - Large, arbitrary data
### Images
2D/3D textures and render targets.
```rust
// CORE
let image = Image::new(&device, extent, format, usage, memory_properties)?;
// EX
let image = create_texture(&device, width, height, format)?;
// EZ
let image = renderer.create_texture(width, height)?;
```
**Types:**
- **Texture** - Sampled in shaders
- **Render Target** - Draw to this
- **Depth/Stencil** - For depth testing
---
## Pipeline
### Shaders
Code that runs on GPU.
```rust
// CORE
let shader = Shader::from_glsl(&device, glsl, ShaderStage::Vertex)?;
// EX
let id = shaders.add_shader(glsl, ShaderStage::Vertex, "name")?;
// EZ
let pipeline = renderer.quick_pipeline(vert_glsl, frag_glsl)?;
```
**Stages:**
- **Vertex** - Process vertices
- **Fragment** - Process pixels
- **Compute** - General-purpose compute
### Graphics Pipeline
Complete config for drawing: shaders, blending, depth, etc.
```rust
// CORE
let pipeline = PipelineBuilder::new()
.vertex_shader(module, "main")
.fragment_shader(module, "main")
.build_graphics(&device, layout)?;
// EX
let id = shaders.build_pipeline(builder, "name")?;
// EZ
let id = renderer.quick_pipeline(vert, frag)?;
```
---
## Commands
### Command Buffer
Records GPU commands. Like a script.
```rust
// CORE
let cmd = pool.allocate_primary(&device)?;
cmd.begin(&device, flags)?;
cmd.bind_pipeline(&device, bind_point, pipeline);
cmd.draw(&device, 3, 1, 0, 0);
cmd.end(&device)?;
// EX
let frame = runtime.begin_frame()?;
let cmd = frame.command_buffer;
// ... record ...
// EZ
renderer.render_frame(|frame| {
frame.bind_pipeline(pipeline)?;
frame.draw(3, 1, 0, 0);
Ok(())
})?;
```
### Dynamic Rendering
Modern way to render without render pass objects.
```rust
cmd.begin_rendering(&rendering_info);
// ... draw commands ...
cmd.end_rendering();
```
shdrlib uses dynamic rendering (Vulkan 1.3+) everywhere.
---
## Synchronization
### Fence
CPU waits for GPU.
```rust
// CORE
let fence = Fence::new(&device, false)?;
queue.submit(&device, cmds, ..., Some(fence.handle()))?;
fence.wait(&device, timeout)?;
// EX/EZ - handled automatically
```
### Semaphore
GPU waits for GPU.
```rust
// CORE
let semaphore = Semaphore::new(&device)?;
queue.submit(..., signal_semaphores: &[semaphore.handle()])?;
// EX/EZ - handled automatically
```
---
## Memory
### Host-Visible
CPU can access. Slower for GPU.
```rust
// Good for: Staging, frequently updated data
let buffer = Buffer::new(&device, size, usage,
vk::MemoryPropertyFlags::HOST_VISIBLE | vk::MemoryPropertyFlags::HOST_COHERENT)?;
```
### Device-Local
GPU-only. Fastest for GPU.
```rust
// Good for: Vertices, textures, render targets
let buffer = Buffer::new(&device, size, usage,
vk::MemoryPropertyFlags::DEVICE_LOCAL)?;
```
**Pattern:** Upload via staging buffer to device-local.
---
## Descriptors
Bindings for shaders to access resources.
```rust
// CORE
let layout = DescriptorSetLayout::new(&device, &bindings)?;
let pool = DescriptorPool::new(&device, max_sets, &pool_sizes)?;
let sets = pool.allocate(&device, &[layout.handle()])?;
// EX
let layout = DescriptorLayoutBuilder::new()
.uniform_buffer(0, ShaderStageFlags::VERTEX)
.build(&device)?;
// EZ - automatic (future feature)
```
**Types:**
- **Uniform Buffer** - Small, frequent updates
- **Storage Buffer** - Large, arbitrary data
- **Sampled Image** - Textures
- **Storage Image** - Read/write images
---
## Tier Mapping
| Instance | Manual | Auto | Auto |
| Device | Manual | Auto | Auto |
| Queue | Manual | Managed | Auto |
| Buffers | Manual | Helpers | One-liners |
| Images | Manual | Helpers | One-liners |
| Shaders | Manual | Manager | One-liners |
| Pipelines | Builder | Manager | One-liners |
| Commands | Manual | Semi-auto | Auto |
| Sync | Manual | Managed | Auto |
---
## Learn More
**Vulkan Tutorial:** https://vulkan-tutorial.com/
**Vulkan Guide:** https://vkguide.dev/
**Spec:** https://registry.khronos.org/vulkan/
**shdrlib guides:**
- [EZ Tier Guide](../guides/ez-tier-guide.md)
- [EX Tier Guide](../guides/ex-tier-guide.md)
- [CORE Tier Guide](../guides/core-tier-guide.md)