documentation on gamma correction incorrect?


the documentation about WebGLRenderer states that:

.gammaInput If set, then it expects that all textures and colors are premultiplied gamma. Default is false.

.gammaOutput If set, then it expects that all textures and colors need to be outputted in premultiplied gamma. Default is false.

My understanding by examining the code is instead that:

  • if gammaInput is true, textures in material are considered sRGB (e.g. diffuseTexture), so the fetched value is linearised before using it in calculations; however, colours (e.g. diffuse color) that are passed to the shader are considered as in linear space.
  • if gammaInput is false, instead, textures and colors are considered as linear
  • if gammaOutput is true, the final color computed by material shaders is gamma-encoded, otherwise not.

If my understanding is correct, I think the documentation is misleading.
In any case, using the MeshStandardMaterial, we should always use gammaOutput=true, right? Otherwise the display will show a wrong color – or are there any other gamma operations outside the shaders?


Author: Fantashit

1 thought on “documentation on gamma correction incorrect?

  1. Yes, the documentation can be improved. Thanks for tracking this down.

    renderer.gammaInput and renderer.gammaOutput were implemented early-on. Later, texture.encoding was added. However, for backward-comparability, gammaInput and gammaOutput remained.

    I think some changes are in order. The following is my understanding of where we want to get to, based on past discussions. Most of the following is already in place.

    1. renderer.gammaInput should be removed (texture.encoding is sufficient)

    2. renderer.gammaOutput should be renamed to renderer.outputEncoding (and default to THREE.sRGBEncoding — or maybe THREE.LinearEncoding — that is debatable)

    3. The RGB channels of the following maps should be assumed to be in sRGB colorspace if the encoding is undefined: (texture.encoding = THREE.sRGBEncoding)

      b. material.envMap (except HDR maps — they need to be decoded, but are in linear space)
      c. material.emissiveMap
      d. future: material.specularMap (when is it changed to a 3-channel map)

    4. Everything else should be assumed to be in linear-RGB colorspace:

      vertex colors
      light.color for directionalLight, pointLight, spotLight, hemisphereLight, areaLight
      alpha channels of color maps
      material.specularMap (for now, only as long as it is a grayscale)
      material.glossinessMap (future)
      HDR environment maps

    This is just my understanding, it is not a decree. 🙂

    Corrections/clarifications are welcome.

    I’m not sure how we should handle encoding if a texture contains per-channel maps that require different encodings — or if that is even an issue…

    /ping @bhouston

Comments are closed.