Three.js: Suggestion: Documentation for shader chunks

[sciecode]

It's a very common occurrence, on the forums/SO, to stumble by people having difficulties integrating existing shader chunks with their own custom shaders.

Most of the problem lies in the lack of a documentation for these. Having to dig through each chunk, determine each of their dependencies and required defines/uniforms makes it for quite a bit of work.

I'm sure it has been considered before, but is there any good reasons for not having these docs, besides being a lot of work? Finding a good way to organize the documentation could be tricky, but having this sort of information available is bound to be beneficial in the long run.

I would be more than happy to contribute with the creation of the documents, given that we can find an appropriated way of organizing and showcasing all the information required for each chunk. I think this is an all or nothing kind of deal.

Interested in hearing thoughts about this and possible counter arguments against having these docs.

[looeee]

is there any good reasons for not having these docs, besides being a lot of work?

Recently, we've been considering switching to node based materials, and when that happens these docs would become obsolete. No idea when, or if, that's likely to happen though.

[Mugen87]

and when that happens these docs would become obsolete.

At least the current implementation of NodeMaterial uses the existing shader chunks e.g.

https://github.com/mrdoob/three.js/blob/d7dcf788026515cd37f209b086e3fab48b4c41a5/examples/jsm/nodes/materials/nodes/StandardNode.js#L69-L74

However, I think documenting NodeMaterial first (the different node types and how to use the system in general) might be more beneficial than documenting the low-level shader chunks.

[munsocket]

I find that we can use string ‘void main() {‘ in most of shaders both for adding new uniforms and structs and for adding calculations inside main() function. Since .onBeforeCompile() looks like hack, we can describe this hack too.

[pailhead]

Shader chunks have existed for a long time, and may not be going anywhere in the near future. It would be nice to document them. +1

However, this can also be done outside of the core/repo.

While a node based system might require documentation for something like MathNode one probably does not need to document the + - / : operators for GLSL, at least not in the context of three.js since they are universal for all GLSL. The chunks that @Mugen87 listed, are fairly unique and could benefit from some documentation, or at least inline comments.

[munsocket]

Bump.

[pailhead]

However, I think documenting NodeMaterial first (the different node types and how to use the system in general) might be more beneficial than documenting the low-level shader chunks.

Id like to make an argument against this. The chunks have been in the core for a long time now, while the NodeMaterial has been opt in. As you’ve demonstrated, NM is (currently) a superset of chunks.

I don’t see that the NM nodes would need any more documentation than what can already be found for glsl. For example a “cross vectors” node is pretty straight forward. Add/multiply would probably require no more than “adds two inputs and outputs result.

If the chunks were somehow private and not visible to the user this would make a lot of sense. But the ShaderChunk dictionary is public. If something is available for you to use in some way or another it should be documented.

@looeee has a good point as well - this migration has been in consideration for a while now and no one is certain when it’s going to happen. While chunks may become legacy at some point, they’re one of the most core features of the library at the moment. (Try using threejs without chunks :)