From dd9c86d07a12307ef0c15eff88b21b2df73fc8cd Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Fri, 31 Jul 2026 19:49:55 -0700 Subject: [PATCH] docs: correct the --hf-color-grading-intensity claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both pages said intensity does not scale a grade and that 0.5 renders the same as 0. That is wrong, and the error was mine: I tested intensity only against twoInkPrint and tapeDamage, then generalised from an effects-only result. The shader mixes ungraded against graded at u_intensity (runtime/colorGrading.ts:1234), so it does scale adjust, wheels, curves, hueCurves, secondaries and the LUT. Runtime tests pin 0.25 and 0.75 reaching the uniform. What it does not scale is details and effects — grain, filmArtifacts, monoScreen, engraving, crosshatch, halftone, twoInkPrint and the tape/CRT families are all applied after that mix (:1235-1262), which is exactly what I had measured. Both pages now say intensity ramps the primary grade only, and to animate the specific effect when the look is effect-based. Reported by miguel-heygen. Co-Authored-By: Claude Opus 5 (1M context) --- docs/guides/color-grading.mdx | 10 +++++++--- docs/prompting/color-grading.mdx | 2 +- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/guides/color-grading.mdx b/docs/guides/color-grading.mdx index 4a74a8877..1c181e8a5 100644 --- a/docs/guides/color-grading.mdx +++ b/docs/guides/color-grading.mdx @@ -268,9 +268,13 @@ just the endpoints. Two things this list does **not** give you: -- **`--hf-color-grading-intensity` does not scale a grade at render time.** - Setting it to `0.5` renders the same as `0`, and animating `0 → 1` produces no - change. Do not reach for it as a generic "ramp the whole look" dial. +- **`--hf-color-grading-intensity` scales the primary grade only.** The shader + mixes between the ungraded sample and the graded one at that value, so it + ramps `adjust`, `wheels`, `curves`, `hueCurves`, `secondaries` and the LUT. + It does **not** touch `details` or `effects` — grain, vignette, halftone, + twoInkPrint, bloom, the tape and CRT families are all applied *after* that + mix. So it is not a master "ramp the whole look" dial when the look is + effect-based; animate the specific effect instead. - **Every other property — `halftone`, `twoInkPrint`, `tapeDamage`, hue curves, secondaries — has no custom property**, so it cannot be tweened this way. diff --git a/docs/prompting/color-grading.mdx b/docs/prompting/color-grading.mdx index 88942ad35..1e6d06cb3 100644 --- a/docs/prompting/color-grading.mdx +++ b/docs/prompting/color-grading.mdx @@ -159,7 +159,7 @@ Nine properties expose a CSS custom property and tween directly — `ascii`, `bl Two caveats worth knowing before you promise a client a ramp: -- **`--hf-color-grading-intensity` does not scale a grade at render time.** A static `0.5` renders the same as `0`. Do not reach for it as a generic "ramp the whole look" dial. +- **`--hf-color-grading-intensity` scales the primary grade only** — `adjust`, `wheels`, `curves`, `hueCurves`, `secondaries` and the LUT. It does *not* scale `details` or `effects`, which are applied after that mix, so it will not ramp grain, halftone, bloom or the tape and CRT families. Reach for the specific effect instead of treating it as a master dial. - **Everything else has no custom property.** Some of those can still be animated by rewriting the `data-color-grading` payload from the timeline, and some cannot — the verified list of which is which lives in the guide's [Animating a Grade](/guides/color-grading#animating-a-grade), so it only has to be maintained in one place. Measure the effect you intend to animate before you promise a ramp, and fall back to a static treatment if it does not move. ## Next steps