Difference between revisions of "CanvasFormat"

(Added new constants available in 0.10.0.)
m
 
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
{{newin|[[0.9.2]]|092|type=enum}}
+
{{newin|[[0.9.0]]|090|type=enum}}
 +
{{deprecatedin|[[11.0]]|110|text=It has been superseded by [[PixelFormat]].}}
 
[[Canvas]] formats.
 
[[Canvas]] formats.
 
== Constants ==
 
== Constants ==
−
;normal: The default Canvas format - an alias for the <code>rgba8</code> format, normally.
+
;normal: The default Canvas format - usually an alias for the <code>rgba8</code> format, or the <code>srgb</code> format if [[love.graphics.isGammaCorrect|gamma-correct rendering]] is enabled in LÖVE [[0.10.0]] and newer.
−
;rgba8: 8 bits per channel (32 bpp) RGBA. Color channel values range from 0-255 (0-1 in shaders.)
+
;hdr: A format suitable for high dynamic range content - an alias for the <code>rgba16f</code> format, normally.
 +
{{New feature|0.9.2|
 +
;rgba8: 8 bits per channel (32 bpp) RGBA. Color channel values range from 0-255 (0-1 in shaders).
 
;rgba4: 4 bits per channel (16 bpp) RGBA.
 
;rgba4: 4 bits per channel (16 bpp) RGBA.
−
;rgb5a1: RGB with 5 bits each, and a 1-bit alpha channel (16 bpp.)
+
;rgb5a1: RGB with 5 bits each, and a 1-bit alpha channel (16 bpp).
 
;rgb565: RGB with 5, 6, and 5 bits each, respectively (16 bpp). There is no alpha channel in this format.
 
;rgb565: RGB with 5, 6, and 5 bits each, respectively (16 bpp). There is no alpha channel in this format.
−
;rgb10a2: RGB with 10 bits per channel, and a 2-bit alpha channel (32 bpp.)
+
;rgb10a2: RGB with 10 bits per channel, and a 2-bit alpha channel (32 bpp).
−
;hdr: A format suitable for high dynamic range content - an alias for the <code>rgba16f</code> format, normally.
+
;rgba16f: Floating point RGBA with 16 bits per channel (64 bpp). Color values can range from [-65504, +65504].
−
;rgba16f: Floating point RGBA with 16 bits per channel (64 bpp.) Color values can range from [-infinity, +infinity].
+
;rgba32f: Floating point RGBA with 32 bits per channel (128 bpp).
−
;rgba32f: Floating point RGBA with 32 bits per channel (128 bpp.) Color values can range from [-infinity, +infinity].
+
;rg11b10f: Floating point RGB with 11 bits in the red and green channels, and 10 bits in the blue channel (32 bpp). There is no alpha channel. Color values can range from [0, +65024].
−
;rg11b10f: Floating point RGB with 11 bits in the red and green channels, and 10 bits in the blue channel (32 bpp.) There is no alpha channel. Color values can range from [0, +infinity].
+
;srgb: The same as <code>rgba8</code>, but the Canvas is ''interpreted'' as being in the sRGB color space. Everything drawn to the Canvas will be converted from linear RGB to sRGB. When the Canvas is drawn (or used in a shader), it will be decoded from sRGB to linear RGB. This reduces color banding when doing gamma-correct rendering, since sRGB encoding has more precision than linear RGB for darker colors.
−
;srgb: The same as <code>rgba8</code>, but the Canvas is ''interpreted'' as being in the sRGB color space. Everything drawn to the Canvas will be converted from linear RGB to sRGB. When the Canvas is drawn (or used in a shader), it will be decoded from sRGB to linear RGB.
+
}}
−
{{newin|[[0.10.0]]|100|type=constants|plural=y}}
+
{{New feature|0.10.0|
−
;r8: Single-channel red format (8 bpp.)
+
;r8: Single-channel (red component) format (8 bpp).
−
;rg8: Two channel red and green format with 8 bits per channel (16 bpp.)
+
;rg8: Two channels (red and green components) with 8 bits per channel (16 bpp).
−
;r16f: Floating point 16 bit format with a single red channel (16 bpp.) Color values can range rom [-infinity, +infinity].
+
;r16f: Floating point single-channel format (16 bpp). Color values can range from [-65504, +65504].
−
;rg16f: Floating point 16 bit per channel format with two channels (32 bpp.) Color values can range rom [-infinity, +infinity].
+
;rg16f: Floating point two-channel format with 16 bits per channel (32 bpp). Color values can range from [-65504, +65504].
−
;r32f: Floating point 32 bit format with a single red channel (32 bpp.) Color values can range rom [-infinity, +infinity].
+
;r32f: Floating point single-channel format (32 bpp).
−
;rg32f: Floating point 32 bit per channel format with two channels (64 bpp.) Color values can range rom [-infinity, +infinity].
+
;rg32f: Floating point two-channel format with 32 bits per channel (64 bpp).
 +
}}
 +
 
 
== Notes ==
 
== Notes ==
−
The 16 bpp formats use half as much VRAM as the 32 bpp formats, but they have significantly lower quality than regular <code>rgba8</code>.
+
The 16 bpp RGB and RGBA formats use half as much VRAM as the 32 bpp RGBA formats, but they have significantly lower quality.
  
 
The HDR / floating point formats are most useful when combined with pixel shaders. Effects such as tonemapped HDR with bloom can be accomplished, or the canvas can be used to store arbitrary non-color data such as positions which can then be used in a custom shader.
 
The HDR / floating point formats are most useful when combined with pixel shaders. Effects such as tonemapped HDR with bloom can be accomplished, or the canvas can be used to store arbitrary non-color data such as positions which can then be used in a custom shader.
Line 29: Line 34:
 
Not all systems support every format. Use [[love.graphics.getCanvasFormats]] to check before creating the Canvas.
 
Not all systems support every format. Use [[love.graphics.getCanvasFormats]] to check before creating the Canvas.
  
−
In general, <code>rgba8</code>, <code>rgba4</code>, <code>rgb5a1</code>, and <code>rgb10a2</code> are supported everywhere. The floating-point formats (<code>rgba16f</code>, <code>rgba32f</code>, and <code>rg11b10f</code>) and <code>srgb</code> are supported on graphics cards capable of OpenGL 3+ / DirectX 10+ (nvidia GeForce 8000 series and up, ATI/AMD HD 2000 series and up, and the Intel HD 2000 and up.) <code>rgb565</code> is often only supported on OpenGL ES or very new desktop OpenGL drivers.
+
In general, <code>rgba8</code>, <code>rgba4</code>, and <code>rgb5a1</code> are supported everywhere. <code>rgb10a2</code> is also supported everywhere on desktop platforms.
 +
 
 +
The regular single- and two-channel formats (<code>r8</code> and <code>rg8</code>), as well as the <code>srgb</code> format, are supported on desktop graphics cards capable of OpenGL 3+ / DirectX 10+ (nvidia GeForce 8000 series and up, ATI/AMD HD 2000 series and up, and the Intel HD 2000 and up), and mobile GPUs capable of OpenGL ES 3.
 +
 
 +
The floating-point formats (<code>rgba16f</code>, <code>rgba32f</code>, <code>rg11b10f</code>, <code>r16f</code>, <code>rg16f</code>, <code>r32f</code>, and <code>rg32f</code>) are supported on OpenGL 3-capable desktop graphics cards, and some OpenGL ES 3 mobile GPUs. The 32-bit-per-channel floating point formats are rarely supported on mobile devices.
 +
 
 +
<code>rgb565</code> is often only supported on OpenGL ES / mobile devices, or with very new desktop OpenGL drivers.
  
 
== See Also ==
 
== See Also ==

Latest revision as of 02:09, 6 July 2019

Available since LÖVE 0.9.0
This enum is not supported in earlier versions.
Deprecated in LÖVE 11.0
It has been superseded by PixelFormat..

Canvas formats.

Constants

normal
The default Canvas format - usually an alias for the rgba8 format, or the srgb format if gamma-correct rendering is enabled in LÖVE 0.10.0 and newer.
hdr
A format suitable for high dynamic range content - an alias for the rgba16f format, normally.
Available since LÖVE 0.9.2
rgba8
8 bits per channel (32 bpp) RGBA. Color channel values range from 0-255 (0-1 in shaders).
rgba4
4 bits per channel (16 bpp) RGBA.
rgb5a1
RGB with 5 bits each, and a 1-bit alpha channel (16 bpp).
rgb565
RGB with 5, 6, and 5 bits each, respectively (16 bpp). There is no alpha channel in this format.
rgb10a2
RGB with 10 bits per channel, and a 2-bit alpha channel (32 bpp).
rgba16f
Floating point RGBA with 16 bits per channel (64 bpp). Color values can range from [-65504, +65504].
rgba32f
Floating point RGBA with 32 bits per channel (128 bpp).
rg11b10f
Floating point RGB with 11 bits in the red and green channels, and 10 bits in the blue channel (32 bpp). There is no alpha channel. Color values can range from [0, +65024].
srgb
The same as rgba8, but the Canvas is interpreted as being in the sRGB color space. Everything drawn to the Canvas will be converted from linear RGB to sRGB. When the Canvas is drawn (or used in a shader), it will be decoded from sRGB to linear RGB. This reduces color banding when doing gamma-correct rendering, since sRGB encoding has more precision than linear RGB for darker colors.


Available since LÖVE 0.10.0
r8
Single-channel (red component) format (8 bpp).
rg8
Two channels (red and green components) with 8 bits per channel (16 bpp).
r16f
Floating point single-channel format (16 bpp). Color values can range from [-65504, +65504].
rg16f
Floating point two-channel format with 16 bits per channel (32 bpp). Color values can range from [-65504, +65504].
r32f
Floating point single-channel format (32 bpp).
rg32f
Floating point two-channel format with 32 bits per channel (64 bpp).


Notes

The 16 bpp RGB and RGBA formats use half as much VRAM as the 32 bpp RGBA formats, but they have significantly lower quality.

The HDR / floating point formats are most useful when combined with pixel shaders. Effects such as tonemapped HDR with bloom can be accomplished, or the canvas can be used to store arbitrary non-color data such as positions which can then be used in a custom shader.

The sRGB format should only be used when doing gamma-correct rendering, which 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. Read more about gamma-correct rendering here, here, and here.

Not all systems support every format. Use love.graphics.getCanvasFormats to check before creating the Canvas.

In general, rgba8, rgba4, and rgb5a1 are supported everywhere. rgb10a2 is also supported everywhere on desktop platforms.

The regular single- and two-channel formats (r8 and rg8), as well as the srgb format, are supported on desktop graphics cards capable of OpenGL 3+ / DirectX 10+ (nvidia GeForce 8000 series and up, ATI/AMD HD 2000 series and up, and the Intel HD 2000 and up), and mobile GPUs capable of OpenGL ES 3.

The floating-point formats (rgba16f, rgba32f, rg11b10f, r16f, rg16f, r32f, and rg32f) are supported on OpenGL 3-capable desktop graphics cards, and some OpenGL ES 3 mobile GPUs. The 32-bit-per-channel floating point formats are rarely supported on mobile devices.

rgb565 is often only supported on OpenGL ES / mobile devices, or with very new desktop OpenGL drivers.

See Also

Other Languages

Dansk – Deutsch – English – Español – Français – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Polski – Português – Română – Slovenský – Suomi – Svenska – Türkçe – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – ไทย – 日本語 – 正體中文 – 简体中文 – Tiếng Việt – 한국어
More info

Retrieved from "https://love2d.org./w/index.php?title=CanvasFormat&oldid=23343"