[freetype2] GSoC-2023-Ahmet a6c2517e6: doc

[Werner Lemberg]

branch: GSoC-2023-Ahmet
commit a6c2517e68c852d8f7a6f7d239edffc83ed03a84
Author: goksu <25721443+goeksu@users.noreply.github.com>
Commit: goksu <25721443+goeksu@users.noreply.github.com>

    doc
---
 builds/testing.mk                   | 38 ++++++++++++++++++++++---------
 src/tools/ftbench/README            | 45 +++++++++++++++++++++++++++++++++++++
 src/tools/ftbench/fonts/tool/sub.sh |  1 +
 src/tools/ftbench/ftbench.c         | 10 ++++++---
 4 files changed, 81 insertions(+), 13 deletions(-)

diff --git a/builds/testing.mk b/builds/testing.mk
index c4d9ec5fc..a600bb08e 100644
--- a/builds/testing.mk
+++ b/builds/testing.mk
@@ -1,21 +1,30 @@
-# Variables
+# Define a few important variables.
 FTBENCH_DIR = $(TOP_DIR)/src/tools/ftbench
 FTBENCH_SRC = $(FTBENCH_DIR)/ftbench.c
 FTBENCH_OBJ = $(OBJ_DIR)/bench.$(SO)
 FTBENCH_BIN = $(OBJ_DIR)/bench$E
-FTBENCH_FLAG ?= -c 1000 -w 100
 INCLUDES = $(TOP_DIR)/include
 FONTS = $(wildcard $(FTBENCH_DIR)/fonts/*.ttf)
+
+
+# Define objects.
 BASELINE_DIR = $(OBJ_DIR)/baseline/
 BENCHMARK_DIR = $(OBJ_DIR)/benchmark/
-BASELINE = $(addprefix $(BASELINE_DIR), $(notdir $(FONTS:.ttf=.txt)))
-BENCHMARK = $(addprefix $(BENCHMARK_DIR), $(notdir $(FONTS:.ttf=.txt)))
 BASELINE_INFO = $(BASELINE_DIR)info.txt
 BENCHMARK_INFO = $(BENCHMARK_DIR)info.txt
 HTMLCREATOR_SRC = $(FTBENCH_DIR)/src/tohtml.py
 HTMLCREATOR = $(OBJ_DIR)/tohtml.py
 HTMLFILE = $(OBJ_DIR)/benchmark.html
 
+# Define flags by default
+FTBENCH_FLAG ?= -c 1000 -w 100
+
+
+# Define test fonts all in the fonts folder.
+BASELINE = $(addprefix $(BASELINE_DIR), $(notdir $(FONTS:.ttf=.txt)))
+BENCHMARK = $(addprefix $(BENCHMARK_DIR), $(notdir $(FONTS:.ttf=.txt)))
+
+
 FT_INCLUDES := $(OBJ_BUILD) \
                  $(INCLUDES) 
 
@@ -23,12 +32,9 @@ COMPILE = $(CC) $(ANSIFLAGS) \
                   $(INCLUDES:%=$I%) \
                   $(CFLAGS)
 
-ifeq ($(PLATFORM),unix)
-    ifdef DEVEL_DIR
-      PLATFORM := unixdev
-    endif
-endif
-
+# Enable C99 for gcc to avoid warnings.
+# Note that clang++ aborts with an error if we use `-std=C99',
+# so check for `++' in $(CC) also.
 ifneq ($(findstring -pedantic,$(COMPILE)),)
     ifeq ($(findstring ++,$(CC)),)
       COMPILE += -std=c99
@@ -38,12 +44,17 @@ endif
 FTLIB := $(LIB_DIR)/$(LIBRARY).$A
 
 ifeq ($(PLATFORM),unix)
+       # `LDFLAGS` comes from the `configure` script (via FreeType's
+       # `builds/unix/unix-cc.mk`), holding all linker flags necessary to
+       # link the FreeType library.
     LINK_CMD    = $(LIBTOOL) --mode=link $(CCraw) \
                   $(subst /,$(COMPILER_SEP),$(LDFLAGS))
     LINK_LIBS   = $(subst /,$(COMPILER_SEP),$(FTLIB) $(EFENCE)) 
 else
     LINK_CMD = $(CC) $(subst /,$(COMPILER_SEP),$(LDFLAGS))
     ifeq ($(PLATFORM),unixdev)
+               # For the pure `make` call (without using `configure`) we have 
to add
+               # all needed libraries manually.
       LINK_LIBS := $(subst /,$(COMPILER_SEP),$(FTLIB) $(EFENCE)) \
                    -lm -lrt -lz -lbz2 -lpthread
       LINK_LIBS += $(shell pkg-config --libs libpng)
@@ -55,10 +66,15 @@ else
     endif
 endif
 
+# Only on Windows we might fall back on GDI+ for PNG saving
 ifeq ($(OS),Windows_NT)
     LINK_LIBS += -lgdiplus
 endif
 
+####################################################################
+#
+# POSIX TERMIOS: Do not define if you use OLD U*ix like 4.2BSD.
+#
 ifeq ($(PLATFORM),unix)
     EXTRAFLAGS = $DUNIX $DHAVE_POSIX_TERMIOS
 endif
@@ -73,6 +89,7 @@ INCLUDES := $(subst /,$(COMPILER_SEP),$(FT_INCLUDES))
 $(BASELINE_DIR) $(BENCHMARK_DIR):
        @mkdir -p $@
 
+# Create ftbench object
 $(FTBENCH_OBJ): $(FTBENCH_SRC) 
        @$(COMPILE) $T$(subst /,$(COMPILER_SEP),$@ $<) $(EXTRAFLAGS)
        @echo "Object created."
@@ -83,6 +100,7 @@ $(FTBENCH_BIN): $(FTBENCH_OBJ)
        @$(LINK_CMD) $T$(subst /,$(COMPILER_SEP),$@ $<) $(LINK_LIBS)
        @echo "Built."
 
+# Copy tohtml.py into objs folder
 .PHONY: copy-html-script
 copy-html-script:
        @cp $(HTMLCREATOR_SRC) $(OBJ_DIR)
diff --git a/src/tools/ftbench/README b/src/tools/ftbench/README
new file mode 100644
index 000000000..db0911a64
--- /dev/null
+++ b/src/tools/ftbench/README
@@ -0,0 +1,45 @@
+ftbench
+========
+
+ftbench is a program designed to run FreeType benchmarks. It accepts various 
options and a font name to run specific tests on font rendering operations.
+
+Each test may involve tasks such as:
+
+. Initializing the library
+. Opening the font file
+. Loading and optionally rendering each glyph
+. Comparing results with cached versions (if available)
+. Configuring specific charmap indices, load flags, etc.
+
+Usage is time-limited or can be explicitly set to use a maximum number of 
iterations per test.
+
+
+Command line options
+--------------------
+
+-C      Compare with cached version (if available).
+-c N    Use at most N iterations for each test (0 means time-limited).
+-e E    Set specific charmap index E.
+-f L    Use hex number L as load flags (see FT_LOAD_XXX'). -H NAME  Use PS 
hinting engine NAME (default is adobe').
+-I VER  Use TT interpreter version VER (default is version 40).
+-i I-J  Forward or reverse range of glyph indices to use.
+-l N    Set LCD filter to N (default is 0: none).
+-m M    Set maximum cache size to M KiByte (default is 1024).
+-p      Preload font file in memory.
+-r N    Set render mode to N (default is 0: normal).
+-s S    Use S ppem as face size (default is 10ppem).
+-t T    Use at most T seconds per bench (default is 2).
+-w N    Use N iterations for warming up before each test.
+
+-b      tests Perform chosen tests (default is all).
+-v      Show version.
+
+Compilation
+-----------
+
+make baseline   To create a baseline for your benchmarks, use the `make 
baseline` command. This will compile the ftbench.c and create a set of baseline 
measurements in the objs/baseline/ directory.
+
+make benchmark  To run the benchmarks, use the `make benchmark` command. The 
results will be stored in the objs/benchmark/ directory. It will copy tohtml.py 
script to objs/ and generate a html file.
+
+make clean-benchmark    To remove all generated benchmark files and clean the 
objs directory, use the `make clean-benchmark` command.
+
diff --git a/src/tools/ftbench/fonts/tool/sub.sh 
b/src/tools/ftbench/fonts/tool/sub.sh
index 3b114cce8..3721b0fb4 100644
--- a/src/tools/ftbench/fonts/tool/sub.sh
+++ b/src/tools/ftbench/fonts/tool/sub.sh
@@ -1,4 +1,5 @@
 #!/bin/bash
+# This tool is to subset fonts.
 
 # Define the Unicode range
 unicodes="U+0021-007E"
diff --git a/src/tools/ftbench/ftbench.c b/src/tools/ftbench/ftbench.c
index 0d5078b45..93312e3a4 100644
--- a/src/tools/ftbench/ftbench.c
+++ b/src/tools/ftbench/ftbench.c
@@ -259,7 +259,8 @@
 #define TIMER_GET( timer )    ( timer )->total
 #define TIMER_RESET( timer )  ( timer )->total = 0
 
-#define CHUNK_SIZE 50
+#define ITER 1000
+#define CHUNK_SIZE 100
 
 int compare(const void* a, const void* b) {
     if (*(double*)a > *(double*)b) return 1;
@@ -273,7 +274,10 @@ static void benchmark(FT_Face face, btest_t* test, int 
max_iter, double max_time
     double total_time = 0.0;
     btimer_t timer;
 
-    int NUM_CHUNKS = max_iter / CHUNK_SIZE;
+    if(max_iter == 0)
+      max_iter = ITER;
+
+    int NUM_CHUNKS = max_iter / CHUNK_SIZE; // split the total iterations into 
chunks to remove the outliers.
     double medians[NUM_CHUNKS];
 
     // Cache
@@ -961,7 +965,6 @@ static void benchmark(FT_Face face, btest_t* test, int 
max_iter, double max_time
                 ps_hinting_engine_names[ps_hinting_engines[0]],
                 ps_hinting_engine_names[ps_hinting_engines[1]] );
 
-    // TODO: add here -w option
     fprintf( stderr,
       "\n"
       "ftbench: run FreeType benchmarks\n"
@@ -1000,6 +1003,7 @@ static void benchmark(FT_Face face, btest_t* test, int 
max_iter, double max_time
              FACE_SIZE );
     fprintf( stderr,
       "  -t T      Use at most T seconds per bench (default is %.0f).\n"
+       "  -w N      Use N iterations for warming up before each test\n"
       "\n"
       "  -b tests  Perform chosen tests (default is all):\n",
              BENCH_TIME );