Основные положения примера Marble Maze

Applies to Windows only

В этом документе описаны основные характеристики проекта Marble Maze, такие как использование Visual C++ в среде выполнения Windows, создание проекта, его структурирование и сборка. В документе также описаны некоторые соглашения, используемые в коде.

Примечание  Пример кода, соответствующего этому документу, см. в примере игры DirectX Marble Maze.

В этом разделе

Основные вопросы, возникающие при планировании и разработке игры для Магазина Windows, которые обсуждаются в этом документе.

  • Использование шаблона Direct3D Application в приложении C++ при создании игры DirectX для Магазина Windows. Использование Visual Studio для сборки проекта приложения Магазина Windows аналогично сборке стандартного проекта.
  • Среда выполнения Windows предоставляет классы и интерфейсы, благодаря чему вы можете создавать приложения Магазина Windows в более современном объектно-ориентированном стиле.
  • Использование ссылок на объекты с применением символа ^ ("шляпка") для контроля за переменными среды выполнения Windows, Microsoft::WRL::ComPtr — для контроля за объектами COM и std::shared_ptr или std::unique_ptr — для контроля за всеми остальными динамически выделенными объектами C++.
  • В большинстве случаев рекомендуется обработка исключений вместо кодов завершения для обработки непредвиденных ошибок.
  • Использование для обнаружения ошибок в приложении аннотаций SAL совместно со средствами анализа кода.

Создание проекта Visual Studio

После скачивания и распаковки примера вы можете открыть файл решения MarbleMaze.sln в Visual Studio и просмотреть его код. Исходный код также можно просмотреть на странице Пример игры DirectX Marble Maze в коллекции примеров MSDN, перейдя на вкладку Просмотр кода.

Когда мы создавали проект Visual Studio для Marble Maze, мы начинали с существующего проекта. Однако если у вас нет уже существующего проекта, который обеспечивает основные функции, необходимые для игры DirectX для Магазина Windows, мы рекомендуем создать проект на основе шаблона Visual Studio Direct3D Application, поскольку он позволяет создать простое работающее трехмерное приложение.

Одним из важных параметров проекта в шаблоне Direct3D Application является параметр /ZW, который позволяет программе использовать языковые исключения среды выполнения Windows. При использовании шаблона Visual Studio этот параметр включен по умолчанию.

Внимание  Параметр /ZW несовместим с такими параметрами, как /clr. В случае /clr это означает, что вы не сможете настроить работу и .NET Framework, и среды выполнения Windows с одним и тем же проектом Visual C++.

Все приложения Магазина Windows, которые вы получаете из Магазина Windows, поставляются в форме пакета приложения. Пакет приложения включает в себя манифест пакета, содержащий информацию о вашем приложении. Например, вы можете указать возможности (то есть требуемый доступ к защищенным системным ресурсам или данным пользователя) вашего приложения. Если вы знаете, что вашему приложению необходимы определенные возможности, используйте манифест пакета для объявления требуемых возможностей. Манифест позволяет также задать свойства проекта, такие как поддерживаемые замены устройств, изображения плиток и экран приветствия. Дополнительные сведения о пакетах приложений см. в разделе Пакеты приложений и развертывание.

Сборка, развертывание и запуск игры

Сборка проекта приложения Магазина Windows происходит аналогично сборке стандартного проекта. В строке меню выберите команды Build (Сборка), Build Solution (Собрать решение). На этапе сборки код компилируется и упаковывается для использования в качестве приложения Магазина Windows.

По завершении сборки проекта его необходимо развернуть. В строке меню выберите команду Build (Сборка), Deploy Solution (Развернуть решение). Visual Studio также разворачивает проект при запуске игры из отладчика.

Развернув проект, выберите плитку Marble Maze для запуска игры. Либо в строке меню Visual Studio выберите команду Debug (Отладка), Start Debugging (Начать отладку).

Управление игрой

Для управления Marble Maze можно использовать сенсорный ввод, акселерометр, контроллер Xbox 360 или мышь.

  • Для изменения активного пункта меню используйте планшет контроллера.
  • Для выбора пункта меню используйте сенсорный ввод, кнопку A, кнопку "Пуск" или мышь.
  • Для наклона лабиринта используйте сенсорный ввод, акселерометр, левый манипулятор или мышь.
  • Для закрытия меню, например таблицы рекордов, используйте сенсорный ввод, кнопку A, кнопку "Пуск" или мышь.
  • Для приостановки и возобновления игры используйте кнопку "Пуск" или клавишу P.
  • Для перезапуска игры используйте кнопку "Назад" на контроллере или клавишу HOME на клавиатуре.
  • Для очистки всех результатов в таблице рекордов используйте кнопку "Назад" или клавишу HOME.

Соглашения, касающиеся кода

Среда выполнения Windows — это интерфейс программирования, который можно использовать для создания приложений Магазина Windows, выполняющихся только в особой среде для приложений. В таких приложениях используются авторизованные функции, типы данных и устройства. Распространяются они через Магазин Windows. На самом низком уровне среда выполнения Windows представляет собой двоичный интерфейс приложения (ABI). ABI — это двоичный контракт низкого уровня, который обеспечивает доступ к API среды выполнения Windows многим языкам программирования, таким как JavaScript, .NET и Visual C++.

Чтобы вызвать API среды выполнения Windows из JavaScript и .NET, этим языкам требуются проекции, специфические для среды каждого языка. Когда вы вызываете API среды выполнения Windows из JavaScript или .NET, вы вызываете проекцию, которая в свою очередь вызывает нижестоящую функцию ABI. Хотя вы можете вызывать функции ABI непосредственно из C++, Майкрософт предоставляет проекции и для C++, так как они значительно упрощают использование API среды выполнения Windows, сохраняя при этом высокую производительность. Майкрософт также предоставляет расширения языка Visual C++, которое поддерживает конкретно проекции среды выполнения Windows. Синтаксис многих из этих расширений похож на синтаксис C++/CLI. Однако вместо обращения к общей среде выполнения языков (CLR) собственные приложения используют для обращения к среде выполнения Windows следующий синтаксис. Модификатор ссылок на объекты (или модификатор ^ ("шляпка")) является важной частью этого нового синтаксиса, постольку он дает возможность автоматически удалять объекты среды выполнения при помощи подсчета ссылок. Вызов методов, таких как AddRef и Release, для управления жизненным циклом объектов среды выполнения Windows не требуется. Среда выполнения удаляет объекты, когда на них не остается ни одной ссылки от других компонентов, например, когда они покидают область или вы устанавливаете для всех ссылок значение nullptr. Другая важная особенность использования Visual C++ для создания приложений Магазина Windows — ключевое слово ref new. Используйте ref new вместо new для создания объектов среды выполнения Windows с подсчетом ссылок. Дополнительные сведения см. в разделе Система типов (C++/CX).

Важно  

При создании объектов или компонентов среды выполнения Windows следует использовать только ^ и ref new. Вы можете использовать стандартный синтаксис C++ при написании основного кода приложения, которое не использует среду выполнения Windows.

Marble Maze использует ^ совместно с Microsoft::WRL::ComPtr, чтобы управлять динамически выделенными объектами и свести к минимуму потери памяти. Мы рекомендуем использовать символ ^ для управления жизненным циклом переменных среды выполнения Windows, ComPtr — для управления жизненным циклом переменных модели COM (например, при использовании DirectX) и std::std::shared_ptr или std::unique_ptr — для управления жизненным циклом всех других динамически выделенных объектов C++.

Дополнительные сведения о расширениях языков, доступных для приложений Магазина Windows на C++, см. в разделе Справочник по языку Visual C++ (C++/CX). Дополнительные сведения об API среды выполнения Windows см. в разделе Справочник по API Windows для приложений Магазина Windows.

Обработка ошибок

В Marble Maze основной метод обработки непредвиденных ошибок — обработка исключений. В коде игр традиционно используются ведение журнала или коды ошибок, например значения HRESULT, для указания на ошибки. В сравнении с этим обработка исключений дает два основных преимущества. Во-первых, она облегчает чтение и поддержку кода. При написании кода удобнее использовать обработку исключений для передачи данных об ошибке в процедуру, которая может обработать эту ошибку. Обычно при использовании кодов ошибок каждая функция должна явно передать данные об ошибках. Во-вторых, вы можете настроить отладчик Visual Studio так, чтобы он прерывался при возникновении исключения, и вы могли бы остановиться непосредственно в расположении и контексте ошибки. Обработка исключений также широко используется в среде выполнения Windows. Таким образом, благодаря использованию исключений в коде вы можете объединить обработку всех ошибок в одной модели.

Мы рекомендуем использовать в вашей модели обработки ошибок следующие соглашения.

  • Используйте исключения для передачи данных о непредвиденных ошибках.
  • Не используйте исключения для управления потоком кода.
  • Захватывайте только те исключения, которые можете безопасно обработать с последующим восстановлением. В ином случае не захватывайте исключение и позвольте приложению завершиться.
  • При вызове процедуры DirectX, которая возвращает HRESULT, используйте функцию DX::ThrowIfFailed. Эта функция определена в DirectXSample.h. ThrowIfFailed вызывает исключение, если переданный HRESULT является кодом ошибки. Например, E_POINTER заставляет ThrowIfFailed вызвать Platform::NullReferenceException.

    Используя ThrowIfFailed, поместите вызов DirectX в отдельную строку для удобочитаемости, как показано в следующем примере.

    
    // Identify the physical adapter (GPU or card) this device is running on.
    ComPtr<IDXGIAdapter> dxgiAdapter;
    DX::ThrowIfFailed(
        dxgiDevice->GetAdapter(&dxgiAdapter)
        );
    
    
    
  • Мы рекомендуем вам избегать использования HRESULT при обработке непредвиденных ошибок, но гораздо важнее избегать использования обработки исключений при управлении потоком кода. Поэтому, когда возникает необходимость управлять потоком кода, предпочтительнее использовать значение, возвращаемое HRESULT.

Аннотации SAL

Использование для обнаружения ошибок в приложении аннотаций SAL совместно со средствами анализа кода.

Используя язык аннотаций исходного кода Microsoft (SAL), вы можете аннотировать (описывать) то, как функция использует свои параметры. Аннотации SAL описывают также возвращаемые значения. Аннотации SAL при выявлении возможных дефектов в исходном коде C и C++ работают совместно со средством C/C++ Code Analysis. Это средство выявляет типичные ошибки кодирования, такие как переполнения буфера, неинициализированную память, разыменование пустых указателей, утечку памяти и ресурсов.

Рассмотрим метод BasicLoader::LoadMesh, заявленный в BasicLoader.h. В этом методе используется параметр _In_ для указания того, что filename — входной параметр (поэтому из него возможно только чтение), _Out_ — для указания того, что vertexBuffer и indexBuffer — выходные параметры (поэтому в них возможна только запись), и _Out_opt_ — для указания того, что vertexCount и indexCount — необязательные выходные параметры (в них возможна запись). Поскольку vertexCount и indexCount являются необязательными выходными параметрами, они могут принимать значение nullptr. Средство C/C++ Code Analysis проверяет вызовы этого метода, чтобы убедиться, что параметры, передаваемые им, удовлетворяют этим критериям.


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


Чтобы выполнить анализ кода вашего приложения, в строке меню выберите команду Build (Сборка), Run Code Analysis on Solution (Выполнить анализ кода решения). Дополнительные сведения об анализе кода см. в разделе Анализ качества кода C/C++ с использованием анализа кода.

Полный перечень возможных аннотаций приведен в sal.h. Дополнительные сведения об Аннотациях SAL.

Следующие действия

Прочтите раздел Структура приложения Marble Maze, чтобы понять, как структурирован код приложения Marble Maze и как структура приложения DirectX для Магазина Windows отличается от структуры традиционного классического приложения.

Связанные разделы

Структура приложения Marble Maze
Разработка Marble Maze, игры Магазина Windows, на C++ и DirectX

 

 

Показ:
© 2014 Microsoft