Migrer de GLFW 2 à GLFW 3

Les fonctions de threading ainsi que la fonction de sommeil ont été supprimées. Elles étaient archaïque, 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, l'affichage peut se faire à partir de threads secondaires et la documentation indique explicitement quelles fonctions peuvent être utilisées à partir des threads secondaires et lesquelles ne peuvent être utilisées que dans le thread principal, c'est-à-dire le thread qui appelle la fonction main.

Les fonctions de chargement d'image et de texture 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 ajoutant des fonctionnalités 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 semble inutile de dupliquer ce travail et de l'attacher à GLFW. Les projets similaires à GLFW, tel que FreeGLUT, peuvent aussi bénéficier de telles bibliothèques. De plus, une telle bibliothèque aurait pu être spécifique à une plate-forme, alors que OpenGL et stdio sont disponibles partout où GLFW l'est.

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

La fonction glfwGetMouseWheel a été supprimée. Les événements de défilement ne représentent pas un état absolu, mais une interprétation du changement relatif de l'état, comme les insertions de caractères. Donc, comme pour les insertions de caractères, il n'y a pas d'« état actuel » correct à retourner. 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 deux dimensions.

La macro GLFWCALL, qui faisait utiliser __stdcall aux fonctions callback sous Windows ont été retirées. GLFW est écrite en C, pas en Pascal. Avec la suppression de cette macro, les utilisateurs de GLFW 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.

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 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 (en 2013) 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 de maintenir 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 claviers 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 des bons citoyens et permettre le fonctionnement de ces raccourcis même lors d'une exécution en mode plein-écran.

Le paramètre de fenêtre GLFW_OPENED a été supprimé. Tant que l'objet de fenêtre est présent, la fenêtre est « ouverte ». Pour détecter sa fermeture par l'utilisateur, jetez un œil à la fonction glfwWindowShouldClose et au callback de fermeture.

GLFW 3 ne propage pas automatiquement les événements lors de l'appel à la fonction glfwSwapBuffers, signifiant que vous devez appeler glfwPollEvents ou glfwWaitEvents vous-même. Contrairement à l'échange de tampons, les fonctions de traitement des événements agissent sur toutes les fenêtres à la fois.

GLFW 3 n'enregistre pas glfwTerminate avec atexit lors de l'initialisation. Pour libérer proprement toutes les ressources allouées par GLFW, vous devez dorénavant appeler vous-même glfwTerminate avant la fermeture du programme.

GLFW 3 n'inclut pas le fichier d'en-tête GLU par défaut et GLU elle-même a été dépréciée, mais 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.

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 du type GLFWwindow*, c'est-à-dire un pointeur vers une structure opaque.

GLFW 3 fournit un support des configurations à écrans multiples en ajoutant un type identifiant GLFWmonitor* et un ensemble de fonctions liées. 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. Il y a la fonction glfwGetPrimaryMonitor qui fournit un comportement similaire à cela dans GLFW 2.

La fermeture d'une fenêtre provoquée par l'utilisateur est maintenant un événement comme un autre. Contrairement à GLFW 2, les fenêtres et contextes créés avec GLFW 3 ne disparaîtront pas sous vos pieds. Chaque fenêtre possède maintenant un indicateur de fermeture qui est défini lorsque l'utilisateur tente de la fermer. Par défaut, rien d'autre n'arrive et la fenêtre reste ouverte et visible. C'est alors à vous de détruire la fenêtre, entreprendre tout 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.

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

GLFW lui-même ne nettoie jamais l'indicateur de fermeture, vous permettant de le définir pour d'autres raisons que la fermeture de la fenêtre, par exemple, lorsque l'utilisateur choisi « Quitter » dans le menu principal.

Chaque fenêtre GLFW 3 possède son propre contexte OpenGL et vous seul, l'utilisateur, pouvez connaître quel contexte doit être activé sur quel thread et ce, à n'importe quel moment. Par conséquent, GLFW 3 ne fait aucune hypothèse pour deviner quand vous souhaitez qu'un contexte soit activé, vous laissant cette décision.

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

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 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 sont retournés par les fonctions glfwGetJoystickAxes et glfwGetJoystickButtons.

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.

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.

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

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.