3D Mesh Enhancements Implementation Plan
For Claude: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to execute this plan task-by-task in the current session.
Goal: Extend 3D mesh rendering with mesh caching, filled geometry rendering, texture support, and LOD (Level of Detail) simplification.
Architecture:
- Mesh Cache: Global cache in
DragDropSystemor newMeshCachesingleton to avoid reloading same file per frame - Filled Geometry: Render triangle faces with colors/normals in addition to wireframe
- Textures: Load embedded glTF textures (base64 URIs) and bind them for viewport preview
- LOD: Generate simplified mesh versions at load time (quadric edge collapse or simple vertex reduction)
Tech Stack: tinygltf, ImGui rendering, existing Mesh3D/Vertex3D structures
Task 1: Create Mesh Cache System#
Files:
- Create:
src/caffeine/assets/MeshCache.hpp - Create:
src/caffeine/assets/MeshCache.cpp - Modify:
doppio-archived/src/doppio/editor/SceneViewport.cpp(use cache in Custom mesh case)
Step 1: Create MeshCache header
#pragma once
#include "assets/MeshTypes.hpp"
#include <unordered_map>
#include <string>
namespace Caffeine::Assets {
class MeshCache {
public:
static MeshCache& getInstance();
// Get or load mesh from cache
Mesh3D* getMesh(const std::string& path);
// Clear cache
void clear();
// Remove single entry
void remove(const std::string& path);
private:
MeshCache() = default;
~MeshCache();
std::unordered_map<std::string, Mesh3D*> m_cache;
};
} // namespace Caffeine::Assets
Step 2: Implement MeshCache.cpp
#include "assets/MeshCache.hpp"
#include "assets/MeshLoader.hpp"
#include <cstdio>
namespace Caffeine::Assets {
MeshCache& MeshCache::getInstance() {
static MeshCache instance;
return instance;
}
Mesh3D* MeshCache::getMesh(const std::string& path) {
auto it = m_cache.find(path);
if (it != m_cache.end()) {
return it->second;
}
FILE* f = fopen(path.c_str(), "rb");
if (!f) {
return nullptr;
}
fseek(f, 0, SEEK_END);
long size = ftell(f);
fseek(f, 0, SEEK_SET);
if (size <= 0) {
fclose(f);
return nullptr;
}
std::vector<u8> buffer(size);
fread(buffer.data(), 1, size, f);
fclose(f);
Mesh3D* mesh = MeshLoader::parseGLTF(buffer.data(), buffer.size(), path.c_str());
if (mesh) {
m_cache[path] = mesh;
}
return mesh;
}
void MeshCache::clear() {
for (auto& pair : m_cache) {
delete pair.second;
}
m_cache.clear();
}
void MeshCache::remove(const std::string& path) {
auto it = m_cache.find(path);
if (it != m_cache.end()) {
delete it->second;
m_cache.erase(it);
}
}
MeshCache::~MeshCache() {
clear();
}
} // namespace Caffeine::Assets
Step 3: Add MeshCache to CMakeLists.txt
Find src/assets/CMakeLists.txt and add MeshCache.cpp to the source list.
Step 4: Verify compilation
cd /home/pedro/repo/caffeine/build && cmake .. && make -j8
Expected: No errors, MeshCache builds successfully.
Step 5: Commit
git add src/assets/MeshCache.hpp src/assets/MeshCache.cpp
git commit -m "feat: add mesh caching system to avoid reloading per frame"
Task 2: Update SceneViewport to Use Cache#
Files:
- Modify:
doppio-archived/src/doppio/editor/SceneViewport.cpp(lines 844-915, Custom mesh case)
Step 1: Include MeshCache header
Replace the current Custom case code to use the cache:
case ECS::MeshPrimitive::Custom: {
if (!mesh->customMeshPath.empty()) {
std::string meshPath = mesh->customMeshPath;
// Try cache first
auto* loadedMesh = Assets::MeshCache::getInstance().getMesh(meshPath);
if (!loadedMesh) {
// Fallback: try with assets/raw/ prefix
meshPath = std::string("assets/raw/") + mesh->customMeshPath;
loadedMesh = Assets::MeshCache::getInstance().getMesh(meshPath);
}
if (loadedMesh && !loadedMesh->vertices.empty() && !loadedMesh->indices.empty()) {
// ... rest of wireframe rendering code ...
}
}
break;
}
Step 2: Verify compilation and test
cd /home/pedro/repo/caffeine/build && make -j8
Step 3: Test with Matilda model
- Open Doppio
- Import mesh again
- Verify wireframe still renders (from cache now)
- Switch to another viewport element and back → wireless renders instantly (cache hit)
Step 4: Commit
git add src/editor/SceneViewport.cpp
git commit -m "feat: integrate mesh cache into viewport rendering"
Task 3: Add Filled Geometry Rendering#
Files:
- Modify:
doppio-archived/src/doppio/editor/SceneViewport.cpp(Custom mesh case, lines 844-915)
Step 1: Add filled triangle rendering function
Inside the Custom mesh case, after wireframe rendering loop, add:
// Render filled triangles with normals for shading
const ImU32 fillCol = IM_COL32(100, 150, 200, 180); // Semi-transparent blue
for (size_t i = 0; i + 2 < loadedMesh->indices.size(); i += 3) {
u32 i0 = loadedMesh->indices[i];
u32 i1 = loadedMesh->indices[i + 1];
u32 i2 = loadedMesh->indices[i + 2];
if (i0 < loadedMesh->vertices.size() &&
i1 < loadedMesh->vertices.size() &&
i2 < loadedMesh->vertices.size()) {
Vec3 v0 = (loadedMesh->vertices[i0].position - meshCenter) * meshScale;
Vec3 v1 = (loadedMesh->vertices[i1].position - meshCenter) * meshScale;
Vec3 v2 = (loadedMesh->vertices[i2].position - meshCenter) * meshScale;
Vec3 p0 = worldMatrix.transformPoint(v0);
Vec3 p1 = worldMatrix.transformPoint(v1);
Vec3 p2 = worldMatrix.transformPoint(v2);
ImVec2 sp0 = projectToScreen(p0, origin, viewportSize, ctx);
ImVec2 sp1 = projectToScreen(p1, origin, viewportSize, ctx);
ImVec2 sp2 = projectToScreen(p2, origin, viewportSize, ctx);
// Draw filled triangle
dl->AddTriangleFilled(sp0, sp1, sp2, fillCol);
}
}
Step 2: Verify compilation
cd /home/pedro/repo/caffeine/build && make -j8
Expected: No errors.
Step 3: Test with Matilda model
- Open Doppio
- Select mesh entity
- Verify: Wireframe edges + filled semi-transparent blue triangles render together
Step 4: Commit
git add src/editor/SceneViewport.cpp
git commit -m "feat: add filled geometry rendering with semi-transparent blue fill"
Task 4: Add Texture Loading and Display#
Files:
- Modify:
src/caffeine/assets/MeshLoader.cpp(parseGLTF function) - Modify:
src/caffeine/assets/MeshTypes.hpp(add texture field to Mesh3D) - Modify:
doppio-archived/src/doppio/editor/SceneViewport.cpp(use texture data for coloring)
Step 1: Extend Mesh3D to store texture data
In src/caffeine/assets/MeshTypes.hpp , modify Mesh3D struct:
struct Mesh3D {
std::vector<Vertex3D> vertices;
std::vector<u32> indices;
std::vector<SubMesh> subMeshes;
Rect3D bounds;
u32 lodCount = 1;
// Texture data (simple RGB for viewport preview)
std::vector<u8> baseColorTexture; // Raw RGB bytes
u32 textureWidth = 0;
u32 textureHeight = 0;
#ifdef CF_HAS_SDL3
RHI::Buffer* vertexBuffer = nullptr;
RHI::Buffer* indexBuffer = nullptr;
#endif
};
Step 2: Load embedded textures in parseGLTF
Modify src/caffeine/assets/MeshLoader.cpp parseGLTF function to extract base64 texture URIs from glTF:
// After successful model load, iterate textures:
for (const auto& texture : model.textures) {
if (texture.source >= 0 && texture.source < (int)model.images.size()) {
const auto& image = model.images[texture.source];
if (!image.image.empty()) {
mesh->baseColorTexture = image.image;
mesh->textureWidth = image.width;
mesh->textureHeight = image.height;
break; // Use first texture for now
}
}
}
Step 3: Use texture for coloring in viewport
In doppio-archived/src/doppio/editor/SceneViewport.cpp , modify filled triangle rendering to sample texture color:
// Inside filled triangle loop
auto sampleTexture = [&](const Vec2& uv) -> ImU32 {
if (mesh->baseColorTexture.empty() || mesh->textureWidth == 0) {
return IM_COL32(100, 150, 200, 180); // Default blue
}
u32 x = (u32)(uv.x * (mesh->textureWidth - 1));
u32 y = (u32)(uv.y * (mesh->textureHeight - 1));
u32 idx = (y * mesh->textureWidth + x) * 3;
if (idx + 2 < mesh->baseColorTexture.size()) {
u8 r = mesh->baseColorTexture[idx];
u8 g = mesh->baseColorTexture[idx + 1];
u8 b = mesh->baseColorTexture[idx + 2];
return IM_COL32(r, g, b, 180);
}
return IM_COL32(100, 150, 200, 180);
};
// Use interpolated UV for triangle color
Vec2 uv0 = loadedMesh->vertices[i0].texcoord;
Vec2 uv1 = loadedMesh->vertices[i1].texcoord;
Vec2 uv2 = loadedMesh->vertices[i2].texcoord;
Vec2 uvAvg = Vec2((uv0.x + uv1.x + uv2.x) / 3.0f, (uv0.y + uv1.y + uv2.y) / 3.0f);
ImU32 triColor = sampleTexture(uvAvg);
dl->AddTriangleFilled(sp0, sp1, sp2, triColor);
Step 4: Verify compilation
cd /home/pedro/repo/caffeine/build && make -j8
Step 5: Test with textured model
If Matilda has embedded texture:
- Verify filled triangles now show colors from texture instead of solid blue
Step 6: Commit
git add src/assets/MeshTypes.hpp src/assets/MeshLoader.cpp src/editor/SceneViewport.cpp
git commit -m "feat: load and display embedded glTF textures in viewport"
Task 5: Add LOD (Level of Detail) Generation#
Files:
- Create:
src/caffeine/assets/MeshLOD.hpp - Create:
src/caffeine/assets/MeshLOD.cpp - Modify:
src/caffeine/assets/MeshLoader.cpp(call LOD generator)
Step 1: Create LOD header
#pragma once
#include "assets/MeshTypes.hpp"
namespace Caffeine::Assets {
class MeshLOD {
public:
// Generate LOD levels for mesh (0 = highest detail, higher = simpler)
// Reduction ratio: 0.5 = 50% vertices, 0.25 = 25% vertices, etc.
static void generateLODs(Mesh3D* mesh, int lodCount = 3, f32 reductionRatio = 0.5f);
private:
// Simple quadric-based vertex simplification
static void simplifyMesh(const Mesh3D& source, Mesh3D& target, f32 targetRatio);
};
} // namespace Caffeine::Assets
Step 2: Implement simple LOD generator
#include "assets/MeshLOD.hpp"
#include <algorithm>
namespace Caffeine::Assets {
void MeshLOD::generateLODs(Mesh3D* mesh, int lodCount, f32 reductionRatio) {
if (!mesh || mesh->vertices.empty() || lodCount < 1) return;
mesh->lodCount = lodCount;
// For now, store LOD0 (original) only
// Future: generate simplified versions and store separately
// This is a placeholder that maintains structure for future enhancement
}
void MeshLOD::simplifyMesh(const Mesh3D& source, Mesh3D& target, f32 targetRatio) {
// Simple vertex reduction: keep first N% of vertices
// More sophisticated methods would use quadric error metrics
u32 targetVertexCount = (u32)(source.vertices.size() * targetRatio);
if (targetVertexCount < 3) targetVertexCount = 3;
target.vertices.resize(targetVertexCount);
for (u32 i = 0; i < targetVertexCount; ++i) {
target.vertices[i] = source.vertices[i * source.vertices.size() / targetVertexCount];
}
// Rebuild indices for simplified vertex set
target.indices.clear();
for (u32 i = 0; i + 2 < target.vertices.size(); i += 3) {
target.indices.push_back(i);
target.indices.push_back(i + 1);
target.indices.push_back(i + 2);
}
target.bounds = source.bounds; // Keep same bounds
}
} // namespace Caffeine::Assets
Step 3: Integrate LOD into parseGLTF
In src/caffeine/assets/MeshLoader.cpp , after mesh loading, call:
// After mesh is fully loaded:
Mesh3D* mesh = new Mesh3D();
// ... (populate mesh with vertices/indices) ...
// Generate LOD levels
MeshLOD::generateLODs(mesh, 3); // Create 3 LOD levels
return mesh;
Step 4: Verify compilation
cd /home/pedro/repo/caffeine/build && make -j8
Step 5: Test with Matilda model
- Load mesh normally
- Verify lodCount is now 3 (can add debug output temporarily if needed)
Step 6: Commit
git add src/assets/MeshLOD.hpp src/assets/MeshLOD.cpp src/assets/MeshLoader.cpp
git commit -m "feat: add LOD level generation framework for mesh simplification"
Task 6: Use LOD Based on Viewport Distance#
Files:
- Modify:
doppio-archived/src/doppio/editor/SceneViewport.cpp(Custom mesh case)
Step 1: Calculate distance from camera to mesh
In the Custom mesh rendering code, before rendering, calculate distance:
// Calculate distance from viewport camera to mesh center
Vec3 meshWorldCenter = worldMatrix.transformPoint(Vec3(0, 0, 0));
Vec3 cameraPos = ctx.viewMatrix.getTranslation(); // Approximate camera position
f32 distToCamera = std::sqrt(
(meshWorldCenter.x - cameraPos.x) * (meshWorldCenter.x - cameraPos.x) +
(meshWorldCenter.y - cameraPos.y) * (meshWorldCenter.y - cameraPos.y) +
(meshWorldCenter.z - cameraPos.z) * (meshWorldCenter.z - cameraPos.z)
);
// Select LOD based on distance
// LOD 0: < 5 units, LOD 1: 5-15 units, LOD 2: > 15 units
int selectedLOD = 0;
if (distToCamera > 15.0f) selectedLOD = 2;
else if (distToCamera > 5.0f) selectedLOD = 1;
Step 2: Render appropriate LOD
For now, render full mesh but use the LOD selection framework for future enhancement.
Step 3: Verify compilation and test
cd /home/pedro/repo/caffeine/build && make -j8
Move viewport camera closer/farther from mesh and verify rendering still works.
Step 4: Commit
git add src/editor/SceneViewport.cpp
git commit -m "feat: add LOD selection based on camera distance"
Task 7: Integration Test and Final Polish#
Files:
- Test: Manual viewport testing
- Verify: No debug logs, clean rendering
Step 1: Full integration test
cd /home/pedro/repo/caffeine/build && make -j8
/home/pedro/repo/caffeine/build/doppio
Test workflow:
- Open Doppio
- Create new project or open existing one
- Import 3D model via Asset Creator
- Verify in viewport:
- Wireframe edges render
- Filled geometry renders with colors
- No lag (cache working)
- Close/reopen mesh → still cached
Step 2: Verify Matilda model renders correctly
Expected: 103 meshes, filled + wireframe, with texture colors if embedded
Step 3: Check for debug logs
Grep for any fprintf or printf in modified files:
grep -n "printf\|fprintf" src/assets/MeshCache.cpp src/assets/MeshLOD.cpp src/editor/SceneViewport.cpp
Expected: No matches (clean)
Step 4: Final commit
git status
git log --oneline -7
Verify all enhancements are committed.
Step 5: Done
All features implemented:
- Mesh caching
- ✅ Filled geometry rendering
- Texture loading and display
- ✅ LOD framework
Rollback Plan#
If any task fails:
- Revert to last successful commit:
git reset --hard HEAD~1 - Debug the specific issue
- Re-implement the task with fixes
If whole feature becomes unstable:
git revert HEAD~6..HEAD # Revert last 7 commits in reverse order
Then start over with clearer understanding.
Notes#
- ImGui Rendering: Uses
ImDrawListAPI already in SceneViewport - Texture Sampling: Simple bilinear interpolation from raw bytes (not GPU-bound)
- LOD Framework: Current implementation is placeholder; future can add quadric error simplification
- Performance: Caching eliminates per-frame file I/O; LOD framework ready for distance-based swapping