Three.js: documentation for Material.needsUpdate

[greggman]

The current docs for Material.needsUpdate say

.needsUpdate : Boolean

Specifies that the material needs to be updated at the WebGL level. Set it to true if you made changes that need to be reflected in WebGL.

But AFAIK most material parameters don't need needsUpdate set? Is it documented anywhere which material parameters might need needsUpdate set?

[looeee]

No, that isn't documented. If you want to go through the various parameters and figure out which ones need it set that would be much appreciated.

[pailhead]

I think it's mostly just copy paste this list over:

https://github.com/mrdoob/three.js/blob/dev/src/renderers/webgl/WebGLProgram.js#L341

However, there might be edge cases and other things. IMO @greggman with your infinite knowledge of WebGL and how browsers are build, i urge you to not spend your time on something like this.

[looeee]

@pailhead perhaps you'd like to take it on instead then?

[pailhead]

Sure, on one condition - discuss this pattern:

Object.defineProperty( someMaterial, 'someProperty', {
  get: ()=>someMaterial._someProperty,
  set: v=>{ 
    someMaterial._someProperty = v 
    someMaterial.needsUpdate = someCondition(v)
  }
})

:)

I'm somewhat kidding. I have an accepted PR where I think it's not consistent with the core, but it tackles the same problem. I am afraid to dive into a manual task such as this, if i'm not 100% sure that there isn't a better pattern out there that will make the documentation obsolete. But, if it causes @greggman to not update docs but do something else webgl / webgl2 related, i'd be more than happy to do this.

[pailhead]

I'd also prefer to have a discussion:

Re: landing code without documentation / examples

Which results in "tribal knowledge" - when needsUpdate should be set is tribal knowledge.

[looeee]

@pailhead please keep discussion on topic. If you want to discuss something else then open a new issue and discuss it there.

[pailhead]

.needsUpdate has to be set when updating:
1. foo
2. bar
3. baz

That doesn't actually feel right, the user is under no obligation to set needsUpdate and i don't know how to explain that in the docs. I felt that these things I mentioned are somewhat related. You DO NOT need to go down a rabbit hole of discussing this, but a brief overview, distilled, could yield that introductory sentence to needsUpdate.

You can (optionally) set needsUpdate when you want the material to update (lorem ipsum webgl).

You have to set needsUpdate if you want the changes from parameters foo,bar and baz to have any effect (you can also decide not to update the material)

Or something else. Like, why is this parameter optional, and up to the user to manage? <- should this be included in the docs? Or should we discuss it (here? somewhere?) in order to make sensible documentation?

[pailhead]

I think the solution here is to couple this with the concept of "compiling". Both if you want the shader to be compiled for webgl, and when you want three to compile internally, you have to set this, i don't think there is another way to actually compile a shader.

Mentioning webgl is extremely confusing, as i'd like my material.color to also be "reflected in webgl", i'd assume i need to do:

myMaterial.color.set(1,1,1)
myMaterial.needsUpdate = true

[greggman]

So l just thought I'd add the majority of properties for which you need to set needsUpdate are properties that are unlikely to change at runtime.

skinning, useVertexColors, morphTargets, are all things that rarely change at runtime. flatShading seems unlikely to change at runtime. The other big one is any texture input map, bumpMap, normalMap, envMap etc if they change from null to Texture or Texture to null. But that's also a rare case.

Maybe the docs could say that rather than listing all the cases? It would be nice to know that it's only exceptional cases where needsUpdate is needed.

[looeee]

@greggman perhaps we could add a note to needsUpdate listing the case where it does need to be set? Something like:

needsUpdate - Specifies that the material needs to be recompiled. This only needs to be set when updating the following material properties: skinning, useVertexColors, morphTargets, and when adding or updating any maps.

[pailhead]

Are you certain about “updating maps”?

Might also be worth considering clipping planes and lights even?

Also why was my last post in this thread marked as spam since we both landed the changed wording and @looeee you have adopted it ("compilation")

[Mugen87]

No, that isn't documented. If you want to go through the various parameters and figure out which ones need it set that would be much appreciated.

It actually is documented here (section Materials):

https://threejs.org/docs/index.html#manual/en/introduction/How-to-update-things

If information are still missing, feel free to create a PR that enhances this section. Separate issues are not necessary.