# Instructions pour les agents

## Portée et priorités permanentes

Ces règles s'appliquent à toute création, modification, correction ou refactorisation de code dans le projet. Les contraintes pédagogiques ci-dessous priment sur les conventions antérieures incompatibles. Les descriptions de l'existant ne constituent pas une autorisation de reproduire des pratiques contraires à ces règles.

Appliquer les priorités suivantes, dans cet ordre :
1. Respecter les exigences fonctionnelles demandées.
2. Respecter les contraintes pédagogiques et de programmation de ce document.
3. Réutiliser les classes, structures et fonctionnalités existantes.
4. Privilégier la simplicité et la lisibilité.
5. Préserver une architecture orientée objet cohérente.
6. Éviter toute complexité supplémentaire non justifiée.

Ne pas introduire de dépendances, d'abstractions ou de fonctionnalités non demandées.

## Projet et points d'entrée

Repères fondés sur les fichiers de `PICTOR/`.

- Application de démonstration graphique C++17 pour Windows x64 ; solution Visual Studio `PICTOR/PICTOR.sln`, projet `PICTOR/PICTOR.vcxproj`.
- `student.cpp` : fonctions `initApp(Model&)`, `processEvent(const Event&, Model&)` et `drawApp(Graphics&, const Model&)`. La démonstration affiche textes, texture, formes et curseur.
- `Model.h` : état de l'application, actuellement limité à `currentMousePos`.
- `G2D/main.cpp` : création de la fenêtre, boucle événementielle, conversion et distribution des événements, rafraîchissement à la demande. Échap ou la fermeture de la fenêtre termine l'application.
- `Graphics.h` et `G2D/Graphics.cpp` : interface de dessin et implémentation des primitives ; `G2D/wrapperSDL.*` : gestion SDL, ressources et rendu. L'interface `Graphics.h` n'expose pas de types SDL.
- `Event.h`, `G2D/Event.cpp`, `G2D/Key.cpp` : événements et traduction des touches. `V2.*` : coordonnées entières et opérations vectorielles ; `Color.*` : couleurs RGBA flottantes entre 0 et 1.
- `Font.h` : description des polices LiberationMono et Tinos ; `Tile.h` : tuile dessinée relativement à son parent, avec fond, texte centré et bordure.

## Conventions du code à respecter

- Utiliser les signatures des trois fonctions de `student.cpp` attendues par `G2D/main.cpp`.
- Conserver la distinction entre coordonnées de pixels (`height - 1 - y`) et bords géométriques (`height - y`) dans le wrapper : l'axe Y de l'application monte depuis le bas de la fenêtre. Les contours épais utilisent un décalage de demi-pixel.
- Interpréter `Event.x/y` selon `Event.Type` : position pour `MouseMove`, numéro du bouton dans `x` pour `MouseDown/MouseUp`, crans horizontaux/verticaux pour `MouseWheel`, dimensions pour `WindowResize`. Les clics ne fournissent pas la position du pointeur ; celle-ci est mémorisée par `MouseMove`.
- Les remplissages `fillConvexPolyline` et `fillConvexPolygon` triangulent en éventail : leur entrée doit être convexe.
- Les ressources SDL sont possédées par des `unique_ptr` avec destructeurs SDL ; images et polices sont mises en cache dans `SDLwrapper`.
- Les sources compilées sont énumérées explicitement dans `PICTOR.vcxproj` : y inscrire tout nouveau `.cpp` destiné à la compilation.

## Mémoire et ressources

- Interdire les pointeurs bruts (`T*`) dans le code applicatif, sauf lorsqu'une API externe, notamment SDL3, les impose strictement. Les limiter aux frontières de l'API, sans généraliser leur usage.
- Ne pas utiliser `new`, `delete`, `malloc` ou `free` pour gérer la mémoire.
- Privilégier les objets à durée de vie automatique, la gestion des ressources par RAII et les conteneurs STL, notamment `std::vector`, `std::array` et `std::map`. Ne jamais introduire de gestion manuelle lorsqu'une solution simple avec la STL ou des objets automatiques suffit.
- Si des pointeurs sont indispensables, notamment pour le polymorphisme par héritage, utiliser `std::unique_ptr` par défaut ; réserver `std::shared_ptr` au partage de propriété réellement nécessaire.
- Conserver la libération des ressources SDL créées, notamment les appels `SDL_Destroy...` utilisés par les destructeurs RAII. Ces appels ne constituent pas une gestion manuelle de la mémoire applicative interdite.

## Périmètre pédagogique et conception objet

- Rester en C++17 dans les notions du cours : `struct`, `class`, templates simples, conteneurs et algorithmes STL, smart pointers, héritage, polymorphisme, foncteurs et expressions lambda.
- Produire du code compréhensible par un étudiant maîtrisant uniquement ce programme : simple, lisible, explicite et pédagogique plutôt que techniquement sophistiqué.
- Ne pas introduire de métaprogrammation complexe. Éviter les fonctionnalités obscures, les techniques avancées inutiles et les patterns complexes lorsqu'une approche orientée objet classique suffit.
- Privilégier la programmation orientée objet : regrouper données et comportements associés dans des classes cohérentes et respecter systématiquement l'encapsulation.
- Écrire explicitement les niveaux d'accès `private` et `public` ; déclarer les attributs privés par défaut et n'exposer que les méthodes nécessaires.
- Ajouter des getters ou setters seulement si un accès ou une modification contrôlée le justifie, pas automatiquement pour chaque attribut.
- Utiliser héritage et polymorphisme pour représenter des relations naturelles entre objets, sans complexifier artificiellement l'architecture.

## Organisation et géométrie

- Définir au maximum une classe ou structure principale par fichier. Ne pas regrouper plusieurs classes indépendantes ; les déclarations auxiliaires strictement liées peuvent rester dans le même fichier.
- Pour une classe, privilégier la séparation entre déclaration (`.h` ou `.hpp`) et implémentation (`.cpp`), avec une organisation et des noms cohérents.
- Utiliser systématiquement le type `V2` existant pour les calculs géométriques 2D : consulter `PICTOR/V2.h`, réutiliser ses méthodes et opérateurs, sans créer de vecteur concurrent ni dupliquer ses opérations.
- `V2` stocke des entiers : conserver les conversions nécessaires aux types SDL et les coordonnées flottantes du rendu interne pour respecter les conventions de demi-pixel, sans en faire une API géométrique concurrente.

## Paramètres, noms et commentaires

- Qualifier les méthodes membres avec `const` lorsqu'elles ne modifient pas l'état de l'objet.
- Privilégier `const T&` pour les objets non modifiés ; utiliser une référence non constante uniquement pour une modification intentionnelle. Passer les types simples peu coûteux (`int`, `float`, `bool`, etc.) par valeur, sans qualifications `const` artificielles ou inutiles.
- Utiliser camelCase pour variables, attributs, fonctions, méthodes et paramètres (`playerPosition`, `movementSpeed`, `updatePosition`, `deltaTime`). Pour classes et structures, conserver la convention existante et privilégier PascalCase en l'absence de convention.
- Ne pas renommer les symboles des bibliothèques externes, notamment SDL3, ni les éléments existants sans nécessité.
- Placer immédiatement au-dessus de chaque nouvelle fonction ou méthode un commentaire bref expliquant son rôle et son fonctionnement, simple, pédagogique et utile, sans paraphraser son nom.
- Si déclaration et définition sont séparées, placer ce commentaire au-dessus de la déclaration dans l'en-tête, sauf convention existante contraire. Actualiser si nécessaire les commentaires des fonctions existantes modifiées de manière importante.

## Erreurs, exceptions et SDL3

- Ne pas mettre en place de gestion des exceptions C++ : ne pas introduire `try`, `catch` ou `throw`.
- Ne pas ajouter de mécanismes de propagation ou de traitement des erreurs, ni de couches d'abstraction dédiées. Ne pas vérifier ou traiter systématiquement les codes de retour servant uniquement à signaler un échec.
- Pour SDL3, ne pas vérifier ni traiter les retours indiquant uniquement le succès ou l'échec ; ne pas ajouter de messages d'erreur, logs ou branchements conditionnels pour gérer ces échecs. Utiliser l'API directement avec un code léger et lisible, en respectant ses pointeurs et handles imposés.
- Préserver les vérifications indispensables à la logique métier ou à la prévention d'un comportement indéfini. La gestion normale des événements, des entrées utilisateur et du cycle de vie des objets reste nécessaire, tout comme la libération des ressources.
- Ces contraintes concernent le code écrit ou modifié. Ne pas supprimer sans nécessité les mécanismes existants dans les parties non concernées, notamment les exceptions, logs et replis déjà présents dans le wrapper.

## Compilation et ressources

Le projet configure MSVC `v145`, le SDK Windows 10, C++17, `/utf-8` et les avertissements de niveau 4. Deux configurations existent : `Debug|x64` et `Release|x64`.

Depuis la racine, dans un terminal où MSBuild et ces composants sont disponibles :

```powershell
msbuild PICTOR/PICTOR.sln /p:Configuration=Debug /p:Platform=x64
msbuild PICTOR/PICTOR.sln /p:Configuration=Release /p:Platform=x64
```

- Exécutable : `PICTOR/BUILD/bin/<Configuration>/PICTOR.exe` ; fichiers intermédiaires : `PICTOR/BUILD/obj/<Configuration>/`.
- `SDL3import/` fournit les en-têtes, bibliothèques et DLL x64 de SDL3 et SDL3_ttf ; les en-têtes annoncent respectivement les versions 3.4.16 et 3.2.2.
- La cible `CopyAssets` copie `images/`, `font/` et les DLL à côté de l'exécutable après compilation ; elle supprime d'abord les images déjà présentes dans le dossier de sortie.
- Les chemins des ressources sont relatifs à l'exécutable via `SDL_GetBasePath()`, pas au répertoire courant. Fournir le nom du fichier à `drawRectWithTexture` ; une image introuvable utilise `64_error.png` comme repli.
- Les polices sont chargées sous le nom `<famille>-<Regular|Bold|Italic|BoldItalic>.ttf`. Les licences SDL sont dans `SDL3import/*/LICENSE.txt` et celles des polices dans `font/*-LICENSE.txt` ; conserver les notices requises lors de leur redistribution.
- `.vs/` contient les données locales Visual Studio ; `PICTOR.vcxproj.user` configure notamment le `PATH` du débogueur pour les DLL SDL.

## Vérifications disponibles

- Aucun projet de tests unitaires ni outil de formatage n'est défini dans les fichiers du projet.
- `PICTOR_SMOKE_TEST`, lorsqu'elle est présente dans l'environnement, fait exécuter trois rendus puis quitter sans attendre d'événement. Pour un exécutable Debug déjà compilé :

```powershell
$env:PICTOR_SMOKE_TEST = '1'
& .\PICTOR\BUILD\bin\Debug\PICTOR.exe
Remove-Item Env:PICTOR_SMOKE_TEST
```

- Ce mode vérifie le démarrage et le chemin de rendu, sans assertions sur le résultat graphique.
- `Graphics::test` contient des scènes visuelles (contours, remplissages, diagonales, bords et pixels) ; son appel `G.test(G)` est actuellement commenté dans `student.cpp`.

## Liste de contrôle avant de terminer une tâche de programmation

Vérifier les changements effectués :
- Aucun `new`, `delete`, `malloc` ou `free` introduit pour gérer la mémoire ; aucun pointeur brut ajouté sans contrainte d'API externe.
- Smart pointers utilisés lorsque nécessaires ; conteneurs STL et objets automatiques privilégiés ; libération des ressources conservée.
- Code limité au programme du cours ; conception orientée objet et encapsulation respectées.
- Au maximum une classe ou structure principale par fichier ; organisation cohérente.
- `V2` réutilisé pour la géométrie 2D, sans duplication de ses opérations.
- `const`, références constantes et passages par valeur employés à bon escient.
- Noms conformes aux conventions ; chaque nouvelle fonction ou méthode possède un commentaire explicatif.
- Aucun mécanisme de gestion des exceptions ou des erreurs ajouté ; aucun traitement de retour SDL3 signalant uniquement un échec introduit.