Material: transparent=true has no effect on glTF materials (since r132)

[konradkissener]

With Three.js r132 I can no longer make my models transparent. I export Models in Blender (2.92.0) as .glb file. I then import via GLTFLoader and set the opacity in JavaScript. I am also unable to make the object transparent using the three.js editor (drag and drop .glb in the editor).

Steps to reproduce the behavior:

1. Export "Blender cube" as .glb file
2. Load the .glb via GLTFLoader
3. Set opacity/transparency on the MeshStandardMaterial

(expect that model ist transparent)

Code

new GLTFLoader().load("cube.glb", (gltf) => {
    const cube = gltf.scene.getObjectByName("Cube");
    if (
      cube instanceof THREE.Mesh &&
      cube.material instanceof THREE.MeshStandardMaterial
    ) {
      scene.add(cube);
      cube.material.opacity = 0.5;
      cube.material.color.set("#0000ff");
      cube.material.transparent = true;
      cube.material.depthWrite = false;
      cube.material.side = THREE.FrontSide;
    }
  });

Expected behavior

With r131, the sample project looks like this:

https://codesandbox.io/s/threejs-transparency-r131-rth6g

Screenshots

With r132, the sample project looks like this:

https://codesandbox.io/s/threejs-transparency-r132-1hs0v

Platform:

• Device: Desktop
• OS: MacOS
• Browser: Chrome
• Three.js version: r132.2

[donmccurdy]

In the latest version you may also need to set material.format = THREE.RGBAFormat to enable transparency. I'm not sure whether that change will remain in future versions though, see #22428 (comment).

[konradkissener]

Thank you @donmccurdy, your proposed solution solves the issue for the JavaScript case.

Should I close the issue, though? The documentation for Material and MeshStandardMaterial does not mention the .format attribute and the behaviour in the three.js editor is quite confusing, as also mentioned by @marcatec in #22428 (comment)

[WestLangley]

Should I close the issue, though?

No. This has to be fixed.

[donmccurdy]

In the short term maybe reverting material.format would be justified? It seems like it might be catching more people by surprise than it helped, unfortunately.

Of the alternatives I think that #22414 (comment) (or something like it) is currently my favorite, turning .transparent into a setter with multiple effects. Happy users can continue using it; users with more advanced needs can dive into the the lower-level settings instead.

[optimus007]

to summarise

• material.transparent : Boolean // master transparency control BUT _alphaTest will still work if this is false

• material.opacity : Float 0-1 // Only works if material.format=THREE.RGBAFormat

• material.alphaMap : greyscale opacity map // works if material.transparent=true & material.format is THREE.RGBAFormat NOTE: GLTF exporter does not export this channel & USDZ exporter does.

• Alpha channel of material.map // ( transparent png image) will work if material.transparent=true & material.format is irrelevant here

• material.format : THREE.format // Is THREE.RGBFormat for imported gltf files and is THREE.RGBAFormat when a new THREE.MeshStandardMaterial is created .

• material._alphaTest : Float 0-1 // clips the transparent part before this threshold value. Side note: this was material.alphaTest before now its material._alphaTest but using matrial.alphaTest still works

is this correct ?

[donmccurdy]

I think _alphaTest is a private variable, it's better to use alphaTest (no change here).

Right now, GLTFLoader sets material.format to RGBFormat when loading a material that should (as defined in the glTF file) be fully opaque: no alpha test, no alpha blending, etc. To enable those effects after loading a glTF file, material.format must be changed to RGBAFormat. It doesn't seem like we're quite happy with this solution, so I would expect this to change.

I think of .transparent as existing only to enable alpha blending, e.g. semi-transparency that does not use physically-based methods like transmission. For all other forms of "not fully opaque" — like alpha hash/dither, transmission, and alpha test — .transparent should remain false.

[pailhead]

In the short term maybe reverting material.format would be justified?

I find this phenomenon a bit odd. Would this basically invalidate a version(s) of three.js (at least from the perspective of this feature)? Would it be possible to label some releases as "broken" or something along those lines?

Ie. for all intents and purposes, if my project uses transparent objects, i might not be able to use 133, but based on the conversation here, 134 may work exactly like 132.

I ran into this somewhat when working with shader chunks, some files can be pretty long lived between versions, but then could also start changing in a few consecutive versions.

[MCArth]

I'm new to three.js - but dropping in to say that I recently experienced this and it was a nightmare to debug - I thought it was an issue with the model. This should definitely be reverted or otherwise fixed.

[donmccurdy]

To recap briefly –

When a material is opaque (which is not the same as .transparent = false!) we want to ignore alpha in output_fragment. When a material is transparent via alpha blending (.transparent = true), we of course need to use alpha in output_fragment.

Unfortunately, we can't solely determine whether to write alpha based on state of .transparent. Additive alpha blending also requires alpha, but may use .transparent = false.

This brings us to a conflict — intuitively and historically, .transparent = true should enable classic alpha blend transparency. But we need to expose an additional option via material.format (perhaps this should be changed), that determines whether alpha is written.

From here, a few ideas:

(A) Replace .format = RGBFormat with .alphaWrite = false? Doesn't fix anything, but does seem like a clearer name.

(B) Ignore .format/.alphaWrite when .transparent=true. We need the option to toggle it for additive blending when .transparent=false but there's no need to choose when .transparent=true.

(C) Turn .transparent into a getter/setter with multiple effects. In the past we've considered making .depthWrite=false the default for transparent objects but couldn't decide on an API to do so — this could be one way.

class Material {

  set transparent ( transparent ) {
    this.alphaMode = AlphaBlend;
    this.alphaWrite = true;
    this.depthWrite = false;
  }

  get transparent () {
    return this.alphaMode === AlphaBlend && this.alphaWrite === true; 
  }

}

If any of these are acceptable, I'm glad to open a PR.

Related issues: #15483 #18631 #21744 #22196 #22414 #22428

[Mugen87]

Replace .format = RGBFormat with .alphaWrite = false? Doesn't fix anything, but does seem like a clearer name.

Indeed! I like alphaWrite as a notation. Sounds like a good addition next to depthWrite.

[takahirox]

@donmccurdy

Thanks for recapping this! I wanted to join the discussion but it was hard to read through the long discussion. The recap help me a lot.

In the three suggestions I want to vote for .alphaWrite because it's clearest, simplest, and most straightforward to me. Others, ignoring some exposed properties in some conditions or having an effect to some exposed properties by setting a property, might be sometimes a bit confusing to users. .format = RGBFormat may be also confusing to users, they may think .format can take other formats like AlphaFormat, DepthFormat or so on, but it may be not what we really want to do.