fix: Honour the clearcoat and sheen gloss invert flags in the glTF exporter - #9837

Fix inverted clearcoat and sheen roughness in the glTF exporter

The glTF exporter wrote clearCoatGloss and sheenGloss unchanged as clearcoatRoughnessFactor and sheenRoughnessFactor. That is only correct for materials that enable clearCoatGlossInvert or sheenGlossInvert, as the glTF importer does. Materials authored with gloss exported the inverse of their roughness. The checks that omit the glTF default roughness of 0 also tested the gloss, not the roughness. So the default smooth clearcoat was exported as fully rough, and the default rough sheen as smooth. The base material's gloss was already converted correctly.

Changes

• Clearcoat and sheen roughness are now invert ? gloss : 1 - gloss, as for the base material. The factor is omitted when that roughness is 0.
• A black sheen color is no longer exported, because it disables the sheen layer. Every sheen the exporter writes now includes its color, so a round trip doesn't depend on how an importer defaults a missing one.
• clearCoatGlossMap and sheenGlossMap are still exported unchanged as the roughness textures. The exporter converts each texture once and never rewrites texels per slot; the base glossMap isn't exported at all. The exporter now warns when it exports one of these maps from a material that treats it as gloss.
• The GltfExporter#build docs describe this limitation.

Behavior change

Materials imported from glTF export as before, except for a black sheen. Materials authored with gloss, with the invert flags off, now export their actual roughness:

This is independent of #9836, which fixes the sheen shading, and consistent with it: both follow the documented meaning of sheenGloss, where 0 is rough.

Tests

New cases in test/extras/exporters/gltf-exporter.test.mjs, for both KHR_materials_clearcoat and KHR_materials_sheen:

• A gloss of 0.8 with the invert flag off exports a roughness of 0.2, and 0.3 with the flag on exports 0.3.
• The default roughness of 0 is omitted.
• A gloss map is attached as the roughness texture, with a warning only when the flag is off.
• Round trip: exporting and re-importing through GlbParser gives the same roughness for gloss 0.8, inverted 0.3, 1 and 0.

For the sheen color, a black sheen is omitted, and black, white and colored sheens re-import with the color they render with.

12 of the 22 new cases fail without the fix. The black sheen cases pass on main, which omitted that sheen, and guard the regression that converting the default gloss to roughness would otherwise cause. Full suites pass: 4487 on Node, 4486 on Dawn (test:webgpu). Lint and docs pass.

Not changed here

• Texture channels aren't remapped. glTF reads clearcoat from R, clearcoat roughness from G, sheen roughness from A and metalness from B. The engine defaults clearCoatMapChannel, sheenGlossMapChannel and metalnessMapChannel to G, so those maps on materials authored in the engine export with data in the wrong channel.
• The importer still defaults a missing sheenColorFactor to white, where glTF's default is black. That's a separate fix. Files from this exporter aren't affected, as every sheen it writes now includes its color.

🤖 Generated with Claude Code