Migrer de GLFW 2 à GLFW 3.1

Équipe de GLFW

Traducteur

Alexandre Laurent

Voici un guide de transition pour migrer de GLFW 2 à GLFW 3.1. Il décrit ce qui a changé ou a été supprimé, mais n'inclut aucune des nouvelles fonctionnalités, sauf si elles sont utiles pour la migration d'un code existant vers la nouvelle bibliothèque.

Commentez

- Titre : Migrer de GLFW 2 à GLFW 3.1

- Auteur : Équipe de GLFW

- Traducteur : Alexandre Laurent

- Parution : 29 janvier 2015

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2015 Équipe de GLFW. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

- II. Fonctionnalités modifiées et supprimées

- II-A. Renommage des fichiers d'en-tête et de bibliothèque

- II-B. Suppression des fonctions de threading

- II-C. Suppression du chargement d'images et de textures

- II-D. Suppression de la macro GLFWCALL

- II-E. Identifiants de fenêtre

- II-F. Sélection explicite d'écran

- II-G. Propagation automatique des événements

- II-H. Gestion de contexte explicite

- II-I. Séparation des tailles de fenêtre de tampon d'image

- II-J. Changement de la fermeture de fenêtre

- II-K. Persistance des paramètres de fenêtrage

- II-L. Énumération du mode vidéo

- II-M. Actions sur les caractères

- II-N. Changement sur la position du curseur

- II-O. Position de la molette de la souris remplacée par des décalages de défilement

- II-P. Action de répétition de touches

- II-Q. Entrée de touche physique

- II-R. Changement sur les fonctions des joysticks

- II-S. Support Win32 MBCS

- II-T. Support des versions plus vieilles que Windows XP

- II-U. Capture globale des raccourcis clavier

- II-V. Arrêt automatique

- II-W. Inclusion du fichier d'en-tête de GLU

- III. Changement de noms

- III-A. Fonctions renommées

- III-B. Tokens renommés

- IV. Remerciements

I - Introduction

Voici un guide de transition pour migrer de GLFW 2 à GLFW 3.1. Il décrit ce qui a changé ou a été supprimé, mais n'inclut aucune des nouvelles fonctionnalités, sauf si elles sont utiles pour la migration d'un code existant vers la nouvelle bibliothèque. Par exemple, l'utilisation des nouvelles fonctions pour les écrans multiples est nécessaire pour créer une fenêtre plein-écran avec GLFW 3.

II - Fonctionnalités modifiées et supprimées

II-A - Renommage des fichiers d'en-tête et de bibliothèque

Le fichier d'en-tête de GLFW 3 est nommé glfw3.h et a été déplacé dans le répertoire de GLFW pour éviter les conflits avec les en-têtes des autres versions majeures. Pareillement, la bibliothèque de GLFW 3 est nommée glfw3, sauf lorsqu'elle est installée en tant que bibliothèque partagée sur les systèmes Unix, où elle est appelée libglfw.so.3 avec le soname.

Ancienne syntaxe

#include <GL/glfw.h>

Nouvelle syntaxe

#include <GLFW/glfw3.h>

II-B - Suppression des fonctions de threading

Les fonctions de threading ainsi que la fonction de sommeil par thread ont été supprimées. Elles étaient archaïques, sous-utilisées, mal intégrées et provoquaient une perte de temps éloignant du but principal de GLFW (c'est-à-dire le contexte, les entrées utilisateur et le fenêtrage). Il existe de meilleures bibliothèques de threading et un support des threads en natif que ce soit en C++11 ou en C11, qui sont eux-mêmes de plus en plus présents.

Si vous souhaitez utiliser les fonctionnalités du C++11 ou du C11, mais que votre compilateur ne les supporte pas encore, jetez un œil aux projets TiniThread++ et TinyCTHread créés par le développeur initial de la GLFW. Ces bibliothèques implémentent un sous-ensemble des bibliothèques C++11 et C11 de threads et, en réalité, certains des programmes de tests de GLFW 3 utilisent TinyCThread.

Toutefois, GLFW 3 supporte mieux une utilisation multithreads que ne le faisait GLFW 2. Les contextes peuvent être activés sur n'importe quel thread, bien qu'ils ne puissent être actifs que sur un seul thread à la fois et la documentation indique explicitement quelles fonctions peuvent être utilisées à partir de n'importe quel thread et lesquelles ne peuvent être utilisées que dans le thread principal.

Fonctions supprimées :

glfwSleep, glfwCreateThread, glfwDestroyThread, glfwWaitThread, glfwGetThreadID, glfwCreateMutex, glfwDestroyMutex, glfwLockMutex, glfwUnlockMutex, glfwCreateCond, glfwDestroyCond, glfwWaitCond, glfwSignalCond, glfwBroadcastCond et glfwGetNumberOfProcessors.

II-C - Suppression du chargement d'images et de textures

Les fonctions de chargement d'images et de textures ont été supprimées. Elles ne supportaient que le format d'image Targa, ne les rendant utiles que dans les exemples pour les débutants. Afin de devenir une fonctionnalité d'assez haute qualité pour être conservée dans GLFW 3, il aurait fallu non seulement supporter d'autres formats d'images, mais aussi les extensions modernes d'OpenGL pour les textures. Cela aurait soit ajouté de nombreuses dépendances externes (libjpeg, libpng, etc.), soit forcé GLFW à embarquer des versions de ces bibliothèques.

Comme il y a déjà des bibliothèques permettant de faire cela, il est inutile de dupliquer le travail et de l'attacher à GLFW. La bibliothèque en résultant ne devrait être spécifique qu'à une plate-forme, alors que OpenGL et studio sont disponibles partout où GLFW l'est.

Fonctions supprimées :

glfwReadImage, glfwReadMemoryImage, glfwFreeImage, glfwLoadTexture2D, glfwLoadMemoryTexture2D et glfwLoadTextureImage2D.

II-D - Suppression de la macro GLFWCALL

La macro GLFWCALL, qui faisait utiliser stdcall aux fonctions callback sous Windows, a été retirée. GLFW est écrite en C, pas en Pascal. Avec la suppression de cette macro, les développeurs d'applications n'ont plus besoin de se souvenir de la nécessité que toutes les fonctions de callback soient marquées avec GLFWCALL. Cela simplifie aussi la création des DLL et des bibliothèques de liaison de DLL, car il n'y a plus besoin de désactiver explicitement les suffixes de points d'entrées @n.

Ancienne syntaxe

void GLFWCALL callback_function(...);

Nouvelle syntaxe

void callback_function(...);

II-E - Identifiants de fenêtre

Comme GLFW 3 supporte l'ouverture de plusieurs fenêtres, les paramètres d'identification de fenêtre ont été ajoutés pour toutes les fonctions et callbacks GLFW liés aux fenêtres. L'identifiant d'une nouvelle fenêtre est retourné par glfwCreateWindow (anciennement glfwOpenWindow). Les identifiants de fenêtre sont des pointeurs du type opaque GLFWwindow.

Ancienne syntaxe

glfwSetWindowTitle("New Window Title");

Nouvelle syntaxe

glfwSetWindowTitle(window, "New Window Title");

II-F - Sélection explicite d'écran

GLFW 3 fournit un support des configurations à écrans multiples. Pour obtenir une fenêtre plein-écran, au lieu de passer GLFW_FULLSCREEN, vous devez spécifier quel moniteur vous souhaitez que la fenêtre utilise. La fonction glfwGetPrimaryMonitor retourne l'écran qu'aurait sélectionné GLFW 2, mais il y a de nombreuses autres fonctions pour les écrans. Les identifiants d'écran sont des pointeurs du type opaque GLFWmonitor.

Ancien mode plein écran basique

glfwOpenWindow(640, 480, 8, 8, 8, 0, 24, 0, GLFW_FULLSCREEN);

Nouveau mode plein écran basique

window = glfwCreateWindow(640, 480, "My Window", glfwGetPrimaryMonitor(), NULL);

Les paramètres du bit de profondeur du tampon d'image de glfwOpenWindow ont été remplacés par des indicateurs de fenêtre, mais comme ils ont des valeurs par défaut logiques vous n'aurez que rarement besoin de ces indicateurs.

II-G - Propagation automatique des événements

GLFW 3 ne propage pas automatiquement les événements dans l'appel à la fonction glfwSwapBuffers, ce qui signifie que vous devez appeler glfwPollEvents ou glfwWaitEvents vous-même. Contrairement à l'échange de tampons qui n'agit que sur une seule fenêtre, les fonctions de traitement des événements agissent sur toutes les fenêtres à la fois.

Ancienne boucle de base

while (...)
{
// Process input
// Render output
glfwSwapBuffers();
}

Nouvelle boucle de base

while (...)
{
// Process input
// Render output
glfwSwapBuffers(window);
glfwPollEvents();
}

II-H - Gestion de contexte explicite

Chaque fenêtre GLFW 3 possède son propre contexte OpenGL et vous seul, le développeur d'application, pouvez savoir quel contexte doit être activé sur quel thread et ce, à n'importe quel moment. Par conséquent, GLFW 3 vous laisse prendre cette décision.

Cela signifie que vous devez appeler glfwMakeContextCurrent après la création d'une fenêtre et avant l'appel de n'importe quelle fonction OpenGL.

II-I - Séparation des tailles de fenêtre de tampon d'image

Les positions et tailles de fenêtre utilisent maintenant les coordonnées-écrans, et peuvent donc différer des pixels sur les machines ayant des écrans à haut PPP. C'est important, car OpenGL utilise des pixels et non des coordonnées-écrans. Par exemple, le rectangle spécifié à la fonction glViewport doit utiliser des pixels. Dorénavant, des fonctions de dimensionnement du tampon image ont été ajoutées. Vous pouvez récupérer la taille du tampon d'image d'une fenêtre avec la fonction glfwGetFramebufferSize. Un callback pour la taille du tampon d'image a aussi été ajouté et peut être défini avec la fonction glfwSetFramebufferSizeCallback.

Ancienne configuration basique du viewport

glfwGetWindowSize(&width, &height);
glViewport(0, 0, width, height);

Nouvelle configuration basique du viewport

glfwGetFramebufferSize(window, &width, &height);
glViewport(0, 0, width, height);

II-J - Changement de la fermeture de fenêtre

Le paramètre GLFW_OPENED a été retiré. Tant que la fenêtre n'a pas été détruite, que ce soit avec la fonction glfwDestroyWindow ou la fonction glfwTerminate, la fenêtre est « ouverte ».

Un utilisateur essayant de fermer une fenêtre est maintenant un événement comme un autre. Contrairement à GLFW 2, les fenêtres et contextes créés avec GLFW 3 ne seront jamais détruits sauf si vous choisissez qu'ils le soient. Chaque fenêtre possède maintenant un indicateur de fermeture qui est défini à GL_TRUE lorsque l'utilisateur tente de fermer cette fenêtre. Par défaut, rien d'autre n'arrive et la fenêtre reste visible. C'est alors à vous de détruire la fenêtre, entreprendre toute autre action, ou simplement ignorer la requête.

Vous pouvez à n'importe quel moment connaître l'état de l'indicateur avec la fonction glfwWindowShouldClose ou le définir avec la fonction glfwSetWindowShouldClose.

Ancienne boucle principale

while (glfwGetWindowParam(GLFW_OPENED))
{
...
}

Nouvelle boucle principale

while (!glfwWindowShouldClose(window))
{
...
}

Le callback de fermeture ne retourne plus de valeur. À la place, il est appelé après que l'indicateur de fermeture a été défini et donc, il peut écraser sa valeur, s'il le souhaite, avant la fin du traitement des événements. Vous ne pouvez cependant pas appeler la fonction glfwDestroyWindow à partir du callback de fermeture (ou n'importe quel autre callback lié aux fenêtres).

Ancienne syntaxe

int GLFWCALL window_close_callback(void);

Nouvelle syntaxe

void window_close_callback(GLFWwindow* window);

GLFW ne nettoie jamais l'indicateur de fermeture à GL_FALSE, signifiant que vous pouvez l'utiliser pour d'autres raisons que la fermeture de la fenêtre, par exemple, lorsque l'utilisateur choisit « Quitter » dans un menu de jeu.

II-K - Persistance des paramètres de fenêtrage

La fonction glfwOpenWindowHint a été renommée en glfwWindowHint.

Les paramètres de fenêtrage ne sont plus réinitialisés à leurs valeurs par défaut à la création d'une fenêtre, mais conservent leurs valeurs tant qu'ils ne sont pas modifiés par glfwWindowHint ou glfwDefaultWindowHints, ou tant que la bibliothèque n'est pas terminée et réinitialisée.

II-L - Énumération du mode vidéo

L'énumération du mode vidéo fonctionne maintenant par écran. La fonction glfwGetVideoModes retourne dorénavant les modes disponibles pour un écran spécifique au lieu de vous laisser deviner la taille du tableau dont vous aurez besoin. La fonction glfwGetDesktopMode, qui avait un comportement mal défini, a été remplacée par glfwGetVideoMode qui retourne le mode actuel d'un écran.

II-M - Actions sur les caractères

Le paramètre action du callback de caractères a été retiré. C'était un artefact provenant des origines de GLFW, c'est-à-dire lorsqu'elle fut développée en anglais par un Suédois. Toutefois, la plupart des dispositions de clavier nécessitent plus d'une touche pour produire les caractères avec des signes diacritiques. Même la disposition du clavier suédois nécessite cela pour les rares cas comme ü.

Ancienne syntaxe

void GLFWCALL character_callback(int character, int action);

Nouvelle syntaxe

void character_callback(GLFWwindow* window, int character);

II-N - Changement sur la position du curseur

La fonction glfwGetMousePos a été renommée en glfwGetCursorPos, glfwSetMousePos en glfwSetCursorPos et glfwSetMousePosCallback en glfwSetCursorPosCallback.

La position du curseur est maintenant en double et non plus en int, que ce soit pour les fonctions directes ou le callback. Certaines plates-formes peuvent fournir un mouvement de curseur en dessous du pixel et cette donnée est maintenant passée à l'application, lorsque possible. Sur les plates-formes où cette information n'est pas fournie, la partie décimale reste à zéro.

GLFW 3 vous permet seulement de positionner le curseur dans une fenêtre avec glfwSetCursorPos (anciennement glfwSetMousePos) lorsque cette fenêtre est active. Si la fenêtre n'est pas active, la fonction échoue silencieusement.

II-O - Position de la molette de la souris remplacée par des décalages de défilement

La fonction glfwGetMouseWheel a été supprimée. Le défilement est produit à partir de décalages et n'a aucune position absolue. Le callback de la molette de la souris a été remplacé par un callback de défilement qui reçoit un décalage de défilement en valeurs à virgule flottante sur deux dimensions. Cela vous permet de recevoir des données de défilement précises à partir, par exemple, des touchpads modernes.

Ancienne syntaxe

void GLFWCALL mouse_wheel_callback(int position);

Nouvelle syntaxe

void scroll_callback(GLFWwindow* window, double xoffset, double yoffset);

Fonctions supprimées :

glfwGetMouseWheel.

II-P - Action de répétition de touches

GLFW_KEY_REPEAT a été supprimé et la répétition de touches est toujours activée, que ce soit pour les touches ou les caractères. Une nouvelle action GLFW_REPEAT a été ajoutée pour permettre au callback de touche de distinguer un appui initial et une répétition. Notez que glfwGetKey retourne seulement GLFW_PRESS ou GLFW_RELEASE.

II-Q - Entrée de touche physique

Les symboles de touches GLFW 3 correspondent aux touches physiques, contrairement à GLFW 2 où les symboles correspondaient aux valeurs générées par la disposition du clavier. Les symboles sont nommés suivant la valeur qu'ils auraient sur une disposition US standard, mais ce n'est qu'une convenance, car tout programmeur est supposé la connaître. Cela signifie que, par exemple, GLFW_KEY_LEFT_BRACKET est toujours une seule et même touche à la même place, peu importe la disposition du clavier de l'utilisateur de votre programme.

La fonctionnalité d'entrée des touches n'a jamais été prévue pour l'insertion de texte, même si cela fonctionne légèrement mieux ainsi dans GLFW 2. Si vous l'utilisiez pour l'insertion de texte, vous devriez utiliser le callback de caractères à la place, que ce soit avec GLFW 2 ou GLFW 3. Cela vous donnera les caractères entrés et non les touches appuyées.

GLFW 3 possède des symboles de touches pour toutes les touches d'un clavier standard à 105 touches, donc au lieu d'avoir à vous rappeler si c'est un 'a' ou 'A', vous pouvez maintenant utiliser juste GLFW_KEY_A.

II-R - Changement sur les fonctions des joysticks

La fonction glfwGetJoystickPos a été renommée glfwGetJoystickAxes.

La fonction glfwGetJoystickParamet les symboles GLFW_PRESENT, GLFW_AXES et GLFW_BUTTONS ont été remplacés par la fonction glfwJoystickPresent, et le nombre d'axes et de boutons est retourné par les fonctions glfwGetJoystickAxes et glfwGetJoystickButtons.

II-S - Support Win32 MBCS

Le portage Win32 de GLFW ne compilera pas en mode MBCS. Toutefois, comme l'utilisation de la version Unicode de la bibliothèque Win32 n'affecte pas l'ensemble du processus, mais seulement les fenêtres créées avec, il est parfaitement possible d'appeler les fonctions MBCS dans une autre partie de la même application. Par conséquent, même si une application utilisant GLFW possède du code en mode MBCS, GLFW n'a pas besoin de le supporter.

II-T - Support des versions plus vieilles que Windows XP

Tout support explicite des versions plus vieilles que Windows XP a été supprimé. Il n'y a aucun code empêchant activement GLFW 3 de tourner sur ces versions précédentes, mais la bibliothèque utilise des fonctions de Win32 que ces versions n'ont pas.

Windows XP a été publié en 2001 et actuellement (janvier 2015) il n'a pas seulement remplacé toutes les versions précédentes de Windows, mais il a aussi été rapidement remplacé par Windows 7 et 8. La bibliothèque MSDN ne fournit même plus de documentation pour les versions précédant Windows 2000, rendant difficile le maintien de la compatibilité avec ces versions et cela même si l'effort en valait la peine.

La bibliothèque Win32 n'a pas toujours été la même et GLFW 3 utilise plusieurs fonctions uniquement disponibles à partir de Windows XP. Même le support d'un système d'exploitation aussi récent que XP (récent par rapport à GLFW 2 qui supporte toujours Windows 95) nécessite la vérification à l'exécution de la présence d'un certain nombre de fonctions qui ne sont présentes que dans les versions modernes de Windows.

II-U - Capture globale des raccourcis clavier

La possibilité de désactiver ou de capturer les raccourcis clavier globaux du système comme Alt + Tab a été retirée. Les applications modernes, que ce soit les jeux, les visualisations scientifiques ou autres devraient être de nos jours de bons citoyens et permettre le fonctionnement de ces raccourcis même lors d'une exécution en mode plein-écran.

II-V - Arrêt automatique

GLFW 3 n'enregistre pas glfwTerminate avec atexit lors de l'initialisation, car exit appelle les fonctions enregistrées à partir du thread appelant et bien qu'il soit permis d'appeler exit à partir de n'importe quel thread, glfwTerminate ne peut être appelé qu'à partir du thread principal.

Pour libérer toutes les ressources allouées par GLFW, vous devez appeler vous-même glfwTerminate, à partir du thread principal, avant la fermeture du programme. Notez que cela détruit toutes les fenêtres qui n'ont pas encore été détruites avec glfwDestroyWindow, invalidant n'importe quel identifiant de fenêtre que vous pourriez conserver.

II-W - Inclusion du fichier d'en-tête de GLU

GLFW 3 n'inclut pas par défaut le fichier d'en-tête GLU et GLU elle-même a été dépréciée par Khronos. Les nouveaux projets doivent éviter d'utiliser GLU, mais si vous devez compiler un ancien code qui a été migré vers GLFW 3, vous pouvez faire en sorte que le fichier d'en-tête de GLFW 3 l'inclue en définissant GLFW_INCLUDE_GLU avant l'inclusion du fichier d'en-tête de GLFW 3.

Ancienne syntaxe

#include <GL/glfw.h>

Nouvelle syntaxe

#define GLFW_INCLUDE_GLU
#include <GLFW/glfw3.h>

III - Changement de noms

III-A - Fonctions renommées

GLFW 2

GLFW 3

Notes

glfwOpenWindow

glfwCreateWindow

Tous les canaux de bits de profondeur sont maintenant des indices.

glfwCloseWindow

glfwDestroyWindow

glfwOpenWindowHint

glfwWindowHint

Accepte maintenant tous les symboles GLFW_*_BITS.

glfwEnable

glfwSetInputMode

glfwDisable

glfwSetInputMode

glfwGetMousePos

glfwGetCursorPos

glfwSetMousePos

glfwSetCursorPos

glfwSetMousePosCallback

glfwSetCursorPosCallback

glfwSetMouseWheelCallback

glfwSetScrollCallback

Accepte des décalages dans le défilement sur deux dimensions en tant que double.

glfwGetJoystickPos

glfwGetJoystickAxes

glfwGetWindowParam

glfwGetWindowAttrib

glfwGetGLVersion

glfwGetWindowAttrib

Utilise GLFW_CONTEXT_VERSION_MAJOR, GLFW_CONTEXT_VERSION_MINOR et GLFW_CONTEXT_REVISION.

glfwGetDesktopMode

glfwGetVideoMode

Retourne le mode actuel d'un écran.

glfwGetJoystickParam

glfwJoystickPresent

Les axes et les boutons sont fournis par glfwGetJoystickAxes et glfwGetJoystickButtons.

III-B - Tokens renommés

GLFW 2

GLFW 3

Notes

GLFW_OPENGL_VERSION_MAJOR

GLFW_CONTEXT_VERSION_MAJOR

Renommé, comme cela s'applique aussi à OpenGL ES.

GLFW_OPENGL_VERSION_MINOR

GLFW_CONTEXT_VERSION_MINOR

Renommé, comme cela s'applique aussi à OpenGL ES.

GLFW_FSAA_SAMPLES

GLFW_SAMPLES

Renommé pour correspondre à la bibliothèque OpenGL.

GLFW_ACTIVE

GLFW_FOCUSED

Renommé pour correspondre au callback de focus de fenêtre.

GLFW_WINDOW_NO_RESIZE

GLFW_RESIZABLE

La valeur par défaut a été inversée.

GLFW_MOUSE_CURSOR

GLFW_CURSOR

Utilisé avec glfwSetInputMode.

GLFW_KEY_ESC

GLFW_KEY_ESCAPE

GLFW_KEY_DEL

GLFW_KEY_DELETE

GLFW_KEY_PAGEUP

GLFW_KEY_PAGE_UP

GLFW_KEY_PAGEDOWN

GLFW_KEY_PAGE_DOWN

GLFW_KEY_KP_NUM_LOCK

GLFW_KEY_NUM_LOCK

GLFW_KEY_LCTRL

GLFW_KEY_LEFT_CONTROL

GLFW_KEY_LSHIFT

GLFW_KEY_LEFT_SHIFT

GLFW_KEY_LALT

GLFW_KEY_LEFT_ALT

GLFW_KEY_LSUPER

GLFW_KEY_LEFT_SUPER

GLFW_KEY_RCTRL

GLFW_KEY_RIGHT_CONTROL

GLFW_KEY_RSHIFT

GLFW_KEY_RIGHT_SHIFT

GLFW_KEY_RALT

GLFW_KEY_RIGHT_ALT

GLFW_KEY_RSUPER

GLFW_KEY_RIGHT_SUPER

IV - Remerciements

Cet article est une traduction autorisée dont le texte original peut être trouvé sur le site officiel de GLFW.