Session 2026-09-22 — Phong GPU, Handles and Shadows
Historical
Last updated:
Branch: feature/editor-plugin-sdk
Objective: advance P0 pillars (rendering Phong + handles) and P1 tasks (point GPU shadows, normal maps on the ground).
Build verificado: caffeine-core , caffeine-runtime , doppio compilam com sucesso.
Resumo executivo#
| Prioridade |
Item |
Estado |
| P0 |
Remover fallback CPU shadows no editor ( SceneViewport ) |
✅ |
| P0 |
Inspector UI para customNormalPath e shininess (mesh + terreno) |
✅ |
| P1 |
Point light shadows GPU |
✅ |
| P1 |
Terreno com normal maps em terrain_lit.frag |
✅ |
| P0 |
Asset handles com generation + LRU + invalidation callbacks |
✅ |
1. Asset handles (Pilar 6)#
O que mudou#
AssetHandle<T> passou a guardar { id, generation } . get() devolve nullptr If the generation doesn't match.
LoadStatus::Invalid quando o slot foi invalidado (LRU ou GC).
- Hot-reload (
clearEntryData ): recharges payload ** without** increasing generation — active handsles remain valid.
- Invalidation (
invalidateEntry ): increase generation, clean payload, notify callbacks.
- LRU eviction: quando
m_cachedBytes > m_maxCacheBytes , removes unreferenced entries in order lastAccessFrame .
registerInvalidationCallback / unregisterInvalidationCallback to release GPU features when an asset is evicted.
CacheStats::evictedCount para telemetria.
Ficheiros#
src/caffeine/assets/AssetHandle.hpp , AssetTypes.hpp , AssetManager.{hpp,cpp}
tests/test_assetmanager.cpp — generation tests, LRU, callbacks
Documentation#
2. Rendering Phong + sombras GPU (Pilar 1)#
Meshes ( scene_lit.* )#
- Shader Phong: ambient + diffuse + specular com
shininess .
- Normal mapping via TBN (
scene_lit.vert exporta tangent/bitangent).
- Tangentes calculadas em
MeshLoader::computeMeshTangents() para OBJ e glTF.
MeshFilterComponent : customNormalPath , shininess (default 32).
- Directional shadows: depth pass + PCF 3×3 in fragment shadow.
- Pointy shadows: up to 2 lights, cubemap Depth (
GpuPointShadowMap ), sample no scene_lit.frag .
Terreno ( terrain_lit.frag )#
- Mesmo modelo Phong que meshes.
- Normal map triplanar via
uNormalMap (sampler slot 5).
TerrainComponent : normalMapPath , shininess (default 16).
TerrainGpuTextureCache carrega e invalida normalMap em sync com texturePath .
- Shadows: directional (slots 6–7) + point (slots 8–9).
castShadows / receiveShadows respeitados no gather GPU.
Editor viewport#
- Com GPU 3D texturizado activo,
gatherSceneLighting(..., buildCpuShadowMaps = false) .
drawSceneMeshesForCamera usa collectSceneLights only — no CPU shadow maps.
- CPU raster remains for wireless/debug and empty entities when GPU is not active.
Inspector + serialization#
| Componente |
Campos novos |
Blob |
MeshFilterComponent |
Normal Map, Shininess |
append after customMaterialPath |
TerrainComponent |
Normal Map, Shininess |
blob version 10 |
Ficheiros principais#
src/caffeine/render/GpuSceneRenderer.cpp , GpuPointShadowMap.{hpp,cpp}
src/caffeine/render/shaders/scene_lit.vert / .frag , terrain_lit.frag
src/scene/LightingSystem.{hpp,cpp}
doppio-archived/src/doppio/editor/SceneViewport.cpp , InspectorPanel.cpp , SceneSerializer.cpp
src/caffeine/terrain/TerrainGpuTextures.cpp , src/caffeine/ecs/TerrainComponents.hpp
Documentation#
3. Continuation (same branch)#
| Item |
Estado |
| Runtime GPU shadows |
✅ RuntimeSceneRenderer integra GpuSceneRenderer |
| CSM 4 cascatas (luz dir 0) |
✅ atlas 1024², splits práticos |
| Spot shadows GPU (2 luzes) |
✅ GpuSpotShadowMap + loop spot nos shaders |
test_scenemanager.cpp |
✅ usa Transform / Acceleration2D ; compila |
| ECS components missing in the tests |
✅ Position2D , Velocity2D , Scale2D , Rotation , Health |
4. Next suggested steps#
- PCSS / bark blending — visual quality of shadows.
- PBR — metallic/roughness on the base Phong.
- Full suite — other tests (
test_cap_loader , editor integration) still with pre-existing errors.
Links#