Document AV1 entropy range coding

src/ImageSharp/Formats/Heif/Av1/Entropy/Av1Distribution.cs

@@ -4,90 +4,260 @@
 namespace SixLabors.ImageSharp.Formats.Heif.Av1.Entropy;
 
 /// <summary>
-/// Class representing the probability distribution used for symbol coding.
+/// Stores and adapts an AV1 inverse cumulative distribution used by the range coder.
 /// </summary>
 internal class Av1Distribution
 {
+    /// <summary>
+    /// The exclusive upper bound of the Q15 probability domain.
+    /// </summary>
     internal const int ProbabilityTop = 1 << ProbabilityBitCount;
+
+    /// <summary>
+    /// The minimum sub-range reserved for each symbol during range coding.
+    /// </summary>
     internal const int ProbabilityMinimum = 4;
+
+    /// <summary>
+    /// The shift that converts stored Q15 cumulative values to the range-coder precision.
+    /// </summary>
     internal const int CdfShift = 15 - ProbabilityBitCount;
+
+    /// <summary>
+    /// The precision reduction applied before multiplying a cumulative value by the coding range.
+    /// </summary>
     internal const int ProbabilityShift = 6;
 
+    /// <summary>
+    /// The number of fractional bits in a stored cumulative probability.
+    /// </summary>
     private const int ProbabilityBitCount = 15;
 
+    /// <summary>
+    /// The inverse cumulative thresholds followed by the required zero sentinel.
+    /// </summary>
     private readonly uint[] probabilities;
+
+    /// <summary>
+    /// The symbol-count contribution to the adaptive update rate.
+    /// </summary>
     private readonly int speed;
+
+    /// <summary>
+    /// The capped number of observations already incorporated into this distribution.
+    /// </summary>
     private int updateCount;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a binary alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
     public Av1Distribution(uint p0)
         : this([p0, 0], 1)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a three-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
     public Av1Distribution(uint p0, uint p1)
         : this([p0, p1, 0], 1)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a four-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
     public Av1Distribution(uint p0, uint p1, uint p2)
         : this([p0, p1, p2, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a five-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
+    /// <param name="p3">The cumulative threshold following symbol three.</param>
     public Av1Distribution(uint p0, uint p1, uint p2, uint p3)
         : this([p0, p1, p2, p3, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a six-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
+    /// <param name="p3">The cumulative threshold following symbol three.</param>
+    /// <param name="p4">The cumulative threshold following symbol four.</param>
     public Av1Distribution(uint p0, uint p1, uint p2, uint p3, uint p4)
         : this([p0, p1, p2, p3, p4, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a seven-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
+    /// <param name="p3">The cumulative threshold following symbol three.</param>
+    /// <param name="p4">The cumulative threshold following symbol four.</param>
+    /// <param name="p5">The cumulative threshold following symbol five.</param>
     public Av1Distribution(uint p0, uint p1, uint p2, uint p3, uint p4, uint p5)
         : this([p0, p1, p2, p3, p4, p5, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for an eight-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
+    /// <param name="p3">The cumulative threshold following symbol three.</param>
+    /// <param name="p4">The cumulative threshold following symbol four.</param>
+    /// <param name="p5">The cumulative threshold following symbol five.</param>
+    /// <param name="p6">The cumulative threshold following symbol six.</param>
     public Av1Distribution(uint p0, uint p1, uint p2, uint p3, uint p4, uint p5, uint p6)
         : this([p0, p1, p2, p3, p4, p5, p6, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a nine-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
+    /// <param name="p3">The cumulative threshold following symbol three.</param>
+    /// <param name="p4">The cumulative threshold following symbol four.</param>
+    /// <param name="p5">The cumulative threshold following symbol five.</param>
+    /// <param name="p6">The cumulative threshold following symbol six.</param>
+    /// <param name="p7">The cumulative threshold following symbol seven.</param>
     public Av1Distribution(uint p0, uint p1, uint p2, uint p3, uint p4, uint p5, uint p6, uint p7)
         : this([p0, p1, p2, p3, p4, p5, p6, p7, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a ten-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
+    /// <param name="p3">The cumulative threshold following symbol three.</param>
+    /// <param name="p4">The cumulative threshold following symbol four.</param>
+    /// <param name="p5">The cumulative threshold following symbol five.</param>
+    /// <param name="p6">The cumulative threshold following symbol six.</param>
+    /// <param name="p7">The cumulative threshold following symbol seven.</param>
+    /// <param name="p8">The cumulative threshold following symbol eight.</param>
     public Av1Distribution(uint p0, uint p1, uint p2, uint p3, uint p4, uint p5, uint p6, uint p7, uint p8)
         : this([p0, p1, p2, p3, p4, p5, p6, p7, p8, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for an eleven-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
+    /// <param name="p3">The cumulative threshold following symbol three.</param>
+    /// <param name="p4">The cumulative threshold following symbol four.</param>
+    /// <param name="p5">The cumulative threshold following symbol five.</param>
+    /// <param name="p6">The cumulative threshold following symbol six.</param>
+    /// <param name="p7">The cumulative threshold following symbol seven.</param>
+    /// <param name="p8">The cumulative threshold following symbol eight.</param>
+    /// <param name="p9">The cumulative threshold following symbol nine.</param>
     public Av1Distribution(uint p0, uint p1, uint p2, uint p3, uint p4, uint p5, uint p6, uint p7, uint p8, uint p9)
         : this([p0, p1, p2, p3, p4, p5, p6, p7, p8, p9, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a thirteen-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
+    /// <param name="p3">The cumulative threshold following symbol three.</param>
+    /// <param name="p4">The cumulative threshold following symbol four.</param>
+    /// <param name="p5">The cumulative threshold following symbol five.</param>
+    /// <param name="p6">The cumulative threshold following symbol six.</param>
+    /// <param name="p7">The cumulative threshold following symbol seven.</param>
+    /// <param name="p8">The cumulative threshold following symbol eight.</param>
+    /// <param name="p9">The cumulative threshold following symbol nine.</param>
+    /// <param name="p10">The cumulative threshold following symbol ten.</param>
+    /// <param name="p11">The cumulative threshold following symbol eleven.</param>
     public Av1Distribution(uint p0, uint p1, uint p2, uint p3, uint p4, uint p5, uint p6, uint p7, uint p8, uint p9, uint p10, uint p11)
         : this([p0, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a fourteen-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
+    /// <param name="p3">The cumulative threshold following symbol three.</param>
+    /// <param name="p4">The cumulative threshold following symbol four.</param>
+    /// <param name="p5">The cumulative threshold following symbol five.</param>
+    /// <param name="p6">The cumulative threshold following symbol six.</param>
+    /// <param name="p7">The cumulative threshold following symbol seven.</param>
+    /// <param name="p8">The cumulative threshold following symbol eight.</param>
+    /// <param name="p9">The cumulative threshold following symbol nine.</param>
+    /// <param name="p10">The cumulative threshold following symbol ten.</param>
+    /// <param name="p11">The cumulative threshold following symbol eleven.</param>
+    /// <param name="p12">The cumulative threshold following symbol twelve.</param>
     public Av1Distribution(uint p0, uint p1, uint p2, uint p3, uint p4, uint p5, uint p6, uint p7, uint p8, uint p9, uint p10, uint p11, uint p12)
         : this([p0, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11, p12, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class for a sixteen-symbol alphabet.
+    /// </summary>
+    /// <param name="p0">The cumulative threshold following symbol zero.</param>
+    /// <param name="p1">The cumulative threshold following symbol one.</param>
+    /// <param name="p2">The cumulative threshold following symbol two.</param>
+    /// <param name="p3">The cumulative threshold following symbol three.</param>
+    /// <param name="p4">The cumulative threshold following symbol four.</param>
+    /// <param name="p5">The cumulative threshold following symbol five.</param>
+    /// <param name="p6">The cumulative threshold following symbol six.</param>
+    /// <param name="p7">The cumulative threshold following symbol seven.</param>
+    /// <param name="p8">The cumulative threshold following symbol eight.</param>
+    /// <param name="p9">The cumulative threshold following symbol nine.</param>
+    /// <param name="p10">The cumulative threshold following symbol ten.</param>
+    /// <param name="p11">The cumulative threshold following symbol eleven.</param>
+    /// <param name="p12">The cumulative threshold following symbol twelve.</param>
+    /// <param name="p13">The cumulative threshold following symbol thirteen.</param>
+    /// <param name="p14">The cumulative threshold following symbol fourteen.</param>
     public Av1Distribution(uint p0, uint p1, uint p2, uint p3, uint p4, uint p5, uint p6, uint p7, uint p8, uint p9, uint p10, uint p11, uint p12, uint p13, uint p14)
         : this([p0, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11, p12, p13, p14, 0], 2)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1Distribution"/> class from forward cumulative thresholds.
+    /// </summary>
+    /// <param name="props">The forward Q15 thresholds followed by a zero sentinel slot.</param>
+    /// <param name="speed">The symbol-count contribution to the update rate.</param>
     private Av1Distribution(uint[] props, int speed)
     {
-        // this.probabilities = props;
         this.probabilities = new uint[props.Length];
+
+        // AV1 range coding consumes inverse cumulative thresholds. The defaults are written in the more readable
+        // forward form, so convert every real threshold while leaving the final zero sentinel untouched.
         for (int i = 0; i < props.Length - 1; i++)
         {
             this.probabilities[i] = ProbabilityTop - props[i];
@@ -97,18 +267,33 @@ internal class Av1Distribution
         this.speed = speed;
     }
 
+    /// <summary>
+    /// Gets the number of symbols represented by the distribution.
+    /// </summary>
     public int NumberOfSymbols { get; }
 
+    /// <summary>
+    /// Gets an inverse cumulative threshold by symbol index.
+    /// </summary>
+    /// <param name="index">The zero-based threshold index.</param>
+    /// <returns>The Q15 inverse cumulative threshold.</returns>
     public uint this[int index] => this.probabilities[index];
 
+    /// <summary>
+    /// Adapts the cumulative thresholds after coding one symbol.
+    /// </summary>
+    /// <param name="value">The zero-based symbol that was coded.</param>
     public void Update(int value)
     {
+        // AV1 slows adaptation after 16 and 32 observations. The symbol-count term is precomputed by each overload
+        // because every distribution has a fixed alphabet size.
         int rate15 = this.updateCount > 15 ? 1 : 0;
         int rate31 = this.updateCount > 31 ? 1 : 0;
-        int rate = 3 + rate15 + rate31 + this.speed; // + get_msb(nsymbs);
+        int rate = 3 + rate15 + rate31 + this.speed;
         int tmp = ProbabilityTop;
 
-        // Single loop (faster)
+        // Switching tmp to zero at the observed symbol moves the thresholds on either side toward the sample while
+        // preserving their inverse-cumulative ordering in one pass.
         for (int i = 0; i < this.NumberOfSymbols - 1; i++)
         {
             tmp = i == value ? 0 : tmp;

src/ImageSharp/Formats/Heif/Av1/Entropy/Av1SymbolReader.cs

@@ -3,31 +3,54 @@
 
 namespace SixLabors.ImageSharp.Formats.Heif.Av1.Entropy;
 
+/// <summary>
+/// Reads AV1 literals and adaptively coded symbols from one bounded entropy-coded byte span.
+/// </summary>
 internal ref struct Av1SymbolReader
 {
+    /// <summary>
+    /// The number of bits in the range-decoder code-value window.
+    /// </summary>
     private const int DecoderWindowsSize = 32;
+
+    /// <summary>
+    /// The synthetic count used after the bounded input has been exhausted and zero padding begins.
+    /// </summary>
     private const int LotsOfBits = 0x4000;
 
+    /// <summary>
+    /// The bounded entropy-coded bytes available to this reader.
+    /// </summary>
     private readonly Span<byte> buffer;
+
+    /// <summary>
+    /// The next byte position to load into the code-value window.
+    /// </summary>
     private int position;
 
-    /*
-     * The difference between the high end of the current range, (low + rng), and
-     * the coded value, minus 1.
-     * This stores up to OD_EC_WINDOW_SIZE bits of that difference, but the
-     * decoder only uses the top 16 bits of the window to decode the next symbol.
-     * As we shift up during renormalization, if we don't have enough bits left in
-     * the window to fill the top 16, we'll read in more bits of the coded
-     * value.
-     */
+    /// <summary>
+    /// The difference between the upper end of the current range and the coded value, minus one.
+    /// </summary>
+    /// <remarks>
+    /// The decoder compares the upper 16 bits. Renormalization shifts consumed bits out and refills the lower portion
+    /// from <see cref="buffer"/> so the comparison remains aligned with <see cref="range"/>.
+    /// </remarks>
     private uint difference;
 
-    // The number of values in the current range.
+    /// <summary>
+    /// The number of code values in the current normalized interval.
+    /// </summary>
     private uint range;
 
-    // The number of bits in the current value.
+    /// <summary>
+    /// The number of buffered bits below the 16-bit comparison window.
+    /// </summary>
     private int count;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1SymbolReader"/> struct over one entropy-coded span.
+    /// </summary>
+    /// <param name="span">The bounded entropy-coded bytes.</param>
     public Av1SymbolReader(Span<byte> span)
     {
         this.buffer = span;
@@ -38,15 +61,25 @@ internal ref struct Av1SymbolReader
         this.Refill();
     }
 
+    /// <summary>
+    /// Reads one symbol and adapts its distribution.
+    /// </summary>
+    /// <param name="distribution">The inverse cumulative distribution for the symbol alphabet.</param>
+    /// <returns>The decoded zero-based symbol.</returns>
     public int ReadSymbol(Av1Distribution distribution)
     {
         int value = this.DecodeIntegerQ15(distribution);
 
-        // UpdateCdf(probabilities, value, numberOfSymbols);
+        // Decoder and encoder must adapt after the same symbol so their subsequent intervals remain identical.
         distribution.Update(value);
         return value;
     }
 
+    /// <summary>
+    /// Reads an unsigned literal in most-significant-bit-first order.
+    /// </summary>
+    /// <param name="bitCount">The number of literal bits to read.</param>
+    /// <returns>The decoded literal.</returns>
     public int ReadLiteral(int bitCount)
     {
         const uint prob = (0x7FFFFFU - (128 << 15) + 128) >> 8;
@@ -66,6 +99,7 @@ internal ref struct Av1SymbolReader
     /// Decode a single binary value.
     /// </summary>
     /// <param name="frequency">The probability that the bit is one, scaled by 32768.</param>
+    /// <returns>The decoded binary value.</returns>
     private bool DecodeBoolQ15(uint frequency)
     {
         uint dif;
@@ -75,13 +109,11 @@ internal ref struct Av1SymbolReader
         uint v;
         bool ret;
 
-        // assert(0 < f);
-        // assert(f < 32768U);
         dif = this.difference;
         range = this.range;
 
-        // assert(dif >> (DecoderWindowsSize - 16) < r);
-        // assert(32768U <= r);
+        // Reserve a minimum interval for both outcomes after reducing the Q15 frequency to the range-coder
+        // multiplication precision. This is the same rounding model used by Av1SymbolWriter.
         v = ((range >> 8) * (frequency >> Av1Distribution.ProbabilityShift)) >> (7 - Av1Distribution.ProbabilityShift);
         v += Av1Distribution.ProbabilityMinimum;
         vw = v << (DecoderWindowsSize - 16);
@@ -146,16 +178,14 @@ internal ref struct Av1SymbolReader
     /// <paramref name="rng"/> has value between 32768 and 65536 (reading more bytes from the stream into dif if
     /// necessary), and stores them back in the decoder context.
     /// </summary>
+    /// <param name="dif">The updated code-value difference.</param>
+    /// <param name="rng">The updated coding interval width.</param>
     private void Normalize(uint dif, uint rng)
     {
-        int d;
-
-        // assert(rng <= 65535U);
-        /*The number of leading zeros in the 16-bit binary representation of rng.*/
-        d = 15 - Av1Math.MostSignificantBit(rng);
-        /*d bits in dec->dif are consumed.*/
+        // Shifting by the leading-zero count restores the interval to [32768, 65536) and consumes the same number of
+        // code-value bits. Adding one before the shift preserves the decoder's difference-minus-one representation.
+        int d = 15 - Av1Math.MostSignificantBit(rng);
         this.count -= d;
-        /*This is equivalent to shifting in 1's instead of 0's.*/
         this.difference = ((dif + 1) << d) - 1;
         this.range = rng << d;
         if (this.count < 0)
@@ -164,19 +194,20 @@ internal ref struct Av1SymbolReader
         }
     }
 
+    /// <summary>
+    /// Loads whole bytes into the lower portion of the code-value window after renormalization.
+    /// </summary>
     private void Refill()
     {
-        int s;
         uint dif = this.difference;
         int cnt = this.count;
         int position = this.position;
         int end = this.buffer.Length;
-        s = DecoderWindowsSize - 9 - (cnt + 15);
+        int s = DecoderWindowsSize - 9 - (cnt + 15);
         for (; s >= 0 && position < end; s -= 8, position++)
         {
-            /*Each time a byte is inserted into the window (dif), bptr advances and cnt
-           is incremented by 8, so the total number of consumed bits (the return
-           value of od_ec_dec_tell) does not change.*/
+            // XOR inserts a source byte into the difference-minus-one representation. Advancing both the byte
+            // position and buffered-bit count leaves the logical number of consumed bits unchanged.
             DebugGuard.MustBeLessThan(s, DecoderWindowsSize - 8, nameof(s));
             dif ^= (uint)this.buffer[position] << s;
             cnt += 8;
@@ -184,19 +215,8 @@ internal ref struct Av1SymbolReader
 
         if (position >= end)
         {
-            /*
-             * We've reached the end of the buffer. It is perfectly valid for us to need
-             * to fill the window with additional bits past the end of the buffer (and
-             * this happens in normal operation). These bits should all just be taken
-             * as zero. But we cannot increment bptr past 'end' (this is undefined
-             * behavior), so we start to increment dec->tell_offs. We also don't want
-             * to keep testing bptr against 'end', so we set cnt to OD_EC_LOTS_OF_BITS
-             * and adjust dec->tell_offs so that the total number of unconsumed bits in
-             * the window (dec->cnt - dec->tell_offs) does not change. This effectively
-             * puts lots of zero bits into the window, and means we won't try to refill
-             * it from the buffer for a very long time (at which point we'll put lots
-             * of zero bits into the window again).
-             */
+            // AV1 range decoding permits the final interval to consume implicit zero padding. A large count models
+            // that padding without advancing beyond the bounded source span or repeatedly attempting to refill it.
             cnt = LotsOfBits;
         }
 

src/ImageSharp/Formats/Heif/Av1/Entropy/Av1SymbolWriter.cs

@@ -6,28 +6,73 @@ using SixLabors.ImageSharp.Memory;
 
 namespace SixLabors.ImageSharp.Formats.Heif.Av1.Entropy;
 
+/// <summary>
+/// Writes AV1 literals and adaptively coded symbols to a range-coded byte sequence.
+/// </summary>
 internal class Av1SymbolWriter : IDisposable
 {
+    /// <summary>
+    /// The lower endpoint of the current coding interval.
+    /// </summary>
     private uint low;
+
+    /// <summary>
+    /// The width of the current normalized coding interval.
+    /// </summary>
     private uint rng = 0x8000U;
 
-    // Count is initialized to -9 so that it crosses zero after we've accumulated one byte + one carry bit.
+    /// <summary>
+    /// The number of accumulated bits relative to the next byte-and-carry flush boundary.
+    /// </summary>
+    /// <remarks>
+    /// The initial value of -9 crosses zero after one output byte and its carry bit have accumulated.
+    /// </remarks>
     private int cnt = -9;
+
+    /// <summary>
+    /// The configuration that supplies output allocation.
+    /// </summary>
     private readonly Configuration configuration;
+
+    /// <summary>
+    /// The pre-carry output values accumulated during renormalization.
+    /// </summary>
     private readonly AutoExpandingMemory<ushort> memory;
+
+    /// <summary>
+    /// The next pre-carry output position.
+    /// </summary>
     private int position;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Av1SymbolWriter"/> class with an estimated output size.
+    /// </summary>
+    /// <param name="configuration">The configuration that supplies output allocation.</param>
+    /// <param name="initialSize">The estimated encoded size in bytes.</param>
     public Av1SymbolWriter(Configuration configuration, int initialSize)
     {
         this.configuration = configuration;
         this.memory = new AutoExpandingMemory<ushort>(configuration, (initialSize + 1) >> 1);
     }
 
+    /// <summary>
+    /// Releases the expandable pre-carry buffer.
+    /// </summary>
     public void Dispose() => this.memory.Dispose();
 
+    /// <summary>
+    /// Writes one binary symbol and adapts its distribution.
+    /// </summary>
+    /// <param name="symbol">The binary symbol.</param>
+    /// <param name="distribution">The inverse cumulative distribution for the binary alphabet.</param>
     public void WriteSymbol(bool symbol, Av1Distribution distribution)
         => this.WriteSymbol(symbol ? 1 : 0, distribution);
 
+    /// <summary>
+    /// Writes one symbol and adapts its distribution.
+    /// </summary>
+    /// <param name="symbol">The zero-based symbol.</param>
+    /// <param name="distribution">The inverse cumulative distribution for the symbol alphabet.</param>
     public void WriteSymbol(int symbol, Av1Distribution distribution)
     {
         DebugGuard.MustBeGreaterThanOrEqualTo(symbol, 0, nameof(symbol));
@@ -38,8 +83,17 @@ internal class Av1SymbolWriter : IDisposable
         distribution.Update(symbol);
     }
 
+    /// <summary>
+    /// Writes one equiprobable literal bit.
+    /// </summary>
+    /// <param name="value">The literal bit.</param>
     public void WriteLiteral(bool value) => this.WriteLiteral(value ? 1u : 0u, 1);
 
+    /// <summary>
+    /// Writes the requested low-order bits in most-significant-bit-first order.
+    /// </summary>
+    /// <param name="value">The unsigned literal value.</param>
+    /// <param name="bitCount">The number of low-order bits to write.</param>
     public void WriteLiteral(uint value, int bitCount)
     {
         const uint p = 0x4000U; // (0x7FFFFFU - (128 << 15) + 128) >> 8;
@@ -50,10 +104,14 @@ internal class Av1SymbolWriter : IDisposable
         }
     }
 
+    /// <summary>
+    /// Terminates the range-coded sequence and propagates pending carries into an owned byte buffer.
+    /// </summary>
+    /// <returns>An owner containing the shortest byte sequence that preserves every encoded symbol.</returns>
     public IMemoryOwner<byte> Exit()
     {
-        // We output the minimum number of bits that ensures that the symbols encoded
-        // thus far will be decoded correctly regardless of the bits that follow.
+        // Round the low endpoint into the current interval so the emitted prefix selects every symbol encoded so far
+        // regardless of the bits that follow it.
         uint l = this.low;
         int c = this.cnt;
         int pos = this.position;
@@ -80,7 +138,8 @@ internal class Av1SymbolWriter : IDisposable
         c = Math.Max((s + 7) >> 3, 0);
         IMemoryOwner<byte> output = this.configuration.MemoryAllocator.Allocate<byte>(pos + c);
 
-        // Perform carry propagation.
+        // Pre-carry values use 16-bit elements so a byte plus a propagated carry can coexist. Walking backwards folds
+        // each carry into the preceding byte without shifting the buffered sequence.
         Span<byte> outputSlice = output.GetSpan()[(output.Length() - pos)..];
         c = 0;
         while (pos > 0)
@@ -109,6 +168,9 @@ internal class Av1SymbolWriter : IDisposable
         l = this.low;
         r = this.rng;
         DebugGuard.MustBeGreaterThanOrEqualTo(r, 32768U, nameof(r));
+
+        // Reduce the Q15 frequency to the range-coder multiplication precision and retain a nonzero interval for
+        // both outcomes. Av1SymbolReader applies the identical rounding model.
         v = ((r >> 8) * (frequency >> Av1Distribution.ProbabilityShift)) >> (7 - Av1Distribution.ProbabilityShift);
         v += Av1Distribution.ProbabilityMinimum;
         if (val)
@@ -136,6 +198,13 @@ internal class Av1SymbolWriter : IDisposable
     private void EncodeIntegerQ15(int symbol, Av1Distribution distribution)
         => this.EncodeIntegerQ15(symbol > 0 ? distribution[symbol - 1] : Av1Distribution.ProbabilityTop, distribution[symbol], symbol, distribution.NumberOfSymbols);
 
+    /// <summary>
+    /// Narrows the coding interval to one symbol's inverse-cumulative bounds.
+    /// </summary>
+    /// <param name="lowFrequency">The inverse cumulative threshold preceding the symbol.</param>
+    /// <param name="highFrequency">The inverse cumulative threshold following the symbol.</param>
+    /// <param name="symbol">The zero-based symbol.</param>
+    /// <param name="numberOfSymbols">The size of the symbol alphabet.</param>
     private void EncodeIntegerQ15(uint lowFrequency, uint highFrequency, int symbol, int numberOfSymbols)
     {
         const int totalShift = 7 - Av1Distribution.ProbabilityShift - Av1Distribution.CdfShift;
@@ -182,11 +251,9 @@ internal class Av1SymbolWriter : IDisposable
         DebugGuard.MustBeLessThanOrEqualTo(rng, 65535U, nameof(rng));
         d = 15 - Av1Math.MostSignificantBit(rng);
         s = c + d;
-        /*TODO: Right now we flush every time we have at least one byte available.
-        Instead we should use an OdEcWindow and flush right before we're about to
-        shift bits off the end of the window.
-        For a 32-bit window this is about the same amount of work, but for a 64-bit
-        window it should be a fair win.*/
+
+        // The 32-bit low endpoint is flushed whenever a byte becomes available. Retaining pre-carry values as
+        // ushort elements defers carry propagation until Exit without requiring a separate wider coding window.
         if (s >= 0)
         {
             uint m;