Migrer de GLFW 2 à GLFW 3.1

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.

#include <GL/glfw.h>

#include <GLFW/glfw3.h>

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.

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.

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.

void GLFWCALL callback_function(...);

void callback_function(...);

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.

glfwSetWindowTitle("New Window Title");

glfwSetWindowTitle(window, "New Window Title");

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.

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

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

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.

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

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

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.

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.

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

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

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.

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

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).

int GLFWCALL window_close_callback(void);

void window_close_callback(GLFWwindow* window);

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.

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.

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 ü.

void GLFWCALL character_callback(int character, int action);

void character_callback(GLFWwindow* window, int character);

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.

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.

void GLFWCALL mouse_wheel_callback(int position);

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

Fonctions supprimées :

glfwGetMouseWheel.

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.

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.

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.

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.

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.

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.

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.

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.

#include <GL/glfw.h>

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