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

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

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

{
  "dependencies": [
    "cdt"
  ]
}

Or install globally:

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.