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:

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:

// 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):

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():

// 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:

// 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:

// 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:

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:

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)

# 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)

# 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)

# 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.