From e838c22a9c39d875ca3822e13ef0ec4dbf76e1ce Mon Sep 17 00:00:00 2001
From: James Jackson-South <james_south@hotmail.com>
Date: Mon, 24 Aug 2026 23:34:20 +1000
Subject: [PATCH] Complete HEIF transform documentation

---
 .../Formats/Heif/Av1/Av1YuvConverter.cs       |  3 +
 .../Heif/Av1/Tiling/Av1SuperblockInfo.cs      |  1 +
 .../Heif/Av1/Transform/Av1CoefficientShape.cs | 15 ++++
 .../Heif/Av1/Transform/Av1TransformClass.cs   | 11 +++
 .../Av1/Transform/Av1TransformFunctionType.cs | 59 +++++++++++++
 .../Heif/Av1/Transform/Av1TransformMode.cs    | 11 +++
 .../Heif/Av1/Transform/Av1TransformSetType.cs |  4 +
 .../Heif/Av1/Transform/Av1TransformSize.cs    | 87 +++++++++++++++++++
 .../Heif/Av1/Transform/Av1TransformType.cs    | 48 ++++++++++
 .../Heif/Av1/Transform/Av1TransformType1d.cs  | 15 ++++
 10 files changed, 254 insertions(+)

diff --git a/src/ImageSharp/Formats/Heif/Av1/Av1YuvConverter.cs b/src/ImageSharp/Formats/Heif/Av1/Av1YuvConverter.cs
index c3c6d214e..1a10640eb 100644
--- a/src/ImageSharp/Formats/Heif/Av1/Av1YuvConverter.cs
+++ b/src/ImageSharp/Formats/Heif/Av1/Av1YuvConverter.cs
@@ -317,6 +317,7 @@ internal static class Av1YuvConverter
     /// <summary>
     /// Converts one YUV row to packed RGB using the resolved H.273 conversion state.
     /// </summary>
+    /// <typeparam name="TSample">The encoded sample type.</typeparam>
     /// <param name="ySource">The luma samples.</param>
     /// <param name="uRow0">The upper blue-difference chroma row.</param>
     /// <param name="uRow1">The lower blue-difference chroma row.</param>
@@ -412,6 +413,7 @@ internal static class Av1YuvConverter
     /// <summary>
     /// Bilinearly reconstructs a chroma sample at a luma coordinate.
     /// </summary>
+    /// <typeparam name="TSample">The encoded sample type.</typeparam>
     /// <param name="row0">The upper chroma row.</param>
     /// <param name="row1">The lower chroma row.</param>
     /// <param name="x">The luma column coordinate.</param>
@@ -485,6 +487,7 @@ internal static class Av1YuvConverter
     /// <summary>
     /// Converts one packed RGB row to YUV 4:4:4 using the resolved H.273 conversion state.
     /// </summary>
+    /// <typeparam name="TSample">The encoded sample type.</typeparam>
     /// <param name="source">The source RGB pixels.</param>
     /// <param name="yDestination">The destination luma samples.</param>
     /// <param name="uDestination">The destination blue-difference chroma samples.</param>
diff --git a/src/ImageSharp/Formats/Heif/Av1/Tiling/Av1SuperblockInfo.cs b/src/ImageSharp/Formats/Heif/Av1/Tiling/Av1SuperblockInfo.cs
index c381c2236..610b0698c 100644
--- a/src/ImageSharp/Formats/Heif/Av1/Tiling/Av1SuperblockInfo.cs
+++ b/src/ImageSharp/Formats/Heif/Av1/Tiling/Av1SuperblockInfo.cs
@@ -106,6 +106,7 @@ internal class Av1SuperblockInfo
     /// <summary>
     /// Gets the mode information records parsed for this superblock in bitstream order.
     /// </summary>
+    /// <returns>The mode information records for the superblock.</returns>
     public Span<Av1BlockModeInfo> GetModeInfos() => this.frameInfo.GetModeInfos(this.Position, this.BlockCount);
 
     /// <summary>
diff --git a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1CoefficientShape.cs b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1CoefficientShape.cs
index b1e62deb1..1cb149288 100644
--- a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1CoefficientShape.cs
+++ b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1CoefficientShape.cs
@@ -8,8 +8,23 @@ namespace SixLabors.ImageSharp.Formats.Heif.Av1.Transform;
 /// </summary>
 internal enum Av1CoefficientShape
 {
+    /// <summary>
+    /// Evaluates the complete coefficient plane.
+    /// </summary>
     Default,
+
+    /// <summary>
+    /// Evaluates the half-coefficient shape.
+    /// </summary>
     N2,
+
+    /// <summary>
+    /// Evaluates the quarter-coefficient shape.
+    /// </summary>
     N4,
+
+    /// <summary>
+    /// Evaluates only the DC coefficient.
+    /// </summary>
     OnlyDc
 }
diff --git a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformClass.cs b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformClass.cs
index 1d96f3ea0..759384373 100644
--- a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformClass.cs
+++ b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformClass.cs
@@ -8,7 +8,18 @@ namespace SixLabors.ImageSharp.Formats.Heif.Av1.Transform;
 /// </summary>
 internal enum Av1TransformClass
 {
+    /// <summary>
+    /// A two-dimensional transform with non-identity processing on both axes.
+    /// </summary>
     Class2D = 0,
+
+    /// <summary>
+    /// A horizontal transform with identity processing on the vertical axis.
+    /// </summary>
     ClassHorizontal = 1,
+
+    /// <summary>
+    /// A vertical transform with identity processing on the horizontal axis.
+    /// </summary>
     ClassVertical = 2,
 }
diff --git a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformFunctionType.cs b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformFunctionType.cs
index cd06fd235..025006789 100644
--- a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformFunctionType.cs
+++ b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformFunctionType.cs
@@ -8,19 +8,78 @@ namespace SixLabors.ImageSharp.Formats.Heif.Av1.Transform;
 /// </summary>
 internal enum Av1TransformFunctionType
 {
+    /// <summary>
+    /// A four-sample discrete cosine transform.
+    /// </summary>
     Dct4,
+
+    /// <summary>
+    /// An eight-sample discrete cosine transform.
+    /// </summary>
     Dct8,
+
+    /// <summary>
+    /// A sixteen-sample discrete cosine transform.
+    /// </summary>
     Dct16,
+
+    /// <summary>
+    /// A thirty-two-sample discrete cosine transform.
+    /// </summary>
     Dct32,
+
+    /// <summary>
+    /// A sixty-four-sample discrete cosine transform.
+    /// </summary>
     Dct64,
+
+    /// <summary>
+    /// A four-sample asymmetric discrete sine transform.
+    /// </summary>
     Adst4,
+
+    /// <summary>
+    /// An eight-sample asymmetric discrete sine transform.
+    /// </summary>
     Adst8,
+
+    /// <summary>
+    /// A sixteen-sample asymmetric discrete sine transform.
+    /// </summary>
     Adst16,
+
+    /// <summary>
+    /// A thirty-two-sample asymmetric discrete sine transform.
+    /// </summary>
     Adst32,
+
+    /// <summary>
+    /// A four-sample identity transform.
+    /// </summary>
     Identity4,
+
+    /// <summary>
+    /// An eight-sample identity transform.
+    /// </summary>
     Identity8,
+
+    /// <summary>
+    /// A sixteen-sample identity transform.
+    /// </summary>
     Identity16,
+
+    /// <summary>
+    /// A thirty-two-sample identity transform.
+    /// </summary>
     Identity32,
+
+    /// <summary>
+    /// A sixty-four-sample identity transform.
+    /// </summary>
     Identity64,
+
+    /// <summary>
+    /// No valid transform function.
+    /// </summary>
     Invalid,
 }
diff --git a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformMode.cs b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformMode.cs
index e56fccca6..b60092117 100644
--- a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformMode.cs
+++ b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformMode.cs
@@ -8,7 +8,18 @@ namespace SixLabors.ImageSharp.Formats.Heif.Av1.Transform;
 /// </summary>
 internal enum Av1TransformMode : byte
 {
+    /// <summary>
+    /// Every transform block is four by four samples.
+    /// </summary>
     Only4x4 = 0,
+
+    /// <summary>
+    /// Each block uses the largest permitted transform size.
+    /// </summary>
     Largest = 1,
+
+    /// <summary>
+    /// Transform-block sizes are selected by block-level syntax.
+    /// </summary>
     Select = 2,
 }
diff --git a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformSetType.cs b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformSetType.cs
index 244228f00..512ca6880 100644
--- a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformSetType.cs
+++ b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformSetType.cs
@@ -39,5 +39,9 @@ internal enum Av1TransformSetType
     /// Allowed transforms: Discrete Trig transforms w/ flip (9) + Identity (1) + 1D Hor/Ver (6)
     /// </summary>
     InterSet1,
+
+    /// <summary>
+    /// The number of defined transform sets.
+    /// </summary>
     AllSets
 }
diff --git a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformSize.cs b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformSize.cs
index 6ea115a73..7d1aa856c 100644
--- a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformSize.cs
+++ b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformSize.cs
@@ -8,26 +8,113 @@ namespace SixLabors.ImageSharp.Formats.Heif.Av1.Transform;
 /// </summary>
 internal enum Av1TransformSize : byte
 {
+    /// <summary>
+    /// A 4-by-4 transform block.
+    /// </summary>
     Size4x4 = 0,
+
+    /// <summary>
+    /// An 8-by-8 transform block.
+    /// </summary>
     Size8x8 = 1,
+
+    /// <summary>
+    /// A 16-by-16 transform block.
+    /// </summary>
     Size16x16 = 2,
+
+    /// <summary>
+    /// A 32-by-32 transform block.
+    /// </summary>
     Size32x32 = 3,
+
+    /// <summary>
+    /// A 64-by-64 transform block.
+    /// </summary>
     Size64x64 = 4,
+
+    /// <summary>
+    /// A 4-by-8 transform block.
+    /// </summary>
     Size4x8 = 5,
+
+    /// <summary>
+    /// An 8-by-4 transform block.
+    /// </summary>
     Size8x4 = 6,
+
+    /// <summary>
+    /// An 8-by-16 transform block.
+    /// </summary>
     Size8x16 = 7,
+
+    /// <summary>
+    /// A 16-by-8 transform block.
+    /// </summary>
     Size16x8 = 8,
+
+    /// <summary>
+    /// A 16-by-32 transform block.
+    /// </summary>
     Size16x32 = 9,
+
+    /// <summary>
+    /// A 32-by-16 transform block.
+    /// </summary>
     Size32x16 = 10,
+
+    /// <summary>
+    /// A 32-by-64 transform block.
+    /// </summary>
     Size32x64 = 11,
+
+    /// <summary>
+    /// A 64-by-32 transform block.
+    /// </summary>
     Size64x32 = 12,
+
+    /// <summary>
+    /// A 4-by-16 transform block.
+    /// </summary>
     Size4x16 = 13,
+
+    /// <summary>
+    /// A 16-by-4 transform block.
+    /// </summary>
     Size16x4 = 14,
+
+    /// <summary>
+    /// An 8-by-32 transform block.
+    /// </summary>
     Size8x32 = 15,
+
+    /// <summary>
+    /// A 32-by-8 transform block.
+    /// </summary>
     Size32x8 = 16,
+
+    /// <summary>
+    /// A 16-by-64 transform block.
+    /// </summary>
     Size16x64 = 17,
+
+    /// <summary>
+    /// A 64-by-16 transform block.
+    /// </summary>
     Size64x16 = 18,
+
+    /// <summary>
+    /// The number of defined transform-block sizes.
+    /// </summary>
     AllSizes = 19,
+
+    /// <summary>
+    /// The number of square transform-block sizes.
+    /// </summary>
     SquareSizes = Size4x8,
+
+    /// <summary>
+    /// No valid transform-block size.
+    /// </summary>
     Invalid = 255,
 }
diff --git a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformType.cs b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformType.cs
index 368c234c0..4d52b464b 100644
--- a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformType.cs
+++ b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformType.cs
@@ -27,17 +27,65 @@ internal enum Av1TransformType : byte
     /// ADST in both directions.
     /// </summary>
     AdstAdst,
+
+    /// <summary>
+    /// Flipped ADST vertically and DCT horizontally.
+    /// </summary>
     FlipAdstDct,
+
+    /// <summary>
+    /// DCT vertically and flipped ADST horizontally.
+    /// </summary>
     DctFlipAdst,
+
+    /// <summary>
+    /// Flipped ADST in both directions.
+    /// </summary>
     FlipAdstFlipAdst,
+
+    /// <summary>
+    /// ADST vertically and flipped ADST horizontally.
+    /// </summary>
     AdstFlipAdst,
+
+    /// <summary>
+    /// Flipped ADST vertically and ADST horizontally.
+    /// </summary>
     FlipAdstAdst,
+
+    /// <summary>
+    /// Identity transforms in both directions.
+    /// </summary>
     Identity,
+
+    /// <summary>
+    /// DCT vertically and identity horizontally.
+    /// </summary>
     VerticalDct,
+
+    /// <summary>
+    /// Identity vertically and DCT horizontally.
+    /// </summary>
     HorizontalDct,
+
+    /// <summary>
+    /// ADST vertically and identity horizontally.
+    /// </summary>
     VerticalAdst,
+
+    /// <summary>
+    /// Identity vertically and ADST horizontally.
+    /// </summary>
     HorizontalAdst,
+
+    /// <summary>
+    /// Flipped ADST vertically and identity horizontally.
+    /// </summary>
     VerticalFlipAdst,
+
+    /// <summary>
+    /// Identity vertically and flipped ADST horizontally.
+    /// </summary>
     HorizontalFlipAdst,
 
     /// <summary>
diff --git a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformType1d.cs b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformType1d.cs
index a47836789..16f80d943 100644
--- a/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformType1d.cs
+++ b/src/ImageSharp/Formats/Heif/Av1/Transform/Av1TransformType1d.cs
@@ -8,8 +8,23 @@ namespace SixLabors.ImageSharp.Formats.Heif.Av1.Transform;
 /// </summary>
 internal enum Av1TransformType1d
 {
+    /// <summary>
+    /// A discrete cosine transform.
+    /// </summary>
     Dct,
+
+    /// <summary>
+    /// An asymmetric discrete sine transform.
+    /// </summary>
     Adst,
+
+    /// <summary>
+    /// A flipped asymmetric discrete sine transform.
+    /// </summary>
     FlipAdst,
+
+    /// <summary>
+    /// An identity transform.
+    /// </summary>
     Identity
 }