Guide de portage du Microsoft Game Development Kit pour XBOX One
Cette rubrique présente les techniques de portage d’une base de code existante vers la plateforme Microsoft Game Development Kit (GDK) pour XBOX. Pour les développeurs qui travaillent déjà sur XBOX One, la plupart des sous-systèmes leur seront familiers, même si la conception des API est différente. Certains domaines, comme les graphismes Direct3D, sont en grande partie inchangés. Cette rubrique fournit une vue d’ensemble du processus de portage global, des liens vers des domaines spécifiques, ainsi que quelques astuces et conseils pour éviter les pièges courants. Vous avez des commentaires sur ce guide ? Faites-nous en part sur le forum des développeurs du Microsoft Game Development Kit (GDK). Si vous développez un nouveau titre avec la plateforme Microsoft Game Development Kit (GDK) plutôt que de porter un titre existant, consultez Développement d’un nouveau titre avec le GDK.À propos du Microsoft Game Development Kit (GDK)
Vous, nos partenaires de développement de jeux, avez fourni à l’équipe Gaming de Microsoft de précieux commentaires sur ce que nous faisons bien et sur ce que nous devons améliorer. Notre objectif principal pour le Microsoft Game Development Kit (GDK) est de répondre directement à vos commentaires et de faire en sorte que vous puissiez :- Continuer à développer des jeux exactement comme vous le faites aujourd’hui
- Partager facilement autant de code que possible entre toutes les initiatives et tous les programmes Microsoft Gaming : nos consoles et PC d’aujourd’hui, et nos consoles et XBOX Game Streaming de demain
- Faire confiance à nos outils et plateformes de développement pour offrir un environnement rapide, fiable et centré sur les développeurs
- Tirer parti des nouveaux services et expériences multiplateformes aussi rapidement et facilement que possible
Sommaire
- Planification de votre projet de portage
- Environnement de développement
- Démarrage de l’application
- Initialisation des applications
- Boucle de messages Windows
- Création des périphériques Direct3D
- Présentation
- Gestion de la durée de vie des processus (PLM)
- Gestion de la mémoire
- Modèle de programmation
- Shaders HLSL
- Gestion des utilisateurs
- Mise en réseau et intégration des services XBOX
- Étapes suivantes
- Conseils et astuces
- Compatibilité binaire et réutilisation des composants
- Style de codage et bonnes pratiques
- Voir aussi
Pour les besoins de ce guide de portage, nous partons du principe que vous ciblez les plateformes Gaming.Xbox.XboxOne.x64 et/ou Gaming.Xbox.Scarlett.x64. Le Microsoft Game Development Kit (GDK) inclut également la plateforme Gaming.Desktop.x64. Il s’agit d’une variante de la plateforme Win32 x64 standard, qui n’est pas traitée dans ce guide de portage.L’intérêt principal de Gaming.Desktop.x64 est d’offrir une expérience similaire à Gaming.Xbox.*.x64 en matière de paramètres de build, d’intégration à Visual Studio, de comportement de disposition libre, etc., lorsque vous ciblez le PC. Vous pouvez également utiliser la plateforme x64 « standard » et implémenter tous les paramètres et l’empaquetage directement pour le PC.
Planification de votre projet de portage
Lorsque vous portez une base de code existante vers le Microsoft Game Development Kit (GDK), vous partez généralement d’un projet XBOX One Software Development Kit existant ou d’une application de bureau Win32 classique. De nombreux développeurs ayant un titre XBOX One existant constateront que leur base de codeDurango constitue un meilleur point de départ, à condition que l’utilisation des API Windows Runtime soit relativement isolée. Les bases de code de bureau Win32 classiques sont bien plus proches du modèle de programmation du Microsoft Game Development Kit (GDK), mais supposent souvent une interface utilisateur et des schémas de contrôle centrés sur le bureau qui doivent être modifiés pour la console. Les bases de code de bureau Win32 classiques ont également tendance à comporter beaucoup d’intégration propre au bureau, en particulier lorsqu’elles font partie de la suite d’outils d’édition du jeu qui utilise des ensembles d’API non pris en charge pour le Microsoft Game Development Kit (GDK) sur XBOX. Chaque point de départ a ses avantages et ses inconvénients. Dans certains cas, il peut être plus simple de puiser dans les deux types pour différentes parties de votre base de code.
Portage depuis le XBOX One Software Development Kit
Si votre base de code prend déjà en charge XBOX One via le XBOX One Software Development Kit (également appelé plateformeDurango), vous avez déjà effectué l’essentiel du travail de modernisation de l’utilisation des API de votre application. Le code devrait également être bien optimisé pour les contraintes spécifiques de la console, et utilise probablement de manière significative les extensions propres à XBOX One, comme suit.
- DirectX 12.X est obligatoire. Si vous utilisez déjà DirectX 12.X pour votre titre XBOX One, aucune modification ne devrait être nécessaire en dehors de l’API de présentation pour votre utilisation de Direct3D.
Si vous utilisez actuellement DirectX 11.X, effectuez d’abord la mise à niveau vers DirectX 12.X. Cela peut être plus facile à faire avec votre build XBOX One Software Development Kit existante avant de passer au Microsoft Game Development Kit (GDK). Pour plus de détails, consultez ces rubriques : Portage de Direct3D 11 vers Direct3D 12 et la présentation Xfest Introduction to Direct3D 12 on XBOX One (XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos), ainsi que la présentation Xfest Porting from Direct3D 11 to Direct3D 12 (XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos).
- Au lieu d’utiliser une chaîne de permutation DXGI, votre logique de présentation doit utiliser l’API PresentX.
- Des modifications importantes ont été apportées au sous-système de mémoire du Game OS du Microsoft Game Development Kit (GDK). Revoyez l’implémentation de votre gestionnaire de mémoire.
- Pour l’entrée des manettes, utilisez la nouvelle API GameInput plutôt que
Windows.Xbox.Input. - Comme les API Windows Runtime ne sont plus utilisées dans la plupart des scénarios, remplacez votre code C++/CX ou C++/WinRT existant par les nouvelles API COM de style Win32 ou DirectX.
- Les fonctionnalités Core Audio sont inchangées. Toutefois, certaines modifications d’API peuvent être nécessaires, comme indiqué dans la comparaison des API audio. XAudio2 avec les extensions XMA, WASAPI et
ISpatialAudioClientsont pris en charge. - Lors de la génération dans Visual Studio, ajoutez les configurations de plateforme
Gaming.Xbox.XboxOne.x64et/ouGaming.Xbox.Scarlett.x64à la place de vos configurations de plateformeDurango, et effectuez la mise à niveau vers Visual Studio 2019 ou Visual Studio 2022.
Pour faciliter l’ajout de nouvelles configurations de plateforme, nous avons créé un exemple appelé SolutionUpdater. Cet outil d’exemple prend un fichier de solution Visual Studio existant et crée automatiquement les nouvelles configurations de plateforme pour tous les fichiers de projet associés référencés par la solution, ce qui accélère considérablement le processus et réduit les risques d’erreurs manuelles. Pour plus d’informations, consultez le document fourni avec l’exemple.
Si votre base de code prend en charge le modèle d’application de la plateforme Windows universelle (UWP), votre chemin de portage est semblable à celui depuis le XBOX One Software Development Kit.
Portage depuis le bureau Win32 classique
Si votre base de code prend uniquement en charge le bureau Win32 classique, le processus de portage peut être assez conséquent, selon l’âge de la base de code par rapport aux API dépréciées et aux autres fonctionnalités. Gardez à l’esprit que les bases de code de bureau Win32 classiques peuvent couvrir un très large éventail d’API remontant jusqu’à l’ère Windows 9x/ME. Cette liste n’est pas exhaustive quant à tous les problèmes potentiels que vous pourriez rencontrer. Lorsque vous ciblez XBOX, vous aurez également les considérations habituelles liées au portage du PC vers la console : interface utilisateur, modèles d’entrée, affichage à résolution fixe, mémoire limitée, etc.- Le code natif x64 est obligatoire. Pour plus d’informations, consultez Programmation 64 bits pour les développeurs de jeux.
- DirectX 12.X est obligatoire. DirectX 11, Direct3D 10, Direct3D 9 ou les versions antérieures ne peuvent pas être utilisés. En outre, OpenGL et Vulkan ne sont pas pris en charge. Pour plus de détails, consultez les guides de portage pour DirectX11 et DirectX12.
- Les composants hérités du DirectX SDK D3DX9, D3DX10, D3DX11 et XACT ne peuvent pas être utilisés. Pour plus d’informations, consultez Microsoft Docs, Where is the DirectX SDK (2021 Edition)?, Living without D3DX et The Zombie DirectX SDK.
WINAPI_FAMILY_GAMESest un sous-ensemble de la famille complète d’API Win32. Limitez-vous à ces API.- L’empaquetage AppX est obligatoire. Mettez à jour votre processus d’empaquetage et de déploiement.
- Pour l’entrée des manettes, utilisez la nouvelle API GameInput plutôt que
Windows.Gaming.Inputou DirectInput. - Pour l’audio, utilisez XAudio2, WASAPI, ISpatialAudioClient ou un middleware audio compatible.
- Supprimez toute utilisation du Registre.
- Le traitement des messages
WndProcdoit être réduit. De nombreux messages, en particulier ceux qui concernent le positionnement, le dimensionnement des fenêtres et l’intégration à l’interpréteur de commandes, ne s’appliquent pas au Microsoft Game Development Kit (GDK) sur XBOX. - Si vous générez avec Visual Studio, mettez à niveau votre code pour qu’il fonctionne avec Visual Studio 2019 ou Visual Studio 2022. Sinon, assurez-vous que votre build utilise les nouvelles définitions de préprocesseur et effectue l’édition de liens avec les bibliothèques de
GXDK\gameKit\lib\amd64, comme la bibliothèque globalexgameplatform.lib. - Pour les composants COM, seul le modèle de thread MTA (multithreaded apartment) est pris en charge. Notez que
COINITBASE_MULTITHREADEDest typique d’une application Direct3D. - Une seule instance de fenêtre est prise en charge. Les instances de fenêtre ou boîtes de dialogue simultanées multiples ne sont pas prises en charge.
Environnement de développement
Visual Studio 2019 (mise à jour 16.11) ou Visual Studio 2022 est l’environnement de développement pris en charge pour le Microsoft Game Development Kit (GDK). Installez les éléments suivants :- Charge de travail : Développement de jeux en C++ pour l’ensemble d’outils de base
- Charge de travail : Développement UWP pour les outils d’empaquetage.
- Charge de travail (facultative) : Développement Desktop en C++ pour les outils et exemples côté PC.
Le développement XBOX One Software Development Kit avec Visual Studio 2017 nécessitait également le composant facultatif Windows 8.1 SDK and UCRT SDK. Ce composant n’est pas requis pour le Microsoft Game Development Kit (GDK).Si vous utilisez encore Visual Studio 2015 ou une version antérieure, la première étape de votre portage consiste à effectuer la mise à niveau vers Visual Studio 2019 ou une version ultérieure.
Plateforme Visual Studio
Le Microsoft Game Development Kit (GDK) s’intègre à Visual Studio pour fournir les plateformesGaming.Xbox.XboxOne.x64 et Gaming.Xbox.Scarlett.x64 permettant de cibler le Game OS Microsoft GDK sur XBOX. Elles remplacent la plateforme Durango du XBOX One Software Development Kit.
Solutions de build personnalisées
Pour générer du code en dehors de Visual Studio, les variables d’environnement d’aide pour les emplacements ont été modifiées. XBOX One Software Development Kit :Dans l’exemple de chemin ci-dessus, build_number représente la build installée sur votre système (par exemple 190700).
%GameDKLatest%\GXDK\gameKit contient tous les en-têtes et bibliothèques des extensions propres à la console, ainsi que la bibliothèque globale principale de la plateforme pour l’édition de liens d’un binaire Microsoft Game Development Kit (GDK). %GameDKLatest%\GRDK\gameKit contient de même les en-têtes et bibliothèques de toutes les fonctionnalités qui ne sont pas propres au développement sur console. Le Microsoft Game Development Kit (GDK) nécessite l’installation du Windows 10 SDK (10.0.19041.0) ou d’une version ultérieure en tant que dépendance. Certains en-têtes et bibliothèques supplémentaires sont disponibles dans %GameDKLatest%\GXDK\toolKit pour les outils de console côté PC.
Depuis la version d’octobre 2023, le Windows 11 SDK (10.0.22000.0) est la version minimale prise en charge.Il existe également un certain nombre d’options et de définitions que vous devez utiliser. Consultez Recommandations relatives aux commutateurs du compilateur et de l’éditeur de liens Visual C++ pour tous les détails, ainsi que l’exemple CMakeExample.
Compilateur (cl.exe)
/D_GAMING_XBOXremplace à la fois/D_XBOX_ONE /D_TITLEet/D_DURANGO./D_GAMING_XBOX_XBOXONEest défini uniquement pour la plateformeGaming.Xbox.XboxOne.x64./D_GAMING_XBOX_SCARLETTest défini uniquement pour la plateformeGaming.Xbox.Scarlett.x64./DWINAPI_FAMILY=WINAPI_FAMILY_GAMEScontrôle le partitionnement des API à la place de la famille d’APIWINAPI_FAMILY_TV_TITLE.- Vous devez définir
/DWIN32_LEAN_AND_MEAN,/D_ATL_NO_DEFAULT_LIBSet/D__WRL_NO_DEFAULT_LIB__ - Pour le Microsoft Game Development Kit (GDK), vous n’utilisez plus aucun commutateur Windows Runtime tel que
/AI,/FUou/ZW. - Continuez à utiliser
/favor:AMD64,/EHscet/fp:fast. - Pour la plateforme
Gaming.Xbox.XboxOne.x64, continuez à utiliser/arch:AVX - Pour la plateforme
Gaming.Xbox.Scarlett.x64, utilisez/arch:AVX2
Avec VS 2019 Update 3 ou une version ultérieure et la plateformeGaming.Xbox.Scarlett.x64, utilisez également/d2vzeroupper. Si vous utilisez l’optimisation de l’ensemble du programme (WPO) / la génération de code au moment de l’édition de liens (LTCG), il faut utiliser/d2:-vzeroupper.
Avec VS 2022 et la plateformeGaming.Xbox.XboxOne.x64, utilisez également/d2vzeroupper-. Si vous utilisez l’optimisation de l’ensemble du programme (WPO) / la génération de code au moment de l’édition de liens (LTCG), il faut utiliser/d2:-vzeroupper-.
Éditeur de liens (link.exe)
- Effectuez l’édition de liens avec
xgameplatform.lib,xgameruntime.lib,d3d12_x.liboud3d12_xs.lib,xmem.libetpixevt.lib. N’utilisez paskernel32.lib,kernelx.lib,onecore.libniWindowsApp.lib. - Pour la bibliothèque XGraphics, utilisez
xg_x.libouxg_xs.lib. - Vous n’avez pas besoin d’utiliser
/WINMDou/WINMDFILE, qui servaient aux API Windows Runtime. - Le Microsoft Game Development Kit (GDK) sur XBOX n’utilise pas de manifestes incorporés ; utilisez donc
/MANIFEST:NO. - Continuez à utiliser
/DYNAMICBASE,/NXCOMPAT.
Envisagez d’utiliser/NODEFAULTLIBpour vous assurer de ne pas effectuer l’édition de liens avec des bibliothèques Win32 non prises en charge, notammentadvapi32.lib comctl32.lib comsupp.lib dbghelp.lib gdi32.lib gdiplus.lib guardcfw.lib kernel32.lib mmc.lib msimg32.lib msvcole.lib msvcoled.lib mswsock.lib ntstrsafe.lib ole2.lib ole2autd.lib ole2auto.lib ole2d.lib ole2ui.lib ole2uid.lib ole32.lib oleacc.lib oleaut32.lib oledlg.lib oledlgd.lib oldnames.lib runtimeobject.lib shell32.lib shlwapi.lib strsafe.lib urlmon.lib user32.lib userenv.lib wlmole.lib wlmoled.lib onecore.lib.
Optimisation de l’utilisation des en-têtes Windows
Le Microsoft Game Development Kit (GDK) utilise l’en-tête standard<Windows.h>. Il est utile de définir les différentes définitions de préprocesseur « lean and mean » en plus de WIN32_LEAN_AND_MEAN, comme mentionné précédemment, afin de limiter le nombre total d’en-têtes système Win32 inclus.
Runtime Visual C++
Avec le XBOX One Software Development Kit, les en-têtes et bibliothèques du runtime Visual C++ faisaient partie du XBOX One Software Development Kit, et les DLL du runtime étaient placées dans le Game OS. Il fallait donc passer à une version plus récente du XBOX One Software Development Kit ou à un niveau de QFE plus récent pour correspondre à la version de mise à jour mineure de Visual Studio utilisée pour générer le code. Avec le Microsoft Game Development Kit (GDK), les DLL du runtime Visual C++ sont incluses dans le package de votre jeu et correspondent à la version de Visual Studio installée localement sur la machine de build.VCRuntime*.dlletmsvcp*.dllsont les DLL du runtime du compilateur Visual C++ et de la bibliothèque C++ standard. Uneucrtbase.dllincluse dans le Game OS est également utilisée.- Pour les builds de débogage, votre package contiendra
VCRuntime*d.dll,msvcp*d.dlletucrbased.dll
Si vous utilisez la ERA Migration Library, vous avez également besoin devccorlib*.dll, qui est utilisée par le compilateur lors de la génération avec/ZW.
AMP n’est pas pris en charge sur XBOX et a été déprécié dans la dernière version de Visual C++.
Démarrage de l’application
Les projets Microsoft Game Development Kit (GDK) utilisent une version simplifiée du démarrage d’application et de la boucle de messages de style bureau Win32, et non les événements CoreWindow de style Windows Runtime. Votre base de code existante devrait comporter l’un des points d’entrée suivants.Développement de bureau Win32
Application XBOX One Software Development Kit ou UWP utilisant C++/CX
Application XBOX One Software Development Kit ou UWP utilisant C++/WinRT
Microsoft Game Development Kit (GDK) sur XBOX
Pour les titres GDK, le point d’entrée est le même que pour le bureau Win32 classique.Initialisation des applications
Une fonction de point d’entrée Win32 typique et très simple ressemble à ceci.- Utilisation minimale de la classe et des styles de fenêtre
- Chaînes UTF-8 plutôt que UTF-16LE
- Initialisation du sous-système Game Runtime
Pour les titres Microsoft Game Development Kit (GDK) sur XBOX, vous ne pouvez avoir qu’une seule fenêtre Win32.
Boucle de messages Windows
Comme de nombreux messages ne s’appliquent pas, les applications Microsoft Game Development Kit (GDK) sur XBOX peuvent utiliser une boucle de messages Win32 très simple.Création des périphériques Direct3D
Les jeux créés avec le Microsoft Game Development Kit (GDK) sur XBOX utilisent l’API Direct3D 12.X, implémentée sous forme de runtime monolithique, exactement comme avec le XBOX One Software Development Kit.
Direct3D 12 et Direct3D 11 standard ne sont pas pris en charge pour les jeux créés avec le Microsoft Game Development Kit (GDK) sur XBOX. Lorsque vous créez un périphérique Direct3D 12 pour DirectX 12.X, utilisez la méthode
D3D12XboxCreateDevice.
API XMem*
Tout appel aux APIXMem* qui utilisent XMEM_GRAPHICS nécessite que le périphérique Direct3D ait été créé avant leur utilisation. Vous pouvez également appeler D3DConfigureVirtualMemory si vous devez effectuer ces appels avant que le périphérique Direct3D n’existe.
Réservation CPU/GPU
Tous les titres Microsoft Game Development Kit (GDK) disposent de toutes les ressources (c’est-à-dire sans réservation GPU pour Kinect) et du septième cœur de processeur. Par défaut, vous obtenez l’équivalent des paramètres de manifeste suivants du XBOX One Software Development Kit.Différences Direct3D entre XBOX One et XBOX Series X|S
L’implémentation du runtime monolithique Direct3D 12.x pour la plateformeGaming.Xbox.XboxOne.x64 est presque identique à l’implémentation de Direct3D 12.x du XBOX One Software Development Kit. Pour votre portage initial vers le Microsoft Game Development Kit (GDK) sur XBOX, cette plateforme est probablement le point de départ le plus simple.
Gaming.Xbox.Scarlett.x64prend en charge jusqu’aux interfaces ID3D12Device8 et ID3D12GraphicsCommandList5, ou leurs versions ultérieures.Gaming.Xbox.XboxOne.x64prend en charge jusqu’à ID3D12Device, ID3D12Device1, ID3D12Device2 et ID3D12GraphicsCommandList.
Gaming.Xbox.Scarlett.x64, il existe des fonctionnalités supplémentaires ainsi que certaines différences dans l’implémentation de Direct3D 12.x.
- Vous devez utiliser une version différente des en-têtes et bibliothèques Direct3D (c’est-à-dire
d3d12_xs.h,d3dx12_xs.h,xg_xs.h,d3d12_xs.lib, etc.). Vous ne pouvez pas mélanger les deux versions de Direct3D 12.x dans le même binaire. - Lorsque le runtime monolithique Direct3D 12.x a été implémenté pour la première fois, il reposait sur le runtime monolithique Direct3D 11.x ; un certain nombre de types Direct3D 11 sont donc définis lors de la génération avec les plateformes
DurangoouGaming.Xbox.XboxOne.x64. Ils ont été supprimés de l’implémentation XBOX Series X|S, si bien que vous pouvez rencontrer des problèmes de build avec toute référence résiduelle à l’en-têted3d11_x.h, aux définitionsD3D11_*, aux classesCD3D11_*ou aux interfacesID3D11*. Vous pouvez les supprimer tout en continuant à générer pour les deux plateformes. - L’ESRAM n’est pas une fonctionnalité des XBOX Series X|S ; les extensions liées à l’ESRAM ne sont donc pas définies pour cette plateforme. Cela signifie également que
xgmemory.h(une aide pour l’utilisation de l’ESRAM) n’est pris en charge que pour la plateformeGaming.Xbox.XboxOne.x64.
Il reste important d’utiliser l’ESRAM sur les appareils XBOX One / XBOX One S pour des performances de rendu optimales. Consultez les exemples SimpleESRAM et AdvancedESRAM.
- Il existe un certain nombre de différences dans les dispositions de la mémoire GPU, en particulier pour les techniques H-tile et C-Mask. Pour plus de détails, consultez les exemples CMaskDecode, HiZDecode, HiStencil et PrimeHTile.
Présentation
Le Microsoft Game Development Kit (GDK) sur XBOX ne prend pas en charge les chaînes de permutation DXGI héritées pour la présentation, mais utilise l’API PresentX. Les nouvelles API PresentX sont conçues pour répondre aux problèmes de latence des chaînes de permutation DXGI et offrent au développeur un contrôle plus direct des mémoires tampons de présentation. Cette API est également conçue pour s’adapter aux futures applications de streaming. La première étape de l’utilisation de PresentX consiste à s’inscrire aux événements de trame après la création du périphérique Direct3D.D3D12_HEAP_FLAG_ALLOW_DISPLAY.
WaitFrameEventX.
DXGI_ERROR_DEVICE_REMOVED et DXGI_ERROR_DEVICE_RESET, qui doivent être gérées pour les jeux PC.
Certaines autres fonctionnalités DXGI associées ont été supprimées, et la fonction ScheduleFrameEventX mentionnée précédemment remplace DXGIXSetFrameNotification du XBOX One Software Development Kit.
Voici le code XBOX One Software Development Kit pour la notification de basculement de trame.
Gestion de la durée de vie des processus (PLM)
Les jeux créés avec le Microsoft Game Development Kit (GDK) sur XBOX utilisent le même modèle de base de gestion de la durée de vie des processus (PLM) que les applications XBOX One XDK et les applications UWP. Les applications s’exécutent en mode non contraint, contraint, suspendu ou arrêté ; autrement dit, aucun code n’est exécuté lors de l’arrêt, et le processus est simplement détruit. Les applications XBOX One Software Development Kit et les applications UWP reçoivent des notifications via leur CoreWindow Windows Runtime. Les jeux Microsoft Game Development Kit (GDK) sur XBOX reçoivent des notifications via des rappels inscrits. Notez qu’il n’existe qu’un événement de suspension et un événement de reprise, et qu’il n’y a plus de phase d’activation explicite. Une approche d’implémentation simple consiste à gérer cela en publiant un messageWM_USER.
WM_USER afin de garantir que la boucle est mise en pause jusqu’à la reprise, et que le comportement de suspension/reprise approprié du GPU a lieu à un moment sûr de la boucle de rendu.
Mode contraint ou complet
La notification des ressources contraintes ou complètes est gérée par une API similaire.Arrêt du processus
Pour les titres commerciaux, l’arrêt du processus est géré de la même manière que pour l’ancienne plateforme XBOX One Software Development Kit. Le processus est suspendu, puis arrêté. Aucun destructeur C++ ni aucun nettoyage n’est exécuté. C’était également le cas si vous appeliezWindows::ApplicationModel::Core::CoreApplication::Exit.
Avec le Microsoft Game Development Kit (GDK), vous pouvez obtenir une sortie propre, comme avec les applications de bureau Win32 classiques, via PostQuitMessage. Votre boucle de messages se termine alors, et le nettoyage normal du code ainsi que la destruction du processus ont lieu. Cela est utile pendant le développement pour détecter les fuites et d’autres problèmes de nettoyage qui seraient autrement difficiles à trouver. Ce comportement invoque toutefois probablement des chemins de code qui ne sont jamais exécutés sur l’ancienne plateforme XBOX One Software Development Kit.
Gestion de la mémoire
Pour plus d’informations sur la gestion de la mémoire, consultez Vue d’ensemble de la mémoire.Modifications du modèle de mémoire
La plateforme Microsoft Game Development Kit (GDK) comprend de nombreuses modifications apportées au modèle de mémoire par rapport au Game OS XBOX One d’origine. L’essentiel de ces efforts a porté sur l’amélioration de l’isolation entre la mémoire utilisée par le titre et celle utilisée par le système. Une meilleure isolation rend l’utilisation de la mémoire plus prévisible entre le titre et le système, et empêche une utilisation inattendue par les appels système. Dans le cadre de ce travail, nous passons à la dernière version du sous-système de gestion de la mémoire de Windows. Bien que de nombreux jeux ne nécessitent pas de modifications majeures, vous devez examiner attentivement votre utilisation de ces API de mémoire. La signification et le comportement des indicateurs ont changé. Si vous allouez et mappez manuellement des pages physiques, gardez à l’esprit que certaines contraintes sur les mappages ont changé et qu’un modèle différent doit être suivi pour les API.- Lorsque des pages physiques sont mappées plus d’une fois dans l’espace d’adressage virtuel, toutes les allocations doivent partager les mêmes paramètres de cohérence du cache. Par exemple, vous ne pouvez pas combiner des paramètres de page Write Combined et des paramètres de page de lecture/écriture CPU normaux sur la même mémoire physique.
- Les paramètres de page et les valeurs de cohérence du cache se trouvent désormais dans la région d’adresses virtuelles dans laquelle les pages sont mappées. Cette région doit être réservée à l’avance en appelant XMemVirtualAlloc et en utilisant le modèle
MEM_RESERVE. Cette étape n’était pas nécessaire dans la version précédente du système d’exploitation.
MEM_LARGE_PAGES. Ses valeurs et sa signification ont changé pour correspondre à celles utilisées dans Windows.
Avec le passage des grandes pages de 4 Mo dans le Game OS XBOX One à 2 Mo dans le système d’exploitation du Microsoft Game Development Kit (GDK) sur XBOX, les spécificateurs de taille XMemAlloc pour les grandes pages sont également passés de
XALLOC_PAGESIZE_4MB à XALLOC_PAGESIZE_2MB.
Notre carte mémoire a également changé et n’est plus segmentée en régions Legacy, Title, Graphics et Physical. Elles couvrent désormais l’ensemble de l’espace d’adressage de 8 To.
Modifications des API
Les API de mémoire du Microsoft Game Development Kit (GDK) commencent par le préfixe XMem et reflètent pour la plupart les API déjà présentes dans le système d’exploitation XBOX One XDK existant, même si leur comportement a changé.
Les nouvelles API sont présentées dans le tableau suivant.
Utiliser XMemVirtualAlloc au lieu de VirtualAlloc
Dans le Microsoft Game Development Kit (GDK), la nouvelle APIXMemVirtualAlloc remplace toutes les utilisations de VirtualAlloc pour l’allocation de mémoire graphique XBOX. Notez les exigences mentionnées précédemment concernant la spécification de la page GPU et de la cohérence du cache pour les réservations ultérieurement associées à des mappages physiques.
Comparaison d’une telle réservation sur le XBOX One Software Development Kit :
Utiliser VirtualFree
La mémoire allouée parVirtualAlloc ou XMemVirtualAlloc est toujours libérée avec VirtualFree. Il n’existe pas d’API XMemVirtualFree.
Utilisation de XMemAlloc
La macro Attributes comporte désormais un paramètre supplémentaire. Par exemple :XMemAllocatePhysicalPages et XMemMapPhysicalPages
Comme les indicateurs de page et la cohérence du cache sont désormais spécifiés au moment de la réservation, les appels d’allocation et de mappage de la mémoire physique sont simplifiés, mais restent par ailleurs semblables à ceux du XBOX One Software Development Kit.XMemAllocatePhysicalPages remplace AllocateTitlePhysicalPages. XMemMapPhysicalPages remplace MapTitlePhysicalPages.
Ce code XBOX One Software Development Kit :
Modèle de programmation
Pour plus d’informations sur le modèle de programmation, consultez la rubrique Modèle de programmation asynchrone.Code synchrone (bloquant) avec GameRuntime
Pour les API pour lesquelles le blocage est une option raisonnable, des versions bloquantes (synchrones) de toutes les fonctionnalités de la bibliothèque ont été fournies, même si les appels sont de longue durée. Le développeur peut créer des threads et appeler les fonctions bloquantes depuis ces threads en utilisant le planificateur pour gérer la concurrence, ce qui est souvent plus simple à implémenter que les futures et promesses de style C++11. Dans certains cas (comme les appels réseau), la durée d’exécution des fonctions est connue pour être non déterministe ; seules des versions asynchrones sont alors fournies.Code asynchrone avec GameRuntime
La plateforme Microsoft Game Development Kit (GDK) inclut un nouveau modèle permettant d’effectuer des tâches asynchrones et de signaler leurs résultats via des rappels. Ce modèle remplace Windows Runtime. Utilisez les API GameRuntime pour spécifier comment et où le travail asynchrone et les rappels ont lieu. L’exemple de code suivant comprend des exemples simples et génériques de configuration d’une file d’attente de tâches Game Runtime pour traiter vos appels système. Cette file d’attente peut être utilisée pour traiter les tâches système et comme emplacement d’exécution des rappels. D’un point de vue conceptuel, un rappel est une tâche qui exécute votre code en réponse à des actions du système. Si nécessaire, vous pouvez créer plusieurs files d’attente de tâches pour gérer le travail sur différents cœurs, ou pour spécifier, appel par appel, la file d’attente qui exécute les rappels. La distribution des éléments de travail en file d’attente peut être pilotée manuellement par votre code (de manière semblable à une file d’attente de messages Windows) ou automatiquement. Voici des exemples simples de création puis de traitement d’une file d’attente pilotée manuellement.Modèle d’affectation de noms général pour les appels d’API asynchrones
Le tableau suivant présente le modèle général utilisé par le Microsoft Game Development Kit (GDK) et le Game Runtime pour nommer les appels asynchrones.XAsyncBlock remplace IAsyncOperation et IAsyncAction
Lorsque vous appelez une fonction asynchrone, créez une structureXAsyncBlock, qui doit rester active pendant toute la durée de l’appel, jusqu’à ce qu’il soit terminé, annulé ou en échec.
Le type XAsyncBlock contient trois paramètres d’intérêt immédiat.
Exemple d’utilisation :
Notez qu’il est essentiel de « remplir de zéros » la structure XAsyncBlock lors de sa création, d’où l’utilisation de{}au lieu de().
Opérations sensibles au temps
Les bibliothèques du Microsoft Game Development Kit (GDK) vous permettent de spécifier si le thread à partir duquel vous effectuez l’appel est sensible au temps. Des avertissements d’exécution peuvent être signalés si vous appelez des fonctions qui ne sont pas sensibles au temps à partir d’un thread sensible au temps.SetTimeSensitiveThread(true) sur ce thread. Vous pouvez également appeler VerifyNotTimeSensitiveThread() dans les fonctions de longue durée de votre propre code pour signaler une utilisation incorrecte depuis des threads critiques en termes de temps.
Shaders HLSL
La plateforme XBOX One Software Development Kit utilisait une version personnalisée du compilateur HLSLFXC.EXE qui prenait en charge la précompilation des shaders programmables Shader Model 5.1 en microcode ATI. En outre, une préversion du compilateur DXIL DXC.EXE pour Shader Model 6 était prise en charge.
Pour le Microsoft Game Development Kit (GDK) sur XBOX, l’utilisation du compilateur DXIL et de Shader Model 6 via DXC.EXE est recommandée. Le compilateur Shader Model 5.1 FXC.EXE est désormais considéré comme hérité. Le nouveau compilateur prend en charge la plupart des indicateurs de ligne de commande pris en charge par l’ancien compilateur, même si certaines defines d’extension propres à XBOX ne sont pas applicables ou ne sont pas prises en charge. Pour plus de détails sur Shader Model 6 et DXIL, consultez le projet GitHub.
Pour l’utilisation de Shader Model 6 sur PC : Windows 10 Creators Update et les versions ultérieures prennent en charge les shaders DXIL Shader Model 6.x, tout comme de nombreux pilotes commerciaux. Au lieu de vous appuyer sur les pilotes WHQL de Windows Update pour cette fonctionnalité, vous devez installer le dernier pilote directement auprès de son fournisseur. Le compilateur
DXC.EXE pour Windows est inclus dans le SDK Windows 10 April 2018 Update et les versions ultérieures. Au moment de l’exécution, vous pouvez déterminer si votre PC prend en charge Shader Model 6.x via CheckFeatureSupport en utilisant D3D12_FEATURE_SHADER_MODEL, mais veillez à initialiser shaderModel.HighestShaderModel avant d’appeler la fonction !%GameDKLatest%\GXDK\bin\XboxOne\DXC.exe.
La version XBOX Series X|S du compilateur DXIL se trouve ici : %GameDKLatest%\GXDK\bin\Scarlett\DXC.exe.
API D3DCompile
Pour Shader Model 6, vous devez utiliser la bibliothèquedxcompiler_x.lib ou dxcompiler_xs.lib plutôt que d3dcompiler_x.lib.
Gestion des utilisateurs
Le modèle utilisateur du Microsoft Game Development Kit (GDK) a changé par rapport à celui auquel vous êtes peut-être habitué dans le XBOX One Software Development Kit. Ce changement vise en partie à mieux répondre aux attentes des utilisateurs en matière de confidentialité et à alléger la charge consistant à suivre en permanence ce que fait le système en arrière-plan avec des utilisateurs dont le titre ne devrait pas se soucier. Au lieu que les titres surveillent une collection à l’échelle du système indiquant quels utilisateurs et invités sont connectés à la console, le système expose uniquement les utilisateurs à la demande. Pour acquérir un utilisateur pour votre titre (par exemple, lorsque l’utilisateur appuie sur le bouton A d’une manette pour démarrer une session de jeu et que la manette n’est pas encore associée à un utilisateur), appelez XUserAddAsync. Cet appel effectue deux actions importantes : il connecte les utilisateurs au titre et met à jour l’association des périphériques d’entrée aux utilisateurs. Un nombre quelconque de périphériques d’entrée peut être associé à un utilisateur à un moment donné. Toutefois, le titre n’est informé que des associations des utilisateurs connectés avec XUserAddAsync. Si le Guide du système est utilisé pour connecter un utilisateur ou modifier des associations en dehors du titre au profit d’un utilisateur que le titre ne connaît pas, le titre est uniquement informé que le périphérique d’entrée a été dissocié. Le système, en dehors du titre, a toutefois toujours connaissance de l’association pour son propre usage. Les titres peuvent surveiller les modifications de l’état d’un utilisateur ou des informations associées à un utilisateur (comme son gamertag, son image de joueur ou ses privilèges) en s’abonnant àXUserChangeEvent (même si certaines de ces informations, comme l’état de connexion de l’utilisateur, peuvent être surveillées par interrogation). Pour cela, appelez XUserRegisterForChangeEvent.
La plupart des titres doivent s’attendre à devoir créer leur propre collection d’utilisateurs, suivre le moment où les utilisateurs se connectent au titre, suivre les associations de périphériques d’entrée et gérer la déconnexion des utilisateurs.
Pour une présentation approfondie de ces modifications, consultez Utilisateurs et périphériques d’entrée. Consultez également l’exemple UserManagement.
Mise en réseau et intégration des services XBOX
Transport réseau
Le Microsoft Game Development Kit (GDK) sur XBOX prend en charge WinSock2 et BCrypt via CNG. Si vous utilisez UDP, au lieu de coder en dur un port tel que 3074 pour la liaison de votre socket multijoueur, vous devez, pour le Microsoft Game Development Kit (GDK), utiliser cette nouvelle API C plate :Windows.Networking.Connectivity. Pour obtenir un exemple de code, consultez Initialisation et connectivité réseau.
Les sockets sécurisés (espace de noms
Windows.Xbox.Networking) ont été supprimés du Microsoft Game Development Kit (GDK).Requêtes web via HTTP
Le Microsoft Game Development Kit (GDK) ne prend plus en chargeIXMLHTTPRequest2 ni MessageWebSocket / StreamWebSocket (espace de noms Windows.Networking.Sockets). Utilisez plutôt WinHTTP.
Pour plus de détails, consultez Requêtes web.
API des services XBOX
Les développeurs qui utilisent actuellement les versions Windows Runtime ou C++ de XSAPI devront passer à la version C plate pour les fonctionnalités d’intégration des services XBOX :- Succès
- Présence
- Profil
- Social
- Social Manager
Étapes suivantes
Une fois votre portage initial depuis l’ERA terminé, vous serez bien placé pour activer un certain nombre de fonctionnalités du Microsoft Game Development Kit (GDK) sur XBOX. Si votre titre fonctionne bien sur le matériel XBOX One S / XBOX One X, voici des moyens simples d’améliorer l’expérience sur les consoles XBOX Series X|S. Notez que bon nombre de ces fonctionnalités sont activées automatiquement pour les titres ERA hérités, mais doivent être activées explicitement pour les titres Microsoft Game Development Kit (GDK) sur XBOX. Maintenant que votre titre est un titre Microsoft Game Development Kit (GDK) natif sur XBOX, n’oubliez pas de les activer !- AutoHDR : cette fonctionnalité convertit automatiquement un titre SDR en HDR au niveau du système, ce qui améliore la qualité visuelle du jeu lorsqu’il est joué sur un écran compatible HDR10. Elle utilise du matériel propre aux XBOX Series X|S ; il n’y a donc aucun coût supplémentaire en CPU, GPU, mémoire, bande passante ou latence. L’amélioration visuelle ne modifie pas l’intention artistique d’origine et étend la luminosité jusqu’à 1 000 nits et les couleurs dans l’espace colorimétrique P3-D65. Une implémentation HDR native sera toujours meilleure, car elle permet un contrôle artistique complet, mais si vous n’avez pas les ressources ou le temps d’implémenter le HDR natif, AutoHDR est un moyen simple et efficace d’obtenir une expérience améliorée.
- Aniso Boost : une amélioration de la qualité d’image sur les consoles XBOX Series X|S est obtenue en promouvant le filtrage de texture linéaire en filtrage anisotrope complet. C’est un moyen simple et rapide d’exploiter la puissance GPU supplémentaire dans un titre existant. En tant que titre Microsoft Game Development Kit (GDK) sur XBOX, vous y parvenez en utilisant le paramètre
D3D12_FILTER_ANISOTROPICpour vos états d’échantillonneur au lieu deD3D12_FILTER_MIN_MAG_MIP_LINEARlors de l’exécution sur XBOX Series X|S :
- FPS Boost : une autre amélioration simple consiste à augmenter la fréquence d’images de rendu sur les consoles XBOX Series X|S. Si votre titre s’exécute à 30 fps sur XBOX One S / XBOX One X (
D3D12XBOX_FRAME_INTERVAL_30_HZ), il peut généralement s’exécuter à 60 fps sur XBOX Series X|S (D3D12XBOX_FRAME_INTERVAL_60_HZ). S’il s’exécute à 60 fps sur XBOX One S/X, il peut probablement s’exécuter à 120 fps sur XBOX Series X|S. Pour plus d’informations, consultez Prise en charge de 120 Hz et l’exemple Simple120Hz.
En plus de l’augmentation de la fréquence d’images, vous pouvez probablement aussi effectuer le rendu en 4K sur XBOX One X et XBOX Series X avec les mêmes performances qu’en 1080p sur XBOX One S / XBOX Series S.
- Quick Resume : cette fonctionnalité est en grande partie automatique, à condition que votre titre implémente correctement la gestion du cycle de vie des processus (PLM). Pour plus de détails, consultez Cycle de vie des jeux XBOX.
Conseils et astuces
Fichier d’empaquetage Microsoft Game Config
Le Microsoft Game Development Kit (GDK) n’utilise plus de fichierPackage.appxmanifest dans la chaîne d’outils de build Visual Studio pour générer AppxManifest.xml. À la place, un fichier MicrosoftGameConfig est utilisé pour regrouper tous les paramètres du package d’application au moment du développement.
Executable Name doit correspondre au nom de l’EXE dans la disposition du package.
Notez que vous pouvez créer un nouveau projet à l’aide de Visual Studio. Sélectionnez Fichier, Nouveau projet, puis sélectionnez le modèle Direct3D 12 XBOX Game du Microsoft Game Development Kit (GDK). Vous pouvez ensuite ajouter à votre projet le fichier MicrosoftGame.config créé par le modèle.
Vous pouvez également ajouter les différentes ressources liées à l’interface utilisateur et au Store, qui doivent être présentes dans le package, en ajoutant une section <ShellVisuals>.
Notez que le XBOX One Software Development Kit comportait un élément WideLogo ; celui-ci est désormais référencé en tant qu’attribut Square480x480Logo.
Pour l’intégration des services XBOX, vous devez également fournir un ID de titre.
.config. Pour une définition complète des options autorisées, consultez Fichier MicrosoftGameConfig.
Obtention du type d’appareil
La méthode GetConsoleType du XBOX One Software Development Kit n’est pas disponible pour le Microsoft Game Development Kit (GDK). Utilisez plutôt l’API GameRuntime XSystemGetDeviceType.Remplacement GDK de xdk.h et _XDK_VER
Dans le XBOX One Software Development Kit, l’en-tête xdk.h fournissait un certain nombre de symboles de build liés au numéro de build du XDK, au niveau de QFE, etc.
Pour les plateformes Gaming.*.x64, vous pouvez utiliser grdk.h :
_GRDK_VERest l’encodage de la version du Gaming GDK utilisée pour générer le binaire (HIWORD.LOWORD). Par exemple,0x4A610479correspond au numéro de build 19041.1145._GRDK_VER_STRINGpour cette build est « April 2020 GRDK »._GRDK_VER_STRING_West la chaîne étendue UTF16-LE équivalente à_GRDK_VER_STRING._GRDK_VER_STRING_COMPACT_Wpour cette build est une chaîne étendue UTF16-LE contenant « April 2020 ».
Gaming.Xbox.*.x64, vous pouvez également utiliser gxdk.h :
_GXDK_VERest l’encodage de la version du Gaming GDK utilisée pour générer le binaire (HIWORD.LOWORD). Par exemple,0x4A610479correspond au numéro de build 19041.1145._GXDK_VER_STRINGpour cette build est « April 2020 GXDK »._GXDK_VER_STRING_West la chaîne étendue UTF16-LE équivalente à_GXDK_VER_STRING._GXDK_VER_STRING_COMPACT_Wpour cette build est une chaîne étendue UTF16-LE contenant « April 2020 ».
Obtention de l’ID du point de terminaison de rendu audio par défaut
Les API Windows Runtime Windows.Media.Devices et Windows.Devices.Enumeration ne sont pas utilisées pour le Microsoft Game Development Kit (GDK) sur XBOX. Pour obtenir le moteur de rendu par défaut, utilisez le code suivant.MapVirtualKey
Les méthodesMapVirtualKey et MapVirtualKeyEx ne sont pas prises en charge pour le Microsoft Game Development Kit (GDK) sur XBOX. Elles sont le plus souvent utilisées pour détecter les touches VK_SHIFT gauche et droite dans le code qui gère le clavier.
MultiByteToWideChar et WideCharToMultiByte
Pour convertir des chaînes de caractères étendus (UTF-16 LE) en chaînes de caractères étroits et inversement, les développeurs Win32 utilisent souvent MultiByteToWideChar et WideCharToMultiByte. Pour les bases de code modernes, nous vous recommandons d’utiliserCP_UTF8 au lieu d’une page de codes spécifique ou de CP_ACP.
Le code suivant fonctionne sur Windows 7 Service Pack 1 et les versions ultérieures.
CP_ACP est traité comme un alias de CP_UTF8. Sur Windows 10 moderne et avec le Microsoft Game Development Kit (GDK), vous pouvez généralement remplacer toutes les occurrences de CP_ACP par CP_UTF8 à l’aide de la fonction Rechercher et remplacer. Pour simplifier ce type de portage, la validation des autres paramètres liés à CP_UTF8 a été supprimée.
C++11 a ajouté l’en-tête <codecvt> comme solution plus portable au problème de la conversion des chaînes, mais il a déjà été déprécié dans C++17. Il est recommandé de s’en tenir aux fonctions de chaîne de la plateforme.
API de localisation et de globalisation
Dans l’ERA, la majeure partie de la prise en charge intégrée de Windows pour la localisation, au-delà de la simple sélection de la page de codes, de la traduction des points de code (la conversion de caractères multioctets en caractères étendus) et du signalement des paramètres régionaux système/utilisateur, était absente. Pour le Microsoft Game Development Kit (GDK), cette fonctionnalité de localisation est entièrement prise en charge, tout commeGetCurrencyFormatEx, GetNumberFormatEx, l’énumération des formats de date et d’heure, et d’autres fonctionnalités.
Remarques sur l’audio XMA2
Si la définition deSHAPE_XMA_INPUT_BUFFER_ALIGNMENT est manquante, vous devez ajouter explicitement une référence à l’en-tête shapexmacontext.h.
Prise en charge des boîtes de message de l’interface utilisateur
Pour faciliter le débogage des plantages et des échecs d’initialisation précoces dans un titre,XGameUiShowMessageDialogAsync a été ajoutée à la collection d’API d’interface utilisateur appelable par le titre (TCUI). Cette API peut être utilisée à tout moment après l’appel de XGameRuntimeInitialize, même avant l’initialisation de D3D. L’API effectue le rendu dans la partition système et est composée par-dessus la sortie du jeu. Elle fonctionne même si la boucle de jeu est arrêtée ou n’effectue pas encore de rendu. Cela peut être très utile pour signaler des informations d’erreur lors d’un plantage, ou même pour inviter à attacher un débogueur tout en bloquant à l’emplacement de l’erreur. Elle est principalement destinée à servir d’outil de diagnostic pendant le développement.
Cet exemple montre une boîte de dialogue d’erreur bloquante invitant le développeur à attacher un débogueur pour investigation.
Bibliothèques d’extension
Dans le XBOX One Software Development Kit, avec l’utilisation des API Windows Runtime, l’ajout de bibliothèques d’extension comme XSAPI ou Game Chat nécessitait l’utilisation de la boîte de dialogue « Références… » dans Visual Studio. Pour le Microsoft Game Development Kit (GDK), ce mécanisme n’est plus utilisé. Ces bibliothèques peuvent désormais être ajoutées via les propriétés du projet Visual Studio. Cela modifie un élément de propriété dans la section Globals du fichiervcxproj :
Compatibilité binaire et réutilisation des composants
L’un des principes directeurs du Microsoft Game Development Kit (GDK) est de maximiser la capacité des développeurs à réutiliser leur travail entre les titres Windows (bureau) et les titres pour console XBOX. Un aspect non abordé précédemment est le travail effectué pour améliorer la compatibilité binaire entre Windows (bureau) et le système d’exploitation du Microsoft Game Development Kit (GDK) sur XBOX. Contrairement aux titres XBOX One Software Development Kit, le Microsoft Game Development Kit (GDK) sur XBOX peut réutiliser divers composants initialement conçus pour Windows x64 (bureau). Cela peut représenter un gain de temps précieux pour le prototypage, l’outillage ou d’autres scénarios dont les performances ne sont pas critiques. Le Microsoft Game Development Kit (GDK) ne comporte aucun outil permettant de déterminer si un composant Windows (bureau) peut être réutilisé ; cela dépend des API du système d’exploitation consommées par le composant en question. Vous pouvez obtenir les API prises en charge par le système d’exploitation du Microsoft Game Development Kit (GDK) sur XBOX en exécutantdumpbin.exe /exports sur les bibliothèques fournies avec le Microsoft Game Development Kit (GDK). Si certaines API propres à un domaine se trouvent dans leurs propres bibliothèques (comme D3D12XboxCreateDevice dans d3d12_x.lib ou d3d12_xs.lib), la majorité des API Win32 héritées sont regroupées dans une seule bibliothèque nommée xgameplatform.lib. La commande suivante, exécutée à partir d’une invite de commandes développeur Visual Studio, affiche l’ensemble principal des API Win32 prises en charge (hormis celles qui se trouvent dans une autre bibliothèque d’importation).
dumpbin.exe /exports "c:\Program Files (x86)\Microsoft GDK\build_number\GXDK\gameKit\lib\amd64\xgameplatform.lib"
Dans l’exemple de chemin ci-dessus, build_number représente la build installée sur votre système (par exemple 190700).
Style de codage et bonnes pratiques
Les recommandations de Code Generation for XBOX One - Best Practices (XBOX Developer Downloads->XBOX One->All XBOX One XDK CHMs) s’appliquent au Microsoft Game Development Kit (GDK). La principale différence dans les paramètres du compilateur est que ces projets ne nécessitent pas l’utilisation de C++/CX (/ZW) ou de C++/WinRT, car la plupart des API de jeu sont de style Win32 ou COM de style DirectX. Voici quelques recommandations générales :
- Tirez parti de la conformité au langage C++14 et, éventuellement, C++17. Notez que la conception des API du Microsoft Game Development Kit (GDK) suppose un compilateur C++11 ou supérieur.
- Le processus de génération de code à virgule flottante natif x64 utilise toujours SSE/SSE2. XBOX One prend en charge
/arch:AVXainsi que F16C. - La gestion des exceptions C++ (
/EHsc) a peu ou pas de surcharge dans le code natif x64. La levée d’exceptions au moment de l’exécution n’est toutefois pas un scénario performant ; elle ne doit donc pas être utilisée pour contrôler le flux. - L’utilisation de techniques de codage sécurisées vis-à-vis des exceptions, comme celles décrites dans Les objets possèdent des ressources (RAII) et Resource Acquisition Is Initialization, est une bonne pratique vivement recommandée, à l’aide de
std::unique_ptr,Microsoft::WRL::ComPtret d’autres classes de pointeurs intelligents. - Privilégiez l’utilisation de types portables standard comme
size_t,ptrdiff_t,int8_t,uint8_t,int16_t,uint16_t,int32_t,uint32_t,int64_t,uint64_t,intptr_tetuintptr_t. - Pour réduire le remplissage interne, regroupez les pointeurs dans les structures et les classes.
- Au lieu des conversions de type C héritées, privilégiez les conversions C++ comme
const_cast<>,static_cast<>,reinterpret_cast<>etdynamic_cast<>. - Utilisez des intrinsèques dans la mesure du possible. Le code natif x64 ne prend pas en charge l’assembleur inline.
Commutateurs du compilateur et de l’éditeur de liens
Utilisez les commutateurs suivants :/O1 /Oipour l’optimisation générale et/O2pour les modules sollicités/fp:fast/arch:AVXpour la famille d’appareils XBOX One ;/arch:AVX2pour les XBOX Series X|S./favor:AMD- Optimisation de l’ensemble du programme et optimisation guidée par profil
- Commutateurs de l’éditeur de liens
/OPT:REF,ICF
/Ox est presque identique à /O2, mais il lui manque /GF (éliminer les chaînes en double) et /Gy (activer la liaison au niveau des fonctions). Privilégiez /O2 à /Ox. Si vous utilisez /Ox, veillez à activer explicitement au moins /Gy, qui est important pour permettre l’optimisation par l’éditeur de liens.
Un certain nombre de nouveaux commutateurs de compilateur ont également été ajoutés à Visual C++ depuis le lancement du XBOX One Software Development Kit ; renseignez-vous donc à leur sujet : /Zc:inline, /Zc:throwingNew, /Zc:__cplusplus, /volatile:iso, /permissive-, /Zc:twoPhase- et /Debug:FASTLINK.
Code conditionnel
Pour le code conditionnel dont les chemins divergent, gardez à l’esprit les conventions suivantes.
Si votre base de code prend déjà en charge le XBOX One Software Development Kit, voici un bon point de départ :
- Recherchez toutes les occurrences de
_XBOX_ONEdans votre base de code - Modifiez les occurrences comme
#if defined(_XBOX_ONE) && defined(_TITLE)où le code utilise les extensions DirectX 12.X, pour obtenir :
#if (defined(_XBOX_ONE) && defined(_TITLE)) || defined(_GAMING_XBOX)
UTF-8 partout
Au cours de la longue histoire de la plateforme Windows, les fonctions ANSI d’origine ont depuis longtemps été dépréciées au profit de la solution Unicode à caractères étendus, c’est-à-dire CreateFileW plutôt que CreateFileA. Cela a résolu le problème de la gestion d’une multitude de pages de codes différentes et a simplifié toutes les chaînes localisables enwchar_t* (UTF-16 LE, little endian). Le manifeste UTF-8 Everywhere défend l’idée que l’encodage multioctet UTF-8 avec char* est une meilleure solution en termes d’empreinte mémoire et de portabilité.
Pour la plateforme Microsoft Game Development Kit (GDK) sur XBOX, la page de codes par défaut est définie sur CP_UTF8 ; toutes les versions ANSI des API de la plateforme Win32 utilisent donc UTF-8. Vous pouvez continuer à utiliser les API à caractères étendus avec UTF-16 LE, mais vous avez également la possibilité d’utiliser UTF-8.
La prise en charge complète d’UTF-8 dans Windows est un ajout très récent ; elle n’est donc pas encore largement utilisée. Pour l’instant, l’utilisateur doit également l’activer explicitement ; vous constaterez peut-être donc que conserver les API à caractères étendus pour votre utilisation de bas niveau des API Win32 est la meilleure option en matière de portabilité.
- Privilégiez l’utilisation d’UTF-8 dans vos API et convertissez en UTF-16 LE uniquement lors de l’appel des API Win32 à caractères étendus. Au lieu d’utiliser
std::wstringetwchar_t*, utilisezstd::stringetchar*en UTF-8. - Pour les littéraux de chaîne étroits, assurez la conformité à UTF-8 en utilisant le préfixe C++
u8plutôt qu’aucun préfixe ouL. - Conservez les
definesde préprocesseur de buildUNICODEet_UNICODEen place (dans Visual Studio, il s’agit de la propriété<CharSet>) par mesure de sécurité, mais au lieu de vous appuyer sur les macros, appelez toujours explicitement la versionW()ouA(). - Évitez
TCHAR,TEXT(),LPTSTRet les autres types et macros de texte hérités. Pour plus d’informations, consultez Prise en charge d’UTF-8 dans le Microsoft Game Development Kit (GDK).
Convention d’affectation de noms : indications de performances et de comportement
Les API de la plateforme Microsoft Game Development Kit (GDK) sur XBOX ont été conçues de sorte que les noms de fonctions donnent des indications implicites sur les performances des fonctions appelées. Une fonction dont le nom contientGet ou Set est censée avoir une faible surcharge et être prévisible. Elle est également censée offrir à peu près le même niveau de performances qu’une fonction wrapper de propriété C++ appelée à sa place, avec une éventuelle opération memcpy pour copier le résultat. Si une fonction utilisait Query plutôt que Get, cela impliquerait qu’il s’agit d’une opération de longue durée susceptible de bloquer jusqu’à son achèvement.
Pour les fonctions qui effectuent des calculs plutôt que de simples requêtes, nous supposons généralement que leurs performances sont à peu près celles auxquelles vous vous attendriez après avoir examiné leurs paramètres d’entrée et le type d’opérations qu’elles effectuent, sauf indication contraire dans la documentation.
Une fonction dont le nom se termine par Async est une opération asynchrone qui peut prendre un temps très long ou indéterminé. Dans la plupart des cas, nous fournissons des versions bloquantes et asynchrones des fonctions dont l’exécution peut être longue. Nous vous laissons choisir la variante la mieux adaptée à votre base de code. Dans certains cas (comme pour les API réseau), nous pouvons omettre entièrement la version bloquante, car en fournir une n’aurait aucun sens.
Si le nom d’une fonction commence par Show et se termine par Async, la fonction affiche des éléments d’interface utilisateur et nécessite généralement une interaction de l’utilisateur pour se terminer. Dans certains cas, le système peut annuler les opérations d’interface utilisateur.
Voir aussi
- Qu’est-ce que le Microsoft Game Development Kit ?
- Prise en main du Microsoft Game Development Kit (GDK)
