Nozioni fondamentali su Marble Maze

Applies to Windows only

In questo documento vengono descritte le principali caratteristiche del progetto Marble Maze, ad esempio come usa Visual C++ nell'ambiente Windows Runtime, come è creato e strutturato e il modo in cui viene compilato. Vengono descritte, inoltre, le numerose convenzioni usate nel codice.

Nota  Il codice di esempio che corrisponde a questo documento è disponibile alla pagina relativa all'esempio di gioco DirectX Marble Maze.

In questo argomento

Ecco alcuni aspetti fondamentali descritti in questo documento relativi alla pianificazione e allo sviluppo del tuo gioco di Windows Store.

  • Usa il modello Applicazione Direct3D in un'applicazione C++ per creare il gioco in Windows Store DirectX. Usa Visual Studio per compilare un progetto di app in Windows Store in modo analogo alla compilazione di un progetto standard.
  • Windows Runtime fornisce classi e interfacce per consentirti di sviluppare app in Windows Store in modo più moderno e orientato agli oggetti.
  • Usa i riferimenti agli oggetti con il simbolo dell'accento circonflesso (^) per gestire la durata delle variabili di Windows Runtime, Microsoft::WRL::ComPtr per gestire la durata degli oggetti COM e std::shared_ptr o std::unique_ptr per gestire la durata di tutti gli altri oggetti C++ con allocazione heap.
  • Nella maggior parte dei casi, usa la gestione delle eccezioni, anziché i codici di risultato, per gestire gli errori imprevisti.
  • Usa le annotazioni SAL con gli strumenti di analisi del codice per individuare gli errori nell'app.

Creazione del progetto Visual Studio

Se hai scaricato ed estratto l'esempio, puoi aprire il file di soluzione MarbleMaze.sln in Visual Studio per visualizzare il codice. Puoi visualizzare il codice sorgente anche nella pagina della raccolta di esempi MSDN relativa all'esempio di gioco Marble Maze DirectX selezionando la scheda Sfoglia il codice.

Quando abbiamo creato il progetto Visual Studio per Marble Maze, siamo partiti da un progetto esistente. Tuttavia, se non hai un progetto esistente che fornisce le funzionalità di base richieste dal tuo gioco in Windows Store DirectX, ti consigliamo di creare un progetto basato sul modello Applicazione Direct3D di Visual Studio, in quanto fornisce un'applicazione 3D funzionante di base.

Un'importante impostazione di progetto nel modello Applicazione Direct3D è l'opzione /ZW, che consente di usare le estensioni del linguaggio Windows Runtime. Questa opzione è abilitata per impostazione predefinita quando si usa il modello di Visual Studio.

Attenzione  L'opzione /ZW non è compatibile con opzioni come /clr. Nel caso di /clr, questo significa che lo stesso progetto Visual C++ non può essere destinato sia a .NET Framework che a Windows Runtime.

Ogni app in Windows Store ottenuta da Windows Store viene fornita come pacchetto di app. Un pacchetto di app contiene un manifesto del pacchetto, che contiene a sua volta informazioni sull'app. Puoi ad esempio specificare le funzionalità dell'app, ad esempio l'accesso richiesto alle risorse di sistema protette o ai dati utente. Se stabilisci che l'app richiede determinate funzionalità, usa il manifesto del pacchetto per dichiararle. Il manifesto consente inoltre di specificare le proprietà del progetto come le rotazioni del dispositivo supportate, le immagini delle sezioni e la schermata iniziale. Per altre info sui pacchetti di app, vedi Pacchetti di app e distribuzione (app di Windows Store).

Compilazione, distribuzione ed esecuzione del gioco

Compila un progetto di app in Windows Store seguendo la stessa procedura usata per la compilazione di un progetto standard. Sulla barra dei menu scegli Compila, Compila soluzione . Il codice viene compilato e compresso in un pacchetto per essere usato come app in Windows Store.

Dopo aver compilato il progetto lo devi distribuire. Sulla barra dei menu scegli Compila, Distribuisci soluzione. Quando esegui il gioco dal debugger, la distribuzione del progetto viene eseguita da Visual Studio.

Al termine della distribuzione del progetto, seleziona il riquadro di Marble Maze per eseguire il gioco. In alternativa, scegli Debug, Avvia debug dalla barra dei menu di Visual Studio.

Controllo del gioco

Per controllare Marble Maze, puoi usare il tocco, l'accelerometro, il controller Xbox 360 oppure il mouse.

  • Usa il tasto direzionale del controller per modificare la voce di menu attiva.
  • Per selezionare una voce di menu, usa il tocco, il pulsante A, il pulsante Start o il mouse.
  • Per inclinare il labirinto, usa il tocco, l'accelerometro, il thumbstick sinistro o il mouse.
  • Per chiudere menu come la tabella dei punteggi elevati, usa il tocco, il pulsante A, il pulsante Start o il mouse.
  • Per sospendere o riprendere il gioco, usa il pulsante Start o il tasto P.
  • Per riavviare il gioco, usa il pulsante Indietro del controller o il tasto Home.
  • Se la tabella dei punteggi elevati è visibile, usa il pulsante Indietro o il tasto Home per cancellare tutti i punteggi.

Convenzioni nel codice

Windows Runtime è un'interfaccia di programmazione che puoi usare per creare app in Windows Store che funzionano solo in un ambiente applicativo speciale. Queste app usano funzioni autorizzate, tipi di dati e dispositivi e sono distribuite da Windows Store. Al livello inferiore, Windows Runtime è costituito da un'interfaccia ABI (Application Binary Interface). ABI è un contratto binario di basso livello che rende le API di Windows Runtime accessibili a più linguaggi di programmazione come JavaScript, i linguaggi .NET e Visual C++.

Per chiamare le API di Windows Runtime da JavaScript e da .NET, questi linguaggi richiedono proiezioni specifiche per ogni ambiente di linguaggio. Quando si chiama un'API di Windows Runtime da JavaScript o da .NET, viene richiamata la proiezione, che a sua volta chiama la funzione ABI sottostante. Sebbene sia possibile chiamare le funzioni ABI direttamente in C++, Microsoft fornisce le proiezioni anche per C++, poiché semplificano notevolmente l'uso delle API di Windows Runtime, senza compromettere le prestazioni. Fornisce inoltre le estensioni del linguaggio per Visual C++ che supportano in modo specifico le proiezioni di Windows Runtime. Molte di queste estensioni del linguaggio sono simili alla sintassi del linguaggio C++/CLI. Tuttavia, invece di puntare a Common Language Runtime (CLR), le app native usano questa sintassi per puntare a Windows Runtime. Il modificatore del riferimento all'oggetto, o l'accento circonflesso (^), è una parte importante di questa nuova sintassi poiché consente l'eliminazione automatica di oggetti di runtime mediante il conteggio dei riferimenti. Anziché chiamare metodi quali AddRef e Release per gestire la durata di un oggetto Windows Runtime, il runtime elimina l'oggetto quando nessun altro componente vi fa riferimento, ad esempio quando lascia l'ambito o si impostano tutti i riferimenti su nullptr. Un'altra parte importante dell'uso di Visual C++ per la creazione di app Windows Store è la parola chiave ref new. Usa ref new anziché new per creare oggetti Windows Runtime con conteggio dei riferimenti. Per altre info, vedi Sistema di tipi (C++/CX).

Importante  

Devi usare solo ^ e ref new quando crei oggetti di Windows Runtime o componenti di Windows Runtime. Puoi ricorrere alla sintassi C++ standard per la scrittura di codice dell'applicazione di base che non usa Windows Runtime.

Marble Maze usa ^ insieme a Microsoft::WRL::ComPtr per gestire gli oggetti con allocazione heap e ridurre al minimo le perdite di memoria. Ti consigliamo di usare ^ per gestire la durata delle variabili Windows Runtime, ComPtr per gestire la durata delle variabili COM (ad esempio con DirectX) e std::std::shared_ptr o std::unique_ptr per gestire la durata di tutti gli oggetti C++ con allocazione heap.

Per altre info sulle estensioni del linguaggio disponibili in un'app in Windows Store C++, vedi Riferimenti al linguaggio Visual C++ (C++/CX). Per altre info sull'API Windows Runtime, vedi Riferimento all'API Windows per app di Windows Store.

Gestione degli errori

Marble Maze usa la gestione delle eccezioni come metodo principale per gestire gli errori non previsti. Sebbene il codice del gioco usi in genere la registrazione o i codici di errore, come i valori HRESULT, per indicare gli errori, la gestione delle eccezioni presenta due vantaggi principali. Innanzi tutto, semplifica la lettura e la gestione del codice. Dal punto di vista del codice, la gestione delle eccezioni è un modo più efficace per propagare un errore a una routine in grado di gestirlo. In genere, l'uso di codici di errore richiede che ogni funzione esegua esplicitamente la propagazione degli errori. Un altro vantaggio consiste nella possibilità di configurare il debugger di Visual Studio in modo che venga interrotto quando si verifica un'eccezione, per consentire l'arresto immediato nella posizione e nel contesto dell'errore. Anche Windows Runtime fa ampio ricorso alla gestione delle eccezioni. Pertanto, con l'uso della gestione delle eccezioni nel tuo codice puoi combinare tutta la gestione degli errori in un unico modello.

Ti consigliamo di usare le convenzioni seguenti nel tuo modello di gestione degli errori:

  • Usa le eccezioni per comunicare gli errori non previsti.
  • Non usare le eccezioni per controllare il flusso del codice.
  • Rileva solo le eccezioni che sei in grado di gestire in modo sicuro e da cui puoi eseguire il ripristino senza rischi. In caso contrario, non rilevare l'eccezione e lascia che l'app si interrompa.
  • Quando chiami una routine DirectX che restituisce HRESULT, usa la funzione DX::ThrowIfFailed. Questa funzione è definita in DirectXSample.h. ThrowIfFailed genera un'eccezione se l'oggetto HRESULT fornito è un codice di errore. Ad esempio, E_POINTER fa in modo che ThrowIfFailed generi Platform::NullReferenceException.

    Quando usi ThrowIfFailed, inserisci la chiamata DirectX su una riga separata per migliorare la leggibilità del codice, come illustrato nell'esempio riportato di seguito.

    
    // Identify the physical adapter (GPU or card) this device is running on.
    ComPtr<IDXGIAdapter> dxgiAdapter;
    DX::ThrowIfFailed(
        dxgiDevice->GetAdapter(&dxgiAdapter)
        );
    
    
    
  • Sebbene sia consigliabile evitare l'uso di HRESULT per gli errori non previsti, è più importante evitare l'uso della gestione delle eccezioni per controllare il flusso del codice. Se necessario, pertanto, per quest'attività è preferibile usare un valore restituito HRESULT.

Annotazioni SAL

Usa le annotazioni SAL con gli strumenti di analisi del codice per individuare gli errori nell'app.

Usando il linguaggio di annotazione del codice sorgente Microsoft (SAL), è possibile annotare, o descrivere, come una funzione usa i parametri. Le annotazioni SAL descrivono anche i valori restituiti e vengono usate in combinazione con lo strumento di analisi del codice C/C++ per individuare possibili errori nel codice sorgente C e C++. Gli errori di codifica più comuni segnalati dallo strumento includono i sovraccarichi del buffer, l'annullamento dell'inizializzazione della memoria, le dereferenziazioni al puntatore null e le perdite di memoria e risorse.

Considera il metodo BasicLoader::LoadMesh, dichiarato in BasicLoader.h. Questo metodo usa _In_ per specificare che filename è un parametro di input (e quindi verrà solo letto), _Out_ per specificare che vertexBuffer e indexBuffer sono parametri di output (e quindi verranno solo scritti) e _Out_opt_ per specificare che vertexCount e indexCount sono parametri di output facoltativi (e consentono le operazioni di scrittura). Poiché vertexCount e indexCount sono parametri di output facoltativi, possono essere nullptr. Lo strumento di analisi del codice C/C++ esamina le chiamate al metodo per verificare che i parametri passati soddisfino questi criteri.


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


Per eseguire l'analisi del codice sulla tua app, scegli Compila, Esegui analisi del codice su soluzione dalla barra dei menu. Per altre info sull'analisi del codice, vedi Verifica della qualità del codice C/C++ tramite analisi del codice.

L'elenco completo delle annotazioni disponibili è definito in sal.h. Per altre info sulle Annotazioni SAL.

Passaggi successivi

Fai riferimento a Struttura dell'applicazione Marble Maze per informazioni sul modo in cui è strutturato il codice dell'applicazione Marble Maze e sulle differenze tra la struttura di un'app in Windows Store DirectX e un'applicazione desktop tradizionale.

Argomenti correlati

Struttura dell'applicazione Marble Maze
Sviluppo di Marble Maze, un gioco di Windows Store scritto in C++ e DirectX

 

 

Mostra:
© 2014 Microsoft