Skip to main content

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
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 existantes, sur toutes les plateformes sur lesquelles nous travaillons et qui raviront les joueurs de demain. Pour plus d’informations 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).

Sommaire

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 code Durango 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é plateforme Durango), 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 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 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_GAMES est 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.Input ou DirectInput.
  • Pour l’audio, utilisez XAudio2, WASAPI, ISpatialAudioClient ou un middleware audio compatible.
  • Supprimez toute utilisation du Registre.
  • Le traitement des messages WndProc doit ê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 globale 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 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 plateformes Gaming.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 :
Microsoft Game Development Kit (GDK) :
Dans l’exemple de chemin ci-dessus, build_number représente la build installée sur votre système (par exemple 190700).
Plusieurs emplacements du Microsoft Game Development Kit (GDK) devront être référencés par les systèmes de build personnalisés. %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_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 devez 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 tel que /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 faut utiliser /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 faut utiliser /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 ou /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 /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 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*.dll et msvcp*.dll sont les DLL du runtime du compilateur Visual C++ et de la bibliothèque C++ standard. Une ucrtbase.dll incluse dans le Game OS est également utilisée.
  • 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é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.
Ce modèle est en grande partie 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 bon point de départ si vous migrez depuis une base de code Win32 existante. Le tableau suivant répertorie les messages Win32 courants rencontrés dans les jeux de bureau Win32 classiques, ainsi que leur applicabilité (ou non) aux titres Microsoft Game Development Kit (GDK) sur XBOX.

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.
À partir de là, la file d’attente de commandes, la liste de commandes et les autres éléments continuent d’être créés comme avec Direct3D 12 standard. Pour prendre en charge le rendu 4K, il suffit d’utiliser une largeur et une hauteur de chaîne de permutation plus grandes, mais vous devez continuer à prendre en charge le 1080p pour les consoles d’entrée de gamme. Voici une méthode recommandée pour 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 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 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 simple.
  • Gaming.Xbox.Scarlett.x64 prend en charge jusqu’aux interfaces ID3D12Device8 et ID3D12GraphicsCommandList5, ou leurs versions ultérieures.
  • Gaming.Xbox.XboxOne.x64 prend en charge jusqu’à ID3D12Device, ID3D12Device1, ID3D12Device2 et ID3D12GraphicsCommandList.
Lors du passage à la plateforme 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 Durango ou Gaming.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ête d3d11_x.h, aux définitions D3D11_*, aux classes CD3D11_* ou aux interfaces ID3D11*. 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 plateforme Gaming.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.
Au lieu de créer une chaîne de permutation DXGI et de demander les ressources de la mémoire tampon d’arrière-plan, créez-les directement avec l’indicateur D3D12_HEAP_FLAG_ALLOW_DISPLAY.
Au début de chaque trame de rendu, définissez d’abord un jeton de pipeline à l’aide de WaitFrameEventX.
À la fin de la trame, 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. 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.
Code équivalent pour les titres Microsoft Game Development Kit (GDK) sur XBOX.
Pour plus de détails, consultez Planification et présentation des trames sur XBOX One, ainsi que les exemples SimpleDeviceAndSwapChain, HDR10 et SimpleHDR.

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 message WM_USER.
Ensuite, la boucle de messages traite le message 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.
Pour plus de détails, consultez l’exemple SimplePLM.

Mode contraint ou complet

La notification des ressources contraintes ou complètes est gérée par une API similaire.
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 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 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, 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.
Pour toutes les allocations mappées pour un accès par le GPU, des indicateurs d’accès GPU explicites sont désormais requis. Il n’y a plus de valeur par défaut basée sur les paramètres de protection du CPU. Veillez à repérer, partout dans votre base de code, les endroits où vous avez utilisé la constante 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 API XMemVirtualAlloc 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 :
et sur le Microsoft Game Development Kit (GDK) :
Ou, pour une allocation non associée à 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 désormais un paramètre supplémentaire. Par exemple :
Devient :

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 :
Devient ceci pour les titres Microsoft Game Development Kit (GDK) :

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.
Pour plus d’informations, consultez l’exemple SimplePLM, qui déclenche les paramètres ainsi que l’interface utilisateur appelable par le 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 des 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 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.
Pour marquer un thread comme sensible au temps, appelez 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 HLSL FXC.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 !
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 devez utiliser la bibliothèque dxcompiler_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 :
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 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).
Pour plus de détails, consultez Présentation de la mise en réseau WinSock.

Requêtes web via HTTP

Le Microsoft Game Development Kit (GDK) ne prend plus en charge IXMLHTTPRequest2 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
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 indiqué dans le tableau suivant.

É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.
Pour plus de détails, consultez Sortie HDR (High Dynamic Range) et l’exemple AutoHDR.
  • 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_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 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 fichier Package.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.
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 é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.
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 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_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 cette build est « April 2020 GRDK ».
  • _GRDK_VER_STRING_W est la chaîne étendue UTF16-LE équivalente à _GRDK_VER_STRING.
  • _GRDK_VER_STRING_COMPACT_W pour cette 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 cette build est « April 2020 GXDK ».
  • _GXDK_VER_STRING_W est la chaîne étendue UTF16-LE équivalente à _GXDK_VER_STRING.
  • _GXDK_VER_STRING_COMPACT_W pour 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é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

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’utiliser CP_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.
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 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 comme GetCurrencyFormatEx, 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 de SHAPE_XMA_INPUT_BUFFER_ALIGNMENT est manquante, vous devez 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 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 fichier vcxproj :
Si cet élément n’est pas présent, seule XSAPI est incluse par défaut.

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écutant dumpbin.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).
Les bibliothèques statiques initialement conçues pour Windows (bureau), qui n’utilisent que des API figurant dans la liste approuvée, peuvent généralement être liées directement à un binaire Microsoft Game Development Kit (GDK) destiné à XBOX. Toutefois, ce n’est pas toujours vrai, car des différences de comportement (comme la limitation à une seule fenêtre) peuvent provoquer 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 relève entièrement des API prises en charge se chargent et fonctionnent également en général telles quelles. Le système d’exploitation du Microsoft Game Development Kit (GDK) sur XBOX contient une logique de transfert permettant de rediriger correctement cet ensemble d’API vers leurs emplacements d’implémentation s’ils diffèrent de ceux de Windows (bureau). Si la possibilité de réutiliser des composants Windows (bureau) sur la console peut faire gagner du temps dans de nombreux scénarios, elle est déconseillée pour les chemins critiques en termes de performances d’un titre commercialisé. La plupart des composants conçus pour Windows (bureau) n’auront pas été générés avec les indicateurs les plus optimaux pour une exécution avec le Microsoft Game Development Kit (GDK). En particulier, comme les composants de bureau ciblent une gamme plus large de processeurs, ils peuvent avoir été générés sans les optimisations AVX. La réutilisation de DLL de bureau peut également entraîner une taille de code globale plus importante que la régénération pour le Microsoft Game Development Kit (GDK).

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:AVX ainsi 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::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 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<> et dynamic_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 /Oi pour l’optimisation générale et /O2 pour les modules sollicités
  • /fp:fast
  • /arch:AVX pour la famille d’appareils XBOX One ; /arch:AVX2 pour 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
Pour des raisons historiques, /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 :
  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, 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 en wchar_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é.
Nous recommandons ce qui suit :
  • 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::wstring et wchar_t*, utilisez std::string et char* en UTF-8.
  • Pour les littéraux de chaîne étroits, assurez la conformité à UTF-8 en utilisant le préfixe C++ u8 plutôt qu’aucun préfixe ou L.
  • Conservez les defines de préprocesseur de build 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 appuyer sur les 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 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 contient Get 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)
Last modified on October 6, 2026