From bb21f1762aee4a7f3890b0daf524a44e7db1c565 Mon Sep 17 00:00:00 2001
From: Guillaume Poirier <gpoirier@mplayerhq.hu>
Date: Sat, 31 Mar 2007 22:39:43 +0000
Subject: [PATCH] Add doxy comments, based on Loren's explanations posted here:
 Date: Mar 30, 2007 9:00 PM Subject: Re: [Ffmpeg-devel] Motion Estimation in
 snow.c for Waevelet encoded frames (DWT)

Originally committed as revision 8579 to svn://svn.ffmpeg.org/ffmpeg/trunk
---
 libavcodec/motion_est.c          |  3 +++
 libavcodec/motion_est_template.c | 15 +++++++++++++--
 libavcodec/mpegvideo.h           |  6 +++++-
 3 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/libavcodec/motion_est.c b/libavcodec/motion_est.c
index 2e8b1d3..cb9731c 100644
--- a/libavcodec/motion_est.c
+++ b/libavcodec/motion_est.c
@@ -103,6 +103,9 @@ static int get_flags(MotionEstContext *c, int direct, int chroma){
            + (chroma ? FLAG_CHROMA : 0);
 }
 
+/*! \brief compares two blocks, which may be full macroblocks or may be
+    partitions thereof.
+ */
 static av_always_inline int cmp(MpegEncContext *s, const int x, const int y, const int subx, const int suby,
                       const int size, const int h, int ref_index, int src_index,
                       me_cmp_func cmp_func, me_cmp_func chroma_cmp_func, const int flags){
diff --git a/libavcodec/motion_est_template.c b/libavcodec/motion_est_template.c
index 897c08e..e014250 100644
--- a/libavcodec/motion_est_template.c
+++ b/libavcodec/motion_est_template.c
@@ -991,13 +991,24 @@ static av_always_inline int diamond_search(MpegEncContext * s, int *best, int dm
         return   var_diamond_search(s, best, dmin, src_index, ref_index, penalty_factor, size, h, flags);
 }
 
+/*!
+   \param P[10][2] a list of candidate mvs to check before starting the
+   iterative search. If one of the candidates is close to the optimal mv, then
+   it takes fewer iterations. And it increases the chance that we find the
+   optimal mv.
+ */
 static av_always_inline int epzs_motion_search_internal(MpegEncContext * s, int *mx_ptr, int *my_ptr,
                              int P[10][2], int src_index, int ref_index, int16_t (*last_mv)[2],
                              int ref_mv_scale, int flags, int size, int h)
 {
     MotionEstContext * const c= &s->me;
-    int best[2]={0, 0};
-    int d, dmin;
+    int best[2]={0, 0};      /*!< x and y coordinates of the best motion vector.
+                               i.e. the difference between the position of the
+                               block current being encoded and the position of
+                               the block chosen to predict it from. */
+    int d;                   ///< the score (cmp + penalty) of any given mv
+    int dmin;                /*!< the best value of d, i.e. the score
+                               corresponding to the mv stored in best[]. */
     int map_generation;
     int penalty_factor;
     const int ref_mv_stride= s->mb_stride; //pass as arg  FIXME
diff --git a/libavcodec/mpegvideo.h b/libavcodec/mpegvideo.h
index fd89f38..80e0f90 100644
--- a/libavcodec/mpegvideo.h
+++ b/libavcodec/mpegvideo.h
@@ -162,7 +162,11 @@ typedef struct MotionEstContext{
     uint32_t *score_map;               ///< map to store the scores
     int map_generation;
     int pre_penalty_factor;
-    int penalty_factor;
+    int penalty_factor;                /*!< an estimate of the bits required to
+                                        code a given mv value, e.g. (1,0) takes
+                                        more bits than (0,0). We have to
+                                        estimate whether any reduction in
+                                        residual is worth the extra bits. */
     int sub_penalty_factor;
     int mb_penalty_factor;
     int flags;
-- 
2.7.4