VAR (Volume-Adaptive Routing) — Auto-Pick CPU or GPU for Your Spatial Queries

const router = VAR.init(null);
const decision = router.route(query_size, world_size); // .gpu or .cpu

What It Is

Why You Need It

Use It in 30 Seconds

# 1. Add to your project
zig fetch --save https://github.com/boonzy00/var/archive/v1.2.0.tar.gz

# 2. In your code
const var_pkg = @import("var");
const router = var_pkg.VAR.init(null);
const world_size = 1000.0 * 1000.0 * 1000.0; // 1 km3
const query_size = 10.0 * 10.0 * 10.0; // 10m box
if (router.route(query_size, world_size) == .gpu) {
 // Send to GPU
}

Real Problems VAR Solves (With Code)

1. Game Camera Culling

const camera_vol = frustumVolume(near, far, fov, aspect); 
if (router.route(camera_vol, world_vol) == .gpu) { 
 cull_on_gpu(); // Parallel win 
} else { 
 cull_on_cpu(); // Rare, but safe 
}
→ GPU 99% of frames. No stutter.
### 2. Explosion Damage Check
**Problem:** Explosion hits half the map. GPU stalls on memory. CPU would fly—but you route wrong → freeze.
**VAR Fix:**
```zig
const blast_vol = sphereVolume(radius); 
if (router.route(blast_vol, world_vol) == .gpu) { 
 damage_on_gpu(); // Bad idea → lag 
} else { 
 damage_on_cpu(); // Fast memory sweep 
}
→ CPU auto-picked. No freeze.
### 3. Robot Obstacle Scan
**Problem:** LiDAR sees a tiny cone. GPU perfect—but you hardcode CPU → wasted cycles.
**VAR Fix:**
```zig
const scan_vol = coneVolume(range, angle); 
const decision = router.route(scan_vol, room_vol); 
if (decision == .gpu) run_gpu_scan(); else run_cpu_scan();
→ GPU for 1000 beams/sec. Battery saved.
### 4. Map Region Query
**Problem:** User zooms out to continent. GPU chokes on data. CPU needed—but you guess wrong.
**VAR Fix:**
```zig
const region_vol = boxVolume(width, height, depth); 
if (router.route(region_vol, earth_vol) == .gpu) { 
 query_gpu(); // Wrong → OOM 
} else { 
 query_cpu(); // Fast scan 
}
→ CPU auto. App stays responsive.
---
## How It Slots In (No Magic, Just Code)
#### 1. **Frustum Culling in Your Game Engine** (e.g., Bevy or Custom Renderer)
**The Suck Without It:** You're looping 10k objects per frame on CPU for a tiny camera view—wasted cycles, GPU idle, FPS tanks from 144 to 60. Manual "if small, GPU" if-statements? Bug city when views change dynamically. 
**VAR Glow-Up:** Auto-routes based on frustum vol vs. world bounding box. GPU for 99% of frames (parallel ray tests fly), CPU fallback for edge-case mega-maps. 
```zig
// In your render loop (Bevy-style)
const world_bbox = level.get_bounding_volume(); // e.g., 1km3
const frustum_vol = frustumVolume(camera.near, camera.far, camera.fov_y, aspect); // ~0.5% selectivity

const decision = router.route(frustum_vol, world_bbox.vol);
if (decision == .gpu) {
 gpu_dispatch_cull(frustum_planes, objects); // Vulkan/Compute: 1000x rays/sec
} else {
 cpu_frustum_test(objects); // Sequential, but rare
}
// → Draw only visible. Smooth as butter.

2. Proximity Alerts in Simulation Sims (e.g., Physics or AI Pathing)

// In sim tick (e.g., custom physics loop)
const alert_vol = sphereVolume(npc.alert_radius); // e.g., 200m = 30% world
const decision = router.route(alert_vol, sim_world_vol);
if (decision == .cpu) {
 cpu_proximity_sweep(npc.pos, radius, entities); // Fast linear scan, low mem
} else {
 gpu_batch_alerts([npc_batch], radius); // Parallel distance checks
}
// → Alerts fire without hitching the sim.

3. Sensor Fusion in Robotics (e.g., ROS Nodes or Drone Nav)

// In sensor callback (ROS-style)
var sensor_vols = [_]f32{ coneVolume(lidar_range=10, angle=30), boxVolume(cam_width=5, height=4, depth=20) }; // Batch 2 sensors
var world_vols = [_]f32{ room_vol } ** 2;
var decisions: [2]Decision = undefined;
router.routeBatch(&sensor_vols, &world_vols, &decisions); // → [.gpu, .gpu] for small; scales to .cpu
for (decisions, 0..) |dec, i| {
 if (dec == .gpu) gpu_fuse_batch(sensors[i]); // CUDA/parallel: 500 Hz fusion
 else cpu_fuse_sequential(sensors[i]); // Memory-bound safe
}
// → Clean map without dropped frames.

4. Drone Swarm Collision Avoidance (e.g., Multi-Agent Simulation)

// In swarm sim loop (e.g., custom physics)
const num_drones = 1000;
var query_vols: [num_drones]f32 = undefined;
var world_vols: [num_drones]f32 = undefined;
var decisions: [num_drones]Decision = undefined;
for (0..num_drones) |i| {
 query_vols[i] = coneVolume(drones[i].sensor_range, drones[i].fov); // Small cones
 world_vols[i] = swarm_bbox.vol; // Huge swarm space
}
router.routeBatch(&query_vols, &world_vols, &decisions);
for (decisions, 0..) |dec, i| {
 if (dec == .gpu) gpu_check_collisions(drones[i]); // Parallel ray casts
 else cpu_brute_force(drones[i]); // Fallback for crowded zones
}
// → Swarm flies smooth, no crashes.

Why This Works (For Confused Devs)

How It Works (Simple Math)

if (query_size / world_size < 1%) → GPU
else → CPU

Config (Optional)

const router = VAR.init(.{
 .gpu_threshold = 0.005, // 0.5% → more GPU
 .cpu_cores = 16, // auto-adjusts
 .gpu_available = false, // force CPU
});

Safety

Performance (Real — Multiple Machines)

Try It

zig build test # tests
cd bench && ./run_bench.sh # real speed

Install

# build.zig.zon
.dependencies = .{
 .var = .{
 .url = "https://github.com/boonzy00/var/archive/v1.2.0.tar.gz",
 .hash = "1220...", // auto-filled
 },
}

// build.zig
const var_dep = b.dependency("var", .{});
exe.root_module.addImport("var", var_dep.module("var"));

What's New in v1.1