Difference between revisions of "PixelFormat"

m
m (First occurence of 11.3 and 11.4 is hyperlink.)
 
(13 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
{{newin|[[0.11.0]]|110|type=enum|text=This enum replaces [[CanvasFormat]] and [[CompressedImageFormat]]}}
+
{{newin|[[11.0]]|110|type=enum|text=This enum replaces [[CanvasFormat]] and [[CompressedImageFormat]]}}
 
Pixel formats for [[Texture]]s, [[ImageData]], and [[CompressedImageData]].
 
Pixel formats for [[Texture]]s, [[ImageData]], and [[CompressedImageData]].
−
 
−
{{notice|This page is a work-in-progress.}}
 
  
 
== Normal color formats ==
 
== Normal color formats ==
Line 14: Line 12:
 
! Usable with [[ImageData]]
 
! Usable with [[ImageData]]
 
! Note(s)
 
! Note(s)
 +
|-
 +
|normal
 +
|4
 +
|32
 +
|[0, 1]
 +
|Yes
 +
|
 +
|Alias for <code>rgba8</code>, or <code>srgba8</code> if [[love.graphics.isGammaCorrect|gamma-correct rendering]] is enabled.
 
|-
 
|-
 
|r8
 
|r8
Line 20: Line 26:
 
|[0, 1]
 
|[0, 1]
 
|Yes
 
|Yes
−
|
+
|[[11.3]]
 
|
 
|
 
|-
 
|-
Line 28: Line 34:
 
|[0, 1]
 
|[0, 1]
 
|Yes
 
|Yes
−
|
+
|11.3
 
|
 
|
 
|-
 
|-
Line 46: Line 52:
 
|
 
|
 
|[[love.graphics.isGammaCorrect|gamma-correct]] version of rgba8.
 
|[[love.graphics.isGammaCorrect|gamma-correct]] version of rgba8.
 +
|-
 +
|r16
 +
|1
 +
|16
 +
|[0, 1]
 +
|[[11.4]]
 +
|11.3
 +
|
 +
|-
 +
|rg16
 +
|2
 +
|32
 +
|[0, 1]
 +
|11.4
 +
|11.3
 +
|
 
|-
 
|-
 
|rgba16
 
|rgba16
Line 51: Line 73:
 
|64
 
|64
 
|[0, 1]
 
|[0, 1]
−
|
+
|11.4
 
|Yes
 
|Yes
 
|
 
|
Line 58: Line 80:
 
|1
 
|1
 
|16
 
|16
−
|[-65504, +65504]
+
|[-65504, +65504]*
 
|Yes
 
|Yes
−
|
+
|11.3
 
|
 
|
 
|-
 
|-
Line 66: Line 88:
 
|2
 
|2
 
|32
 
|32
−
|[-65504, +65504]
+
|[-65504, +65504]*
 
|Yes
 
|Yes
−
|
+
|11.3
 
|
 
|
 
|-
 
|-
Line 74: Line 96:
 
|4
 
|4
 
|64
 
|64
−
|[-65504, +65504]
+
|[-65504, +65504]*
 
|Yes
 
|Yes
 
|Yes
 
|Yes
Line 82: Line 104:
 
|1
 
|1
 
|32
 
|32
−
|[-infinity, +infinity]
+
|[-3.4028235e38, 3.4028235e38]*
 
|Yes
 
|Yes
−
|
+
|11.3
 
|
 
|
 
|-
 
|-
Line 90: Line 112:
 
|2
 
|2
 
|64
 
|64
−
|[-infinity, +infinity]
+
|[-3.4028235e38, 3.4028235e38]*
 
|Yes
 
|Yes
−
|
+
|11.3
 
|
 
|
 
|-
 
|-
Line 98: Line 120:
 
|4
 
|4
 
|128
 
|128
−
|[-infinity, +infinity]
+
|[-3.4028235e38, 3.4028235e38]*
 
|Yes
 
|Yes
 
|Yes
 
|Yes
 
|
 
|
 +
|-
 +
|la8
 +
|2
 +
|16
 +
|[0, 1]
 +
|
 +
|
 +
| Used by [[GlyphData]]. Same as <code>rg8</code>, but accessed as (L, L, L, A)
 
|-
 
|-
 
|rgba4
 
|rgba4
Line 108: Line 138:
 
|[0, 1]
 
|[0, 1]
 
|Yes
 
|Yes
−
|
+
|11.3
 
|
 
|
 
|-
 
|-
Line 116: Line 146:
 
|[0, 1]
 
|[0, 1]
 
|Yes
 
|Yes
−
|
+
|11.3
 
|
 
|
 
|-
 
|-
Line 124: Line 154:
 
|[0, 1]
 
|[0, 1]
 
|Yes
 
|Yes
−
|
+
|11.3
 
|
 
|
 
|-
 
|-
Line 132: Line 162:
 
|[0, 1]
 
|[0, 1]
 
|Yes
 
|Yes
−
|
+
|11.3
 
|
 
|
 
|-
 
|-
Line 138: Line 168:
 
|3
 
|3
 
|32
 
|32
−
|[0, 65024]
+
|[0, 65024]**
 
|Yes
 
|Yes
−
|
+
|11.3
 
|
 
|
 
|}
 
|}
 +
 +
<nowiki>*</nowiki> -infinity and +infinity are also valid values.<br>
 +
<nowiki>**</nowiki> +infinity is also a valid value.
  
 
== Depth / stencil formats ==
 
== Depth / stencil formats ==
−
All depth and stencil pixel formats are only usable in [[Canvas]]es. They are [[Texture:isReadable|non-readable]] by default, and Canvases with a depth/stencil format created with the [[love.graphics.newCanvas|readable flag]] can only access the depth values of their pixels in shaders (stencil values are not readable no matter what).
+
All depth and stencil pixel formats are only usable in [[Canvas]]es.
 +
 
 +
They are [[Texture:isReadable|non-readable]] by default, and Canvases with a depth/stencil format created with the [[love.graphics.newCanvas|readable flag]] can only access the depth values of their pixels in shaders (stencil values are not readable no matter what).
 
=== Constants ===
 
=== Constants ===
 
{| class="wikitable"
 
{| class="wikitable"
Line 192: Line 227:
  
 
== Compressed formats ==
 
== Compressed formats ==
−
All compressed pixel formats are only usable in [[Image]]s via [[CompressedImageData]] (compressed textures). Unlike regular color formats, these stay compressed in RAM and VRAM. This is good for saving memory space as well as improving performance, since the graphics card will be able to keep more of the image's pixels in its fast-access cache when drawing it.
+
All compressed pixel formats are only usable in [[Image]]s via [[CompressedImageData]] (compressed textures).
 +
 
 +
Unlike regular color formats, these stay compressed in RAM and VRAM. This is good for saving memory space as well as improving performance, since the graphics card will be able to keep more of the image's pixels in its fast-access cache when drawing it.
  
−
=== Constants ===
+
=== Constants (desktop GPUs) ===
 
{| class="wikitable"
 
{| class="wikitable"
 
! Name
 
! Name
Line 205: Line 242:
 
|3
 
|3
 
|4
 
|4
 +
|[0, 1]
 +
|Suitable for fully opaque images on desktop systems.
 +
|-
 +
|DXT3
 +
|4
 +
|8
 +
|[0, 1]
 +
|Smooth variations in opacity do not mix well with this format. DXT1 or DXT5 is generally better in every situation.
 +
|-
 +
|DXT5
 +
|4
 +
|8
 +
|[0, 1]
 +
|Recommended for images with varying opacity on desktop systems.
 +
|-
 +
|BC4
 +
|1
 +
|4
 +
|[0, 1]
 +
|Also known as 3Dc+ or ATI1. Stores just the red channel.
 +
|-
 +
|BC4s
 +
|1
 +
|4
 +
|[-1, 1]
 +
|Less precision than BC4 but allows negative numbers.
 +
|-
 +
|BC5
 +
|2
 +
|8
 +
|[0, 1]
 +
|Also known as 3Dc or ATI2. Often used for normal maps on desktop systems.
 +
|-
 +
|BC5s
 +
|2
 +
|8
 +
|[-1, 1]
 +
|Less precision than BC5 but allows negative numbers. Often used for normal maps on desktop systems.
 +
|-
 +
|BC6h
 +
|3
 +
|8
 +
|[0, +infinity]
 +
|Stores [https://en.wikipedia.org/wiki/Half-precision_floating-point_format half-precision] floating point RGB data. Suitable for HDR images on desktop systems.
 +
|-
 +
|BC6hs
 +
|3
 +
|8
 +
|[-infinity, +infinity]
 +
|Less precision than BC6h but allows negative numbers.
 +
|-
 +
|BC7
 +
|4
 +
|8
 +
|[0, 1]
 +
|Very good at representing opaque or transparent images, but requires a DX11 / OpenGL 4-capable GPU.
 +
|}
 +
 +
=== Constants (mobile GPUs) ===
 +
{| class="wikitable"
 +
! Name
 +
! Components
 +
! Bits per pixel
 +
! Range
 +
! Note(s)
 +
|-
 +
|ETC1
 +
|3
 +
|4
 +
|[0, 1]
 +
|Suitable for fully opaque images on older Android devices.
 +
|-
 +
|ETC2rgb
 +
|3
 +
|4
 +
|[0, 1]
 +
|Suitable for fully opaque images on newer mobile devices
 +
|-
 +
|ETC2rgba
 +
|4
 +
|8
 +
|[0, 1]
 +
|Recommended for images with varying opacity on newer mobile devices.
 +
|-
 +
|ETC2rgba1
 +
|4
 +
|4
 +
|[0, 1]
 +
|RGBA variant of the ETC2 format where pixels are either fully transparent or fully opaque.
 +
|-
 +
|EACr
 +
|1
 +
|4
 +
|[0, 1]
 +
|Stores just the red channel.
 +
|-
 +
|EACrs
 +
|1
 +
|4
 +
|[-1, 1]
 +
|Less precision than EACr but allows negative numbers.
 +
|-
 +
|EACrg
 +
|2
 +
|8
 +
|[0, 1]
 +
|Stores red and green channels.
 +
|-
 +
|EACrgs
 +
|2
 +
|8
 +
|[-1, 1]
 +
|Less precision than EACrg but allows negative numbers.
 +
|-
 +
|PVR1rgb2
 +
|3
 +
|2
 +
|[0, 1]
 +
|Images using this format must be square and power-of-two sized.
 +
|-
 +
|PVR1rgb4
 +
|3
 +
|4
 +
|[0, 1]
 +
|Images using this format must be square and power-of-two sized.
 +
|-
 +
|PVR1rgba2
 +
|4
 +
|2
 +
|[0, 1]
 +
|Images using this format must be square and power-of-two sized.
 +
|-
 +
|PVR1rgba4
 +
|4
 +
|4
 +
|[0, 1]
 +
|Images using this format must be square and power-of-two sized.
 +
|-
 +
|ASTC4x4
 +
|4
 +
|8
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC5x4
 +
|4
 +
|6.4
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC5x5
 +
|4
 +
|5.12
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC6x5
 +
|4
 +
|4.27
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC6x6
 +
|4
 +
|3.56
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC8x5
 +
|4
 +
|3.2
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC8x6
 +
|4
 +
|2.67
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC8x8
 +
|4
 +
|2
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC10x5
 +
|4
 +
|2.56
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC10x6
 +
|4
 +
|2.13
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC10x8
 +
|4
 +
|1.6
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC10x10
 +
|4
 +
|1.28
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC12x10
 +
|4
 +
|1.07
 +
|[0, 1]
 +
|
 +
|-
 +
|ASTC12x12
 +
|4
 +
|0.89
 
|[0, 1]
 
|[0, 1]
 
|
 
|
 
|}
 
|}
 +
 +
== Notes ==
 +
Not all formats are supported in love.graphics [[Image]]s and [[Canvas]]es on all systems, although the DXT compressed image formats have close to 100% support on desktop operating systems.
 +
 +
The BC4 and BC5 formats are supported on systems with DirectX 10 / OpenGL 3-capable desktop hardware and drivers. The BC6H and BC7 formats are only supported on desktop systems with DirectX 11 / OpenGL 4-capable hardware and very recent drivers. macOS does not support BC6H or BC7 at all currently.
 +
 +
ETC1 is supported by ''most'' Android devices, as well as the iPhone 5s and newer.
 +
 +
The ETC2 and EAC formats are supported by the iPhone 5s and newer, all OpenGL ES 3-capable Android devices, and OpenGL 4.3-capable desktop GPUs.
 +
 +
The PVR1 formats are supported by all iOS devices, as well as the small number of Android devices which have PowerVR GPUs.
 +
 +
ASTC is supported by new mobile devices (e.g. the iPhone 6 and newer), Android devices which have Adreno 4xx (and later) GPUs, and Skylake (and newer) integrated Intel GPUs. It has a variety of variants to allow for picking the most compressed possible one that doesn't have any noticeable compression artifacts, for a given texture.
 +
 +
Use [[love.graphics.getCanvasFormats]] and [[love.graphics.getImageFormats]] to check for Canvas and Image support, respectively:
 +
<source lang="lua">
 +
local supportedformats = love.graphics.getImageFormats()
 +
 +
if not supportedformats["DXT5"] then
 +
    -- Can't load CompressedImageData with the DXT5 format into images!
 +
    -- On some Linux systems with Mesa drivers, the user will need to install a "libtxc-dxtn" package because the DXT (aka S3TC) formats used to be patented.
 +
    -- Support for DXT formats on all other desktop drivers is pretty much guaranteed.
 +
end
 +
 +
if not supportedformats["BC5"] then
 +
    -- Can't load CompressedImageData with the BC5 format into images!
 +
    -- The user likely doesn't have a video card capable of using that format.
 +
end
 +
</source>
  
 
== See Also ==
 
== See Also ==
 
* [[parent::love.image]]
 
* [[parent::love.image]]
 
* [[parent::love.graphics]]
 
* [[parent::love.graphics]]
 +
* [[parent::love.font]]
 
* [[love.image.newImageData]]
 
* [[love.image.newImageData]]
 
* [[love.graphics.getImageFormats]]
 
* [[love.graphics.getImageFormats]]
Line 219: Line 505:
 
* [[ImageData:getFormat]]
 
* [[ImageData:getFormat]]
 
* [[CompressedImageData:getFormat]]
 
* [[CompressedImageData:getFormat]]
 +
* [[GlyphData:getFormat]]
 
[[Category:Enums]]
 
[[Category:Enums]]
 
{{#set:Description=Pixel formats for [[Texture]]s, [[ImageData]], and [[CompressedImageData]].}}
 
{{#set:Description=Pixel formats for [[Texture]]s, [[ImageData]], and [[CompressedImageData]].}}
 +
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|PixelFormat}}
 
{{i18n|PixelFormat}}

Latest revision as of 09:22, 9 January 2022

Available since LÖVE 11.0
This enum replaces CanvasFormat and CompressedImageFormat.

Pixel formats for Textures, ImageData, and CompressedImageData.

Normal color formats

Constants

Name Components Bits per pixel Range Usable with Canvases Usable with ImageData Note(s)
normal 4 32 [0, 1] Yes Alias for rgba8, or srgba8 if gamma-correct rendering is enabled.
r8 1 8 [0, 1] Yes 11.3
rg8 2 16 [0, 1] Yes 11.3
rgba8 4 32 [0, 1] Yes Yes
srgba8 4 32 [0, 1] Yes gamma-correct version of rgba8.
r16 1 16 [0, 1] 11.4 11.3
rg16 2 32 [0, 1] 11.4 11.3
rgba16 4 64 [0, 1] 11.4 Yes
r16f 1 16 [-65504, +65504]* Yes 11.3
rg16f 2 32 [-65504, +65504]* Yes 11.3
rgba16f 4 64 [-65504, +65504]* Yes Yes
r32f 1 32 [-3.4028235e38, 3.4028235e38]* Yes 11.3
rg32f 2 64 [-3.4028235e38, 3.4028235e38]* Yes 11.3
rgba32f 4 128 [-3.4028235e38, 3.4028235e38]* Yes Yes
la8 2 16 [0, 1] Used by GlyphData. Same as rg8, but accessed as (L, L, L, A)
rgba4 4 16 [0, 1] Yes 11.3
rgb5a1 4 16 [0, 1] Yes 11.3
rgb565 3 16 [0, 1] Yes 11.3
rgb10a2 4 32 [0, 1] Yes 11.3
rg11b10f 3 32 [0, 65024]** Yes 11.3

* -infinity and +infinity are also valid values.
** +infinity is also a valid value.

Depth / stencil formats

All depth and stencil pixel formats are only usable in Canvases.

They are non-readable by default, and Canvases with a depth/stencil format created with the readable flag can only access the depth values of their pixels in shaders (stencil values are not readable no matter what).

Constants

Name Bits per pixel Has depth Has stencil Note(s)
stencil8 8 Yes
depth16 16 Yes
depth24 24 Yes
depth32f 32 Yes
depth24stencil8 32 Yes Yes
depth32fstencil8 40 Yes Yes

Compressed formats

All compressed pixel formats are only usable in Images via CompressedImageData (compressed textures).

Unlike regular color formats, these stay compressed in RAM and VRAM. This is good for saving memory space as well as improving performance, since the graphics card will be able to keep more of the image's pixels in its fast-access cache when drawing it.

Constants (desktop GPUs)

Name Components Bits per pixel Range Note(s)
DXT1 3 4 [0, 1] Suitable for fully opaque images on desktop systems.
DXT3 4 8 [0, 1] Smooth variations in opacity do not mix well with this format. DXT1 or DXT5 is generally better in every situation.
DXT5 4 8 [0, 1] Recommended for images with varying opacity on desktop systems.
BC4 1 4 [0, 1] Also known as 3Dc+ or ATI1. Stores just the red channel.
BC4s 1 4 [-1, 1] Less precision than BC4 but allows negative numbers.
BC5 2 8 [0, 1] Also known as 3Dc or ATI2. Often used for normal maps on desktop systems.
BC5s 2 8 [-1, 1] Less precision than BC5 but allows negative numbers. Often used for normal maps on desktop systems.
BC6h 3 8 [0, +infinity] Stores half-precision floating point RGB data. Suitable for HDR images on desktop systems.
BC6hs 3 8 [-infinity, +infinity] Less precision than BC6h but allows negative numbers.
BC7 4 8 [0, 1] Very good at representing opaque or transparent images, but requires a DX11 / OpenGL 4-capable GPU.

Constants (mobile GPUs)

Name Components Bits per pixel Range Note(s)
ETC1 3 4 [0, 1] Suitable for fully opaque images on older Android devices.
ETC2rgb 3 4 [0, 1] Suitable for fully opaque images on newer mobile devices
ETC2rgba 4 8 [0, 1] Recommended for images with varying opacity on newer mobile devices.
ETC2rgba1 4 4 [0, 1] RGBA variant of the ETC2 format where pixels are either fully transparent or fully opaque.
EACr 1 4 [0, 1] Stores just the red channel.
EACrs 1 4 [-1, 1] Less precision than EACr but allows negative numbers.
EACrg 2 8 [0, 1] Stores red and green channels.
EACrgs 2 8 [-1, 1] Less precision than EACrg but allows negative numbers.
PVR1rgb2 3 2 [0, 1] Images using this format must be square and power-of-two sized.
PVR1rgb4 3 4 [0, 1] Images using this format must be square and power-of-two sized.
PVR1rgba2 4 2 [0, 1] Images using this format must be square and power-of-two sized.
PVR1rgba4 4 4 [0, 1] Images using this format must be square and power-of-two sized.
ASTC4x4 4 8 [0, 1]
ASTC5x4 4 6.4 [0, 1]
ASTC5x5 4 5.12 [0, 1]
ASTC6x5 4 4.27 [0, 1]
ASTC6x6 4 3.56 [0, 1]
ASTC8x5 4 3.2 [0, 1]
ASTC8x6 4 2.67 [0, 1]
ASTC8x8 4 2 [0, 1]
ASTC10x5 4 2.56 [0, 1]
ASTC10x6 4 2.13 [0, 1]
ASTC10x8 4 1.6 [0, 1]
ASTC10x10 4 1.28 [0, 1]
ASTC12x10 4 1.07 [0, 1]
ASTC12x12 4 0.89 [0, 1]

Notes

Not all formats are supported in love.graphics Images and Canvases on all systems, although the DXT compressed image formats have close to 100% support on desktop operating systems.

The BC4 and BC5 formats are supported on systems with DirectX 10 / OpenGL 3-capable desktop hardware and drivers. The BC6H and BC7 formats are only supported on desktop systems with DirectX 11 / OpenGL 4-capable hardware and very recent drivers. macOS does not support BC6H or BC7 at all currently.

ETC1 is supported by most Android devices, as well as the iPhone 5s and newer.

The ETC2 and EAC formats are supported by the iPhone 5s and newer, all OpenGL ES 3-capable Android devices, and OpenGL 4.3-capable desktop GPUs.

The PVR1 formats are supported by all iOS devices, as well as the small number of Android devices which have PowerVR GPUs.

ASTC is supported by new mobile devices (e.g. the iPhone 6 and newer), Android devices which have Adreno 4xx (and later) GPUs, and Skylake (and newer) integrated Intel GPUs. It has a variety of variants to allow for picking the most compressed possible one that doesn't have any noticeable compression artifacts, for a given texture.

Use love.graphics.getCanvasFormats and love.graphics.getImageFormats to check for Canvas and Image support, respectively: 

local supportedformats = love.graphics.getImageFormats()

if not supportedformats["DXT5"] then
    -- Can't load CompressedImageData with the DXT5 format into images!
    -- On some Linux systems with Mesa drivers, the user will need to install a "libtxc-dxtn" package because the DXT (aka S3TC) formats used to be patented.
    -- Support for DXT formats on all other desktop drivers is pretty much guaranteed.
end

if not supportedformats["BC5"] then
    -- Can't load CompressedImageData with the BC5 format into images!
    -- The user likely doesn't have a video card capable of using that format.
end

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=PixelFormat&oldid=27354"