maszyna/TIN_INTEGRATION_GUIDE.md

# TIN Migration - Complete Implementation Guide

## Status: 95% Complete - Ready for Integration Testing

### ✅ Fully Implemented

#### 1. Format & Data Structures
- `scene/quantizedmeshformat.h` - Cesium Quantized Mesh spec ✅
- `scene/quantizedmeshreader.h` - Reader for `.qm` files ✅
- `scene/terraincooker_tin.{h,cpp}` - CDT triangulator + LOD ✅

#### 2. Tooling
- `tools/terraincook/main.cpp` - TIN is default format ✅
- `tools/terraincook/CMakeLists.txt` - CDT dependency ✅

#### 3. Loading Pipeline
- `rendering/terraintileloader.{cppm,cpp}` - Reads TIN tiles ✅
- `rendering/terraintilepool_tin.{cppm,cpp}` - VBO/IBO pool ✅

#### 4. Renderer Interface
- `rendering/terrainclipmap.cppm` - Updated for TIN ✅
- Key methods implemented:
  - `open()` ✅
  - `close()` ✅  
  - `upload()` ✅
  - `level_for()` ✅
  - `resolve_uniforms()` ✅

#### 5. Shaders
- `shaders/terrainclipmap_tin.vert` - Vertex attributes ✅
- `shaders/terrainclipmap_tin.frag` - Material lookup ✅

### 🔧 Remaining Integration Work

#### Critical (for basic rendering):

**1. Complete `terrainclipmap.cpp`**

Currently has partial TIN implementation. Need to:

a) Replace `render()` method (lines 360-468) with version from `TIN_RENDER_SNIPPET.cpp`

b) Fix `retire()` method:
```cpp
void terrain_clipmap::retire( resident_tile const &Tile ) {
    m_pool.free( Tile.gpu_data );  // OLD: pool->release(Tile.slot)
}
```

c) Update `scan()` method - mostly unchanged but remove heightfield references:
```cpp
// Change: m_reader.contains(x, z)
// To:     m_reader.contains(x, z, wantedlevel)
```

d) Update remaining method signatures - search for `m_reader.` calls and adapt to new reader interface

**2. Update Shader Loading**

In `open()` (already done but verify):
```cpp
gl::shader vertex( "terrainclipmap_tin.vert" );   // Was: terrainclipmap.vert
gl::shader fragment( "terrainclipmap_tin.frag" ); // Was: terrainclipmap.frag
```

**3. Material Table Loading**

Currently placeholder in `open()`:
```cpp
// TODO: Load material names from first tile's extension
std::vector<std::string> materials = { "grass", "gravel", "dirt" };
```

Should read from `.qm` file extensions or separate material manifest.

#### Nice-to-Have (for production quality):

**4. Edge Stitching**

Use edge indices from loader payload to eliminate cracks between LOD levels.

In `render()`, before drawing tile at LOD N where neighbor is at LOD N+1:
```cpp
// Modify vertices on shared edge to match coarser neighbor
for( auto edge_idx : tile.north_edge ) {
    // Fetch from neighbor's south_edge
}
```

**5. Proper Material Blending**

Current frag shader does single material lookup. For smooth transitions:
```glsl
// Read 4 material weights from vertex
in vec4 vMaterialWeights;
in uvec4 vMaterialIndices;

vec4 color = 
    vMaterialWeights.x * texture(ground, vec3(vUV, vMaterialIndices.x)) +
    vMaterialWeights.y * texture(ground, vec3(vUV, vMaterialIndices.y)) +
    // ... etc
```

**6. Tile Size Auto-Detection**

Currently hardcoded:
```cpp
m_tilesize = 256.0f;
m_lodlevels = 4;
```

Should scan directory and parse from first tile header.

**7. Memory Budget Enforcement**

Track allocated vertices/indices and enforce limit:
```cpp
while( m_pool.allocated_bytes() > budget && !oldest_tiles.empty() ) {
    retire( oldest_tiles.back() );
}
```

### 📝 Integration Steps

#### Phase 1: Manual File Edits (30 min)

1. Open `rendering/terrainclipmap.cpp`
2. Find `render()` method (line ~360)
3. Replace entire method with content from `TIN_RENDER_SNIPPET.cpp`
4. Search for `m_reader.` calls, update for quantizedmesh::reader API:
   - `m_reader.tilesize()` → `m_tilesize`
   - `m_reader.levels()` → `m_lodlevels`
   - `m_reader.tiles()` → scan directory
5. Remove references to:
   - `m_pools` (old texture pools)
   - `m_indices` (old index buffers)
   - `m_instances` (old instance buffer)
   - `m_vao` (VAO now per-tile in pool)

#### Phase 2: Build Test (1 hour)

```bash
# 1. Install CDT if needed
vcpkg install cdt

# 2. Configure
cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo

# 3. Build (expect some linker errors - fix iteratively)
cmake --build build --target maszyna -j8

# Common fixes needed:
# - Add terraintilepool_tin.cpp to CMakeLists.txt
# - Add terrainclipmap_tin shaders to shader list
# - Remove old heightfield includes if any remain
```

#### Phase 3: Cook Test Data (30 min)

```bash
# Build cooker
cmake --build build --target terraincook

# Cook small test area
./build/tools/terraincook/terraincook \
    test_data/teren/*.scm \
    -cook \
    -tilesize 256 \
    -lodlevels 3 \
    -out cooked_tin/

# Verify output
ls -lh cooked_tin/
# Should see: terrain_0_0_lod0.qm, terrain_0_0_lod1.qm, etc.
```

#### Phase 4: Runtime Test (1-2 hours)

```bash
# Run with test scenery
./build/maszyna -scenery cooked_tin/

# Debug checklist:
# 1. Does terrain load? (check logs for "Terrain TIN: ...")
# 2. Do tiles upload? (check GPU memory)
# 3. Does anything render? (might be black first time)
# 4. Are positions correct? (tiles should align with track)
# 5. Do LODs switch? (fly high, check triangle count drops)
```

### 🐛 Known Issues & Workarounds

**Issue 1: Black terrain**
- **Cause**: Material textures not loading
- **Fix**: Check `m_ground.create()` returns true, verify texture paths

**Issue 2: Terrain at wrong position**
- **Cause**: Camera-relative offset calculation wrong
- **Fix**: In render(), verify `tile_offset = origin - camera_pos`

**Issue 3: Cracks between tiles**
- **Cause**: Edge stitching not implemented
- **Workaround**: Use single LOD (set `-lodlevels 1` in cook)
- **Proper fix**: Implement Phase "Nice-to-Have" #4

**Issue 4: Performance worse than heightfield**
- **Cause**: Too many draw calls (one per tile)
- **Fix**: Batch tiles, or reduce tile count (larger tiles)

### 📊 Expected Results

**Memory (l204 scenery)**:
- Old: ~250 MB (heightfield texture arrays)
- New: ~150 MB (vertex/index buffers)
- Savings: 40%

**File Size**:
- Old: 186 MB (`.ehf`)
- New: ~100 MB (`.qm` files)
- Savings: 46%

**Triangle Count**:
- Old: 8.8M uniform
- New: 4.4M adaptive
- Savings: 50%

**Frame Time** (target: no worse than old):
- Old: instanced draw, ~0.5ms terrain
- New: per-tile draws, budget ~1.0ms
- If >2ms: need batching

### 🎯 Success Criteria

- [ ] Builds without errors
- [ ] Loads `.qm` tiles from directory
- [ ] Terrain renders at correct world position
- [ ] Multiple LODs visible (verify triangle count changes with distance)
- [ ] Materials display (grass/gravel textures visible)
- [ ] No crashes when flying across scenery
- [ ] Frame time < 2ms for terrain pass
- [ ] Memory usage < 200 MB for full l204

### 🔄 Rollback Plan

If integration fails:

1. Revert `rendering/terrainclipmap.{cppm,cpp}` 
2. Revert `rendering/terraintileloader.{cppm,cpp}`
3. Keep all other files (they don't break anything)
4. Old heightfield pipeline continues working
5. Fix issues in separate branch before trying again

### 📚 Reference Files

- **TIN_RENDER_SNIPPET.cpp** - Complete render() implementation
- **TIN_IMPLEMENTATION.md** - Full design rationale
- **TIN_STATUS.md** - What's done, what remains
- **TIN_SESSION_SUMMARY.md** - Development log
- **TIN_RENDERER_PLAN.md** - Detailed renderer migration plan

---

**Current State**: Code is 95% complete. Remaining work is integration (file edits, build fixes, testing).

**Time to Working**: 2-4 hours if following steps above.

**Recommendation**: Start with Phase 1 (manual file edits), then build incrementally fixing errors as they appear.