codegen/vulkan/vulkan-docs-next/appendices/compressedtex.adoc

// Copyright 2015-2023 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[appendix]
[[compressed_image_formats]]
= Compressed Image Formats

The compressed texture formats used by Vulkan are described in the
specifically identified sections of the <<data-format,Khronos Data Format
Specification>>, version 1.3.

Unless otherwise described, the quantities encoded in these compressed
formats are treated as normalized, unsigned values.

Those formats listed as sRGB-encoded have in-memory representations of
[eq]#R#, [eq]#G# and [eq]#B# components which are nonlinearly-encoded as
[eq]#R'#, [eq]#G'#, and [eq]#B'#; any alpha component is unchanged.
As part of filtering, the nonlinear [eq]#R'#, [eq]#G'#, and [eq]#B'# values
are converted to linear [eq]#R#, [eq]#G#, and [eq]#B# components; any alpha
component is unchanged.
The conversion between linear and nonlinear encoding is performed as
described in the "`KHR_DF_TRANSFER_SRGB`" section of the Khronos Data Format
Specification.

<<<

[[appendix-compressedtex-bc]]
== Block-Compressed Image Formats

BC1, BC2 and BC3 formats are described in "`S3TC Compressed Texture Image
Formats`" chapter of the <<data-format,Khronos Data Format Specification>>.
BC4 and BC5 are described in the "`RGTC Compressed Texture Image Formats`"
chapter.
BC6H and BC7 are described in the "`BPTC Compressed Texture Image Formats`"
chapter.

.Mapping of Vulkan BC formats to descriptions
[width="90%",options="header",cols="5,4"]
|====
| elink:VkFormat | <<data-format,Khronos Data Format Specification>> description
2+^| Formats described in the "`S3TC Compressed Texture Image Formats`" chapter
| ename:VK_FORMAT_BC1_RGB_UNORM_BLOCK |BC1 with no alpha
| ename:VK_FORMAT_BC1_RGB_SRGB_BLOCK  |BC1 with no alpha, sRGB-encoded
| ename:VK_FORMAT_BC1_RGBA_UNORM_BLOCK|BC1 with alpha
| ename:VK_FORMAT_BC1_RGBA_SRGB_BLOCK |BC1 with alpha, sRGB-encoded
| ename:VK_FORMAT_BC2_UNORM_BLOCK     |BC2
| ename:VK_FORMAT_BC2_SRGB_BLOCK      |BC2, sRGB-encoded
| ename:VK_FORMAT_BC3_UNORM_BLOCK     |BC3
| ename:VK_FORMAT_BC3_SRGB_BLOCK      |BC3, sRGB-encoded
2+^| Formats described in the "`RGTC Compressed Texture Image Formats`" chapter
| ename:VK_FORMAT_BC4_UNORM_BLOCK     |BC4 unsigned
| ename:VK_FORMAT_BC4_SNORM_BLOCK     |BC4 signed
| ename:VK_FORMAT_BC5_UNORM_BLOCK     |BC5 unsigned
| ename:VK_FORMAT_BC5_SNORM_BLOCK     |BC5 signed
2+^| Formats described in the "`BPTC Compressed Texture Image Formats`" chapter
| ename:VK_FORMAT_BC6H_UFLOAT_BLOCK   |BC6H (unsigned version)
| ename:VK_FORMAT_BC6H_SFLOAT_BLOCK   |BC6H (signed version)
| ename:VK_FORMAT_BC7_UNORM_BLOCK     |BC7
| ename:VK_FORMAT_BC7_SRGB_BLOCK      |BC7, sRGB-encoded
|====

<<<

[[appendix-compressedtex-etc2]]
== ETC Compressed Image Formats

The following formats are described in the "`ETC2 Compressed Texture Image
Formats`" chapter of the <<data-format,Khronos Data Format Specification>>.

.Mapping of Vulkan ETC formats to descriptions
[options="header",cols="1,1"]
|====
| elink:VkFormat | <<data-format,Khronos Data Format Specification>> description
| ename:VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK     |RGB ETC2
| ename:VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK      |RGB ETC2 with sRGB encoding
| ename:VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK   |RGB ETC2 with punch-through alpha
| ename:VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK    |RGB ETC2 with punch-through alpha and sRGB
| ename:VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK   |RGBA ETC2
| ename:VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK    |RGBA ETC2 with sRGB encoding
| ename:VK_FORMAT_EAC_R11_UNORM_BLOCK         |Unsigned R11 EAC
| ename:VK_FORMAT_EAC_R11_SNORM_BLOCK         |Signed R11 EAC
| ename:VK_FORMAT_EAC_R11G11_UNORM_BLOCK      |Unsigned RG11 EAC
| ename:VK_FORMAT_EAC_R11G11_SNORM_BLOCK      |Signed RG11 EAC
|====

<<<

[[appendix-compressedtex-astc]]
== ASTC Compressed Image Formats

ASTC formats are described in the "`ASTC Compressed Texture Image Formats`"
chapter of the <<data-format,Khronos Data Format Specification>>.

.Mapping of Vulkan ASTC formats to descriptions
[width="90%",options="header",cols="55%,20%,25%"]
|====
| elink:VkFormat ^| Compressed texel block dimensions ^| Requested mode
| ename:VK_FORMAT_ASTC_4x4_UNORM_BLOCK        ^|[eq]#4 {times} 4#   ^|Linear LDR
| ename:VK_FORMAT_ASTC_4x4_SRGB_BLOCK         ^|[eq]#4 {times} 4#   ^|sRGB
| ename:VK_FORMAT_ASTC_5x4_UNORM_BLOCK        ^|[eq]#5 {times} 4#   ^|Linear LDR
| ename:VK_FORMAT_ASTC_5x4_SRGB_BLOCK         ^|[eq]#5 {times} 4#   ^|sRGB
| ename:VK_FORMAT_ASTC_5x5_UNORM_BLOCK        ^|[eq]#5 {times} 5#   ^|Linear LDR
| ename:VK_FORMAT_ASTC_5x5_SRGB_BLOCK         ^|[eq]#5 {times} 5#   ^|sRGB
| ename:VK_FORMAT_ASTC_6x5_UNORM_BLOCK        ^|[eq]#6 {times} 5#   ^|Linear LDR
| ename:VK_FORMAT_ASTC_6x5_SRGB_BLOCK         ^|[eq]#6 {times} 5#   ^|sRGB
| ename:VK_FORMAT_ASTC_6x6_UNORM_BLOCK        ^|[eq]#6 {times} 6#   ^|Linear LDR
| ename:VK_FORMAT_ASTC_6x6_SRGB_BLOCK         ^|[eq]#6 {times} 6#   ^|sRGB
| ename:VK_FORMAT_ASTC_8x5_UNORM_BLOCK        ^|[eq]#8 {times} 5#   ^|Linear LDR
| ename:VK_FORMAT_ASTC_8x5_SRGB_BLOCK         ^|[eq]#8 {times} 5#   ^|sRGB
| ename:VK_FORMAT_ASTC_8x6_UNORM_BLOCK        ^|[eq]#8 {times} 6#   ^|Linear LDR
| ename:VK_FORMAT_ASTC_8x6_SRGB_BLOCK         ^|[eq]#8 {times} 6#   ^|sRGB
| ename:VK_FORMAT_ASTC_8x8_UNORM_BLOCK        ^|[eq]#8 {times} 8#   ^|Linear LDR
| ename:VK_FORMAT_ASTC_8x8_SRGB_BLOCK         ^|[eq]#8 {times} 8#   ^|sRGB
| ename:VK_FORMAT_ASTC_10x5_UNORM_BLOCK       ^|[eq]#10 {times} 5#  ^|Linear LDR
| ename:VK_FORMAT_ASTC_10x5_SRGB_BLOCK        ^|[eq]#10 {times} 5#  ^|sRGB
| ename:VK_FORMAT_ASTC_10x6_UNORM_BLOCK       ^|[eq]#10 {times} 6#  ^|Linear LDR
| ename:VK_FORMAT_ASTC_10x6_SRGB_BLOCK        ^|[eq]#10 {times} 6#  ^|sRGB
| ename:VK_FORMAT_ASTC_10x8_UNORM_BLOCK       ^|[eq]#10 {times} 8#  ^|Linear LDR
| ename:VK_FORMAT_ASTC_10x8_SRGB_BLOCK        ^|[eq]#10 {times} 8#  ^|sRGB
| ename:VK_FORMAT_ASTC_10x10_UNORM_BLOCK      ^|[eq]#10 {times} 10# ^|Linear LDR
| ename:VK_FORMAT_ASTC_10x10_SRGB_BLOCK       ^|[eq]#10 {times} 10# ^|sRGB
| ename:VK_FORMAT_ASTC_12x10_UNORM_BLOCK      ^|[eq]#12 {times} 10# ^|Linear LDR
| ename:VK_FORMAT_ASTC_12x10_SRGB_BLOCK       ^|[eq]#12 {times} 10# ^|sRGB
| ename:VK_FORMAT_ASTC_12x12_UNORM_BLOCK      ^|[eq]#12 {times} 12# ^|Linear LDR
| ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK       ^|[eq]#12 {times} 12# ^|sRGB
ifdef::VK_VERSION_1_3,VK_EXT_texture_compression_astc_hdr[]
| ename:VK_FORMAT_ASTC_4x4_SFLOAT_BLOCK       ^|[eq]#4 {times} 4#   ^|HDR
| ename:VK_FORMAT_ASTC_5x4_SFLOAT_BLOCK       ^|[eq]#5 {times} 4#   ^|HDR
| ename:VK_FORMAT_ASTC_5x5_SFLOAT_BLOCK       ^|[eq]#5 {times} 5#   ^|HDR
| ename:VK_FORMAT_ASTC_6x5_SFLOAT_BLOCK       ^|[eq]#6 {times} 5#   ^|HDR
| ename:VK_FORMAT_ASTC_6x6_SFLOAT_BLOCK       ^|[eq]#6 {times} 6#   ^|HDR
| ename:VK_FORMAT_ASTC_8x5_SFLOAT_BLOCK       ^|[eq]#8 {times} 5#   ^|HDR
| ename:VK_FORMAT_ASTC_8x6_SFLOAT_BLOCK       ^|[eq]#8 {times} 6#   ^|HDR
| ename:VK_FORMAT_ASTC_8x8_SFLOAT_BLOCK       ^|[eq]#8 {times} 8#   ^|HDR
| ename:VK_FORMAT_ASTC_10x5_SFLOAT_BLOCK      ^|[eq]#10 {times} 5#  ^|HDR
| ename:VK_FORMAT_ASTC_10x6_SFLOAT_BLOCK      ^|[eq]#10 {times} 6#  ^|HDR
| ename:VK_FORMAT_ASTC_10x8_SFLOAT_BLOCK      ^|[eq]#10 {times} 8#  ^|HDR
| ename:VK_FORMAT_ASTC_10x10_SFLOAT_BLOCK     ^|[eq]#10 {times} 10# ^|HDR
| ename:VK_FORMAT_ASTC_12x10_SFLOAT_BLOCK     ^|[eq]#12 {times} 10# ^|HDR
| ename:VK_FORMAT_ASTC_12x12_SFLOAT_BLOCK     ^|[eq]#12 {times} 12# ^|HDR
endif::VK_VERSION_1_3,VK_EXT_texture_compression_astc_hdr[]
|====

ifndef::VK_VERSION_1_3,VK_EXT_texture_compression_astc_hdr[]
ASTC textures containing any HDR blocks should: not be passed into the API
using an sRGB or UNORM texture format.
endif::VK_VERSION_1_3,VK_EXT_texture_compression_astc_hdr[]
ifdef::VK_VERSION_1_3,VK_EXT_texture_compression_astc_hdr[]
ASTC textures containing HDR block encodings should: be passed to the API
using an ASTC SFLOAT texture format.
endif::VK_VERSION_1_3,VK_EXT_texture_compression_astc_hdr[]

[NOTE]
.Note
====
An HDR block in a texture passed using a LDR UNORM format will return the
appropriate ASTC error color if the implementation supports only the ASTC
LDR profile, but may result in either the error color or a decompressed HDR
color if the implementation supports HDR decoding.
====

ifdef::VK_EXT_astc_decode_mode[]

=== ASTC Decode Mode

If the `VK_EXT_astc_decode_mode` extension is enabled, the decode mode is
determined as follows:

.Mapping of Vulkan ASTC decoding format to ASTC decoding modes
[width="75%",options="header",cols="75%,25%"]
|====
| elink:VkFormat ^| Decoding mode
| ename:VK_FORMAT_R16G16B16A16_SFLOAT    ^| decode_float16
| ename:VK_FORMAT_R8G8B8A8_UNORM         ^| decode_unorm8
| ename:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 ^| decode_rgb9e5
|====

Otherwise, the ASTC decode mode is decode_float16.

Note that an implementation may: use HDR mode when linear LDR mode is
requested unless the decode mode is decode_unorm8.
endif::VK_EXT_astc_decode_mode[]
ifndef::VK_EXT_astc_decode_mode[]
The ASTC decode mode is decode_float16.

Note that an implementation may: use HDR mode when linear LDR mode is
requested.
endif::VK_EXT_astc_decode_mode[]


ifdef::VK_IMG_format_pvrtc[]
<<<

[[appendix-compressedtex-pvrtc]]
== PVRTC Compressed Image Formats

PVRTC formats are described in the "`PVRTC Compressed Texture Image
Formats`" chapter of the <<data-format,Khronos Data Format Specification>>.

.Mapping of Vulkan PVRTC formats to descriptions
[width="75%",options="header",cols="63%,15%,22%"]
|====
| elink:VkFormat ^| Compressed texel block dimensions ^| sRGB-encoded
| ename:VK_FORMAT_PVRTC1_2BPP_UNORM_BLOCK_IMG  ^|[eq]#8 {times} 4# ^|No
| ename:VK_FORMAT_PVRTC1_4BPP_UNORM_BLOCK_IMG  ^|[eq]#4 {times} 4# ^|No
| ename:VK_FORMAT_PVRTC2_2BPP_UNORM_BLOCK_IMG  ^|[eq]#8 {times} 4# ^|No
| ename:VK_FORMAT_PVRTC2_4BPP_UNORM_BLOCK_IMG  ^|[eq]#4 {times} 4# ^|No
| ename:VK_FORMAT_PVRTC1_2BPP_SRGB_BLOCK_IMG   ^|[eq]#8 {times} 4# ^|Yes
| ename:VK_FORMAT_PVRTC1_4BPP_SRGB_BLOCK_IMG   ^|[eq]#4 {times} 4# ^|Yes
| ename:VK_FORMAT_PVRTC2_2BPP_SRGB_BLOCK_IMG   ^|[eq]#8 {times} 4# ^|Yes
| ename:VK_FORMAT_PVRTC2_4BPP_SRGB_BLOCK_IMG   ^|[eq]#4 {times} 4# ^|Yes
|====
endif::VK_IMG_format_pvrtc[]