Guia de portabilidade do Microsoft Game Development Kit para XBOX One
Este tópico fornece uma visão geral das técnicas para portar uma base de código existente para a plataforma Microsoft Game Development Kit (GDK) para XBOX. Para desenvolvedores que já trabalham com o XBOX One, a maioria dos subsistemas será familiar, embora usem um design de API diferente. Algumas áreas, como os gráficos Direct3D, permanecem praticamente inalteradas. Este tópico fornece uma visão geral de alto nível do processo geral de portabilidade, links para áreas específicas e alguns truques e dicas para evitar armadilhas comuns. Tem comentários sobre este guia? Conte para nós no fórum de desenvolvedores do Microsoft Game Development Kit (GDK). Se você estiver desenvolvendo um novo título com a plataforma Microsoft Game Development Kit (GDK) em vez de portar um título existente, consulte Desenvolvendo um novo título com o GDK.Sobre o Microsoft Game Development Kit (GDK)
Vocês, nossos parceiros de desenvolvimento de jogos, forneceram à equipe de Gaming da Microsoft comentários valiosos sobre o que fazemos bem e o que precisamos melhorar. Nosso principal objetivo para o Microsoft Game Development Kit (GDK) é atender diretamente aos seus comentários e garantir que você possa:- Continuar desenvolvendo jogos exatamente como faz hoje
- Compartilhar facilmente o máximo de código possível, em todas as iniciativas e programas de Gaming da Microsoft: nossos consoles e PCs de hoje, e nossos consoles e o XBOX Game Streaming de amanhã
- Confiar em nossas ferramentas e plataformas de desenvolvimento para fornecer um ambiente rápido, confiável e focado no desenvolvedor
- Aproveitar novos serviços e experiências multiplataforma da forma mais rápida e fácil possível
Conteúdo
- Planejando seu projeto de portabilidade
- Ambiente de desenvolvimento
- Inicialização do aplicativo
- Inicializando aplicativos
- Loop de mensagens do Windows
- Criação de dispositivos Direct3D
- Apresentação
- Gerenciamento do tempo de vida do processo (PLM)
- Gerenciamento de memória
- Modelo de programação
- Sombreadores HLSL
- Gerenciamento de usuários
- Rede e integração com XBOX services
- Próximas etapas
- Dicas e truques
- Compatibilidade binária e reutilização de componentes
- Estilo de codificação e práticas recomendadas
- Confira também
Para os fins deste guia de portabilidade, presumiremos que você esteja direcionando as plataformas Gaming.Xbox.XboxOne.x64 e/ou Gaming.Xbox.Scarlett.x64. O Microsoft Game Development Kit (GDK) também inclui a plataforma Gaming.Desktop.x64. Ela é uma variante da plataforma Win32 x64 padrão, que não é abordada neste guia de portabilidade.O principal valor da Gaming.Desktop.x64 é fornecer uma experiência semelhante à Gaming.Xbox.*.x64 em termos de configurações de build, integração com o Visual Studio, comportamento de layout solto etc. ao direcionar o PC. Como alternativa, você pode usar a plataforma x64 ‘padrão’ e implementar todas as configurações/empacotamento diretamente para PC.
Planejando seu projeto de portabilidade
Ao portar uma base de código existente para o Microsoft Game Development Kit (GDK), normalmente você começa a partir de um projeto existente do XBOX One Software Development Kit ou de um aplicativo da área de trabalho Win32 clássico. Muitos desenvolvedores com um título existente do XBOX One descobrirão que sua base de códigoDurango é um ponto de partida melhor, desde que o uso de APIs do Windows Runtime seja relativamente isolado. As bases de código da área de trabalho Win32 clássicas estão muito mais próximas do modelo de programação do Microsoft Game Development Kit (GDK), mas geralmente pressupõem interface do usuário e esquemas de controle centrados na área de trabalho que precisam ser modificados para o console. As bases de código da área de trabalho Win32 clássicas também tendem a ter muita integração centrada na área de trabalho, especialmente quando são usadas como parte do conjunto de ferramentas de edição do jogo que utiliza conjuntos de API não compatíveis com o Microsoft Game Development Kit (GDK) no XBOX. Há prós e contras em começar com cada uma. Em alguns casos, você pode achar mais fácil aproveitar os dois tipos para diferentes partes da sua base de código.
Portabilidade a partir do XBOX One Software Development Kit
Se sua base de código já oferece suporte ao XBOX One por meio do XBOX One Software Development Kit (também conhecido como plataformaDurango), você já fez a maior parte do trabalho de modernizar o uso de API do seu aplicativo. O código também deve estar bem otimizado para as restrições específicas do console e provavelmente faz uso significativo de extensões específicas do XBOX One, como descrito a seguir.
- O DirectX 12.X é obrigatório. Se você já usa o DirectX 12.X para seu título do XBOX One, nenhuma alteração deve ser necessária além da API de apresentação para o seu uso do Direct3D.
Se você estiver usando o DirectX 11.X agora, atualize primeiro para o DirectX 12.X. Isso pode ser mais fácil de fazer com seu build existente do XBOX One Software Development Kit antes de migrar para o Microsoft Game Development Kit (GDK). Para obter detalhes, consulte estes tópicos: Portabilidade do Direct3D 11 para o Direct3D 12 e a palestra do Xfest Introduction to Direct3D 12 on XBOX One (XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos), e a palestra do Xfest Porting from Direct3D 11 to Direct3D 12 (XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos).
- Em vez de usar uma cadeia de troca DXGI, sua lógica de apresentação deve usar a API PresentX.
- Algumas alterações significativas foram feitas no subsistema de memória do Game OS do GDK do Microsoft Game Development Kit (GDK). Revise a implementação do seu gerenciador de memória.
- Para entrada do controle, use a nova API GameInput em vez de
Windows.Xbox.Input. - Como as APIs do Windows Runtime não são mais usadas na maioria dos cenários, substitua seu código C++/CX ou C++/WinRT existente pelas novas APIs COM no estilo Win32 ou no estilo DirectX.
- A funcionalidade principal de áudio não foi alterada. No entanto, algumas alterações de API podem ser necessárias, conforme descrito na comparação de APIs de áudio. O XAudio2 com extensões XMA, o WASAPI e o
ISpatialAudioClientsão compatíveis. - Ao compilar no Visual Studio, adicione as configurações de plataforma
Gaming.Xbox.XboxOne.x64e/ouGaming.Xbox.Scarlett.x64no lugar das configurações de plataformaDurangoe atualize para o Visual Studio 2019 ou o Visual Studio 2022.
Para ajudar a adicionar novas configurações de plataforma, produzimos um exemplo chamado SolutionUpdater. Essa ferramenta de exemplo usa um arquivo de solução do Visual Studio existente e cria automaticamente as novas configurações de plataforma para todos os arquivos de projeto associados referenciados pela solução, acelerando muito o processo e reduzindo a possibilidade de erros manuais. Para obter mais informações, consulte o documento incluído com o exemplo.
Se sua base de código oferece suporte ao modelo de aplicativo da Plataforma Universal do Windows (UWP), você tem um caminho de portabilidade semelhante ao do XBOX One Software Development Kit.
Portabilidade a partir da área de trabalho Win32 clássica
Se sua base de código oferece suporte apenas à área de trabalho Win32 clássica, o processo de portabilidade pode ser bastante extenso, dependendo de quão recente é a base de código em relação a APIs preteridas e outros recursos. Lembre-se de que as bases de código da área de trabalho Win32 clássicas podem abranger um conjunto muito grande de APIs que remontam à era do Windows 9x/ME. Esta lista não abrange todos os possíveis problemas que você pode encontrar. Ao direcionar o XBOX, você também terá as considerações habituais de portabilidade do PC para o console: interface do usuário, modelos de entrada, exibição com resolução fixa, memória restrita e assim por diante.- O x64 nativo é obrigatório. Para obter mais informações, consulte Programação de 64 bits para desenvolvedores de jogos.
- O DirectX 12.X é obrigatório. DirectX 11, Direct3D 10, Direct3D 9 ou anteriores não podem ser usados. Além disso, OpenGL e Vulkan não são compatíveis. Para obter detalhes, consulte os guias de portabilidade para DirectX11 e DirectX12.
- Os componentes herdados do DirectX SDK D3DX9, D3DX10, D3DX11 e XACT não podem ser usados. Para obter mais informações, consulte Microsoft Docs, Where is the DirectX SDK (2021 Edition)?, Living without D3DX e The Zombie DirectX SDK.
WINAPI_FAMILY_GAMESé um subconjunto da família completa de APIs Win32. Limite-se a essas APIs.- O empacotamento AppX é obrigatório. Atualize seu processo de empacotamento e implantação.
- Para entrada do controle, use a nova API GameInput em vez de
Windows.Gaming.Inputou DirectInput. - Para áudio, use XAudio2, WASAPI, ISpatialAudioClient ou middleware de áudio compatível.
- Remova as instâncias de uso do registro.
- O tratamento das mensagens
WndProcdeve ser reduzido. Muitas das mensagens, especialmente aquelas que lidam com posicionamento, dimensionamento e integração com o shell das janelas, não se aplicam ao Microsoft Game Development Kit (GDK) no XBOX. - Se você compila com o Visual Studio, atualize seu código para funcionar com o Visual Studio 2019 ou o Visual Studio 2022. Caso contrário, garanta que seu build use as novas definições de pré-processador e vincule com bibliotecas em
GXDK\gameKit\lib\amd64, como a biblioteca abrangentexgameplatform.lib. - Para componentes COM, somente o modelo de threading de apartamento multithread (MTA) é compatível. Observe que
COINITBASE_MULTITHREADEDé típico para um aplicativo Direct3D. - Somente uma única instância de janela é compatível. Várias instâncias de janela simultâneas ou caixas de diálogo não são compatíveis.
Ambiente de desenvolvimento
O Visual Studio 2019 (atualização 16.11) ou o Visual Studio 2022 é o ambiente de desenvolvimento compatível com o Microsoft Game Development Kit (GDK). Instale o seguinte:- Carga de trabalho: Desenvolvimento de jogos com C++ para o conjunto principal de ferramentas
- Carga de trabalho: Desenvolvimento para UWP para as ferramentas de empacotamento.
- Carga de trabalho (opcional): desenvolvimento para desktop com C++ para ferramentas e exemplos do lado do PC.
O desenvolvimento com o XBOX One Software Development Kit no Visual Studio 2017 também exigia o componente opcional Windows 8.1 SDK and UCRT SDK. Esse componente não é necessário para o Microsoft Game Development Kit (GDK).Se você ainda estiver usando o Visual Studio 2015 ou anterior, a primeira etapa do seu esforço de portabilidade é atualizar para o Visual Studio 2019 ou posterior.
Plataforma do Visual Studio
O Microsoft Game Development Kit (GDK) se integra ao Visual Studio para fornecer as plataformasGaming.Xbox.XboxOne.x64 e Gaming.Xbox.Scarlett.x64 para direcionar o Game OS do Microsoft GDK no XBOX. Isso substitui a plataforma Durango do XBOX One Software Development Kit.
Soluções de build personalizadas
Para compilar código fora do Visual Studio, os auxiliares de ambiente para locais foram alterados. XBOX One Software Development Kit:No caminho de exemplo acima, build_number representa o build instalado no seu sistema (por exemplo, 190700).
%GameDKLatest%\GXDK\gameKit contém todos os cabeçalhos e bibliotecas para extensões específicas do console e a biblioteca abrangente principal da plataforma para vincular um binário do Microsoft Game Development Kit (GDK). %GameDKLatest%\GRDK\gameKit contém de forma semelhante os cabeçalhos e bibliotecas para toda a funcionalidade que não é específica do desenvolvimento para console. O Microsoft Game Development Kit (GDK) exige que o Windows 10 SDK (10.0.19041.0) ou posterior esteja instalado como dependência. Alguns cabeçalhos/bibliotecas adicionais estão disponíveis em %GameDKLatest%\GXDK\toolKit para ferramentas de console do lado do PC.
A partir da versão de outubro de 2023, o Windows 11 SDK (10.0.22000.0) é a versão mínima compatível.Também há várias opções e definições que você deve usar. Consulte Recomendações de opções do compilador e do vinculador do Visual C++ para obter todos os detalhes, bem como o exemplo CMakeExample.
Compilador (cl.exe)
/D_GAMING_XBOXsubstitui tanto/D_XBOX_ONE /D_TITLEquanto/D_DURANGO./D_GAMING_XBOX_XBOXONEé definido somente para a plataformaGaming.Xbox.XboxOne.x64./D_GAMING_XBOX_SCARLETTé definido somente para a plataformaGaming.Xbox.Scarlett.x64./DWINAPI_FAMILY=WINAPI_FAMILY_GAMEScontrola o particionamento de API no lugar da família de APIsWINAPI_FAMILY_TV_TITLE.- Você deve definir
/DWIN32_LEAN_AND_MEAN,/D_ATL_NO_DEFAULT_LIBSe/D__WRL_NO_DEFAULT_LIB__ - Para o Microsoft Game Development Kit (GDK), você não usa mais nenhuma opção do Windows Runtime, como
/AI,/FUou/ZW. - Continue a usar
/favor:AMD64,/EHsce/fp:fast. - Para a plataforma
Gaming.Xbox.XboxOne.x64, continue a usar/arch:AVX - Para a plataforma
Gaming.Xbox.Scarlett.x64, use/arch:AVX2
Com o VS 2019 Update 3 ou posterior e a plataformaGaming.Xbox.Scarlett.x64, use também/d2vzeroupper. Se você estiver usando Otimização de Programa Inteiro (WPO) / Geração de Código em Tempo de Vinculação (LTCG), a opção precisa ser/d2:-vzeroupper.
Com o VS 2022 e a plataformaGaming.Xbox.XboxOne.x64, use também/d2vzeroupper-. Se você estiver usando Otimização de Programa Inteiro (WPO) / Geração de Código em Tempo de Vinculação (LTCG), a opção precisa ser/d2:-vzeroupper-.
Vinculador (link.exe)
- Vincule com
xgameplatform.lib,xgameruntime.lib,d3d12_x.liboud3d12_xs.lib,xmem.libepixevt.lib. Não usekernel32.lib,kernelx.lib,onecore.libouWindowsApp.lib. - Para a biblioteca XGraphics, use
xg_x.libouxg_xs.lib. - Você não precisa usar
/WINMDou/WINMDFILE, que eram para APIs do Windows Runtime. - O Microsoft Game Development Kit (GDK) no XBOX não usa manifestos inseridos, portanto, use
/MANIFEST:NO. - Continue a usar
/DYNAMICBASE,/NXCOMPAT.
Considere usar/NODEFAULTLIBpara garantir que você não esteja vinculando com nenhuma biblioteca Win32 incompatível, incluindoadvapi32.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.
Otimizando o uso de cabeçalhos do Windows
O Microsoft Game Development Kit (GDK) usa o cabeçalho padrão<Windows.h>. É útil definir as várias definições de pré-processador “lean and mean”, além de WIN32_LEAN_AND_MEAN, conforme mencionado anteriormente, para manter sob controle o número total de cabeçalhos do sistema Win32 que você inclui.
Runtime do Visual C++
Com o XBOX One Software Development Kit, os cabeçalhos e bibliotecas do Visual C++ Runtime faziam parte do XBOX One Software Development Kit, com as DLLs de runtime colocadas dentro do Game OS. Isso exigia a atualização para uma versão mais recente do XBOX One Software Development Kit ou nível de QFE para corresponder à versão de atualização secundária do Visual Studio usada para compilar o código. Com o Microsoft Game Development Kit (GDK), as DLLs do Visual C++ Runtime são incluídas como parte do pacote do seu jogo e correspondem à versão do Visual Studio instalada localmente no computador de build.VCRuntime*.dllemsvcp*.dllsão as DLLs do runtime do compilador Visual C++ e da Biblioteca Padrão C++. Há também umucrtbase.dllincluído no Game OS que é usado.- Para builds de depuração, seu pacote conterá
VCRuntime*d.dll,msvcp*d.dlleucrbased.dll
Se você usar a ERA Migration Library, também precisará devccorlib*.dll, que é usado pelo compilador ao compilar com/ZW.
O AMP não é compatível com o XBOX e foi preterido na versão mais recente do Visual C++.
Inicialização do aplicativo
Os projetos do Microsoft Game Development Kit (GDK) usam uma versão simplificada da inicialização de aplicativo e do loop de mensagens no estilo da área de trabalho Win32, e não eventos CoreWindow no estilo do Windows Runtime. Sua base de código existente deve ter um dos pontos de entrada a seguir.Desenvolvimento para a área de trabalho Win32
XBOX One Software Development Kit ou aplicativo UWP usando C++/CX
XBOX One Software Development Kit ou aplicativo UWP usando C++/WinRT
Microsoft Game Development Kit (GDK) no XBOX
Para títulos do GDK, o ponto de entrada é o mesmo da área de trabalho Win32 clássica.Inicializando aplicativos
Uma função de ponto de entrada Win32 típica e muito básica tem esta aparência.- Uso mínimo de classe e estilos de janela
- Cadeias de caracteres UTF-8 em vez de UTF-16LE
- Inicialização do subsistema Game Runtime
Para títulos do Microsoft Game Development Kit (GDK) no XBOX, você pode ter apenas uma janela Win32.
Loop de mensagens do Windows
Como muitas mensagens não se aplicam, os aplicativos do Microsoft Game Development Kit (GDK) no XBOX podem usar um loop de mensagens Win32 muito básico.Criação de dispositivos Direct3D
Os jogos compilados com o Microsoft Game Development Kit (GDK) no XBOX usam a API Direct3D 12.X, que é implementada como o runtime monolítico, exatamente como é implementada com o XBOX One Software Development Kit.
O Direct3D 12 e o Direct3D 11 padrão não são compatíveis com jogos compilados com o Microsoft Game Development Kit (GDK) no XBOX. Ao criar um dispositivo Direct3D 12 para o DirectX 12.X, use o método
D3D12XboxCreateDevice.
APIs XMem*
Todas as chamadas para APIsXMem* que usam XMEM_GRAPHICS exigem que o dispositivo Direct3D tenha sido criado antes de serem usadas. Como alternativa, você pode chamar D3DConfigureVirtualMemory se precisar usar essas chamadas antes que o dispositivo Direct3D exista.
Reserva de CPU/GPU
Todos os títulos do Microsoft Game Development Kit (GDK) obtêm recursos completos (ou seja, sem reserva de GPU para o Kinect) e o sétimo núcleo de CPU. Por padrão, você obtém o equivalente às seguintes configurações de manifesto do XBOX One Software Development Kit.Diferenças do Direct3D entre XBOX One e XBOX Series X|S
A implementação do runtime monolítico do Direct3D 12.x para a plataformaGaming.Xbox.XboxOne.x64 é quase idêntica à implementação do Direct3D 12.x do XBOX One Software Development Kit. Para sua portabilidade inicial para o Microsoft Game Development Kit (GDK) no XBOX, essa plataforma provavelmente é o ponto de partida mais fácil.
Gaming.Xbox.Scarlett.x64oferece suporte até as interfaces ID3D12Device8 e ID3D12GraphicsCommandList5 ou versões posteriores.Gaming.Xbox.XboxOne.x64oferece suporte até ID3D12Device, ID3D12Device1, ID3D12Device2 e ID3D12GraphicsCommandList.
Gaming.Xbox.Scarlett.x64, há alguns recursos adicionais, bem como algumas diferenças na implementação do Direct3D 12.x.
- Você precisa usar uma versão diferente dos cabeçalhos e bibliotecas do Direct3D (ou seja,
d3d12_xs.h,d3dx12_xs.h,xg_xs.h,d3d12_xs.libetc.). Não é possível misturar as duas versões do Direct3D 12.x no mesmo binário. - Quando o runtime monolítico do Direct3D 12.x foi implementado pela primeira vez, ele foi construído sobre o runtime monolítico do Direct3D 11.x, portanto, vários tipos do Direct3D 11 são definidos ao compilar com as plataformas
DurangoouGaming.Xbox.XboxOne.x64. Eles foram removidos da implementação do XBOX Series X|S, portanto, você poderá encontrar problemas de build com quaisquer referências remanescentes ao cabeçalhod3d11_x.h, a definiçõesD3D11_*, a classesCD3D11_*ou a interfacesID3D11*. Elas podem ser removidas e o código ainda será compilado para ambas as plataformas. - A ESRAM não é um recurso do XBOX Series X|S, portanto, as extensões relacionadas à ESRAM não são definidas para essa plataforma. Isso também significa que
xgmemory.h(um auxiliar para utilizar a ESRAM) só é compatível com a plataformaGaming.Xbox.XboxOne.x64.
Continua sendo importante utilizar a ESRAM em dispositivos XBOX One / XBOX One S para obter o desempenho de renderização ideal. Consulte os exemplos SimpleESRAM e AdvancedESRAM.
- Há várias diferenças nos layouts de memória da GPU, em particular nas técnicas de H-tile e C-Mask. Para obter detalhes, consulte os exemplos CMaskDecode, HiZDecode, HiStencil e PrimeHTile.
Apresentação
O Microsoft Game Development Kit (GDK) no XBOX não oferece suporte a cadeias de troca DXGI herdadas para apresentação, mas usa a API PresentX. As novas APIs PresentX foram projetadas para resolver questões de latência com cadeias de troca DXGI e fornecem ao desenvolvedor um controle mais direto dos buffers de apresentação. Essa API também foi projetada para ser dimensionada para futuros aplicativos de streaming. A primeira etapa para usar o PresentX é registrar-se para eventos de quadro após a criação do dispositivo Direct3D.D3D12_HEAP_FLAG_ALLOW_DISPLAY.
WaitFrameEventX.
DXGI_ERROR_DEVICE_REMOVED e DXGI_ERROR_DEVICE_RESET, que precisam ser tratados em jogos para PC.
Algumas outras funcionalidades relacionadas ao DXGI foram removidas, e a função ScheduleFrameEventX mencionada anteriormente substitui DXGIXSetFrameNotification do XBOX One Software Development Kit.
Aqui está o código do XBOX One Software Development Kit para notificação de inversão de quadro.
Gerenciamento do tempo de vida do processo (PLM)
Os jogos compilados com o Microsoft Game Development Kit (GDK) no XBOX usam o mesmo modelo básico de gerenciamento do tempo de vida do processo (PLM) usado pelos aplicativos do XBOX One XDK e pelos aplicativos UWP. Os aplicativos são executados sem restrições, com restrições, suspensos ou encerrados; ou seja, nenhum código é executado no encerramento, e o processo é simplesmente destruído. Os aplicativos do XBOX One Software Development Kit e os aplicativos UWP recebem notificações por meio de sua CoreWindow do Windows Runtime. Os jogos do Microsoft Game Development Kit (GDK) no XBOX recebem notificações por meio de retornos de chamada registrados. Observe que há apenas um evento de suspensão e um de retomada, e não há mais uma fase de ativação explícita. Uma abordagem de implementação simples é lidar com isso postando uma mensagemWM_USER.
WM_USER para garantir que o loop seja pausado até a retomada e que o comportamento adequado de suspensão/retomada da GPU ocorra em um momento seguro no loop de renderização.
Com restrições versus completo
A notificação de recursos restritos versus completos é tratada por meio de uma API semelhante.Encerramento do processo
Para títulos de varejo, o encerramento do processo é tratado da mesma forma que na plataforma mais antiga do XBOX One Software Development Kit. O processo é suspenso e, em seguida, encerrado. Nenhum destruidor C++ ou limpeza é processado. Isso também era verdade se você chamasseWindows::ApplicationModel::Core::CoreApplication::Exit.
Com o Microsoft Game Development Kit (GDK), você pode obter uma saída limpa, como é possível com aplicativos da área de trabalho Win32 clássicos, por meio de PostQuitMessage. Isso faz com que o loop de mensagens seja encerrado, e a limpeza normal do código e a desmontagem do processo ocorrerão. Isso é útil durante o desenvolvimento para ajudar a detectar vazamentos e outros problemas de limpeza que, de outra forma, podem ser difíceis de encontrar. No entanto, esse comportamento provavelmente invoca caminhos de código que nunca são executados na plataforma mais antiga do XBOX One Software Development Kit.
Gerenciamento de memória
Para obter mais informações sobre o gerenciamento de memória, consulte Visão geral da memória.Alterações no modelo de memória
A plataforma Microsoft Game Development Kit (GDK) inclui muitas alterações feitas no modelo de memória em relação ao Game OS original do XBOX One. A maior parte desse esforço foi dedicada a melhorar o isolamento da memória usada pelo título em relação à memória usada pelo sistema. Melhorar o isolamento tornaria o uso de memória mais previsível entre o título e o sistema e evitaria o uso inesperado por chamadas do sistema. Como parte desse trabalho, estamos migrando para a versão mais recente do subsistema de Gerenciamento de Memória do Windows. Embora muitos jogos não exijam grandes alterações, você deve examinar cuidadosamente o uso dessas APIs de memória. Os significados e o comportamento dos sinalizadores foram alterados. Se você estiver alocando e mapeando páginas físicas manualmente, lembre-se de que algumas restrições de mapeamento foram alteradas e que um padrão diferente deve ser seguido para as APIs.- Quando páginas físicas são mapeadas no Espaço de Endereço Virtual mais de uma vez, todas as alocações devem compartilhar as mesmas configurações de coerência de cache. Por exemplo, não é possível misturar configurações de página Write Combined e de Leitura/Gravação normal da CPU na mesma memória física.
- As configurações de página e os valores de coerência de cache agora residem na região de endereço virtual na qual as páginas são mapeadas. Essa região deve ser reservada com antecedência chamando XMemVirtualAlloc e usando o padrão
MEM_RESERVE. Essa etapa não era necessária na versão anterior do sistema operacional.
MEM_LARGE_PAGES. Seus valores e significados foram alterados para corresponder aos significados usados em todo o Windows.
Com a mudança das páginas grandes de 4 MB no Game OS do XBOX One para 2 MB no sistema operacional do Microsoft Game Development Kit (GDK) no XBOX, os especificadores de tamanho do XMemAlloc também mudaram para páginas grandes, de
XALLOC_PAGESIZE_4MB para XALLOC_PAGESIZE_2MB.
Nosso mapa de memória também mudou e não é mais segmentado nas regiões Legacy, Title, Graphics e Physical. Agora elas abrangem todo o espaço de endereço de 8 TB.
Alterações nas APIs
As APIs de memória do Microsoft Game Development Kit (GDK) começam com o prefixo XMem e, em sua maioria, espelham as APIs já existentes no sistema operacional do XBOX One XDK, embora seu comportamento tenha mudado.
As novas APIs são mostradas na tabela a seguir.
Use XMemVirtualAlloc em vez de VirtualAlloc
No Microsoft Game Development Kit (GDK), a nova APIXMemVirtualAlloc substitui todos os usos de VirtualAlloc para alocar memória gráfica do XBOX. Observe os requisitos anteriores para especificar a página da GPU e os requisitos de coerência de cache para reservas que posteriormente serão apoiadas por mapeamentos físicos.
Uma comparação dessa reserva no XBOX One Software Development Kit:
Use VirtualFree
A memória alocada porVirtualAlloc ou XMemVirtualAlloc ainda é liberada com VirtualFree. Não existe uma API XMemVirtualFree.
Uso do XMemAlloc
A macro Attributes agora tem um parâmetro adicional. Por exemplo:XMemAllocatePhysicalPages e XMemMapPhysicalPages
Com a mudança dos sinalizadores de página e da coerência de cache para o momento da reserva, as chamadas para alocar e mapear memória física foram simplificadas, mas, fora isso, são semelhantes às do XBOX One Software Development Kit.XMemAllocatePhysicalPages substitui AllocateTitlePhysicalPages. XMemMapPhysicalPages substitui MapTitlePhysicalPages.
Este código do XBOX One Software Development Kit:
Modelo de programação
Para obter mais informações sobre o modelo de programação, consulte o tópico Modelo de Programação Assíncrona.Código síncrono (de bloqueio) com GameRuntime
Para APIs em que o bloqueio é uma opção razoável, foram fornecidas as versões de bloqueio (síncronas) de todas as funcionalidades da biblioteca, mesmo que as chamadas sejam de longa duração. O desenvolvedor pode gerar threads e chamar as funções de bloqueio a partir desses threads usando o agendador para gerenciar a simultaneidade, o que geralmente é mais simples de implementar do que futures e promises no estilo C++11. Há alguns casos (como chamadas de rede) em que se sabe que o tempo de execução das funções é não determinístico, portanto, apenas versões assíncronas são fornecidas.Código assíncrono com GameRuntime
A plataforma Microsoft Game Development Kit (GDK) inclui um novo modelo para executar tarefas assíncronas e relatar seus resultados por meio de retornos de chamada. Esse modelo substitui o Windows Runtime. Use as APIs do GameRuntime para especificar como e onde o trabalho assíncrono e os retornos de chamada ocorrem. O código de exemplo a seguir inclui exemplos simples e padronizados de como uma Fila de Tarefas do Game Runtime é configurada para processar suas chamadas do sistema. Essa fila pode ser usada para processar tarefas do sistema e como o local onde os retornos de chamada são executados. Conceitualmente, um retorno de chamada é uma tarefa que executa o seu código em resposta a ações do sistema. Se necessário, você pode criar várias Filas de Tarefas para gerenciar o trabalho em núcleos diferentes ou para especificar, chamada a chamada, a fila que executa os retornos de chamada. O despacho de itens de trabalho enfileirados pode ser bombeado manualmente pelo seu código (isso é semelhante a uma fila de mensagens do Windows) ou bombeado automaticamente. Veja a seguir exemplos simples de como uma fila bombeada manualmente é criada e depois bombeada.Padrão geral de nomenclatura para chamadas de API assíncronas
A tabela a seguir mostra o padrão geral usado pelo Microsoft Game Development Kit (GDK) e pelo Game Runtime para nomear chamadas assíncronas.XAsyncBlock substitui IAsyncOperation e IAsyncAction
Ao chamar uma função assíncrona, crie uma estruturaXAsyncBlock, que deve ser mantida ativa durante a chamada até que ela seja concluída, cancelada ou falhe.
O tipo XAsyncBlock contém três parâmetros de relevância imediata.
Exemplo de uso:
Observe que é fundamental “preencher com zeros” a estrutura XAsyncBlock ao criá-la, daí o uso de{}em vez de().
Operações sensíveis ao tempo
As bibliotecas do Microsoft Game Development Kit (GDK) permitem especificar se o thread a partir do qual você está chamando é sensível ao tempo. Avisos de runtime podem ser relatados se você chamar funções que não são sensíveis ao tempo a partir de um thread sensível ao tempo.SetTimeSensitiveThread(true) no thread. Você também pode chamar VerifyNotTimeSensitiveThread() de dentro de funções de longa duração no seu próprio código para relatar o uso inadequado a partir de threads críticos em termos de tempo.
Sombreadores HLSL
A plataforma XBOX One Software Development Kit usava uma versão personalizada do compilador HLSLFXC.EXE que oferecia suporte à pré-compilação de sombreadores programáveis do Shader Model 5.1 para microcódigo ATI. Além disso, havia suporte à versão prévia do compilador DXIL DXC.EXE para o Shader Model 6.
Para o Microsoft Game Development Kit (GDK) no XBOX, recomenda-se o uso do compilador DXIL e do Shader Model 6 por meio do DXC.EXE. O compilador FXC.EXE do Shader Model 5.1 agora é considerado herdado. O novo compilador oferece suporte à maioria dos sinalizadores de linha de comando compatíveis com o compilador antigo, embora algumas das defines de extensão específicas do XBOX não sejam aplicáveis ou não sejam compatíveis. Para obter detalhes sobre o Shader Model 6 e a DXIL, consulte o projeto no GitHub.
Para uso do Shader Model 6 no PC: o Windows 10 Creators Update e versões posteriores oferecem suporte a sombreadores DXIL do Shader Model 6.x, assim como muitos drivers de varejo. Em vez de depender dos drivers WHQL do Windows Update para esse recurso, você precisa instalar o driver mais recente diretamente do fornecedor. O compilador
DXC.EXE para Windows está incluído no SDK do Windows 10 April 2018 Update e versões posteriores. Em runtime, você pode determinar se seu PC oferece suporte ao Shader Model 6.x por meio de CheckFeatureSupport usando D3D12_FEATURE_SHADER_MODEL, mas não se esqueça de inicializar shaderModel.HighestShaderModel antes de chamar a função!%GameDKLatest%\GXDK\bin\XboxOne\DXC.exe.
A versão do compilador DXIL para XBOX Series X|S está localizada aqui: %GameDKLatest%\GXDK\bin\Scarlett\DXC.exe.
APIs D3DCompile
Para o Shader Model 6, você deve usar a bibliotecadxcompiler_x.lib ou dxcompiler_xs.lib em vez de d3dcompiler_x.lib.
Gerenciamento de usuários
O modelo de usuário do Microsoft Game Development Kit (GDK) mudou em relação ao que você pode estar acostumado no XBOX One Software Development Kit. Isso ocorre em parte para gerenciar melhor as expectativas de privacidade dos usuários e para aliviar o fardo de sempre acompanhar o que o sistema está fazendo em segundo plano com usuários com os quais o título não deveria se preocupar. Em vez de os títulos monitorarem uma coleção de todo o sistema com os usuários e convidados conectados ao console, o sistema expõe os usuários somente sob demanda. Para adquirir um usuário para seu título (por exemplo, quando o usuário pressiona o botão A em um controle para iniciar uma sessão de jogo e o controle ainda não foi associado a um usuário), faça uma chamada para XUserAddAsync. Essa chamada executará duas ações importantes: conecta os usuários ao título e atualiza o emparelhamento de dispositivos de entrada do usuário. Os usuários podem ter qualquer número de dispositivos de entrada emparelhados a eles ao mesmo tempo. No entanto, o título só é informado sobre associações de usuários que foram conectados com XUserAddAsync. Se o Guia do sistema for usado para conectar um usuário ou alterar associações fora do título para um usuário que o título desconhece, o título será informado apenas de que o dispositivo de entrada foi desemparelhado. No entanto, o sistema fora do título ainda conhece o emparelhamento para uso do sistema. Os títulos podem monitorar alterações no estado de um usuário ou nas informações associadas a um usuário (como Gamertag, Imagem do Jogador ou Privilégios) assinandoXUserChangeEvent (embora algumas dessas informações, como o estado de entrada do usuário, possam ser monitoradas por sondagem). Para fazer isso, chame XUserRegisterForChangeEvent.
A maioria dos títulos deve esperar precisar criar sua própria coleção de usuários, acompanhar quando os usuários entram no título, acompanhar as associações de dispositivos de entrada e lidar com a saída dos usuários.
Para uma discussão detalhada dessas alterações, consulte Usuários e dispositivos de entrada. Confira também o exemplo UserManagement.
Rede e integração com XBOX services
Transporte de rede
O Microsoft Game Development Kit (GDK) no XBOX oferece suporte tanto ao WinSock2 quanto ao BCrypt por meio do CNG. Se estiver usando UDP, em vez de codificar uma porta, como 3074, para a associação do soquete multijogador, no Microsoft Game Development Kit (GDK) você deve usar esta nova API C simples:Windows.Networking.Connectivity. Para obter o código de exemplo, consulte Inicialização e conectividade de rede.
Os Secure Sockets (namespace
Windows.Xbox.Networking) foram removidos do Microsoft Game Development Kit (GDK).Solicitações da Web via HTTP
O Microsoft Game Development Kit (GDK) não oferece mais suporte aIXMLHTTPRequest2 nem a MessageWebSocket / StreamWebSocket (namespace Windows.Networking.Sockets). Em vez disso, você deve usar o WinHTTP.
Para obter mais detalhes, consulte Solicitações da Web.
APIs do XBOX services
Os desenvolvedores que atualmente usam as versões Windows Runtime ou C++ da XSAPI precisarão migrar para a versão C simples para os recursos de integração com o XBOX services:- Conquistas
- Presença
- Perfil
- Social
- Social Manager
Próximas etapas
Depois de concluir sua portabilidade inicial a partir da ERA, você estará em ótima posição para habilitar diversos recursos do Microsoft Game Development Kit (GDK) no XBOX. Se o seu título estiver funcionando bem no hardware XBOX One S / XBOX One X, estas são maneiras fáceis de melhorar a experiência nos consoles XBOX Series X|S. Observe que muitos desses recursos são habilitados automaticamente para títulos ERA herdados, mas são opcionais para títulos do Microsoft Game Development Kit (GDK) no XBOX. Agora que seu título é nativo do Microsoft Game Development Kit (GDK) no XBOX, não deixe de habilitá-los!- AutoHDR: esse recurso converte automaticamente um título SDR em HDR no nível do sistema, aprimorando a qualidade visual do jogo quando jogado em uma tela compatível com HDR10. Ele usa hardware específico do XBOX Series X|S, portanto, não há custo extra de CPU, GPU, memória, largura de banda ou latência. O aprimoramento visual não altera a intenção artística original e expande o brilho para até 1000 nits e as cores para o espaço de cores P3-D65. Uma implementação nativa de HDR sempre será melhor, permitindo controle artístico total, mas se você não tiver os recursos ou o tempo para implementar HDR nativo, o AutoHDR é uma maneira fácil e eficaz de obter uma experiência aprimorada.
- Aniso Boost: uma melhoria na qualidade da imagem nos consoles XBOX Series X|S é obtida promovendo a filtragem de textura linear para filtragem anisotrópica completa. Essa é uma maneira rápida e fácil de aplicar poder extra da GPU a um título de jogo existente. Como título do Microsoft Game Development Kit (GDK) no XBOX, você consegue isso usando a configuração
D3D12_FILTER_ANISOTROPICpara os estados do amostrador em vez deD3D12_FILTER_MIN_MAG_MIP_LINEARao executar no XBOX Series X|S:
- FPS Boost: outra melhoria simples é aumentar a taxa de quadros de renderização nos consoles XBOX Series X|S. Se o seu título é executado a 30 fps no XBOX One S / XBOX One X (
D3D12XBOX_FRAME_INTERVAL_30_HZ), ele geralmente pode ser executado a 60 fps no XBOX Series X|S (D3D12XBOX_FRAME_INTERVAL_60_HZ). Se ele é executado a 60 fps no XBOX One S/X, provavelmente pode ser executado a 120 fps no XBOX Series X|S. Consulte Suporte a 120Hz e o exemplo Simple120Hz para obter mais informações.
Além do aumento da taxa de quadros, você provavelmente também pode renderizar em 4K no XBOX One X e no XBOX Series X com o mesmo desempenho que obtém em 1080p no XBOX One S / XBOX Series S.
- Quick Resume: esse recurso é automático na maior parte, desde que seu título implemente corretamente o Gerenciamento do Ciclo de Vida do Processo (PLM). Consulte Ciclo de vida do jogo XBOX para obter mais detalhes.
Dicas e truques
Arquivo de empacotamento Microsoft Game Config
O Microsoft Game Development Kit (GDK) não usa mais um arquivoPackage.appxmanifest durante a cadeia de ferramentas de build do Visual Studio para gerar AppxManifest.xml. Em vez disso, um arquivo MicrosoftGameConfig é usado para abrigar todas as configurações do pacote do aplicativo no momento do desenvolvimento.
Executable Name deve corresponder ao nome do EXE no layout do pacote.
Observe que você pode criar um novo projeto usando o Visual Studio. Selecione Arquivo, Novo Projeto e, em seguida, selecione o modelo Direct3D 12 XBOX Game do Microsoft Game Development Kit (GDK). Em seguida, você pode adicionar ao seu projeto o MicrosoftGame.config criado pelo modelo.
Como opção, você pode adicionar os vários ativos relacionados à interface do usuário e à Store, que precisam estar presentes no pacote, adicionando uma seção <ShellVisuals>.
Observe que o XBOX One Software Development Kit tinha um elemento WideLogo; agora ele é referenciado como o atributo Square480x480Logo.
Para a integração com o XBOX services, você também precisa fornecer um Title ID.
.config. Para obter uma definição completa das opções permitidas, consulte Arquivo MicrosoftGameConfig.
Obtendo o tipo de dispositivo
O método GetConsoleType do XBOX One Software Development Kit não está disponível no Microsoft Game Development Kit (GDK). Em vez disso, use a API do GameRuntime XSystemGetDeviceType.Substituto do GDK para xdk.h e _XDK_VER
No XBOX One Software Development Kit, o cabeçalho xdk.h fornecia vários símbolos de build relacionados ao número de build do XDK, nível de QFE etc.
Para as plataformas Gaming.*.x64, você pode usar grdk.h:
_GRDK_VERé a codificação de versão do Gaming GDK usado para compilar o binário (HIWORD.LOWORD). Por exemplo,0x4A610479é o número de build 19041.1145._GRDK_VER_STRINGpara esse build é “April 2020 GRDK”._GRDK_VER_STRING_Wcadeia de caracteres larga UTF16-LE equivalente a_GRDK_VER_STRING._GRDK_VER_STRING_COMPACT_Wpara esse build é uma cadeia de caracteres larga UTF16-LE contendo “April 2020”.
Gaming.Xbox.*.x64, você também pode usar gxdk.h:
_GXDK_VERé a codificação de versão do Gaming GDK usado para compilar o binário (HIWORD.LOWORD). Por exemplo,0x4A610479é o número de build 19041.1145._GXDK_VER_STRINGpara esse build é “April 2020 GXDK”._GXDK_VER_STRING_Wcadeia de caracteres larga UTF16-LE equivalente a_GXDK_VER_STRING._GXDK_VER_STRING_COMPACT_Wpara esse build é uma cadeia de caracteres larga UTF16-LE contendo “April 2020”.
Obtendo a ID do ponto de extremidade de renderização de áudio padrão
As APIs do Windows Runtime Windows.Media.Devices e Windows.Devices.Enumeration não são usadas no Microsoft Game Development Kit (GDK) no XBOX. Para obter o renderizador padrão, use o código a seguir.MapVirtualKey
Os métodosMapVirtualKey e MapVirtualKeyEx não são compatíveis com o Microsoft Game Development Kit (GDK) no XBOX. Normalmente, eles são usados para detectar as teclas VK_SHIFT esquerda e direita no código que trata o teclado.
MultiByteToWideChar e WideCharToMultiByte
Ao converter entre cadeias de caracteres largos (UTF-16 LE) e cadeias de caracteres estreitos, os desenvolvedores Win32 costumam usar MultiByteToWideChar e WideCharToMultiByte. Para bases de código modernas, recomendamos que você useCP_UTF8 em vez de uma página de código específica ou CP_ACP.
O código a seguir funciona no Windows 7 Service Pack 1 e posterior.
CP_ACP é tratado como um alias para CP_UTF8. No Windows 10 moderno e com o Microsoft Game Development Kit (GDK), geralmente você pode substituir todas as instâncias de CP_ACP por CP_UTF8 usando localizar e substituir. Para simplificar esse tipo de portabilidade, a validação de outros parâmetros relacionados a CP_UTF8 foi removida.
O C++11 adicionou o cabeçalho <codecvt> como uma solução mais portátil para o problema de conversão de cadeias de caracteres, mas ele já foi preterido no C++17. A recomendação é continuar usando as funções de cadeia de caracteres da plataforma.
APIs de localização e globalização
Na ERA, faltava a maior parte do suporte interno do Windows para localização além da simples seleção de página de código, da tradução de pontos de código (a conversão de multibyte para caractere largo) e do relatório de localidade do sistema/usuário. No Microsoft Game Development Kit (GDK), essa funcionalidade de localização é totalmente compatível, assim comoGetCurrencyFormatEx, GetNumberFormatEx, a enumeração de formatos de data e hora e outros recursos.
Observações sobre áudio XMA2
Se estiver faltando a definição deSHAPE_XMA_INPUT_BUFFER_ALIGNMENT, você precisará adicionar explicitamente uma referência ao cabeçalho shapexmacontext.h.
Suporte a caixas de mensagem da interface do usuário
Para ajudar a melhorar a depuração de falhas e erros de inicialização precoce em um título,XGameUiShowMessageDialogAsync foi adicionado à coleção de APIs de interface do usuário que pode ser chamada pelo título (TCUI). Essa API pode ser usada a qualquer momento depois que XGameRuntimeInitialize for chamado, mesmo antes da inicialização do D3D. A API é renderizada dentro da partição do sistema e é composta sobre a saída do jogo. Ela continua funcionando mesmo que o loop do jogo esteja interrompido ou ainda não esteja renderizando. Isso pode ser muito útil para relatar informações de erros de falha ou até mesmo para solicitar a anexação do depurador enquanto o código fica bloqueado no local do erro. Ela se destina principalmente a ser uma ferramenta de diagnóstico durante o desenvolvimento.
Este exemplo mostra uma caixa de diálogo de erro com bloqueio, solicitando que o desenvolvedor anexe o depurador para investigação.
Bibliotecas de extensão
No XBOX One Software Development Kit, com o uso de APIs do Windows Runtime, adicionar bibliotecas de extensão como a XSAPI ou o Game Chat exigia o uso da caixa de diálogo ‘Referências…’ no Visual Studio. No Microsoft Game Development Kit (GDK), esse mecanismo não é mais usado. Em vez disso, elas podem ser adicionadas por meio das propriedades do projeto do Visual Studio. Isso edita um elemento de propriedade na seção Globals dovcxproj:
Compatibilidade binária e reutilização de componentes
Um dos princípios orientadores do Microsoft Game Development Kit (GDK) é maximizar a capacidade dos desenvolvedores de reutilizar seu trabalho entre títulos do Windows para desktop e do console XBOX. Um aspecto disso que não foi discutido anteriormente é que foi feito um trabalho para melhorar a compatibilidade binária entre o Windows para desktop e o sistema operacional do Microsoft Game Development Kit (GDK) no XBOX. Ao contrário dos títulos do XBOX One Software Development Kit, o Microsoft Game Development Kit (GDK) no XBOX pode reutilizar diversos componentes originalmente compilados para o Windows para desktop x64. Isso pode ser um recurso valioso para economizar tempo em prototipagem, ferramentas ou outros cenários que não são críticos para o desempenho. Não há ferramentas no Microsoft Game Development Kit (GDK) para determinar se um componente do Windows para desktop pode ser reutilizado, mas isso é determinado pelas APIs do sistema operacional consumidas pelo componente em questão. As APIs compatíveis do sistema operacional do Microsoft Game Development Kit (GDK) no XBOX podem ser obtidas executandodumpbin.exe /exports nas bibliotecas fornecidas com o Microsoft Game Development Kit (GDK). Embora algumas APIs específicas de área residam em suas próprias bibliotecas (como D3D12XboxCreateDevice em d3d12_x.lib ou d3d12_xs.lib), a maioria das APIs Win32 herdadas está agregada em uma única biblioteca chamada xgameplatform.lib. O comando a seguir, quando executado em um Prompt de Comando do Desenvolvedor do Visual Studio, mostra o conjunto principal de APIs Win32 compatíveis (exceto aquelas que residem em outra biblioteca de importação).
dumpbin.exe /exports "c:\Program Files (x86)\Microsoft GDK\build_number\GXDK\gameKit\lib\amd64\xgameplatform.lib"
No caminho de exemplo acima, build_number representa o build instalado no seu sistema (por exemplo, 190700).
Estilo de codificação e práticas recomendadas
As diretrizes em Code Generation for XBOX One - Best Practices (XBOX Developer Downloads->XBOX One->All XBOX One XDK CHMs) se aplicam ao Microsoft Game Development Kit (GDK). A principal diferença nas configurações do compilador é que esses projetos não exigem o uso de C++/CX (/ZW) ou C++/WinRT, porque a maioria das APIs de jogos tem estilo Win32 ou COM no estilo DirectX. Aqui estão algumas recomendações gerais:
- Aproveite a conformidade de linguagem do C++14 e, opcionalmente, do C++17. Observe que o design da API do Microsoft Game Development Kit (GDK) pressupõe um compilador C++11 ou melhor.
- O processo de geração de código de ponto flutuante nativo x64 sempre usa SSE/SSE2. O XBOX One oferece suporte a
/arch:AVX, bem como a F16C. - O Tratamento de Exceções do C++ (
/EHsc) tem pouca ou nenhuma sobrecarga em código nativo x64. No entanto, o lançamento de exceções em runtime não é um cenário de desempenho, portanto, não deve ser usado para controlar o fluxo. - O uso de técnicas de codificação seguras para exceções, como as descritas em Objects Own Resources (RAII) e Resource Acquisition Is Initialization, é uma prática recomendada fortemente usando
std::unique_ptr,Microsoft::WRL::ComPtre outras classes de ponteiro inteligente. - Dê preferência ao uso de tipos portáteis padrão, como
size_t,ptrdiff_t,int8_t,uint8_t,int16_t,uint16_t,int32_t,uint32_t,int64_t,uint64_t,intptr_teuintptr_t. - Para minimizar o preenchimento interno, agrupe ponteiros em estruturas e classes.
- Em vez da conversão herdada no estilo C, dê preferência a conversões C++, como
const_cast<>,static_cast<>,reinterpret_cast<>edynamic_cast<>. - Use intrínsecos sempre que possível. O código nativo x64 não oferece suporte a assembly embutido.
Opções do compilador e do vinculador
Use as seguintes opções:/O1 /Oipara otimização geral e/O2para módulos críticos/fp:fast/arch:AVXpara a família de dispositivos XBOX One;/arch:AVX2para XBOX Series X|S./favor:AMD- Otimização de Programa Inteiro e Otimização Guiada por Perfil
- Opções do vinculador
/OPT:REF,ICF
/Ox é quase o mesmo que /O2, mas não inclui /GF (Eliminar Cadeias de Caracteres Duplicadas) nem /Gy (Habilitar Vinculação no Nível da Função). Dê preferência a /O2 em vez de /Ox. Se você usar /Ox, habilite explicitamente pelo menos /Gy, que é importante para habilitar a otimização do vinculador.
Também foram adicionadas várias novas opções de compilador ao Visual C++ desde o lançamento do XBOX One Software Development Kit, portanto, informe-se sobre elas: /Zc:inline, /Zc:throwingNew, /Zc:__cplusplus, /volatile:iso, /permissive-, /Zc:twoPhase- e /Debug:FASTLINK.
Código condicional
Para código condicional em que os caminhos divergem, tenha em mente as seguintes convenções.
Se sua base de código já oferece suporte ao XBOX One Software Development Kit, um bom ponto de partida é fazer o seguinte:
- Pesquise todas as instâncias de
_XBOX_ONEna sua base de código - Altere instâncias como
#if defined(_XBOX_ONE) && defined(_TITLE)em que o código usa extensões do DirectX 12.X, transformando esses casos em:
#if (defined(_XBOX_ONE) && defined(_TITLE)) || defined(_GAMING_XBOX)
UTF-8 em todos os lugares
Na longa história da plataforma Windows, as funções ANSI originais foram preteridas há muito tempo em favor da solução Unicode de caracteres largos, ou seja, CreateFileW em vez de CreateFileA. Isso resolveu o problema de lidar com uma infinidade de páginas de código diferentes e simplificou todas as cadeias de caracteres localizáveis parawchar_t* (UTF-16 LE, little endian). O manifesto UTF-8 Everywhere defende que a codificação multibyte UTF-8 com char* é uma solução melhor em termos de uso de memória e portabilidade.
Para a plataforma Microsoft Game Development Kit (GDK) no XBOX, a página de código padrão é definida como CP_UTF8, portanto, todas as versões ANSI das APIs da plataforma Win32 usam UTF-8. Você pode continuar a usar as APIs de caracteres largos com UTF-16 LE, mas também tem a opção de usar UTF-8.
O suporte completo a UTF-8 no Windows é uma adição muito recente, portanto, ainda não é amplamente usado. Também é algo que o usuário precisa ativar no momento, portanto, você pode descobrir que manter o uso de baixo nível das APIs Win32 nas APIs de caracteres largos é a melhor opção para portabilidade.
- Dê preferência ao uso de UTF-8 nas suas APIs e converta para UTF-16 LE somente ao chamar APIs de caracteres largos do Win32. Em vez de usar
std::wstringewchar_t*, usestd::stringechar*como UTF-8. - Para literais de cadeia de caracteres estreitos, garanta a conformidade com UTF-8 usando o prefixo C++
u8em vez de nenhum prefixo ouL. - Mantenha as
definesde pré-processador de buildUNICODEe_UNICODEexistentes (no Visual Studio, essa é a propriedade<CharSet>) como medida de segurança, mas, em vez de depender das macros, sempre chame explicitamente a versãoW()ouA(). - Evite
TCHAR,TEXT(),LPTSTRe outros tipos e macros de texto herdados. Para obter mais informações, consulte Suporte a UTF-8 no Microsoft Game Development Kit (GDK).
Convenção de nomenclatura: dicas de desempenho e comportamento
As APIs da plataforma Microsoft Game Development Kit (GDK) no XBOX foram projetadas com o objetivo de fazer com que os nomes das funções façam afirmações implícitas sobre o desempenho das funções chamadas. Espera-se que uma função que inclua a palavraGet ou Set em seu nome tenha baixa sobrecarga e seja previsível. Também se espera que ela tenha aproximadamente o mesmo nível de desempenho que uma função wrapper de propriedade C++ com qualquer operação memcpy para copiar o resultado. Se uma função usasse Query em vez de Get, isso implicaria que se trata de uma operação de longa duração que pode bloquear até ser concluída.
Para funções que realizam cálculos em vez de consultas simples, geralmente presumimos que o desempenho seja aproximadamente o que você esperaria após inspecionar seus parâmetros de entrada e os tipos de operações que realizam, a menos que a documentação indique o contrário.
Uma função cujo nome termina em Async é uma operação assíncrona e pode levar um tempo muito longo ou indeterminado para ser concluída. Na maioria dos casos, fornecemos versões de bloqueio e assíncronas de funções que podem levar muito tempo para serem executadas. Deixamos você decidir qual variedade funciona melhor para sua base de código. Em alguns casos (como nas APIs de rede), podemos omitir totalmente a versão de bloqueio, porque fornecê-la não faria sentido.
Se o nome de uma função começa com Show e termina com Async, a função exibe elementos de interface do usuário e, para retornar, normalmente exige interação do usuário. Em alguns casos, o sistema pode cancelar operações de interface do usuário.
Confira também
- O que é o Microsoft Game Development Kit?
- Introdução ao Microsoft Game Development Kit (GDK)
