# Known Issues and Gaps

## DXBC Backend

### Not Implemented (emit error diagnostic)

- **`asin`, `acos`, `atan`, `atan2`** — No SM5.0 native equivalent. These emit an `.Error`
  diagnostic and return zero. A polynomial approximation (e.g. Chebyshev minimax) is
  needed for correctness.

- **`determinant`, `inverse`** — No SM5.0 native equivalent. These emit an `.Error`
  diagnostic and return zero. Encoding them manually requires 16–40+ instructions and
  is left as future work.

### Correctness Bugs

- **`distance` with an inline-constructed constant vector argument** — e.g.
  `distance(pos, vec3(1.0, 0.0, 0.0))` produces bytecode that D3DDisassemble rejects
  (`E_FAIL 0x80004005`). The same call with both args as shader inputs passes. Root cause
  not yet identified; suspected issue in how a 3-component `ADD` with a negate modifier
  interacts with the constructed-constant temp register encoding. Workaround: pre-assign
  the constant to a `let` binding before passing to `distance`.

### Partial / Untested

- **`mat * mat`** — Implemented for the cbuffer × cbuffer case via MUL+MAD column chains.
  The temp-register × temp-register path (for matrices returned from function calls or
  constructed inline) relies on a convention that consecutive temp indices hold matrix
  columns; this convention is not enforced at allocation time and has not been validated.

- **`transpose`** — Only the 4×4 cbuffer matrix case is implemented. Non-cbuffer matrices
  and non-square sizes emit a `.Warning` diagnostic and return the input unchanged.

- **`sample_level`** — Implemented and encoded (SAMPLE_L opcode). Not yet covered by a
  golden-file test.

- **`refract`** — Implemented as an inline formula (~15 instructions). Not yet covered by a
  golden-file test.

- **TGSM / `IR_Shared_Ref`** — `dcl_tgsm_structured`, `ld_structured`, and
  `store_structured` are emitted for compute shader shared variables. The instructions are
  encoded but have not been validated against D3DDisassemble, since compute shaders still
  fail the validator for unrelated reasons (see below).

- **Dynamic `IR_Index` / indexable temps** — `dcl_indexable_temp` is declared and
  `x0[r.x]` relative-addressing is emitted for dynamically-indexed array variables.
  Not yet exercised by any test shader.

### Compute Shader Gaps

- **D3DDisassemble still rejects compute shaders.** The existing `compute_basic` test
  passes our validator only because the validator calls `D3DDisassemble` which currently
  appears to pass — but the previously-documented compute issue (`docs/dxbc_compute_issue.md`)
  noted C++ exceptions in d3dcompiler_47.dll for compute shaders with barriers or UAVs.
  Full compute parity requires:
  - UAV / storage-buffer declarations (`dcl_uav_typed`, `dcl_uav_structured`) — not
    implemented; `IR_Binding_Kind.Buffer` has a TODO in `dxbc_setup_bindings`.
  - Structured buffer load/store for UAVs (`ld_uav_typed`, `store_uav_typed`) — opcodes
    not yet defined in `dxbc_spec.odin`.

### Tooling

- **`tools/dxbc_dump.py` has incorrect opcode labels.** The dump script decodes the raw
  opcode integer but does not have a complete name table for SM5.0. Many instructions are
  shown with wrong names (e.g. `dcl_temps` is labeled `dcl_thread_group`,
  `dcl_globalFlags` is labeled `dcl_tgsm_raw`, `dcl_input_ps` is labeled `dcl_output`).
  The raw bytes are correct; only the text labels are wrong. The actual D3DDisassemble
  output (when it succeeds) is authoritative.

---

## SPIR-V Backend

- **`sample_level`** — No `OpImageSampleExplicitLod` emission; only implicit-LOD sampling
  is implemented.

- **`asin`, `acos`, `atan`, `atan2`** — Mapped through `GLSL.std.450` extended
  instructions (Asin, Acos, Atan, Atan2); these exist in the enum but are not listed in
  `spirv_glsl_ext_inst`. Verify coverage.

---

## MSL Backend

- **Many math builtins are missing from `builtin_to_msl`.** Only 9 functions are
  explicitly mapped. Functions like `sin`, `cos`, `sqrt`, `abs`, `clamp`, `min`, `max`,
  `pow`, `exp`, `log`, `floor`, `ceil`, `round`, `sign`, `step`, etc. are not in the
  switch and fall through to identity (the name is passed through unchanged). This happens
  to work for functions whose name matches the MSL name, but is fragile.

- **`sample_level`** — Noted in a comment as unimplemented (would need `.sample(s, uv,
  level(lod))`).

---

## All Backends

- **Geometry and tessellation shaders** — `Shader_Stage.Geometry`,
  `.Tessellation_Control`, `.Tessellation_Eval` are defined in the IR but no backend
  emits code for them.

- **Atomic operations** — Not exposed in the IR or any backend.

- **Image load/store** — Only texture sampling is implemented; no
  `imageLoad`/`imageStore` (SPIR-V), `read`/`write` (MSL), or UAV typed
  load/store (DXBC).

- **Ray tracing** — Not supported.