Guía de migración al Microsoft Game Development Kit para XBOX One
Este tema proporciona información general sobre las técnicas para migrar una base de código existente a la plataforma del Microsoft Game Development Kit (GDK) para XBOX. Para los desarrolladores que ya realizan desarrollo para XBOX One, la mayoría de los subsistemas les resultarán familiares, aunque con un diseño de API diferente. Algunas áreas, como los gráficos Direct3D, permanecen prácticamente sin cambios. Este tema proporciona una visión general de alto nivel de todo el proceso de migración, vínculos a áreas específicas y algunos trucos y sugerencias para evitar errores comunes. ¿Tienes comentarios sobre esta guía? Háznoslo saber en el foro de desarrolladores del Microsoft Game Development Kit (GDK). Si estás desarrollando un título nuevo con la plataforma del Microsoft Game Development Kit (GDK) en lugar de migrar un título existente, consulta Desarrollo de un título nuevo con el GDK.Acerca del Microsoft Game Development Kit (GDK)
Ustedes, nuestros asociados de desarrollo de juegos, han proporcionado al equipo de Gaming de Microsoft valiosos comentarios sobre lo que hacemos bien y lo que necesitamos mejorar. Nuestro objetivo principal con el Microsoft Game Development Kit (GDK) es abordar directamente sus comentarios y garantizar que puedan:- Seguir desarrollando juegos exactamente como lo hacen hoy
- Compartir fácilmente la mayor cantidad de código posible entre todas las iniciativas y programas de Microsoft Gaming: nuestras consolas y PC de hoy, y nuestras consolas y XBOX Game Streaming del mañana
- Confiar en que nuestras herramientas y plataformas de desarrollo proporcionan un entorno rápido, confiable y centrado en el desarrollador
- Aprovechar los nuevos servicios y experiencias multiplataforma de la forma más rápida y sencilla posible
Contenido
- Planificación del proyecto de migración
- Entorno de desarrollo
- Inicio de la aplicación
- Inicialización de aplicaciones
- Bucle de mensajes de Windows
- Creación de dispositivos Direct3D
- Presentación
- Administración de la duración de procesos (PLM)
- Administración de memoria
- Modelo de programación
- Sombreadores HLSL
- Administración de usuarios
- Redes e integración de los servicios XBOX
- Pasos siguientes
- Trucos y sugerencias
- Compatibilidad binaria y reutilización de componentes
- Estilo de codificación y procedimientos recomendados
- Consulte también
A efectos de esta guía de migración, supondremos que el destino son las plataformas Gaming.Xbox.XboxOne.x64 o Gaming.Xbox.Scarlett.x64. El Microsoft Game Development Kit (GDK) también incluye la plataforma Gaming.Desktop.x64. Es una variante de la plataforma x64 Win32 estándar, que no se trata en esta guía de migración.El valor principal de Gaming.Desktop.x64 es proporcionar una experiencia similar a Gaming.Xbox.*.x64 en cuanto a configuración de compilación, integración con Visual Studio, comportamiento del diseño suelto (loose layout), etc., cuando el destino es un PC. Como alternativa, puedes usar la plataforma x64 “estándar” e implementar toda la configuración y el empaquetado directamente para PC.
Planificación del proyecto de migración
Cuando migras una base de código existente al Microsoft Game Development Kit (GDK), normalmente partes de un proyecto existente del XBOX One Software Development Kit o de una aplicación clásica de escritorio Win32. Muchos desarrolladores con un título existente de XBOX One encontrarán que su base de códigoDurango es un mejor punto de partida, siempre que el uso de las API de Windows Runtime esté relativamente aislado. Las bases de código clásicas de escritorio Win32 están mucho más cerca del modelo de programación del Microsoft Game Development Kit (GDK), pero a menudo asumen esquemas de interfaz de usuario y control centrados en el escritorio que deben modificarse para la consola. Las bases de código clásicas de escritorio Win32 también tienden a tener mucha integración centrada en el escritorio, especialmente cuando se usan como parte del conjunto de herramientas de edición del juego, que utiliza conjuntos de API no compatibles con el Microsoft Game Development Kit (GDK) en XBOX. Empezar por cada una tiene ventajas y desventajas. En algunos casos, puede resultarte más fácil tomar elementos de ambos tipos para distintas partes de tu base de código.
Migración desde el XBOX One Software Development Kit
Si tu base de código ya es compatible con XBOX One a través del XBOX One Software Development Kit (también conocido como la plataformaDurango), ya has hecho la mayor parte del trabajo de modernizar el uso de API de tu aplicación. El código también debería estar bien optimizado para las restricciones específicas de la consola y, probablemente, hace un uso significativo de las extensiones específicas de XBOX One, como se indica a continuación.
- Se requiere DirectX 12.X. Si ya usas DirectX 12.X para tu título de XBOX One, no deberían ser necesarios cambios más allá de la API de presentación para tu uso de Direct3D.
Si actualmente usas DirectX 11.X, actualiza primero a DirectX 12.X. Esto puede ser más fácil de hacer con tu compilación existente del XBOX One Software Development Kit antes de pasar al Microsoft Game Development Kit (GDK). Para más detalles, consulta estos temas: Migración de Direct3D 11 a Direct3D 12, la charla de Xfest Introduction to Direct3D 12 on XBOX One (XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos) y la charla de Xfest Porting from Direct3D 11 to Direct3D 12 (XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos).
- En lugar de usar una cadena de intercambio DXGI, tu lógica de presentación debe usar la API PresentX.
- Se han realizado algunos cambios significativos en el subsistema de memoria del Game OS del GDK para el Microsoft Game Development Kit (GDK). Revisa la implementación de tu administrador de memoria.
- Para la entrada de mando, usa la nueva API GameInput en lugar de
Windows.Xbox.Input. - Dado que las API de Windows Runtime ya no se usan en la mayoría de los escenarios, reemplaza tu código C++/CX o C++/WinRT existente por las nuevas API COM de estilo Win32 o de estilo DirectX.
- La funcionalidad de Core Audio no ha cambiado. Sin embargo, es posible que se requieran algunos cambios de API, como se describe en la comparación de API de audio. Se admiten XAudio2 con extensiones XMA, WASAPI e
ISpatialAudioClient. - Al compilar en Visual Studio, agrega las configuraciones de plataforma
Gaming.Xbox.XboxOne.x64oGaming.Xbox.Scarlett.x64en lugar de tus configuraciones de plataformaDurango, y actualiza a Visual Studio 2019 o Visual Studio 2022.
Para ayudar a agregar nuevas configuraciones de plataforma hemos creado un ejemplo llamado SolutionUpdater. Esta herramienta de ejemplo toma un archivo de solución de Visual Studio existente y crea automáticamente las nuevas configuraciones de plataforma para todos los archivos de proyecto asociados a los que hace referencia la solución, lo que acelera enormemente el proceso y reduce la posibilidad de errores manuales. Para más información, revisa el documento incluido con el ejemplo.
Si tu base de código admite el modelo de aplicación de la Plataforma universal de Windows (UWP), tienes una ruta de migración similar a la del XBOX One Software Development Kit.
Migración desde el escritorio Win32 clásico
Si tu base de código solo admite el escritorio Win32 clásico, el proceso de migración podría ser bastante extenso, según lo reciente que sea la base de código con respecto a las API en desuso y otras características. Ten en cuenta que las bases de código clásicas de escritorio Win32 pueden abarcar un rango muy amplio de API que se remontan hasta la era de Windows 9x/ME. Esta lista no es exhaustiva de todos los posibles problemas que podrías encontrar. Cuando el destino es XBOX, también tendrás las consideraciones habituales de migrar de PC a consola: interfaz de usuario, modelos de entrada, pantalla de resolución fija, memoria limitada, etc.- Se requiere x64 nativo. Para más información, consulta Programación de 64 bits para desarrolladores de juegos.
- Se requiere DirectX 12.X. No se pueden usar DirectX 11, Direct3D 10, Direct3D 9 ni versiones anteriores. Además, OpenGL y Vulkan no se admiten. Para más detalles, consulta las guías de migración de DirectX11 y DirectX12.
- No se pueden usar los componentes heredados del SDK de DirectX D3DX9, D3DX10, D3DX11 y XACT. Para más información, consulta Microsoft Docs, Where is the DirectX SDK (2021 Edition)?, Living without D3DX y The Zombie DirectX SDK.
WINAPI_FAMILY_GAMESes un subconjunto de la familia completa de API Win32. Limítate a esas API.- Se requiere el empaquetado AppX. Actualiza tu proceso de empaquetado e implementación.
- Para la entrada de mando, usa la nueva API GameInput en lugar de
Windows.Gaming.Inputo DirectInput. - Para el audio, usa XAudio2, WASAPI, ISpatialAudioClient o middleware de audio compatible.
- Elimina los usos del Registro.
- El manejo de los mensajes de
WndProcdebe reducirse. Muchos de los mensajes, en particular los que tratan del posicionamiento, el tamaño de las ventanas y la integración con el shell, no se aplican al Microsoft Game Development Kit (GDK) en XBOX. - Si compilas con Visual Studio, actualiza tu código para que funcione con Visual Studio 2019 o Visual Studio 2022. En caso contrario, asegúrate de que tu compilación use las nuevas definiciones del preprocesador y se vincule con las bibliotecas de
GXDK\gameKit\lib\amd64, como la biblioteca paraguasxgameplatform.lib. - Para los componentes COM, solo se admite el modelo de subprocesamiento de apartamento multiproceso (MTA). Ten en cuenta que
COINITBASE_MULTITHREADEDes lo habitual para una aplicación Direct3D. - Solo se admite una única instancia de ventana. No se admiten varias instancias de ventana simultáneas ni cuadros de diálogo.
Entorno de desarrollo
Visual Studio 2019 (actualización 16.11) o Visual Studio 2022 es el entorno de desarrollo compatible con el Microsoft Game Development Kit (GDK). Instala lo siguiente:- Carga de trabajo: Desarrollo de juegos con C++ para el conjunto de herramientas principal
- Carga de trabajo: Desarrollo de UWP para las herramientas de empaquetado.
- Carga de trabajo (opcional): Desarrollo de escritorio con C++ para las herramientas y ejemplos del lado del PC.
El desarrollo con el XBOX One Software Development Kit con Visual Studio 2017 también requería el componente opcional Windows 8.1 SDK and UCRT SDK. Este componente no es necesario para el Microsoft Game Development Kit (GDK).Si todavía usas Visual Studio 2015 o una versión anterior, el primer paso de tu esfuerzo de migración es actualizar a Visual Studio 2019 o posterior.
Plataforma de Visual Studio
El Microsoft Game Development Kit (GDK) se integra con Visual Studio para proporcionar las plataformasGaming.Xbox.XboxOne.x64 y Gaming.Xbox.Scarlett.x64 cuyo destino es el Game OS del GDK de Microsoft en XBOX. Esto reemplaza a la plataforma Durango del XBOX One Software Development Kit.
Soluciones de compilación personalizadas
Para compilar código fuera de Visual Studio, se han cambiado las variables auxiliares de entorno para las ubicaciones. XBOX One Software Development Kit:En la ruta de ejemplo anterior, build_number representa la compilación instalada en tu sistema (por ejemplo, 190700).
%GameDKLatest%\GXDK\gameKit contiene todos los encabezados y bibliotecas para las extensiones específicas de la consola, y la biblioteca paraguas principal de la plataforma para vincular un binario del Microsoft Game Development Kit (GDK). De forma similar, %GameDKLatest%\GRDK\gameKit contiene los encabezados y bibliotecas de toda la funcionalidad que no es específica del desarrollo para consola. El Microsoft Game Development Kit (GDK) requiere que esté instalado el Windows 10 SDK (10.0.19041.0) o posterior como dependencia. Algunos encabezados y bibliotecas adicionales están disponibles en %GameDKLatest%\GXDK\toolKit para las herramientas de consola del lado del PC.
A partir de la versión de octubre de 2023, el Windows 11 SDK (10.0.22000.0) es la versión mínima admitida.También hay una serie de opciones y definiciones que deberías usar. Consulta las recomendaciones de modificadores del compilador y enlazador de Visual C++ para conocer todos los detalles, así como el ejemplo CMakeExample.
Compilador (cl.exe)
/D_GAMING_XBOXreemplaza tanto a/D_XBOX_ONE /D_TITLEcomo a/D_DURANGO./D_GAMING_XBOX_XBOXONEse define solo para la plataformaGaming.Xbox.XboxOne.x64./D_GAMING_XBOX_SCARLETTse define solo para la plataformaGaming.Xbox.Scarlett.x64./DWINAPI_FAMILY=WINAPI_FAMILY_GAMEScontrola la partición de API en lugar de la familia de APIWINAPI_FAMILY_TV_TITLE.- Debes definir
/DWIN32_LEAN_AND_MEAN,/D_ATL_NO_DEFAULT_LIBSy/D__WRL_NO_DEFAULT_LIB__ - Para el Microsoft Game Development Kit (GDK), ya no se usa ningún modificador de Windows Runtime como
/AI,/FUo/ZW. - Sigue usando
/favor:AMD64,/EHscy/fp:fast. - Para la plataforma
Gaming.Xbox.XboxOne.x64, sigue usando/arch:AVX - Para la plataforma
Gaming.Xbox.Scarlett.x64, usa/arch:AVX2
Con VS 2019 Update 3 o posterior y la plataformaGaming.Xbox.Scarlett.x64, usa también/d2vzeroupper. Si usas la optimización de todo el programa (WPO) / generación de código en tiempo de vínculo (LTCG), debe ser/d2:-vzeroupper.
Con VS 2022 y la plataformaGaming.Xbox.XboxOne.x64, usa también/d2vzeroupper-. Si usas la optimización de todo el programa (WPO) / generación de código en tiempo de vínculo (LTCG), debe ser/d2:-vzeroupper-.
Enlazador (link.exe)
- Vincula con
xgameplatform.lib,xgameruntime.lib,d3d12_x.libod3d12_xs.lib,xmem.libypixevt.lib. No useskernel32.lib,kernelx.lib,onecore.libniWindowsApp.lib. - Para la biblioteca XGraphics, usa
xg_x.liboxg_xs.lib. - No necesitas usar
/WINMDni/WINMDFILE, que eran para las API de Windows Runtime. - El Microsoft Game Development Kit (GDK) en XBOX no usa manifiestos incrustados, así que usa
/MANIFEST:NO. - Sigue usando
/DYNAMICBASE,/NXCOMPAT.
Deberías considerar usar/NODEFAULTLIBpara asegurarte de no vincular con ninguna biblioteca Win32 no compatible, incluidasadvapi32.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.
Optimización del uso de encabezados de Windows
El Microsoft Game Development Kit (GDK) usa el encabezado estándar<Windows.h>. Es útil definir las distintas definiciones de preprocesador “lean and mean”, además de WIN32_LEAN_AND_MEAN, como se mencionó anteriormente, para mantener bajo control el número total de encabezados de sistema Win32 que incorporas.
Runtime de Visual C++
Con el XBOX One Software Development Kit, los encabezados y bibliotecas del runtime de Visual C++ formaban parte del XBOX One Software Development Kit, y las DLL del runtime se colocaban dentro del Game OS. Esto requería actualizar a una versión más reciente del XBOX One Software Development Kit o a un nivel de QFE que coincidiera con la versión de actualización menor de Visual Studio que se usaba para compilar el código. Con el Microsoft Game Development Kit (GDK), las DLL del runtime de Visual C++ se incluyen como parte del paquete de tu juego y coinciden con la versión de Visual Studio que esté instalada localmente en la máquina de compilación.VCRuntime*.dllymsvcp*.dllson las DLL del runtime del compilador de Visual C++ y de la biblioteca estándar de C++. Hay unaucrtbase.dllincluida en el Game OS que también se usa.- Para las compilaciones de depuración, tu paquete contendrá
VCRuntime*d.dll,msvcp*d.dllyucrbased.dll
Si haces uso de la ERA Migration Library, también necesitasvccorlib*.dll, que el compilador usa al compilar con/ZW.
AMP no se admite para XBOX y se ha declarado en desuso en la versión más reciente de Visual C++.
Inicio de la aplicación
Los proyectos del Microsoft Game Development Kit (GDK) usan una versión simplificada del inicio de aplicación y el bucle de mensajes de estilo escritorio de Win32, no los eventos de CoreWindow de estilo Windows Runtime. Tu base de código existente debería tener uno de los siguientes puntos de entrada.Desarrollo de escritorio Win32
Aplicación del XBOX One Software Development Kit o UWP con C++/CX
Aplicación del XBOX One Software Development Kit o UWP con C++/WinRT
Microsoft Game Development Kit (GDK) en XBOX
Para los títulos del GDK, el punto de entrada es el mismo que en el escritorio clásico Win32.Inicialización de aplicaciones
Una función de punto de entrada Win32 típica y muy básica tiene este aspecto.- Uso mínimo de clases y estilos de ventana
- Cadenas UTF-8 en lugar de UTF-16LE
- Inicialización del subsistema Game Runtime
Para los títulos del Microsoft Game Development Kit (GDK) en XBOX, solo puedes tener una ventana Win32.
Bucle de mensajes de Windows
Dado que muchos mensajes no se aplican, las aplicaciones del Microsoft Game Development Kit (GDK) en XBOX pueden usar un bucle de mensajes Win32 muy básico.Creación de dispositivos Direct3D
Los juegos compilados con el Microsoft Game Development Kit (GDK) en XBOX usan la API Direct3D 12.X, que se implementa como el runtime monolítico, tal como se implementa con el XBOX One Software Development Kit.
Direct3D 12 estándar y Direct3D 11 no se admiten para los juegos compilados con el Microsoft Game Development Kit (GDK) en XBOX. Cuando crees un dispositivo Direct3D 12 para DirectX 12.X, usa el método
D3D12XboxCreateDevice.
API XMem*
Cualquier llamada a las APIXMem* que use XMEM_GRAPHICS requiere que el dispositivo Direct3D se haya creado antes de usarlas. Como alternativa, puedes llamar a D3DConfigureVirtualMemory si necesitas usar esas llamadas antes de que exista el dispositivo Direct3D.
Reserva de CPU/GPU
Todos los títulos del Microsoft Game Development Kit (GDK) obtienen los recursos completos (es decir, sin reserva de GPU para Kinect) y el séptimo núcleo de CPU. De forma predeterminada, obtienes el equivalente de la siguiente configuración de manifiesto del XBOX One Software Development Kit.Diferencias de Direct3D entre XBOX One y XBOX Series X|S
La implementación del runtime monolítico de Direct3D 12.x para la plataformaGaming.Xbox.XboxOne.x64 es casi idéntica a la implementación de Direct3D 12.x del XBOX One Software Development Kit. Para tu migración inicial al Microsoft Game Development Kit (GDK) en XBOX, esta plataforma es probablemente el punto de partida más fácil.
Gaming.Xbox.Scarlett.x64admite hasta las interfaces ID3D12Device8 e ID3D12GraphicsCommandList5 o versiones posteriores.Gaming.Xbox.XboxOne.x64admite hasta ID3D12Device, ID3D12Device1, ID3D12Device2 e ID3D12GraphicsCommandList.
Gaming.Xbox.Scarlett.x64, hay algunas capacidades adicionales, así como algunas diferencias en la implementación de Direct3D 12.x.
- Necesitas usar una versión diferente de los encabezados y bibliotecas de Direct3D (es decir,
d3d12_xs.h,d3dx12_xs.h,xg_xs.h,d3d12_xs.lib, etc.). No puedes mezclar las dos versiones de Direct3D 12.x en el mismo binario. - Cuando se implementó por primera vez el runtime monolítico de Direct3D 12.x, se construyó sobre el runtime monolítico de Direct3D 11.x, por lo que hay varios tipos de Direct3D 11 definidos al compilar con las plataformas
DurangooGaming.Xbox.XboxOne.x64. Estos se han eliminado de la implementación de XBOX Series X|S, por lo que podrías encontrarte con problemas de compilación con cualquier referencia residual al encabezadod3d11_x.h, las definicionesD3D11_*, las clasesCD3D11_*o las interfacesID3D11*. Se pueden eliminar y aun así compilar para ambas plataformas. - ESRAM no es una característica de XBOX Series X|S, por lo que las extensiones relacionadas con ESRAM no están definidas para esta plataforma. Esto también significa que
xgmemory.h(una utilidad auxiliar para usar ESRAM) solo se admite para la plataformaGaming.Xbox.XboxOne.x64.
Sigue siendo importante utilizar ESRAM en los dispositivos XBOX One / XBOX One S para un rendimiento de representación óptimo. Consulta los ejemplos SimpleESRAM y AdvancedESRAM.
- Hay varias diferencias en los diseños de memoria de la GPU, en particular en las técnicas de H-tile y C-Mask. Para más detalles, consulta los ejemplos CMaskDecode, HiZDecode, HiStencil y PrimeHTile.
Presentación
El Microsoft Game Development Kit (GDK) en XBOX no admite las cadenas de intercambio DXGI heredadas para la presentación, sino que usa la API PresentX. Las nuevas API PresentX están diseñadas para abordar los problemas de latencia de las cadenas de intercambio DXGI y proporcionan al desarrollador un control más directo de los búferes de presentación. Esta API también está diseñada para escalar para futuras aplicaciones de streaming. El primer paso para usar PresentX es registrarse para los eventos de fotograma después de crear el dispositivo Direct3D.D3D12_HEAP_FLAG_ALLOW_DISPLAY.
WaitFrameEventX.
DXGI_ERROR_DEVICE_REMOVED y DXGI_ERROR_DEVICE_RESET, que deben manejarse en los juegos para PC.
Se ha eliminado otra funcionalidad relacionada de DXGI, y la función ScheduleFrameEventX mencionada anteriormente sustituye a DXGIXSetFrameNotification del XBOX One Software Development Kit.
Este es el código del XBOX One Software Development Kit para la notificación de cambio de fotograma (flip).
Administración de la duración de procesos (PLM)
Los juegos compilados con el Microsoft Game Development Kit (GDK) en XBOX usan el mismo modelo básico de administración de la duración de procesos (PLM) que utilizan las aplicaciones del XBOX One XDK y las aplicaciones UWP. Las aplicaciones se ejecutan sin restricciones, con restricciones, suspendidas o finalizadas; es decir, no se ejecuta ningún código para la finalización y el proceso simplemente se destruye. Las aplicaciones del XBOX One Software Development Kit y las aplicaciones UWP reciben notificaciones a través de su CoreWindow de Windows Runtime. Los juegos del Microsoft Game Development Kit (GDK) en XBOX reciben notificaciones a través de devoluciones de llamada registradas. Ten en cuenta que solo hay un evento de suspensión y otro de reanudación, y ya no hay una fase de activación explícita. Un enfoque de implementación sencillo es manejar esto publicando un mensajeWM_USER.
WM_USER para garantizar que el bucle se pause hasta la reanudación, y que el comportamiento adecuado de suspensión/reanudación de la GPU tenga lugar en un momento seguro del bucle de representación.
Restringido frente a completo
La notificación de recursos restringidos frente a completos se maneja mediante una API similar.Finalización de procesos
Para los títulos comerciales, la finalización de procesos se maneja igual que en la plataforma anterior del XBOX One Software Development Kit. El proceso se suspende y después se finaliza. No se procesa ninguno de los destructores de C++ ni la limpieza. Esto también era cierto si llamabas aWindows::ApplicationModel::Core::CoreApplication::Exit.
Con el Microsoft Game Development Kit (GDK), puedes lograr una salida limpia como en las aplicaciones clásicas de escritorio Win32 mediante PostQuitMessage. Esto hace que tu bucle de mensajes finalice y que se realicen la limpieza normal del código y el desmontaje del proceso. Esto es útil durante el desarrollo para ayudar a detectar fugas y otros problemas de limpieza que, de otro modo, pueden ser difíciles de encontrar. Sin embargo, es probable que este comportamiento invoque rutas de código que nunca se ejecutan en la plataforma anterior del XBOX One Software Development Kit.
Administración de memoria
Para más información sobre la administración de memoria, consulta Información general sobre la memoria.Cambios en el modelo de memoria
La plataforma del Microsoft Game Development Kit (GDK) incluye muchos cambios realizados en el modelo de memoria con respecto al Game OS original de XBOX One. La mayor parte de este esfuerzo se ha dedicado a mejorar el aislamiento de la memoria usada por el título respecto de la memoria usada por el sistema. Mejorar el aislamiento haría que el uso de memoria fuera más predecible entre el título y el sistema, y evitaría un uso inesperado por parte de las llamadas del sistema. Como parte de este trabajo, estamos pasando a la versión más reciente del subsistema de administración de memoria de Windows. Aunque muchos juegos no requerirán cambios importantes, deberías examinar cuidadosamente tu uso de estas API de memoria. Los significados y el comportamiento de las marcas han cambiado. Si asignas y mapeas páginas físicas manualmente, ten en cuenta que algunas restricciones de los mapeos han cambiado y que debe seguirse un patrón diferente para las API.- Cuando las páginas físicas se mapean en el espacio de direcciones virtuales más de una vez, todas las asignaciones deben compartir la misma configuración de coherencia de caché. Por ejemplo, no puedes mezclar la configuración de páginas Write Combined y la de lectura/escritura normal de CPU en la misma memoria física.
- La configuración de páginas y los valores de coherencia de caché ahora residen en la región de direcciones virtuales en la que se mapean las páginas. Esta región debe reservarse con antelación llamando a XMemVirtualAlloc y usando el patrón
MEM_RESERVE. Este paso no era necesario en la versión anterior del sistema operativo.
MEM_LARGE_PAGES. Sus valores y significados han cambiado para coincidir con los significados usados en todo Windows.
Con el cambio de las páginas grandes de 4 MB en el Game OS de XBOX One a 2 MB en el sistema operativo del Microsoft Game Development Kit (GDK) en XBOX, los especificadores de tamaño de XMemAlloc también han cambiado para las páginas grandes de
XALLOC_PAGESIZE_4MB a XALLOC_PAGESIZE_2MB.
Nuestro mapa de memoria también ha cambiado y ya no está segmentado en las regiones Legacy, Title, Graphics y Physical. Ahora cubren todo el espacio de direcciones de 8 TB.
Cambios en las API
Las API de memoria del Microsoft Game Development Kit (GDK) comienzan con el prefijo XMem y, en su mayor parte, reflejan las API ya existentes en el sistema operativo del XBOX One XDK, aunque su comportamiento ha cambiado.
Las nuevas API se muestran en la siguiente tabla.
Uso de XMemVirtualAlloc en lugar de VirtualAlloc
En el Microsoft Game Development Kit (GDK), la nueva APIXMemVirtualAlloc reemplaza todos los usos de VirtualAlloc para asignar memoria gráfica de XBOX. Ten en cuenta los requisitos anteriores para especificar los requisitos de página de GPU y coherencia de caché en las reservas que posteriormente se respaldan con mapeos físicos.
Una comparación de una reserva de este tipo en el XBOX One Software Development Kit:
Uso de VirtualFree
La memoria asignada porVirtualAlloc o XMemVirtualAlloc se sigue liberando con VirtualFree. No hay una API XMemVirtualFree.
Uso de XMemAlloc
La macro Attributes ahora tiene un parámetro adicional. Por ejemplo:XMemAllocatePhysicalPages y XMemMapPhysicalPages
Con el cambio de mover las marcas de página y la coherencia de caché al momento de la reserva, las llamadas para asignar y mapear memoria física se simplifican, pero por lo demás son similares a las del XBOX One Software Development Kit.XMemAllocatePhysicalPages reemplaza a AllocateTitlePhysicalPages. XMemMapPhysicalPages reemplaza a MapTitlePhysicalPages.
Este código del XBOX One Software Development Kit:
Modelo de programación
Para más información sobre el modelo de programación, consulta el tema Modelo de programación asincrónica.Código sincrónico (con bloqueo) con GameRuntime
Para las API en las que el bloqueo es una opción razonable, se han proporcionado las versiones con bloqueo (sincrónicas) de toda la funcionalidad de la biblioteca, incluso si las llamadas fueran de larga duración. El desarrollador puede generar subprocesos y llamar a las funciones con bloqueo desde esos subprocesos usando el programador para administrar la simultaneidad, lo que a menudo es más sencillo de implementar que los futures y promises de estilo C++11. Hay algunos casos (como las llamadas de red) en los que se sabe que el tiempo de ejecución de las funciones no es determinista, por lo que solo se proporcionan versiones asincrónicas.Código asincrónico con GameRuntime
La plataforma del Microsoft Game Development Kit (GDK) incluye un nuevo modelo para realizar tareas asincrónicas y notificar sus resultados mediante devoluciones de llamada. Este modelo reemplaza a Windows Runtime. Usa las API de GameRuntime para especificar cómo y dónde se producen el trabajo asincrónico y las devoluciones de llamada. El siguiente código de ejemplo incluye ejemplos básicos y sencillos de cómo se configura una cola de tareas del Game Runtime para procesar tus llamadas del sistema. Esta cola puede usarse para procesar tareas del sistema y como la ubicación donde se ejecutan las devoluciones de llamada. Conceptualmente, una devolución de llamada es una tarea que ejecuta tu código en respuesta a acciones del sistema. Si es necesario, puedes crear varias colas de tareas para administrar el trabajo en distintos núcleos, o para especificar la cola que ejecuta las devoluciones de llamada llamada por llamada. El despacho de los elementos de trabajo en cola puede bombearse manualmente desde tu código (esto es similar a una cola de mensajes de Windows) o bombearse automáticamente. Los siguientes son ejemplos sencillos de cómo se crea y luego se bombea una cola bombeada manualmente.Patrón general de nomenclatura para las llamadas API asincrónicas
La siguiente tabla muestra el patrón general usado por el Microsoft Game Development Kit (GDK) y el Game Runtime para nombrar las llamadas asincrónicas.XAsyncBlock reemplaza a IAsyncOperation e IAsyncAction
Al llamar a una función asincrónica, crea una estructuraXAsyncBlock, que debe mantenerse viva durante toda la llamada hasta que se haya completado, cancelado o haya fallado.
El tipo XAsyncBlock contiene tres parámetros de relevancia inmediata.
Ejemplo de uso:
Ten en cuenta que es fundamental que “rellenes con ceros” la estructura XAsyncBlock cuando la crees, de ahí el uso de{}en lugar de().
Operaciones sensibles al tiempo
Las bibliotecas del Microsoft Game Development Kit (GDK) te permiten especificar si el subproceso desde el que llamas es sensible al tiempo. Se pueden notificar advertencias en tiempo de ejecución si llamas a funciones que no son sensibles al tiempo desde un subproceso sensible al tiempo.SetTimeSensitiveThread(true) en el subproceso. También puedes llamar a VerifyNotTimeSensitiveThread() desde dentro de las funciones de larga duración de tu propio código para notificar un uso indebido desde subprocesos de tiempo crítico.
Sombreadores HLSL
La plataforma del XBOX One Software Development Kit usaba una versión personalizada del compilador HLSLFXC.EXE que admitía la precompilación de sombreadores programables del Shader Model 5.1 a microcódigo ATI. Además, se admitía en versión preliminar el compilador DXIL DXC.EXE para el Shader Model 6.
Para el Microsoft Game Development Kit (GDK) en XBOX, se recomienda el uso del compilador DXIL y el Shader Model 6 mediante DXC.EXE. El compilador FXC.EXE del Shader Model 5.1 se considera ahora heredado. El nuevo compilador admite la mayoría de las marcas de línea de comandos admitidas por el compilador antiguo, aunque algunas de las defines de extensión específicas de XBOX no son aplicables o no se admiten. Para más detalles sobre el Shader Model 6 y DXIL, consulta el proyecto de GitHub.
Para el uso del Shader Model 6 en PC: Windows 10 Creators Update y versiones posteriores admiten los sombreadores DXIL del Shader Model 6.x, al igual que muchos controladores comerciales. En lugar de depender de los controladores WHQL de Windows Update para esta característica, necesitas instalar el controlador más reciente directamente desde su proveedor. El compilador
DXC.EXE para Windows se incluye en el SDK de Windows 10 April 2018 Update y versiones posteriores. En tiempo de ejecución, puedes determinar si tu PC admite el Shader Model 6.x mediante CheckFeatureSupport usando D3D12_FEATURE_SHADER_MODEL, pero ¡asegúrate de inicializar shaderModel.HighestShaderModel antes de llamar a la función!%GameDKLatest%\GXDK\bin\XboxOne\DXC.exe.
La versión de XBOX Series X|S del compilador DXIL se encuentra aquí: %GameDKLatest%\GXDK\bin\Scarlett\DXC.exe.
API D3DCompile
Para el Shader Model 6, deberías usar la bibliotecadxcompiler_x.lib o dxcompiler_xs.lib en lugar de d3dcompiler_x.lib.
Administración de usuarios
El modelo de usuarios ha cambiado en el Microsoft Game Development Kit (GDK) con respecto a lo que podrías estar acostumbrado en el XBOX One Software Development Kit. Esto se debe, en parte, a la necesidad de administrar mejor las expectativas de privacidad de los usuarios y a aliviar la carga de tener que estar siempre al tanto de lo que el sistema hace en segundo plano con usuarios que al título no deberían importarle. En lugar de que los títulos supervisen una colección de todo el sistema con los usuarios e invitados que han iniciado sesión en la consola, el sistema solo expone los usuarios a petición. Para adquirir un usuario para tu título (por ejemplo, cuando el usuario presiona el botón A de un mando para iniciar una sesión de juego y el mando aún no se ha asociado a un usuario), realiza una llamada a XUserAddAsync. Esta llamada realizará dos acciones importantes: inicia la sesión de los usuarios en el título y actualiza el emparejamiento de dispositivos de entrada de los usuarios. Los usuarios pueden tener cualquier cantidad de dispositivos de entrada emparejados a la vez. Sin embargo, el título solo recibe información sobre las asociaciones de los usuarios que han iniciado sesión con XUserAddAsync. Si se usa la Guía del sistema para iniciar la sesión de un usuario o cambiar asociaciones fuera del título a un usuario que el título desconoce, entonces al título solo se le indica que el dispositivo de entrada se ha desemparejado. El sistema fuera del título, sin embargo, sigue conociendo el emparejamiento para uso del sistema. Los títulos pueden supervisar los cambios en el estado de un usuario o en la información asociada a un usuario (como su gamertag, imagen de jugador o privilegios) suscribiéndose aXUserChangeEvent (aunque parte de esta información, como el estado de inicio de sesión del usuario, podría supervisarse mediante sondeo). Esto se hace llamando a XUserRegisterForChangeEvent.
La mayoría de los títulos deberían prever la necesidad de crear su propia colección de usuarios, hacer el seguimiento de cuándo los usuarios inician sesión en el título, hacer el seguimiento de las asociaciones de dispositivos de entrada y manejar el cierre de sesión de los usuarios.
Para una discusión en profundidad de estos cambios, consulta Usuarios y dispositivos de entrada. Consulta también el ejemplo UserManagement.
Redes e integración de los servicios XBOX
Transporte de red
El Microsoft Game Development Kit (GDK) en XBOX admite tanto WinSock2 como BCrypt mediante CNG. Si usas UDP, en lugar de codificar de forma rígida un puerto como el 3074 para el enlace del socket multijugador, para el Microsoft Game Development Kit (GDK) deberías hacer uso de esta nueva API C plana:Windows.Networking.Connectivity. Para código de ejemplo, consulta Inicialización de red y conectividad.
Los sockets seguros (espacio de nombres
Windows.Xbox.Networking) se han eliminado para el Microsoft Game Development Kit (GDK).Solicitudes web mediante HTTP
El Microsoft Game Development Kit (GDK) ya no admiteIXMLHTTPRequest2 ni MessageWebSocket / StreamWebSocket (espacio de nombres Windows.Networking.Sockets). En su lugar, deberías hacer uso de WinHTTP.
Para más detalles, consulta Solicitudes web.
API de los servicios XBOX
Los desarrolladores que actualmente usan las versiones de Windows Runtime o C++ de XSAPI deberán pasar a usar la versión C plana para las características de integración de los servicios XBOX:- Logros
- Presencia
- Perfil
- Social
- Social Manager
Pasos siguientes
Después de completar tu migración inicial desde ERA, estarás en una excelente posición para habilitar una serie de características del Microsoft Game Development Kit (GDK) en XBOX. Si tu título funciona bien en hardware XBOX One S / XBOX One X, estas son formas fáciles de mejorar la experiencia en las consolas XBOX Series X|S. Ten en cuenta que muchas de estas características se habilitan automáticamente para los títulos ERA heredados, pero son de participación voluntaria (opt-in) para los títulos del Microsoft Game Development Kit (GDK) en XBOX. Ahora que tu título es nativo del Microsoft Game Development Kit (GDK) en XBOX, ¡asegúrate de habilitarlas!- AutoHDR: esta característica convierte automáticamente un título SDR a HDR a nivel de sistema, mejorando la calidad visual del juego cuando se reproduce en una pantalla compatible con HDR10. Usa hardware específico de XBOX Series X|S, por lo que no hay costo adicional de CPU, GPU, memoria, ancho de banda ni latencia. La mejora visual no cambia la intención artística original y expande el brillo hasta 1000 nits y los colores al espacio de color P3-D65. Una implementación HDR nativa siempre será mejor, ya que permite un control artístico total, pero si no tienes los recursos o el tiempo para implementar HDR nativo, AutoHDR es una forma fácil y eficaz de lograr una experiencia mejorada.
- Aniso Boost: se obtiene una mejora de la calidad de imagen en las consolas XBOX Series X|S promoviendo el filtrado lineal de texturas a filtrado anisotrópico completo. Esta es una forma rápida y fácil de aplicar potencia adicional de GPU a un título de juego existente. Como título del Microsoft Game Development Kit (GDK) en XBOX, esto se logra usando la configuración
D3D12_FILTER_ANISOTROPICpara tus estados de muestreador en lugar deD3D12_FILTER_MIN_MAG_MIP_LINEARcuando se ejecuta en XBOX Series X|S:
- FPS Boost: otra mejora sencilla es aumentar la velocidad de fotogramas de representación en las consolas XBOX Series X|S. Si tu título se ejecuta a 30 fps en XBOX One S / XBOX One X (
D3D12XBOX_FRAME_INTERVAL_30_HZ), normalmente puede ejecutarse a 60 fps en XBOX Series X|S (D3D12XBOX_FRAME_INTERVAL_60_HZ). Si se ejecuta a 60 fps en XBOX One S/X, es probable que pueda ejecutarse a 120 fps en XBOX Series X|S. Consulta Compatibilidad con 120 Hz y el ejemplo Simple120Hz para más información.
Además del aumento de la velocidad de fotogramas, es probable que también puedas representar a 4K en XBOX One X y XBOX Series X con el mismo rendimiento que a 1080p en XBOX One S / XBOX Series S.
- Quick Resume: esta característica es automática en su mayor parte, siempre que tu título implemente correctamente la administración del ciclo de vida de procesos (PLM). Consulta Ciclo de vida del juego de XBOX para más detalles.
Trucos y sugerencias
Archivo de empaquetado Microsoft Game Config
El Microsoft Game Development Kit (GDK) ya no usa un archivoPackage.appxmanifest durante la cadena de herramientas de compilación de Visual Studio para generar AppxManifest.xml. En su lugar, se usa un archivo MicrosoftGameConfig para alojar toda la configuración del paquete de la aplicación en tiempo de desarrollo.
Executable Name debe coincidir con el nombre del EXE en el diseño del paquete.
Ten en cuenta que puedes crear un proyecto nuevo usando Visual Studio. Selecciona File, New Project y, a continuación, selecciona la plantilla Direct3D 12 XBOX Game del Microsoft Game Development Kit (GDK). Después puedes agregar a tu proyecto el archivo MicrosoftGame.config creado por la plantilla.
Como opción, puedes agregar los distintos recursos de interfaz de usuario y relacionados con la Store, que deben estar presentes en el paquete, agregando una sección <ShellVisuals>.
Ten en cuenta que el XBOX One Software Development Kit tenía un elemento WideLogo; ahora se hace referencia a él como el atributo Square480x480Logo.
Para la integración de los servicios XBOX, también necesitas proporcionar un Title ID.
.config. Para una definición completa de las opciones permitidas, consulta Archivo MicrosoftGameConfig.
Obtención del tipo de dispositivo
El método GetConsoleType del XBOX One Software Development Kit no está disponible para el Microsoft Game Development Kit (GDK). Usa en su lugar la API de GameRuntime XSystemGetDeviceType.Reemplazo en el GDK de xdk.h y _XDK_VER
En el XBOX One Software Development Kit, el encabezado xdk.h proporcionaba una serie de símbolos de compilación relacionados con el número de compilación del XDK, el nivel de QFE, etc.
Para las plataformas Gaming.*.x64, puedes hacer uso de grdk.h:
_GRDK_VERes la codificación de versión del GDK de Gaming usado para compilar el binario (HIWORD.LOWORD). Por ejemplo,0x4A610479es el número de compilación 19041.1145._GRDK_VER_STRINGpara esa compilación es “April 2020 GRDK”._GRDK_VER_STRING_Wes el equivalente en cadena ancha UTF16-LE de_GRDK_VER_STRING._GRDK_VER_STRING_COMPACT_Wpara esa compilación es una cadena ancha UTF16-LE que contiene “April 2020”.
Gaming.Xbox.*.x64, también puedes hacer uso de gxdk.h:
_GXDK_VERes la codificación de versión del GDK de Gaming usado para compilar el binario (HIWORD.LOWORD). Por ejemplo,0x4A610479es el número de compilación 19041.1145._GXDK_VER_STRINGpara esa compilación es “April 2020 GXDK”._GXDK_VER_STRING_Wes el equivalente en cadena ancha UTF16-LE de_GXDK_VER_STRING._GXDK_VER_STRING_COMPACT_Wpara esa compilación es una cadena ancha UTF16-LE que contiene “April 2020”.
Obtención del identificador del punto de conexión de representación de audio predeterminado
Las API de Windows Runtime Windows.Media.Devices y Windows.Devices.Enumeration no se usan para el Microsoft Game Development Kit (GDK) en XBOX. Para obtener el representador predeterminado, usa el código siguiente.MapVirtualKey
Los métodosMapVirtualKey y MapVirtualKeyEx no se admiten para el Microsoft Game Development Kit (GDK) en XBOX. Lo más común es que se usen para detectar las teclas VK_SHIFT izquierda y derecha en el código que maneja el teclado.
MultiByteToWideChar y WideCharToMultiByte
Al convertir entre cadenas de caracteres anchos (UTF-16 LE) y cadenas de caracteres estrechos, los desarrolladores de Win32 suelen usar MultiByteToWideChar y WideCharToMultiByte. Para las bases de código modernas, recomendamos usarCP_UTF8 en lugar de una página de códigos específica o CP_ACP.
El código siguiente funciona en Windows 7 Service Pack 1 y posteriores.
CP_ACP se trata como un alias de CP_UTF8. En Windows 10 moderno y con el Microsoft Game Development Kit (GDK), normalmente puedes reemplazar todas las instancias de CP_ACP por CP_UTF8 usando buscar y reemplazar. Para simplificar este tipo de migración, se eliminó la validación de otros parámetros relacionados con CP_UTF8.
C++11 agregó el encabezado <codecvt> como una solución más portable al problema de convertir cadenas, pero ya se ha declarado en desuso en C++17. La recomendación es seguir con las funciones de cadena de la plataforma.
API de localización y globalización
En ERA, faltaba la mayor parte de la compatibilidad integrada de Windows para la localización, más allá de la simple selección de página de códigos, la traducción de puntos de código (la conversión de multibyte a widechar) y el informe de la configuración regional del sistema/usuario. Para el Microsoft Game Development Kit (GDK), esta funcionalidad de localización es totalmente compatible, al igual queGetCurrencyFormatEx, GetNumberFormatEx, la enumeración de formatos de fecha y hora, y otras características.
Notas sobre el audio XMA2
Si te falta la definición deSHAPE_XMA_INPUT_BUFFER_ALIGNMENT, tendrás que agregar explícitamente una referencia al encabezado shapexmacontext.h.
Compatibilidad con cuadros de mensaje de interfaz de usuario
Para ayudar a mejorar la depuración de bloqueos y errores de inicialización tempranos dentro de un título, se ha agregadoXGameUiShowMessageDialogAsync a la colección de API de interfaz de usuario invocable desde el título (TCUI). Esta API puede usarse en cualquier momento después de que se haya llamado a XGameRuntimeInitialize, incluso antes de la inicialización de D3D. La API se representa dentro de la partición del sistema y se compone sobre la salida del juego. Sigue funcionando incluso si el bucle del juego está detenido o aún no está representando. Esto puede ser muy útil para notificar información de errores de bloqueo, o incluso para solicitar la conexión del depurador mientras se bloquea en el lugar del error. Está pensada principalmente como una herramienta de diagnóstico en tiempo de desarrollo.
Este ejemplo muestra un cuadro de diálogo de error de estilo bloqueante, que solicita al desarrollador que se conecte para investigar.
Bibliotecas de extensión
En el XBOX One Software Development Kit, con el uso de las API de Windows Runtime, agregar bibliotecas de extensión como XSAPI o Game Chat requería usar el cuadro de diálogo ‘References…’ de Visual Studio. Para el Microsoft Game Development Kit (GDK), este mecanismo ya no se usa. En su lugar, pueden agregarse mediante las propiedades del proyecto de Visual Studio. Esto edita un elemento de propiedad en la sección Globals delvcxproj:
Compatibilidad binaria y reutilización de componentes
Uno de los principios rectores del Microsoft Game Development Kit (GDK) es maximizar la capacidad de los desarrolladores de reutilizar su trabajo entre Windows de escritorio y los títulos de consola XBOX. Un aspecto de esto que no se ha tratado anteriormente es que se ha trabajado para mejorar la compatibilidad binaria entre Windows de escritorio y el sistema operativo del Microsoft Game Development Kit (GDK) en XBOX. A diferencia de los títulos del XBOX One Software Development Kit, el Microsoft Game Development Kit (GDK) en XBOX puede reutilizar una variedad de componentes que se compilaron originalmente para Windows de escritorio x64. Esto puede ser una valiosa característica de ahorro de tiempo para la creación de prototipos, herramientas u otros escenarios que no sean críticos para el rendimiento. No hay herramientas en el Microsoft Game Development Kit (GDK) para determinar si un componente de Windows de escritorio puede reutilizarse, sino que esto viene determinado por las API del sistema operativo que consume el componente en cuestión. Las API compatibles del sistema operativo del Microsoft Game Development Kit (GDK) en XBOX pueden obtenerse ejecutandodumpbin.exe /exports en las bibliotecas que se incluyen con el Microsoft Game Development Kit (GDK). Aunque algunas API específicas de un área residen en sus propias bibliotecas (como D3D12XboxCreateDevice dentro de d3d12_x.lib o d3d12_xs.lib), la mayoría de las API Win32 heredadas se agregan en una única biblioteca llamada xgameplatform.lib. El siguiente comando, cuando se ejecuta desde un símbolo del sistema para desarrolladores de Visual Studio, muestra el conjunto principal de API Win32 compatibles (aparte de las que residen en otra biblioteca de importación).
dumpbin.exe /exports "c:\Program Files (x86)\Microsoft GDK\build_number\GXDK\gameKit\lib\amd64\xgameplatform.lib"
En la ruta de ejemplo anterior, build_number representa la compilación instalada en tu sistema (por ejemplo, 190700).
Estilo de codificación y procedimientos recomendados
La guía de Code Generation for XBOX One - Best Practices (XBOX Developer Downloads->XBOX One->All XBOX One XDK CHMs) se aplica al Microsoft Game Development Kit (GDK). La principal diferencia en la configuración del compilador es que estos proyectos no requieren el uso de C++/CX (/ZW) ni C++/WinRT, porque la mayoría de las API de juego tienen el estilo de COM de tipo Win32 o DirectX. Aquí tienes algunas recomendaciones generales:
- Aprovecha la conformidad del lenguaje C++14 y, opcionalmente, C++17. Ten en cuenta que el diseño de las API del Microsoft Game Development Kit (GDK) asume un compilador C++11 o mejor.
- El proceso de generación de código de punto flotante nativo x64 siempre usa SSE/SSE2. XBOX One admite
/arch:AVX, así como F16C. - El manejo de excepciones de C++ (
/EHsc) tiene poca o ninguna sobrecarga en el código nativo x64. Sin embargo, el lanzamiento de excepciones en tiempo de ejecución no es un escenario de rendimiento, por lo que no debería usarse para controlar el flujo. - El uso de técnicas de codificación seguras frente a excepciones, como las descritas en Objects Own Resources (RAII) y Resource Acquisition Is Initialization, es un procedimiento recomendado muy aconsejable usando
std::unique_ptr,Microsoft::WRL::ComPtry otras clases de punteros inteligentes. - Da preferencia al uso de tipos portables estándar como
size_t,ptrdiff_t,int8_t,uint8_t,int16_t,uint16_t,int32_t,uint32_t,int64_t,uint64_t,intptr_tyuintptr_t. - Para minimizar el relleno interno, agrupa los punteros en estructuras y clases.
- En lugar de la conversión heredada de estilo C, da preferencia a las conversiones de C++ como
const_cast<>,static_cast<>,reinterpret_cast<>ydynamic_cast<>. - Usa intrínsecos siempre que sea posible. El código nativo x64 no admite ensamblado en línea.
Modificadores del compilador y del enlazador
Usa los siguientes modificadores:/O1 /Oipara optimización general y/O2para los módulos críticos/fp:fast/arch:AVXpara la familia de dispositivos XBOX One;/arch:AVX2para XBOX Series X|S./favor:AMD- Optimización de todo el programa y optimización guiada por perfiles
- Modificadores del enlazador
/OPT:REF,ICF
/Ox es casi lo mismo que /O2, pero le faltan tanto /GF (Eliminar cadenas duplicadas) como /Gy (Habilitar vinculación en el nivel de función). Da preferencia a /O2 sobre /Ox. Si usas /Ox, asegúrate de habilitar explícitamente al menos /Gy, que es importante para habilitar la optimización del enlazador.
También se han agregado varios modificadores nuevos del compilador a Visual C++ desde el lanzamiento del XBOX One Software Development Kit, así que asegúrate de informarte sobre ellos: /Zc:inline, /Zc:throwingNew, /Zc:__cplusplus, /volatile:iso, /permissive-, /Zc:twoPhase- y /Debug:FASTLINK.
Código condicional
Para el código condicional en el que las rutas divergen, ten en cuenta las siguientes convenciones.
Si tu base de código ya admite el XBOX One Software Development Kit, un buen punto de partida es hacer lo siguiente:
- Buscar todas las instancias de
_XBOX_ONEen tu base de código - Cambiar las instancias como
#if defined(_XBOX_ONE) && defined(_TITLE), donde el código usa las extensiones de DirectX 12.X, convirtiéndolas en estos casos:
#if (defined(_XBOX_ONE) && defined(_TITLE)) || defined(_GAMING_XBOX)
UTF-8 en todas partes
En la larga historia de la plataforma Windows, las funciones ANSI originales llevan mucho tiempo en desuso en favor de la solución Unicode de caracteres anchos, es decir, CreateFileW en lugar de CreateFileA. Esto resolvió el problema de tratar con una gran cantidad de páginas de códigos diferentes y simplificó todas las cadenas localizables awchar_t* (UTF-16 LE, little endian). El manifiesto UTF-8 Everywhere defiende que la codificación multibyte UTF-8 con char* es una mejor solución en términos de huella de memoria y portabilidad.
Para la plataforma del Microsoft Game Development Kit (GDK) en XBOX, la página de códigos predeterminada está establecida en CP_UTF8, por lo que cualquier versión ANSI de las API de la plataforma Win32 usa UTF-8. Puedes seguir usando las API de caracteres anchos con UTF-16 LE, pero también tienes la opción de usar UTF-8.
La compatibilidad completa con UTF-8 en Windows es una incorporación muy reciente, por lo que aún no está muy extendida. También es algo en lo que el usuario tiene que participar de forma voluntaria por el momento, así que podrías encontrar que mantener tu uso de bajo nivel de las API Win32 en las API de caracteres anchos es la mejor opción por portabilidad.
- Da preferencia al uso de UTF-8 en tus API y convierte a UTF-16 LE solo al llamar a las API Win32 de caracteres anchos. En lugar de usar
std::wstringywchar_t*, usastd::stringychar*como UTF-8. - Para los literales de cadena estrechos, garantiza la adherencia a UTF-8 usando el prefijo
u8de C++ en lugar de ningún prefijo oL. - Mantén las definiciones de preprocesador de compilación
UNICODEy_UNICODEque ya estén en su lugar (en Visual Studio, esto es la propiedad<CharSet>) como medida de seguridad, pero en lugar de depender de las macros, llama siempre explícitamente a la versiónW()oA(). - Evita
TCHAR,TEXT(),LPTSTRy otros tipos y macros de texto heredados. Para más información, consulta Compatibilidad con UTF-8 en el Microsoft Game Development Kit (GDK).
Convención de nomenclatura: indicaciones de rendimiento y comportamiento
Las API de la plataforma del Microsoft Game Development Kit (GDK) en XBOX se han diseñado con el propósito de que los nombres de las funciones hagan afirmaciones implícitas sobre el rendimiento de las funciones que se llaman. Se espera que una función que incluye la palabraGet o Set en su nombre tenga una sobrecarga baja y sea predecible. También se espera que tenga aproximadamente el mismo nivel de rendimiento que si se llamara en lugar de una función contenedora de propiedad de C++ con cualquier operación memcpy para copiar el resultado. Si una función usara Query en lugar de Get, esto implicaría que es una operación de larga duración que podría bloquearse hasta completarse.
Para las funciones que realizan cálculos en lugar de consultas simples, normalmente asumimos que el rendimiento es aproximadamente el que esperarías después de inspeccionar sus parámetros de entrada y los tipos de operaciones que realizan, a menos que la documentación indique lo contrario.
Una función cuyo nombre termina en Async es una operación asincrónica y podría tardar mucho tiempo o un tiempo indeterminado en completarse. En la mayoría de los casos, proporcionamos versiones con bloqueo y asincrónicas de las funciones que pueden tardar mucho en ejecutarse. Te dejamos decidir qué variante funciona mejor para tu base de código. En algunos casos (como con las API de red), podríamos omitir por completo la versión con bloqueo, porque proporcionarla no tendría sentido.
Si el nombre de una función comienza con Show y termina con Async, la función muestra elementos de interfaz de usuario y, para regresar, normalmente requiere la interacción del usuario. En algunos casos, el sistema puede cancelar las operaciones de interfaz de usuario.
Consulte también
- ¿Qué es el Microsoft Game Development Kit?
- Introducción al Microsoft Game Development Kit (GDK)
