Construct Material System

Status: Complete Last Updated: 2026-02-02

Overview

The Construct CAD application provides a comprehensive PBR (Physically Based Rendering) material system for applying surface properties to SDF primitives and operators.

Architecture

Core Components

Component	Location	Purpose
`CatalogMaterial`	`construct/model/`	Material data class with PBR properties
`MaterialLibrary`	`construct/model/`	Singleton manager for all materials
`MaterialListModel`	`construct/model/`	Qt model for material list views
`MaterialDelegate`	`construct/ui/`	Custom delegate for rich material rendering
`MaterialPreviewWidget`	`construct/ui/`	Sphere preview with material properties
`MaterialSelectorWidget`	`construct/ui/`	Inline material picker, used on scene-tree rows and in the material list
`MaterialListWidget`	`construct/ui/`	Reusable list component
`MaterialListPopup`	`construct/ui/`	Popup dialog for material selection
`MaterialEditorWindow`	`construct/ui/`	Full material editing interface

Material Properties

Property	Type	Range	Description
`name`	QString	-	Display name
`category`	QString	-	Grouping category
`albedo`	QVector4D	0-1 RGBA	Base color
`metallic`	float	0-1	Metalness factor
`roughness`	float	0-1	Surface roughness
`emission`	float	0-100	Self-illumination intensity
`lastModified`	QDateTime	-	Timestamp for sorting
`isBuiltIn`	bool	-	Read-only flag for defaults

Built-in Materials

The library provides 20 built-in materials across categories:

Metals: Chrome, Gold, Copper, Bronze, Iron
Plastics: Red, Blue, Green, White, Black
Ceramics: Ceramic, Porcelain
Stone: Marble, Granite, Concrete
Special: Glass, Rubber, Emissive white, Emissive orange
Basic: Default (gray)

Built-in materials cannot be modified directly. Use "Save As Copy" to create editable versions.

Material Selection

Row Selector

The material selector appears on an item's row in the scene tree when the row is expanded:

┌─────────────────────────────────────────────┐
│ Material                                    │
│ ┌────────┐                          [Edit ] │
│ │   ●    │  Material Name           [Clone] │
│ │ preview│  M: 0.0 · R: 0.5                 │
│ └────────┘                                  │
└─────────────────────────────────────────────┘

Click preview: Opens material list popup
Double-click: Opens material editor
Edit button: Opens material editor
Clone button: Opens editor with unsaved clone

Single-click on any material to select it. The popup closes automatically. Click outside to cancel.

Materials are sorted:

User materials (most recently modified first)
Built-in materials (alphabetically by category, then name)

Built-in materials display with a subtle lighter background.

Material Editor

Access via toolbar button or double-clicking a material.

Layout

Left panel: Material list with "New material" button
Right panel: Large preview, parameter controls

Operations

Button	Action
New material	Create blank custom material
Save	Save changes to library
Save as copy	Create new material from current (for built-ins)
Revert	Discard unsaved changes
Delete	Remove custom material

Clone Workflow

When clicking "Clone" on a row:

Editor opens with unsaved clone (marked as "New")
Name has "(clone)" suffix
User edits properties as desired
Save: Adds material to library
Revert/Close: Discards clone silently

Visual indicators:

Blue dot + "(New)" in title: Unsaved new material
Orange dot + "*" in title: Modified existing material

CSG Material Blending

Operators support material blending between their operands.

Properties

Property	Values	Description
`materialMode`	BaseWins, OperandWins, Blend	Which material takes priority
`blendSharpness`	0.0 - 1.0	Transition sharpness (0=smooth, 1=hard)

Modes

BaseWins (0): First operand's material used
OperandWins (1): Second operand's material used
Blend (2): Materials interpolate based on distance

File Format

Materials are stored in .construct files with a separate materials: section:

construct:
  version: 1
  name: "My Scene"

materials:
  my_custom_red:
    name: "My Custom Red"
    category: "Custom"
    albedo: [0.9, 0.1, 0.1, 1.0]
    metallic: 0.0
    roughness: 0.3
    emission: 0.0

instances:
  sphere_1:
    type: sphere
    materialId: "my_custom_red"
    params:
      radius: 10

Persistence

Built-in materials: Loaded from code at startup
User materials: Stored in ~/.local/share/OctoMY/OctoMY Construct/materials.json
Project materials: Stored within .construct files

Test Coverage

Material system tests in test/testSDFModel/:

testInstanceMaterialDefaultValues
testInstanceMaterialSerialization
testMaterialRoundTrip
testInstanceBlendSharpness
testInstanceMaterialMode
testInstanceBlendingSerialization
testMaterialBlendingDSLRoundTrip

Fixture: test/testSDFModel/fixtures/material_blending.construct