Design and Implementation of a PBR Material Editing Tool for the Filament Engine

The article describes the motivation, goals, architecture, and implementation details of a PBR material editing tool built on top of the Filament rendering engine. The tool aims to lower the barrier for creating PBR materials, accelerate the workflow from material authoring to mobile‑side validation, and provide cross‑platform support.

Background : After switching the 3D space of the "得物" app to Filament, rendering quality improved, but the material pipeline (edit → compile → mobile render → validation) remained time‑consuming. A dedicated editor is proposed to streamline this process.

Goals : Unify material editing and rendering on PC, ensure identical rendering results on PC and mobile, support multi‑platform distribution, and enable direct export of mobile‑ready material packages.

Process Optimization : By moving rendering to the PC, the need for repeated multi‑platform compilation is eliminated, and lighting adjustments become more convenient.

Principle : The editor combines a GUI (ImGui) with the Filament engine in an SDL2 context, allowing real‑time preview of material changes.

Main Functions include material editing, model‑material assignment, data persistence, model optimization, texture compression, material export, and import.

GUI : Uses ImGui (C++) for fast, portable UI components.

Material Editing : Provides editing of material properties, lighting models, and texture maps. Users select meshes, adjust parameters, and see immediate results.

Multi‑mesh Material Mapping : Uses Assimp to parse OBJ files into an aiScene. Each aiMesh has an mMaterialIndex that maps to an aiMaterial. Filament traverses the scene, creates Mesh and Part structures, and assigns material IDs accordingly.

Example of a persisted material JSON entry:

{
  "129" : {
    "baseColorIndex" : 1,
    "baseColorMap" : "/Users/test/Downloads/Watch_TISSOT_Classic/image/Watch_TISSOT_Classic_Color.png",
    "exported" : false,
    "metallicIndex" : 1,
    "metallicMap" : "/Users/test/Downloads/Watch_TISSOT_Classic/image/Watch_TISSOT_Classic_M.png",
    "normalIndex" : 1,
    "normalMap" : "/Users/test/Downloads/Watch_TISSOT_Classic/image/Watch_TISSOT_Classic_Normal.png",
    "shadingModel" : "lit"
  }
}

Model‑Material Assignment : Ensures that custom material names match the names in the imported mesh so that the editor can replace default materials with user‑defined ones.

Persistence : Saves edited material attributes and associated model files to a JSON file using jsoncpp. Sample C++ persistence code:

if (!dst_dir.exists()) {
    dst_dir.mkdir();
}
Json::Value* root = new Json::Value();
Json::Value& tmp = *root;
std::vector
dependency_resources;
for (auto entry: memoryPersist) {
    std::string material_name = entry.first;
    if (material_name.empty()) {
        continue;
    }
    tmp[entry.first] = Json::Value(exportMaterialJson(entry.second, &dependency_resources));
}
// copy model file
utils::Path dst_obj = dst_dir.concat(model_path.getName());
if (!dst_obj.exists()) {
    std::filesystem::copy_file(model_path.c_str(), dst_obj.c_str());
}
tmp["model"] = model_path.getName();
// write JSON file
std::ofstream ofs;
utils::Path json_path = dst_dir.concat("material.json");
ofs.open(json_path, std::ios::out);
if (ofs.is_open()) {
    Json::StyledWriter sw;
    ofs << sw.write(tmp);
}
ofs.close();

Model Optimization & Texture Compression : Converts OBJ models to Filamesh, reducing vertex count and compressing tangent‑space normals to 16‑bit, achieving ~3:1 size reduction. Texture compression uses ETC on Android and PVR on iOS, and converts textures to KTX for GPU‑direct consumption, cutting decode time from hundreds of milliseconds to a few milliseconds.

Material Export : Generates a mobile‑ready package containing the compiled filamat shader, a JSON material list, the optimized model, and associated textures. The material definition (MAT file) includes fixed parameters and conditional logic; dynamic values are supplied via the JSON file.

Excerpt of a MAT file:

material {
    name : LitOpaque,
    shadingModel : lit,
    parameters : [
        { type : float3, name : baseColor },
        { type : int, name : baseColorIndex },
        { type : sampler2d, name : baseColorMap },
        { type : int, name : normalIndex },
        { type : sampler2d, name : normalMap }
    ],
    specularAntiAliasing : true,
    requires : [ uv0 ]
}
fragment {
    void material(inout MaterialInputs material) {
        if (materialParams.normalIndex > -1) {
            material.normal = texture(materialParams_normalMap, getUV0()).xyz * 2.0 - 1.0;
        }
        prepareMaterial(material);
        if (materialParams.baseColorIndex > -1) {
            material.baseColor = texture(materialParams_baseColorMap, getUV0());
        } else {
            material.baseColor.rgb = materialParams.baseColor;
        }
        if (materialParams.roughnessIndex > -1) {
            material.roughness = texture(materialParams_roughnessMap, getUV0()).r;
        } else {
            material.roughness = materialParams.roughness;
        }
    }
}

Material Import : Allows designers to load exported material packages for validation, reconstructing the scene by loading the JSON material data, the model, and the textures.

Conclusion : The Filament Creator material editor streamlines PBR workflow, reduces iteration time, and ensures consistent visual quality across PC and mobile platforms, benefiting 3D product presentation and user experience.