Enhance texture/material transform documentation

[pailhead]

After seeing this:

https://github.com/mrdoob/three.js/blob/dev/src/renderers/WebGLRenderer.js#L1991-L2061

I propose adding some kind of documentation to let the world know that there is magic happening under the hood.

Texture classes have a transform property. Materials can use multiple textures, but also have a single transform property.
Because a single material, with a single transform property can have many textures with many unique transform properties - Three.js does voodoo magic under the hood to chose which texture's transform to honor.
This is the list [insert list].

edit

1. map
2. specularMap
3. displacementMap
4. normalMap
5. bumpMap
6. roughnessMap
7. metalnessMap
8. alphaMap
9. emissiveMap

Maybe warn the user that if they have some kind of transform on the emissive map, it will be completely ignored, and the user can expect to see the transform belonging to any other 8 map slots that come before?

Three.js version

• Dev
• r89
• ...

Browser

• All of them
• Chrome
• Firefox
• Internet Explorer

OS

• All of them
• Windows
• macOS
• Linux
• Android
• iOS

Hardware Requirements (graphics card, VR Device, ...)

[looeee]

Documenting this sounds like a good idea, but describing it as 'voodoo magic' is not really acceptable... In my opinion 😛

[WestLangley]

See https://stackoverflow.com/questions/14371385/can-a-three-js-material-have-separate-repeat-values-for-a-bump-map-and-a-texture/14372235#14372235

[pailhead]

but describing it as 'voodoo magic'

J/k was just stubbing it :) but the list does seem somewhat arbitrary hence the term

[pailhead]

@WestLangley

That is an interesting point, all shader related problems can be solved by simply writing shaders. I’d suggest looking into onBeforeCompile instead of writing a shader from scratch though.

Still, as is this seems like tribal knowledge. I know your SO answers are widely referenced but maybe the information in that answer should be in the actual documentation.

[WestLangley]

@pailhead Would you be willing to improve the docs? The SO link is just suggested text you can copy if you want.

[pailhead]

It might be worth revisiting what this transformation is and how it behaves.

three.js/src/renderers/shaders/ShaderChunk/uv_vertex.glsl

Line 3 in 1c7a88b

vUv = ( uvTransform * vec3( uv, 1 ) ).xy;

I would like to use a texture!

Thats super awesome! Do you want to scale it, offset it and/or rotate it, perhaps?

(opt1) I have absolutely no idea what you're talking about....

Thats's fine! I'm just going to set up an identity matrix in the shader and add a few more instructions here and there... You don't have to worry about a thing!

(opt2) Yes please! I have a bunch of textures that need to go into channel uv0 which need to tile and repeat and stuff, you see they're representing brick, and all these elements that make it look all nice and slightly shiny, bumpy and such. But then i have a light map that needs to not tile, but be in this whole other chan....

Say no more! I've got just the thing you need! Texture has a number of properties that you can mutate, one of them is a Vector2 another one is a float etc.

(opt2) Cool. I have 4 textures total, so, but i'm going to reuse them on multiple objects, with different offsets.

Ahh, in that case you have to first clone the materials then also clone the textures.

(opt2) Wait what? So first I need to mutate these 4 textures the same, to be able to use them on one object to begin with?

Well... technically you don't have to, I'm ever going to use just one of them to apply the transformation.

(opt2) Hmm... which one?

Hold on, consult [this] SO answer, I don't really know. :(. If you want to be safe, just make sure they all have the exact same values, then you won't care which one I use.

(opt2) So then i have to clone all four of these, to use them in another material?

Yeah... Also, use some inspector to make sure the textures aren't actually duplicated, I have some history with that...

(opt2) Err..

If you don't like it you can always write some GLSL,..

Meh, probably didnt explain it well, but maybe having something like:

const myMaterial = new THREE.Material({
   map: someTexture,
   anotherMap: anotherTexture,
   textureTransform: wantTransformOrNoIdeaWhatItIs ? 
      new THREE.TextureTransform({position,rotation,offset}) :
      null,
})

or

const myMaterial = new THREE.Material({
   map: someMap,
   mapChannel: 0,
   anotherMap: anotherMap,
   anotherMapChannel: 1,
   thirdMap: thirdMap,
   thirdMapChannel: 2,
   textureTransform: [ new Transform(), null, new Transform()],
})

Or even

const anotherTexture = new THREE.Texture({ transform: new THREE.TextureTransform() })

[pailhead]

@WestLangley

uhh i may have some bias towards how it works today. Documenting at least, may give me some piece, so in lieu of rethinking this, yes i can document this.
I fear that the explanation may end up sounding a bit confusing though, (long list, priorities, edge cases etc) was hoping that might point towards a flaw and get us to rethink this.

btw no offense, i thought i can make it sound funny :D

[pailhead]

This discussion seems to have been resurrected in #14214

[pailhead]

There's also an example submitted to show the users how they can override this behavior.
#14174