WebGLRenderer: Add support for rotating env maps.

[Mugen87]

Fixed #16328.

Description

This PR adds a frequent requested feature to WebGLRenderer: The ability to rotate environment maps.

Instead of adding a new property to Texture level, I've realized a more clean approach by adding:

• Scene.backgroundRotation which controls the rotation of the scene's skybox as suggested in CubeTexture orientation #16328 (comment).
• Scene.environmentRotation which controls the rotation of the scene's environment as suggested in WebGLRenderer: Add support for rotating env maps. #27758 (comment).
• envMapRotation for all materials which support envMap.

The new properties are of type Euler. Environment maps in the equirectangular, cube map and cuveUV (PMREM) format can be rotated now.

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

Filesize dev	Filesize PR	Diff
676.4 kB (168.2 kB)	678 kB (168.6 kB)	+1.65 kB

🌳 Bundle size after tree-shaking

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

Filesize dev	Filesize PR	Diff
457.2 kB (111 kB)	458.4 kB (111.3 kB)	+1.2 kB

[WestLangley]

In what coordinate frame is the background Euler rotation applied? I assume you intend it to be the three.js right-hand coordinate frame. In the shader, the coordinate frame is left-handed.

In this PR, the background rotation around the x-axis is backwards from the expected convention. A sign flip may fix that.

[WestLangley]

Do you intend to add support for rotating scene.environment?

[Mugen87]

I assume you intend it to be the three.js right-hand coordinate frame.

Yes. I was a bit unsure about the point of reference when judging the direction of rotations for env maps. I hope the last commit fixes the x-axis issue.

Do you intend to add support for rotating scene.environment?

Users can already achieve that by modifying the new envMapRotation property of their PBR materials. This makes it also consistent with envMapIntensity which is a per-material property only as well.

I would only add an additional option if users struggle with the existing solution.

[mrdoob]

Hmmm... I think scene.environmentRotation is more likely to be used than material.envMapRotation.

[mrdoob]

I think it would be better to add support for scene.environmentRotation first, and after that we can see if people really need material.envMapRotation.

[Mugen87]

The problem with this approach is that Scene.environment only applies to MeshStandardMaterial. Hence, basic, lambert and phong materials which do support environment maps can't align their reflections to the rotated background.

How about we add Scene.environmentRotation additionally?

[Mugen87]

I also think it's in general more flexible to have the ability to rotate environment maps directly in the material (if we don't provide a per texture setting).

[mrdoob]

How about we add Scene.environmentRotation additionally? When set, it overshadows MeshStandardMateraial.envMapRotation like with envMap.

That sounds good to me.

I guess scene.environmentRotation would be new Euler() by default so the renderer will actually have to check if scene.environment === null to then use material.envMap and material.envMapRotation, right?

[Mugen87]

Yes, I think we can nicely put this check in getProgram() and save the result in the material properties.

[Mugen87]

Okay, Scene.environmentRotation has been added. It only affects physical materials and only if Scene.environment is used.

[WestLangley]

The reflections and rotations are not correct. I'll file a PR in an attempted fix.

Unfortunately, getting these calculations correct has taken considerable effort...