Difference between revisions of "CompressedImageFormat"

(Added formats new in 0.10.0)
m
Line 3: Line 3:
  
 
Unlike traditional PNG or jpeg, these formats stay compressed in RAM and in the graphics card's 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.
 
Unlike traditional PNG or jpeg, these formats stay compressed in RAM and in the graphics card's 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.
 +
 +
{{notice|In LÖVE versions prior to [[0.10.0]], these constants are all lower-case.}}
 
== Constants ==
 
== Constants ==
;dxt1: The DXT1 format. RGB data at 4 bits per pixel (compared to 32 bits for [[ImageData]] and regular [[Image]]s.) Suitable for fully opaque images on desktop systems.
+
;DXT1: The DXT1 format. RGB data at 4 bits per pixel (compared to 32 bits for [[ImageData]] and regular [[Image]]s.) Suitable for fully opaque images on desktop systems.
;dxt3: The DXT3 format. RGBA data at 8 bits per pixel. Smooth variations in opacity do not mix well with this format.
+
;DXT3: The DXT3 format. RGBA data at 8 bits per pixel. Smooth variations in opacity do not mix well with this format.
;dxt5: The DXT5 format. RGBA data at 8 bits per pixel. Recommended for images with varying opacity on desktop systems.
+
;DXT5: The DXT5 format. RGBA data at 8 bits per pixel. Recommended for images with varying opacity on desktop systems.
;bc4: The BC4 format (also known as 3Dc+ or ATI1.) Stores just the red channel, at 4 bits per pixel.
+
;BC4: The BC4 format (also known as 3Dc+ or ATI1.) Stores just the red channel, at 4 bits per pixel.
;bc4s: The signed variant of the BC4 format. Same as above but pixel values in the texture are in the range of [-1, 1] instead of [0, 1] in shaders.
+
;BC4s: The signed variant of the BC4 format. Same as above but pixel values in the texture are in the range of [-1, 1] instead of [0, 1] in shaders.
;bc5: The BC5 format (also known as 3Dc or ATI2.) Stores red and green channels at 8 bits per pixel.
+
;BC5: The BC5 format (also known as 3Dc or ATI2.) Stores red and green channels at 8 bits per pixel.
;bc5s: The signed variant of the BC5 format.
+
;BC5s: The signed variant of the BC5 format.
 
{{newin|[[0.9.2]]|092|type=constants|plural='y'}}
 
{{newin|[[0.9.2]]|092|type=constants|plural='y'}}
;bc6h: The BC6H format. Stores [http://en.wikipedia.org/wiki/Half-precision_floating-point_format half-precision] floating-point RGB data in the range of [0, infinity) at 8 bits per pixel. Suitable for HDR images on desktop systems.
+
;BC6h: The BC6H format. Stores [http://en.wikipedia.org/wiki/Half-precision_floating-point_format half-precision] floating-point RGB data in the range of [0, infinity) at 8 bits per pixel. Suitable for HDR images on desktop systems.
;bc6hs: The signed variant of the BC6H format. Stores RGB data in the range of (-infinity, +infinity.)
+
;BC6hs: The signed variant of the BC6H format. Stores RGB data in the range of (-infinity, +infinity.)
;bc7: The BC7 format (also known as BPTC.) Stores RGB or RGBA data at 8 bits per pixel.
+
;BC7: The BC7 format (also known as BPTC.) Stores RGB or RGBA data at 8 bits per pixel.
;bc7srgb: The sRGB-encoded variant of the BC7 format.
+
;BC7srgb: The sRGB-encoded variant of the BC7 format.
 
{{newin|[[0.10.0]]|100|type=constants|plural=y}}
 
{{newin|[[0.10.0]]|100|type=constants|plural=y}}
 
;ETC1: The ETC1 format. RGB data at 4 bits per pixel. Suitable for fully opaque images on older Android devices.
 
;ETC1: The ETC1 format. RGB data at 4 bits per pixel. Suitable for fully opaque images on older Android devices.
Line 25: Line 27:
 
;EACrg: The two-channel variant of the EAC format. Stores red and green channels at 8 bits per pixel.
 
;EACrg: The two-channel variant of the EAC format. Stores red and green channels at 8 bits per pixel.
 
;EACrgs: The signed two-channel variant of the EAC format.
 
;EACrgs: The signed two-channel variant of the EAC format.
;PVR1rgb2: The 2 bit per channel RGB variant of the PVRTC1 format. Stores RGB data at 2 bits per pixel. Textures compressed with PVRTC1 formats must be square.
+
;PVR1rgb2: The 2 bit per channel RGB variant of the PVRTC1 format. Stores RGB data at 2 bits per pixel. Textures compressed with PVRTC1 formats must be square and power-of-two sized.
 
;PVR1rgb4: The 4 bit per channel RGB variant of the PVRTC1 format. Stores RGB data at 4 bits per pixel.
 
;PVR1rgb4: The 4 bit per channel RGB variant of the PVRTC1 format. Stores RGB data at 4 bits per pixel.
 
;PVR1rgba2: The 2 bit per channel RGBA variant of the PVRTC1 format.
 
;PVR1rgba2: The 2 bit per channel RGBA variant of the PVRTC1 format.
Line 32: Line 34:
 
Not all formats are supported in love.graphics [[Image]]s on all systems, although the DXT formats have close to 100% support on desktop operating systems.
 
Not all formats are supported in love.graphics [[Image]]s on all systems, although the DXT 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 hardware and drivers. The BC6H and BC7 formats are only supported on systems with DirectX 11 / OpenGL 4-capable hardware and very recent drivers. Mac OS X does not support BC6H or BC7 at all currently.
+
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. Mac OS X does not support BC6H or BC7 at all currently.
 +
 
 +
ETC1 is supported by Android devices, as well as newer (OpenGL ES 3-capable) iOS devices.
 +
 
 +
The PVR1 formats are supported by iOS devices, as well as Android devices with PowerVR GPUs.
 +
 
 +
The ETC2 and EAC formats are supported by newer (OpenGL ES 3-capable) iOS and Android devices.
  
 
Use [[love.graphics.getCompressedImageFormats]] to check for support:
 
Use [[love.graphics.getCompressedImageFormats]] to check for support:
Line 38: Line 46:
 
local supportedformats = love.graphics.getCompressedImageFormats()
 
local supportedformats = love.graphics.getCompressedImageFormats()
  
 +
-- Note: use "DXT5" instead of "dxt5" in 0.10.0 and newer.
 
if not supportedformats["dxt5"] then
 
if not supportedformats["dxt5"] then
 
     -- Can't load CompressedImageData with the DXT5 format into images!
 
     -- Can't load CompressedImageData with the DXT5 format into images!
Line 44: Line 53:
 
end
 
end
  
 +
-- Note: use "BC5" instead of "bc5" in 0.10.0 and newer.
 
if not supportedformats["bc5"] then
 
if not supportedformats["bc5"] then
 
     -- Can't load CompressedImageData with the BC5 format into images!
 
     -- Can't load CompressedImageData with the BC5 format into images!

Revision as of 23:55, 14 November 2015

Available since LÖVE 0.9.0
This enum is not supported in earlier versions.

Compressed image data formats. Here and here are a couple overviews of many of the formats.

Unlike traditional PNG or jpeg, these formats stay compressed in RAM and in the graphics card's 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.

O.png In LÖVE versions prior to 0.10.0, these constants are all lower-case.  


Constants

DXT1
The DXT1 format. RGB data at 4 bits per pixel (compared to 32 bits for ImageData and regular Images.) Suitable for fully opaque images on desktop systems.
DXT3
The DXT3 format. RGBA data at 8 bits per pixel. Smooth variations in opacity do not mix well with this format.
DXT5
The DXT5 format. RGBA data at 8 bits per pixel. Recommended for images with varying opacity on desktop systems.
BC4
The BC4 format (also known as 3Dc+ or ATI1.) Stores just the red channel, at 4 bits per pixel.
BC4s
The signed variant of the BC4 format. Same as above but pixel values in the texture are in the range of [-1, 1] instead of [0, 1] in shaders.
BC5
The BC5 format (also known as 3Dc or ATI2.) Stores red and green channels at 8 bits per pixel.
BC5s
The signed variant of the BC5 format.
Available since LÖVE 0.9.2
These constants are not supported in earlier versions.
BC6h
The BC6H format. Stores half-precision floating-point RGB data in the range of [0, infinity) at 8 bits per pixel. Suitable for HDR images on desktop systems.
BC6hs
The signed variant of the BC6H format. Stores RGB data in the range of (-infinity, +infinity.)
BC7
The BC7 format (also known as BPTC.) Stores RGB or RGBA data at 8 bits per pixel.
BC7srgb
The sRGB-encoded variant of the BC7 format.
Available since LÖVE 0.10.0
These constants are not supported in earlier versions.
ETC1
The ETC1 format. RGB data at 4 bits per pixel. Suitable for fully opaque images on older Android devices.
ETC2rgb
The RGB variant of the ETC2 format. RGB data at 4 bits per pixel. Suitable for fully opaque images on newer mobile devices.
ETC2rgba
The RGBA variant of the ETC2 format. RGBA data at 8 bits per pixel. Recommended for images with varying opacity on newer mobile devices.
ETC2rgba1
The RGBA variant of the ETC2 format where pixels are either fully transparent or fully opaque. RGBA data at 4 bits per pixel.
EACr
The single-channel variant of the EAC format. Stores just the red channel, at 4 bits per pixel.
EACrs
The signed single-channel variant of the EAC format. Same as above but pixel values in the texture are in the range of [-1, 1] instead of [0, 1] in shaders.
EACrg
The two-channel variant of the EAC format. Stores red and green channels at 8 bits per pixel.
EACrgs
The signed two-channel variant of the EAC format.
PVR1rgb2
The 2 bit per channel RGB variant of the PVRTC1 format. Stores RGB data at 2 bits per pixel. Textures compressed with PVRTC1 formats must be square and power-of-two sized.
PVR1rgb4
The 4 bit per channel RGB variant of the PVRTC1 format. Stores RGB data at 4 bits per pixel.
PVR1rgba2
The 2 bit per channel RGBA variant of the PVRTC1 format.
PVR1rgba4
The 4 bit per channel RGBA variant of the PVRTC1 format.

Notes

Not all formats are supported in love.graphics Images on all systems, although the DXT 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. Mac OS X does not support BC6H or BC7 at all currently.

ETC1 is supported by Android devices, as well as newer (OpenGL ES 3-capable) iOS devices.

The PVR1 formats are supported by iOS devices, as well as Android devices with PowerVR GPUs.

The ETC2 and EAC formats are supported by newer (OpenGL ES 3-capable) iOS and Android devices.

Use love.graphics.getCompressedImageFormats to check for support:

local supportedformats = love.graphics.getCompressedImageFormats()

-- Note: use "DXT5" instead of "dxt5" in 0.10.0 and newer.
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 are patented.
    -- Support for DXT formats on all other desktop drivers is pretty much guaranteed.
end

-- Note: use "BC5" instead of "bc5" in 0.10.0 and newer.
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