Normal.js: Improve JSDoc

[WestLangley]

As the title says.

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	337.69 78.76	337.69 78.76	+0 B +0 B
WebGPU	557.35 154.34	557.35 154.34	+0 B +0 B
WebGPU Nodes	556.27 154.12	556.27 154.12	+0 B +0 B

🌳 Bundle size after tree-shaking

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

	Before	After	Diff
WebGL	468.91 113.42	468.91 113.42	+0 B +0 B
WebGPU	632.96 171.33	632.96 171.33	+0 B +0 B
WebGPU Nodes	588.09 160.72	588.09 160.72	+0 B +0 B

[WestLangley]

What is the proper distinction between normalView and normalViewGeometry?

//

This may need clarification, too -- in a separate PR, that is.

https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language#normal

[sunag]

What is the proper distinction between normalView and normalViewGeometry?

The transformed term reflects the modifications applied by processes such as skinning, morphing, and similar techniques. The term transformed also includes following the correct orientation of the face, so that the normals are inverted inside the geometry.

[WestLangley]

Trying to clarify...

normalView is the view-space normal, post skinning and morphs.

normalView honors the material sidedness.

//

normalViewGeometry in TSL is the same as the so-called nonPerturbedNormal in the WebGLRenderer shaders. That is, it is the view-space normal, unmodified by skinning or morphs.

1. Does normalViewGeometry honor the material sidedness?
2. Can normalViewGeometry be made private so we don't have to explain it?

[sunag]

1, 2. No for both I imagine.

normalViewGeometry is used internally to construct the normalView, so not honoring material sidedness simplifies the process, besides being used in other examples like webgpu_tsl_earth of the normalWorldGeometry variant for some optimization techniques this may not be desired honoring material sideness, not making it private can help in more specific cases.

The developer could still use the function directionToFaceDirection() for honor the material sidedness.

const objectNormalView = directionToFaceDirection( normalViewGeometry );

[WestLangley]

The word "transformed" was removed. Is that OK, or do you want the word restored?

[sunag]

Its ok for me. If we are going to remove the term transformed, I think it would be better to modify the description of nodes with the *Geometry suffix so that it is explicit that they are not modified with skinned or morph.

[WestLangley]

Yes, that is why I removed the term.

And I mentioned this because with this PR normalView and normalViewGeometry now have identical descriptions -- as do normalWorld and normalWorldGeometry.

I do not know how to describe the accessors having the *Geometry suffix. With the exception of the three.js roughness calculation, I am not aware of any other use cases in the literature where one would need them.

This is why I asked if you would consider removing them, and using them only internally. That would be my preference.

[sunag]

It is definitely something very specific and I think each engine assigns a name to it, Unreal uses Pre-Skinned Normal for similar purpose and gives some examples using tri-planar texture here. I think it is useful that we have it, as we saw this was used to optimize the code in some examples like webgpu_tsl_earth, webgpu_reflection and the background shader, so it is positive.

[WestLangley]

@sunag OK. Do you like the Pre-Skinned terminology? I can refer to it as the "pre-skinned vertex normal of the currently-rendered object in view space."

[sunag]

I’d like it to be automatic for the user to understand that the Geometry suffix does not process vertices for skinned, morphed, or custom transformations. Pre-Skinned seems to only refer to skinned meshes. Maybe we could add something like this?

/**
 * TSL object that represents the vertex normal of the currently rendered object in view space.
 * 
 * Nodes with the *Geometry suffix do not process skinned, morphed, or custom vertex transformations.
 *
 * @tsl

This is present in other places as well as positionGeometry.

[WestLangley]

@sunag Unfortunately, this is leading to more questions for me..

Rather than continuing with this back-and-forth, I'd prefer to merge this PR for now, and then wait for you to add clarifications in a follow-up PR. Hopefully, I will then be able to better understand your intentions. 🙏