> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Guia de portabilidade do Microsoft Game Development Kit para XBOX One
> Guia para portar um título de jogo ou mecanismo ERA existente do XBOX One para o Microsoft Game Development Kit (GDK), abrangendo configuração, Direct3D, PLM e armadilhas.
# 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)](https://aka.ms/gdkforum).
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
Queremos ajudar você a desenvolver seu jogo em qualquer plataforma que desejar, usando quaisquer paradigmas de programação que você já usa. Queremos ajudar você a levar seus jogos para todas as nossas plataformas de jogos que existem hoje, para todas as plataformas em que estamos trabalhando e que encantarão os jogadores de amanhã.
Para obter informações mais detalhadas sobre o Microsoft Game Development Kit (GDK), consulte O que é o Microsoft Game Development Kit? e Introdução ao Microsoft Game Development Kit (GDK).
## Conteúdo
* [Planejando seu projeto de portabilidade](#portfrom)
* [Ambiente de desenvolvimento](#devenv)
* [Inicialização do aplicativo](#appstartup)
* [Inicializando aplicativos](#appinit)
* [Loop de mensagens do Windows](#winmsgloop)
* [Criação de dispositivos Direct3D](#d3ddevicecreate)
* [Apresentação](#presentation)
* [Gerenciamento do tempo de vida do processo (PLM)](#plm)
* [Gerenciamento de memória](#memmgmt)
* [Modelo de programação](#appmodel)
* [Sombreadores HLSL](#hlsl)
* [Gerenciamento de usuários](#user)
* [Rede e integração com XBOX services](#live)
* [Próximas etapas](#nextsteps)
* [Dicas e truques](#tips)
* [Compatibilidade binária e reutilização de componentes](#bincompat)
* [Estilo de codificação e práticas recomendadas](#codingstyle)
* [Confira também](#seealso)
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ódigo `Durango` é 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 plataforma `Durango`), 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](https://learn.microsoft.com/windows/desktop/direct3d12/porting-from-direct3d-11-to-direct3d-12) e a palestra do Xfest Introduction to Direct3D 12 on XBOX One [(XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos)](https://aka.ms/gdkdl), e a palestra do Xfest Porting from Direct3D 11 to Direct3D 12 [(XBOX Developer Downloads->Conference Material->Xfest 2015 GPU Track Videos)](https://aka.ms/gdkdl).
* 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.
| Área | Microsoft Game Development Kit (GDK) |
| - | - |
| Connected Storage | Nova API C simples |
| Rede | [WinSock2](https://learn.microsoft.com/windows/desktop/WinSock/)
[WinHTTP](https://learn.microsoft.com/windows/desktop/WinHttp/about-winhttp) |
| Empacotamento e instalação por streaming | Nova API C simples |
| Interface do usuário padrão (interface do usuário que pode ser chamada pelo título (TCUI)) | Nova API C simples |
| Store | Nova API C simples |
| Gerenciamento de usuários | Nova API C simples |
| API do XBOX services (XSAPI) | Nova API C simples; consulte Introdução às APIs C do XBOX services e a referência da XSAPI. |
* 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 `ISpatialAudioClient` são compatíveis.
* Ao compilar no Visual Studio, adicione as configurações de plataforma `Gaming.Xbox.XboxOne.x64` e/ou `Gaming.Xbox.Scarlett.x64` no lugar das configurações de plataforma `Durango` e 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*](https://aka.ms/xgdsamples). 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](https://learn.microsoft.com/windows/desktop/DxTechArts/sixty-four-bit-programming-for-game-developers).
* 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](https://learn.microsoft.com/windows/desktop/direct3d11/d3d11-programming-guide-migrating) e [DirectX12](https://learn.microsoft.com/windows/desktop/direct3d12/porting-from-direct3d-11-to-direct3d-12).
* Os componentes herdados do DirectX SDK D3DX9, D3DX10, D3DX11 e XACT não podem ser usados. Para obter mais informações, consulte [Microsoft Docs](https://learn.microsoft.com/windows/desktop/directx-sdk--august-2009-), [Where is the DirectX SDK (2021 Edition)?](https://aka.ms/dxsdk), [Living without D3DX](https://aka.ms/Kfsdiu) e [The Zombie DirectX SDK](https://aka.ms/AA4gfea).
* `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.Input` ou 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 `WndProc` deve 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 abrangente `xgameplatform.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 plataformas `Gaming.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:
```text theme={null}
DurangoXDK=C:\Program Files (x86)\Microsoft Durango XDK\
XboxOneXDKLatest=C:\Program Files (x86)\Microsoft Durango XDK\170614\
XboxOneExtensionSDKLatest=C:\Program Files (x86)\Microsoft SDKs\Durango.170614\v8.0\
```
Microsoft Game Development Kit (GDK):
```text theme={null}
GameDK=C:\Program Files (x86)\Microsoft GDK\
GameDKLatest=C:\Program Files (x86)\Microsoft GDK\build_number\
```
No caminho de exemplo acima, *build\_number* representa o build instalado no seu sistema (por exemplo, 190700).
Há vários locais no Microsoft Game Development Kit (GDK) que precisarão ser referenciados por sistemas de build personalizados. `%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*](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Tools/CMakeExample).
#### Compilador (cl.exe)
* `/D_GAMING_XBOX` substitui tanto `/D_XBOX_ONE /D_TITLE` quanto `/D_DURANGO`.
* `/D_GAMING_XBOX_XBOXONE` é definido somente para a plataforma `Gaming.Xbox.XboxOne.x64`.
* `/D_GAMING_XBOX_SCARLETT` é definido somente para a plataforma `Gaming.Xbox.Scarlett.x64`.
* `/DWINAPI_FAMILY=WINAPI_FAMILY_GAMES` controla o particionamento de API no lugar da família de APIs `WINAPI_FAMILY_TV_TITLE`.
* Você deve definir `/DWIN32_LEAN_AND_MEAN`, `/D_ATL_NO_DEFAULT_LIBS` e `/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`, `/FU` ou `/ZW`.
* Continue a usar `/favor:AMD64`, `/EHsc` e `/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 plataforma `Gaming.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 plataforma `Gaming.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.lib` ou `d3d12_xs.lib`, `xmem.lib` e `pixevt.lib`. Não use `kernel32.lib`, `kernelx.lib`, `onecore.lib` ou `WindowsApp.lib`.
* Para a biblioteca XGraphics, use `xg_x.lib` ou `xg_xs.lib`.
* Você não precisa usar `/WINMD` ou `/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 `/NODEFAULTLIB` para garantir que você não esteja vinculando com nenhuma biblioteca Win32 incompatível, incluindo `advapi32.lib comctl32.lib comsupp.lib dbghelp.lib gdi32.lib gdiplus.lib guardcfw.lib kernel32.lib mmc.lib msimg32.lib msvcole.lib msvcoled.lib mswsock.lib ntstrsafe.lib ole2.lib ole2autd.lib ole2auto.lib ole2d.lib ole2ui.lib ole2uid.lib ole32.lib oleacc.lib oleaut32.lib oledlg.lib oledlgd.lib oldnames.lib runtimeobject.lib shell32.lib shlwapi.lib strsafe.lib urlmon.lib user32.lib userenv.lib wlmole.lib wlmoled.lib onecore.lib`.
### Otimizando o uso de cabeçalhos do Windows
O Microsoft Game Development Kit (GDK) usa o cabeçalho padrão ``. É ú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.
```cpp theme={null}
// Use the C++ standard templated min/max.
#define NOMINMAX
// DirectX apps don't need GDI.
#define NODRAWTEXT
#define NOGDI
#define NOBITMAP
// Include if you need this.
#define NOMCX
// Include if you need this.
#define NOSERVICE
// WinHelp is deprecated.
#define NOHELP
#include
```
### 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*.dll` e `msvcp*.dll` são as DLLs do runtime do compilador Visual C++ e da Biblioteca Padrão C++. Há também um `ucrtbase.dll` incluído no Game OS que é usado.
* Para builds de depuração, seu pacote conterá `VCRuntime*d.dll`, `msvcp*d.dll` e `ucrbased.dll`
> Se você usar a *ERA Migration Library*, também precisará de `vccorlib*.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
```cpp theme={null}
int WINAPI wWinMain(
_In_ HINSTANCE hInstance,
_In_opt_ HINSTANCE hPrevInstance,
_In_ LPWSTR lpCmdLine,
_In_ int nCmdShow)
{
...
```
### XBOX One Software Development Kit ou aplicativo UWP usando C++/CX
```cpp theme={null}
int __cdecl main(Platform::Array^ /*argv*/)
{
auto viewProviderFactory = ref new ViewProviderFactory();
CoreApplication::Run(viewProviderFactory);
return 0;
}
```
### XBOX One Software Development Kit ou aplicativo UWP usando C++/WinRT
```cpp theme={null}
int WINAPIV WinMain()
{
winrt::init_apartment();
ViewProviderFactory viewProviderFactory;
CoreApplication::Run(viewProviderFactory);
winrt::uninit_apartment();
return 0;
}
```
### 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.
```cpp theme={null}
int WINAPI wWinMain(
_In_ HINSTANCE hInstance,
_In_opt_ HINSTANCE hPrevInstance,
_In_ LPWSTR lpCmdLine,
_In_ int nCmdShow)
{
...
}
```
## Inicializando aplicativos
Uma função de ponto de entrada Win32 típica e muito básica tem esta aparência.
```cpp theme={null}
int WINAPI wWinMain(
_In_ HINSTANCE hInstance,
_In_opt_ HINSTANCE hPrevInstance,
_In_ LPWSTR lpCmdLine,
_In_ int nCmdShow)
{
HRESULT hr = CoInitializeEx(nullptr, COINITBASE_MULTITHREADED);
if (FAILED(hr))
return 1;
// Register a class and create a window.
{
// Register class
WNDCLASSEXW wcex = {};
wcex.cbSize = sizeof(WNDCLASSEXW);
wcex.style = CS_HREDRAW | CS_VREDRAW;
wcex.lpfnWndProc = WndProc;
wcex.hInstance = hInstance;
wcex.hIcon = LoadIconW(hInstance, L"IDI_ICON");
wcex.hCursor = LoadCursorW(nullptr, IDC_ARROW);
wcex.hbrBackground = reinterpret_cast(COLOR_WINDOW + 1);
wcex.lpszClassName = L"MyGameWindowClass";
wcex.hIconSm = LoadIconW(wcex.hInstance, L"IDI_ICON");
if (!RegisterClassExW(&wcex))
return 1;
// Create a window.
RECT rc = { 0, 0, static_cast(1280), static_cast(720) };
AdjustWindowRect(&rc, WS_OVERLAPPEDWINDOW, FALSE);
HWND hwnd = CreateWindowExW(0, L"MyGameWindowClass", L"My Game",
WS_OVERLAPPEDWINDOW,
CW_USEDEFAULT, CW_USEDEFAULT,
rc.right - rc.left, rc.bottom - rc.top, nullptr, nullptr, hInstance,
nullptr);
if (!hwnd)
return 1;
ShowWindow(hwnd, nCmdShow);
SetWindowLongPtr(hwnd, GWLP_USERDATA, /* some object */ );
GetClientRect(hwnd, &rc);
// Initialize a device and more by using rc as the "real" size of the swap chain.
}
// Main message loop.
MSG msg = {};
while (WM_QUIT != msg.message)
{
if (PeekMessage(&msg, nullptr, 0, 0, PM_REMOVE))
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
else
{
// Update and Render
}
}
CoUninitialize();
return static_cast(msg.wParam);
}
```
Esse padrão é basicamente o mesmo para títulos do Microsoft Game Development Kit (GDK) no XBOX, mas podemos simplificá-lo um pouco:
* 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
```cpp theme={null}
int WINAPI wWinMain(
_In_ HINSTANCE hInstance,
_In_opt_ HINSTANCE hPrevInstance,
_In_ LPWSTR lpCmdLine,
_In_ int nCmdShow)
{
// Initialize the Game Runtime APIs.
if (FAILED(InitializeGameRuntime())) // Function in GameRuntimeInit.h
return 1;
// Register a class and create a window.
{
// Register class
WNDCLASSEXA wcex = {};
wcex.cbSize = sizeof(WNDCLASSEXA);
wcex.style = CS_HREDRAW | CS_VREDRAW;
wcex.lpfnWndProc = WndProc;
wcex.hInstance = hInstance;
wcex.lpszClassName = "MyGameWindowClass";
wcex.hbrBackground = reinterpret_cast(COLOR_WINDOW + 1);
if (!RegisterClassExA(&wcex))
return 1;
// Create a window.
HWND hwnd = CreateWindowExA(0, u8"MyGameWindowClass", u8"My Game",
WS_OVERLAPPEDWINDOW,
CW_USEDEFAULT, CW_USEDEFAULT,
1920, 1080, nullptr, nullptr, hInstance,
nullptr);
if (!hwnd)
return 1;
ShowWindow(hwnd, nCmdShow);
SetWindowLongPtr(hwnd, GWLP_USERDATA, /* some object of type SomeClass */ );
// Initialize a device and more.
// Assume a swap chain of 1080p, 1440p, or 4K.
}
// Main message loop.
MSG msg = {};
while (WM_QUIT != msg.message)
{
if (PeekMessage(&msg, nullptr, 0, 0, PM_REMOVE))
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
else
{
// Update and Render
}
}
UninitializeGameRuntime();
return static_cast(msg.wParam);
}
```
> 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.
```cpp theme={null}
LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
auto appPtr = reinterpret_cast(GetWindowLongPtr(hWnd, GWLP_USERDATA));
switch (message)
{
case WM_CREATE:
break;
case WM_ACTIVATEAPP:
break;
// WM_USER messages the application posts to itself.
return DefWindowProc(hWnd, message, wParam, lParam);
}
```
O uso de um loop de mensagens Win32 é opcional, mas é um ponto de partida útil se você estiver migrando de uma base de código Win32 existente.
A tabela a seguir mostra uma lista de mensagens Win32 comuns encontradas em jogos da área de trabalho Win32 clássicos e a aplicação (ou a falta dela) dessas mensagens a títulos do Microsoft Game Development Kit (GDK) no XBOX.
| Mensagem | Descrição |
| - | - |
| WM\_CREATE | Essa mensagem é enviada quando a janela é criada. |
| WM\_DESTROY
WM\_CLOSE | Essas mensagens não se aplicam a títulos do Microsoft Game Development Kit (GDK) no XBOX, que usam um modelo de suspensão/encerramento de gerenciamento do tempo de vida do processo (PLM). |
| WM\_CHAR
WM\_KEYDOWN
WM\_KEYUP | Essas mensagens são enviadas para entrada de teclado e teclas virtuais do GamePad. |
| WM\_SYSKEYDOWN
WM\_SYSKEYUP
WM\_CHAR | Essas mensagens são enviadas para entrada de teclado. |
| WM\_USER | Os aplicativos podem enviar suas próprias mensagens para o loop de mensagens. Os aplicativos podem aproveitar isso porque elas são processadas no contexto do thread do loop principal. |
| WM\_SIZE | Essa mensagem está relacionada às configurações de minimizado, maximizado e restaurado. No entanto, títulos do Microsoft Game Development Kit (GDK) no XBOX não encontram esses cenários. |
| WM\_ENTERSIZEMOVE
WM\_EXITSIZEMOVE
WM\_GETMINMAXINFO | Essas mensagens estão relacionadas ao redimensionamento "rubber-band" na área de trabalho. No entanto, um título do Microsoft Game Development Kit (GDK) no XBOX não encontra esse cenário. |
| WM\_PAINT | Para aplicativos da área de trabalho Win32, essa mensagem normalmente é implementada para redesenhar a janela em cenários de pausa ou de redimensionamento "rubber-band", que não se aplicam. |
| WM\_POWERBROADCAST | Os títulos do Microsoft Game Development Kit (GDK) no XBOX usam as notificações de PLM para suspensão/retomada, e não o modelo de modos de energia de suspensão da área de trabalho. |
| WM\_SETFOCUS
WM\_KILLFOCUS
WM\_ACTIVATE
WM\_ACTIVATEAPP
WM\_SHOWWINDOW | Para títulos do Microsoft Game Development Kit (GDK) no XBOX, essas mensagens são enviadas quando o usuário está interagindo com o guia ou retornando de outra interface do usuário que pode ser chamada pelo título (TCUI). |
| WM\_TIMER | Essa mensagem é compatível com títulos do Microsoft Game Development Kit (GDK) no XBOX se você usar `SetTimer` / `KillTimer`. |
## 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.
| Direct3D 12 padrão | Extensões do DirectX 12.X |
| - | - |
| `#include `
`#include ` | `#include ` ou `#include ` |
| `#include ` | `#include ` ou `#include ` |
| D3D12CreateDevice | D3D12XboxCreateDevice |
| Macro IDD\_PPV\_ARGS | Macro IDD\_GRAPHICS\_PPV\_ARGS |
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`.
```cpp theme={null}
ComPtr device;
...
D3D12XBOX_CREATE_DEVICE_PARAMETERS params = {};
params.Version = D3D12_SDK_VERSION;
#if defined(_DEBUG)
// Enable the debug layer.
params.ProcessDebugFlags = D3D12_PROCESS_DEBUG_FLAG_DEBUG_LAYER_ENABLED;
#elif defined(PROFILE)
// Enable the instrumented driver.
params.ProcessDebugFlags = D3D12XBOX_PROCESS_DEBUG_FLAG_INSTRUMENTED;
#endif
params.GraphicsCommandQueueRingSizeBytes = static_cast(D3D12XBOX_DEFAULT_SIZE_BYTES);
params.GraphicsScratchMemorySizeBytes = static_cast(D3D12XBOX_DEFAULT_SIZE_BYTES);
params.ComputeScratchMemorySizeBytes = static_cast(D3D12XBOX_DEFAULT_SIZE_BYTES);
ThrowIfFailed(D3D12XboxCreateDevice(
nullptr,
¶ms,
IID_GRAPHICS_PPV_ARGS(device.GetAddressOf())
));
```
A partir daqui, a fila de comandos, a lista de comandos e outros itens continuarão a ser criados como seriam com o Direct3D 12 padrão.
Para oferecer suporte à renderização em 4K, basta usar uma largura e altura maiores para a cadeia de troca, mas você deve continuar a oferecer suporte a 1080p para consoles de menor desempenho. Uma maneira recomendada de determinar quando usar 4K, 1440p ou 1080p é a seguinte:
```cpp theme={null}
RECT outputSize = { 0, 0, 1920, 1080 };
switch (XSystemGetDeviceType())
{
case XSystemDeviceType::XboxOne:
case XSystemDeviceType::XboxOneS:
break;
case XSystemDeviceType::XboxScarlettLockhart /* Xbox Series S */:
outputSize = { 0, 0, 2560, 1440 };
break;
case XSystemDeviceType::XboxScarlettAnaconda /* Xbox Series X */:
case XSystemDeviceType::XboxOneXDevkit:
case XSystemDeviceType::XboxScarlettDevkit:
default:
outputSize = { 0, 0, 3840, 2160 };
break;
}
```
Para obter mais detalhes, consulte o exemplo [*SimpleDeviceAndSwapChain*](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/IntroGraphics/SimpleDeviceAndSwapChain).
### APIs XMem\*
Todas as chamadas para APIs `XMem*` 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.
```cpp theme={null}
D3D11X_VIRTUAL_MEMORY_CONFIGURATION vmConfig = {};
vmConfig.PageTableMemory4MBPageCount = 5;
ThrowIfFailed(
D3DConfigureVirtualMemory(&VMConfig)
);
```
### 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.
```xml theme={null}
variable
```
### 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 plataforma `Gaming.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.x64` oferece suporte até as interfaces ID3D12Device8 e ID3D12GraphicsCommandList5 ou versões posteriores.
* `Gaming.Xbox.XboxOne.x64` oferece suporte até ID3D12Device, ID3D12Device1, ID3D12Device2 e ID3D12GraphicsCommandList.
Ao migrar para a plataforma `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.lib` etc.). 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 `Durango` ou `Gaming.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çalho `d3d11_x.h`, a definições `D3D11_*`, a classes `CD3D11_*` ou a interfaces `ID3D11*`. 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 plataforma `Gaming.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*](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Graphics/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.
```cpp theme={null}
// First, retrieve the underlying DXGI device from the D3D device.
ComPtr dxgiDevice;
ThrowIfFailed(device.As(&dxgiDevice));
// Identify the physical adapter (GPU or card) that this device is running on.
ComPtr dxgiAdapter;
ThrowIfFailed(dxgiDevice->GetAdapter(dxgiAdapter.GetAddressOf()));
// Retrieve the outputs for the adapter.
ComPtr dxgiOutput;
ThrowIfFailed(dxgiAdapter->EnumOutputs(0, dxgiOutput.GetAddressOf()));
// Set the frame interval, and register for frame events.
ThrowIfFailed(device->SetFrameIntervalX(
dxgiOutput.Get(),
D3D12XBOX_FRAME_INTERVAL_60_HZ,
2 /* Allow 2 frames of latency */,
D3D12XBOX_FRAME_INTERVAL_FLAG_NONE));
ThrowIfFailed(device->ScheduleFrameEventX(
D3D12XBOX_FRAME_EVENT_ORIGIN,
0U,
nullptr,
D3D12XBOX_SCHEDULE_FRAME_EVENT_FLAG_NONE));
```
Em vez de criar uma cadeia de troca DXGI e solicitar os recursos de buffer de fundo, crie-os diretamente com o sinalizador `D3D12_HEAP_FLAG_ALLOW_DISPLAY`.
```cpp theme={null}
ComPtr renderTargets[MAX_BACK_BUFFER_COUNT];
...
CD3DX12_HEAP_PROPERTIES swapChainHeapProperties(D3D12_HEAP_TYPE_DEFAULT);
D3D12_RESOURCE_DESC swapChainBufferDesc = CD3DX12_RESOURCE_DESC::Tex2D(
backBufferFormat,
backBufferWidth,
backBufferHeight,
1, // This resource has only one texture.
1 // Use a single mipmap level.
);
swapChainBufferDesc.Flags |= D3D12_RESOURCE_FLAG_ALLOW_RENDER_TARGET;
D3D12_CLEAR_VALUE swapChainOptimizedClearValue = {};
swapChainOptimizedClearValue.Format = backBufferFormat;
for (UINT n = 0; n < m_backBufferCount; n++)
{
ThrowIfFailed(m_d3dDevice->CreateCommittedResource(
&swapChainHeapProperties,
D3D12_HEAP_FLAG_ALLOW_DISPLAY,
&swapChainBufferDesc,
D3D12_RESOURCE_STATE_PRESENT,
&swapChainOptimizedClearValue,
IID_GRAPHICS_PPV_ARGS(renderTargets[n].GetAddressOf())));
D3D12_RENDER_TARGET_VIEW_DESC rtvDesc = {};
rtvDesc.Format = m_backBufferFormat;
rtvDesc.ViewDimension = D3D12_RTV_DIMENSION_TEXTURE2D;
CD3DX12_CPU_DESCRIPTOR_HANDLE rtvDescriptor(rtvDescriptorHeap->GetCPUDescriptorHandleForHeapStart(), n,
rtvDescriptorSize);
device->CreateRenderTargetView(renderTargets[n].Get(), &rtvDesc, rtvDescriptor);
}
```
No início de cada quadro de renderização, defina primeiro um token de pipeline usando `WaitFrameEventX`.
```cpp theme={null}
D3D12XBOX_FRAME_PIPELINE_TOKEN framePipelineToken = {};
...
framePipelineToken = D3D12XBOX_FRAME_PIPELINE_TOKEN_NULL;
ThrowIfFailed(device->WaitFrameEventX(D3D12XBOX_FRAME_EVENT_ORIGIN, INFINITE, nullptr,
D3D12XBOX_WAIT_FRAME_EVENT_FLAG_NONE, &framePipelineToken));
```
No final do quadro, use o mesmo token para chamar PresentX.
```cpp theme={null}
D3D12XBOX_PRESENT_PLANE_PARAMETERS planeParameters = {};
planeParameters.Token = framePipelineToken;
planeParameters.ResourceCount = 1;
planeParameters.ppResources = renderTargets[backBufferIndex].GetAddressOf();
ThrowIfFailed(commandQueue->PresentX(1, &planeParameters, nullptr));
```
Assim como os títulos do XBOX One Software Development Kit, os jogos do Microsoft Game Development Kit (GDK) no XBOX não encontram os erros `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.
```cpp theme={null}
FlipEvent = CreateEvent(nullptr, false, false, "DXGIXFrameFlipEvent");
VERIFYD3D12RESULT(DXGIXSetFrameNotification(FRAME_NOTIFICATION_FLIPPED, FlipEvent));
```
Código equivalente para títulos do Microsoft Game Development Kit (GDK) no XBOX.
```cpp theme={null}
FlipEvent = CreateEventA(nullptr, false, false, u8"ScheduleFrameEventX");
D3D12XBOX_SCHEDULE_FRAME_OBJECT_LIST objList = { 1, &FlipEvent };
VERIFYD3D12RESULT(GetD3D12Device()->ScheduleFrameEventX(D3D12XBOX_FRAME_EVENT_DISPLAY_FLIP, 0, &objList, D3D12XBOX_SCHEDULE_FRAME_EVENT_FLAG_NONE));
```
Para obter mais detalhes, consulte Agendamento e apresentação de quadros no XBOX One e os exemplos [*SimpleDeviceAndSwapChain*](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/IntroGraphics/SimpleDeviceAndSwapChain), [*HDR10*](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Graphics/HDR10) e [*SimpleHDR*](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Graphics/SimpleHDR).
## 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 mensagem `WM_USER`.
```cpp theme={null}
#include
...
PAPPSTATE_REGISTRATION hPLM = {};
HANDLE plmSuspendComplete = nullptr;
HANDLE plmSignalResume = nullptr;
...
// Create a window.
plmSuspendComplete = CreateEventEx(nullptr, nullptr, 0, EVENT_MODIFY_STATE | SYNCHRONIZE);
plmSignalResume = CreateEventEx(nullptr, nullptr, 0, EVENT_MODIFY_STATE | SYNCHRONIZE);
if (!plmSuspendComplete || !plmSignalResume)
return 1;
if (RegisterAppStateChangeNotification([](BOOLEAN quiesced, PVOID context)
{
if (quiesced)
{
ResetEvent(plmSuspendComplete);
ResetEvent(plmSignalResume);
// To ensure we use the main UI thread to process the notification, we self-post a message.
PostMessage(reinterpret_cast(context), WM_USER, 0, 0);
// To defer suspension, we must wait to exit this callback.
(void)WaitForSingleObject(plmSuspendComplete, INFINITE);
}
else
{
SetEvent(plmSignalResume);
}
}, hwnd, &hPLM))
return 1;
// Message loop.
UnregisterAppStateChangeNotification(hPLM);
CloseHandle(plmSuspendComplete);
CloseHandle(plmSignalResume);
```
Em seguida, o loop de mensagens trataria a mensagem `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.
```cpp theme={null}
LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
...
switch (message)
{
case WM_USER:
// Call SuspendX(0) on your command queue, and cease all GPU submissions.
// Complete deferral.
SetEvent(plmSuspendComplete);
(void)WaitForSingleObject(plmSignalResume, INFINITE);
// Before picking up rendering again, call ResumeX on your command queue.
// You'll also need to register again for frame events
// via SetFrameIntervalX and ScheduleFrameEventX.
break;
}
...
}
```
Para obter mais detalhes, consulte o exemplo [*SimplePLM*](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/System/SimplePLM).
### Com restrições versus completo
A notificação de recursos restritos versus completos é tratada por meio de uma API semelhante.
```cpp theme={null}
#include
PAPPCONSTRAIN_REGISTRATION hPLM2 = {};
// Create a window.
if (RegisterAppConstrainedChangeNotification([](BOOLEAN constrained, PVOID context)
{
SendMessage(reinterpret_cast(context), WM_USER+1, (constrained) ? 1 : 0, 0);
}, hwnd, &hPLM2))
return 1;
// Message loop
UnregisterAppConstrainedChangeNotification(hPLM2);
```
Aqui usamos uma mensagem pelos mesmos motivos que usamos anteriormente no caso de suspensão/retomada.
```cpp theme={null}
LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
switch (message)
{
case WM_USER+1:
if (wParam)
{
// Constrained resources mode
}
else
{
// Full resource mode
}
break;
}
}
```
Para obter mais detalhes, consulte o exemplo [*SimplePLM*](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/System/SimplePLM).
### 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ê chamasse `Windows::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.
Para todas as alocações mapeadas para acesso pela GPU, sinalizadores explícitos de acesso da GPU agora são obrigatórios. Não há mais um padrão baseado nas configurações de proteção da CPU.
Tome cuidado para identificar, em qualquer lugar da sua base de código, onde você usou a constante `MEM_LARGE_PAGES`. Seus valores e significados foram alterados para corresponder aos significados usados em todo o Windows.
| Nome | Significado na API do XBOX One Software Development Kit | Significado no Microsoft Game Development Kit (GDK) no XBOX | Significado no Windows para desktop |
| :- | -: | -: | -: |
| MEM\_LARGE\_PAGES | Página de 64 KB | Página de 2 MB (ambíguo, pode ser removido) | Página de 2 MB |
| MEM\_4MB\_PAGES | Página de 4 MB | Não definido | Não definido |
| MEM\_64K\_PAGES | Não definido | Página de 64 KB | Não definido |
| MEM\_2MB\_PAGES | Não definido | Página de 2 MB | Não definido |
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.
| API do XBOX One Software Development Kit | Microsoft Game Development Kit (GDK) no XBOX |
| :- | :- |
| VirtualAlloc | XMemVirtualAlloc |
| VirtualFree | [VirtualFree](https://learn.microsoft.com/windows/desktop/api/memoryapi/nf-memoryapi-virtualfree) |
| AllocateTitlePhysicalPages | XMemAllocatePhysicalPages |
| MapTitlePhysicalPages | XMemMapPhysicalPages |
| FreeTitlePhysicalPages | XMemFreePhysicalPages |
| TitleMemoryStatus | XMemGetWorkingSetStatistics |
As novas APIs são mostradas na tabela a seguir.
| Nome | Descrição |
| :- | :- |
| XMemVirtualQuery | Consulta o Espaço de Endereço Virtual e retorna informações sobre como suas páginas estão mapeadas. É semelhante ao VirtualQuery no Win32, mas é usado principalmente para depuração e diagnóstico. |
### Use XMemVirtualAlloc em vez de VirtualAlloc
No Microsoft Game Development Kit (GDK), a nova API `XMemVirtualAlloc` 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:
```cpp theme={null}
void * memPool = VirtualAlloc(nullptr,
size,
MEM_LARGE_PAGES | MEM_GRAPHICS | MEM_RESERVE,
PAGE_READONLY);
```
e no Microsoft Game Development Kit (GDK):
```cpp theme={null}
void * memPool = XMemVirtualAlloc(nullptr,
size,
MEM_64K_PAGES | MEM_RESERVE,
XMEM_GRAPHICS | XMEM_MAPPABLE,
PAGE_READONLY | PAGE_GRAPHICS_COHERENT | PAGE_GRAPHICS_READWRITE);
```
Ou, para uma alocação não apoiada por páginas físicas mapeadas e confirmada no momento da reserva:
```cpp theme={null}
void* memory = VirtualAlloc(nullptr,
size,
MEM_RESERVE | MEM_COMMIT | MEM_LARGE_PAGES | MEM_GRAPHICS,
PAGE_READWRITE | PAGE_WRITECOMBINE);
```
Muda para:
```cpp theme={null}
void* memory = XMemVirtualAlloc(nullptr,
size,
MEM_RESERVE | MEM_COMMIT | MEM_64K_PAGES,
TITLE_MEM_GRAPHICS,
PAGE_READWRITE | PAGE_WRITECOMBINE | PAGE_GRAPHICS_READWRITE);
```
### Use VirtualFree
A memória alocada por `VirtualAlloc` 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:
```cpp theme={null}
const uint64_t c_XMemAllocAttributes = MAKE_XALLOC_ATTRIBUTES(
eXALLOCAllocatorId_MiddlewareReservedMin,
0,
XALLOC_MEMTYPE_GRAPHICS_WRITECOMBINE_GPU_READONLY,
XALLOC_PAGESIZE_64KB,
XALLOC_ALIGNMENT_64K);
```
Muda para:
```cpp theme={null}
const uint64_t c_XMemAllocAttributes = MAKE_XALLOC_ATTRIBUTES(
eXALLOCAllocatorId_MiddlewareReservedMin,
0,
XALLOC_MEMTYPE_GRAPHICS_WRITECOMBINE_GPU_READONLY,
XALLOC_PAGESIZE_64KB,
XALLOC_ALIGNMENT_64K,
0);
```
### 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:
```cpp theme={null}
void * memPool = VirtualAlloc(nullptr, size, MEM_LARGE_PAGES | MEM_GRAPHICS | MEM_RESERVE, PAGE_READONLY);
AllocateTitlePhysicalPages(GetCurrentProcess(), MEM_LARGE_PAGES, &NumPages64, PageArray);
MapTitlePhysicalPages(memPool, NumPages64, MEM_GRAPHICS | MEM_LARGE_PAGES, PAGE_READONLY, PageArray);
```
Muda para o seguinte para títulos do Microsoft Game Development Kit (GDK):
```cpp theme={null}
void * memPool = XMemVirtualAlloc(nullptr, size, MEM_64K_PAGES | MEM_RESERVE, XMEM_GRAPHICS | XMEM_MAPPABLE, PAGE_READONLY | PAGE_GRAPHICS_COHERENT | PAGE_GRAPHICS_READWRITE);
XMemAllocatePhysicalPages(MEM_64K_PAGES, &NumPages64, PageArray);
XMemMapPhysicalPages(memPool, NumPages64, PageArray);
```
## 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.
```cpp theme={null}
XTaskQueueHandle queue;
// This one allows async work to use the default thread pool, but completion is explicit.
ThrowIfFailed(
XTaskQueueCreate(XTaskQueueDispatchMode::ThreadPool, XTaskQueueDispatchMode::Manual, &queue)
);
...
// This pumps the completion work, which takes place on the calling thread.
while (XTaskQueueDispatch(m_queue, XTaskQueuePort::Completion, 0))
{
// ... do other work ...
}
```
Para obter mais informações, consulte o exemplo [*SimplePLM*](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/System/SimplePLM), que aciona as configurações, bem como a interface do usuário que pode ser chamada pelo título (TCUI) para entrada usando uma fila assíncrona XTask.
Para obter detalhes sobre o Modelo de Programação Assíncrona, consulte os tópicos Modelo de Programação Assíncrona e Design da fila de tarefas assíncronas. Confira também o exemplo [*AsynchronousProgramming*](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/System/AsynchronousProgramming).
### 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.
| Esquema de função | Significado |
| :- | :- |
| QueryUpdateStatus | Chamada síncrona de longa duração |
| QueryUpdateStatusAsync | Chamada assíncrona, provavelmente não determinística, de longa duração |
| QueryUpdateStatusAsyncResultSize | Chamada antes que os resultados sejam obtidos da operação, se o tamanho variar |
| QueryUpdateStatusAsyncResult | Obtém o resultado da operação assíncrona |
### XAsyncBlock substitui IAsyncOperation e IAsyncAction
Ao chamar uma função assíncrona, crie uma estrutura `XAsyncBlock`, 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.
| Tipo | Campo | Uso |
| -: | :- | :- |
| XTaskQueueHandle | queue | A fila que você designou como aquela na qual o trabalho assíncrono será executado.
Um valor nulo implica a execução no pool de threads do sistema. |
| void\* | context | Um campo que você pode usar para identificar qual chamada você fez que causou a execução da operação assíncrona.
Normalmente, é um ponteiro *this* de um objeto ou um identificador exclusivo. |
| XAsyncCompletionRoutine\* | callback | O ponteiro de função da rotina a ser chamada quando o retorno de chamada for executado. |
Exemplo de uso:
```cpp theme={null}
auto b = new XAsyncBlock{};
b->context = this;
b->queue = queue;
b->callback = [](XAsyncBlock* async)
{
UpdateStatus status;
if(SUCCEEDED(QueryUpdateStatusAsyncResult(async, &status)))
{
printf("Update Status: %d\r\n", status);
}
delete async;
};
QueryUpdateStatusAsync("Foo", b);
```
> 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.
```cpp theme={null}
HRESULT SetTimeSensitiveThread(bool isTimeSensitive);
HRESULT VerifyNotTimeSensitiveThread();
```
Para marcar um thread como sensível ao tempo, chame `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 HLSL `FXC.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](https://github.com/Microsoft/DirectXShaderCompiler).
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!
A versão do compilador DXIL para XBOX One está localizada aqui: `%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 biblioteca `dxcompiler_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) assinando `XUserChangeEvent` (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:
```cpp theme={null}
uint16_t port;
hr = XNetworkingQueryPreferredLocalUdpMultiplayerPort(&port);
if (FAILED(hr))
// NAT traversal failure
```
Para detectar a conectividade de rede com o Microsoft Game Development Kit (GDK), use o [IPHelper](https://learn.microsoft.com/windows/desktop/IpHlp/ip-helper-start-page) em vez do namespace `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).
Para obter mais detalhes, consulte Introdução à rede WinSock.
### Solicitações da Web via HTTP
O Microsoft Game Development Kit (GDK) não oferece mais suporte a `IXMLHTTPRequest2` nem a `MessageWebSocket` / `StreamWebSocket` (namespace `Windows.Networking.Sockets`). Em vez disso, você deve usar o [WinHTTP](https://learn.microsoft.com/windows/desktop/WinHttp/about-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
Consulte Introdução às APIs C do XBOX services e a referência da XSAPI.
Se você estiver usando o Game Chat 2, saiba que algumas classes foram renomeadas, conforme mostrado na tabela a seguir.
| Nome no XBOX One Software Development Kit | Nome no Microsoft Game Development Kit (GDK) no XBOX |
| :- | :- |
| game\_chat\_audio\_encoding\_type\_and\_bitrate | game\_chat\_audio\_encoding\_bitrate |
| set\_audio\_encoding\_type\_and\_bitrate | set\_audio\_encoding\_bitrate |
| audio\_encoding\_type\_and\_bitrate | audio\_encoding\_bitrate |
## 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.
```cpp theme={null}
// Try to switch the display into HDR mode
auto result = XDisplayTryEnableHdrMode(XDisplayHdrModePreference::PreferHdr, nullptr);
if (result == XDisplayHdrModeResult::Enabled)
{
// Specify the Auto HDR flag during D3D device creation
params.CreateDeviceFlags = D3D12XBOX_CREATE_DEVICE_FLAG_ENABLE_AUTO_HDR;
}
// Create the D3D device
HRESULT hr = D3D12XboxCreateDevice(...);
```
Consulte Saída de alto alcance dinâmico (HDR) e o exemplo *AutoHDR* para obter mais detalhes.
* **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_ANISOTROPIC` para os estados do amostrador em vez de `D3D12_FILTER_MIN_MAG_MIP_LINEAR` ao executar no XBOX Series X|S:
```cpp theme={null}
D3D12_SAMPLER_DESC desc = { D3D12_FILTER_ANISOTROPIC,
D3D12_TEXTURE_ADDRESS_MODE_WRAP,
D3D12_TEXTURE_ADDRESS_MODE_WRAP,
D3D12_TEXTURE_ADDRESS_MODE_WRAP,
0, D3D12_MAX_MAXANISOTROPY, D3D12_COMPARISON_FUNC_NEVER,
{ 0, 0, 0, 0 }, 0, D3D12_FLOAT32_MAX };
D3D12_SAMPLER_DESC desc = { D3D12_FILTER_ANISOTROPIC,
D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
D3D12_TEXTURE_ADDRESS_MODE_CLAMP,
0, D3D12_MAX_MAXANISOTROPY, D3D12_COMPARISON_FUNC_NEVER,
{ 0, 0, 0, 0 }, 0, D3D12_FLOAT32_MAX };
```
* **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](/pt-BR/build/console-features/console-workflows/xbox-game-life-cycle) para obter mais detalhes.
## Dicas e truques
### Arquivo de empacotamento Microsoft Game Config
O Microsoft Game Development Kit (GDK) não usa mais um arquivo `Package.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.
```xml theme={null}
```
O elemento `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 ``.
```xml theme={null}
```
> 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.
```xml theme={null}
hex-number
```
Conforme observado acima, você não precisa mais usar elementos de manifesto para obter o 7º núcleo e a disponibilidade estendida de recursos da GPU, mas pode usar o manifesto para controlar a memória do título.
```xml theme={null}
variable
```
O elemento appxmanifest acima foi substituído por um elemento cujo padrão é "Standard" para o controle de memória do título.
```xml theme={null}
Advanced
```
Algumas extensões de manifesto do XBOX One Software Development Kit também podem ser transferidas para o arquivo `.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**.
```cpp theme={null}
#include
XSystemDeviceType deviceType = XSystemGetDeviceType();
switch (deviceType)
{
case XSystemDeviceType::Pc: ... break;
case XSystemDeviceType::XboxOne: ... break;
case XSystemDeviceType::XboxOneS: ... break;
case XSystemDeviceType::XboxOneX: ... break;
case XSystemDeviceType::XboxOneXDevkit: ... break;
case XSystemDeviceType::XboxScarlettLockhart: /* Xbox Series S */ ... break;
case XSystemDeviceType::XboxScarlettAnaconda: /* Xbox Series X */ ... break;
case XSystemDeviceType::XboxScarlettDevkit: ... break;
case XSystemDeviceType::Unknown: ... break;
}
```
### 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_STRING` para esse build é "April 2020 GRDK".
* `_GRDK_VER_STRING_W` cadeia de caracteres larga UTF16-LE equivalente a `_GRDK_VER_STRING`.
* `_GRDK_VER_STRING_COMPACT_W` para esse build é uma cadeia de caracteres larga UTF16-LE contendo "April 2020".
Para as plataformas `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_STRING` para esse build é "April 2020 GXDK".
* `_GXDK_VER_STRING_W` cadeia de caracteres larga UTF16-LE equivalente a `_GXDK_VER_STRING`.
* `_GXDK_VER_STRING_COMPACT_W` para 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.
```cpp theme={null}
#include
ComPtr devEnum;
hr = CoCreateInstance(__uuidof(MMDeviceEnumerator), nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(devEnum.GetAddressOf()));
// Check hr for errors
ComPtr devices;
hr = devEnum->EnumAudioEndpoints(eRender, DEVICE_STATE_ACTIVE, &devices);
// Check hr for errors
ComPtr endpoint;
hr = devices->Item(0, endpoint.GetAddressOf();
// Check hr for errors
LPWSTR id = nullptr;
hr = endpoint->GetId(&id);
// Check hr for errors
// The id variable contains the device identifier used by XAudio2
CoTaskMemFree(id);
```
### MapVirtualKey
Os métodos `MapVirtualKey` 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.
```cpp theme={null}
int vk = static_cast(wParam);
switch (vk)
{
case VK_SHIFT:
#if defined(WINAPI_FAMILY) && (WINAPI_FAMILY == WINAPI_FAMILY_GAMES)
vk = (((lParam & 0x00ff0000) >> 16) == 0x36) ? VK_RSHIFT : VK_LSHIFT;
#else
vk = MapVirtualKey((lParam & 0x00ff0000) >> 16, MAPVK_VSC_TO_VK_EX);
#endif
break;
case VK_CONTROL:
vk = (lParam & 0x01000000) ? VK_RCONTROL : VK_LCONTROL;
break;
case VK_MENU:
vk = (lParam & 0x01000000) ? VK_RMENU : VK_LMENU;
break;
}
```
### MultiByteToWideChar e WideCharToMultiByte
Ao converter entre cadeias de caracteres largos (UTF-16 LE) e cadeias de caracteres estreitos, os desenvolvedores Win32 costumam usar [MultiByteToWideChar](https://learn.microsoft.com/windows/desktop/api/stringapiset/nf-stringapiset-multibytetowidechar) e [WideCharToMultiByte](https://learn.microsoft.com/windows/desktop/api/stringapiset/nf-stringapiset-widechartomultibyte). Para bases de código modernas, recomendamos que você use `CP_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.
```cpp theme={null}
// Name is a char array as input.
wchar_t wname[MAX_PATH] = {};
int result = MultiByteToWideChar(CP_UTF8, 0, name, -1, wname, MAX_PATH);
if (result <= 0) // Error
```
Às vezes, 437 e 1252 são usados diretamente. A 437 não é compatível com o XBOX One Software Development Kit nem com o Microsoft Game Development Kit (GDK) no XBOX. A 1252 funcionava no XBOX One XDK, mas não é compatível com o Microsoft Game Development Kit (GDK) no XBOX. No Microsoft Game Development Kit (GDK) no XBOX, `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 `` 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 como `GetCurrencyFormatEx`, `GetNumberFormatEx`, a enumeração de formatos de data e hora e outros recursos.
### Observações sobre áudio XMA2
Se estiver faltando a definição de `SHAPE_XMA_INPUT_BUFFER_ALIGNMENT`, você precisará adicionar explicitamente uma referência ao cabeçalho shapexmacontext.h.
```cpp theme={null}
#include
```
Com o XBOX One Software Development Kit, esse cabeçalho era incluído implicitamente por alguns outros cabeçalhos de áudio.
### 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.
```cpp theme={null}
XTaskQueueHandle queue;
ThrowIfFailed(
XTaskQueueCreate(XTaskQueueDispatchMode::ThreadPool, XTaskQueueDispatchMode::Immediate, &queue)
);
XAsyncBlock* ab = new XAsyncBlock;
ZeroMemory(ab, sizeof(XAsyncBlock));
ab->queue = queue;
// Show dialog, wait for completion, get result.
XGameUiMessageDialogButton button;
if (SUCCEEDED(XGameUiShowMessageDialogAsync(ab, u8"This is a title", u8"This is content text", u8"Option #1", u8"Option #2", u8"Option #3", XGameUiMessageDialogButton::First, XGameUiMessageDialogButton::Third)) &&
SUCCEEDED(XAsyncGetStatus(ab, true)) &&
SUCCEEDED(XGameUiShowMessageDialogResult(ab, &button)))
{
DoSomethingWithResponse(button);
}
```
### 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 do `vcxproj`:
```text theme={null}
Xbox.Game.Chat.2.Cpp.API;Xbox.Services.API.C
```
Se esse elemento não estiver presente, o padrão é incluir somente a XSAPI.
## 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 executando `dumpbin.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).
Bibliotecas estáticas originalmente compiladas para o Windows para desktop, que usam apenas APIs da lista aprovada, geralmente podem ser vinculadas diretamente a um binário do Microsoft Game Development Kit (GDK) destinado ao XBOX. No entanto, isso não é universalmente verdadeiro, pois diferenças de comportamento (como a limitação de janela única) podem causar falhas de runtime do componente se ele não tiver sido projetado para lidar com essas diferenças.
As bibliotecas de vínculo dinâmico (DLLs) que têm uma lista de importação totalmente dentro das APIs compatíveis também geralmente serão carregadas e funcionarão sem alterações. O sistema operacional do Microsoft Game Development Kit (GDK) no XBOX contém lógica de encaminhamento para redirecionar corretamente esse conjunto de APIs para os locais de implementação, caso sejam diferentes do Windows para desktop.
Embora a capacidade de reutilizar componentes do Windows para desktop no console possa economizar tempo em muitos cenários, isso não é recomendado para caminhos críticos para o desempenho em um título lançado. A maioria dos componentes compilados pensando no Windows para desktop não terá sido compilada com os sinalizadores mais adequados para execução com o Microsoft Game Development Kit (GDK). Mais notavelmente, como os componentes de desktop são destinados a uma gama mais ampla de CPUs, esses componentes podem ter sido compilados sem otimizações AVX. Reutilizar DLLs de desktop também pode resultar em um tamanho total de código maior, em comparação com a recompilação para o Microsoft Game Development Kit (GDK).
## 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)](https://aka.ms/gdkdl) 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)](https://learn.microsoft.com/cpp/cpp/objects-own-resources-raii) e [Resource Acquisition Is Initialization](https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization), é uma prática recomendada fortemente usando `std::unique_ptr`, `Microsoft::WRL::ComPtr` e 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_t` e `uintptr_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<>` e `dynamic_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 /Oi` para otimização geral e `/O2` para módulos críticos
* `/fp:fast`
* `/arch:AVX` para a família de dispositivos XBOX One; `/arch:AVX2` para XBOX Series X|S.
* `/favor:AMD`
* Otimização de Programa Inteiro e Otimização Guiada por Perfil
* Opções do vinculador `/OPT:REF,ICF`
Por motivos históricos, `/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](https://blogs.msdn.com/b/vcblog/archive/2015/08/06/new-in-vs-2015-zc-throwingnew.aspx), [/Zc:\_\_cplusplus](https://blogs.msdn.microsoft.com/vcblog/2018/04/09/msvc-now-correctly-reports-__cplusplus/), `/volatile:iso`, [/permissive-](https://blogs.msdn.microsoft.com/vcblog/2016/11/16/permissive-switch/), [/Zc:twoPhase-](https://blogs.msdn.microsoft.com/vcblog/2017/09/11/two-phase-name-lookup-support-comes-to-msvc/) e [/Debug:FASTLINK](https://blogs.msdn.microsoft.com/vcblog/2015/10/16/debugfastlink-for-vs2015-update-1/).
### Código condicional
Para código condicional em que os caminhos divergem, tenha em mente as seguintes convenções.
| Plataforma | Compilação condicional |
| - | - |
| Desenvolvimento para a área de trabalho Win32 | `#if !defined(WINAPI_FAMILY) \|\| (WINAPI_FAMILY == WINAPI_FAMILY_DESKTOP_APP)` |
| XBOX One Software Development Kit | `#if defined(WINAPI_FAMILY) && (WINAPI_FAMILY == WINAPI_FAMILY_TV_TITLE)`
-ou-
`#if defined(_XBOX_ONE) && defined(_TITLE)` |
| Microsoft Game Development Kit (GDK) no XBOX One ou XBOX Series X\|S | `#ifdef _GAMING_XBOX` |
| Microsoft Game Development Kit (GDK) somente no XBOX One | `#ifdef _GAMING_XBOX_XBOXONE` |
| Microsoft Game Development Kit (GDK) somente no XBOX Series X\|S | `#ifdef _GAMING_XBOX_SCARLETT` |
Se sua base de código já oferece suporte ao XBOX One Software Development Kit, um bom ponto de partida é fazer o seguinte:
1. Pesquise todas as instâncias de `_XBOX_ONE` na sua base de código
2. 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 para `wchar_t*` (UTF-16 LE, little endian). O [manifesto UTF-8 Everywhere](https://utf8everywhere.org/) 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.
Recomendamos o seguinte:
* 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::wstring` e `wchar_t*`, use `std::string` e `char*` como UTF-8.
* Para literais de cadeia de caracteres estreitos, garanta a conformidade com UTF-8 usando o prefixo C++ `u8` em vez de nenhum prefixo ou `L`.
* Mantenha as `defines` de pré-processador de build `UNICODE` e `_UNICODE` existentes (no Visual Studio, essa é a propriedade ``) como medida de segurança, mas, em vez de depender das macros, sempre chame explicitamente a versão `W()` ou `A()`.
* Evite `TCHAR`, `TEXT()`, `LPTSTR` e 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 palavra `Get` 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)
## Related topics
- [Diretório de tópicos NDA: links ativos do Microsoft Learn](/pt-BR/nda/nda-topic-directory.md)
- [Características de consola para el XBOX Game Development Kit](/es/build/console-features/index.md)
- [Usuarios y dispositivos de entrada](/es/build/core-features/common/user/users-input-devices.md)
- [Guias de portabilidade para o XBOX GDK](/pt-BR/home/build-first-title/porting-guides.md)
- [Documentação de desenvolvimento de jogos XBOX](/pt-BR/index.md)