// Copyright (c) 2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

include::meta/VK_EXT_astc_decode_mode.txt[]

Last Modified Date::
    2018-08-07
Contributors::
  - Jan-Harald Fredriksen, Arm

The existing specification requires that low dynamic range (LDR) ASTC
textures are decompressed to FP16 values per component.
In many cases, decompressing LDR textures to a lower precision intermediate
result gives acceptable image quality.
Source material for LDR textures is typically authored as 8-bit UNORM
values, so decoding to FP16 values adds little value.
On the other hand, reducing precision of the decoded result reduces the size
of the decompressed data, potentially improving texture cache performance
and saving power.

The goal of this extension is to enable this efficiency gain on existing
ASTC texture data.
This is achieved by giving the application the ability to select the
intermediate decoding precision.

Three decoding options are provided:

  * Decode to elink:VK_FORMAT_R16G16B16A16_SFLOAT precision: This is the
    default, and matches the required behavior in the core API.
  * Decode to elink:VK_FORMAT_R8G8B8A8_UNORM precision: This is provided as
    an option in LDR mode.
  * Decode to elink:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 precision: This is
    provided as an option in both LDR and HDR mode.
    In this mode, negative values cannot be represented and are clamped to
    zero.
    The alpha component is ignored, and the results are as if alpha was 1.0.
    This decode mode is optional and support can be queried via the physical
    device properties.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_ASTC_DECODE_FEATURES_EXT

=== New Enums

None.

=== New Structures

  * slink:VkImageViewASTCDecodeModeEXT
  * slink:VkPhysicalDeviceASTCDecodeFeaturesEXT

=== New Functions

None.

=== Issues

1) Are implementations allowed to decode at a higher precision than what is
    requested?

    RESOLUTION: No.
    If we allow this, then this extension could be exposed on all
    implementations that support ASTC.
    But developers would have no way of knowing what precision was actually
    used, and thus whether the image quality is sufficient at reduced
    precision.

2) Should the decode mode be image view state and/or sampler state?

    RESOLUTION: Image view state only.
    Some implementations treat the different decode modes as different
    texture formats.

=== Example

Create an image view that decodes to VK_FORMAT_R8G8B8A8_UNORM precision:

[source,c++]
----------------------------------------

    VkImageViewASTCDecodeModeEXT decodeMode =
    {
        VK_STRUCTURE_TYPE_IMAGE_VIEW_ASTC_DECODE_MODE_EXT, // sType
        NULL, // pNext
        VK_FORMAT_R8G8B8A8_UNORM // decode mode
    };

    VkImageViewCreateInfo createInfo =
    {
        VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO, // sType
        &decodeMode, // pNext
        // flags, image, viewType set to application-desired values
        VK_FORMAT_ASTC_8x8_UNORM_BLOCK, // format
        // components, subresourceRange set to application-desired values
    };    

    VkImageView imageView;
    VkResult result = vkCreateImageView(
        device,
        &createInfo,
        NULL,
        &imageView);
----------------------------------------

=== Version History

 * Revision 1, 2018-08-07 (Jan-Harald Fredriksen)
   - Initial revision