acos-without-saturate
Status: stub. The full-length analysis is queued for a v1.0.x patch release per ADR 0018, section 5, criterion #6. The companion rule page at docs/rules/acos-without-saturate.md contains the canonical detection logic + GPU reasoning.
TL;DR
The IEEE 754 specification for acos returns NaN for any argument outside [-1, 1]. Hardware implementations on AMD RDNA 2/3 (v_acos_f32), NVIDIA Turing/Ada (MUFU.RCOS family), and Intel Xe-HPG (the transcendental pipe) faithfully implement this: feed 1.0 + 1e-7 and you get a NaN, which then propagates through every subsequent math op into the final colour write. A single NaN pixel in a deferred shading buffer corrupts every subsequent neighbourhood operation (TAA, denoisers, blur), often manifesting as a black or fluorescent-pink dot that grows over a few frames. This is one of the most common GPU correctness bugs in production rendering code.
What the rule fires on
Calls to acos(x) (and asin(x)) where the argument is the result of a dot(a, b) between two vectors that are not both provably unit-length, or any other expression whose value is mathematically in [-1, 1] but, due to floating-point rounding, can land just outside that range. The canonical pattern is acos(dot(normalize(a), normalize(b))) where the two normalize calls produce vectors whose dot product can round to 1.0 + epsilon or -1.0 - epsilon; acos of an out-of-domain argument returns NaN.
See the What it detects section of the rule page for the full pattern definition.
Why it matters
The full GPU-mechanism analysis lives in the Why it matters on a GPU section of the companion rule page.
Examples
The bad / good code snippets are kept canonical on the rule page; see acos-without-saturate.md -> Examples.
See also
- Rule page -- canonical reference + change log.
- math overview -- broader context.
- ADR 0018 -- v1.0 readiness plan.
This is a v1.0-ship stub. Full analysis pending; track issue link TBD.