Classes d’id Tech 4 (neo/ui)

Description des fichiers dans le dossier neo/ui.

  • Chaque section prend le nom des deux fichiers C++ (.h et .cpp) auquelle elle fait référence. Ainsi, BindWindow indique les fichiers BindWindow.h et BindWindow.cpp.
  • Certaines sections ajouteront l'extension pour signaler un fichier unique, tel ListGUILocal.h.
  • Une note « + description » indique que le ou les fichiers contiennent une description détaillée pour une ou plusieurs classes.
  • Une classe entre parenthèses indique qu'elle est héritée : SousClasse (ClasseDeBase).
  • Les hypothèses incertaines seront marquées clairement ; elles sont probables, mais pas confirmées.

Tous les éléments dans un gui sont des sous-fenêtres ; elles peuvent être interactives ou non. Voici tous les types de sous-fenêtres :

  • windowDef
  • editDef
  • choiceDef
  • sliderDef
  • markerDef
  • bindDef
  • listDef
  • fieldDef
  • renderDef
  • gameSSDDef
  • gameBearShootDef
  • gameBustOutDef

Les objets windowDef sont les plus communs ; les autres sont des cas spéciaux.

Chacun de ces types est associé à une classe dans ce dossier. La classe pour les windowDef est définie dans Window.h, celle d'editDef dans EditWindow.h, celle de choiceDef dans ChoiceWindow.h, etc.

=BindWindow

Classe : idBindWindow (idWindow)

La classe représentant les bindDef, des sous-fenêtres servant à assigner une touche à une commande. Le menu Pause contient des bindDef pour les commandes du jeu.

  • HandleEvent() traite les affectations de touche. Elle est appelée lorsqu'on clique l'option pour changer la touche, et aussi lorsque la nouvelle touche est assignée

=ChoiceWindow

Classe : idChoiceWindow (idWindow)

La classe représentant les choiceDef, visibles dans le menu Pause > Système > Config jeu.

Lorsqu'on clique sur une de ces sous-fenêtres, les options disponibles (souvent juste Oui et Non) passent en cycle.

=DeviceContext

On dirait qu'idDeviceContext gère le côté graphique des gui : on y trouve des méthodes pour afficher et formater des rectangles et du texte, de même qu'afficher le curseur.

  • DrawCursor() est la fonction qui dessine le curseur spécial du gui (pas le curseur par défaut, qui apparaît lorsqu'on ouvre la console)
  • DrawText() affiche les zones de texte dans les guis. Sans cette fonction, aucun texte n'y serait visible

=EditWindow

Classe : idEditWindow (idWindow)

Les editDef ; des chaînes de texte éditables, visibles dans le menu Pause > Système > Config jeu > Nom joueur.

  • idEditWindow::GainFocus() est appelée (plus d'une fois, en fait) quand on clique sur un editDef pour modifier son texte

=FieldWindow

La classe idFieldWindow (idWindow) supporte les fieldDef, qui selon idDevNet (en), ne sont pas utilisés dans Doom 3 et ne fonctionnent probablement pas.

=GameBearShootWindow

Classes :

  • BSEntity (une des seules classes dans tout le code qui ne commencent pas par « id »)
  • idGameBearShootWindow

Cette classe serait reliée au jeu d'arcade Shoot the Bear dans Doom 3.

=GameBustOutWindow

Classes :

  • BOEntity
  • BOBrick
  • idGameBustOutWindow

Sans doute un autre jeu d'arcade que je n'ai pas vu.

=GuiScript

Une structure nommée guiCommandDef_t est définie ici ; une occurrence de cette structure associe une fonction de gui à une fonction de C++, via un pointeur de fonction : handler. Voir les notes sur idGuiScript::Parse().

Toutes les commandes de gui valides sont indiquées dans un tableau d'objets guiCommandDef_t, commandList[]. Les fonctions (globales) qui leur sont associées sont aussi définies ici : Script_Set(), Script_SetFocus(), etc.

Note : Les commandes qui affectent le niveau et son script sont traitées dans Entity.cpp (idEntity::HandleGuiCommands()).

Classes :

  • idGuiScript
  • idGuiScriptList

idGuiScript

Cette classe se charge de l'interprétation (et peut-être aussi l'exécution) des commandes de gui. Un objet idGuiScript est construit pour chaque nouvelle commande.

  • idGuiScript::Parse(), utilisée sur toutes les commandes d'un fichier gui après l'étape de chargement, vérifie si une commande est valide, c'est-à-dire présente dans commandList. Cette fonction associe aussi un pointeur de fonction (handler) à la fonction C++ correspondante
  • idGuiScript::Execute() exécute la fonction pointée par le pointeur handler

idGuiScriptList

Maintient une liste d'objets idGuiScript (peut-être pour toutes les commandes dans un fichier ?).

=ListGUI

Classe : idListGUI

Une classe d'interface, héritée par idListGUILocal (dans ListGUILocal.h).

=ListGUILocal.h

Classe : idListGUILocal (idList<idStr>, idListGUI)

idListGUILocal gère les éléments d'un listDef (voir la section ListWindow).

  • idListGUILocal::Add() vérifie si un élément avec l'index spécifié (paramètre id) est présent parmi les éléments de la liste. Si oui, l'élément prend la nouvelle valeur (paramètre s) ; sinon, un nouvel élément est ajouté avec la valeur
  • idListGUILocal::Push() ajoute simplement un élément à la fin de la liste

=ListWindow

Classe : idListWindow (idWindow)

Les sous-fenêtres listDef sont des listes de valeurs à choisir.

  • idListWindow::SetCurrentSel() est appelée lorsqu'on clique une des options disponibles. Le paramètre sel aura l'index de la valeur sélectionnée (0, 1, 2, etc.)

=MarkerWindow

Les markerDef ne sont pas utilisés dans Doom 3 et ne fonctionnent probablement pas.

Classe : idMarkerWindow (idWindow)

=Rectangle

Classes :

  • idRectangle
  • idRegion

idRectangle

Un rectangle théorique ; cette classe n'affiche rien à l'écran.

Il est probable qu'idRectangle ne serve que de base mathématique pour d'autres classes qui dessinent des formes à l'écran.

idRegion

Cette classe ne fait que maintenir une liste d'objets idRectangle.

Les opérations qu'on peut faire sur ces objets sont limitées ; de toute apparence, idRegion sert principalement :

  • à gérer une liste de rectangles qui sont reliés d'une façon quelconque
  • à vérifier si un des rectangles dans sa liste contient un point 2D spécifié en paramètre (voir la méthode Contains())

=RegExp

Contrairement à ce qu'on pourrait croire, ces fichiers n'ont rien à voir avec les expressions régulières ; « RegExp » signifie probablement Register Expression.

Classes :

  • idRegister
  • idRegisterList

idRegister

Je crois qu'une occurrence de cette classe contient une seule propriété d'un windowDef : rect, bordercolor, text, etc.

  • Le membre name (idStr) contient le nom de la propriété
  • Le membre type (short) indique le type de donnée, sa valeur reflétant une des constantes de l'enum REGTYPE

idRegisterList

Cette classe contient une liste d'objets idRegister ; peut-être contient-elle tous les idRegister appartenant à un windowDef particulier ?

=RenderWindow

Classe : idRenderWindow (idWindow)

Les renderDef affichent un objet 3D. Ils ne sont utilisés que dans le menu principal, qui affiche la planète Mars dans l'arrière-plan.

=SliderWindow

Classe : idSliderWindow (idWindow)

Les sliderDef sont utilisés pour des paramètres graduels : volume, sensibilité de la souris, etc.

Hypothèse : ces sous-fenêtres seraient aussi utilisées pour les barres de défilement pour d'autres sortes d'éléments graphiques. Les classes idListWindow et idEditWindow ont chacun un objet idSliderWindow.

=SimpleWindow

idSimpleWindow est une version légère de la classe idWindow (qui représente les objets windowDef dans les gui).

Les idSimpleWindow sont seulement créés dans idWindow::Parse(). Si un idWindow est simple (voir idWindow::IsSimple()), il est converti en idSimpleWindow, probablement pour économiser de l'espace.

  • Le seul constructeur prend comme paramètre un objet idWindow
  • idSimpleWindow::GetParent() retourne le windowDef parent de cette fenêtre

La structure drawWin_t est constituée tout simplement d'un idWindow et d'un idSimpleWindow. Elle est souvent utilisée comme paramètre dans les fonctions reliées aux idWinVar.

=UserInterface.h

Les GUI.

Classes :

  • idUserInterface (abstraite, voir idUserInterfaceLocal)
  • idUserInterfaceManager

=UserInterfaceLocal.h

Classe : idUserInterfaceLocal (idUserInterface)

  • idUserInterfaceLocal::HandleNamedEvent() déclenche un événement nommé dans le windowDef Desktop d'un gui, qui propagera l'événement à ses enfants.

    Note : une fois déclaré dans un fichier .gui (avec onNamedEvent), un événement nommé sera immédiatement utilisable par le code.

=Window

Window.cpp définit toutes les propriétés disponibles pour les windowDef dans un tableau, RegisterVars.

Ce même fichier se charge de la création d'un objet idWindow (qui représente un windowDef dans un gui). Les autres fichiers (EditWindow.h, ChoiceWindow.h...) se chargent des autres types de sous-fenêtres.

Classes :

  • rvNamedEvent
  • idWindow

idWindow

Les objets windowDef dans les GUI.

  • idWindow::GetWinVarByName() retourne une variable de gui
  • idWindow::MouseEnter() représente le survol de la souris sur un windowDef. Cette fonction n'est appelée qu'une fois dans idWindow::RouteMouseCoords()
  • idWindow::Parse() détermine le type de fenêtre dans le script de gui : windowDef, editDef, etc.
  • idWindow::Redraw() met à jour et affiche les windowDef, et (dans le cas du windowDef Desktop) aussi le curseur de la souris
  • idWindow::RouteMouseCoords() observe la position de la souris, et appelle MouseEnter() et MouseExit() quand la souris survole ou quitte un windowDef
  • idWindow::RunScript() est appelée pour tous les événements de gui (OnActivate, OnEnter, OnAction...). Son seul argument indique le type d'événement, faisant référence à une énumération appartenant à idWindow :

    enum {
    ON_MOUSEENTER = 0,
    ON_MOUSEEXIT,
    ON_ACTION,
    ON_ACTIVATE,
    ON_DEACTIVATE,
    ON_ESC,
    ON_FRAME,
    ON_TRIGGER,
    ON_ACTIONRELEASE,
    ON_ENTER,
    ON_ENTERRELEASE,
    SCRIPT_COUNT
    };

    Note : Cette fonction est appelée chaque image avec l'événement ON_FRAME.

  • idWindow::StateChanged() met à jour l'apparence du windowDef et appelle la fonction StateChanged() de tous ses enfants idWindow et idSimpleWindow
  • idWindow::Interactive() vérifie si le windowDef ou ses enfants peuvent être cliqués, donc s'ils ont une propriété OnActionHypothèse : Étant donné qu'OnAction est la seule propriété vérifiée, c'est peut-être pour cette raison que les survols de la souris (onMouseEnter) n'appellent pas idEntity::HandleGuiCommands().
  • idWindow::IsSimple() retourne false si le windowDef a des enfants, des événements ou d'autres propriétés spéciales ; les windowDef statiques en arrière-plan seraient donc des exemples de windowDef simples

=Winvar

Ces fichiers gèrent les variables qui passent par un gui. Certaines d'entre elles sont définies dans le C++, d'autres dans le gui lui-même.

Quelques exemples de variables de gui dans hud.gui (le gui du HUD du joueur) : player_health, player_ammo et player_armor. À l'occurrence, ces variables sont réglées par des méthodes d'idPlayer.

Classes principales :

  • idWinVar
  • idMultiWinVar (idList< idWinVar * >)

Sous-classes d'idWinVar :

  • idWinBackground (idWinStr)
  • idWinBool
  • idWinFloat
  • idWinInt
  • idWinRectangle
  • idWinStr
  • idWinVec2
  • idWinVec3
  • idWinVec4

idWinVar

  • idWinVar::GetName() retourne le nom d'une variable de gui
  • idWinVar::SetName() règle son nom

idWinStr

  • idStr::c_str() retourne la valeur de cette variable sous forme de const char*

idWinRectangle

  • operator const idRectangle&() permet de convertir le rectangle en idRectangle