Documentation: Suggest common or required texture color spaces

Description

In the color management documentation, under "input color space", we give general guidelines on when to use different color spaces for different textures.

Color textures: PNG or JPEG Textures containing color information (like .map or .emissiveMap) use the closed domain sRGB color space, and must be annotated with texture.colorSpace = SRGBColorSpace. Formats like OpenEXR (sometimes used for .envMap or .lightMap) use the Linear-sRGB color space indicated with texture.colorSpace = LinearSRGBColorSpace, and may contain values in the open domain [0,∞].

Non-color textures: Textures that do not store color information (like .normalMap or .roughnessMap) do not have an associated color space, and generally use the (default) texture annotation of texture.colorSpace = NoColorSpace. In rare cases, non-color data may be represented with other nonlinear encodings for technical reasons.

While that's good background for users to understand, not every user is going to read through that page, and I think we could do better at providing in-context help in the Material documentation.

Solution

On the documentation page for each Material, for each of the .map, .normalMap, ... and other texture property descriptions, add a sentence describing which colorspaces to use. In some cases there's a single correct choice, in other cases multiple choices are valid but one choice is more common than others if you're not sure what to use.

Since there are a lot of these properties, I'd like to get agreement on the wording before opening that PR. Suggestions, for a couple example textures, below;

.map : Texture The color map. May optionally include an alpha channel, typically combined with .transparent or .alphaTest. Default is null. The texture map color is modulated by the diffuse .color. This texture contains color, and is usually assigned .colorSpace = SRGBColorSpace, but other color spaces are also supported.

.emissiveMap : Texture Set emissive (glow) map. Default is null. The emissive map color is modulated by the emissive color and the emissive intensity. If you have an emissive map, be sure to set the emissive color to something other than black. This texture contains color, and is usually assigned .colorSpace = SRGBColorSpace, but other color spaces are also supported.

.normalMap : Texture The texture to create a normal map. The RGB values affect the surface normal for each pixel fragment and change the way the color is lit. Normal maps do not change the actual shape of the surface, only the lighting. In case the material has a normal map authored using the left handed convention, the y component of normalScale should be negated to compensate for the different handedness. This texture contains non-color data, and must be assigned .colorSpace = NoColorSpace.

Alternatives

list all texture color spaces in the color management guide?
https://github.com/mrdoob/three.js/pull/25857

Additional context

Does it sound OK to add wording about color spaces, as shown in bold above, to each material texture's documentation?

/cc @WestLangley

mrdoob / three.js