moare doc is moare

This commit is contained in:
tth 2021-04-22 23:52:39 +02:00
parent 2bd44fa853
commit dcc1ff35cb
2 changed files with 134 additions and 35 deletions

5
Global.makefile Normal file
View File

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

View File

@ -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'à
faire des trucs futiles et des images qui clignotent.
Nous avons donc sous la main un ensemble d'outils mécaniques qui ne demande
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
quasiment pareil avec Fedora\index{Fedora}.
\textit{Attention, ça devient un peu gore\dots}
une distribution Debian\index{Debian} récente (amd64 et x86),
mais ça marche quasiment pareil avec Fedora\index{Fedora} 64,
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 ?}.
Elle est donc faite, à la base, par ces deux fonctions~:
ce qui est un sujet parfois délicat\footnote{GC or not GC ?} parce que
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
reste des transits ram/ps.
est tout aussi pertinent.
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
un flou de meilleure qualité. Aucune mise à l'échelle n'etant
effctuée, les pixels de sortie peuvent atteindre des valeurs
considérables\footnote{Prévoir une gestion des \textsf{overflows} ?}
(de même taille et de même type) afin d'obtenir
un flou temporel de meilleure qualité. Aucune mise à l'échelle n'etant
effectuée, les pixels de sortie peuvent atteindre des valeurs
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}