🗿 Mesh Loading
Importação de OBJ e glTF para Mesh3D: geometria, tangentes,
normais suaves, materiais glTF por superfÃcie e modos alpha, mais o caminho de upload GPU.
Visão Geral#
Carregamento de malhas 3D nos formatos .obj e .gltf, convertendo para o formato interno .caf (Mesh). Os shaders são fontes GLSL compiladas para SPIR-V pelo Render::ShaderCompiler.
Normal mapping: após import, computeMeshTangents() preenche Vertex3D::tangent (vec4 com handedness em .w). O editor liga normal maps via MeshFilterComponent::customNormalPath no passe forward PBR materials-phong.md.
Smooth shading: meshes importadas sem normais recebem computeSmoothNormals() em MeshLoader.cpp. Primitivas GPU procedurais (GpuProceduralMeshes.cpp) usam normais analÃticas — não chamar computeSmoothNormals() nelas (evita costuras em esfera/torus/cápsula). Ver plans/2026-09-22-viewport-rendering-quality-session.md.
Modos alpha: o importador lê alphaMode (OPAQUE, MASK, BLEND) e alphaCutoff do glTF para MeshSurfaceMaterial; o renderer aplica-os por submesh, permitindo misturar materiais opacos e cutout na mesma mesh.
API Implementada#
namespace Caffeine::Assets {
struct Color {
f32 r, g, b, a = 1.0f;
static Color white();
static Color black();
};
struct Rect3D {
Vec3 min, max;
Vec3 center() const;
Vec3 extents() const;
};
struct Vertex3D {
Vec3 position;
Vec3 normal;
Vec2 texcoord;
Vec4 tangent;
};
struct SubMesh {
u32 indexOffset = 0;
u32 indexCount = 0;
u32 materialIndex = 0;
FixedString<64> name;
};
struct Mesh3D {
std::vector<Vertex3D> vertices;
std::vector<VertexSkin> skin; // paralelo a vertices quando skinned
std::vector<u32> indices;
std::vector<SubMesh> subMeshes;
std::vector<MeshSurfaceMaterial> materials; // dados glTF por superfÃcie
Rect3D bounds;
u32 lodCount = 1;
u32 geometryRevision = 1;
u32 uploadedRevision = 0;
bool flipTextureV = true; // OBJ V-up vs glTF V-down
#ifdef CF_HAS_SDL3
RHI::Buffer* vertexBuffer = nullptr;
RHI::Buffer* indexBuffer = nullptr;
#endif
};
struct Material3D {
FixedString<64> name;
Color albedoColor = Color::white();
f32 roughness = 0.5f;
f32 metallic = 0.0f;
#ifdef CF_HAS_SDL3
RHI::Texture* albedoTexture = nullptr;
RHI::Texture* normalTexture = nullptr;
RHI::Texture* roughnessTexture = nullptr;
RHI::Shader* shader = nullptr;
#endif
};
struct MeshRenderer {
FixedString<128> meshPath;
Mesh3D* mesh = nullptr;
Material3D* material = nullptr;
bool castShadows = true;
bool receiveShadows = true;
};
class MeshLoader {
public:
MeshLoader() = default;
#ifdef CF_HAS_SDL3
explicit MeshLoader(RHI::RenderDevice* device);
#endif
static Mesh3D* fromMemory(const Vertex3D* verts, u32 vertCount,
const u32* indices, u32 indexCount);
static Mesh3D* parseOBJ(const char* src, usize srcLen);
Mesh3D* loadOBJ(const char* path);
#ifdef CF_HAS_SDL3
void uploadToGPU(Mesh3D* mesh);
#endif
};
class MeshSystem : public ECS::ISystem {
public:
void onUpdate(ECS::World& world, f32 dt) override;
};
} // namespace Caffeine::Assets
namespace Caffeine::ECS {
struct Position3D { Vec3 position; };
struct Rotation3D { Vec4 quaternion = Vec4(0.0f, 0.0f, 0.0f, 1.0f); };
struct Scale3D { Vec3 scale = Vec3(1.0f, 1.0f, 1.0f); };
} // namespace Caffeine::ECS
Compilação de shaders#
namespace Caffeine::Render {
struct CompiledShader {
std::vector<u8> bytecode;
std::string errorLog;
bool success = false;
};
class ShaderCompiler {
public:
// Fonte GLSL → SPIR-V para o stage pedido.
CompiledShader compileGlsl(const std::string& source, RHI::ShaderStage stage,
const char* entryPoint = "main");
CompiledShader compileCached(const std::string& source, RHI::ShaderStage stage,
const char* entryPoint = "main");
void clearCache();
};
} // namespace Caffeine::Render
Os shaders internos estão listados em BuiltinShader (render/ShaderBytecode.hpp) e são
criados por createBuiltinShader; os pipelines são construÃdos com
RenderDevice::createGraphicsPipeline(vs, fs, desc).
Componentes ECS (editor / runtime)#
namespace Caffeine::ECS {
struct MeshFilterComponent {
MeshPrimitive primitive = MeshPrimitive::Cube;
std::string customMeshPath;
std::string customTexturePath;
std::string customNormalPath; // normal map (relativo ao projeto)
std::string customMaterialPath;
f32 shininess = 32.0f; // expoente especular Phong
};
struct MeshRendererComponent {
std::string meshPath;
std::string materialPath;
bool castShadows = true;
bool receiveShadows = true;
};
} // namespace Caffeine::ECS
Inspector: campos Albedo Texture, Normal Map e Shininess em MeshFilterComponent. Serialização em SceneSerializer (blob após customMaterialPath).
Exemplos de Uso#
// ── Carregar mesh OBJ ─────────────────────────────────────────
Caffeine::Assets::MeshLoader meshLoader;
Mesh3D* mesh = meshLoader.loadOBJ("models/player.obj");
// ── Criar entidade 3D ─────────────────────────────────────────
Entity player3D = world.create();
world.add<Position3D>(player3D, {Vec3(0.0f, 0.0f, 0.0f)});
world.add<Rotation3D>(player3D);
world.add<Scale3D>(player3D, {Vec3(1.0f, 1.0f, 1.0f)});
world.add<MeshRenderer>(player3D, MeshRenderer{});
// ── Sistema de renderização ───────────────────────────────────
MeshSystem meshSystem;
meshSystem.onUpdate(world, 0.016f);
Critério de Aceitação#
- [x] Vertex3D struct definido (position, normal, texcoord, tangent vec4)
- [x]
computeMeshTangents()após import OBJ/glTF - [x] Normal map + shininess em
MeshFilterComponent(GPU Phong) - [x] Mesh3D struct com vertices, indices, subMeshes, bounds
- [x] MeshLoader::fromMemory cria mesh de vértices e Ãndices
- [x] MeshLoader::parseOBJ lê formato .obj (v, vt, vn, f)
- [x] MeshLoader::loadOBJ carrega arquivo do disco
- [x] MeshSystem::onUpdate integrado com ECS
- [x] Componentes 3D (Position3D, Rotation3D, Scale3D)
- [x] 22+ testes cobrindo todos os componentes
- [x] Compila sem SDL3 (CPU-only path)
- [x] GPU upload guardado com #ifdef CF_HAS_SDL3
Dependências#
- Upstream: Asset Manager, Formato .caf, RHI
- Downstream: Skeletal Animation, Asset Pipeline
Tópicos relacionados#
| Tópico | Descrição |
|---|---|
| Renderização & Pipeline | Meshes e shaders na pipeline 3D |
| Assets & Pipeline | Mesh loading integrado ao pipeline de assets |
Referências#
docs/architecture_specs.md— §15 Math Libraryrendering/rhi.md— Buffer/Shader creationrendering/texture-quality-lod.md— LOD de texturas no render GPUplans/2026-09-22-viewport-rendering-quality-session.md— costuras de shading em primitivas