Home / Materials

Materials

A material describes how a surface looks: its colour, its shininess, its metal/roughness, its reflection and its transparency. The engine offers two illumination models — PHONG and PBR — and a common set of fields serialized identically in scene files and in the personal library. Everything on this page comes from srcs/common/Material.hpp and the SceneParser::parseMaterial function.

Illumination models

Each material carries a model field that selects the shading model. Two values are recognized by the parser (case-insensitive); any other value raises a loading error.

{
    "name": "Matte red",
    "model": "phong",
    "base_color": [200, 40, 40]
}

PHONG model

The PHONG model combines three classic terms. The final colour of a lit point is the sum of an ambient component, a diffuse component (Lambert's law, proportional to N·L) and a specular component (glossy highlight).

By default specular is [0,0,0] (no highlight) and shininess is 32. For glossy plastic, give a non-zero specular colour (for example a light grey) and raise shininess.

PBR model

The PBR model follows a metallic-roughness workflow: the base colour is the albedo of a dielectric and the reflection colour of a metal, while roughness controls the sharpness of reflections. Advanced parameters add clearcoat, sheen and transmission.

Reflection and transparency

Four fields, shared by both models, drive secondary rays and opacity:

All fields

The table below lists every field of the Material struct, with its JSON name, type, range, real default value and role. The "Alias" column shows the extra keys the parser accepts (camelCase variants).

Textures and normal maps

A material can sample a colour texture and apply a normal perturbation. Images are loaded through stb_image (common formats: PNG, JPG, etc.), converted to RGB and cached by path (TextureCache), then sampled bilinearly with UV wrapping (repeat).

Colour texture

If texture_map_enabled is true and texture_map is non-empty, the point's base colour is read from the texture at the hit's uv coordinates, multiplied by texture_uv_scale (tiling factor). Raising texture_uv_scale repeats the pattern more often across the surface.

{
    "name": "Tiled floor",
    "model": "pbr",
    "roughness": 0.7,
    "texture_map": "tests/textures/tiles.png",
    "texture_map_enabled": true,
    "texture_uv_scale": 4.0
}

Normal maps

The normal_map field stores a path, and normal_map_enabled turns the effect on. The engine applies a procedural normal perturbation based on Perlin noise when the effect is enabled and no image path is given: normal_noise_frequency sets the scale of the relief and normal_scale (clamped to 0–1) how strongly it blends with the geometric normal.

Material library

Materials can be saved into a personal library (MaterialLibrary) located in ~/.raytracer/materials/. Each material is stored in a <name>.json file. The name is sanitized to form the filename: any non-alphanumeric character (other than - and _) becomes _, and an empty name becomes material.

Material market

The graphical interface provides a Material Market window (MarketWindow) with two tabs:

Examples

Three typical materials, in the format accepted by the scene parser and the library.

Matte plastic (PHONG)

{
    "name": "Red plastic",
    "model": "phong",
    "base_color": [200, 40, 40],
    "specular": [60, 60, 60],
    "shininess": 24.0,
    "reflectivity": 0.05
}

Brushed metal (PBR)

{
    "name": "Gold metal",
    "model": "pbr",
    "base_color": [212, 175, 55],
    "metallic": 1.0,
    "roughness": 0.25,
    "ao": 1.0,
    "specular_level": 0.5,
    "reflectivity": 0.4
}

Transparent glass (PBR)

{
    "name": "Glass",
    "model": "pbr",
    "base_color": [230, 240, 245],
    "roughness": 0.02,
    "transparency": 0.9,
    "transmission": 1.0,
    "ior": 1.5,
    "reflectivity": 0.1,
    "alpha": 0.2
}

Tips

The engine has no skybox: a secondary ray (reflection or refraction) that heads into the void returns no light. Metals and glass then appear dark. A few reflexes:

• Surround reflective/transparent surfaces with lit geometry (a floor, walls, other objects) so reflections and refraction catch something.
• Add lights visible from those surfaces (see Lights).
• If a metal or glass stays too dark, lower reflectivity and transparency and raise the diffuse share (lighter base_color, lower metallic) to keep the surface readable.
• For a sharp reflection, keep roughness low (PBR) or shininess high (PHONG); for a satin look, raise roughness gradually.