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

include::{generated}/meta/VK_KHR_shader_float_controls.txt[]

*Last Modified Date*::
    2018-09-11
*IP Status*::
    No known IP claims.
*Interactions and External Dependencies*::
  - This extension requires
    {spirv}/KHR/SPV_KHR_float_controls.html[`SPV_KHR_float_controls`]
*Contributors*::
    - Alexander Galazin, Arm
    - Jan-Harald Fredriksen, Arm
    - Jeff Bolz, NVIDIA
    - Graeme Leese, Broadcom
    - Daniel Rakos, AMD

=== Description

The `VK_KHR_shader_float_controls` extension enables efficient use of
floating-point computations through the ability to query and override the
implementation's default behavior for rounding modes, denormals, signed
zero, and infinity.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FLOAT_CONTROLS_PROPERTIES_KHR

=== New Enums

  * None

=== New Structures

  * slink:VkPhysicalDeviceFloatControlsPropertiesKHR

=== New Functions

  * None

=== New SPIR-V Capabilities

  * <<spirvenv-capabilities-table-shaderfloatcontrols,code:DenormPreserve>>
  * <<spirvenv-capabilities-table-shaderfloatcontrols,code:DenormFlushToZero>>
  * <<spirvenv-capabilities-table-shaderfloatcontrols,code:SignedZeroInfNanPreserve>>
  * <<spirvenv-capabilities-table-shaderfloatcontrols,code:RoundingModeRTE>>
  * <<spirvenv-capabilities-table-shaderfloatcontrols,code:RoundingModeRTZ>>

=== Issues

1) Which instructions must flush denorms?

*RESOLVED*: Only floating-point conversion, floating-point arithmetic,
floating-point relational (except code:OpIsNaN, code:OpIsInf), and
floating-point GLSL.std.450 extended instructions must flush denormals.

2) What is the denorm behavior for intermediate results?

*RESOLVED*: When a SPIR-V instruction is implemented as a sequence of other
instructions:
 - in the code:DenormFlushToZero execution mode the intermediate
   instructions may flush denormals, the final result of the sequence must:
   not be denormal.
 - in the code:DenormPreserve execution mode denormals must be preserved
   throughout the whole sequence.

3) Do denorm and rounding mode controls apply to code:OpSpecConstantOp?

*RESOLVED*: Yes, except when the opcode is code:OpQuantizeToF16.

4) The SPIR-V specification says that code:OpConvertFToU and
code:OpConvertFToS unconditionally round towards zero.
Do the rounding mode controls specified through the execution modes apply to
them?

*RESOLVED*: No, these instructions unconditionally round towards zero.

5) Do any of the "Pack" GLSL.std.450 instructions count as conversion
instructions and have the rounding mode apply?

*RESOLVED*: No, only instructions listed in the section "3.32.11.
Conversion Instructions" of the SPIR-V specification count as conversion
instructions.

6) When using inf/nan-ignore mode, what is expected of code:OpIsNan and
   code:OpIsInf?

*RESOLVED*: These instructions must always accurately detect inf/nan if it
is passed to them.

[[VK_KHR_shader_controls_v4_incompatibility]]
=== Version 4 API incompatiblity

The original versions of VK_KHR_shader_controls shipped with booleans named
"separateDenormSettings" and "separateRoundingModeSettings", which at first
glance could've indicated "they can all independently set, or not".
However the spec language as written indicated that the 32-bit value could
always be set independently, and only the 16- and 64-bit controls needed to
be the same if these values were VK_FALSE.

As a result of this slight disparity, and lack of test coverage for this
facet of the extension, we ended up with two different behaviors in the
wild, where some implementations worked as written, and others worked based
on the naming.
As these are hard limits in hardware with reasons for exposure as written,
it was not possible to standardise on a single way to make this work within
the existing API.

No known users of this part of the extension exist in the wild, and as such
the Vulkan WG took the unusual step of retroactively changing the once
boolean value into a tri-state enum, breaking source compatibility.
This was however done in such a way as to retain ABI compatibility, in case
any code using this did exist; with the numerical values 0 and 1 retaining
their original specified meaning, and a new value signifying the additional
"all need to be set together" state.
If any applications exist today, compiled binaries will continue to work as
written in most cases, but will need changes before the code can be
recompiled.


=== Version History

  * Revision 4, 2019-06-18 (Tobias Hector)
    - Modified settings restrictions, see
      <<VK_KHR_shader_controls_v4_incompatibility>>
  * Revision 3, 2018-09-11 (Alexander Galazin)
    - Minor restructuring
  * Revision 2, 2018-04-17 (Alexander Galazin)
    - Added issues and resolutions
  * Revision 1, 2018-04-11 (Alexander Galazin)
    - Initial draft