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
//! RFC #238 staged-resampling-pipeline framework — Phase 0.
//!
//! The RFC models the convert→resample path as a *staged pipeline* and
//! treats a resample as a **splice** into that pipeline at a chosen
//! stage. The colour domain an area downscale averages in then falls out
//! of *where* the splice lands: averaging the native codes before the
//! convert is a different result from converting first and averaging the
//! output. This module is the production foundation those splice stages
//! and the domain choice are expressed through; the design was validated
//! end-to-end against one format by the held PoC (see the
//! `AveragingDomain` history note below).
//!
//! Phase 0 introduces the framework **types** plus an insertion-point
//! [`select_insertion_point`] **selector**, and re-expresses the existing
//! native-vs-row-stage dispatch of `Yuv420p` (4:2:0 planar) through that
//! selector with **zero behaviour change** — the selector reproduces
//! today's tier choice bit-for-bit. Only [`AveragingDomain::Encoded`] and
//! its two splice stages ([`InsertionPoint::NativeCodes`] /
//! [`InsertionPoint::EncodedOutput`]) are exercised; the [`Linear`] and
//! [`Premultiplied`] domains, the full per-plane filter spec, and the
//! support policy are later phases.
//!
//! [`Linear`]: AveragingDomain::Linear
//! [`Premultiplied`]: AveragingDomain::Premultiplied
pub
pub use TransferFunction;
/// The colour domain an RFC #238 area downscale averages in.
///
/// Each variant names the colour space the box-average is taken in,
/// which is equivalently the pipeline stage the resample is spliced at
/// (see the [module docs](self)). Because a YUV→RGB convert is affine,
/// the domains land at materially different RGB, so the choice is
/// observable — that is the reason it is offered.
///
/// Phase 0 only exercises [`Self::Encoded`]; [`Self::Linear`] and
/// [`Self::Premultiplied`] are reserved for later phases.
/// How the [`AveragingDomain::Linear`] tail decodes `YUV→RGB` before it
/// lifts the result to linear light — the *referent* of the linear-light
/// average (RFC #238 #244).
///
/// Both modes share the rest of the linear pipeline (decode → EOTF → area
/// bin → OETF → clamp at output); they differ only in *which* `YUV→RGB`
/// decode fills the buffer the EOTF lifts:
///
/// - [`Self::DisplayReferred`] (the **default**) decodes through the
/// production Q15 `yuv_*_to_rgb_row` kernel, which **clamps and quantizes**
/// the result to 8-bit `[0, 255]` before the EOTF. The average is then
/// *display-referred*: it mixes the converted in-gamut 8-bit RGB in linear
/// light (a gamma-correct resize). Out-of-gamut excursions — super-black /
/// super-white luma, or chroma that drives a channel past the `[0, 1]`
/// cube — are discarded at the convert clamp.
/// - [`Self::SceneReferred`] decodes the **same affine matrix** in unclamped
/// `f32`, preserving those out-of-gamut excursions, lifts *that* to linear
/// light via the EOTF (whose odd-symmetric extrapolation handles
/// out-of-`[0, 1]` inputs), averages in linear light, and clamps **only**
/// at the re-encoded output. This is the physically faithful average for
/// content with super-black / super-white or saturated chroma.
///
/// The two coincide (modulo `f32` rounding) on content that stays in gamut
/// through the decode — they diverge exactly where the 8-bit convert clamp
/// would otherwise have thrown information away.
///
/// The mode is consulted only on the [`AveragingDomain::Linear`] path of the
/// planar 8-bit YUV family; the encoded and direct paths ignore it.
/// A pipeline splice stage — *where* in the convert pipeline an RFC #238
/// resample is inserted.
///
/// Phase 0 enumerates the two stages the [`AveragingDomain::Encoded`]
/// domain splices at; the linear-light and premultiplied stages arrive
/// with their domains in later phases. The [`select_insertion_point`]
/// selector maps a resample's eligibility and plan onto one of these.
pub
/// Inputs to [`select_insertion_point`] — the facts that determine which
/// pipeline stage a resample splices at.
///
/// These mirror exactly the values today's per-format dispatch already
/// branches on, so the selector can reproduce the current choice without
/// any new information: a format's static eligibility for a native tier,
/// the resample plan's [area-vs-filter](crate::resample::SpanKind) kind,
/// and the sink's `with_native` request.
pub
/// Selects the pipeline splice stage for a resample, given its
/// [domain](AveragingDomain) and [context](InsertionContext).
///
/// Phase 0 resolves only [`AveragingDomain::Encoded`]: the resample
/// splices at the [native codes](InsertionPoint::NativeCodes) when the
/// format is native-eligible, the sink enabled the native tier, and the
/// plan is an area downscale; otherwise it splices at the
/// [encoded output](InsertionPoint::EncodedOutput). This reproduces the
/// existing `Yuv420p` native-vs-row-stage decision exactly — see
/// [`crate::sinker::MixedSinker`]'s `Yuv420p` `process` dispatch.
///
/// As of Phase 2 the [`Linear`] domain resolves to the
/// [linear-light](InsertionPoint::LinearLight) stage (decode → linearise →
/// bin → re-encode), independent of the native-tier inputs (the linear
/// average is its own splice, not a native fast-tier variant).
///
/// # Premultiplied is rejected upstream, never resolved here
///
/// [`Premultiplied`] is a **reserved future-phase** domain with *no valid
/// insertion point yet*, so the selector deliberately does **not** map it to
/// any splice — in particular it must not silently resolve to the
/// [encoded output](InsertionPoint::EncodedOutput), which is a different
/// domain (`Premultiplied` is not `Encoded`; for the Phase 5 alpha formats
/// they diverge). Every caller rejects `Premultiplied` with a typed error in
/// its own exhaustive `match *averaging_domain` *before* reaching this
/// selector (see `MixedSinker`'s per-format `process` dispatch, which only
/// ever calls the selector with [`AveragingDomain::Encoded`]). Reaching the
/// `Premultiplied` arm therefore signals a routing bug — a dispatch that
/// failed to reject it — so the arm is an [`unreachable!`] rather than a
/// silent legitimate route. Phase 5 will give `Premultiplied` its real
/// insertion point and replace the guard.
///
/// [`Linear`]: AveragingDomain::Linear
/// [`Premultiplied`]: AveragingDomain::Premultiplied
pub const
/// An RFC #238 resampling strategy: the [averaging domain](AveragingDomain)
/// and (in later phases) the filter specification it resamples with.
///
/// Phase 0 carries only the domain plus a minimal filter placeholder; the
/// real per-plane filter spec and support policy are later phases. The
/// [default](Default) is [`AveragingDomain::Encoded`] with the
/// [area](FilterSpec::Area) filter — the current behaviour.
/// Minimal filter placeholder for [`ResampleStrategy`] — Phase 0 scope.
///
/// Distinguishes only the box-average area path from a (to be specified)
/// windowed-filter kernel; the real per-plane kernel parameters and
/// support policy are later phases.