New TSL doc

[Makio64]

Description

Currently the doc of threejs is very nice but it doesnt seems appropriated for all the small tsl function like uv() / min() / vec2() / position() / etc.. and I recently found myself diving into the Github research of this repo or into the large examples fews times a day while working with TSL.

Solution

I suggest a part of the doc dedicated to the TSL with on the left the nodes list and on the right minimal code.
With a UX similar to current examples but more appropriated for such a small node like animejs did : https://animejs.com/documentation/

I believe it'll help a lot of devs and will ease a lot the learning curve of TSL.

Alternatives

Add TSL pages in the docs with all the nodes, maybe sort with large category such as math vertex fragment posteffect

Additional context

No response

[Mugen87]

Related: @sunag has started a Wiki page for TSL here: https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language

[Makio64]

@Mugen87 The wiki page was a nice introduction. As Node/TSL matures it needs to be add to the documentation/website, it's one of the core concept of the project and it doesn't make sense anymore to be keep in a single wiki page.

Another advantage : it'll be easier to update it when someone commit a change, like it's the case for adding/modifying functions in the rest of the project.

[Samsy]

Im am confused with the actual nodes of a nodematerial without explanations of how each node affect the shading.

Like for example, normalNode :

If I set a normalNode, is it rewriting the entire normal calcs and overriding let say a normal map that was set on the material previously ? or a normalNode is affecting the source normals ( geometry ) of the mesh ?

Same goes for colorNode, is it overriding every diffuse calculation including a map that was set on the material ? or is it just affecting the diffuse color regardless of the next map calculations

etc..

But also, when not defined by the user, are those set internally with a default node behavior for each ? How can we get access to default templates of each node for each material ?

There is also a lot of nodes, and wish they were all listed and given all explanations about how they work, and how they would affect the final render.

[sunag]

I'm doing some updates here https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language#nodematerial

[Mugen87]

In the last weeks almost all node classes and TSL functions have been documented via JSDoc. The new documentation should hopefully make the signatures more clear as well as the purpose of predefined TSL objects and functions. When I'm done with documenting the remaining node classes (e.g. the new materials like MeshBasicNodeMaterial are still missing), I will focusing on the documentation of WebGPURenderer related modules (which is also quite a task).

That said, an API documentation can't replace guides, tutorials or manual-like articles with a more in-depth and coherent style. Until we have agreed on a new manual approach (see #27832), I suggest adding new TSL or WebGPU related pages to https://threejs.org/manual/. Does that sound acceptable?

[mrdoob]

I suggest adding new TSL or WebGPU related pages to https://threejs.org/manual/. Does that sound acceptable?

To manual or to docs? We could also do a new api folder... 🤔

[Makio64]

@mrdoob @Mugen87 would be nice to add the new docs indocs under webgpu & tsl category + a dedicated page in manual to explain the new concepts.

[Makio64]

@Mugen87 I saw you added so much doc into tsl code, is it accessible somewhere? Do you need help on this part ?

[Mugen87]

Up to know, the JSDoc based documentation was only available locally (we running npm run build-docs) or via auto-completion in editors. With the next release, we eventually publish the new docs and replace the former documentation #30748.

What we don't have so far are more in-depth guides about TSL or WebGPURenderer. Like the ones from the manual. Help in this context would be welcome^^. Useful guides could be:

• "Migrating from WebGLRenderer to WebGPURenderer" which could explain the differences between both renderers and their material systems as well as common migration tasks (e.g. ShaderMaterial to TSL).
• "A Basic Introduction to TSL": Explaining the basic concepts of TSL, show some sample code (maybe a how to? section), mention the TSL Transpiler.
• More specific guides about certain aspects of TSL or WebGPURenderer like compute shaders or post processing.

The articles don't have to be "complete" or perfect right from the beginning. A start with some basic information would already be a huge help. The guides should be added at https://threejs.org/manual/ in a new category TSL or WebGPU.

Notice that articles like Color Management or Installation from the previous documentation have been moved to the manual via #30736. So any new articles should be added there.