aom: Document frame size to copy in loop filter

From 151cfc83f08df5a94d059d233f2228d5afcaf462 Mon Sep 17 00:00:00 2001
From: Cheng Chen <[EMAIL REDACTED]>
Date: Mon, 5 Feb 2024 13:52:15 -0800
Subject: [PATCH] Document frame size to copy in loop filter

In AV1, loop filter applies to the whole frame according to the
aligned with and height.

Comments are added to resolve a TODO and make it clear to understand
the filtering process of loop filter and super res.

Comments are also added in the buffer struct for y_width and
y_crop_width.

Change-Id: Idd80603f5b840421237d3edd4829212f585841d9
---
 aom_scale/generic/yv12extend.c |  3 ---
 aom_scale/yv12config.h         | 11 +++++++++++
 av1/encoder/picklpf.c          | 16 +++++++++++++---
 3 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/aom_scale/generic/yv12extend.c b/aom_scale/generic/yv12extend.c
index d19a2626f0..727a99e053 100644
--- a/aom_scale/generic/yv12extend.c
+++ b/aom_scale/generic/yv12extend.c
@@ -301,9 +301,6 @@ void aom_yv12_copy_frame_c(const YV12_BUFFER_CONFIG *src_bc,
   aom_yv12_extend_frame_borders_c(dst_bc, num_planes);
 }
 
-// TODO(marpan/wtc): Look into why use_crop can't always be 1.
-// Some tests are currently failing if 1 is used in
-// av1/encoder/picklpf.c (function yv12_copy_plane).
 void aom_yv12_copy_y_c(const YV12_BUFFER_CONFIG *src_ybc,
                        YV12_BUFFER_CONFIG *dst_ybc, int use_crop) {
   int row;
diff --git a/aom_scale/yv12config.h b/aom_scale/yv12config.h
index f192a3032e..ebc318b9a7 100644
--- a/aom_scale/yv12config.h
+++ b/aom_scale/yv12config.h
@@ -45,18 +45,29 @@ typedef struct yv12_buffer_config {
   /*!\cond */
   union {
     struct {
+      // The aligned frame width of luma.
+      // It is aligned to a multiple of 8:
+      // y_width = (y_crop_width + 7) & ~7
       int y_width;
+      // The aligned frame width of chroma.
+      // uv_width = y_width >> subsampling_x
       int uv_width;
     };
     int widths[2];
   };
   union {
     struct {
+      // The aligned frame height of luma.
+      // It is aligned to a multiple of 8:
+      // y_height = (y_crop_height + 7) & ~7
       int y_height;
+      // The aligned frame height of chroma.
+      // uv_height = y_height >> subsampling_y
       int uv_height;
     };
     int heights[2];
   };
+  // The frame size en/decoded by AV1
   union {
     struct {
       int y_crop_width;
diff --git a/av1/encoder/picklpf.c b/av1/encoder/picklpf.c
index ca64edb6da..d06215547c 100644
--- a/av1/encoder/picklpf.c
+++ b/av1/encoder/picklpf.c
@@ -27,9 +27,19 @@
 #include "av1/encoder/encoder.h"
 #include "av1/encoder/picklpf.h"
 
-// TODO(marpan/wtc): Look into why crop_width/height can't be used
-// (use_crop set to 1) in aom_yv12_copy_y/u/v below. Some tests
-// are failing if this is done.
+// AV1 loop filter applies to the whole frame accoring to mi_rows and mi_cols,
+// which are calculated based on aligned width and aligned height,
+// In addition, if super res is enabled, it copies the whole frame
+// according to the alighed with and height (av1_superres_upscale()).
+// So we need to copy the whole filtered region, instead of the cropped region.
+// For example, input image size is: 160x90.
+// Then src->y_crop_width = 160, src->y_crop_height = 90.
+// The aligned frame size is: src->y_width = 160, src->y_height = 96.
+// AV1 aligns frame size to a multiple of 8, if there is
+// chroma subsampling, it is able to ensure the chroma is also
+// an integer number of mi units. mi unit is 4x4, 8 = 4 * 2, and 2 luma mi
+// units correspond to 1 chroma mi unit if there is subsampling.
+// See: aom_realloc_frame_buffer() in yv12config.c.
 static void yv12_copy_plane(const YV12_BUFFER_CONFIG *src_bc,
                             YV12_BUFFER_CONFIG *dst_bc, int plane) {
   switch (plane) {