Princípios básicos da amostra do Marble Maze

Applies to Windows only

Este documento descreve as características fundamentais do projeto Marble Maze, por exemplo, como ele usa o Visual C++ no ambiente de Tempo de Execução do Windows, como ele é criado e estruturado e como ele é compilado. O documento também descreve várias das convenções que são usadas no código.

Observação  O código de amostra que corresponde a esse documento está disponível em Amostra do jogo DirectX Marble Maze.

Neste tópico

Veja a seguir alguns dos pontos-chave que este documento discute para quando você planejar e desenvolver seu jogo da Windows Store.

  • Use o modelo de Aplicativo Direct3D em um aplicativo C++ para criar seu jogo DirectX da Windows Store. Use o Visual Studio para criar um projeto de aplicativo da Windows Store exatamente como você criaria um projeto padrão.
  • O Tempo de Execução do Windows oferece classes e interfaces para que seja possível desenvolver aplicativos da Windows Store com o uso de um método mais moderno orientado a objetos.
  • Use referências de objeto com o símbolo de circunflexo (^) para gerenciar o tempo de vida de variáveis do Tempo de Execução do Windows, Microsoft::WRL::ComPtr para gerenciar o tempo de vida de objetos COM e std::shared_ptr ou std::unique_ptr para gerenciar o tempo de vida de todos os outros objetos C++ alocados ao heap.
  • Na maioria dos casos, use o tratamento de exceções em vez de códigos de resultado para lidar com erros inesperados.
  • Use anotações SAL junto com ferramentas de análise de código para ajudar a descobrir erros no seu aplicativo.

Criando o projeto do Visual Studio

Se você baixou e extraiu a amostra, pode abrir o arquivo de solução MarbleMaze.sln no Visual Studio e obter o código bem na sua frente. Você também pode ver a origem na página da Galeria de Amostras da MSDN Amostra do jogo DirectX Marble Maze, selecionando a guia Pesquisar Código.

Quando criamos o projeto do Visual Studio para o Marble Maze, começamos com um projeto existente. No entanto, se você ainda não tem um projeto existente que forneça a funcionalidade básica necessária para o seu jogo DirectX da Windows Store, convém criar um projeto com base no modelo de Aplicativo Direct3D do Visual Studio, pois ele fornece um aplicativo 3D de trabalho básico.

Uma definição de projeto importante no modelo de Aplicativo Direct3D é a opção /ZW, que permite que o programa use as extensões de linguagem do Tempo de Execução do Windows. Essa opção é habilitada por padrão quando você usa o modelo do Visual Studio.

Cuidado  A opção /ZW não é compatível com opções como /clr. No caso de /clr, isso significa que você não pode direcionar tanto o .NET Framework quanto o Tempo de Execução do Windows a partir do mesmo projeto Visual C++.

Cada aplicativo da Windows Store que você adquire na Windows Store vem no formato de um pacote de aplicativo. Um pacote de aplicativo contém um manifesto de pacote, que contém informações sobre o aplicativo. Por exemplo, você pode especificar os recursos (isto é, o acesso necessário a recursos protegidos do sistema ou dados de usuário) do seu aplicativo. Se você determinar que o seu aplicativo exige determinados recursos, use o manifesto de pacote para declarar os recursos necessários. O manifesto também permite especificar as propriedades do projeto, como rotações de dispositivos com suporte, imagens de blocos e a tela inicial. Para saber mais sobre pacotes de aplicativo, veja Pacotes e implantação de aplicativo.

Criando, implantando e executando o jogo

Crie um projeto de aplicativo da Windows Store exatamente como você criaria um projeto padrão. (Na barra de menus, escolha Compilar, Compilar Solução.) Nesta etapa, o código é compilado e também empacotado para uso como um aplicativo da Windows Store.

Depois de compilar o projeto, você precisa implantá-lo. (Na barra de menu, escolha Compilar, Implantar Solução.) O Visual Studio também implanta o projeto quando você executa o jogo no depurador.

Depois de implantar o projeto, escolha o bloco do Marble Maze para executar o jogo. Como opção, no Visual Studio, na barra de menus, escolha Depurar, Iniciar Depuração.

Controlando o jogo

Você pode usar toque, acelerômetro, controlador do Xbox 360 ou mouse para controlar o Marble Maze.

  • Use o teclado direcional no controle para mudar o item de menu ativo.
  • Use toque, o botão A, o botão Iniciar ou o mouse para escolher um item de menu.
  • Use toque, o acelerômetro, o botão de controle esquerdo ou o mouse para inclinar o labirinto.
  • Use toque, o botão A, o botão Iniciar ou o mouse para fechar menus, como a tabela de pontuações altas.
  • Use o botão Iniciar ou a tecla P para pausar ou retomar o jogo.
  • Use o botão Voltar no controlador ou a tecla Página Inicial no teclado para reiniciar o jogo.
  • Quando a tabela de pontuações altas estiver visível, use o botão Voltar ou tecla Página Inicial para limpar todas as pontuações.

Convenções de código

O Tempo de Execução do Windows é uma interface de programação que pode ser usada para criar aplicativos da Windows Store que são executados somente e um aplicativo especial. Esses aplicativos usam funções autorizadas, tipos de dados e dispositivos, sendo distribuídos a partir da Windows Store. No nível mais baixo, o Tempo de Execução do Windows é formado por uma ABI (interface Vinária de Aplicativo). A ABI é um contrato binário de nível inferior que torna as APIs do Tempo de Execução do Windows mais acessíveis a várias linguagens de programação, como o JavaScript, as linguagens .NET e o Microsoft Visual C++.

Para chamar APIs do Tempo de Execução do Windows do JavaScript e do .NET, essas linguagens exigem projeções que são específicas do ambiente de cada linguagem. Quando você chama uma API do Tempo de Execução do Windows do JavaScript ou do .NET, invoca a projeção, que, em seguida, chama a função ABI subjacente. Embora você possa chamar as funções ABI diretamente em C++, a Microsoft também oferece projeções para C++, pois elas simplificam muito o consumo das APIs do Tempo de Execução do Windows, ao mesmo tempo mantendo o alto desempenho. A Microsoft também disponibiliza extensões de linguagem para o Visual C++ que oferecem suporte especificamente às projeções do Tempo de Execução do Windows. Muitas dessas extensões de linguagem lembram a sintaxe da linguagem C++/CLI. No entanto, em vez de se voltarem para o CLR (Common Language Runtime), os aplicativos nativos usam essa sintaxe para se voltarem ao Tempo de Execução do Windows. O modificador de referência de objeto, ou circunflexo (^), é uma parte importante dessa nova sintaxe, pois permite a exclusão automática de objetos de tempo de execução por meio da contagem de referência. Em vez de chamar métodos, como AddRef e Release para gerenciar o tempo de vida de um objeto do Tempo de Execução do Windows, o tempo de execução exclui o objeto quando não há outras referências de componentes, por exemplo, quando ele sai do escopo ou define todas as referências como nullptr. Outra parte importante do uso do Visual C++ para criar aplicativos da Windows Store é a palavra-chave ref new. Use ref new em vez de new para criar objetos de contagem de referências do Tempo de Execução do Windows. Para saber mais, veja o artigo Sistema de tipos (C++/CX).

Importante  

Você só precisa usar ^ e ref new quando criar objetos ou componentes do Tempo de Execução do Windows. Você pode usar a sintaxe do C++ padrão ao criar o código básico do aplicativo que não usa o Tempo de Execução do Windows.

O Marble Maze usa ^ junto com Microsoft::WRL::ComPtr para gerenciar objetos alocados em pilha e reduzir a perda de memória. Recomendamos o uso de ^ para gerenciar a vida útil das variáveis do Tempo de Execução do Windows, de ComPtr para gerenciar a vida útil das variáveis COM (como quando o DirectX é usado) e de std::std::shared_ptr ou std::unique_ptr para gerenciar a vida útil de todos os outros objetos C++ alocados em pilha.

Para saber mais sobre as extensões de linguagem que estão disponíveis para um aplicativo da Windows Store em C++, veja Referência da linguagem C++ (C++/CX). Para saber mais sobre a API do Tempo de Execução do Windows, veja Referência da API do Windows para aplicativos da Windows Store.

Tratamento de erros

O Marble Maze usa o tratamento de exceções como a principal maneira de lidar com erros inesperados. Embora o código jogo use tradicionalmente códigos de erro ou registro em log, como valores de HRESULT, para indicar erros, o tratamento de exceções apresenta duas vantagens principais. Em primeiro lugar, ele pode facilitar a leitura e a manutenção do código. Em termos de código, o tratamento de exceções é a maneira mais eficiente de propagar um erro para uma rotina que pode lidar com esse erro. O uso de códigos de erro geralmente exige que cada função propague os erros de maneira explícita. Uma segunda vantagem é que você também pode configurar o depurador do Visual Studio para ser interrompido quando ocorrer uma exceção, parando imediatamente no local e no contexto do erro. O Tempo de Execução do Windows também usa amplamente o tratamento de exceções. Assim, ao usar o tratamento de exceções no seu código, você pode consolidar o tratamento de erros em um único modelo.

Recomendamos o uso das seguintes convenções no seu modelo de tratamento de erros:

  • Use exceções para comunicar erros inesperados.
  • Não use exceções para controlar o fluxo do código.
  • Capture somente as exceções que podem ser tratadas e recuperadas com segurança. Caso contrário, não capture a exceção e permita que o aplicativo seja encerrado.
  • Quando você chamar uma rotina DirectX que retorna HRESULT, use a função DX::ThrowIfFailed. Essa função é definida em DirectXSample.h. ThrowIfFailed lançará uma exceção se o HRESULT fornecido for um código de erro. Por exemplo, E_POINTER faz com que ThrowIfFailed lance Platform::NullReferenceException.

    Quando você usar ThrowIfFailed, coloque a chamada DirectX em uma linha separada para ajudar a melhorar a legibilidade do código, conforme mostrado no exemplo a seguir.

    
    // Identify the physical adapter (GPU or card) this device is running on.
    ComPtr<IDXGIAdapter> dxgiAdapter;
    DX::ThrowIfFailed(
        dxgiDevice->GetAdapter(&dxgiAdapter)
        );
    
    
    
  • Embora seja recomendável evite o uso de HRESULT para erros inesperados, é mais importante evitar o uso do tratamento de exceções para controlar o fluxo do código. Portanto, é preferível usar um valor de retorno de HRESULT quando necessário para controlar o fluxo do código.

Anotações SAL

Use anotações SAL junto com ferramentas de análise de código para ajudar a descobrir erros no seu aplicativo.

Usando a linguagem de anotação de código-fonte da Microsoft (SAL), você pode anotar, ou descrever, como uma função usa seus parâmetros. Anotações SAL também descrevem valores de retorno. Anotações SAL trabalham com a ferramenta de Análise de Código C/C++ para descobrir possíveis defeitos no o código fonte C e C++. Erros de codificação comuns relatados pela ferramenta incluem saturações de buffer, memória não inicializada, cancelamentos de referência de ponteiro nulo e vazamentos de memória e recursos.

Considere o método BasicLoader::LoadMesh, que é declarado em BasicLoader.h. Este método usa _In_ para especificar que filename é um parâmetro de entrada (e, portanto, apenas será usado para leitura), _Out_ para especificar que vertexBuffer e indexBuffer são parâmetros de saída (e, portanto, apenas serão usados para gravação) e _Out_opt_ para especificar que vertexCount e indexCount são parâmetros de saída opcionais (e podem ser gravados). Como vertexCount e indexCount são parâmetros de saída opcionais, eles podem ser nullptr. A ferramenta de Análise de Código C/C++ examina chamadas para esse método de forma a garantir que os parâmetros que ela transmitir irão atender a esses critérios.


void LoadMesh(
    _In_ Platform::String^ filename,
    _Out_ ID3D11Buffer** vertexBuffer,
    _Out_ ID3D11Buffer** indexBuffer,
    _Out_opt_ uint32* vertexCount,
    _Out_opt_ uint32* indexCount
    );


Para realizar a análise de código no seu aplicativo, na barra de menu, escolha Construir, Executar Análise de Código na Solução. Para saber mais sobre a análise de código, veja Analisando a qualidade do código C/C++ com o uso da análise de código.

A lista completa de anotações disponíveis está definida em sal.h. Para saber mais sobre Anotações SAL.

Próximas etapas

Leia Estrutura do aplicativo Marble Maze para saber mais sobre como o código do aplicativo Marble Maze é estruturado e como a estrutura de um aplicativo da Windows Store DirectX é diferente daquela de um aplicativo de área de trabalho tradicional.

Tópicos relacionados

Estrutura do aplicativo Marble Maze
Desenvolvendo o Marble Maze, um jogo da Windows Store em C++ e DirectX

 

 

Mostrar:
© 2014 Microsoft