Difference between revisions of "love.math.linearToGamma"

(Created page)
 
(Updated for 11.0)
 
(3 intermediate revisions by the same user not shown)
Line 6: Line 6:
 
Read more about gamma-correct rendering [http://http.developer.nvidia.com/GPUGems3/gpugems3_ch24.html here], [http://filmicgames.com/archives/299 here], and [http://renderwonk.com/blog/index.php/archive/adventures-with-gamma-correct-rendering/ here].
 
Read more about gamma-correct rendering [http://http.developer.nvidia.com/GPUGems3/gpugems3_ch24.html here], [http://filmicgames.com/archives/299 here], and [http://renderwonk.com/blog/index.php/archive/adventures-with-gamma-correct-rendering/ here].
  
 +
In versions prior to [[11.0]], color component values were within the range of 0 to 255 instead of 0 to 1.
 
{{notice|Gamma-correct rendering is an advanced topic and it's easy to get color-spaces mixed up. If you're not sure whether you need this, you might want to avoid it.}}
 
{{notice|Gamma-correct rendering is an advanced topic and it's easy to get color-spaces mixed up. If you're not sure whether you need this, you might want to avoid it.}}
 
== Function ==
 
== Function ==
Line 49: Line 50:
 
<source lang="lua">
 
<source lang="lua">
 
local function PremultiplyLinearPixel(x, y, r, g, b, a)
 
local function PremultiplyLinearPixel(x, y, r, g, b, a)
   r = r * a / 255
+
   r = r * a
   g = g * a / 255
+
   g = g * a
   b = b * a / 255
+
   b = b * a
 
   return r, g, b, a
 
   return r, g, b, a
 
end
 
end
Line 57: Line 58:
 
local function PremultiplyGammaPixel(x, y, r, g, b, a)
 
local function PremultiplyGammaPixel(x, y, r, g, b, a)
 
   r, g, b = love.math.gammaToLinear(r, g, b)
 
   r, g, b = love.math.gammaToLinear(r, g, b)
   r = r * a / 255
+
   r = r * a
   g = g * a / 255
+
   g = g * a
   b = b * a / 255
+
   b = b * a
 
   r, g, b = love.math.linearToGamma(r, g, b)
 
   r, g, b = love.math.linearToGamma(r, g, b)
 
   return r, g, b, a
 
   return r, g, b, a
 
end
 
end
  
-- Loads an image and pre-multiplies its RGB values with its alpha, for use with the 'premultiplied' alpha blend mode.
+
-- Loads an image and pre-multiplies its RGB values with its alpha, for use with the ('alpha', 'premultiplied') blend mode.
 
-- The multiplication correctly accounts for the color-space of the image.
 
-- The multiplication correctly accounts for the color-space of the image.
function NewPremultipliedImage(filepath, format)
+
function NewPremultipliedImage(filepath, flags)
 
     local imagedata = love.image.newImageData(filepath)
 
     local imagedata = love.image.newImageData(filepath)
  
     local mapfunction = format == "srgb" and PremultiplyGammaPixel or PremultiplyLinearPixel
+
     local mapfunction = (flags and flags.linear) and PremultiplyLinearPixel or PremultiplyGammaPixel
 
     imagedata:mapPixel(mapfunction)
 
     imagedata:mapPixel(mapfunction)
  
     return love.graphics.newImage(imagedata, format)
+
     return love.graphics.newImage(imagedata, flags)
 
end
 
end
  
-- This assumes gamma-correct rendering (with the sRGB window flag) is being done.
+
image = NewPremultipliedImage("pig.png")
image = NewPremultipliedImage("pig.png", "srgb")
 
 
</source>
 
</source>
  
Line 83: Line 83:
 
* [[love.math.gammaToLinear]]
 
* [[love.math.gammaToLinear]]
 
[[Category:Functions]]
 
[[Category:Functions]]
{{#set:Description=Converts a color from gamma-space (sRGB) to linear-space (RGB).}}
+
{{#set:Description=Converts a color from linear-space (RGB) to gamma-space (sRGB).}}
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|love.math.linearToGamma}}
 
{{i18n|love.math.linearToGamma}}

Latest revision as of 20:31, 1 April 2018

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

Converts a color from linear-space (RGB) to gamma-space (sRGB). This is useful when storing linear RGB color values in an image, because the linear RGB color space has less precision than sRGB for dark colors, which can result in noticeable color banding when drawing.

In general, colors chosen based on what they look like on-screen are already in gamma-space and should not be double-converted. Colors calculated using math are often in the linear RGB space.

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

In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

O.png Gamma-correct rendering is an advanced topic and it's easy to get color-spaces mixed up. If you're not sure whether you need this, you might want to avoid it.  


Function

Synopsis

cr, cg, cb = love.math.linearToGamma( lr, lg, lb )

Arguments

number lr
The red channel of the linear RGB color to convert.
number lg
The green channel of the linear RGB color to convert.
number lb
The blue channel of the linear RGB color to convert.

Returns

number cr
The red channel of the converted color in gamma sRGB space.
number cg
The green channel of the converted color in gamma sRGB space.
number cb
The blue channel of the converted color in gamma sRGB space.

Notes

An alpha value can be passed into the function as a fourth argument, but it will be returned unchanged because alpha is always linear.

Function

Synopsis

cr, cg, cb = love.math.linearToGamma( color )

Arguments

table color
An array with the red, green, and blue channels of the linear RGB color to convert.

Returns

number cr
The red channel of the converted color in gamma sRGB space.
number cg
The green channel of the converted color in gamma sRGB space.
number cb
The blue channel of the converted color in gamma sRGB space.

Function

Synopsis

c = love.math.linearToGamma( lc )

Arguments

number lc
The value of a color channel in linear RGB space to convert.

Returns

number c
The value of the color channel in gamma sRGB space.

Examples

Pre-multiply an image's alpha with its RGB values in linear RGB space

local function PremultiplyLinearPixel(x, y, r, g, b, a)
   r = r * a
   g = g * a
   b = b * a
   return r, g, b, a
end

local function PremultiplyGammaPixel(x, y, r, g, b, a)
   r, g, b = love.math.gammaToLinear(r, g, b)
   r = r * a
   g = g * a
   b = b * a
   r, g, b = love.math.linearToGamma(r, g, b)
   return r, g, b, a
end

-- Loads an image and pre-multiplies its RGB values with its alpha, for use with the ('alpha', 'premultiplied') blend mode.
-- The multiplication correctly accounts for the color-space of the image.
function NewPremultipliedImage(filepath, flags)
    local imagedata = love.image.newImageData(filepath)

    local mapfunction = (flags and flags.linear) and PremultiplyLinearPixel or PremultiplyGammaPixel
    imagedata:mapPixel(mapfunction)

    return love.graphics.newImage(imagedata, flags)
end

image = NewPremultipliedImage("pig.png")

See Also

Other Languages