moare doc is moare

Global.makefile

@@ -0,0 +1,5 @@
+
+#
+#	This file is the 'grandmasata' of the compilation process.
+#
+

doc/the_floatimg_hack.tex

@@ -50,7 +50,7 @@
 \begin{document}
 \maketitle
 
-\section*{Image flottante ?}
+\section*{Une image flottante ?}
 
 Mais de quoi parle-t-on exactement ?
 
@@ -145,7 +145,7 @@ nous allons créer une image RGB\index{RGB} complètement noire,
 puis l'enregistrer dans un fichier \texttt{.fimg}\index{.fimg},
 un format complètement inconnu, puisque je viens de l'inventer
 à l'instant même.
-Enfin, non, il y a déja longtemps, avant la pandémie.
+Enfin, non, il y a déja longtemps, avant la grande pandémie.
 
 Tout d'abord, nous devons déclarer et garnir quelques variables
 pour gérer la machinerie interne.
@@ -194,22 +194,26 @@ mean values:
 max value       0.000000
 \end{verbatim}
 
-Nous avons donc sous la main une mécanique qui ne demande qu'à
+Nous avons donc sous la main un ensemble d'outils mécaniques qui ne demande
-faire des trucs futiles et des images qui clignotent.
+qu'à faire des trucs futiles et des images qui clignotent.
+Avec un bon script bash, il y a déja de quoi faire.
 La suite vers la page \pageref{codaz}. 
 
 Vous trouverez dans le répertoire \texttt{tools/}\index{tools/}
 d'autres exemples de mise en œuvre des fonctions disponibles
 sous formes d'outils en ligne de commande,
-lesquels sont décrits en page \pageref{outils}.
+lesquels sont approximativement décrits en page \pageref{outils}.
 
 % ===================================================================
 \section{Installation}
 
 Sauf indications contraires, ces instructions se réfèrent à
-une distribution Debian\index{Debian} récente, mais ça marche
+une distribution Debian\index{Debian} récente (amd64 et x86),
-quasiment pareil avec Fedora\index{Fedora}.
+mais ça marche quasiment pareil avec Fedora\index{Fedora} 64,
-\textit{Attention, ça devient un peu gore\dots}
+et
+probablement Raspbian\index{Raspbian}, modulo les éventuels
+soucis de boutisme.
+\textit{Attention, ça va devenir un peu gore\dots}
 
 \subsection{Prérequis}
 
@@ -234,7 +238,10 @@ Il faut aussi savoir où trouver le code.
 
 \subsection{Compilation}
 
-Un script \texttt{build.sh} permet de construire approximativement 
+La première chose à faire est d'aller regarder le contenu du fichier
+\texttt{Global.makefile} à la racine du projet. Il contient des
+informations pertinentes pour la suite des choses.
+Ensuite, un script \texttt{build.sh} permet de construire approximativement 
 le bouzin. Il est loin d'être parfait\footnote{Il doit être possible
 de faire un Makefile récursif, mais\dots}.
 Dans chacun des répertoires à traiter, ce script devrait trouver
@@ -271,11 +278,12 @@ contenant un certain nombre de définition de structures, de macros,
 de constantes\footnote{À l'ancienne, via le pré-processeur} 
 et les prototypes des fonctions utilisables par vos logiciels.
 
-Au niveau du code source, ces fonctions sont approximativement
+Au niveau du code source, ces fonctions sont très approximativement
 classées en deux catégories : \texttt{lib/} et \texttt{funcs/}.
 La première contient les choses qui sont relativement figées,
 et la seconde celles qui risquent de bouger. Cette classification
 est en fait indécement arbitraire.
+D'autant plus qu'il y a aussi un répertoire nommé « experiemental ».
 
 \subsection{Structures, macros\dots}
 
@@ -305,7 +313,7 @@ Le troisième est le type d'image : pour le moment, il y en a % trois
 un certain nombre
 qui sont définis\footnote{et plus ou moins bien gérés\dots} :
 gris, rgb et rgba/rgbz\index{rgba}\index{rgbz}.
-Les constantes adéquates sont dans \texttt{floatimg.h}
+Les constantes adéquates sont déclarées dans \texttt{floatimg.h}~:
 
 \begin{lstlisting}
 #define FIMG_TYPE_GRAY              1
@@ -347,7 +355,7 @@ un affichage plus détaillé. Ça peut parfois aider.
 Une bonne partie des fonctions que nous allons voir est indéterministe.
 Ce qui veut dire, en langage de tous les soirs, que ça risque de ne
 pas être la même chose dans l'avenir. Mais après tout, ce n'est
-encore qu'un concept en devenir, n'est-ce pas ?
+encore qu'un concept en devenir, n'est-il pas ?
 
 %		----------------------------------
 
@@ -355,8 +363,9 @@ encore qu'un concept en devenir, n'est-ce pas ?
 
 La première chose que nous devons absolument voir est la gestion
 dynamique de la mémoire qui sera occupée par tous ces pixels flottants,
-ce qui est un sujet parfois délicat\footnote{GC or not GC ?}.
+ce qui est un sujet parfois délicat\footnote{GC or not GC ?} parce que
-Elle est donc faite, à la base, par ces deux fonctions~:
+les pixels sont précieux et doivent être bien rangés.
+Cette gestion est donc faite, à la base, par ces deux fonctions~:
 
 \begin{lstlisting}
 int fimg_create(FloatImg *fimg, int w, int h, int type);
@@ -365,7 +374,8 @@ int fimg_destroy(FloatImg *fimg);
 
 L'appelant doit lui-même gérer le descripteur d'image (une structure
 C décrite plus haut) en le considérant comme un type semi-opaque dont
-la forme \emph{peut} varier.
+la forme \emph{peut} varier, mais qu'il convient de mettre à zéro
+avant le moindre usage\footnote{\texttt{man 3 memset}}.
 Certains membres de cette structure sont
 documentés dans ce document, et les autres sont dangereux à
 toucher. Les types d'images actuellement gérés sont les trois grands
@@ -382,10 +392,10 @@ int fimg_images_not_compatible(FloatImg *a, FloatImg *b);
 \end{lstlisting}
 
 
-C'est bien beau d'être enfin résident en mémoire centrale, mais
+C'est bien beau d'être enfin une image résidente en mémoire centrale, mais
 pouvoir aussi exister à long terme en étant stocké dans la matrice
-est tout aussi pertinent. Il y a deux opérations qui supportent le
+est tout aussi pertinent.
-reste des transits ram/ps.
+Il y a deux opérations qui supportent le reste des transits ram/ps.
 Le format des fichiers est décrit page \pageref{formatfimg}.
 
 \begin{lstlisting}
@@ -581,9 +591,13 @@ typedef struct {
 la valeur maximale, la date de création, une longueur d'onde,
 et bien plus encore.
 
-Le champ \texttt{magic[8]} doit contenir une valeur magique.
+Le champ \texttt{magic[8]} doit contenir une valeur magique~:
+les quatre premier octets doivent contenir les quatre caractères
+\texttt{'FIMG'}, et les quatre dernier doivent être à 0.
 Le champ \texttt{t} (le type de l'image) doit avoir les trois octets
-de poids fort à 0.
+de poids fort à 0. Vous trouverez les constantes de type dans le
+fichier \texttt{floatimg.h}, et quelques informations
+(non-)essentielles.
 
 %		----------------------------------
 
@@ -714,11 +728,14 @@ int fimg_colors_mixer_a(FloatImg *fimg, float fval);
 
 Un \textsl{glitch} peut-il être classé dans la catégorie des effets
 spéciaux ou non ? \textsc{Hmha}, non. un fx est paramétrable
-et surtout répétitif. Un glitch est quasiment souvbent un phénomène
+et surtout répétitif. Un glitch est quasiment souvent un phénomène
 aléatoire\index{drand48} et tout aussi paramétrable.
 
 J'ai commencé à étudier ces objets étranges quand j'ai commencé
-sur l'interpolator\index{interpolator} à l'automne 2020.
+à travailler sur l'interpolator\index{interpolator} à l'automne 2020.
+Hélas, j'ai vite réalisé que c'était assez délicat.
+Pour ce genre de \textsl{usecase}, le numérique est pitoyable si on
+le compare au \textsc{Betamax}\index{Betamax}.
 
 %		----------------------------------
 
@@ -809,12 +826,12 @@ return 0;
 
 Je vous laisse imaginer les dégats que peut faire cette 
 fonction en utilisation réelle. Mieux, je vous propose
-d'essayer par vous-même.
+d'essayer par vous-même, vous allez voir, c'est assez créatif.
 En particulier tout le reste du code qui suppose qu'un pixel
 ne peut \textbf{pas} être négatif va peut-être exploser de rire.
 Vous pouvez aussi remarquer qu'il n'y a pas de controle
 de cohérence sur les dimensions des deux images, malgré l'existence
-de fonctions prévues à cet effet..
+de fonctions prévues à cet effet\dots
 
 
 % ===================================================================
@@ -852,7 +869,7 @@ Usage:  mkfimg [options]  quux.fimg width height
 
 La plupart des types d'image générée prennent un paramètre flottant qui
 devra être donné avec l'option \texttt{-k F.F} avec une valeur par défaut
-à $1.0$.
+à $1.0$, ce qui n'est pas toujours une bonne valeur.
 
 \begin{description}	\index{XXX}
 \item [black/gray/grey:] efface avec 0.0 (black) ou avec la valeur
@@ -991,10 +1008,10 @@ logiciel aux calendes grecques, voire même plus tard.
 \subsection{cumulfimgs}\index{cumulfimgs}\label{cumulfimgs}
 
 Cet outil accumule\index{cumul} une quantité d'images flottantes
-(même taille et même type) afin d'obtenir
+(de même taille et de même type) afin d'obtenir
-un flou de meilleure qualité. Aucune mise à l'échelle n'etant
+un flou temporel de meilleure qualité. Aucune mise à l'échelle n'etant
-effctuée, les pixels de sortie peuvent atteindre des valeurs
+effectuée, les pixels de sortie peuvent atteindre des valeurs
-considérables\footnote{Prévoir une gestion des \textsf{overflows} ?}
+considérables\footnote{Faut-il prévoir une gestion des \textsf{overflows} ?}
 
 \begin{verbatim}
 tth@delirium:~/Devel/FloatImg/tools$ ./cumulfimgs -h
@@ -1009,6 +1026,74 @@ cumulator options :
 Le nom par défaut du fichier résultant est \texttt{out.fimg}.
 L'exportation « multiformat » est pour bientôt.
 
+% ===================================================================
+\section{Debug}\index{Debug}
+
+\textit{Et quand plus rien ne fonctionne normalement ?}
+
+Ayant une attirance marquée pour la méthode de développement dite
+de \textsl{larache}, que je pratique intensément, j'ai quand même
+besoin de m'équiper de quelques garde-fous. Avec l'expérience, j'ai
+découvert quelques méthodes bien utile quand on est à court de
+poudre verte.
+
+\subsection{À la compilation}
+
+Première de cordée, la méthode \texttt{DEBUG\_LEVEL}\index{DEBUG\_LEVEL}.
+Elle me sert
+essentiellement à tracer les appels de fonctions, et les paramètres
+qu'elles reçoivent. Ça fait vraiment partie de la création
+des \textsl{boiler-plates}.
+C'est une valeur numérique entière définie dans chaque
+\texttt{Makefile}\index{Makefile}
+qui sera ensuite utilisée
+par le préprocesseur afin de rajouter ce genre de code dans l'exécutable~:
+
+\begin{verbatim}
+int fimg_export_picture(FloatImg *pic, char *fname, int flags)
+{
+int		filetype, foo;
+#if DEBUG_LEVEL
+fprintf(stderr, ">>> %s ( %p '%s' 0x%X )\n", __func__, pic, fname, flags);
+#endif
+...
+\end{verbatim}
+
+Le principe est simple, n'est-il pas, alors pourquoi s'en priver ?
+Bien entendu, la même constante peut être utilisée plus agressivement
+avec une condition comme \texttt{\#if DEBUG\_LEVEL > 2} permettant
+de générer encore plus de messages traçants.
+
+Ensuite, pour les cas les plus graves, qui nécessiteront l'utilisation
+du dévermineur \texttt{gdb}\index{gdb}, il y a la directive
+\texttt{MUST\_ABORT} qui est bien plus violente, mais parfois bien
+pratique. Voici le cas classique d'utilisation~:
+
+\begin{verbatim}
+foo = fimg_strange_function(&picture, 13.37);
+if (foo) {
+        fprintf(stderr, "epic fail %d in %s\n", foo, __func__);
+#if MUST_ABORT
+        abort();
+#endif
+...
+\end{verbatim}
+
+À condition d'avoir bien réglé votre ulimit pour la génération d'un coredump,
+vous aurez sous la main un fichier \textsc{core} qui vous permettra
+de, par exemple, remonter la pile d'appel avec la commande \texttt{back} de
+gdb. Mais pour le moment, juste une infime partie du code est instrumentée
+avec ce dispositif.
+
+
+\subsection{À l'exécution}
+
+De l'utilisation des nombres magiques dans la détection des structures
+corrompues par un pointeur ayant perdu le nord\dots
+
+De l'utilisation des variables d'environnement pour transformer des warnings
+en erreurs fatales\dots
+
 % ===================================================================
 \section{TODO}\index{TODO}\label{TODO}\
 		\index{XXX}
@@ -1016,16 +1101,17 @@ L'exportation « multiformat » est pour bientôt.
 Il reste plein de choses à faire pour que ce soit vraiment utilisable,
 surtout dans un contexte artistique à grande porosité.
 C'est par ces frottements de techniques ayant du sens que les
-choses seront acquises.
+choses seront acquises, pour le pire, le meilleur et la
+futilité du monde futur..
 
 \begin{itemize} 
-\item	Import/export au format \textsc{tiff}\index{TIFF}.
+\item	Import/export au format \textsc{tiff}\index{TIFF} à continuer.
 \item	Remplacer le « fait-maison » par \textsc{libnetpnm}\index{pnm}.
 	\textsl{[en cours]}.
 \item	Compléter les traitements mathémathiques (eg le gamma\index{gamma}).
 \item	Formaliser les codes d'erreur. \textbf{Urgent}.
 \item	Faire une passe complète de Valgrind\index{valgrind}.
-\item	Intégrer la fonderie et l'interpolator.
+\item	Intégrer la fonderie, l'interpolator et le singlepass.
 \item	Vérifier le gestion des images mono-canal.
 \end{itemize}
 
@@ -1374,7 +1460,8 @@ foultitude d'effets spéciaux.
 
 \subsection{\textsl{moving average}}
 
-\texttt{./fonderie} : Basé sur la moyenne mobile.
+\texttt{./fonderie} : Basé sur la moyenne mobile, avec une structure de
+fifo\index{fifo} particulièrement mal conçue.
 
 \subsection{Interpolator}\index{interpolator}
 
@@ -1388,8 +1475,11 @@ avec l'option \texttt{-L}\footnote{liste hélas peu machinable.}
 
 \subsection{Déviance}
 
-Là, nous tombons dans la troiD de haut niveau, avec plein de maths
+Là, nous tombons dans de la \textsl{troiD}\index{3d} de haut niveau,
+avec plein de maths compliquées
 à l'intérieur.
+Et surtout quelque chose qui n'est encore qu'une idée abstraite,
+mais il y aura du zbuffer dedans.
 
 % ===================================================================
 
@@ -1409,6 +1499,10 @@ faire des images au bord d'un lac ou dans la campagne de l'Ariège.
 
 % -------------------------------------------------------------------
 
+%                 XXX
+% maintenant, comment faire un index sur trois colonnes ?
+%
+
 \printindex
 
 \end{document}