Création du vocabulaire SDL2

publication: 5 novembre 2024 / mis à jour 6 novembre 2024

Nous allons voir comment est assurée la liaison logicielle entre eForth Windows et les fonctions disponibles dans SDL2.dll.

Le mot clé est dll. Ce mot est disponible dans le vocabulaire windows. Il crée un ticket d’accès vers des ressources Windows. Si vous avez correctement installé eForth windows et SDL2.dll, on va créer notre ticket d’accès :

windows 
\ Entry point to SDL2.dll library 
z" SDL2.dll" dll SDL2.dll

Ici, notre ticket a été nommé SDL2.dll. On aurait pu le nommer plus simplement SDL2 ou SDL2ticket…

Création et utilisation d’un ticket de liaison logicielle

Reprenons la ligne qui crée le ticket de liaison logicielle :

z" SDL2.dll" dll SDL2.dll

On y voit :

en bleu, le nom du fichier de la librairie à laquelle on va se connecter par liaison logicielle ;
en vert le mot dll qui car créer le ticket de liaison logicielle ;
en rouge notre ticket de liaison logicielle.

Définition du vocabulaire SDL2

Afin d’éviter toute collision logicielle avec des mots prédéfinis du vocabulaire forth, il est fortement recommandé de définir tous les mots propres à la liaison logicielle dans un vocabulaire spécifique :

vocabulary SDL2

Ceci crée le vocabulaire SDL2. Tous les mots de liaison logicielle avec SDL2.dll seront définis dans ce vocabulaire. Pour créer ces nouvelles définitions, nous devrons accéder aux autres vocabulaires forth, windows et structures :

only FORTH also  windows also  structures also

Et enfin, on force la définition des nouveaux mots dans ce vocabulaire SDL2 :

SDL2 definitions

Voici la séquence complète des opérations de définition et exploitation de ce vocabulaire SDL2 :

vocabulary SDL2 
only FORTH also  windows also  structures also 
SDL2 definitions 
 
\ Entry point to SDL2.dll library 
z" SDL2.dll" dll SDL2.dll 
SDL2

Si on exécute vlist, on doit voir ceci :

--> vlist 
SDL2.dll

Ici, SDL2.dll est le premier mot dans notre vocabulaire SDL2.

Définition des liaisons logicielles

Notre ticket SDL2.dll est devenu un mot de définition. Pour créer le mot GetError :

\ Retrieve a message about the last error that occurred on the current thread 
z" SDL_GetError"            0 SDL2.dll GetError ( -- zstr )

On retrouve ici :

en bleu, le nom de la fonction tel qu’il est défini dans la librairie SDL2.dll sous Windows ;
en vert le nombre de paramètres à passer et le ticket de liaison logicielle ;
en rouge le nouveau mot créé dans le vocabulaire SDL2.

On peut vérifier la création de GetError en tapant vlist qui affiche :

--> vlist 
GetError SDL2.dll

Passage des paramètres vers les liaisons logicielles

Dans l’exemple précédent, le mot GetError ne nécessite pas de paramètre. Voyons le cas d’un mot nécessitant plusieurs paramètres :

\ Set the color used for drawing operations (Rect, Line and Clear) 
z" SDL_SetRenderDrawColor"  5 SDL2.dll SetRenderDrawColor

Ici, en rouge, la valeur 5 qui indique au ticket de liaison logicielle qu’il faudra prendre en compte cinq paramètres pour le mot SetRenderDrawColor.

Ici un mot qui ne nécessite qu’un seul paramètre :

\ Destroy the rendering context for a window and free associated textures 
z" SDL_DestroyRenderer"     1 SDL2.dll DestroyRenderer

Il n’y a pas d’indication à donner sur la nature et le nombre de paramètres récupérés par Forth après exécution des mots définis par un ticket de liaison logicielle.

Comprendre la documentation SDL2

La documentation de référence est accessible ici :
https://wiki.libsdl.org/SDL2/CategoryAPI

Pour eForth Windows, il n’est pas question de créer tous les mots associés à ces fonctions. D’une part, certaines fonctions comme SDL_GetAndroidSDKVersion ne concernent pas l’environnement Windows. D’autre part, le but de cette documentation est de vous donner les clés pour rajouter des mots si vous voulez utiliser une fonction dont la liaison logicielle n’a pas été définie dans SDL2.

Voyons un cas précis, la fonction SDL_SetTextureColorMod, dont la documentation est accessible ici :
https://wiki.libsdl.org/SDL2/SDL_SetTextureColorMod

La partie qui nous intéresse est ici :

On voit ici qu’il y a quatre paramètres : texture, r, g et b. la seule chose à retenir c’est ce nombre quatre pour définir notre mot SetTextureColorMod :

z" SDL_SetTextureColorMod"     4 SDL2.dll  SetTextureColorMod

Et c’est tout !

Lors de son exécution, le mot SetTextureColorMod renvoie 0 ou une valeur négative en cas d’erreur. Cette donnée sera à traiter lors de l’exécution du programme.

La documentation de chaque mot du vocabulaire SDL2 est disponible ici :
https://eforth.arduino-forth.com/index/glossaire-windows/

Utilisez la recherche textuelle pour retrouver la documentation complète d’un mot du vocabulaire forth ou SDL2.

Ici la documentation détaillée de GetWindowSizeInPixels :
https://eforth.arduino-forth.com/help/explain-eforth-windows/id/1141

Legal: site web personnel sans commerce / personal site without seling