viewport_lib/scene/material.rs
1/// Procedural UV visualization mode for parameterization inspection.
2///
3/// When set on a [`Material`], the mesh fragment shader ignores the albedo texture and
4/// renders a procedural pattern driven by the mesh UV coordinates instead. Useful for
5/// inspecting UV distortion, seams, and parameterization quality without needing a texture.
6///
7/// Requires the mesh to have UV coordinates. Has no effect if the mesh lacks UVs.
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9pub enum ParamVisMode {
10 /// Alternating black/white squares tiled in UV space.
11 Checker = 1,
12 /// Thin grid lines at UV integer boundaries.
13 Grid = 2,
14 /// Polar checkerboard centred at UV (0.5, 0.5) — reveals rotational consistency.
15 LocalChecker = 3,
16 /// Concentric rings centred at UV (0.5, 0.5) — reveals radial distortion.
17 LocalRadial = 4,
18}
19
20/// UV parameterization visualization settings.
21///
22/// Attach to [`Material::param_vis`] to enable procedural UV pattern rendering.
23/// The `scale` controls tile frequency — higher values produce more, smaller tiles.
24#[derive(Debug, Clone, Copy, PartialEq)]
25pub struct ParamVis {
26 /// Which procedural pattern to render.
27 pub mode: ParamVisMode,
28 /// Tile frequency multiplier. Default 8.0 — produces 8 checker squares per UV unit.
29 pub scale: f32,
30}
31
32impl Default for ParamVis {
33 fn default() -> Self {
34 Self { mode: ParamVisMode::Checker, scale: 8.0 }
35 }
36}
37
38/// Controls how back faces of a mesh are rendered.
39///
40/// Use [`BackfacePolicy::Cull`] (the default) to hide back faces, [`BackfacePolicy::Identical`]
41/// to show them with the same shading as front faces, or [`BackfacePolicy::DifferentColor`]
42/// to shade back faces in a distinct color — useful for spotting mesh orientation errors or
43/// highlighting the interior of open surfaces.
44#[derive(Debug, Clone, Copy, PartialEq)]
45pub enum BackfacePolicy {
46 /// Back faces are culled (invisible). Default.
47 Cull,
48 /// Back faces are visible and shaded identically to front faces.
49 Identical,
50 /// Back faces are visible and shaded in the given RGB color (linear 0..1).
51 ///
52 /// Front faces receive normal shading; back faces receive Blinn-Phong shading
53 /// with the supplied color and the same ambient/diffuse/specular coefficients.
54 /// The normal is flipped so lighting is computed from the back-face perspective.
55 DifferentColor([f32; 3]),
56}
57
58impl Default for BackfacePolicy {
59 fn default() -> Self {
60 BackfacePolicy::Cull
61 }
62}
63
64/// Per-object material properties for Blinn-Phong and PBR shading.
65///
66/// Materials carry all shading parameters that were previously global in `LightingSettings`.
67/// Each `SceneRenderItem` now has its own `Material`, enabling per-object visual distinction.
68///
69/// This struct is `#[non_exhaustive]`: construct via [`Material::default`],
70/// [`Material::from_color`], or spread syntax (`..Default::default()`). This allows new
71/// fields to be added in future phases without breaking downstream code.
72#[non_exhaustive]
73#[derive(Debug, Clone, Copy, PartialEq)]
74pub struct Material {
75 /// Base diffuse color [r, g, b] in linear 0..1 range. Default [0.7, 0.7, 0.7].
76 pub base_color: [f32; 3],
77 /// Ambient light coefficient. Default 0.15.
78 pub ambient: f32,
79 /// Diffuse light coefficient. Default 0.75.
80 pub diffuse: f32,
81 /// Specular highlight coefficient. Default 0.4.
82 pub specular: f32,
83 /// Specular shininess exponent. Default 32.0.
84 pub shininess: f32,
85 /// Metallic factor for PBR Cook-Torrance shading. 0=dielectric, 1=metal. Default 0.0.
86 pub metallic: f32,
87 /// Roughness factor for PBR microfacet distribution. 0=mirror, 1=fully rough. Default 0.5.
88 pub roughness: f32,
89 /// Opacity (1.0 = fully opaque, 0.0 = fully transparent). Default 1.0.
90 pub opacity: f32,
91 /// Optional albedo texture identifier. None = no texture applied. Default None.
92 pub texture_id: Option<u64>,
93 /// Optional normal map texture identifier. None = no normal mapping. Default None.
94 ///
95 /// The normal map must be in tangent-space with XY encoded as RG (0..1 -> -1..+1).
96 /// Requires UVs and tangents on the mesh for correct TBN construction.
97 pub normal_map_id: Option<u64>,
98 /// Optional ambient occlusion map texture identifier. None = no AO map. Default None.
99 ///
100 /// The AO map R channel encodes cavity factor (0=fully occluded, 1=fully lit).
101 /// Applied multiplicatively to ambient and diffuse terms.
102 pub ao_map_id: Option<u64>,
103 /// Use Cook-Torrance PBR shading instead of Blinn-Phong. Default false.
104 ///
105 /// When true, `metallic` and `roughness` drive the GGX BRDF.
106 /// PBR outputs linear HDR values; enable `post_process.enabled` for correct tone mapping.
107 pub use_pbr: bool,
108 /// Optional matcap texture identifier. When set, matcap shading replaces
109 /// Blinn-Phong/PBR. Default None.
110 ///
111 /// Obtain a `MatcapId` from [`ViewportGpuResources::builtin_matcap_id`] or
112 /// [`ViewportGpuResources::upload_matcap`]. Blendable matcaps (alpha-channel)
113 /// tint the result with `base_color`; static matcaps override color entirely.
114 pub matcap_id: Option<crate::resources::MatcapId>,
115 /// UV parameterization visualization. When set, replaces albedo/lighting with a
116 /// procedural pattern in UV space — useful for inspecting parameterization quality.
117 ///
118 /// Requires UV coordinates on the mesh. Default None (standard shading).
119 pub param_vis: Option<ParamVis>,
120 /// Back-face rendering policy. Default [`BackfacePolicy::Cull`] (back faces hidden).
121 ///
122 /// Use [`BackfacePolicy::Identical`] for single-sided geometry like planes and open
123 /// surfaces. Use [`BackfacePolicy::DifferentColor`] to highlight back faces in a
124 /// distinct color — helpful for diagnosing mesh orientation errors.
125 pub backface_policy: BackfacePolicy,
126}
127
128impl Default for Material {
129 fn default() -> Self {
130 Self {
131 base_color: [0.7, 0.7, 0.7],
132 ambient: 0.15,
133 diffuse: 0.75,
134 specular: 0.4,
135 shininess: 32.0,
136 metallic: 0.0,
137 roughness: 0.5,
138 opacity: 1.0,
139 texture_id: None,
140 normal_map_id: None,
141 ao_map_id: None,
142 use_pbr: false,
143 matcap_id: None,
144 param_vis: None,
145 backface_policy: BackfacePolicy::Cull,
146 }
147 }
148}
149
150impl Material {
151 /// Returns `true` if the backface policy makes back faces visible (`Identical` or `DifferentColor`).
152 pub fn is_two_sided(&self) -> bool {
153 matches!(self.backface_policy, BackfacePolicy::Identical | BackfacePolicy::DifferentColor(_))
154 }
155
156 /// Construct from a plain color, all other parameters at their defaults.
157 pub fn from_color(color: [f32; 3]) -> Self {
158 Self {
159 base_color: color,
160 ..Default::default()
161 }
162 }
163
164 /// Construct a Cook-Torrance PBR material.
165 ///
166 /// - `metallic`: 0.0 = dielectric, 1.0 = full metal
167 /// - `roughness`: 0.0 = mirror, 1.0 = fully rough
168 ///
169 /// All other parameters take their defaults. Enable post-processing
170 /// (`PostProcessSettings::enabled = true`) for correct HDR tone mapping.
171 pub fn pbr(base_color: [f32; 3], metallic: f32, roughness: f32) -> Self {
172 Self {
173 base_color,
174 use_pbr: true,
175 metallic,
176 roughness,
177 ..Default::default()
178 }
179 }
180}