WebGLRenderer: Consolidate premultiplied alpha handling in opaque_fragment

[mrdoob]

Related issue: #32433

Description

• Moved premultiplied alpha logic into opaque_fragment.glsl.js, pre-multiplying RGB by alpha before tone mapping
• Removed premultiplied_alpha_fragment.glsl.js (was causing double-multiplication)

Motivation

Pre-multiplying in the shader preserves HDR information when rendering to LDR framebuffers:

	Light	Clamp	Blend	Result
Before (hardware)	5.0	1.0	× 0.1	0.1
After (shader)	5.0 × 0.1	0.5	—	0.5

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	350.43 83.06	350.1 83.03	-334 B -33 B
WebGPU	616.03 171	616.03 171	+0 B +0 B
WebGPU Nodes	614.64 170.74	614.64 170.74	+0 B +0 B

🌳 Bundle size after tree-shaking

Minimal build including a renderer, camera, empty scene, and dependencies.

	Before	After	Diff
WebGL	482.47 117.86	482.14 117.83	-334 B -34 B
WebGPU	687.42 186.76	687.42 186.76	+0 B +0 B
WebGPU Nodes	637.26 173.94	637.26 173.94	+0 B +0 B

[mrdoob]

@gkjohnson

Interestingly, the only example that gets affected by this is the ldraw one:

Before	After

[mrdoob]

Oh no, this triggers some weird behaviour in SwiftShader...

Screen.Recording.2025-12-02.at.09.05.00.mov

[gkjohnson]

This ordering is right to fix the original issue but it does change the color space in which alpha is applied which can have an impact on the final blend color. This is a quick demo of a sphere with sRGB color 0x660000, 0.25 opacity, transparent=true, on a white background. The left is "premultipliedAlpha=true" and the right is "premultipliedAlpha=false". You'll see that the premultiplied alpha sphere is a richer red since the alpha is applied in linear-sRGB color space rather than sRGB, which is what the graphics API will do:

Before

After

---

Here's the same demo with a <div> colored the same way. You can see that it also performs blending in sRGB color space which does not match the new premultiplied alpha coloring, though on it's own I think the color actually looks bit nicer with the change and may be more "correct" by some interpretations. Though it's wrong if you're trying to match CSS colors:

For other context there have been some other forum posts in the past about this same phenomenon when using effect composer since it uses linear color targets (see here or here). Not exactly sure what the best thing to do here is but I'll let other's chime in. Applying tone mapping as a post process would avoid all of this but I know there are performance implications.

Interestingly, the only example that gets affected by this is the ldraw one:

I'll take a look at what might be going on here later.

Oh no, this triggers some weird behaviour in SwiftShader...

😬 This I can't help with, unfortunately 😅 But that's super odd

edit: It actually looks like there are a number of references to "premultiplied_alpha_fragment" still in the examples folder that would cause a number of examples to break, including the "ldraw" and "fat lines" ones

[gkjohnson]

Interestingly, the only example that gets affected by this is the ldraw one:

This is probably because the demo has tonemapping enabled and LDrawLoader implicitly sets "premultipliedAlpha" to true. Perhaps that line should be removed to align with other loaders - but all the same here's some testing to get a sense for what's happening:

	dev	this pr
toneMapping=NONE premultipliedAlpha=true
toneMapping=NONE premultipliedAlpha=false
toneMapping=ACES premultipliedAlpha=true
toneMapping=ACES premultipliedAlpha=false

All of the opacity values are set to ~0.5. From the change in the first row it seems like this is primarily due the blended color value having alpha applied a new color space. And since premultipliedAlpha was already enabled it's now taking effect since tone mapping is also enabled in the demo.

The colors picked for LDraw palette were likely determined based on the blending results in sRGB color space rather than linear - and definitely not originally selected for use with PBR materials or transparency.

[mrdoob]

edit: It actually looks like there are a number of references to "premultiplied_alpha_fragment" still in the examples folder that would cause a number of examples to break, including the "ldraw" and "fat lines" ones

Oh, now I can reproduce. I wonder why I couldn't reproduce before... Fixing...

[gkjohnson]

I wonder why I couldn't reproduce before...

Possibly testing before deleting the premultiplied_alpha_fragment file?

---

Also one option that occurs to me in order to avoid the differences would be the following when premultiplied alpha is true:

• convert color from linear-srgb to target color space
• multiply color by alpha
• convert color to target color space to linear-srgb
• continue to apply tone mapping etc
• apply final color space conversion

Not the most elegant feeling and requires two additional color space conversion operations (possibly not so terrible in the grand scheme of some of these shaders) but it would address the color consistency issue while still allowing for premultiplied alpha tone mapping.

[mrdoob]

Was curious to see what the changes would be if we added an internal MSAA RT to WebGLRenderer: #32461

[gkjohnson]

After thinking through it for a few days I think I would probably take the approach of converting to the target color space, applying alpha, and converting back to the working color space. This should be not so expensive in the grand scheme of things and only need to be run when premultiplied alpha is true and blending is enabled.

This will avoid any performance overhead from a new required half-float fullscreen pass and any functionality loss like per-object tonemap settings. Even if we do want to "detone" some objects to address I'm not sure if it will full work because there is generally information loss in a tone mapping step. More realistically I think we'd need some kind of "mask" for tone mapping application rendered using MRT like a deferred rendering system.

On a related topic, I'm wondering if it's worth raising the idea of setting the default of "premultipliedAlpha" to true, again, since the results are generally much nicer for transparent objects in bright lighting.

[donmccurdy]

Not that we'd necessarily change anything in WebGLRenderer now, but I might prefer to think of tone mapping as a pass-level setting. So overlays, billboards, or UI elements that don't participate in scene lighting would ideally be drawn in a later pass, composited after tone mapping. Rather than trying to mask out specific objects within a 3D scene, which may have transparency, etc... In that case materials like MeshNormalMaterial do not need special treatment.

If our premultiplied alpha blending equation is...

out = src + dst x (1 - alpha)

... is it a concern that our premultiplied 'src' may now have components greater than the alpha value? I'm not sure I understand the implications of that change, or whether it may introduce more clipping at 1.0 that the tone mapping would otherwise have avoided.

[mrdoob]

@gkjohnson

After thinking through it for a few days I think I would probably take the approach of converting to the target color space, applying alpha, and converting back to the working color space. This should be not so expensive in the grand scheme of things and only need to be run when premultiplied alpha is true and blending is enabled.

Just gave that a try: #32470

[mrdoob]

@gkjohnson

On a related topic, I'm wondering if it's worth raising the idea of setting the default of "premultipliedAlpha" to true, again, since the results are generally much nicer for transparent objects in bright lighting.

Gave that a try too: #32472