oxedyne/fe2o3 — fe2o3_graphics/src/hevc/mod.rs

oxedyne/fe2o3/fe2o3_graphics/src/hevc/mod.rs

54.2 KiB, 280 runs

created by r1870400018:20461, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1	//! An HEVC decoder, for the still pictures inside a HEIC file.
2	//!
3	//! HEVC (ITU-T H.265) is the codec a phone's photograph is coded in once it stops being JPEG, and
4	//! there is no way to read one without decoding it. This module is that decoder. It is built for
5	//! intra coding only -- a still picture refers to nothing but itself, so everything about
6	//! motion, reference pictures and prediction between frames is absent by construction rather than
7	//! unimplemented.
8	//!
9	//! # What is here
10	//!
11	//! The whole of it, for the intra case. The bitstream side: splitting a stream into NAL units,
12	//! undoing the emulation-prevention bytes, and reading the sequence and picture parameter sets that
13	//! say how big the picture is and how it is cut up. That is the part every later stage is written
14	//! against, and the part that can be checked before any pixel exists: the size a sequence parameter
15	//! set codes must agree with the size the HEIF container's `ispe` property declares, and those two
16	//! numbers are written into the file by different parts of an encoder.
17	//!
18	//! Then the slice segment header, including the entry points that say where each row of the picture
19	//! begins; the CABAC arithmetic decoder; the context variables each syntax element uses; the coding
20	//! quadtree; residual coding; dequantisation and the inverse transforms; all thirty-five intra
21	//! prediction modes; deblocking and the sample adaptive offset; and the conversion out of 4:2:0
22	//! into red, green and blue. [`picture`] is the entry point and runs the lot.
23	//!
24	//! The arithmetic decoder is the last piece that can be held to a standard before a picture comes
25	//! out, and it is held to two: every context starts in a state the probability tables actually
26	//! have -- all 256 initialisation values against every quantisation parameter a slice may carry --
27	//! and the coding interval is between 256 and 510 after every bin, whatever is fed in. A
28	//! renormalisation one shift short satisfies neither and decodes plausible rubbish rather than
29	//! failing, which is the kind of fault that otherwise survives until a photograph comes out
30	//! wrong.
31	//!
32	//! Everything after it is held to another decoder instead, because by then there is a picture to
33	//! compare: `tests/hevc_tiles.rs` puts every brightness and colour sample beside what FFmpeg makes
34	//! of the same file, with both loop filters running at both ends.
35	//!
36	//! # What the pictures in one real library actually are
37	//!
38	//! Every sequence parameter set in 359 HEIC photographs out of a family library was read, and they
39	//! are uniform: **8-bit 4:2:0, coding tree blocks of 32, the sample adaptive offset on, no PCM, no
40	//! scaling lists, one tile**. The tiles are 512 by 512 in 350 of them, 1024 by 1024 in eight, and
41	//! the one photograph not stored as a grid is 720 by 720.
42	//!
43	//! One of those measurements was a surprise and it changes the shape of the decoder: **every one of
44	//! them is coded in wavefronts** (`entropy_coding_sync_enabled_flag`). The arithmetic decoder is
45	//! therefore reset at the start of every row of coding tree blocks, from the state saved after the
46	//! second block of the row above, and the slice header carries a byte offset for each row. That is
47	//! not an exotic case to be refused; it is the case. All 359 slice headers read, and in each the
48	//! number of rows the header names agrees with the number the sequence parameter set implies --
49	//! sixteen for a 512-pixel tile at 32, twenty-three for the 720-pixel picture -- which is the
50	//! check that caught the first reading, where the flag was mistaken for something rare and every
51	//! photograph in the corpus was refused.
52	//!
53	//! # References
54	//!
55	//! ITU-T H.265 (ISO/IEC 23008-2). The NAL unit header is §7.3.1.2, the sequence parameter set
56	//! §7.3.2.2, the picture parameter set §7.3.2.3, the profile-tier-level structure §7.3.3, and the
57	//! short-term reference picture sets §7.3.7. The `hvcC` record the parameter sets arrive in is
58	//! ISO/IEC 14496-15 §8.3.3. Every constant below names the clause it comes from.
59	//!
60	//! [Written with AI entirely](https://need2know.ai/entirely-ai/code)\
61	//! Anthropic Claude
62
63	pub mod cabac;
64	pub mod colour;
65	pub mod decode;
66	pub mod filter;
67	pub mod intra;
68	pub mod scan;
69	pub mod transform;
70
71	pub use cabac::{
72	Cabac,
73	Contexts,
74	Ctx,
75	Rows,
76	Set,
77	CONTEXTS,
78	};
79
80	use oxedyne_fe2o3_core::prelude::*;
81
82	// The largest picture this decoder will describe, in luma samples each way. Sixteen thousand is
83	// past every camera and well inside what the level limits allow; it is a ceiling against a
84	// parameter set that is a mistake, not a limit on real photographs.
85	pub const MAX_SIDE: u32 = 16_384;
86
87	/// NAL unit types this decoder cares about (H.265 Table 7-1).
88	pub mod nal {
89	pub const IDR_W_RADL: u8 = 19; // an IDR picture with no leading pictures, which a still is
90	pub const IDR_N_LP: u8 = 20; // the other IDR form
91	pub const VPS: u8 = 32;
92	pub const SPS: u8 = 33;
93	pub const PPS: u8 = 34;
94	}
95
96	/// One NAL unit: what it is, and its payload with the emulation prevention undone.
97	#[derive(Clone, Debug)]
98	pub struct Unit {
99	pub kind: u8, // the type, from the two-byte NAL unit header
100	pub layer: u8, // temporal sub-layer, plus one as the header codes it
101	pub body: Vec<u8>, // after the header, every emulation prevention byte removed
102	// The payload as it arrived, escaping and all, because the entry point offsets in a slice
103	// header are counted in escaped bytes: "emulation prevention bytes that appear in the slice
104	// segment data portion of the coded slice segment NAL unit are counted as part of the slice
105	// segment data for purposes of subset identification" (§7.4.7.1). Splitting the unescaped
106	// payload at those offsets puts every row of blocks after the first escaped byte in the
107	// wrong place.
108	pub raw: Vec<u8>,
109	}
110
111	/// What a sequence parameter set says about the pictures that follow it.
112	///
113	/// Only the fields a still picture's decoder acts on are kept. The rest are read past, because a
114	/// parameter set is a run of variable-length codes and there is no skipping to a field without
115	/// decoding everything before it.
116	#[derive(Clone, Debug, PartialEq, Eq)]
117	pub struct Sps {
118	pub id: u8, // which set this is, as a picture parameter set names it
119	pub chroma: u8, // 0 monochrome, 1 for 4:2:0, 2 for 4:2:2, 3 for 4:4:4
120	pub coded_w: u32, // coded width in luma samples, before the conformance window
121	pub coded_h: u32, // and coded height
122	pub width: u32, // the width the picture is meant to be shown at
123	pub height: u32, // and the height as shown
124	pub luma_bits: u8, // bits a luma sample
125	pub chroma_bits: u8, // bits a chroma sample
126	pub ctb_size: u32, // a coding tree block, in luma samples: 16, 32 or 64
127	pub min_cb: u32, // the smallest coding block, in luma samples
128	pub min_tb: u32, // the smallest transform block, in luma samples
129	pub max_tb: u32, // and the largest
130	pub max_depth_intra: u8, // how deep the transform tree may go in an intra unit
131	pub sao: bool, // is the sample adaptive offset filter on?
132	pub pcm: bool, // may coding units carry raw samples?
133	pub strong_smoothing: bool, // the stronger intra smoothing filter, at 32 by 32
134	// On does not mean bespoke. Every photograph in the corpus turns the scaling lists on and
135	// carries none of its own, which means the default lists apply -- and those are not flat, so
136	// a decoder that reads this as "no scaling" quantises every block wrongly and produces a
137	// picture that is recognisable and wrong.
138	pub scaling_lists: bool, // are the scaling lists in use at all?
139	pub weights: Option<Scaling>, // this sequence's own lists, or the default ones
140	// Both windows may sit off the top left corner: the conformance window usually does not and
141	// the default display window of a stabilised film always does, since it is centred in a
142	// picture coded larger than it shows. Cropping from the corner instead moves the whole
143	// picture by that offset.
144	pub show_x0: u32, // where the shown picture begins, in luma samples
145	pub show_y0: u32, // the same downwards
146	// Out of the video usability information, where a stream says how it is to be shown. A
147	// conversion into red, green and blue that guesses this wrong makes a photograph with no
148	// real black in it, or one whose blacks are crushed.
149	pub full_range: bool, // full range rather than the studio one
150	pub matrix: u8, // ISO/IEC 23091-2: 1 high definition, 5 and 6 standard
151	// A slice header carries the picture order count for every picture except an IDR, which has
152	// none to state. A film's first frame is very often a clean random access picture rather
153	// than an IDR, and a header read as though it were an IDR's is read out of step from this
154	// field on.
155	pub poc_bits: u8, // bits the count's lower part is coded in
156	// A still picture references nothing and needs none of these sets; what they are for is the
157	// slice header, which may name one or write a new one predicted from them, and either way
158	// the bits cannot be stepped over without knowing how large the set referred to is.
159	pub st_sets: Vec<(u32, u32)>, // pictures each short-term set names, negative and positive
160	pub long_term: bool, // may a slice header name long-term reference pictures?
161	pub temporal_mvp: bool, // does a slice header carry the temporal predictor flag?
162	}
163
164	/// What a picture parameter set says about the slices that reference it.
165	#[derive(Clone, Debug, PartialEq, Eq)]
166	pub struct Pps {
167	pub id: u8, // which set this is, as a slice header names it
168	pub sps_id: u8, // which sequence parameter set it belongs to
169	pub init_qp: i32, // already offset by the 26 the syntax subtracts
170	pub cu_qp_delta: bool, // may a coding unit carry its own quantisation delta?
171	pub qp_delta_depth: u8, // how far down the quadtree a delta may be sent
172	pub cb_qp_offset: i32, // the chroma quantisation offsets
173	pub cr_qp_offset: i32, // and for the other chroma channel
174	pub transform_skip: bool, // may a block skip the transform entirely?
175	pub sign_hiding: bool, // the last coefficient's sign inferred rather than coded
176	pub transquant_bypass: bool, // an intra residual coded across the transform tree
177	pub tiles: bool, // is the picture cut into tiles?
178	pub wavefront: bool, // entropy coding synchronised at each row of blocks
179	pub deblocking: bool, // does the deblocking filter run?
180	pub slice_chroma_qp: bool, // may a slice header carry a further chroma offset?
181	// The slice header cannot be read without the count of reserved flags: they are bits to be
182	// stepped over, and stepping over the wrong number puts every field after them one place
183	// out.
184	pub extra_header_bits: u8, // reserved flags a slice header carries first
185	pub output_flag: bool, // does a slice header carry a picture output flag?
186	pub deblocking_override: bool, // may a slice header override the settings?
187	pub filter_across_slices: bool, // and therefore whether a slice carries its own flag
188	// The slice header cannot be read without this either: a segment that is not the first of
189	// its picture carries a flag saying whether it continues the header before it, and only
190	// where this says one may.
191	pub dependent_slices: bool, // may a segment continue the header before it?
192	}
193
194	/// Splits a byte-stream of length-prefixed NAL units, as `hvcC` and `mdat` carry them.
195	///
196	/// `length_size` comes from the configuration record and is one, two or four. A unit that runs past
197	/// the end of the buffer is a truncated file and is refused rather than decoded as far as it goes:
198	/// half a coded picture is not half a picture, it is noise.
199	pub fn split_lengthed(bytes: &[u8], length_size: usize) -> Outcome<Vec<Unit>> {
200	if !matches!(length_size, 1 \| 2 \| 4) {
201	return Err(err!(
202	"A NAL unit length is coded in {} bytes, and only one, two and four are legal.",
203	length_size;
204	Invalid, Input, Decode));
205	}
206	let mut out = Vec::new();
207	let mut at = 0usize;
208	while at + length_size <= bytes.len() {
209	let mut len = 0usize;
210	for i in 0..length_size {
211	len = (len << 8) \| bytes[at + i] as usize;
212	}
213	at += length_size;
214	if len == 0 {
215	return Err(err!("A NAL unit of no length."; Invalid, Input, Decode));
216	}
217	let end = match at.checked_add(len) {
218	Some(end) if end <= bytes.len() => end,
219	_ => return Err(err!(
220	"A NAL unit says it is {} bytes and {} remain.", len, bytes.len() - at;
221	Invalid, Input, Decode)),
222	};
223	out.push(res!(unit(&bytes[at..end])));
224	at = end;
225	}
226	if at != bytes.len() {
227	return Err(err!(
228	"{} bytes are left over after the last NAL unit.", bytes.len() - at;
229	Invalid, Input, Decode));
230	}
231	Ok(out)
232	}
233
234	/// Splits an Annex B stream, where units are separated by start codes rather than lengths.
235	///
236	/// This is the form a parameter set arrives in inside `hvcC`, and the form a raw `.265` file takes.
237	pub fn split_annex_b(bytes: &[u8]) -> Outcome<Vec<Unit>> {
238	let mut starts: Vec<usize> = Vec::new();
239	let mut i = 0usize;
240	while i + 3 <= bytes.len() {
241	if bytes[i] == 0 && bytes[i + 1] == 0 && bytes[i + 2] == 1 {
242	starts.push(i + 3);
243	i += 3;
244	} else {
245	i += 1;
246	}
247	}
248	let mut out = Vec::with_capacity(starts.len());
249	for (n, from) in starts.iter().enumerate() {
250	let to = match starts.get(n + 1) {
251	// Back off the start code of the next unit, and the trailing zero a four-byte start
252	// code puts in front of it.
253	Some(next) => {
254	let mut end = next - 3;
255	if end > *from && bytes[end - 1] == 0 {
256	end -= 1;
257	}
258	end
259	},
260	None => bytes.len(),
261	};
262	if to > *from {
263	out.push(res!(unit(&bytes[*from..to])));
264	}
265	}
266	Ok(out)
267	}
268
269	/// Reads one NAL unit: its two-byte header, and its payload unescaped.
270	pub fn unit(raw: &[u8]) -> Outcome<Unit> {
271	if raw.len() < 3 {
272	return Err(err!(
273	"A NAL unit is {} bytes, and its header alone is two.", raw.len();
274	Invalid, Input, Decode));
275	}
276	// forbidden_zero_bit, then six bits of type, six of layer, three of temporal id (§7.3.1.2).
277	if raw[0] & 0x80 != 0 {
278	return Err(err!(
279	"A NAL unit's forbidden bit is set, so this is not an HEVC stream.";
280	Invalid, Input, Decode));
281	}
282	Ok(Unit {
283	kind: (raw[0] >> 1) & 0x3f,
284	layer: raw[1] & 0x07,
285	body: rbsp(&raw[2..]),
286	raw: raw[2..].to_vec(),
287	})
288	}
289
290	/// Removes the emulation prevention bytes from a payload (§7.4.2).
291	///
292	/// A `0x03` after two zero bytes is there only to stop the payload looking like a start code, and
293	/// is not part of the syntax.
294	pub fn rbsp(nal: &[u8]) -> Vec<u8> {
295	let mut out = Vec::with_capacity(nal.len());
296	let mut zeros = 0usize;
297	for &b in nal {
298	if zeros >= 2 && b == 0x03 {
299	zeros = 0;
300	continue;
301	}
302	out.push(b);
303	zeros = if b == 0 { zeros + 1 } else { 0 };
304	}
305	out
306	}
307
308	/// Where an unescaped position sits in the payload it was unescaped from.
309	///
310	/// Emulation prevention only ever removes bytes, so the escaped position is the unescaped one
311	/// plus however many were removed before it. This walks the same state machine [`rbsp`] does rather
312	/// than inverting it, because the two staying in step is the whole point.
313	pub fn escaped_at(nal: &[u8], unescaped: usize) -> usize {
314	let mut out = 0usize;
315	let mut zeros = 0usize;
316	for (i, b) in nal.iter().enumerate() {
317	if out == unescaped {
318	return i;
319	}
320	if *b == 3 && zeros >= 2 {
321	zeros = 0;
322	continue;
323	}
324	out += 1;
325	zeros = if *b == 0 { zeros + 1 } else { 0 };
326	}
327	nal.len()
328	}
329
330	/// The parameter sets carried in an `hvcC` decoder configuration record (ISO/IEC 14496-15 §8.3.3).
331	///
332	/// The record's own fields describe the stream's profile and the width of the length prefixes; the
333	/// arrays at the end carry the parameter sets themselves, as Annex B payloads without start codes.
334	#[derive(Clone, Debug)]
335	pub struct Config {
336	pub length_size: usize, // bytes prefixing each NAL unit in the picture's own data
337	pub sets: Vec<Unit>, // every parameter set, in the order the record carries them
338	}
339
340	/// Reads an `hvcC` record.
341	pub fn config(bytes: &[u8]) -> Outcome<Config> {
342	// 22 bytes of fixed fields, then a count of arrays.
343	if bytes.len() < 23 {
344	return Err(err!(
345	"A decoder configuration record is {} bytes, and its fixed fields alone are 22.",
346	bytes.len();
347	Invalid, Input, Decode));
348	}
349	if bytes[0] != 1 {
350	return Err(err!(
351	"A decoder configuration record of version {}, and this reads version 1.", bytes[0];
352	Invalid, Input, Unknown));
353	}
354	let length_size = (bytes[21] & 0x03) as usize + 1;
355	let arrays = bytes[22] as usize;
356	let mut sets = Vec::new();
357	let mut at = 23usize;
358	for _ in 0..arrays {
359	if at + 3 > bytes.len() {
360	return Err(err!(
361	"A configuration record ends inside its array of parameter sets.";
362	Invalid, Input, Decode));
363	}
364	let count = u16::from_be_bytes([bytes[at + 1], bytes[at + 2]]) as usize;
365	at += 3;
366	for _ in 0..count {
367	if at + 2 > bytes.len() {
368	return Err(err!(
369	"A configuration record ends inside a parameter set's length.";
370	Invalid, Input, Decode));
371	}
372	let len = u16::from_be_bytes([bytes[at], bytes[at + 1]]) as usize;
373	at += 2;
374	let end = match at.checked_add(len) {
375	Some(end) if end <= bytes.len() => end,
376	_ => return Err(err!(
377	"A parameter set says it is {} bytes and {} remain.",
378	len, bytes.len() - at;
379	Invalid, Input, Decode)),
380	};
381	sets.push(res!(unit(&bytes[at..end])));
382	at = end;
383	}
384	}
385	Ok(Config { length_size, sets })
386	}
387
388	/// A reader of the bits of an RBSP, most significant first.
389	pub struct Bits<'a> {
390	buf: &'a [u8],
391	pos: usize, // the next bit, counted from the first bit of the first byte
392	}
393
394	impl<'a> Bits<'a> {
395
396	pub fn new(buf: &'a [u8]) -> Self {
397	Self { buf, pos: 0 }
398	}
399
400	pub fn left(&self) -> usize {
401	(self.buf.len() * 8).saturating_sub(self.pos)
402	}
403
404	/// The next `n` bits as an unsigned integer, most significant first.
405	pub fn u(&mut self, n: usize) -> Outcome<u32> {
406	if n > 32 {
407	return Err(err!("A field of {} bits was asked for, and 32 is the widest.", n; Bug));
408	}
409	let mut v = 0u32;
410	for _ in 0..n {
411	let byte = self.pos >> 3;
412	if byte >= self.buf.len() {
413	return Err(err!(
414	"The parameter set ends after {} bits, inside a field.", self.buf.len() * 8;
415	Invalid, Input, Decode));
416	}
417	let bit = (self.buf[byte] >> (7 - (self.pos & 7))) & 1;
418	v = (v << 1) \| bit as u32;
419	self.pos += 1;
420	}
421	Ok(v)
422	}
423
424	pub fn flag(&mut self) -> Outcome<bool> {
425	Ok(res!(self.u(1)) == 1)
426	}
427
428	pub fn consumed(&self) -> Outcome<usize> {
429	Ok(self.pos)
430	}
431
432	pub fn skip(&mut self, n: usize) -> Outcome<()> {
433	for _ in 0..n / 32 {
434	let _ = res!(self.u(32));
435	}
436	let _ = res!(self.u(n % 32));
437	Ok(())
438	}
439
440	/// An unsigned Exp-Golomb code, §9.2.
441	pub fn ue(&mut self) -> Outcome<u32> {
442	let mut zeros = 0usize;
443	while res!(self.u(1)) == 0 {
444	zeros += 1;
445	if zeros > 31 {
446	return Err(err!(
447	"An Exp-Golomb code is prefixed by more than 31 zeroes, which no legal value \
448	is.";
449	Invalid, Input, Decode));
450	}
451	}
452	if zeros == 0 {
453	return Ok(0);
454	}
455	let rest = res!(self.u(zeros)) as u64;
456	let v = (1u64 << zeros) - 1 + rest;
457	if v > u32::MAX as u64 {
458	return Err(err!(
459	"An Exp-Golomb code decodes to {}, beyond what any field holds.", v;
460	Invalid, Input, Decode));
461	}
462	Ok(v as u32)
463	}
464
465	/// A signed Exp-Golomb code, §9.2.2.
466	pub fn se(&mut self) -> Outcome<i32> {
467	let k = res!(self.ue());
468	let m = ((k as i64 + 1) / 2) as i32;
469	Ok(if k % 2 == 1 { m } else { -m })
470	}
471	}
472
473	/// Steps over a profile, tier and level structure (§7.3.3).
474	///
475	/// Nothing in it changes how a picture is decoded -- it says what a decoder must be capable of, and
476	/// a decoder that is about to try is going to find out. It has to be walked rather than skipped by
477	/// a byte count only in the sub-layer case, where the number of flags depends on the flags.
478	fn profile_tier_level(b: &mut Bits, profile_present: bool, max_sub_layers: usize) -> Outcome<()> {
479	if profile_present {
480	// 2 + 1 + 5 bits, 32 of compatibility flags, 48 of constraint flags.
481	res!(b.skip(8 + 32 + 48));
482	}
483	res!(b.skip(8));
484	if max_sub_layers == 0 {
485	return Ok(());
486	}
487	let mut profile = [false; 8];
488	let mut level = [false; 8];
489	for i in 0..max_sub_layers.saturating_sub(1).min(8) {
490	profile[i] = res!(b.flag());
491	level[i] = res!(b.flag());
492	}
493	if max_sub_layers > 1 {
494	// The flags are padded out to eight pairs.
495	for _ in max_sub_layers.saturating_sub(1)..8 {
496	res!(b.skip(2));
497	}
498	}
499	for i in 0..max_sub_layers.saturating_sub(1).min(8) {
500	if profile[i] {
501	res!(b.skip(8 + 32 + 48));
502	}
503	if level[i] {
504	res!(b.skip(8));
505	}
506	}
507	Ok(())
508	}
509
510	/// The weights a picture quantises each block against (§7.3.4, §7.4.5).
511	///
512	/// Six lists a size -- one each for the three colour components, predicted from within the picture
513	/// and from another, though a still photograph only ever uses the first three. The numbers climb
514	/// away from the corner because the eye notices an error in a block's coarse detail more than in
515	/// its fine, so the fine detail is quantised harder.
516	///
517	/// A sequence that turns the lists on and carries none of its own takes the default ones, which are
518	/// not flat; a decoder that reads "on" as "no scaling" quantises every block wrongly and produces a
519	/// picture that is recognisable and wrong.
520	#[derive(Clone, Debug, PartialEq, Eq)]
521	pub struct Scaling {
522	pub list: [[[u8; 64]; 6]; 4], // ScalingList[sizeId][matrixId][i], in diagonal scan order
523	pub dc: [[u8; 6]; 2], // the corner at the two largest sizes, coded on its own
524	}
525
526	impl Scaling {
527
528	/// The default lists, which is what a sequence carrying none of its own means.
529	pub fn default_lists() -> Self {
530	let mut out = Self { list: [[[16u8; 64]; 6]; 4], dc: [[16u8; 6]; 2] };
531	for size in 1..4 {
532	for id in 0..6 {
533	let from = crate::hevc::transform::DEFAULT_LIST[(id >= 3) as usize];
534	out.list[size][id] = from;
535	}
536	}
537	out
538	}
539
540	/// One weight, by size, matrix and position within the block (equations 7-44 to 7-49).
541	///
542	/// The sixteen and thirty-two sample matrices are the eight-sample one with each of its values
543	/// covering two or four samples each way, and a corner of their own.
544	pub fn factor(&self, log2: u32, matrix: usize, x: usize, y: usize, raster: &[u8; 64]) -> i32 {
545	match log2 {
546	2 => raster[(y & 3) * 4 + (x & 3)] as i32,
547	3 => raster[y * 8 + x] as i32,
548	_ => {
549	if x == 0 && y == 0 {
550	return self.dc[(log2 - 4) as usize][matrix] as i32;
551	}
552	let shrink = log2 - 3;
553	raster[(y >> shrink) * 8 + (x >> shrink)] as i32
554	},
555	}
556	}
557
558	/// One list laid out in raster order rather than in the diagonal scan's.
559	pub fn raster(&self, log2: u32, matrix: usize) -> [u8; 64] {
560	let size_id = (log2 - 2).min(3) as usize;
561	let side = if size_id == 0 { 4 } else { 8 };
562	let list = &self.list[size_id][matrix];
563	let mut out = [16u8; 64];
564	for (i, (x, y)) in crate::hevc::scan::positions(side, crate::hevc::scan::Order::Diagonal)
565	.iter()
566	.enumerate()
567	{
568	out[y as usize side + *x as usize] = list[i];
569	}
570	out
571	}
572	}
573
574	/// Reads a scaling list (§7.3.4).
575	///
576	/// A list is either coded outright as a chain of differences, or taken from an earlier list in the
577	/// same set, or -- where it names itself as its own source -- from the default.
578	fn scaling_list(b: &mut Bits) -> Outcome<Scaling> {
579	let mut out = Scaling::default_lists();
580	let defaults = Scaling::default_lists();
581	for size in 0..4usize {
582	let mut id = 0usize;
583	while id < 6 {
584	let coefficients = 64usize.min(1 << (4 + (size << 1)));
585	if !res!(b.flag()) {
586	// Taken from another list rather than coded. A delta of nought means the default,
587	// which is the one case where "predicted from" does not mean "copied from".
588	let delta = res!(b.ue()) as usize;
589	if delta == 0 {
590	out.list[size][id] = defaults.list[size][id];
591	if size > 1 {
592	out.dc[size - 2][id] = 16;
593	}
594	} else {
595	let from = id.saturating_sub(delta * if size == 3 { 3 } else { 1 });
596	out.list[size][id] = out.list[size][from];
597	if size > 1 {
598	out.dc[size - 2][id] = out.dc[size - 2][from];
599	}
600	}
601	} else {
602	let mut next = 8i32;
603	if size > 1 {
604	let dc = res!(b.se()) + 8;
605	if !(1..=255).contains(&dc) {
606	return Err(err!(
607	"A scaling list's corner value is {}, outside 1 to 255.", dc;
608	Invalid, Input, Decode));
609	}
610	out.dc[size - 2][id] = dc as u8;
611	next = dc;
612	}
613	for i in 0..coefficients {
614	let delta = res!(b.se());
615	next = (next + delta + 256).rem_euclid(256);
616	out.list[size][id][i] = next as u8;
617	}
618	}
619	// The 32 by 32 lists come in twos rather than sixes.
620	id += if size == 3 { 3 } else { 1 };
621	}
622	}
623	// A 32 by 32 chroma list does not exist below 4:4:4, but the arrays are square; filling the
624	// gaps from luma keeps a lookup by matrix identifier from finding sixteens.
625	for id in [1usize, 2, 4, 5] {
626	let from = if id < 3 { 0 } else { 3 };
627	out.list[3][id] = out.list[3][from];
628	out.dc[1][id] = out.dc[1][from];
629	}
630	Ok(out)
631	}
632
633	/// Steps over one short-term reference picture set (§7.3.7).
634	///
635	/// A still picture references nothing, so no picture is kept -- but how many the set names is,
636	/// because the next set may be coded as a difference from this one and a slice header may be coded
637	/// as a difference from any of them, and neither can be stepped over without the count.
638	fn short_term_ref_pic_set(b: &mut Bits, idx: usize, count: usize, previous: &mut Vec<(u32, u32)>)
639	-> Outcome<()>
640	{
641	let mut predicted = false;
642	if idx != 0 {
643	predicted = res!(b.flag());
644	}
645	if predicted {
646	// Which earlier set this one is a difference from. Only a set written in a slice header
647	// says so; a set in the sequence parameter set is always a difference from the one before
648	// it (§7.4.8).
649	let mut back = 1usize;
650	if idx == count {
651	back = res!(b.ue()) as usize + 1;
652	}
653	let _delta_rps_sign = res!(b.flag());
654	let _abs_delta_rps = res!(b.ue());
655	let (negative, positive) = match idx.checked_sub(back).and_then(\|at\| previous.get(at)) {
656	Some(pair) => *pair,
657	None => return Err(err!(
658	"A reference picture set is coded as a difference from set {} of {}, which is not \
659	there.", idx as i64 - back as i64, previous.len();
660	Invalid, Input, Decode)),
661	};
662	// One flag pair for each picture of the set referred to, and one for the picture that set
663	// is itself relative to. The ones kept are what this set names, which is what the next
664	// difference will be measured against.
665	let mut kept = 0u32;
666	for _ in 0..(negative + positive + 1) {
667	let used = res!(b.flag());
668	let mut keep = used;
669	if !used {
670	keep = res!(b.flag());
671	}
672	if keep {
673	kept += 1;
674	}
675	}
676	previous.push((kept, 0));
677	return Ok(());
678	}
679	let negative = res!(b.ue());
680	let positive = res!(b.ue());
681	if negative > 64 \|\| positive > 64 {
682	return Err(err!(
683	"A reference picture set names {} and {} pictures, and 64 is the most either may be.",
684	negative, positive;
685	Invalid, Input, Decode));
686	}
687	for _ in 0..negative {
688	let _delta = res!(b.ue());
689	let _used = res!(b.flag());
690	}
691	for _ in 0..positive {
692	let _delta = res!(b.ue());
693	let _used = res!(b.flag());
694	}
695	previous.push((negative, positive));
696	Ok(())
697	}
698
699	/// Reads a sequence parameter set (§7.3.2.2).
700	pub fn sps(body: &[u8]) -> Outcome<Sps> {
701	let mut b = Bits::new(body);
702	let _vps_id = res!(b.u(4));
703	let max_sub_layers = res!(b.u(3)) as usize + 1;
704	let _temporal_id_nesting = res!(b.flag());
705	res!(profile_tier_level(&mut b, true, max_sub_layers));
706	let id = res!(b.ue());
707	if id > 15 {
708	return Err(err!(
709	"A sequence parameter set numbered {}, and 15 is the highest.", id;
710	Invalid, Input, Decode));
711	}
712	let chroma = res!(b.ue());
713	if chroma > 3 {
714	return Err(err!(
715	"A chroma format of {}, and 3 is the highest.", chroma; Invalid, Input, Decode));
716	}
717	if chroma == 3 {
718	let _separate_colour_plane = res!(b.flag());
719	}
720	let coded_w = res!(b.ue());
721	let coded_h = res!(b.ue());
722	if coded_w == 0 \|\| coded_h == 0 \|\| coded_w > MAX_SIDE \|\| coded_h > MAX_SIDE {
723	return Err(err!(
724	"A sequence parameter set codes a picture of {} by {}.", coded_w, coded_h;
725	Invalid, Input, Decode));
726	}
727	// The conformance window trims the coded picture down to what is shown, in units of the chroma
728	// sampling: a 1920 by 1080 picture is coded as 1920 by 1088 and trimmed by four rows.
729	let (mut left, mut right, mut top, mut bottom) = (0u32, 0u32, 0u32, 0u32);
730	if res!(b.flag()) {
731	left = res!(b.ue());
732	right = res!(b.ue());
733	top = res!(b.ue());
734	bottom = res!(b.ue());
735	}
736	let (sub_w, sub_h) = match chroma {
737	1 => (2u32, 2u32),
738	2 => (2, 1),
739	_ => (1, 1),
740	};
741	let trim_x = left.saturating_add(right).saturating_mul(sub_w);
742	let trim_y = top.saturating_add(bottom).saturating_mul(sub_h);
743	if trim_x >= coded_w \|\| trim_y >= coded_h {
744	return Err(err!(
745	"A conformance window trims {} by {} from a picture of {} by {}.",
746	trim_x, trim_y, coded_w, coded_h;
747	Invalid, Input, Decode));
748	}
749	let luma_bits = res!(b.ue()) as u8 + 8;
750	let chroma_bits = res!(b.ue()) as u8 + 8;
751	if luma_bits > 16 \|\| chroma_bits > 16 {
752	return Err(err!(
753	"A sample of {} bits, and 16 is the most this decoder reads.", luma_bits.max(chroma_bits);
754	Invalid, Input, Unknown));
755	}
756	let poc_bits = res!(b.ue()) as u8 + 4;
757	if poc_bits > 16 {
758	return Err(err!(
759	"A picture order count of {} bits, and 16 is the most.", poc_bits;
760	Invalid, Input, Decode));
761	}
762	// The ordering information is given either once for the highest sub-layer or once for each.
763	let for_each = res!(b.flag());
764	let first = if for_each { 0 } else { max_sub_layers - 1 };
765	for _ in first..max_sub_layers {
766	let _max_dec_pic_buffering = res!(b.ue());
767	let _num_reorder = res!(b.ue());
768	let _max_latency = res!(b.ue());
769	}
770	let min_cb = 1u32 << (res!(b.ue()) + 3);
771	let ctb_size = min_cb << res!(b.ue());
772	let min_tb = 1u32 << (res!(b.ue()) + 2);
773	let max_tb = min_tb << res!(b.ue());
774	if !matches!(ctb_size, 16 \| 32 \| 64) \|\| min_cb < 8 \|\| max_tb > 32 \|\| min_tb < 4 {
775	return Err(err!(
776	"A block geometry of ctb {}, min cb {}, tb {} to {}, which no legal stream has.",
777	ctb_size, min_cb, min_tb, max_tb;
778	Invalid, Input, Decode));
779	}
780	let _max_depth_inter = res!(b.ue());
781	let max_depth_intra = res!(b.ue()) as u8;
782	let scaling_lists = res!(b.flag());
783	let mut weights = None;
784	if scaling_lists {
785	weights = Some(if res!(b.flag()) {
786	res!(scaling_list(&mut b))
787	} else {
788	Scaling::default_lists()
789	});
790	}
791	let _amp = res!(b.flag());
792	let sao = res!(b.flag());
793	let pcm = res!(b.flag());
794	if pcm {
795	let _pcm_luma_bits = res!(b.u(4));
796	let _pcm_chroma_bits = res!(b.u(4));
797	let _log2_min_pcm_cb = res!(b.ue());
798	let _log2_diff_pcm_cb = res!(b.ue());
799	let _pcm_loop_filter_disabled = res!(b.flag());
800	}
801	let short_term_sets = res!(b.ue()) as usize;
802	if short_term_sets > 64 {
803	return Err(err!(
804	"A sequence parameter set carries {} reference picture sets, and 64 is the most.",
805	short_term_sets;
806	Invalid, Input, Decode));
807	}
808	let mut previous: Vec<(u32, u32)> = Vec::with_capacity(short_term_sets);
809	for i in 0..short_term_sets {
810	res!(short_term_ref_pic_set(&mut b, i, short_term_sets, &mut previous));
811	}
812	let long_term_present = res!(b.flag());
813	if long_term_present {
814	let long_term = res!(b.ue()) as usize;
815	if long_term > 32 {
816	return Err(err!(
817	"A sequence parameter set carries {} long-term reference pictures.", long_term;
818	Invalid, Input, Decode));
819	}
820	for _ in 0..long_term {
821	let bits = (res!(b.ue()) % 32) as usize;
822	let _ = bits;
823	// The poc is coded in log2_max_poc bits, which was read past above; a still picture
824	// has none of these, and a stream that does is not one this decoder will be handed.
825	return Err(err!(
826	"A sequence parameter set carries long-term reference pictures, which a still \
827	picture does not have.";
828	Invalid, Input, Unknown));
829	}
830	}
831	let temporal_mvp = res!(b.flag());
832	let strong_smoothing = res!(b.flag());
833	// The video usability information, which is where a stream says how it is to be shown: which
834	// weights its colour was coded against, whether its samples run the full range, and -- the one
835	// that changes the picture's size -- the default display window.
836	//
837	// A phone's stabilised film carries one. Stabilisation works by coding a picture larger
838	// than it shows and moving the window about inside it, and the window is written here. A
839	// decoder that ignores it hands back the wobbly margin as though it were part of the film,
840	// about nine per cent wider and taller than every player shows.
841	let (mut full_range, mut matrix) = (false, 2u8);
842	let (mut show_x, mut show_y) = (0u32, 0u32);
843	let (mut show_x0, mut show_y0) = (0u32, 0u32);
844	if res!(b.flag()) {
845	if res!(b.flag()) {
846	// The sample aspect ratio, read past: a picture is drawn at the size it is coded and
847	// stretching it is the caller's business.
848	let idc = res!(b.u(8));
849	if idc == 255 {
850	let _sar_w = res!(b.u(16));
851	let _sar_h = res!(b.u(16));
852	}
853	}
854	if res!(b.flag()) {
855	let _overscan_appropriate = res!(b.flag());
856	}
857	if res!(b.flag()) {
858	let _video_format = res!(b.u(3));
859	full_range = res!(b.flag());
860	if res!(b.flag()) {
861	let _primaries = res!(b.u(8));
862	let _transfer = res!(b.u(8));
863	matrix = res!(b.u(8)) as u8;
864	}
865	}
866	if res!(b.flag()) {
867	let _chroma_loc_top = res!(b.ue());
868	let _chroma_loc_bottom = res!(b.ue());
869	}
870	let _neutral_chroma = res!(b.flag());
871	let _field_seq = res!(b.flag());
872	let _frame_field_info = res!(b.flag());
873	if res!(b.flag()) {
874	let dw_left = res!(b.ue());
875	let dw_right = res!(b.ue());
876	let dw_top = res!(b.ue());
877	let dw_bottom = res!(b.ue());
878	show_x = dw_left.saturating_add(dw_right).saturating_mul(sub_w);
879	show_y = dw_top.saturating_add(dw_bottom).saturating_mul(sub_h);
880	show_x0 = dw_left.saturating_mul(sub_w);
881	show_y0 = dw_top.saturating_mul(sub_h);
882	}
883	// Nothing after the window is read: the timing information, the bitstream restrictions and
884	// the hypothetical reference decoder say nothing about the samples.
885	}
886	let width = coded_w - trim_x;
887	let height = coded_h - trim_y;
888	if show_x >= width \|\| show_y >= height {
889	return Err(err!(
890	"A default display window trims {} by {} from a picture of {} by {}.",
891	show_x, show_y, width, height;
892	Invalid, Input, Range));
893	}
894	Ok(Sps {
895	id: id as u8,
896	chroma: chroma as u8,
897	coded_w,
898	coded_h,
899	width: width - show_x,
900	height: height - show_y,
901	show_x0: left.saturating_mul(sub_w) + show_x0,
902	show_y0: top.saturating_mul(sub_h) + show_y0,
903	luma_bits,
904	chroma_bits,
905	ctb_size,
906	min_cb,
907	min_tb,
908	max_tb,
909	max_depth_intra,
910	sao,
911	pcm,
912	strong_smoothing,
913	scaling_lists,
914	weights,
915	poc_bits,
916	full_range,
917	matrix,
918	st_sets: previous,
919	long_term: long_term_present,
920	temporal_mvp,
921	})
922	}
923
924	/// Reads a picture parameter set (§7.3.2.3).
925	pub fn pps(body: &[u8]) -> Outcome<Pps> {
926	let mut b = Bits::new(body);
927	let id = res!(b.ue());
928	let sps_id = res!(b.ue());
929	if id > 63 \|\| sps_id > 15 {
930	return Err(err!(
931	"A picture parameter set numbered {} against sequence set {}.", id, sps_id;
932	Invalid, Input, Decode));
933	}
934	let dependent_slices = res!(b.flag());
935	let output_flag = res!(b.flag());
936	let extra_header_bits = res!(b.u(3)) as u8;
937	let sign_hiding = res!(b.flag());
938	let _cabac_init_present = res!(b.flag());
939	let _num_ref_idx_l0 = res!(b.ue());
940	let _num_ref_idx_l1 = res!(b.ue());
941	let init_qp = res!(b.se()) + 26;
942	let _constrained_intra_pred = res!(b.flag());
943	let transform_skip = res!(b.flag());
944	let cu_qp_delta = res!(b.flag());
945	let qp_delta_depth = if cu_qp_delta { res!(b.ue()) as u8 } else { 0 };
946	let cb_qp_offset = res!(b.se());
947	let cr_qp_offset = res!(b.se());
948	let slice_chroma_qp = res!(b.flag());
949	let _weighted_pred = res!(b.flag());
950	let _weighted_bipred = res!(b.flag());
951	let transquant_bypass = res!(b.flag());
952	let tiles = res!(b.flag());
953	let wavefront = res!(b.flag());
954	if tiles {
955	// The geometry of the tiles is read past rather than kept: what this decoder needs from a
956	// tiled picture is to know it is one, and to say so.
957	let columns = res!(b.ue()) as usize;
958	let rows = res!(b.ue()) as usize;
959	if columns > 1024 \|\| rows > 1024 {
960	return Err(err!(
961	"A picture in {} by {} tiles.", columns + 1, rows + 1; Invalid, Input, Decode));
962	}
963	if !res!(b.flag()) {
964	for _ in 0..columns {
965	let _width = res!(b.ue());
966	}
967	for _ in 0..rows {
968	let _height = res!(b.ue());
969	}
970	}
971	let _loop_filter_across_tiles = res!(b.flag());
972	}
973	let filter_across_slices = res!(b.flag());
974	let mut deblocking = true;
975	let mut deblocking_override = false;
976	if res!(b.flag()) {
977	deblocking_override = res!(b.flag());
978	deblocking = !res!(b.flag());
979	if deblocking {
980	let _beta_offset = res!(b.se());
981	let _tc_offset = res!(b.se());
982	}
983	}
984	Ok(Pps {
985	id: id as u8,
986	sps_id: sps_id as u8,
987	init_qp,
988	cu_qp_delta,
989	qp_delta_depth,
990	cb_qp_offset,
991	cr_qp_offset,
992	transform_skip,
993	sign_hiding,
994	transquant_bypass,
995	tiles,
996	wavefront,
997	deblocking,
998	slice_chroma_qp,
999	extra_header_bits,
1000	output_flag,
1001	deblocking_override,
1002	filter_across_slices,
1003	dependent_slices,
1004	})
1005	}
1006
1007	/// What a slice segment header says, for the one kind of slice a still picture has.
1008	///
1009	/// A picture is one slice and the slice is intra, so most of the syntax -- reference lists,
1010	/// weighted prediction, temporal motion vectors -- is not reached at all. What matters here is
1011	/// where the header ends: the arithmetic decoder starts at the next byte boundary after it, and
1012	/// a header read one bit short starts the whole of the rest of the decode in the wrong place.
1013	#[derive(Clone, Debug, PartialEq, Eq)]
1014	pub struct Slice {
1015	pub first: bool, // is this segment the first of its picture?
1016	// Nought for the first segment of a picture, which is every segment of a picture that is
1017	// one slice -- which every photograph is and many films are not.
1018	pub address: u32, // the coding tree block it begins at, raster order from nought
1019	pub across_slices: bool, // the picture parameter set's answer where absent (§7.4.7.1)
1020	pub pps_id: u8, // which picture parameter set the slice references
1021	pub kind: u8, // 2 is intra, and this decoder reads no other
1022	pub qp: i32, // the quantisation parameter this slice starts at
1023	pub sao_luma: bool, // does the sample adaptive offset run on luma here?
1024	pub sao_chroma: bool, // and on chroma?
1025	pub data_at: usize, // the header's end rounded up to a byte, where §9.3.1 starts
1026	pub deblocking: bool, // does the deblocking filter run on this slice?
1027	pub cb_qp_offset: i32, // what this slice adds to the picture's chroma offsets
1028	pub cr_qp_offset: i32, // and for the other chroma component
1029	// One a row of coding tree blocks, under wavefront coding, which is what every photograph
1030	// measured uses.
1031	pub entries: Vec<u64>, // where each piece begins, as the length of the one before
1032	}
1033
1034	/// Which picture parameter set a slice names, read without the set itself.
1035	///
1036	/// The identifier is the third element of the header and none of the three before it depends on a
1037	/// parameter set, so it can be had before choosing one -- which is the point: a caller holding
1038	/// several sets has to know which it is being asked for. It sits before the segment address, so
1039	/// this reads the same three elements whether or not the segment is the first of its picture.
1040	pub fn slice_pps_id(body: &[u8]) -> Outcome<u8> {
1041	let mut b = Bits::new(body);
1042	let _first = res!(b.flag());
1043	// Only an IRAP picture carries this flag, and every still is one.
1044	let _no_output_of_prior_pics = res!(b.flag());
1045	Ok(res!(b.ue()) as u8)
1046	}
1047
1048	/// Reads a slice segment header (§7.3.6.1).
1049	///
1050	/// Only the independent, intra case: a dependent slice segment carries no header of its own but
1051	/// continues the one before it, and is refused by name.
1052	///
1053	/// A segment that is not the first of its picture carries the coding tree block it begins at, in as
1054	/// many bits as it takes to count the picture's blocks -- which is why the sequence parameter set is
1055	/// needed to read a header at all.
1056	pub fn slice(body: &[u8], sps: &Sps, pps: &Pps) -> Outcome<Slice> {
1057	slice_of(nal::IDR_W_RADL, body, sps, pps)
1058	}
1059
1060	/// The same, for a slice of a picture that may not be an IDR.
1061	///
1062	/// A film's first frame very often is not one. A clean random access picture opens a stream
1063	/// just as an IDR does and is decoded exactly as one -- it references nothing before itself -- but
1064	/// its slice header carries the picture order count and the reference picture set that an IDR's
1065	/// does not, because the pictures after it may reference what it names. A header read as though
1066	/// it were an IDR's is read out of step from that field onwards, and what comes out is a plausible
1067	/// number of entry points and a picture of noise.
1068	///
1069	/// `kind` is the NAL unit type, which is the only thing that says which of the two this is.
1070	pub fn slice_of(kind: u8, body: &[u8], sps: &Sps, pps: &Pps) -> Outcome<Slice> {
1071	let mut b = Bits::new(body);
1072	let first = res!(b.flag());
1073	// Only an IRAP picture carries this flag, and every still is one.
1074	let _no_output_of_prior_pics = res!(b.flag());
1075	let pps_id = res!(b.ue());
1076	let mut address = 0u32;
1077	if !first {
1078	if pps.dependent_slices && res!(b.flag()) {
1079	return Err(err!(
1080	"A dependent slice segment, which carries no header of its own but continues the \
1081	one before it."; Unimplemented));
1082	}
1083	// As many bits as it takes to count the picture's coding tree blocks (§7.4.7.1).
1084	let ctb = sps.ctb_size.max(1);
1085	let blocks = ((sps.coded_w + ctb - 1) / ctb) as u64 * ((sps.coded_h + ctb - 1) / ctb) as u64;
1086	let mut width = 0usize;
1087	while (1u64 << width) < blocks {
1088	width += 1;
1089	}
1090	address = res!(b.u(width)) as u32;
1091	if address as u64 >= blocks {
1092	return Err(err!(
1093	"A slice segment begins at block {} of a picture holding {}.", address, blocks;
1094	Invalid, Input, Decode));
1095	}
1096	}
1097	if pps_id as u8 != pps.id {
1098	return Err(err!(
1099	"A slice references picture parameter set {} and the one in hand is {}.",
1100	pps_id, pps.id;
1101	Invalid, Input, Missing));
1102	}
1103	// Reserved, and to be stepped over rather than understood. Stepping over the wrong number of
1104	// them puts every field after them one place out, which is why the count is carried here from
1105	// the picture parameter set rather than assumed to be zero. They come before the slice
1106	// type (§7.3.6.1).
1107	res!(b.skip(pps.extra_header_bits as usize));
1108	let slice_kind = res!(b.ue());
1109	if slice_kind != 2 {
1110	return Err(err!(
1111	"A slice of type {}, and a still picture's slices are all intra (type 2).", slice_kind;
1112	Invalid, Input, Unknown));
1113	}
1114	if pps.output_flag {
1115	let _pic_output_flag = res!(b.flag());
1116	}
1117	// What an IDR does not carry, and everything else does: where this picture sits in output
1118	// order, and which pictures the ones after it may reference.
1119	if kind != nal::IDR_W_RADL && kind != nal::IDR_N_LP {
1120	let _poc_lsb = res!(b.u(sps.poc_bits as usize));
1121	let from_sps = res!(b.flag());
1122	if !from_sps {
1123	// A set of its own, written here and coded as a difference from one of the sequence's.
1124	let mut sets = sps.st_sets.clone();
1125	let count = sets.len();
1126	res!(short_term_ref_pic_set(&mut b, count, count, &mut sets));
1127	} else if sps.st_sets.len() > 1 {
1128	// As many bits as it takes to count them (§7.4.7.1).
1129	let mut width = 0usize;
1130	while (1usize << width) < sps.st_sets.len() {
1131	width += 1;
1132	}
1133	let _which = res!(b.u(width));
1134	}
1135	if sps.long_term {
1136	// A sequence carrying long-term reference pictures is refused where it is read, so
1137	// reaching this means the flag is set and the sequence names none of them.
1138	let _num_long_term_pics = res!(b.ue());
1139	return Err(err!(
1140	"A slice names long-term reference pictures, which a picture decoded on its own \
1141	has no use for and this reader does not follow."; Unimplemented));
1142	}
1143	if sps.temporal_mvp {
1144	let _temporal_mvp = res!(b.flag());
1145	}
1146	}
1147	let mut sao_luma = false;
1148	let mut sao_chroma = false;
1149	if sps.sao {
1150	sao_luma = res!(b.flag());
1151	if sps.chroma != 0 {
1152	sao_chroma = res!(b.flag());
1153	}
1154	}
1155	let qp = pps.init_qp + res!(b.se());
1156	if qp < -(6 * (sps.luma_bits as i32 - 8)) \|\| qp > 51 {
1157	return Err(err!(
1158	"A slice starts at a quantisation parameter of {}, outside the legal range.", qp;
1159	Invalid, Input, Decode));
1160	}
1161	// The chroma offsets a slice may add to the picture's own. Kept rather than stepped over:
1162	// they go into the chroma quantisation parameter of every block, so a picture whose slice
1163	// carries one and whose decoder ignores it comes out with the wrong colour saturation.
1164	let (mut cb_offset, mut cr_offset) = (0i32, 0i32);
1165	if pps.slice_chroma_qp {
1166	cb_offset = res!(b.se());
1167	cr_offset = res!(b.se());
1168	}
1169	let mut deblocking = pps.deblocking;
1170	if pps.deblocking_override && res!(b.flag()) {
1171	deblocking = !res!(b.flag());
1172	if deblocking {
1173	let _beta = res!(b.se());
1174	let _tc = res!(b.se());
1175	}
1176	}
1177	// Whether the loop filters run across this slice's boundaries. Where the header does not carry
1178	// it, the picture parameter set's answer stands (§7.4.7.1).
1179	let mut across_slices = pps.filter_across_slices;
1180	if pps.filter_across_slices && (sao_luma \|\| sao_chroma \|\| deblocking) {
1181	across_slices = res!(b.flag());
1182	}
1183	// Where the picture is cut up for parallel decoding, the header says where each piece begins.
1184	//
1185	// A still photograph out of a phone is coded this way. Every one of the 359 HEIC files
1186	// measured sets `entropy_coding_sync_enabled_flag`, which is wavefront coding: the arithmetic
1187	// decoder is reset at the start of every row of coding tree blocks, from the state saved after
1188	// the second block of the row above. So this is not an exotic case to be refused -- it is the
1189	// case, and the offsets below are how the rows are found.
1190	let mut entries: Vec<u64> = Vec::new();
1191	if pps.tiles \|\| pps.wavefront {
1192	let count = res!(b.ue()) as usize;
1193	if count > 4096 {
1194	return Err(err!(
1195	"A slice names {} entry points, and no picture this decoder reads has so many.",
1196	count;
1197	Invalid, Input, Decode));
1198	}
1199	if count > 0 {
1200	let width = res!(b.ue()) as usize + 1;
1201	if width > 32 {
1202	return Err(err!(
1203	"An entry point offset of {} bits, and 32 is the widest.", width;
1204	Invalid, Input, Decode));
1205	}
1206	for _ in 0..count {
1207	entries.push(res!(b.u(width)) as u64 + 1);
1208	}
1209	}
1210	// Under wavefront coding there is one piece per row of coding tree blocks, so the count
1211	// has to agree with the picture's own geometry -- and the geometry came out of the
1212	// sequence parameter set, a different NAL unit written at a different time. A slice header
1213	// read one bit out of step produces a count that is nonsense against it, which makes this
1214	// the cheapest check there is on the whole header: it is what caught the reading that
1215	// refused every photograph in the corpus rather than reading its entry points.
1216	//
1217	// A segment covering part of a picture names fewer pieces than the picture has rows, and
1218	// how many fewer is not knowable from the header alone -- so what is checked here is that
1219	// it names no more, and the exact form is checked by [`whole_picture_rows`] once the number
1220	// of segments is known.
1221	if pps.wavefront && !pps.tiles {
1222	let rows = ((sps.coded_h + sps.ctb_size - 1) / sps.ctb_size) as usize;
1223	let over = entries.len() + 1 > rows;
1224	if over {
1225	return Err(err!(
1226	"A slice names {} pieces and the picture is {} rows of coding tree blocks \
1227	deep. The header has been read out of step.", entries.len() + 1, rows;
1228	Invalid, Input, Decode));
1229	}
1230	}
1231	}
1232	// The header ends with a stop bit and however many zeroes reach the byte boundary, and the
1233	// arithmetic decoder starts at that boundary (§9.3.1).
1234	let bits = res!(b.consumed());
1235	let data_at = (bits + 1 + 7) / 8;
1236	if data_at >= body.len() {
1237	return Err(err!(
1238	"A slice header of {} bits leaves no data in a payload of {} bytes.", bits, body.len();
1239	Invalid, Input, Decode));
1240	}
1241	Ok(Slice {
1242	first,
1243	address,
1244	across_slices,
1245	pps_id: pps_id as u8,
1246	kind: slice_kind as u8,
1247	qp,
1248	cb_qp_offset: cb_offset,
1249	cr_qp_offset: cr_offset,
1250	sao_luma,
1251	sao_chroma,
1252	data_at,
1253	deblocking,
1254	entries,
1255	})
1256	}
1257
1258	#[cfg(test)]
1259	mod tests {
1260	use super::*;
1261
1262	#[test]
1263	fn test_emulation_prevention_is_undone_00() -> Outcome<()> {
1264	// A 0x03 after two zeroes is not payload; one after a single zero is.
1265	req!(rbsp(&[0, 0, 3, 1, 0, 3, 2]), vec![0u8, 0, 1, 0, 3, 2]);
1266	Ok(())
1267	}
1268
1269	#[test]
1270	fn test_a_truncated_nal_unit_is_refused_01() -> Outcome<()> {
1271	// Four bytes of length saying eight, with three following.
1272	let stream = [0u8, 0, 0, 8, 0x26, 1, 9];
1273	req!(split_lengthed(&stream, 4).is_err(), true,
1274	"A unit running past the end of the buffer was read as if it fitted.");
1275	Ok(())
1276	}
1277
1278
1279
1280
1281
1282
1283
1284	#[test]
1285	fn test_exp_golomb_reads_the_codes_the_specification_names_02() -> Outcome<()> {
1286	// 1 -> 0, 010 -> 1, 011 -> 2, 00100 -> 3, and the signed mapping 0, 1, -1, 2, -2.
1287	let mut b = Bits::new(&[0b1010_0110, 0b0100_0000]);
1288	req!(res!(b.ue()), 0);
1289	req!(res!(b.ue()), 1);
1290	req!(res!(b.ue()), 2);
1291	req!(res!(b.ue()), 3);
1292	let mut c = Bits::new(&[0b1010_0110, 0b0100_0000]);
1293	req!(res!(c.se()), 0);
1294	req!(res!(c.se()), 1);
1295	req!(res!(c.se()), -1);
1296	req!(res!(c.se()), 2);
1297	Ok(())
1298	}
1299	}
1300
1301	// ---------------------------------------------------------------- the whole of one picture
1302
1303	/// Decodes one coded picture: an HEIC tile, or a whole photograph that was not cut into tiles.
1304	///
1305	/// `config` is the `hvcC` record from the container, which carries the parameter sets, and `data`
1306	/// is the item's bytes -- NAL units with a length prefix each, which is how a HEIF file stores
1307	/// them rather than with start codes.
1308	///
1309	/// The picture comes back in 4:2:0 at whatever depth it was coded, which for every photograph this
1310	/// was written against is eight bits. It has not been through the deblocking filter or the
1311	/// sample adaptive offset, which are separate passes over a finished picture.
1312	pub fn picture(record: &[u8], data: &[u8]) -> Outcome<decode::Picture> {
1313	let (pic, _sps) = res!(coded(record, data));
1314	Ok(pic)
1315	}
1316
1317	/// The same picture, cropped to the size it is meant to be shown at.
1318	///
1319	/// A coded picture is a whole number of coding tree blocks and a shown one is not: a 1920 by 1080
1320	/// film is coded 1920 by 1088, and the sequence parameter set's conformance window says which of
1321	/// those rows are the picture. [`picture`] hands back what was coded, because the HEIC path crops to
1322	/// the size the container declares instead and cropping twice would take the same rows off again.
1323	/// A caller with no container to ask -- a film's first frame -- wants this one.
1324	pub fn picture_shown(record: &[u8], data: &[u8]) -> Outcome<decode::Picture> {
1325	let (pic, sps) = res!(coded(record, data));
1326	let (w, h) = (sps.width as usize, sps.height as usize);
1327	let (x0, y0) = (sps.show_x0 as usize, sps.show_y0 as usize);
1328	if x0 == 0 && y0 == 0 && w >= pic.y.w && h >= pic.y.h {
1329	return Ok(pic);
1330	}
1331	Ok(pic.window(x0, y0, w.min(pic.y.w), h.min(pic.y.h)))
1332	}
1333
1334	/// Decodes one coded picture, and answers the sequence parameter set it was coded against.
1335	///
1336	/// The set is handed back because what a caller does with the picture next depends on it: the
1337	/// conformance window is in it, and so is everything a caller would otherwise have to parse the
1338	/// parameter sets again to learn.
1339	fn coded(record: &[u8], data: &[u8]) -> Outcome<(decode::Picture, Sps)> {
1340	let cfg = res!(config(record));
1341	// Every set the record carries, not the last of each. A photograph out of a
1342	// camera carries one apiece and either would do; a film carries several, and
1343	// a slice names which one it was coded against. Keeping the last read meant
1344	// four films in ten were refused for referring to a set that was in hand all
1345	// along.
1346	let mut seqs: Vec<Sps> = Vec::new();
1347	let mut pics: Vec<Pps> = Vec::new();
1348	for unit in &cfg.sets {
1349	match unit.kind {
1350	nal::SPS => seqs.push(res!(sps(&unit.body))),
1351	nal::PPS => pics.push(res!(pps(&unit.body))),
1352	_ => {},
1353	}
1354	}
1355	if seqs.is_empty() {
1356	return Err(err!(
1357	"The decoder configuration carries no sequence parameter set."; Invalid, Input));
1358	}
1359	if pics.is_empty() {
1360	return Err(err!(
1361	"The decoder configuration carries no picture parameter set."; Invalid, Input));
1362	}
1363
1364	// And the slices are in the item's own bytes. Every slice of the picture, not the first:
1365	// a photograph is one slice and a film's frame need not be, and a picture read from one of
1366	// four segments is a quarter of a picture.
1367	let units = res!(split_lengthed(data, cfg.length_size));
1368	let mut heads: Vec<(Slice, usize)> = Vec::new();
1369	let mut chosen: Option<(Sps, Pps)> = None;
1370	for (i, unit) in units.iter().enumerate() {
1371	match unit.kind {
1372	nal::IDR_W_RADL \| nal::IDR_N_LP \| 21 => {
1373	// Which sets this slice was coded against: the picture set it
1374	// names, and the sequence set that one belongs to.
1375	let want = res!(slice_pps_id(&unit.body));
1376	let pps = match pics.iter().find(\|p\| p.id == want) {
1377	Some(p) => p.clone(),
1378	None => return Err(err!(
1379	"A slice references picture parameter set {}, and the configuration \
1380	carries {}.", want,
1381	pics.iter().map(\|p\| p.id.to_string()).collect::<Vec<_>>().join(", ");
1382	Invalid, Input, Missing)),
1383	};
1384	let sps = match seqs.iter().find(\|s\| s.id == pps.sps_id) {
1385	Some(s) => s.clone(),
1386	None => return Err(err!(
1387	"Picture parameter set {} belongs to sequence parameter set {}, and the \
1388	configuration carries {}.", pps.id, pps.sps_id,
1389	seqs.iter().map(\|s\| s.id.to_string()).collect::<Vec<_>>().join(", ");
1390	Invalid, Input, Missing)),
1391	};
1392	let head = res!(slice_of(unit.kind, &unit.body, &sps, &pps));
1393	// A second coded picture in the same access unit is somebody else's frame: this
1394	// reads the first picture, and the first picture ends where the next one begins.
1395	if head.first && !heads.is_empty() {
1396	break;
1397	}
1398	match &chosen {
1399	Some((have_sps, have_pps)) => {
1400	if have_sps.id != sps.id \|\| have_pps.id != pps.id {
1401	return Err(err!(
1402	"Two slices of one picture reference different parameter sets.";
1403	Invalid, Input, Mismatch));
1404	}
1405	},
1406	None => chosen = Some((sps, pps)),
1407	}
1408	heads.push((head, i));
1409	},
1410	_ => {},
1411	}
1412	}
1413	let (sps, pps) = match chosen {
1414	Some(pair) => pair,
1415	None => return Err(err!("Those bytes hold no coded slice."; Invalid, Input, Decode)),
1416	};
1417	// A picture that is one slice must name one piece a row of blocks, since that is what
1418	// wavefront coding is. It is the cheapest check there is on the whole header -- the count and
1419	// the geometry come out of different NAL units written at different times -- and it is what
1420	// caught the reading that refused every photograph in the corpus.
1421	if heads.len() == 1 && pps.wavefront && !pps.tiles {
1422	let rows = ((sps.coded_h + sps.ctb_size - 1) / sps.ctb_size) as usize;
1423	let named = heads[0].0.entries.len() + 1;
1424	if named != rows {
1425	return Err(err!(
1426	"A slice names {} pieces and the picture is {} rows of coding tree blocks deep. \
1427	The header has been read out of step.", named, rows;
1428	Invalid, Input, Decode));
1429	}
1430	}
1431	// The header was read from the unescaped payload; the data after it has to be handed over
1432	// escaped, because that is what the entry point offsets count.
1433	let parts: Vec<(&Slice, &[u8])> = heads.iter()
1434	.map(\|(head, i)\| {
1435	let raw = &units[*i].raw;
1436	(head, &raw[escaped_at(raw, head.data_at).min(raw.len())..])
1437	})
1438	.collect();
1439	let pic = res!(decode::picture_of(&sps, &pps, &parts));
1440	Ok((pic, sps))
1441	}