# 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