Skip to main content

Guide de portage du Microsoft Game Development Kit pour XBOX One

Cette rubrique présente un aperçu des techniques de portage d’une base de code existante vers la plateforme Microsoft Game Development Kit (GDK) pour XBOX. Pour les développeurs qui développent déjà pour XBOX One, la plupart des sous-systèmes leur seront familiers, bien qu’ils utilisent une conception d’API différente. Certains domaines, comme les graphiques Direct3D, sont en grande partie inchangés. Cette rubrique offre une vue d’ensemble du processus de portage global, des liens vers des domaines précis, ainsi que quelques trucs et astuces pour éviter les pièges courants. Vous avez des commentaires sur ce guide? Faites-nous-en part dans 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 nous assurer que vous pouvez :
  • Continuer à développer des jeux exactement comme vous le faites aujourd’hui
  • Partager facilement le plus de code possible, dans l’ensemble des initiatives et des programmes de Microsoft Gaming : nos consoles et nos PC d’aujourd’hui, ainsi que nos consoles et XBOX Game Streaming de demain
  • Faire confiance à nos outils et plateformes de développement pour offrir un environnement rapide, fiable et axé sur les développeurs
  • Tirer parti des nouveaux services et des nouvelles expériences multiplateformes aussi rapidement et facilement que possible
Nous voulons vous aider à développer votre jeu sur la plateforme de votre choix, en utilisant les paradigmes de programmation que vous utilisez déjà. Nous voulons vous aider à proposer vos jeux sur toutes nos plateformes de jeu qui existent aujourd’hui, sur toutes les plateformes sur lesquelles nous travaillons et qui raviront les joueurs de demain. Pour obtenir des renseignements plus détaillés sur le Microsoft Game Development Kit (GDK), consultez Qu’est-ce que le Microsoft Game Development Kit? et Prise en main du Microsoft Game Development Kit (GDK).

Contenu

Aux fins de ce guide de portage, nous supposerons que vous ciblez les plateformes Gaming.Xbox.XboxOne.x64 et/ou Gaming.Xbox.Scarlett.x64. Le Microsoft Game Development Kit (GDK) comprend également la plateforme Gaming.Desktop.x64. Il s’agit d’une variante de la plateforme x64 Win32 standard, qui n’est pas couverte dans ce guide de portage.La valeur principale de Gaming.Desktop.x64 est d’offrir une expérience semblable à celle de Gaming.Xbox.*.x64 en matière de paramètres de génération, d’intégration à Visual Studio, de comportement de disposition libre (loose layout), 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 soit d’un projet XBOX One Software Development Kit existant, soit d’une application de bureau Win32 classique. De nombreux développeurs ayant un titre XBOX One existant constateront que leur base de code Durango constitue un meilleur point de départ, pourvu que l’utilisation des API Windows Runtime soit relativement isolée. Les bases de code de bureau Win32 classiques sont beaucoup 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 axés sur le bureau qui doivent être modifiés pour la console. Les bases de code de bureau Win32 classiques ont aussi tendance à comporter beaucoup d’intégration axée sur le bureau, particulièrement 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 comporte des avantages et des inconvénients. Dans certains cas, vous trouverez peut-être plus facile de puiser dans les deux types pour différentes parties de votre base de code.

Portage à partir du XBOX One Software Development Kit

Si votre base de code prend déjà en charge la XBOX One au moyen du XBOX One Software Development Kit (aussi appelé plateforme Durango), vous avez déjà effectué la majeure partie du travail de modernisation de l’utilisation des API de votre application. Le code devrait également être bien optimisé pour les contraintes propres à la console, et utilise probablement de façon importante les extensions propres à la XBOX One, comme suit.
  • DirectX 12.X est requis. Si vous utilisez déjà DirectX 12.X pour votre titre XBOX One, aucune modification ne devrait être nécessaire au-delà 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 existant 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 d’échange DXGI, votre logique de présentation doit utiliser l’API PresentX.
  • Des changements importants ont été apportés au sous-système de mémoire pour le Game OS GDK du Microsoft Game Development Kit (GDK). Revoyez l’implémentation de votre gestionnaire de mémoire.
  • Pour l’entrée de manette, 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 de style DirectX.
  • La fonctionnalité Core Audio est inchangée. Cependant, certaines modifications d’API peuvent être nécessaires, comme le décrit la comparaison des API audio. XAudio2 avec les extensions XMA, WASAPI et ISpatialAudioClient sont pris en charge.
  • Lors de la génération dans Visual Studio, ajoutez les configurations de plateforme Gaming.Xbox.XboxOne.x64 et/ou Gaming.Xbox.Scarlett.x64 à la place de vos configurations de plateforme Durango, et effectuez la mise à niveau vers Visual Studio 2019 ou Visual Studio 2022.
Pour faciliter l’ajout de nouvelles configurations de plateforme, nous avons produit 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 grandement le processus et réduit le risque d’erreurs manuelles. Pour plus de renseignements, consultez le document inclus 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 à partir du XBOX One Software Development Kit.

Portage à partir du bureau Win32 classique

Si votre base de code prend en charge uniquement le bureau Win32 classique, le processus de portage pourrait être assez considérable, selon l’ancienneté 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 qui remontent jusqu’à l’ère de Windows 9x/ME. Cette liste n’est pas exhaustive pour tous les problèmes potentiels que vous pourriez rencontrer. Lorsque vous ciblez la XBOX, vous aurez également les considérations habituelles du 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 requis. Pour plus de renseignements, consultez Programmation 64 bits pour les développeurs de jeux.
  • DirectX 12.X est requis. DirectX 11, Direct3D 10, Direct3D 9 ou les versions antérieures ne peuvent pas être utilisés. De plus, 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 de renseignements, consultez Microsoft Docs, Where is the DirectX SDK (2021 Edition)?, Living without D3DX et The Zombie DirectX SDK.
  • WINAPI_FAMILY_GAMES est un sous-ensemble de la famille complète d’API Win32. Limitez-vous à ces API.
  • L’empaquetage AppX est requis. Mettez à jour votre processus d’empaquetage et de déploiement.
  • Pour l’entrée de manette, utilisez la nouvelle API GameInput plutôt que Windows.Gaming.Input ou DirectInput.
  • Pour l’audio, utilisez XAudio2, WASAPI, ISpatialAudioClient ou un intergiciel audio compatible.
  • Supprimez toutes les utilisations du registre.
  • Le traitement des messages WndProc doit être réduit. Bon nombre des messages, particulièrement ceux qui concernent le positionnement, le dimensionnement et l’intégration à l’interpréteur de commandes des fenêtres, 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 dans GXDK\gameKit\lib\amd64, comme la bibliothèque générale xgameplatform.lib.
  • Pour les composants COM, seul le modèle de thread MTA (multithreaded apartment) est pris en charge. Notez que COINITBASE_MULTITHREADED est typique d’une application Direct3D.
  • Une seule instance de fenêtre est prise en charge. Les instances de fenêtre ou les 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 effort de portage est d’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 plateformes Gaming.Xbox.XboxOne.x64 et Gaming.Xbox.Scarlett.x64 permettant de cibler le Game OS Microsoft GDK sur XBOX. Cela remplace la plateforme Durango du XBOX One Software Development Kit.

Solutions de génération personnalisées

Pour générer du code en dehors de Visual Studio, les assistants d’environnement pour les emplacements ont été modifiés. XBOX One Software Development Kit :
Microsoft Game Development Kit (GDK) :
Dans l’exemple de chemin ci-dessus, build_number représente le build installé sur votre système (p. ex. 190700).
Plusieurs emplacements du Microsoft Game Development Kit (GDK) devront être référencés par les systèmes de génération personnalisés. %GameDKLatest%\GXDK\gameKit contient tous les en-têtes et bibliothèques pour les extensions propres à la console, ainsi que la bibliothèque générale principale de la plateforme pour l’édition de liens d’un binaire Microsoft Game Development Kit (GDK). %GameDKLatest%\GRDK\gameKit contient de façon semblable les en-têtes et bibliothèques pour toutes les fonctionnalités qui ne sont pas propres au développement sur console. Le Microsoft Game Development Kit (GDK) exige que le Windows 10 SDK (10.0.19041.0) ou une version ultérieure soit installé comme 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 devriez 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_XBOX remplace à la fois /D_XBOX_ONE /D_TITLE et /D_DURANGO.
  • /D_GAMING_XBOX_XBOXONE est défini uniquement pour la plateforme Gaming.Xbox.XboxOne.x64.
  • /D_GAMING_XBOX_SCARLETT est défini uniquement pour la plateforme Gaming.Xbox.Scarlett.x64.
  • /DWINAPI_FAMILY=WINAPI_FAMILY_GAMES contrôle le partitionnement des API à la place de la famille d’API WINAPI_FAMILY_TV_TITLE.
  • Vous devriez définir /DWIN32_LEAN_AND_MEAN, /D_ATL_NO_DEFAULT_LIBS et /D__WRL_NO_DEFAULT_LIB__
  • Pour le Microsoft Game Development Kit (GDK), vous n’utilisez plus aucun commutateur Windows Runtime comme /AI, /FU ou /ZW.
  • Continuez à utiliser /favor:AMD64, /EHsc et /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 plateforme Gaming.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 doit s’agir de /d2:-vzeroupper.
Avec VS 2022 et la plateforme Gaming.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 doit s’agir de /d2:-vzeroupper-.
  • Effectuez l’édition de liens avec xgameplatform.lib, xgameruntime.lib, d3d12_x.lib ou d3d12_xs.lib, xmem.lib et pixevt.lib. N’utilisez pas kernel32.lib, kernelx.lib, onecore.lib ni WindowsApp.lib.
  • Pour la bibliothèque XGraphics, utilisez xg_x.lib ou xg_xs.lib.
  • Vous n’avez pas besoin d’utiliser /WINMD ni /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.
Vous devriez envisager d’utiliser /NODEFAULTLIB pour vous assurer de ne pas effectuer l’édition de liens avec des bibliothèques Win32 non prises en charge, notamment advapi32.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 diverses définitions de préprocesseur « lean and mean » en plus de WIN32_LEAN_AND_MEAN, comme mentionné précédemment, afin de garder sous contrôle le nombre total d’en-têtes système Win32 que vous incluez.

Runtime Visual C++

Avec le XBOX One Software Development Kit, les en-têtes et les 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 effectuer la mise à jour vers 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 votre package de jeu et correspondent à la version de Visual Studio installée localement sur l’ordinateur de génération.
  • VCRuntime*.dll et msvcp*.dll sont les DLL du runtime du compilateur Visual C++ et de la bibliothèque C++ standard. Un fichier ucrtbase.dll inclus dans le Game OS est également utilisé.
  • Pour les builds de débogage, votre package contiendra VCRuntime*d.dll, msvcp*d.dll et ucrbased.dll
Si vous utilisez la ERA Migration Library, vous avez également besoin de vccorlib*.dll, qui est utilisé par le compilateur lors de la génération avec /ZW.
AMP n’est pas pris en charge pour la 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 avoir l’un des points d’entrée suivants.

Développement de bureau Win32

XBOX One Software Development Kit ou application UWP utilisant C++/CX

XBOX One Software Development Kit ou application 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.
Ce modèle est essentiellement le même pour les titres Microsoft Game Development Kit (GDK) sur XBOX, mais nous pouvons le simplifier quelque peu :
  • 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.
L’utilisation d’une boucle de messages Win32 est facultative, mais c’est un point de départ utile si vous passez d’une base de code Win32 existante. Le tableau suivant présente une liste des messages Win32 courants que l’on trouve dans les jeux de bureau Win32 classiques, ainsi que l’applicabilité (ou non) de ces messages aux titres Microsoft Game Development Kit (GDK) sur XBOX.

Création de périphériques Direct3D

Les jeux générés avec le Microsoft Game Development Kit (GDK) sur XBOX utilisent l’API Direct3D 12.X, qui est implémentée sous forme de runtime monolithique, tout comme elle l’est avec le XBOX One Software Development Kit. Direct3D 12 et Direct3D 11 standard ne sont pas pris en charge pour les jeux généré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.
À partir de là, la file d’attente de commandes, la liste de commandes et les autres éléments continueront d’être créés comme ils le seraient avec Direct3D 12 standard. Pour prendre en charge le rendu 4K, il suffit d’utiliser une largeur et une hauteur de chaîne d’échange plus grandes, mais vous devriez continuer à prendre en charge le 1080p pour les consoles d’entrée de gamme. Voici une façon recommandée de déterminer quand utiliser le 4K, le 1440p ou le 1080p :
Pour plus de détails, consultez l’exemple SimpleDeviceAndSwapChain.

API XMem*

Tout appel aux API XMem* qui utilisent XMEM_GRAPHICS exige que le périphérique Direct3D ait été créé avant leur utilisation. Vous pouvez également appeler D3DConfigureVirtualMemory si vous devez utiliser ces appels avant que le périphérique Direct3D n’existe.

Réservation CPU/GPU

Tous les titres Microsoft Game Development Kit (GDK) obtiennent toutes les ressources (c’est-à-dire aucune réservation GPU pour Kinect) ainsi que le septième cœur du 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 plateforme Gaming.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 facile.
  • Gaming.Xbox.Scarlett.x64 prend en charge jusqu’aux interfaces ID3D12Device8 et ID3D12GraphicsCommandList5 ou des versions ultérieures.
  • Gaming.Xbox.XboxOne.x64 prend en charge jusqu’à ID3D12Device, ID3D12Device1, ID3D12Device2 et ID3D12GraphicsCommandList.
Lorsque vous passez à la plateforme Gaming.Xbox.Scarlett.x64, il existe des capacité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 des bibliothèques Direct3D (c.-à-d. d3d12_xs.h, d3dx12_xs.h, xg_xs.h, d3d12_xs.lib, etc.). Vous ne pouvez pas combiner 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 a été construit par-dessus 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 Durango ou Gaming.Xbox.XboxOne.x64. Ceux-ci ont été supprimés de l’implémentation XBOX Series X|S; vous pourriez donc rencontrer des problèmes de génération avec toute référence résiduelle à l’en-tête d3d11_x.h, aux définitions D3D11_*, aux classes CD3D11_* ou aux interfaces ID3D11*. Ces références peuvent être supprimées tout en permettant la génération pour les deux plateformes.
  • L’ESRAM n’est pas une fonctionnalité de la 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 (un assistant pour l’utilisation de l’ESRAM) est uniquement pris en charge pour la plateforme Gaming.Xbox.XboxOne.x64.
Il demeure 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 d’échange DXGI héritées pour la présentation, mais utilise plutôt l’API PresentX. Les nouvelles API PresentX sont conçues pour répondre aux préoccupations de latence liées aux chaînes d’échange DXGI et offrent au développeur un contrôle plus direct des tampons de présentation. Cette API est également conçue pour évoluer en fonction des futures applications de diffusion en continu. La première étape de l’utilisation de PresentX consiste à s’inscrire aux événements d’image après la création du périphérique Direct3D.
Au lieu de créer une chaîne d’échange DXGI et de demander les ressources de tampon d’arrière-plan, créez-les directement avec l’indicateur D3D12_HEAP_FLAG_ALLOW_DISPLAY.
Au début de chaque image de rendu, définissez d’abord un jeton de pipeline à l’aide de WaitFrameEventX.
À la fin de l’image, utilisez le même jeton pour appeler PresentX.
Comme pour les titres XBOX One Software Development Kit, les jeux Microsoft Game Development Kit (GDK) sur XBOX ne rencontrent pas les erreurs DXGI_ERROR_DEVICE_REMOVED et DXGI_ERROR_DEVICE_RESET, qui doivent être gérées pour les jeux PC. D’autres fonctionnalités DXGI connexes ont été supprimées, et la fonction ScheduleFrameEventX mentionnée précédemment remplace DXGIXSetFrameNotification du XBOX One Software Development Kit. Voici le code du XBOX One Software Development Kit pour la notification de basculement d’image.
Code équivalent pour les titres Microsoft Game Development Kit (GDK) sur XBOX.
Pour plus de détails, consultez Planification et présentation des images sur XBOX One, ainsi que les exemples SimpleDeviceAndSwapChain, HDR10 et SimpleHDR.

Gestion de la durée de vie des processus (PLM)

Les jeux généré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 celui utilisé par les applications XBOX One XDK et les applications UWP. Les applications s’exécutent en mode non limité, limité, suspendu ou arrêté; c’est-à-dire qu’aucun code ne s’exécute lors de l’arrêt et que le processus est simplement détruit. Les applications XBOX One Software Development Kit et les applications UWP reçoivent des notifications au moyen de leur CoreWindow Windows Runtime. Les jeux Microsoft Game Development Kit (GDK) sur XBOX reçoivent des notifications au moyen de 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 message WM_USER.
Par la suite, la boucle de messages gérerait le message WM_USER pour s’assurer que la boucle est mise en pause jusqu’à la reprise, et que le comportement approprié de suspension/reprise du GPU se produit à un moment sûr dans la boucle de rendu.
Pour plus de détails, consultez l’exemple SimplePLM.

Mode limité ou complet

La notification des ressources limitées par rapport aux ressources complètes est gérée au moyen d’une API semblable.
Ici, nous utilisons un message pour les mêmes raisons que précédemment dans le cas de la suspension/reprise.
Pour plus de détails, consultez l’exemple SimplePLM.

Arrêt du processus

Pour les titres commerciaux, l’arrêt du processus est géré de la même façon que pour l’ancienne plateforme XBOX One Software Development Kit. Le processus est suspendu, puis arrêté. Aucun des destructeurs C++ ni aucun nettoyage n’est traité. Cela était également vrai si vous appeliez Windows::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 au moyen de PostQuitMessage. Cela entraîne la sortie de votre boucle de messages, et le nettoyage normal du code ainsi que le démontage du processus ont lieu. C’est utile pendant le développement pour aider à détecter les fuites et d’autres problèmes de nettoyage qui peuvent autrement être difficiles à trouver. Ce comportement, toutefois, invoque 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 de renseignements sur la gestion de la mémoire, consultez Vue d’ensemble de la mémoire.

Changements apportés au modèle de mémoire

La plateforme Microsoft Game Development Kit (GDK) comprend de nombreux changements apportés au modèle de mémoire par rapport au Game OS XBOX One d’origine. La majeure partie de cet effort a été consacrée à l’amélioration de l’isolation de la mémoire utilisée par le titre par rapport à la mémoire utilisée par le système. L’amélioration de l’isolation rendrait l’utilisation de la mémoire plus prévisible pour le titre et le système, et empêcherait 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 aucun changement majeur, vous devriez 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 relatives aux 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 normaux de lecture/écriture CPU sur la même mémoire physique.
  • Les paramètres de page et les valeurs de cohérence du cache résident maintenant 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 requise dans la version précédente du système d’exploitation.
Pour toutes les allocations mappées pour un accès par le GPU, des indicateurs d’accès GPU explicites sont maintenant requis. Il n’existe plus de valeur par défaut basée sur les paramètres de protection du CPU. Veillez à repérer tout endroit de votre base de code où vous avez utilisé la constante MEM_LARGE_PAGES. Ses valeurs et sa signification ont changé pour correspondre aux significations utilisées dans l’ensemble de Windows. Avec le passage des grandes pages de 4 Mo dans le Game OS XBOX One à 2 Mo dans le système d’exploitation Microsoft Game Development Kit (GDK) sur XBOX, les spécificateurs de taille XMemAlloc ont également changé pour les grandes pages, passant 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. Celles-ci couvrent maintenant l’ensemble de l’espace d’adressage de 8 To.

Changements apportés aux API

Les API de mémoire du Microsoft Game Development Kit (GDK) commencent par le préfixe XMem et, pour la plupart, reflètent 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 API XMemVirtualAlloc remplace toutes les utilisations de VirtualAlloc pour l’allocation de mémoire graphique XBOX. Notez les exigences précédentes relatives à la spécification des exigences de page GPU et de cohérence du cache pour les réservations ultérieurement soutenues par des mappages physiques. Une comparaison d’une telle réservation dans le XBOX One Software Development Kit :
et dans le Microsoft Game Development Kit (GDK) :
Ou, pour une allocation non soutenue par des pages physiques mappées et validée au moment de la réservation :
Devient :

Utiliser VirtualFree

La mémoire allouée par VirtualAlloc ou XMemVirtualAlloc est toujours libérée avec VirtualFree. Il n’existe pas d’API XMemVirtualFree.

Utilisation de XMemAlloc

La macro Attributes comporte maintenant un paramètre supplémentaire. Par exemple :
Devient :

XMemAllocatePhysicalPages et XMemMapPhysicalPages

Avec le déplacement des indicateurs de page et de la cohérence du cache au moment de la réservation, les appels d’allocation et de mappage de la mémoire physique sont simplifiés, mais sont par ailleurs semblables à ceux du XBOX One Software Development Kit. XMemAllocatePhysicalPages remplace AllocateTitlePhysicalPages. XMemMapPhysicalPages remplace MapTitlePhysicalPages. Ce code du XBOX One Software Development Kit :
Devient ceci pour les titres Microsoft Game Development Kit (GDK) :

Modèle de programmation

Pour plus de renseignements sur le modèle de programmation, consultez la rubrique Modèle de programmation asynchrone.

Code synchrone (bloquant) avec GameRuntime

Pour les API où le blocage est une option raisonnable, les versions bloquantes (synchrones) de toutes les fonctionnalités de 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 à partir de 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 reconnue comme non déterministe; seules des versions asynchrones sont alors fournies.

Code asynchrone avec GameRuntime

La plateforme Microsoft Game Development Kit (GDK) comprend un nouveau modèle pour effectuer des tâches asynchrones et signaler leurs résultats au moyen de rappels. Ce modèle remplace Windows Runtime. Utilisez les API GameRuntime pour indiquer comment et où le travail asynchrone et les rappels se produisent. L’exemple de code suivant comprend des exemples de code standard simples montrant comment une file d’attente de tâches Game Runtime est configurée 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. Conceptuellement, un rappel est une tâche qui exécute votre code en réponse à des actions du système. Au besoin, vous pouvez créer plusieurs files d’attente de tâches pour gérer le travail sur différents cœurs, ou pour indiquer, 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 effectuée manuellement par votre code (de façon semblable à une file d’attente de messages Windows) ou automatiquement. Voici des exemples simples de création d’une file d’attente distribuée manuellement, puis de sa distribution.
Pour plus de renseignements, consultez l’exemple SimplePLM, qui déclenche les paramètres ainsi que l’interface utilisateur pouvant être appelée par un titre (TCUI) pour la connexion à l’aide d’une file d’attente asynchrone XTask. Pour plus de détails sur le modèle de programmation asynchrone, consultez les rubriques Modèle de programmation asynchrone et Conception de la file d’attente de tâches asynchrones. Consultez également l’exemple AsynchronousProgramming.

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 structure XAsyncBlock, qui doit être maintenue en vie 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 d’indiquer si le thread à partir duquel vous appelez 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.
Pour marquer un thread comme sensible au temps, appelez SetTimeSensitiveThread(true) sur le thread. Vous pouvez également appeler VerifyNotTimeSensitiveThread() à partir de fonctions de longue durée dans votre propre code pour signaler une utilisation inappropriée à partir de threads critiques en temps.

Nuanceurs HLSL

La plateforme XBOX One Software Development Kit utilisait une version personnalisée du compilateur HLSL FXC.EXE qui prenait en charge la précompilation des nuanceurs programmables Shader Model 5.1 en microcode ATI. De plus, 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 est recommandée au moyen de DXC.EXE. Le compilateur Shader Model 5.1 FXC.EXE est maintenant 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, bien que certaines des defines d’extension propres à la XBOX ne soient pas applicables ou 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 nuanceurs DXIL Shader Model 6.x, tout comme de nombreux pilotes commerciaux. Au lieu de compter sur les pilotes WHQL de Windows Update pour cette fonctionnalité, vous devez installer le pilote le plus récent directement auprès de son fournisseur. Le compilateur DXC.EXE pour Windows est inclus dans le SDK de la mise à jour d’avril 2018 de Windows 10 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 au moyen de CheckFeatureSupport en utilisant D3D12_FEATURE_SHADER_MODEL, mais assurez-vous d’initialiser shaderModel.HighestShaderModel avant d’appeler la fonction!
La version XBOX One du compilateur DXIL se trouve ici : %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 devriez utiliser la bibliothèque dxcompiler_x.lib ou dxcompiler_xs.lib plutôt que d3dcompiler_x.lib.

Gestion des utilisateurs

Le modèle d’utilisateur du Microsoft Game Development Kit (GDK) diffère de celui auquel vous êtes peut-être habitué dans le XBOX One Software Development Kit. Cela vise en partie à mieux gérer les attentes des utilisateurs en matière de confidentialité et à alléger le fardeau de toujours suivre ce que fait le système en arrière-plan avec des utilisateurs dont le titre ne devrait pas se soucier. Plutôt que de demander aux titres de surveiller une collection à l’échelle du système des utilisateurs et des invités 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 commencer une session de jeu et que la manette n’a pas encore été associée à un utilisateur), appelez XUserAddAsync. Cet appel effectue deux actions importantes : il connecte les utilisateurs au titre et met à jour le jumelage des périphériques d’entrée de l’utilisateur. Les utilisateurs peuvent avoir n’importe quel nombre de périphériques d’entrée jumelés à la fois. Cependant, le titre n’est informé que des associations des utilisateurs qui ont été connectés avec XUserAddAsync. Si le Guide du système est utilisé pour connecter un utilisateur ou modifier des associations en dehors du titre vers 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, connaît toutefois toujours le jumelage pour l’utilisation par le système. Les titres peuvent surveiller les changements de l’état d’un utilisateur ou des renseignements associés à un utilisateur (comme son gamertag, son image de joueur ou ses privilèges) en s’abonnant à XUserChangeEvent (bien que certains de ces renseignements, comme l’état de connexion de l’utilisateur, puissent être surveillés par interrogation). Pour ce faire, appelez XUserRegisterForChangeEvent. La plupart des titres devraient 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 discussion approfondie de ces changements, consultez Utilisateurs et périphériques d’entrée. Consultez également l’exemple UserManagement.

Réseau et intégration des services XBOX

Transport réseau

Le Microsoft Game Development Kit (GDK) sur XBOX prend en charge à la fois WinSock2 et BCrypt au moyen de CNG. Si vous utilisez UDP, plutôt que de coder en dur un port comme 3074 pour la liaison de votre socket multijoueur, vous devriez utiliser, pour le Microsoft Game Development Kit (GDK), cette nouvelle API C plate :
Pour détecter la connectivité réseau avec le Microsoft Game Development Kit (GDK), utilisez IPHelper plutôt que l’espace de noms Windows.Networking.Connectivity. Pour un exemple de code, consultez Initialisation et connectivité du réseau.
Les sockets sécurisés (espace de noms Windows.Xbox.Networking) ont été supprimés pour le Microsoft Game Development Kit (GDK).
Pour plus de détails, consultez Présentation du réseau WinSock.

Requêtes Web au moyen de HTTP

Le Microsoft Game Development Kit (GDK) ne prend plus en charge IXMLHTTPRequest2 ni MessageWebSocket / StreamWebSocket (espace de noms Windows.Networking.Sockets). Vous devriez plutôt utiliser 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
Consultez Présentation des API C des services XBOX et la référence XSAPI. Si vous utilisez Game Chat 2, sachez que quelques classes ont été renommées, comme l’indique le tableau suivant.

Étapes suivantes

Après avoir terminé votre portage initial à partir de l’ERA, vous serez en excellente position pour activer un certain nombre de fonctionnalités du Microsoft Game Development Kit (GDK) sur XBOX. Si votre titre s’exécute bien sur le matériel XBOX One S / XBOX One X, voici des façons 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 natif Microsoft Game Development Kit (GDK) sur XBOX, assurez-vous 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 à la XBOX Series X|S; il n’y a donc aucun surcoût en matière de CPU, de GPU, de mémoire, de bande passante ou de latence. L’amélioration visuelle ne modifie pas l’intention artistique d’origine et étend la luminosité jusqu’à 1000 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 une façon simple et efficace d’obtenir une expérience améliorée.
Consultez Sortie à plage dynamique élevée (HDR) et l’exemple AutoHDR pour plus de détails.
  • Aniso Boost : Une amélioration de la qualité d’image sur les consoles XBOX Series X|S est obtenue en faisant passer le filtrage de texture linéaire au filtrage anisotrope complet. C’est une façon simple et rapide de mettre la puissance GPU supplémentaire au service d’un titre de jeu existant. En tant que titre Microsoft Game Development Kit (GDK) sur XBOX, vous y parvenez en utilisant le paramètre D3D12_FILTER_ANISOTROPIC pour vos états d’échantillonneur au lieu de D3D12_FILTER_MIN_MAG_MIP_LINEAR lors 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 images par seconde sur XBOX One S / XBOX One X (D3D12XBOX_FRAME_INTERVAL_30_HZ), il peut généralement s’exécuter à 60 images par seconde sur XBOX Series X|S (D3D12XBOX_FRAME_INTERVAL_60_HZ). S’il s’exécute à 60 images par seconde sur XBOX One S/X, il peut probablement s’exécuter à 120 images par seconde sur XBOX Series X|S. Consultez Prise en charge de 120 Hz et l’exemple Simple120Hz pour plus de renseignements.
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). Consultez Cycle de vie des jeux XBOX pour plus de détails.

Trucs et astuces

Fichier d’empaquetage Microsoft Game Config

Le Microsoft Game Development Kit (GDK) n’utilise plus de fichier Package.appxmanifest pendant la chaîne d’outils de génération de Visual Studio pour générer AppxManifest.xml. Un fichier MicrosoftGameConfig est plutôt utilisé pour regrouper tous les paramètres du package d’application au moment du développement.
L’élément 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, de façon facultative, ajouter les diverses 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 maintenant référencé en tant qu’attribut Square480x480Logo.
Pour l’intégration des services XBOX, vous devez également fournir un ID de titre.
Comme indiqué ci-dessus, vous n’avez plus besoin d’utiliser des éléments de manifeste pour obtenir le 7e cœur et la disponibilité étendue des ressources GPU, mais vous pouvez utiliser le manifeste pour contrôler la mémoire du titre.
L’élément appxmanifest ci-dessus a été remplacé par un élément dont la valeur par défaut est « Standard » pour le contrôle de la mémoire du titre.
Certaines extensions de manifeste du XBOX One Software Development Kit peuvent également être transférées dans le fichier .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 génération liés au numéro de build de l’XDK, au niveau de QFE, etc. Pour les plateformes Gaming.*.x64, vous pouvez utiliser grdk.h :
  • _GRDK_VER est l’encodage de la version du Gaming GDK utilisée pour générer le binaire (HIWORD.LOWORD). Par exemple, 0x4A610479 correspond au numéro de build 19041.1145.
  • _GRDK_VER_STRING pour ce build est « April 2020 GRDK ».
  • _GRDK_VER_STRING_W est l’équivalent en chaîne étendue UTF16-LE de _GRDK_VER_STRING.
  • _GRDK_VER_STRING_COMPACT_W pour ce build est une chaîne étendue UTF16-LE contenant « April 2020 ».
Pour les plateformes Gaming.Xbox.*.x64, vous pouvez également utiliser gxdk.h :
  • _GXDK_VER est l’encodage de la version du Gaming GDK utilisée pour générer le binaire (HIWORD.LOWORD). Par exemple, 0x4A610479 correspond au numéro de build 19041.1145.
  • _GXDK_VER_STRING pour ce build est « April 2020 GXDK ».
  • _GXDK_VER_STRING_W est l’équivalent en chaîne étendue UTF16-LE de _GXDK_VER_STRING.
  • _GXDK_VER_STRING_COMPACT_W pour ce 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éthodes MapVirtualKey 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

Lors de la conversion entre des chaînes de caractères étendus (UTF-16 LE) et des chaînes de caractères étroits, les développeurs Win32 utilisent souvent MultiByteToWideChar et WideCharToMultiByte. Pour les bases de code modernes, nous vous recommandons d’utiliser CP_UTF8 au lieu d’une page de codes particulière ou de CP_ACP. Le code suivant fonctionne sur Windows 7 Service Pack 1 et les versions ultérieures.
Les pages de codes 437 et 1252 sont parfois utilisées directement. La page 437 n’est pas prise en charge pour le XBOX One Software Development Kit ni pour le Microsoft Game Development Kit (GDK) sur XBOX. La page 1252 fonctionnait sur le XBOX One XDK, mais n’est pas prise en charge pour le Microsoft Game Development Kit (GDK) sur XBOX. Pour le Microsoft Game Development Kit (GDK) sur XBOX, 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 celui-ci a déjà été déprécié dans C++17. La recommandation est 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 page de codes, de la traduction de points de code (la conversion de caractères multioctets en caractères étendus) et de la déclaration des paramètres régionaux du système et de l’utilisateur, était absente. Pour le Microsoft Game Development Kit (GDK), cette fonctionnalité de localisation est entièrement prise en charge, tout comme GetCurrencyFormatEx, GetNumberFormatEx, l’énumération des formats de date et d’heure, et d’autres fonctionnalités.

Notes sur l’audio XMA2

S’il vous manque la définition de SHAPE_XMA_INPUT_BUFFER_ALIGNMENT, vous devrez ajouter explicitement une référence à l’en-tête shapexmacontext.h.
Avec le XBOX One Software Development Kit, cet en-tête était inclus implicitement par d’autres en-têtes audio.

Prise en charge des boîtes de message de l’interface utilisateur

Pour aider à améliorer le débogage des plantages et des échecs d’initialisation précoce dans un titre, XGameUiShowMessageDialogAsync a été ajoutée à la collection d’API d’interface utilisateur pouvant être appelée par un 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 son rendu dans la partition système et est composée par-dessus la sortie du jeu. Elle fonctionne toujours 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 renseignements sur une erreur ayant causé un plantage, ou même pour inviter à attacher un débogueur tout en bloquant à l’endroit de l’erreur. Elle est destinée principalement à servir d’outil de diagnostic pendant le développement. Cet exemple montre une boîte de dialogue d’erreur de style bloquant, invitant le développeur à attacher un débogueur pour enquêter.

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é. Celles-ci peuvent plutôt être ajoutées au moyen des propriétés du projet Visual Studio. Cela modifie un élément de propriété dans la section Globals du fichier vcxproj :
Si cet élément n’est pas présent, la valeur par défaut consiste à inclure uniquement XSAPI.

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 pour Windows de bureau et pour console XBOX. Un aspect qui n’a pas été abordé précédemment est le travail effectué pour améliorer la compatibilité binaire entre Windows de bureau et le système d’exploitation 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 qui ont été conçus à l’origine pour Windows de bureau x64. Cela peut constituer une fonctionnalité précieuse permettant de gagner du temps pour le prototypage, l’outillage ou d’autres scénarios dont les performances ne sont pas critiques. Il n’existe aucun outil dans le Microsoft Game Development Kit (GDK) pour déterminer si un composant Windows de bureau peut être réutilisé; cela est plutôt déterminé par les API du système d’exploitation consommées par le composant en question. Les API prises en charge du système d’exploitation Microsoft Game Development Kit (GDK) sur XBOX peuvent être obtenues en exécutant dumpbin.exe /exports sur les bibliothèques fournies avec le Microsoft Game Development Kit (GDK). Bien que certaines API propres à un domaine résident 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, lorsqu’elle est exécutée à partir d’une invite de commandes développeur Visual Studio, affiche l’ensemble principal des API Win32 prises en charge (à l’exception de celles qui résident 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 le build installé sur votre système (p. ex. 190700).
Les bibliothèques statiques conçues à l’origine pour Windows de bureau, qui n’utilisent que des API de la liste approuvée, peuvent généralement être liées directement dans un binaire Microsoft Game Development Kit (GDK) destiné à la XBOX. Cependant, ce n’est pas toujours le cas, car des différences de comportement (comme la limitation à une seule fenêtre) peuvent entraîner des échecs d’exécution du composant s’il n’a pas été conçu pour gérer de telles différences. Les bibliothèques de liens dynamiques (DLL) dont la liste d’importation se situe entièrement dans les API prises en charge se chargent et fonctionnent également en général telles quelles. Le système d’exploitation Microsoft Game Development Kit (GDK) sur XBOX contient une logique de transfert pour rediriger correctement cet ensemble d’API vers leurs emplacements d’implémentation s’ils diffèrent de ceux de Windows de bureau. Bien que la possibilité de réutiliser des composants Windows de bureau sur la console puisse faire gagner du temps dans de nombreux scénarios, cela n’est pas conseillé pour les chemins critiques en matière de performances dans un titre commercialisé. La plupart des composants conçus pour Windows de bureau n’auront pas été générés avec les indicateurs les plus optimaux pour l’exécution avec le Microsoft Game Development Kit (GDK). Plus particulièrement, comme les composants de bureau ciblent un éventail plus large de processeurs, ces composants peuvent avoir été générés sans optimisations AVX. La réutilisation de DLL de bureau peut également entraîner une taille de code globale plus importante, comparativement à une nouvelle génération pour le Microsoft Game Development Kit (GDK).

Style de codage et pratiques exemplaires

Les directives 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) ni de C++/WinRT, car la plupart des API de jeu sont de style Win32 ou de style COM DirectX. Voici quelques recommandations générales :
  • Tirez parti de la conformité au langage C++14 et, de façon facultative, 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. La XBOX One prend en charge /arch:AVX ainsi que F16C.
  • La gestion des exceptions C++ (/EHsc) entraîne 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 axé sur les performances; elle ne devrait donc pas être utilisée pour contrôler le flux.
  • L’utilisation de techniques de codage sécuritaires en cas d’exception, comme celles décrites dans Objects Own Resources (RAII) et Resource Acquisition Is Initialization, est une pratique exemplaire fortement recommandée, à l’aide de std::unique_ptr, Microsoft::WRL::ComPtr et 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_t et uintptr_t.
  • Pour réduire au minimum le remplissage interne, regroupez les pointeurs dans les structures et les classes.
  • Au lieu du transtypage hérité de style C, privilégiez les transtypages C++ comme const_cast<>, static_cast<>, reinterpret_cast<> et dynamic_cast<>.
  • Utilisez des intrinsèques lorsque c’est possible. Le code natif x64 ne prend pas en charge l’assembleur en ligne.

Commutateurs du compilateur et de l’éditeur de liens

Utilisez les commutateurs suivants :
  • /O1 /Oi pour l’optimisation générale et /O2 pour les modules critiques
  • /fp:fast
  • /arch:AVX pour la famille d’appareils XBOX One; /arch:AVX2 pour la XBOX Series X|S.
  • /favor:AMD
  • Optimisation de l’ensemble du programme et optimisation guidée par profil
  • Commutateurs d’éditeur de liens /OPT:REF,ICF
Pour des raisons historiques, /Ox est presque identique à /O2, mais il lui manque à la fois /GF (élimination des chaînes en double) et /Gy (activation de l’édition de liens au niveau des fonctions). Privilégiez /O2 plutôt que /Ox. Si vous utilisez /Ox, assurez-vous d’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; assurez-vous donc de vous renseigner à leur sujet : /Zc:inline, /Zc:throwingNew, /Zc:__cplusplus, /volatile:iso, /permissive-, /Zc:twoPhase- et /Debug:FASTLINK.

Code conditionnel

Pour le code conditionnel où 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 :
  1. Recherchez toutes les occurrences de _XBOX_ONE dans votre base de code
  2. Modifiez les occurrences comme #if defined(_XBOX_ONE) && defined(_TITLE) où le code utilise les extensions DirectX 12.X, de sorte que ces cas deviennent :
    #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, par exemple CreateFileW plutôt que CreateFileA. Cela a résolu le problème de la gestion d’une myriade de pages de codes différentes et a simplifié toutes les chaînes localisables en wchar_t* (UTF-16 LE, little endian). Le manifeste UTF-8 Everywhere soutient que l’encodage multioctet UTF-8 avec char* est une meilleure solution en matière 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. Il s’agit également d’une option que l’utilisateur doit activer pour le moment; vous pourriez donc constater que limiter votre utilisation de bas niveau des API Win32 aux API à caractères étendus est la meilleure option pour la portabilité.
Nous recommandons ce qui suit :
  • Privilégiez l’utilisation d’UTF-8 dans vos API, et effectuez la conversion en UTF-16 LE uniquement lors de l’appel des API Win32 à caractères étendus. Au lieu d’utiliser std::wstring et wchar_t*, utilisez std::string et char* en UTF-8.
  • Pour les littéraux de chaîne étroite, assurez-vous de respecter UTF-8 en utilisant le préfixe C++ u8 plutôt qu’aucun préfixe ou L.
  • Conservez les defines de préprocesseur de génération UNICODE et _UNICODE en place (dans Visual Studio, il s’agit de la propriété <CharSet>) par mesure de sécurité, mais au lieu de vous fier aux macros, appelez toujours explicitement la version W() ou A().
  • Évitez TCHAR, TEXT(), LPTSTR et les autres types et macros de texte hérités. Pour plus de renseignements, 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 façon que les noms de fonction donnent des indications implicites sur les performances des fonctions appelées. Une fonction dont le nom comprend Get ou Set est censée être peu coûteuse et prévisible. Elle est également censée offrir à peu près le même niveau de performances que si elle était appelée à la place d’une fonction d’encapsulation de propriété C++ avec une 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 qui pourrait bloquer jusqu’à ce qu’elle soit terminée. Pour les fonctions qui effectuent des calculs plutôt que de simples requêtes, nous supposons généralement que les performances correspondent à peu près à ce à quoi vous vous attendriez après avoir examiné leurs paramètres d’entrée et les types 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 et pourrait prendre un temps très long ou indéterminé à se terminer. Dans la plupart des cas, nous fournissons des versions bloquantes et asynchrones des fonctions dont l’exécution peut être longue. Nous vous laissons décider de la variante qui convient le mieux à votre base de code. Dans certains cas (comme pour les API réseau), nous pourrions 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, pour retourner, nécessite généralement une interaction de l’utilisateur. 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)
Last modified on October 6, 2026