pixon 0.8.0

SIMD-dispatched color conversion for the FFmpeg AVPixelFormat space: one-call decode of validated source frames to RGB / RGBA / Luma / HSV, fused resampling while converting, colorimetry-honest matrices and chroma siting, no_std-friendly.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
//! The BT.2100 curves and the analysis mapping, held to the published values.
//!
//! The curve anchors are the ones the private `pq_hlg` module carried until
//! the curves became public: `colour-science` docstring examples
//! (`eotf_ST2084` / `eotf_inverse_ST2084`, `oetf_ARIBSTDB67`) and the exact
//! construction points of ITU-R BT.2100-2 Tables 4 and 5. A transcription
//! error in any constant moves them well outside the stated tolerances. The
//! mapping laws state the numbers the module note states: BT.2408's
//! reference white and 18% grey, BT.2087's gamut matrix, the knee at 0.75,
//! and the inverse BT.1886 encode.

use super::{
  HLG_NOMINAL_PEAK_NITS, HdrTransfer, KNEE_START, MapError, PQ_PEAK_NITS, REFERENCE_WHITE_NITS,
  SdrMapping, expf32, hlg_inverse_oetf, hlg_oetf, hlg_ootf, hlg_system_gamma, mapping::knee,
  powf32, pq_eotf, pq_inverse_eotf,
};
use crate::{Primaries, Transfer};

/// BT.2020's luminance row, BT.2100 Table 5's `Y_s` weights.
const BT2020_LUMINANCE: [f32; 3] = [0.2627, 0.6780, 0.0593];

/// The knee the module note states. The laws spell the number rather than
/// read [`KNEE_START`], so a moved knee is caught here.
const STATED_KNEE: f32 = 0.75;

/// The stated knee applied to light relative to reference white.
fn stated_knee(light: f32) -> f32 {
  if light <= STATED_KNEE {
    light
  } else {
    let room = 1.0 - STATED_KNEE;
    STATED_KNEE + room * (1.0 - expf32(-(light - STATED_KNEE) / room))
  }
}

/// A `[0, 1]` signal to a full-range 8-bit code, rounded to nearest.
fn code(signal: f32) -> u8 {
  (signal * 255.0 + 0.5) as u8
}

/// Every HDR transfer, as the vocabulary spells it.
const HDR: [Transfer; 2] = [Transfer::SmpteSt2084Pq, Transfer::AribStdB67Hlg];

/// The relative slack every float law in this file takes under Miri.
///
/// Miri adds a few ULP of noise to every float intrinsic call (`powf`, `exp`, `ln`, `log10`), and
/// the PQ chain's `(vp − c1)` and `1/m1` power amplify it: CI has seen 1.15e-3 relative on a
/// `map_signal` probe. One hundredth is that with a wide margin, and it is still a law: a wrong
/// constant or a wrong curve moves these values by far more.
const MIRI_RELATIVE: f32 = 1e-2;

/// THE ONE HELPER: the slack two computed values `a` and `b` get — none on real hardware, and
/// [`MIRI_RELATIVE`] of the larger magnitude under Miri. Every comparison below reads it, so a law
/// never carries a Miri tolerance of its own.
fn miri_slack(a: f32, b: f32) -> f32 {
  if cfg!(miri) {
    MIRI_RELATIVE * a.abs().max(b.abs())
  } else {
    0.0
  }
}

/// Whether two computations of one value agree: within `native` on real hardware, and within the
/// larger of `native` and [`miri_slack`] under Miri.
fn near(a: f32, b: f32, native: f32) -> bool {
  (a - b).abs() <= native.max(miri_slack(a, b))
}

/// `a < b`, with [`miri_slack`] under Miri.
fn below(a: f32, b: f32) -> bool {
  a < b + miri_slack(a, b)
}

/// `a <= b`, with [`miri_slack`] under Miri.
fn at_most(a: f32, b: f32) -> bool {
  a <= b + miri_slack(a, b)
}

/// Whether two computations of one pixel quantise alike: equal on real hardware; under Miri as far
/// apart as [`MIRI_RELATIVE`] of full scale can move a code, plus one for a rounding boundary.
fn same_codes(a: [u8; 3], b: [u8; 3]) -> bool {
  let codes = if cfg!(miri) {
    1 + (MIRI_RELATIVE * 255.0) as u8
  } else {
    0
  };
  a.iter().zip(b).all(|(x, y)| x.abs_diff(y) <= codes)
}

// ---- the BT.2100 curves ---------------------------------------------------

#[test]
fn pq_matches_st2084_reference() {
  // BT.2100 anchors: signal 1.0 ↔ linear 1.0 (= 10 000 cd/m²), signal 0 ↔
  // linear 0. The signal-1.0 fixed point holds iff c1 = c3 − c2 + 1.
  assert!(near(pq_eotf(1.0), 1.0, 1e-6), "eotf(1.0)={}", pq_eotf(1.0));
  assert!(near(pq_eotf(0.0), 0.0, 1e-9), "eotf(0.0)={}", pq_eotf(0.0));
  assert!(
    near(pq_inverse_eotf(1.0), 1.0, 1e-5),
    "oetf(1.0)={}",
    pq_inverse_eotf(1.0)
  );

  // colour-science `eotf_inverse_ST2084(100)` = 0.5080784: 100 cd/m² is the
  // normalised linear 0.01, encoded to signal 0.5080784. This single point
  // pins all five PQ constants in the encode direction.
  const SIGNAL_100_NITS: f32 = 0.508_078_4;
  assert!(
    near(pq_inverse_eotf(0.01), SIGNAL_100_NITS, 5e-4),
    "oetf(0.01)={} want {SIGNAL_100_NITS}",
    pq_inverse_eotf(0.01),
  );
  // colour-science `eotf_ST2084(0.508078421517399)` = 100 cd/m²: the decode
  // direction of the same anchor (normalised 0.01).
  assert!(
    near(pq_eotf(SIGNAL_100_NITS), 0.01, 1e-4),
    "eotf({SIGNAL_100_NITS})={} want 0.01",
    pq_eotf(SIGNAL_100_NITS),
  );

  // PQ's inverse-EOTF maps linear 0 to a small non-zero signal `c1^m2`
  // (≈ 7.3e-7), a known property of the curve — assert it stays negligible.
  assert!(
    near(pq_inverse_eotf(0.0), 0.0, 1e-5),
    "oetf(0.0)={}",
    pq_inverse_eotf(0.0)
  );
}

#[test]
fn a_super_white_saturates_at_the_peak() {
  // PQ signal E' is defined on [0, 1]; a super-white magnitude saturates at
  // the peak (linear 1.0) — it must NOT cross the den=0 pole at |c| ~= 1.99
  // (which overflows toward +inf just below it and folds to black just above
  // it). Pins values straddling the pole.
  for &c in &[1.0_f32, 1.5, 1.99, 2.0, 10.0] {
    let y = pq_eotf(c);
    assert!(y.is_finite(), "pq_eotf({c})={y} must be finite");
    assert!(
      near(y, 1.0, 1e-6),
      "pq_eotf({c})={y} must saturate at 1.0 (not inf/black)"
    );
  }
  // Odd extension: super-black saturates at -1.0.
  assert!(
    near(pq_eotf(-2.0), -1.0, 1e-6),
    "pq_eotf(-2.0)={}",
    pq_eotf(-2.0)
  );

  // HLG likewise clamps the [0, 1] signal domain (its log segment would grow
  // unbounded for E' > 1); a super-white input equals the peak hlg_inverse_oetf(1.0).
  let hlg_peak = hlg_inverse_oetf(1.0);
  for &c in &[1.0_f32, 2.0, 10.0] {
    let e = hlg_inverse_oetf(c);
    assert!(
      e.is_finite() && near(e, hlg_peak, 1e-6),
      "hlg_inverse_oetf({c})={e} must saturate at hlg_inverse_oetf(1.0)={hlg_peak}"
    );
  }
}

#[test]
fn hlg_matches_bt2100_reference() {
  // BT.2100 breakpoint: scene-linear 1/12 (HLG reference white) encodes to
  // signal 0.5, and the lower (gamma) segment is exact there.
  assert!(
    near(hlg_oetf(1.0 / 12.0), 0.5, 1e-6),
    "oetf(1/12)={}",
    hlg_oetf(1.0 / 12.0),
  );
  // Inverse breakpoint: signal 0.5 decodes back to scene-linear 1/12.
  assert!(
    near(hlg_inverse_oetf(0.5), 1.0 / 12.0, 1e-6),
    "eotf(0.5)={}",
    hlg_inverse_oetf(0.5),
  );

  // colour-science `oetf_ARIBSTDB67(0.18)` = 0.2121320. Under the BT.2100
  // normalisation E = E_arib / 12, that is `oetf(0.015)` — a lower (gamma)
  // segment point: sqrt(3·0.015) = 0.2121320.
  assert!(
    near(hlg_oetf(0.015), 0.212_132, 1e-5),
    "oetf(0.015)={}",
    hlg_oetf(0.015),
  );
  assert!(
    near(hlg_inverse_oetf(0.212_132), 0.015, 1e-5),
    "eotf(0.2121320)={}",
    hlg_inverse_oetf(0.212_132),
  );

  // Upper (log) segment construction anchors — these exercise a, b and c:
  // scene-linear 1.0 ↔ signal 1.0 (c is defined to make this hold), and
  // scene-linear 0 ↔ signal 0.
  assert!(
    near(hlg_oetf(1.0), 1.0, 1e-4),
    "oetf(1.0)={}",
    hlg_oetf(1.0)
  );
  assert!(
    near(hlg_inverse_oetf(1.0), 1.0, 1e-4),
    "eotf(1.0)={}",
    hlg_inverse_oetf(1.0)
  );
  assert!(
    near(hlg_oetf(0.0), 0.0, 1e-9),
    "oetf(0.0)={}",
    hlg_oetf(0.0)
  );
  assert!(
    near(hlg_inverse_oetf(0.0), 0.0, 1e-9),
    "eotf(0.0)={}",
    hlg_inverse_oetf(0.0)
  );
}

#[test]
fn each_curve_inverts_its_pair() {
  // EOTF and OETF are exact analytic inverses; verify the f32 round-trip
  // over the unit signal interval. (The round-trip is insensitive to the
  // constants' absolute values — the `*_matches_*_reference` tests pin
  // those — so this guards only the inverse relationship.)
  for i in 0..=256 {
    let c = i as f32 / 256.0;
    let pq = pq_inverse_eotf(pq_eotf(c));
    assert!(near(pq, c, 2e-3), "pq oetf(eotf({c}))={pq}");
    let pq2 = pq_eotf(pq_inverse_eotf(c));
    assert!(near(pq2, c, 2e-3), "pq eotf(oetf({c}))={pq2}");
    let hlg = hlg_oetf(hlg_inverse_oetf(c));
    assert!(near(hlg, c, 1e-3), "hlg oetf(eotf({c}))={hlg}");
    let hlg2 = hlg_inverse_oetf(hlg_oetf(c));
    assert!(near(hlg2, c, 1e-3), "hlg eotf(oetf({c}))={hlg2}");
  }
}

#[test]
fn each_curve_is_odd() {
  // The per-channel curves are odd (`f(-c) == -f(c)`) so super-black
  // excursions linearise symmetrically rather than folding — the same
  // contract the SDR curves honour.
  for &c in &[0.05_f32, 0.25, 0.6, 0.9] {
    assert!(near(pq_eotf(-c), -pq_eotf(c), 1e-6), "pq eotf odd at {c}");
    assert!(
      near(pq_inverse_eotf(-c), -pq_inverse_eotf(c), 1e-6),
      "pq oetf odd at {c}"
    );
    assert!(
      near(hlg_inverse_oetf(-c), -hlg_inverse_oetf(c), 1e-6),
      "hlg eotf odd at {c}"
    );
    assert!(
      near(hlg_oetf(-c), -hlg_oetf(c), 1e-6),
      "hlg oetf odd at {c}"
    );
  }
}

#[test]
fn the_hdr_curves_differ_from_sdr() {
  // A mid-tone linearises differently under the HDR curves than the SDR
  // BT.1886 default, so the BT.2100 decode is observably distinct.
  let c = 0.5_f32;
  let bt1886 = crate::resample::TransferFunction::Bt1886.eotf(c);
  let pq = pq_eotf(c);
  let hlg = hlg_inverse_oetf(c);
  assert!(
    below(1e-3, (pq - bt1886).abs()),
    "PQ vs BT.1886 must differ"
  );
  assert!(
    below(1e-3, (hlg - bt1886).abs()),
    "HLG vs BT.1886 must differ"
  );
  assert!(below(1e-3, (pq - hlg).abs()), "PQ vs HLG must differ");
}

// ---- BT.2100 and BT.2408 anchors the mapping is built on -------------------

/// BT.2408 puts HDR reference white, 203 cd/m², at PQ 58%, and BT.2100's
/// 1000 cd/m² at PQ 75%.
#[test]
fn pq_places_reference_white_at_58_percent() {
  let white = pq_inverse_eotf(REFERENCE_WHITE_NITS / PQ_PEAK_NITS);
  assert!(near(white, 0.5806, 1e-3), "PQ(203 cd/m²) = {white}");
  let thousand = pq_inverse_eotf(1000.0 / PQ_PEAK_NITS);
  assert!(near(thousand, 0.7518, 1e-3), "PQ(1000 cd/m²) = {thousand}");
}

/// BT.2408 on the 1000 cd/m² reference display: HLG 75% is reference white,
/// 203 cd/m², and HLG 38% is 18% grey, 26 cd/m².
#[test]
fn hlg_places_reference_white_at_75_percent() {
  let white = hlg_ootf(
    [hlg_inverse_oetf(0.75); 3],
    BT2020_LUMINANCE,
    HLG_NOMINAL_PEAK_NITS,
  );
  assert!(near(white[1], 203.0, 1.0), "HLG 75% = {} cd/m²", white[1]);
  let grey = hlg_ootf(
    [hlg_inverse_oetf(0.38); 3],
    BT2020_LUMINANCE,
    HLG_NOMINAL_PEAK_NITS,
  );
  assert!(near(grey[1], 26.0, 0.5), "HLG 38% = {} cd/m²", grey[1]);
  assert_eq!(
    hlg_ootf([0.0; 3], BT2020_LUMINANCE, HLG_NOMINAL_PEAK_NITS),
    [0.0; 3],
    "black is black on any display"
  );
}

/// BT.2100 Table 5: γ = 1.2 at 1000 cd/m², and `1.2 + 0.42·log10(L_W/1000)`
/// beside it.
#[test]
fn the_hlg_system_gamma_is_bt2100s() {
  assert!(near(hlg_system_gamma(1000.0), 1.2, 0.0));
  assert!(near(hlg_system_gamma(2000.0), 1.326_433, 1e-5));
  assert!(near(hlg_system_gamma(400.0), 1.032_867, 1e-5));
}

/// The matrix from BT.2020 to BT.709 is ITU-R BT.2087-0's, and BT.2020's
/// luminance row is BT.2100's `Y_s` weights: both derived from the
/// chromaticities `mediaframe` tabulates, not copied.
#[test]
fn the_gamut_matrix_from_bt2020_is_bt2087s() {
  const BT2087: [[f32; 3]; 3] = [
    [1.6605, -0.5876, -0.0728],
    [-0.1246, 1.1329, -0.0083],
    [-0.0182, -0.1006, 1.1187],
  ];
  let mapping = SdrMapping::for_picture(&Transfer::SmpteSt2084Pq, &Primaries::Bt2020)
    .expect("BT.2020 converts");
  let hdr = mapping.hdr.as_ref().expect("PQ maps");
  for (row, (got, want)) in hdr.to_bt709.iter().zip(BT2087).enumerate() {
    for column in 0..3 {
      assert!(
        near(got[column], want[column], 2e-4),
        "[{row}][{column}] = {} want {}",
        got[column],
        want[column],
      );
    }
  }
  for (got, want) in hdr.luminance.iter().zip(BT2020_LUMINANCE) {
    assert!(near(*got, want, 1e-4), "luminance {got} want {want}");
  }
}

// ---- the mapping ----------------------------------------------------------

/// The knee starts at 0.75 of SDR white: identity below, slope one at the
/// start, rising above, and never past white. It rises strictly as far as
/// `f32` resolves the increments. Near the asymptote two steps can round to
/// the same value, so beyond two whites the law asks only that it never falls.
#[test]
fn the_knee_starts_where_stated() {
  for step in 0..=75 {
    let light = step as f32 / 100.0;
    assert_eq!(
      knee(light),
      light,
      "below the knee, {light} passes unchanged"
    );
  }
  let slope = (knee(STATED_KNEE + 1e-3) - knee(STATED_KNEE)) / 1e-3;
  assert!(near(slope, 1.0, 1e-2), "slope at the knee {slope}");
  let mut previous = knee(STATED_KNEE);
  for step in 1..=400 {
    let light = STATED_KNEE + step as f32 / 50.0;
    let rolled = knee(light);
    if light <= 2.0 {
      assert!(below(previous, rolled), "rising at {light}: {rolled}");
    } else {
      assert!(
        at_most(previous, rolled),
        "never falling at {light}: {rolled}"
      );
    }
    assert!(
      below(rolled, light) && at_most(rolled, 1.0),
      "compressed at {light}: {rolled}"
    );
    previous = rolled;
  }
  assert!(
    below(knee(2.0), 1.0),
    "two whites still below white: {}",
    knee(2.0)
  );
}

/// A PQ ramp and an HLG ramp of neutral greys map into `[0, 1]`, rising,
/// with each output the stated knee of its display light, encoded by the
/// inverse BT.1886 EOTF.
#[test]
fn a_pq_and_an_hlg_ramp_map_into_sdr_with_the_stated_knee() {
  for transfer in HDR {
    let mapping = SdrMapping::for_picture(&transfer, &Primaries::Bt2020).expect("BT.2020 converts");
    let mut previous = 0.0f32;
    for step in 0..=1023 {
      let signal = step as f32 / 1023.0;
      let out = mapping.map_signal([signal; 3]);
      for channel in out {
        assert!(
          (0.0..=1.0).contains(&channel),
          "{transfer:?} {signal}: {out:?}"
        );
        assert!(near(channel, out[1], 1e-5), "grey stays grey: {out:?}");
      }
      assert!(
        at_most(previous, out[1] + 1e-6),
        "{transfer:?} rising at {signal}"
      );
      previous = out[1];

      let light = match transfer {
        Transfer::SmpteSt2084Pq => pq_eotf(signal) * 10_000.0 / 203.0,
        _ => 1000.0 * powf32(hlg_inverse_oetf(signal), 1.2) / 203.0,
      };
      let shown = powf32(out[1], 2.4);
      let want = stated_knee(light);
      assert!(
        near(shown, want, 2e-4 + 2e-4 * want),
        "{transfer:?} {signal}: shown {shown} want {want} from light {light}",
      );
      if light > STATED_KNEE {
        assert!(
          below(shown, light),
          "above the knee the light is compressed: {shown} from {light}"
        );
      }
    }
  }
}

/// PQ 58% and HLG 75% (reference white) land at 0.961, and BT.2408's 18%
/// grey (26 cd/m²) at 0.425: the stated knee, then the inverse BT.1886
/// encode.
#[test]
fn reference_white_and_grey_land_where_stated() {
  let pq = SdrMapping::for_picture(&Transfer::SmpteSt2084Pq, &Primaries::Bt2020).expect("PQ");
  let hlg = SdrMapping::for_picture(&Transfer::AribStdB67Hlg, &Primaries::Bt2020).expect("HLG");

  let white = pq.map_signal([pq_inverse_eotf(203.0 / 10_000.0); 3])[1];
  assert!(near(white, 0.9606, 1e-3), "PQ reference white {white}");
  let white = hlg.map_signal([0.75; 3])[1];
  assert!(near(white, 0.9606, 2e-3), "HLG reference white {white}");

  let grey = pq.map_signal([pq_inverse_eotf(26.0 / 10_000.0); 3])[1];
  assert!(near(grey, 0.4247, 1e-3), "PQ 18% grey {grey}");
  let grey = hlg.map_signal([0.38; 3])[1];
  assert!(near(grey, 0.4264, 2e-3), "HLG 18% grey {grey}");
}

/// The declared gamut is converted: a saturated BT.2020 green is not the
/// picture the same codes make over BT.709, while a grey is the same in
/// both. An unspecified gamut reads as BT.2020, and BT.709 converts by the
/// identity.
#[test]
fn the_declared_gamut_is_converted_to_bt709() {
  for transfer in HDR {
    let wide = SdrMapping::for_picture(&transfer, &Primaries::Bt2020).expect("BT.2020");
    let narrow = SdrMapping::for_picture(&transfer, &Primaries::Bt709).expect("BT.709");
    let green = [0.3, 0.6, 0.3];
    let (from_wide, from_narrow) = (wide.map_signal(green), narrow.map_signal(green));
    assert!(
      below(from_wide[0] + 0.05, from_narrow[0]),
      "{transfer:?}: BT.2020 green loses red in BT.709 ({from_wide:?} vs {from_narrow:?})",
    );
    let grey = [0.5; 3];
    let (a, b) = (wide.map_signal(grey), narrow.map_signal(grey));
    for channel in 0..3 {
      assert!(near(a[channel], b[channel], 1e-5), "grey: {a:?} vs {b:?}");
    }
    let unstated =
      SdrMapping::for_picture(&transfer, &Primaries::Unspecified).expect("unspecified");
    if cfg!(miri) {
      // Miri's float-intrinsic noise: each construction builds its 8-bit table through its own
      // `powf`/`exp` calls, so two equal mappings agree there only within `near`.
      assert_eq!(unstated.transfer(), wide.transfer());
      let (a, b) = (
        unstated.hdr.as_ref().expect("maps"),
        wide.hdr.as_ref().expect("maps"),
      );
      for (x, y) in a.to_bt709.iter().flatten().zip(b.to_bt709.iter().flatten()) {
        assert!(
          near(*x, *y, 0.0),
          "an unspecified gamut is BT.2020: {x} vs {y}"
        );
      }
      for (x, y) in a.luminance.iter().zip(&b.luminance) {
        assert!(near(*x, *y, 0.0), "and so is its luminance: {x} vs {y}");
      }
      for probe in [[0.1, 0.4, 0.9], [0.5; 3], [0.75, 0.2, 0.3], [1.0, 1.0, 0.0]] {
        let (x, y) = (unstated.map_signal(probe), wide.map_signal(probe));
        for channel in 0..3 {
          assert!(
            near(x[channel], y[channel], 0.0),
            "{probe:?}: {x:?} vs {y:?}"
          );
        }
      }
    } else {
      assert_eq!(unstated, wide, "an unspecified gamut is BT.2020");
    }
    let identity = narrow.hdr.as_ref().expect("maps").to_bt709;
    for (row, line) in identity.iter().enumerate() {
      for (column, value) in line.iter().enumerate() {
        let want = if row == column { 1.0 } else { 0.0 };
        assert!(
          near(*value, want, 1e-6),
          "BT.709 to BT.709 [{row}][{column}] {value}"
        );
      }
    }
  }
}

/// Every transfer but PQ and HLG builds a passthrough, and a passthrough
/// leaves a BT.709 picture as it is, through every face.
#[test]
fn a_bt709_picture_passes_through_unchanged() {
  for transfer in [
    Transfer::Bt709,
    Transfer::Unspecified,
    Transfer::Smpte170M,
    Transfer::Bt2020_10Bit,
    Transfer::Iec6196621,
    Transfer::Linear,
  ] {
    let mapping = SdrMapping::for_picture(&transfer, &Primaries::Bt709).expect("SDR");
    assert!(mapping.is_passthrough(), "{transfer:?}");
    assert_eq!(mapping.transfer(), None);
    let original: [u8; 768] = core::array::from_fn(|i| (i * 7 % 256) as u8);
    let mut rgb = original;
    mapping.map_rgb8(&mut rgb);
    assert_eq!(
      rgb, original,
      "{transfer:?}: the 8-bit face changed nothing"
    );
    assert_eq!(mapping.map_signal([0.1, 0.5, 0.9]), [0.1, 0.5, 0.9]);
    let mut narrowed = [0u8; 6];
    mapping
      .map_rgb16(&[0, 512, 1023, 1023, 0, 256], 10, &mut narrowed)
      .expect("whole pixels");
    assert_eq!(
      narrowed,
      [0, 128, 255, 255, 0, 64],
      "only the depth narrows"
    );
  }
  assert!(
    SdrMapping::for_picture(&Transfer::Bt709, &Primaries::Film)
      .expect("an SDR picture is never refused")
      .is_passthrough()
  );
  assert!(SdrMapping::passthrough().is_passthrough());
}

/// A PQ or HLG picture over a gamut with no derivable BT.709 conversion is
/// refused, naming both its transfer and its gamut.
#[test]
fn a_gamut_with_no_conversion_is_refused_by_name() {
  for primaries in [
    Primaries::Film,
    Primaries::Bt470M,
    Primaries::SmpteRp431,
    Primaries::SmpteSt428,
    Primaries::other("vendor-gamut"),
  ] {
    for transfer in HDR {
      let refused = SdrMapping::for_picture(&transfer, &primaries).expect_err("refused");
      assert_eq!(refused.primaries(), &primaries);
      assert_eq!(Some(refused.transfer()), HdrTransfer::of(&transfer));
      let said = std::format!("{refused}");
      assert!(said.contains(primaries.as_str()), "{said}");
      assert!(said.contains(refused.transfer().as_str()), "{said}");
    }
  }
  for primaries in [
    Primaries::Bt709,
    Primaries::Bt2020,
    Primaries::SmpteEg432,
    Primaries::Bt470Bg,
    Primaries::Smpte170M,
    Primaries::Smpte240M,
    Primaries::Ebu3213E,
    Primaries::Unspecified,
  ] {
    for transfer in HDR {
      assert!(
        SdrMapping::for_picture(&transfer, &primaries).is_ok(),
        "{primaries:?} has a D65 white and converts",
      );
    }
  }
}

/// The 8-bit face is the signal face at `code / 255`, quantised to the
/// nearest code.
#[test]
fn the_8_bit_face_is_the_signal_face_quantised() {
  for transfer in HDR {
    for primaries in [Primaries::Bt2020, Primaries::Bt709] {
      let mapping = SdrMapping::for_picture(&transfer, &primaries).expect("converts");
      for value in 0..=255u8 {
        for pixel in [
          [value, value, value],
          [value, 255 - value, value / 2],
          [255, value, 0],
        ] {
          let mut mapped = pixel;
          mapping.map_rgb8(&mut mapped);
          let want = mapping
            .map_signal(pixel.map(|c| c as f32 / 255.0))
            .map(code);
          // The face's table and the signal face are separate intrinsic calls: `same_codes`.
          assert!(
            same_codes(mapped, want),
            "{transfer:?} over {primaries:?}: {pixel:?} gave {mapped:?}, want {want:?}"
          );
        }
      }
      let mut partial = [200u8, 100, 50, 25];
      mapping.map_rgb8(&mut partial);
      assert_eq!(partial[3], 25, "a trailing partial pixel is left alone");
    }
  }
}

/// The 16-bit face maps at its native depth, reads a sample above full
/// scale as full scale, and refuses a depth or a length it cannot map.
#[test]
fn the_16_bit_face_maps_at_its_native_depth() {
  let mapping = SdrMapping::for_picture(&Transfer::AribStdB67Hlg, &Primaries::Bt2020).expect("HLG");
  let rgb: [u16; 6] = [0, 600, 1023, 512, 512, 512];
  let mut out = [0u8; 6];
  mapping.map_rgb16(&rgb, 10, &mut out).expect("whole pixels");
  for (pixel, mapped) in rgb.as_chunks::<3>().0.iter().zip(out.as_chunks::<3>().0) {
    let want = mapping
      .map_signal([0, 1, 2].map(|i| f32::from(pixel[i]) / 1023.0))
      .map(code);
    // The face and the test call the mapping separately: `same_codes`.
    assert!(
      same_codes(*mapped, want),
      "{pixel:?} gave {mapped:?}, want {want:?}"
    );
  }

  let (mut over, mut full) = ([0u8; 3], [0u8; 3]);
  mapping.map_rgb16(&[2000; 3], 10, &mut over).expect("whole");
  mapping.map_rgb16(&[1023; 3], 10, &mut full).expect("whole");
  // Two calls over the same full-scale signal: `same_codes`.
  assert!(
    same_codes(over, full),
    "above full scale reads as full scale"
  );

  assert_eq!(
    mapping.map_rgb16(&rgb, 0, &mut out),
    Err(MapError::Depth { bits: 0 })
  );
  assert_eq!(
    mapping.map_rgb16(&rgb, 17, &mut out),
    Err(MapError::Depth { bits: 17 })
  );
  assert_eq!(
    mapping.map_rgb16(&rgb, 10, &mut out[..3]),
    Err(MapError::LengthMismatch {
      samples: 6,
      bytes: 3
    }),
  );
  assert_eq!(
    mapping.map_rgb16(&rgb[..5], 10, &mut out[..5]),
    Err(MapError::LengthMismatch {
      samples: 5,
      bytes: 5
    }),
  );
}

/// The faces never answer a value outside `[0, 1]` or a NaN, whatever
/// they are handed.
#[test]
fn every_output_is_a_signal() {
  for transfer in HDR {
    let mapping = SdrMapping::for_picture(&transfer, &Primaries::Bt2020).expect("converts");
    for input in [
      [-1.0, 0.5, 2.0],
      [f32::NAN, 0.25, 0.75],
      [f32::INFINITY, f32::NEG_INFINITY, 0.0],
      [1.0, 0.0, 0.0],
      [0.0, 0.0, 1.0],
    ] {
      for channel in mapping.map_signal(input) {
        assert!(
          (0.0..=1.0).contains(&channel),
          "{transfer:?} {input:?}: {channel}"
        );
      }
    }
  }
}

/// The constants the module note states are the ones the mapping uses.
#[test]
fn the_stated_constants() {
  assert_eq!(KNEE_START, STATED_KNEE);
  assert_eq!(REFERENCE_WHITE_NITS, 203.0);
  assert_eq!(HLG_NOMINAL_PEAK_NITS, 1000.0);
  assert_eq!(PQ_PEAK_NITS, 10_000.0);
  assert!(near(hlg_oetf(1.0 / 12.0), 0.5, 1e-6));
}