Difference between revisions of "love.graphics.isGammaCorrect"

m (Notes)
(Notes: Updated links)
 
(6 intermediate revisions by 3 users not shown)
Line 2: Line 2:
 
Gets whether gamma-correct rendering is supported and enabled. It can be enabled by setting <code>t.gammacorrect = true</code> in [[love.conf]].
 
Gets whether gamma-correct rendering is supported and enabled. It can be enabled by setting <code>t.gammacorrect = true</code> in [[love.conf]].
  
Not all devices support gamma-correct rendering, in which case it will be automatically disabled and this function will return false. It is supported on desktop systems which have graphics cards that are capable of using OpenGL 3 / DIrectX 10, and iOS devices that can use OpenGL ES 3.
+
Not all devices support gamma-correct rendering, in which case it will be automatically disabled and this function will return false. It is supported on desktop systems which have graphics cards that are capable of using OpenGL 3 / DirectX 10, and iOS devices that can use OpenGL ES 3.
  
 
== Function ==
 
== Function ==
Line 25: Line 25:
  
 
* [[Canvas]]es which use the "normal" or "srgb" [[CanvasFormat]] will have their content blended in linear RGB and the result will be stored in the canvas in sRGB, when drawing to them. When the Canvas itself is drawn, its pixel colors will be converted from sRGB to linear RGB in the same manner as Images. Keeping the canvas pixel data stored as sRGB allows for better precision (less banding) for darker colors compared to "rgba8".
 
* [[Canvas]]es which use the "normal" or "srgb" [[CanvasFormat]] will have their content blended in linear RGB and the result will be stored in the canvas in sRGB, when drawing to them. When the Canvas itself is drawn, its pixel colors will be converted from sRGB to linear RGB in the same manner as Images. Keeping the canvas pixel data stored as sRGB allows for better precision (less banding) for darker colors compared to "rgba8".
 +
  
 
Because most conversions are automatically handled, your own code doesn't need to worry about sRGB and linear RGB color conversions when gamma-correct rendering is enabled, except in a couple cases:
 
Because most conversions are automatically handled, your own code doesn't need to worry about sRGB and linear RGB color conversions when gamma-correct rendering is enabled, except in a couple cases:
Line 32: Line 33:
 
* If  a [[Shader]] is used which has uniform / extern variables or other variables that are meant to be used as colors, and [[Shader:sendColor]] isn't used.
 
* If  a [[Shader]] is used which has uniform / extern variables or other variables that are meant to be used as colors, and [[Shader:sendColor]] isn't used.
  
In both cases, [[love.math.gammaToLinear]] can be used to convert color values to linear RGB in Lua code, or the <code>gammaCorrectColor</code> (or <code>unGammaCorrectColor</code> if necessary) shader functions can be used inside shader code. Those shader functions ''only'' do conversions if gamma-correct rendering is actually enabled. The <code>LOVE_GAMMA_CORRECT</code> shader preprocessor define will be set if so.
+
In both cases, [[love.math.gammaToLinear]] can be used to convert color values to linear RGB in Lua code.
 +
 
 +
 
 +
In shader code the following functions are available if manual conversions are necessary. They ''only'' do conversions if gamma-correct rendering is actually enabled. The <code>LOVE_GAMMA_CORRECT</code> shader preprocessor define will be set if so:
 +
* <code>float/vec3/vec4 gammaCorrectColor(float/vec3/vec4 color)</code> (performant but less precise).
 +
* <code>float/vec3/vec4 gammaCorrectColorPrecise(float/vec3/vec4 color)</code> (slower but accurate, equivalent to <code>love.math.gammaToLinear</code>).
 +
* <code>float/vec3/vec4 unGammaCorrectColor(float/vec3/vec4 color)</code> (performant but less precise).
 +
* <code>float/vec3/vec4 unGammaCorrectColorPrecise(float/vec3/vec4 color)</code> (slower but accurate, equivalent to <code>love.math.linearToGamma</code>).
 +
 
 +
 
 +
Read more about gamma-correct rendering [https://developer.nvidia.com/gpugems/gpugems3/part-iv-image-effects/chapter-24-importance-being-linear here], [http://filmicworlds.com/blog/linear-space-lighting-i-e-gamma/ here], and [http://renderwonk.com/blog/index.php/archive/adventures-with-gamma-correct-rendering/ here].
  
 
== See Also ==
 
== See Also ==
Line 39: Line 50:
 
* [[love.math.gammaToLinear]]
 
* [[love.math.gammaToLinear]]
 
* [[love.math.linearToGamma]]
 
* [[love.math.linearToGamma]]
 +
* [[Shader:sendColor]]
 
[[Category:Functions]]
 
[[Category:Functions]]
 
{{#set:Description=Gets whether gamma-correct rendering is enabled.}}
 
{{#set:Description=Gets whether gamma-correct rendering is enabled.}}
 
{{#set:Sub-Category=State}}
 
{{#set:Sub-Category=State}}
 +
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|love.graphics.isGammaCorrect}}
 
{{i18n|love.graphics.isGammaCorrect}}

Latest revision as of 05:23, 4 February 2022

Available since LÖVE 0.10.0
This function is not supported in earlier versions.

Gets whether gamma-correct rendering is supported and enabled. It can be enabled by setting t.gammacorrect = true in love.conf.

Not all devices support gamma-correct rendering, in which case it will be automatically disabled and this function will return false. It is supported on desktop systems which have graphics cards that are capable of using OpenGL 3 / DirectX 10, and iOS devices that can use OpenGL ES 3.

Function

Synopsis

gammacorrect = love.graphics.isGammaCorrect( )

Arguments

None.

Returns

boolean gammacorrect
True if gamma-correct rendering is supported and was enabled in love.conf, false otherwise.

Notes

When gamma-correct rendering is enabled, many functions and objects perform automatic color conversion between sRGB and linear RGB in order for blending and shader math to be mathematically correct (which they aren't if it's not enabled.)

  • Images will have their colors automatically converted from sRGB to linear RGB when drawing them (and when getting their pixels in a Shader), unless the flag linear = true is set when creating the Image.
  • Everything drawn to the screen will be blended in linear RGB and then the result will be converted to sRGB for display.
  • Canvases which use the "normal" or "srgb" CanvasFormat will have their content blended in linear RGB and the result will be stored in the canvas in sRGB, when drawing to them. When the Canvas itself is drawn, its pixel colors will be converted from sRGB to linear RGB in the same manner as Images. Keeping the canvas pixel data stored as sRGB allows for better precision (less banding) for darker colors compared to "rgba8".


Because most conversions are automatically handled, your own code doesn't need to worry about sRGB and linear RGB color conversions when gamma-correct rendering is enabled, except in a couple cases:

  • If a Mesh with custom vertex attributes is used and one of the attributes is meant to be used as a color in a Shader, and the attribute isn't named "VertexColor".
  • If a Shader is used which has uniform / extern variables or other variables that are meant to be used as colors, and Shader:sendColor isn't used.

In both cases, love.math.gammaToLinear can be used to convert color values to linear RGB in Lua code.


In shader code the following functions are available if manual conversions are necessary. They only do conversions if gamma-correct rendering is actually enabled. The LOVE_GAMMA_CORRECT shader preprocessor define will be set if so:

  • float/vec3/vec4 gammaCorrectColor(float/vec3/vec4 color) (performant but less precise).
  • float/vec3/vec4 gammaCorrectColorPrecise(float/vec3/vec4 color) (slower but accurate, equivalent to love.math.gammaToLinear).
  • float/vec3/vec4 unGammaCorrectColor(float/vec3/vec4 color) (performant but less precise).
  • float/vec3/vec4 unGammaCorrectColorPrecise(float/vec3/vec4 color) (slower but accurate, equivalent to love.math.linearToGamma).


Read more about gamma-correct rendering here, here, and here.

See Also


Other Languages