Varyings
========

This is the naming convention followed by the hardware (slightly different
from Vulkan naming):

- "Attribute": per-vertex data
- "Varying": per-fragment data

Thus vertex shaders always interact with attributes and fragment/pixel shaders
only interact with varyings (commonly shortened to "VAR").


Hardware descriptors
--------------------

Before Valhall there were two types of hardware descriptors:

- ``AttributeDescriptor``: Descriptor for a single attribute in a larger buffer,
  contains offset, stride and the in-memory format.
- ``BufferDescriptor``: Buffer, when used for attributes and varyings it
  contains: pointer, size and stride

Midgard (v5)
------------
Attributes are loaded/stored using ``LD_ATTR``/``ST_ATTR``, those query the
attribute descriptors and buffer descriptors to find the real global memory
offset before loading/storing.
All varyings are loaded using ``LD_VAR``, including flat attributes (using a
modifier), and special attributes (position, psiz, ecc...).  Special attributes
require a special descriptor, that is not backed by any buffer, it generates
data on-the-fly.
There is a concept of in-memory format and register format, the first is written
inside of the ``AttributeDescriptor`` while the register format is a modifier of
the instructions, when those two disagree the hardware will try to convert them,
this is only supported between int-int or float-float operations.


Bifrost (v6)
------------
Changes:

- ``ST_ATTR`` is replaced by ``LEA_ATTR`` and ``ST_CVT`` pairs.

  - ``LEA_ATTR`` queries memory address and format from the appropriate
    descriptor.
  - ``ST_CVT`` performs the actual conversion and memory store.
- A new ``LD_VAR_SPECIAL`` is introduced, now special attributes do not need
  special descriptors.
- ``LD_VAR`` only handles interpolated varyings, flat varyings are now handled
  by ``LD_VAR_FLAT``.

Valhall (v9)
------------
Valhall introduced layout-specific instructions, ``LEA_BUF`` and ``LD_VAR_BUF``,
those do not use ``AttributeDescriptor`` but read ``BufferDescriptor`` directly.
These new instructions bake the offset and in-memory format of the attribute
inside of the shader code itself, saving a lookup.  If all shaders in a program
use those instructions, we can remove all ``AttributeDescriptor``.  If the
shaders aren't compiled together, one of the shaders cannot know the data layout,
and it needs to fall back to the old ``AttributeDescriptor``-based path.  We
also have to fall back to ``AttributeDescriptor`` completely if the attribute
offset overflows the immediate field.

``LD_VAR_BUF`` only supports ``.f16`` and ``.f32`` as register modifiers, we can
also load (flat) ints with those.  We need to specify no conversion
(``.f16.src_flat16`` or ``.f32.src_flat32``), but with those we can load both
16-bit and 32-bit integers.

In this architecture we assume the VS always uses IDVS, emitting attribute data
with ``LEA_BUF`` (instead of ``LEA_ATTR``), and never emit varying
``AttributeDescriptor`` for VS.

Challenges
----------
Theoretically, the output types from the VS and input types from the FS should
always agree.  In practice we cannot trust the varyings types given to us,
here are some challenging examples:

* Shaders are allowed to use the same types with different precision modifiers.
* ``nir_opt_varying`` erases highp flat types with "float32" and packs them
  together.
* Some games like to play with ``intBitsToFloat`` / ``floatBitsToInt``, so it's
  possible to have VS write int and FS read float (in that case, we treat the
  underlying bits as float, allowing for NaN normalization)

In practice you have to follow these rules:

* Only FS knows a varying smoothness, VS sees everything as flat.
* When linked together, you cannot trust highp flat types, but you can trust
  precision
* While loading/storing data, mistaking a float for an int is ok, mistaking an
  int for a float seems to be lossy even without bit-size conversions.  Be
  conservative on what you say is a float.
* You cannot lower flat varyings after they passed through ``nir_opt_varying``

Current implementation rules:

* VS decides the memory layout
* Descriptor formats can mismatch between stages (eg. VS int - FS float)
* Descriptor formats always match what the instructions are using


To regain the type information:

* in VS, every highp varying is written as U32
* in FS, highp flat varyings are read as U32, highp smooth are read as F32
* for mediump, we trust the original type