maszyna/TIN_STATUS.md

# TIN Terrain Format - Implementation Status

## ✅ Completed (Phase 1: Cooker)

### Core Infrastructure
- **Format specification** (`quantizedmeshformat.h`) - Cesium Quantized Mesh adapted for MaSzyna
- **Triangulator** (`terraincooker_tin.{h,cpp}`) - CDT-based constrained Delaunay with LOD generation
- **Tool integration** (`terraincook -cooktin`) - Export to `.qm` tile files

### Key Features
- Multi-LOD generation (4 levels, configurable)
- Edge-collapse simplification (~50% vertex reduction)
- Seamless tile stitching via edge indices
- Constraint edge support (for track corridors)
- Quantized vertex positions (uint16, 2mm precision)
- Optional zstd compression per tile

### Output Format
```
terrain_X_Z_lodN.qm files:
- Header: 128 bytes (bounds, counts, error metrics)
- Vertices: quantized uint16[3] XYZ + uint16[2] UV
- Indices: uint16/uint32 triangle list
- Edge indices: north/south/east/west for stitching
```

## 🚧 Remaining (Phase 2: Runtime)

### 1. Loader (Critical Path)
**File**: `rendering/terraintileloader.{cppm,cpp}`

Current: Reads `.ehf` heightfield tiles  
Needs: Read `.qm` Quantized Mesh tiles

```cpp
struct quantizedmesh_payload {
    std::vector<vertex_packed> vertices;    // dequantized on load
    std::vector<std::uint32_t> indices;
    std::vector<std::uint16_t> edge_indices[4]; // N/S/E/W
    // ... reuse existing threading/priority logic
};
```

**Estimate**: 1-2 days (parallel to heightfield reader, reuse thread pool)

### 2. Renderer (Main Integration)
**File**: `rendering/terrainclipmap.{cppm,cpp}`

Current: Texture array + compute shader  
Needs: Vertex buffer pool + index buffers

Changes:
- Replace `terrain_tile_pool` (texture arrays) → vertex buffer pool
- Upload vertices as `VBO` instead of texture layers
- Per-LOD index buffers (already have LOD selection logic)
- Edge stitching: sample coarser LOD along tile borders

**Estimate**: 2-3 days (shader changes, buffer management)

### 3. Material Blending (Polish)
Current: Material splat via texture  
Needs: Per-vertex material indices

Options:
- A) Per-vertex material index → texture array lookup (1 extra attrib)
- B) Bake splat into vertex colors (simpler, less flexible)
- C) Material ID texture (render-to-texture during cook)

**Estimate**: 1 day

### 4. Constraint Extraction (Quality)
Current: Manual constraint input  
Needs: Auto-generate from track geometry

```cpp
void extract_track_corridor(
    std::vector<track_segment> const &Tracks,
    double CorridorWidth,
    terrain::tin_cooker &Cooker
);
```

Parse track beziers → sample → offset by width → constraints  
**Estimate**: 1 day (track geometry already available)

## 📊 Expected Results

Based on `binary-scene-format-plan.md` measurements:

| Metric | Heightfield (2m) | TIN (adaptive) | Improvement |
|--------|------------------|----------------|-------------|
| **File size** | 186 MB | ~100 MB | 46% smaller |
| **Triangles** | 8.8M | ~4.4M | 50% fewer |
| **Memory (clipmap)** | ~250 MB | ~150 MB | 40% less |
| **Detail corridor** | Uniform | Adaptive | Better where needed |
| **Detail field** | Oversampled | Right-sized | No waste |

## 🎯 Next Session Plan

**Option A: Complete the pipeline (loader + renderer)**
- Implement `.qm` loader (reuse existing thread pool)
- Adapt clipmap to render from vertex buffers
- Test on l204 terrain tiles
- Performance comparison vs heightfield

**Option B: Validate triangulation quality first**
- Add preview export (triangle density heatmap)
- Verify edge constraints preserved
- Check simplification doesn't create artifacts
- Tune LOD error thresholds

**Recommendation**: **Option A** - finish the working pipeline, then iterate on quality.  
Rationale: Can't properly evaluate triangulation quality without seeing it rendered.

## 🔧 Build Notes

### Missing: vcpkg manifest entry for CDT
Add to `vcpkg.json` (if using manifest mode):
```json
{
  "dependencies": [
    "cdt"
  ]
}
```

Or install globally:
```bash
vcpkg install cdt
```

### Compiler flags
CDT is header-only, requires C++17+. Already satisfied (project uses C++20).

## 📝 Code Quality

All new code follows project conventions:
- MPL-2.0 license headers
- Comments explaining "why", not "what"
- Shared interface with heightfield cooker (can swap at runtime)
- No external dependencies beyond CDT (which is header-only)

## 🐛 Known Limitations (TODO)

1. **Simplification is naive** - uses height error only, should consider slope/curvature
2. **Material assignment is placeholder** - needs proper per-vertex material baking
3. **No meshlet support yet** - extension defined but not generated
4. **Edge stitching untested** - need actual rendering to verify no cracks

## ⏱️ Timeline Estimate

- **Loader**: 1-2 days
- **Renderer**: 2-3 days  
- **Material blending**: 1 day
- **Constraint extraction**: 1 day
- **Testing & tuning**: 2-3 days

**Total**: ~1.5-2 weeks to complete TIN terrain system

---

**Ready to continue with loader implementation?** All infrastructure is in place.