# Akari GPU ABI

Self-contained layout rules. Akari never links engine code; hosts must match these offsets on the CPU.

Language syntax: [`docs/reference/akari-language.md`](/docs/reference/akari-language.md). Grammar: [`syntax.ebnf`](https://github.com/Flying-Rat/hikari/blob/develop/src/akari/syntax.ebnf). Product shader packaging: [`docs/guides/shaders.md`](/docs/guides/shaders.md).

## Scalar and vector

| Type | Size | Uniform align | Storage align |
|------|------|---------------|---------------|
| `bool` | 4 (0/1 as `u32`) | 4 | 4 |
| `i32` / `u32` / `f32` | 4 | 4 | 4 |
| `uint64` / `u64` | 8 | 8 | 8 |
| `float2` / `int2` / `uint2` | 8 | 8 | 4 |
| `float3` / `int3` / `uint3` | 12 | 16 | 4 |
| `float4` / `int4` / `uint4` | 16 | 16 | 4 |

## Matrices

Column-major. Each column is a vector with the alignment rules above.

| Type | Uniform size (rounded) | Notes |
|------|------------------------|-------|
| `float4x4` | 64 | 4 × `float4` |
| `float3x3` | 48 | 3 × `float3` padded to 16 per column in uniform |

## Structs

- Alignment = max member alignment
- Size rounded up to struct alignment
- Members laid out in declaration order with padding for alignment
- No bitfields
- `@packed` on a struct forces **storage** packing for that type even when nested
  under a uniform context (tight member align; no std140 float3 padding). Use only
  for storage/vertex-like payloads that the CPU mirrors the same way.

```akari
@packed
struct PackedV {
    a: float
    b: float3   // offset 4, size 12 under storage rules
}
```

## Arrays

| Context | Element stride |
|---------|----------------|
| Uniform / constant | each element aligned to **16** (std140 array rule) |
| Structured / storage (`Buf` / `RwBuf`) | tightly packed to element size/align |
| Inside `@packed` struct | storage packing (tight) |

## Buffer kinds

| Authoring type | Layout rules |
|----------------|--------------|
| `Uniform<T>` | uniform/constant (std140-like) |
| `Buf<T>` / `RwBuf<T>` | structured/storage packing |
| `AtomicBuf<T>` | storage packing |

## Endianness

Little-endian (documented assumption).

## Validation

Layout queries use checked 32-bit sizes and offsets. Recursive value types, unknown types, and arithmetic overflow are compilation errors; layouts are memoized per type and packing class. Layout traversal also diagnoses excessively deep value-type nesting. Use `akari transpile --dump-layout` for JSON offsets/sizes. Host CI that compares CPU mirrors is optional and lives outside Akari.