Documentation: Suggest common or required texture color spaces

[donmccurdy]

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?
• Material: Infer texture color space (WIP) #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

[WestLangley]

I think your suggestion is fine.

Regarding wording, I like to be very explicit. Maybe something like the following...

This texture contains color data, and you must specify the texture's color space by assigning a value to the texture's .colorSpace property. For example, texture.colorSpace = THREE.SRGBColorSpace. See <some_link> for the supported color space options.