goldy 0.1.0

Goldy - Modern Graphics Library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# Target Hardware

Goldy targets **modern GPUs only**. This is a deliberate choice that enables significant API simplification.

## Minimum Requirements

| Platform | Minimum | Year | Notes |
|----------|---------|------|-------|
| **NVIDIA** | RTX 2000 / GTX 1600 | 2018 | Vulkan 1.4, mesh shaders |
| **AMD** | RDNA 1 (RX 5000) | 2019 | Vulkan 1.4, modern cache |
| **Intel** | Xe / Alchemist | 2022 | Vulkan 1.4, DX12 |
| **Apple** | M1 / A14 | 2020 | Metal 2+, unified memory |
| **Qualcomm** | Adreno 650+ | 2019 | Vulkan 1.2+ with extensions |

## What "Modern" Means

These hardware generations share key architectural features:

### 1. Coherent Cache Hierarchies

Modern GPUs have coherent L2 caches. This means:
- No manual cache flush/invalidate
- Simplified synchronization
- Better CPU-GPU data sharing

### 2. Bindless Resource Access

Descriptors live in GPU-visible memory:
- No descriptor set limits
- Index-based resource access in shaders
- Simpler binding model

### 3. Unified Memory (where available)

Apple Silicon and integrated GPUs share memory with CPU:
- Zero-copy data transfer
- Simplified allocation
- Lower latency

### 4. 64-bit Buffer Addresses

Shaders can use direct pointers:
- Buffer device address support
- Simpler data access patterns
- Pointer arithmetic in shaders

### 5. Dynamic Rendering

No need for render pass objects:
- Render targets specified at draw time
- Simpler API
- No render pass compatibility issues

## What This Excludes

Goldy does **not** support:

| Excluded | Reason |
|----------|--------|
| GTX 900 series | No Vulkan 1.2 bindless |
| AMD GCN (RX 400/500) | Driver support ended 2021 |
| Intel Gen9 (HD 500/600) | Limited Vulkan support |
| iPhone 11 / A13 | No Metal 4.0 |
| Integrated Intel < Xe | Feature gaps |

## The Tradeoff

By requiring modern hardware, Goldy can:

✅ **Assume modern features** as baseline (bindless, dynamic rendering)  
✅ **Skip compatibility layers** that add complexity  
✅ **Use native backend idioms** without translation  
✅ **Provide simpler API** with fewer edge cases  

But it cannot:

❌ Run on older hardware  
❌ Support the long tail of legacy systems  
❌ Deploy to low-end current devices  

## Checking Compatibility

Goldy will report unsupported devices at initialization:

```rust
let instance = Instance::new()?;

// List available adapters
for adapter in instance.enumerate_adapters() {
    println!("{}: {:?}", adapter.name, adapter.device_type);
}

// create_device will fail on unsupported hardware
let device = instance.create_device(DeviceType::DiscreteGpu)?;
```

## Future Hardware

As GPUs evolve, Goldy can adopt new features:

- **Automatic hazard detection** → Simpler barriers
- **Hardware descriptor management** → Simpler binding
- **Universal unified memory** → Simpler allocation

Goldy's non-standard status means it can adopt these simplifications as hardware supports them, without waiting for committee consensus.