[freetype2] GSoC-2017-kushal 5309ed9: Comments and README

[Kushal K S V S]

branch: GSoC-2017-kushal
commit 5309ed97ddfe3a51777df12c37d359f727e3e27c
Author: Kushal K S V S <address@hidden>
Commit: Kushal K S V S <address@hidden>

    Comments and README
---
 tests/README              | 90 +++++++++++++++++++++++++++--------------------
 tests/bitmap.c            |  2 +-
 tests/html/diff.html      |  1 +
 tests/html/scripts/top.js | 12 ++++---
 tests/html/styles/top.css | 20 ++++++++---
 tests/make_sprite.c       |  1 +
 tests/runme.sh            |  7 +++-
 7 files changed, 83 insertions(+), 50 deletions(-)

diff --git a/tests/README b/tests/README
index 91c4d34..43d00f8 100644
--- a/tests/README
+++ b/tests/README
@@ -1,3 +1,5 @@
+Test-Framework for FreeType's Rendering output.
+
 INSTRUCTIONS
 
 NOTE: One version of FreeType is referred as "base" version and the
@@ -6,73 +8,85 @@ NOTE: One version of FreeType is referred as "base" version 
and the
   1. Get the two versions ready
   -------------------------------------
 
-    Download an older version of FreeType (For example : 2.6.5)
-    ( This being the "base" version of the two)
-    Go to 'include/freetype/ftoption.h' and uncomment this line
+  Download an older version of FreeType (For example : 2.6.5)
+  ( This being the "base" version of the two)
+  Go to 'include/freetype/ftoption.h' and uncomment this line
 
-        #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING
+      #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING
   
   2. Compile the two versions 
   -------------------------------------     
-   Go to the "base" version's folder and compile the library.
+  Go to the "base" version's folder and compile the library.
 
       ./configure --enable-shared --disable-static
       make
 
-    Repeat step 2. for the "test" version as well.
+  Repeat step 2. for the "test" version as well.
 
  3. Compile the code
   -------------------------------------     
-    Return to this folder and make the binary
+  Return to this folder and make the binary
 
       make tests
 
  4. Run the executable
   ------------------------------------- 
 
-    => Set resolution in DPI by passing argument to variable FT_TEST_DPI.
+  => Set resolution in DPI by passing argument to variable FT_TEST_DPI.
 
-    => Set the Rendering mode by passing FT_TEST_RENDER_MODE.
-       FT_TEST_RENDER_MODE can take values 1. MONO
-                             2. AA
-                             3. RGB
-                             4. BGR
-                             5. VRGB
-                             6. VBGR
+  => Set the Rendering mode by passing FT_TEST_RENDER_MODE.
+     FT_TEST_RENDER_MODE can take values 1. MONO
+                           2. AA
+                           3. RGB
+                           4. BGR
+                           5. VRGB
+                           6. VBGR
 
-    => Set the variables FT_TEST_BASE_DLL and FT_TEST_TEST_DLL to
-       point to the libfreetype.so file of the base and the test
-       versions respectively.
+  => Set the variables FT_TEST_BASE_DLL and FT_TEST_TEST_DLL to
+     point to the libfreetype.so file of the base and the test
+     versions respectively.
 
-       By default, the folders '$(HOME)/base/' and '$(HOME)/test/'
-       folders are set for FT_TEST_BASE_DIR and FT_TEST_TEST_DIR
-       respectively. If FT_TEST_XXX_DLL isn't defined, these values
-       are taken to search for DLL files.
+     By default, the folders '$(HOME)/base/' and '$(HOME)/test/'
+     folders are set for FT_TEST_BASE_DIR and FT_TEST_TEST_DIR
+     respectively. If FT_TEST_XXX_DLL isn't defined, these values
+     are taken to search for DLL files.
 
-    => Set FT_TEST_FONT_FILE to the path to font files needed.
+  => Set FT_TEST_FONT_FILE to the path to font files needed.
 
-    => set FT_TEST_PT_SIZE as a number to denote the font size.
+  => set FT_TEST_PT_SIZE as a number to denote the font size.
 
-    EXAMPLE:    FT_TEST_BASE_DIR=/home/wl/kushal/base \
-          FT_TEST_TEST_DIR=/home/wl/kushal/test \
-          FT_TEST_DPI="72 96" \
-          FT_TEST_FONT_FILE="test.ttf" \
-          FT_TEST_RENDER_MODE="AA RGB" \
-          FT_TEST_PT_SIZE="16 20" \
-          ./runme.sh
-    ( The values in the above example denote the default values
-    for the variables )
+       EXAMPLE:  FT_TEST_BASE_DIR=/home/wl/kushal/base \
+                       FT_TEST_TEST_DIR=/home/wl/kushal/test \
+                       FT_TEST_DPI="72 96" \
+                       FT_TEST_FONT_FILE="test.ttf" \
+                       FT_TEST_RENDER_MODE="AA RGB" \
+                       FT_TEST_PT_SIZE="16 20" \
+                       ./runme.sh
+  ( The values in the above example denote the default values
+  for the variables )
 
   Open ./html/top.html for the web interface.
 ---------------------------------------------------------------------
 
 FEATURES
 
-  Creates an interactive web interface to visualize glyphs.
-  (html/top.html)
+  An interactive web interface to visualize glyphs.(html/top.html)
 
   View lists of glyphs in tables in the left iFrame accessed by
   selecting values from the drop-box.
+  ( The list consists of all the glyphs whose images rendered on
+  the two versions of the FreeType library are different. )
+
+  NOTE: If there is no visual difference in the two images, this
+        means that the dimensions of the images rendered aren't
+        the same for both the versions.
+        This is because the smaller images are aligned and padded
+        and then compared.
+
+  Subimages in the sprite sheet.
+    1.  'Base' version's rendering of the glyph.
+    2.  'Test' version's rendering of the glyph.
+    3.  'Base' version glyph as Gray
 
   By clicking on the Headers of the respective columns,they can be
   arranged (in increasing/decreasing order) based on
@@ -85,7 +99,5 @@ FEATURES
 
   Click on the Buttons below the iframe for the animations.
 
-  To be Added ...
-
-
-
+  To pause the animation, click and hold on the image.
+  
diff --git a/tests/bitmap.c b/tests/bitmap.c
index 8158af7..a8d1894 100644
--- a/tests/bitmap.c
+++ b/tests/bitmap.c
@@ -43,7 +43,7 @@ HASH_32 * Generate_Hash_x86_32( FT_Bitmap * bitmap,
 }
 
 /* This function takes the render mode argument and */
-/* returns the corresponding render_mode */
+/* returns the corresponding render_mode code */
 int Get_Render_Mode(const char* mode){
   /* Using -1 as the error code */
   int render_mode = -1;
diff --git a/tests/html/diff.html b/tests/html/diff.html
index 0702fa3..ec184cd 100644
--- a/tests/html/diff.html
+++ b/tests/html/diff.html
@@ -5,6 +5,7 @@
        <script type="text/javascript" src ="scripts/top.js" ></script>
        <link rel="stylesheet" type="text/css" href="styles/top.css">
 </head>
+<!--  Division used for animation -->
   <div id="animation" class="animation"></div><br>
 </body>
 </html>
diff --git a/tests/html/scripts/top.js b/tests/html/scripts/top.js
index e77372e..072736c 100644
--- a/tests/html/scripts/top.js
+++ b/tests/html/scripts/top.js
@@ -1,3 +1,5 @@
+// If any value in the 'select' list(s) changes, the corresponding
+// HTML document is loaded in frame_1.
 function change() {
        var dpi = document.getElementById('dpi').value;
        var font = document.getElementById('font').value;
@@ -7,7 +9,7 @@ function change() {
   var string = "pages/"+dpi+"/"+font+"/"+mode+"/"+size+"/index.html";
   frame.src = string;
 }
-
+// Function to sort the columns of the table when you click on the header
 var people, asc1 = 1,asc2 = 1,asc3 = 1;
 
 function sort_t(tbody, col, asc){
@@ -30,7 +32,9 @@ function sort_t(tbody, col, asc){
   }
   tbody.innerHTML = "<tr>"+arr.join("</tr><tr>")+"</tr>";
 }
-
+// Function to change the source of the background image in the iframe
+// (frame_2). This function also fits the division according to the
+// size of the iframe such that the background image fits in the frame.
 function frame_2_source(image){
   var path = "url("+image.src+")";
 
@@ -76,7 +80,7 @@ function frame_2_source(image){
   div.style.width= div_w/4 + "px";
   div.style.height= div_h + "px";
 }
-
+// Functions to trigger the corresponding animations.
 function class_one_two(){
   var div = frame_2.document.getElementById('animation');
   div.className = 'animation one_two';
@@ -91,7 +95,7 @@ function class_one_four(){
   var div = frame_2.document.getElementById('animation');
   div.className = 'animation one_four';
 }
-
+// Functions for the 'Go to Top button'
 // When the user scrolls down 20px from the top of the document, show the 
button
 window.onscroll = function() {scrollFunction()};
 
diff --git a/tests/html/styles/top.css b/tests/html/styles/top.css
index 22c9059..a41fbd5 100644
--- a/tests/html/styles/top.css
+++ b/tests/html/styles/top.css
@@ -1,6 +1,8 @@
+/* Font for the whole document */
 * {
   font-family: "Courier New", Courier, monospace;
 }
+/* Sprite image in the table */
 #sprite { 
     image-rendering: optimizeSpeed;             /* STOP SMOOTHING, GIVE ME 
SPEED  */
     image-rendering: -moz-crisp-edges;          /* Firefox                     
   */
@@ -12,6 +14,7 @@
     width: 100%;
     height: auto;
 }
+/* Table style for the list view */
 table {
   border-collapse: collapse;
   border: none;
@@ -30,10 +33,12 @@ th {
   background-color: #C8C8C8;
   cursor: pointer;
 }
+/* Image column in a row */
 #image_row{
   width: 50%;
   height: auto;
 }
+/* Go to top button */
 #myBtn {
   display: none;
   position: fixed;
@@ -47,7 +52,7 @@ th {
   color: white;
 }
 
-/*Top Page styling begins*/
+/* Top Page styling begins */
 #frame_1{
   width:49%;
   height:500px;
@@ -58,6 +63,7 @@ th {
   height:500px;
   align-self: left;
 }
+/* Animation select buttons*/
 #select_animation{
   margin-left: 50%;
 }
@@ -65,6 +71,7 @@ th {
   font-size: 16px;
   text-align: left;
 }
+/* Animation div on the right iframe */
 .animation {
   image-rendering: optimizeSpeed;
   image-rendering: -moz-crisp-edges;
@@ -79,7 +86,7 @@ th {
   background: url("");
   background-repeat: no-repeat;
   background-size: cover;
-
+  /* Nominal Width on load */
   width: 120px;
   height: 130px;
 }
@@ -88,6 +95,7 @@ th {
   -webkit-animation-play-state: paused;
   animation-play-state: paused;
 }
+/* Transition between 1st and the 2nd sub-image */
 .one_two {
     -webkit-animation: one_two 2s steps(2) infinite;
        -moz-animation: one_two 2s steps(2) infinite;
@@ -95,6 +103,7 @@ th {
          -o-animation: one_two 2s steps(2) infinite;
             animation: one_two 2s steps(2) infinite;
 }
+/* Transition between 1st and the 2nd sub-image */
 .one_three {
     -webkit-animation: one_three 2s steps(2) infinite;
        -moz-animation: one_three 2s steps(2) infinite;
@@ -102,6 +111,7 @@ th {
          -o-animation: one_three 2s steps(2) infinite;
             animation: one_three 2s steps(2) infinite;
 }
+/* Transition between 1st and the 2nd sub-image */
 .one_four {
     -webkit-animation: one_four 2s steps(2) infinite;
        -moz-animation: one_four 2s steps(2) infinite;
@@ -111,15 +121,15 @@ th {
 }
 @-webkit-keyframes one_two {
    from { background-position:      0px; }
-     to { background-position:   66.66%; }
+     to { background-position:   66.66%; } /* Goes to 2nd sub-image */
 }
 @-webkit-keyframes one_three {
    from { background-position:      0px; }
-     to { background-position:  133.33%; }
+     to { background-position:  133.33%; } /* Goes to 3rd sub-image */
 }
 @-webkit-keyframes one_four {
    from { background-position:      0px; }
-     to { background-position:     200%; }
+     to { background-position:     200%; } /* Goes to 4rd sub-image */
 }
 
 @-moz-keyframes one_two {
diff --git a/tests/make_sprite.c b/tests/make_sprite.c
index b85c2b8..ac454e0 100644
--- a/tests/make_sprite.c
+++ b/tests/make_sprite.c
@@ -4,6 +4,7 @@ int main(int argc, char const *argv[])
 {
   if(argc != 7)
   {
+    /* Not needed coz it is automated using runme.sh */
     printf("Not enough arguments. Refer README\n");
     return 0;
   }
diff --git a/tests/runme.sh b/tests/runme.sh
index 8c9ed98..7c929fc 100755
--- a/tests/runme.sh
+++ b/tests/runme.sh
@@ -1,8 +1,9 @@
 #! /bin/bash
-
+# Remove all the previous files.
 rm -rf ./html/pages
 rm -f ./html/top.html
 #####################################################################
+# Setting Default values for the variables if not defined.
 FT_TEST_DPI=${FT_TEST_DPI:-72 96}
 FT_TEST_FONT_FILE=${FT_TEST_FONT_FILE:-test.ttf}
 FT_TEST_RENDER_MODE=${FT_TEST_RENDER_MODE:-AA RGB}
@@ -17,6 +18,7 @@ 
FT_TEST_TEST_DLL=${FT_TEST_TEST_DLL:-$FT_TEST_TEST_DIR/objs/.libs/libfreetype.so
 mkdir ./html/pages
 touch ./html/top.html
 #####################################################################
+# Generating top.html file
 echo "
 <!DOCTYPE html>
   <head>
@@ -33,6 +35,7 @@ echo "
       <iframe id=\"frame_1\" name=\"frame_1\" src=\"\" ></iframe>
       <iframe id=\"frame_2\" name=\"frame_2\" src=\"diff.html\" 
></iframe>">./html/top.html
 #####################################################################
+# Filling html/top.html file with links to all the index.html files.
 for i in $FT_TEST_DPI; do
   mkdir ./html/pages/$i
   for j in $FT_TEST_FONT_FILE; do
@@ -48,6 +51,7 @@ for i in $FT_TEST_DPI; do
   done
 done
 #####################################################################
+# Buttons for animation selection
 echo '<div id="select_animation">
         <button onclick="class_one_two()">One-Two</button>
         <button onclick="class_one_three()">One-Three</button>
@@ -55,6 +59,7 @@ echo '<div id="select_animation">
       </div>
       <div class="select">'>>./html/top.html
 #####################################################################
+# Populating the selection lists with options
 echo '<label>DPI&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp:<select name="dpi" 
id="dpi" onchange="change()">'>>./html/top.html
 for i in $FT_TEST_DPI; do
   echo "  <option value= $i > $i </option>">>./html/top.html