Documentation for CommonQuantParams

Also, a few renames for clarity.

BUG=aomedia:2610

Change-Id: Id5e3096d8493f57b606bacbc428cde926daedcc7

av1/common/av1_common_int.h

diff --git a/av1/common/av1_common_int.h b/av1/common/av1_common_int.h
index 9232755..3b8cb13 100644
--- a/av1/common/av1_common_int.h
+++ b/av1/common/av1_common_int.h
@@ -419,19 +419,28 @@
                     int height);
 };
 
-// Parameters related to quantization.
+// Parameters related to quantization at the frame level.
 typedef struct CommonQuantParams CommonQuantParams;
 struct CommonQuantParams {
-  // Base qIndex of the frame in the range 0 to 255.
-  // The qindex per block may have a delta from this: see 'delta_q_info' below.
+  // Base qindex of the frame in the range 0 to 255.
   int base_qindex;
 
+  // Delta of qindex (from base_qindex) for Y plane DC coefficient.
+  // Note: y_ac_delta_q is implicitly 0.
   int y_dc_delta_q;
+
+  // Delta of qindex (from base_qindex) for U plane DC and AC coefficients.
   int u_dc_delta_q;
   int v_dc_delta_q;
+
+  // Delta of qindex (from base_qindex) for V plane DC and AC coefficients.
+  // Same as those for U plane if cm->seq_params.separate_uv_delta_q == 0.
   int u_ac_delta_q;
   int v_ac_delta_q;
 
+  // Note: The qindex per superblock may have a delta from the qindex obtained
+  // at frame level from parameters above, based on 'cm->delta_q_info'.
+
   // The dequantizers below are true dequantizers used only in the
   // dequantization process.  They have the same coefficient
   // shift/scale as TX.
@@ -448,10 +457,14 @@
   const qm_val_t *u_iqmatrix[MAX_SEGMENTS][TX_SIZES_ALL];
   const qm_val_t *v_iqmatrix[MAX_SEGMENTS][TX_SIZES_ALL];
 
-  int using_qmatrix;
-  int qm_y;
-  int qm_u;
-  int qm_v;
+  // Flag indicating whether quantization matrices are being used:
+  //  - If true, qm_level_y, qm_level_u and qm_level_v indicate the level
+  //    indices to be used to access appropriate global quant matrix tables.
+  //  - If false, we implicitly use level index 'NUM_QM_LEVELS - 1'.
+  bool using_qmatrix;
+  int qmatrix_level_y;
+  int qmatrix_level_u;
+  int qmatrix_level_v;
 };
 
 // Context used for transmitting various symbols in the bistream.

av1/common/quant_common.c

diff --git a/av1/common/quant_common.c b/av1/common/quant_common.c
index 9b967fe..e976752 100644
--- a/av1/common/quant_common.c
+++ b/av1/common/quant_common.c
@@ -226,8 +226,8 @@
 }
 
 bool av1_use_qmatrix(const CommonQuantParams *quant_params,
-                     const MACROBLOCKD *const xd, int segment_id) {
-  // True if we are using Q matrix and this is not a lossless segment.
+                     const struct macroblockd *xd, int segment_id) {
+  // True if explicit Q matrix levels and this is not a lossless segment.
   return quant_params->using_qmatrix && !xd->lossless[segment_id];
 }
 

av1/common/quant_common.h

diff --git a/av1/common/quant_common.h b/av1/common/quant_common.h
index fb27326..9c30204 100644
--- a/av1/common/quant_common.h
+++ b/av1/common/quant_common.h
@@ -47,7 +47,7 @@
 int av1_get_qindex(const struct segmentation *seg, int segment_id,
                    int base_qindex);
 
-// Returns true if we should use quantization matrix.
+// Returns true if we are using quantization matrix.
 bool av1_use_qmatrix(const struct CommonQuantParams *quant_params,
                      const struct macroblockd *xd, int segment_id);
 

av1/decoder/decodeframe.c

diff --git a/av1/decoder/decodeframe.c b/av1/decoder/decodeframe.c
index 0dc539f..3634dec 100644
--- a/av1/decoder/decodeframe.c
+++ b/av1/decoder/decodeframe.c
@@ -2064,16 +2064,16 @@
   }
   quant_params->using_qmatrix = aom_rb_read_bit(rb);
   if (quant_params->using_qmatrix) {
-    quant_params->qm_y = aom_rb_read_literal(rb, QM_LEVEL_BITS);
-    quant_params->qm_u = aom_rb_read_literal(rb, QM_LEVEL_BITS);
+    quant_params->qmatrix_level_y = aom_rb_read_literal(rb, QM_LEVEL_BITS);
+    quant_params->qmatrix_level_u = aom_rb_read_literal(rb, QM_LEVEL_BITS);
     if (!separate_uv_delta_q)
-      quant_params->qm_v = quant_params->qm_u;
+      quant_params->qmatrix_level_v = quant_params->qmatrix_level_u;
     else
-      quant_params->qm_v = aom_rb_read_literal(rb, QM_LEVEL_BITS);
+      quant_params->qmatrix_level_v = aom_rb_read_literal(rb, QM_LEVEL_BITS);
   } else {
-    quant_params->qm_y = 0;
-    quant_params->qm_u = 0;
-    quant_params->qm_v = 0;
+    quant_params->qmatrix_level_y = 0;
+    quant_params->qmatrix_level_u = 0;
+    quant_params->qmatrix_level_v = 0;
   }
 }
 
@@ -2101,17 +2101,20 @@
     const int use_qmatrix = av1_use_qmatrix(quant_params, xd, i);
     // NB: depends on base index so there is only 1 set per frame
     // No quant weighting when lossless or signalled not using QM
-    const int qmlevel_y = use_qmatrix ? quant_params->qm_y : NUM_QM_LEVELS - 1;
+    const int qmlevel_y =
+        use_qmatrix ? quant_params->qmatrix_level_y : NUM_QM_LEVELS - 1;
     for (int j = 0; j < TX_SIZES_ALL; ++j) {
       quant_params->y_iqmatrix[i][j] =
           av1_iqmatrix(quant_params, qmlevel_y, AOM_PLANE_Y, j);
     }
-    const int qmlevel_u = use_qmatrix ? quant_params->qm_u : NUM_QM_LEVELS - 1;
+    const int qmlevel_u =
+        use_qmatrix ? quant_params->qmatrix_level_u : NUM_QM_LEVELS - 1;
     for (int j = 0; j < TX_SIZES_ALL; ++j) {
       quant_params->u_iqmatrix[i][j] =
           av1_iqmatrix(quant_params, qmlevel_u, AOM_PLANE_U, j);
     }
-    const int qmlevel_v = use_qmatrix ? quant_params->qm_v : NUM_QM_LEVELS - 1;
+    const int qmlevel_v =
+        use_qmatrix ? quant_params->qmatrix_level_v : NUM_QM_LEVELS - 1;
     for (int j = 0; j < TX_SIZES_ALL; ++j) {
       quant_params->v_iqmatrix[i][j] =
           av1_iqmatrix(quant_params, qmlevel_v, AOM_PLANE_V, j);

av1/encoder/av1_quantize.c

diff --git a/av1/encoder/av1_quantize.c b/av1/encoder/av1_quantize.c
index 995c90b..789590f 100644
--- a/av1/encoder/av1_quantize.c
+++ b/av1/encoder/av1_quantize.c
@@ -677,7 +677,8 @@
   const int use_qmatrix = av1_use_qmatrix(quant_params, xd, segment_id);
 
   // Y
-  const int qmlevel_y = use_qmatrix ? quant_params->qm_y : NUM_QM_LEVELS - 1;
+  const int qmlevel_y =
+      use_qmatrix ? quant_params->qmatrix_level_y : NUM_QM_LEVELS - 1;
   x->plane[0].quant_QTX = quants->y_quant[qindex];
   x->plane[0].quant_fp_QTX = quants->y_quant_fp[qindex];
   x->plane[0].round_fp_QTX = quants->y_round_fp[qindex];
@@ -693,7 +694,8 @@
          sizeof(quant_params->giqmatrix[qmlevel_y][0]));
 
   // U
-  const int qmlevel_u = use_qmatrix ? quant_params->qm_u : NUM_QM_LEVELS - 1;
+  const int qmlevel_u =
+      use_qmatrix ? quant_params->qmatrix_level_u : NUM_QM_LEVELS - 1;
   x->plane[1].quant_QTX = quants->u_quant[qindex];
   x->plane[1].quant_fp_QTX = quants->u_quant_fp[qindex];
   x->plane[1].round_fp_QTX = quants->u_round_fp[qindex];
@@ -708,7 +710,8 @@
          quant_params->giqmatrix[qmlevel_u][1],
          sizeof(quant_params->giqmatrix[qmlevel_u][1]));
   // V
-  const int qmlevel_v = use_qmatrix ? quant_params->qm_v : NUM_QM_LEVELS - 1;
+  const int qmlevel_v =
+      use_qmatrix ? quant_params->qmatrix_level_v : NUM_QM_LEVELS - 1;
   x->plane[2].quant_QTX = quants->v_quant[qindex];
   x->plane[2].quant_fp_QTX = quants->v_quant_fp[qindex];
   x->plane[2].round_fp_QTX = quants->v_round_fp[qindex];
@@ -747,16 +750,16 @@
   quant_params->u_ac_delta_q = 0;
   quant_params->v_dc_delta_q = 0;
   quant_params->v_ac_delta_q = 0;
-  quant_params->qm_y = aom_get_qmlevel(quant_params->base_qindex,
-                                       cpi->min_qmlevel, cpi->max_qmlevel);
-  quant_params->qm_u =
+  quant_params->qmatrix_level_y = aom_get_qmlevel(
+      quant_params->base_qindex, cpi->min_qmlevel, cpi->max_qmlevel);
+  quant_params->qmatrix_level_u =
       aom_get_qmlevel(quant_params->base_qindex + quant_params->u_ac_delta_q,
                       cpi->min_qmlevel, cpi->max_qmlevel);
 
   if (!cm->seq_params.separate_uv_delta_q)
-    quant_params->qm_v = quant_params->qm_u;
+    quant_params->qmatrix_level_v = quant_params->qmatrix_level_u;
   else
-    quant_params->qm_v =
+    quant_params->qmatrix_level_v =
         aom_get_qmlevel(quant_params->base_qindex + quant_params->v_ac_delta_q,
                         cpi->min_qmlevel, cpi->max_qmlevel);
 }

av1/encoder/bitstream.c

diff --git a/av1/encoder/bitstream.c b/av1/encoder/bitstream.c
index 396731a..324ce4c 100644
--- a/av1/encoder/bitstream.c
+++ b/av1/encoder/bitstream.c
@@ -2045,12 +2045,12 @@
   }
   aom_wb_write_bit(wb, quant_params->using_qmatrix);
   if (quant_params->using_qmatrix) {
-    aom_wb_write_literal(wb, quant_params->qm_y, QM_LEVEL_BITS);
-    aom_wb_write_literal(wb, quant_params->qm_u, QM_LEVEL_BITS);
+    aom_wb_write_literal(wb, quant_params->qmatrix_level_y, QM_LEVEL_BITS);
+    aom_wb_write_literal(wb, quant_params->qmatrix_level_u, QM_LEVEL_BITS);
     if (!separate_uv_delta_q)
-      assert(quant_params->qm_u == quant_params->qm_v);
+      assert(quant_params->qmatrix_level_u == quant_params->qmatrix_level_v);
     else
-      aom_wb_write_literal(wb, quant_params->qm_v, QM_LEVEL_BITS);
+      aom_wb_write_literal(wb, quant_params->qmatrix_level_v, QM_LEVEL_BITS);
   }
 }