WinRT в Unreal

В ходе разработки HoloLens может потребоваться написать функцию с помощью WinRT. Например, для открытия диалогового окна файла в приложении HoloLens потребуется файл FileSavePicker в файле заголовка winrt/Windows.Storage.Pickers.h. WinRT поддерживается в системе сборки Unreal начиная с версии 4.26.

4.26

Стандартные API-интерфейсы WinRT

Наиболее распространенным и простым способом использования WinRT является вызов методов из WinSDK. Для этого откройте файл YourModule.Build.cs и добавьте следующие строки:

if (Target.Platform == UnrealTargetPlatform.Win64 || Target.Platform == UnrealTargetPlatform.HoloLens)
{
	// These parameters are mandatory for winrt support
	bEnableExceptions = true;
	bUseUnity = false;
	CppStandard = CppStandardVersion.Cpp17;
	PublicSystemLibraries.AddRange(new string[] { "shlwapi.lib", "runtimeobject.lib" });
	PrivateIncludePaths.Add(Path.Combine(Target.WindowsPlatform.WindowsSdkDir,        
                                        "Include", 
                                        Target.WindowsPlatform.WindowsSdkVersion, 
                                        "cppwinrt"));
}

Далее необходимо добавить следующие заголовки WinRT:

#if (PLATFORM_WINDOWS || PLATFORM_HOLOLENS) 
//Before writing any code, you need to disable common warnings in WinRT headers
#pragma warning(disable : 5205 4265 4268 4946)

#include "Windows/AllowWindowsPlatformTypes.h"
#include "Windows/AllowWindowsPlatformAtomics.h"
#include "Windows/PreWindowsApi.h"

#include <unknwn.h>
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Perception.Spatial.h>
#include <winrt/Windows.Foundation.Collections.h>

#include "Windows/PostWindowsApi.h"
#include "Windows/HideWindowsPlatformAtomics.h"
#include "Windows/HideWindowsPlatformTypes.h"
#endif

Код WinRT можно скомпилировать только на платформах Win64 и HoloLens, поэтому инструкция if предотвращает включение библиотек WinRT на другие платформы. Добавлен unknwn.h для интерфейса IUnknown.

WinRT из пакета NuGet

Это немного сложнее, если вам нужно добавить пакет NuGet с поддержкой WinRT. В этом случае Visual Studio может выполнять практически все задачи за вас, а система сборки Unreal — нет. К счастью, это не так сложно. Ниже приведен пример скачивания пакета Microsoft.MixedReality.QR. Вы можете заменить его другим, просто убедитесь, что вы не потеряете winmd-файл и скопируйте правильную библиотеку DLL.

Dll-файлы windows SDK из предыдущего раздела обрабатываются операционной системой. Dll-файлами NuGet должен управлять код в модуле. Рекомендуется добавить код для их скачивания, копирования в папку двоичных файлов и загрузки в память процесса при запуске модуля.

На первом шаге необходимо добавить packages.config (/nuget/reference/packages-config) в корневую папку модуля. В нее необходимо добавить все пакеты, которые вы хотите скачать, включая все их зависимости. Здесь я добавил Microsoft.MixedReality.QR в качестве основной полезной нагрузки и два других в качестве зависимостей к нему. Формат этого файла совпадает с форматом в Visual Studio:

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Microsoft.MixedReality.QR" version="0.5.2102" targetFramework="native" />
  <package id="Microsoft.VCRTForwarders.140" version="1.0.6" targetFramework="native" />
  <package id="Microsoft.Windows.CppWinRT" version="2.0.200729.8" targetFramework="native" />
</packages>

Теперь вы можете скачать NuGet, необходимые пакеты или обратиться к документации NuGet.

Откройте Файл YourModule.Build.cs и добавьте следующий код:

// WinRT with Nuget support
if (Target.Platform == UnrealTargetPlatform.Win64 || Target.Platform == UnrealTargetPlatform.HoloLens)
{
	// these parameters mandatory for winrt support
	bEnableExceptions = true;
	bUseUnity = false;
	CppStandard = CppStandardVersion.Cpp17;
	PublicSystemLibraries.AddRange(new string [] { "shlwapi.lib", "runtimeobject.lib" });

	// prepare everything for nuget
	string MyModuleName = GetType().Name;
	string NugetFolder = Path.Combine(PluginDirectory, "Intermediate", "Nuget", MyModuleName);
	Directory.CreateDirectory(NugetFolder);

	string BinariesSubFolder = Path.Combine("Binaries", "ThirdParty", Target.Type.ToString(), Target.Platform.ToString(), Target.Architecture);

	PrivateDefinitions.Add(string.Format("THIRDPARTY_BINARY_SUBFOLDER=\"{0}\"", BinariesSubFolder.Replace(@"\", @"\\")));

	string BinariesFolder = Path.Combine(PluginDirectory, BinariesSubFolder);
	Directory.CreateDirectory(BinariesFolder);

	ExternalDependencies.Add("packages.config");

	// download nuget
	string NugetExe = Path.Combine(NugetFolder, "nuget.exe");
	if (!File.Exists(NugetExe))
	{
		using (System.Net.WebClient myWebClient = new System.Net.WebClient())
		{
			// we aren't focusing on a specific nuget version, we can use any of them but the latest one is preferable
			myWebClient.DownloadFile(@"https://dist.nuget.org/win-x86-commandline/latest/nuget.exe", NugetExe);
		}
	}

	// run nuget to update the packages
	{
		var StartInfo = new System.Diagnostics.ProcessStartInfo(NugetExe, string.Format("install \"{0}\" -OutputDirectory \"{1}\"", Path.Combine(ModuleDirectory, "packages.config"), NugetFolder));
		StartInfo.UseShellExecute = false;
		StartInfo.CreateNoWindow = true;
		var ExitCode = Utils.RunLocalProcessAndPrintfOutput(StartInfo);
		if (ExitCode < 0)
		{
			throw new BuildException("Failed to get nuget packages.  See log for details.");
		}
	}

	// get list of the installed packages, that's needed because the code should get particular versions of the installed packages
	string[] InstalledPackages = Utils.RunLocalProcessAndReturnStdOut(NugetExe, string.Format("list -Source \"{0}\"", NugetFolder)).Split(new char[] { '\r', '\n' });

	// winmd files of the packages
	List<string> WinMDFiles = new List<string>();

	// WinRT lib for some job
	string QRPackage = InstalledPackages.FirstOrDefault(x => x.StartsWith("Microsoft.MixedReality.QR"));
	if (!string.IsNullOrEmpty(QRPackage))
	{
		string QRFolderName = QRPackage.Replace(" ", ".");

		// copying dll and winmd binaries to our local binaries folder
		// !!!!! please make sure that you use the path of file! Unreal can't do it for you !!!!!
		string WinMDFile = Path.Combine(NugetFolder, QRFolderName, @"lib\uap10.0.18362\Microsoft.MixedReality.QR.winmd");
		SafeCopy(WinMDFile, Path.Combine(BinariesFolder, "Microsoft.MixedReality.QR.winmd"));

		SafeCopy(Path.Combine(NugetFolder, QRFolderName, string.Format(@"runtimes\win10-{0}\native\Microsoft.MixedReality.QR.dll", Target.WindowsPlatform.Architecture.ToString())),
			Path.Combine(BinariesFolder, "Microsoft.MixedReality.QR.dll"));

		// also both both binaries must be in RuntimeDependencies, unless you get failures in Hololens platform
		RuntimeDependencies.Add(Path.Combine(BinariesFolder, "Microsoft.MixedReality.QR.dll"));
		RuntimeDependencies.Add(Path.Combine(BinariesFolder, "Microsoft.MixedReality.QR.winmd"));

		//add winmd file to the list for further processing using cppwinrt.exe
		WinMDFiles.Add(WinMDFile);
	}

	if (Target.Platform == UnrealTargetPlatform.Win64)
	{
		// Microsoft.VCRTForwarders.140 is needed to run WinRT dlls in Win64 platforms
		string VCRTForwardersPackage = InstalledPackages.FirstOrDefault(x => x.StartsWith("Microsoft.VCRTForwarders.140"));
		if (!string.IsNullOrEmpty(VCRTForwardersPackage))
		{
			string VCRTForwardersName = VCRTForwardersPackage.Replace(" ", ".");
			foreach (var Dll in Directory.EnumerateFiles(Path.Combine(NugetFolder, VCRTForwardersName, "runtimes/win10-x64/native/release"), "*_app.dll"))
			{
				string newDll = Path.Combine(BinariesFolder, Path.GetFileName(Dll));
				SafeCopy(Dll, newDll);
				RuntimeDependencies.Add(newDll);
			}
		}
	}

	// get WinRT package 
	string CppWinRTPackage = InstalledPackages.FirstOrDefault(x => x.StartsWith("Microsoft.Windows.CppWinRT"));
	if (!string.IsNullOrEmpty(CppWinRTPackage))
	{
		string CppWinRTName = CppWinRTPackage.Replace(" ", ".");
		string CppWinRTExe = Path.Combine(NugetFolder, CppWinRTName, "bin", "cppwinrt.exe");
		string CppWinRTFolder = Path.Combine(PluginDirectory, "Intermediate", CppWinRTName, MyModuleName);
		Directory.CreateDirectory(CppWinRTFolder);

		// all downloaded winmd file with WinSDK to be processed by cppwinrt.exe
		var WinMDFilesStringbuilder = new System.Text.StringBuilder();
		foreach (var winmd in WinMDFiles)
		{
			WinMDFilesStringbuilder.Append(" -input \"");
			WinMDFilesStringbuilder.Append(winmd);
			WinMDFilesStringbuilder.Append("\"");
		}

		// generate winrt headers and add them into include paths
		var StartInfo = new System.Diagnostics.ProcessStartInfo(CppWinRTExe, string.Format("{0} -input \"{1}\" -output \"{2}\"", WinMDFilesStringbuilder, Target.WindowsPlatform.WindowsSdkVersion, CppWinRTFolder));
		StartInfo.UseShellExecute = false;
		StartInfo.CreateNoWindow = true;
		var ExitCode = Utils.RunLocalProcessAndPrintfOutput(StartInfo);
		if (ExitCode < 0)
		{
			throw new BuildException("Failed to get generate WinRT headers.  See log for details.");
		}

		PrivateIncludePaths.Add(CppWinRTFolder);
	}
	else
	{
		// fall back to default WinSDK headers if no winrt package in our list
		PrivateIncludePaths.Add(Path.Combine(Target.WindowsPlatform.WindowsSdkDir, "Include", Target.WindowsPlatform.WindowsSdkVersion, "cppwinrt"));
	}
}

Необходимо определить метод SafeCopy следующим образом:

private void SafeCopy(string source, string destination)
{
	if(!File.Exists(source))
	{
		Log.TraceError("Class {0} can't find {1} file for copying", this.GetType().Name, source);
		return;
	}

	try
	{
		File.Copy(source, destination, true);
	}
	catch(IOException ex)
	{
		Log.TraceWarning("Failed to copy {0} to {1} with exception: {2}", source, destination, ex.Message);
		if (!File.Exists(destination))
		{
			Log.TraceError("Destination file {0} does not exist", destination);
			return;
		}

		Log.TraceWarning("Destination file {0} already existed and is probably in use.  The old file will be used for the runtime dependency.  This may happen when packaging a Win64 exe from the editor.", destination);
	}
}

Библиотеки DLL NuGet должны загружаться в память процесса Win32 вручную; Мы рекомендуем добавить загрузку вручную в метод запуска модуля:

void StartupModule() override
{
#if PLATFORM_WINDOWS
	const FString LibrariesDir = FPaths::ProjectPluginsDir() / "MyModule" / THIRDPARTY_BINARY_SUBFOLDER;
	FPlatformProcess::PushDllDirectory(*LibrariesDir);

	const FString DllName = "Microsoft.MixedReality.QR.dll";
	if (!FPlatformProcess::GetDllHandle(*DllName))
	{
		UE_LOG(LogHMD, Warning, TEXT("Dll \'%s\' can't be loaded from \'%s\'"), *DllName, *LibrariesDir);
	}

	FPlatformProcess::PopDllDirectory(*LibrariesDir);
#endif
}

Наконец, можно включить заголовки WinRT в код, как описано в предыдущем разделе.

4.25

Unreal не компилирует изначально код WinRT в версии 4.25, поэтому ваша задача — создать отдельный двоичный файл, который может использовать система сборки Unreal.

Задачи

• Создание универсальной библиотеки DLL Windows, которая открывает FileSaveDialogue
• Связывание этой библиотеки DLL с проектом игры Unreal
• Сохранение файла в HoloLens из схемы Unreal с помощью новой библиотеки DLL

Начало работы

1. Убедитесь, что установлены все необходимые средства .
2. Создайте проект Unreal и присвойте ему имя Consumewinrt
3. Включение необходимых подключаемых модулей для разработки HoloLens
4. Настройка развертывания на устройстве или эмуляторе

Создание библиотеки DLL WinRT

1. Откройте новый проект Visual Studio и создайте проект DLL (универсальной версии Windows) в том же каталоге, что и файл создания игры Unreal.

2. Присвойте проекту имя HoloLensWinrtDLL и задайте расположение в качестве подкаталога ThirdParty для файла проекта unreal's uproject.
   • Выберите Поместить решение и проект в один каталог , чтобы упростить поиск путей позже.

Важно!

После компиляции нового проекта уделите особое внимание пустым файлам CPP и файлам заголовков с именами HoloLensWinrtDLL.cpp и HoloLensWinrtDLL.h соответственно. Заголовок — это включаемый файл, который использует библиотеку DLL в Unreal, а cpp содержит текст экспортируемых функций и содержит любой код WinRT, который Unreal не смог бы скомпилировать в противном случае.

3. Перед добавлением кода необходимо обновить свойства проекта, чтобы убедиться, что необходимый код WinRT может компилироваться:
   • Щелкните правой кнопкой мыши проект HoloLensWinrtDLL и выберите свойства.
   • Измените раскрывающийся список Конфигурация на Все конфигурации, а в раскрывающемся списке Платформа — на Все платформы.
   • В разделе Свойства> конфигурации C/C++> Все параметры:
     • Добавьте await в дополнительные параметры , чтобы мы могли ждать асинхронных задач.
     • Измените стандарт языка C++ на стандарт ISO C++17 (/std:c++17), чтобы включить любой код WinRT.

Проект готов к обновлению источника БИБЛИОТЕКи DLL с помощью кода WinRT, который открывает диалоговое окно файла и сохраняет файл на диск HoloLens.

Добавление кода DLL

1. Откройте HoloLensWinrtDLL.h и добавьте экспортированную функцию DLL для Unreal для использования:

#pragma once

class HoloLensWinrtDLL
{
public:
    _declspec(dllexport) static void OpenFileDialogue();
};

2. Откройте HoloLensWinrtDLL.cpp и добавьте все заголовки, которые будет использовать класс:

#include "pch.h"
#include "HoloLensWinrtDLL.h"

#include <winrt/Windows.Storage.h>
#include <winrt/Windows.Storage.Streams.h>
#include <winrt/Windows.Storage.Pickers.h>
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Foundation.Collections.h>

#include <string>
#include <vector>
#include <thread>

Примечание

Весь код WinRT хранится в HoloLensWinrtDLL.cpp, поэтому Unreal не пытается включить код WinRT при ссылке на заголовок.

3. В HoloLensWinrtDLL.cpp добавьте текст функции для OpenFileDialogue() и всего поддерживаемого кода:

// sgm is declared outside of OpenFileDialogue so it doesn't
// get destroyed when OpenFileDialogue goes out of scope.
SaveGameManager sgm;

void HoloLensWinrtDLL::OpenFileDialogue()
{
    sgm.SaveGame();
}

4. Добавьте класс SaveGameManager в HoloLensWinrtDLL.cpp для обработки диалогового окна файла и сохранения файла:

class SaveGameManager
{
public:
    SaveGameManager()
    {
    }

    ~SaveGameManager()
    {
        // Wait for currently running thread to complete before terminating.
        if(m_thread.joinable())
        {
            m_thread.join();
        }
    }

    void SaveGame()
    {
        OpenFileDialogueAction();
    }

private:
    winrt::Windows::Storage::StorageFile m_file = winrt::Windows::Storage::StorageFile(nullptr);
    std::thread m_thread;

    winrt::Windows::Foundation::IAsyncAction OpenFileDialogueAction()
    {
        std::vector<winrt::hstring> extensions;
        extensions.push_back(L".txt");

        auto picker = winrt::Windows::Storage::Pickers::FileSavePicker();

        // FileSavePicker needs a file type to open without errors.
        picker.FileTypeChoices().Insert(L"Plain Text",
                                        winrt::single_threaded_vector<winrt::hstring>(
                                        std::move(extensions)));

        // Opening the FilePicker must be done on the Game UI thread.
        // Any other IAsyncOperations should be done on a background thread.
        m_file = co_await picker.PickSaveFileAsync();

        if(m_file)
        {
            // Unreal's game thread is an STA, async tasks need to run on
            // a background MTA thread, or waiting on them will deadlock.    
            std::thread thread([this]() { RunThread(); });
            m_thread = std::move(thread);
        }
    }

    void RunThread()
    {
        // Ensure this thread is an MTA
        winrt::init_apartment();
        Run().get();
    }

    winrt::Windows::Foundation::IAsyncAction Run()
    {
        co_await winrt::Windows::Storage::FileIO::WriteTextAsync(
                m_file, L"Hello WinRT");
    }
};

5. Выполните сборку решения для выпуска > ARM64 , чтобы выполнить сборку библиотеки DLL в дочернем каталоге ARM64/Release/HoloLensWinrtDLL из решения DLL.

Добавление двоичного файла WinRT в Unreal

Для связывания и использования библиотеки DLL в Unreal требуется проект C++. Если вы используете проект Blueprint, его можно легко преобразовать в проект C++, добавив класс C++:

1. В редакторе Unreal откройте файл > Новый класс C++ и создайте субъектс именем WinrtActor для выполнения кода в библиотеке DLL:

Примечание

Решение теперь создано в том же каталоге, что и файл проекта, а также новый скрипт сборки с именем Source/ConsumeWinRT/ConsumeWinRT.Build.cs.

2. Откройте решение, найдите папку Games/ConsumeWinRT/Source/ConsumeWinRT и откройте Файл ConsumeWinRT.build.cs:

Связывание библиотеки DLL

1. В Файле ConsumeWinRT.build.cs добавьте свойство , чтобы найти путь включения для библиотеки DLL (каталог, содержащий HoloLensWinrtDLL.h). Библиотека DLL находится в дочернем каталоге для пути включения, поэтому это свойство будет использоваться в качестве двоичного корневого каталога:

using System.IO;

public class ConsumeWinRT : ModuleRules
{
    private string WinrtIncPath
    {
        get 
        {
            string ModulePath = Path.GetDirectoryName(
                   RulesCompiler.GetFileNameFromType(this.GetType()));

            // Third party directory is at the project root,
            // which is two directories up from the game .exe (Binaries/HoloLens)
            return Path.GetFullPath(
                   Path.Combine(ModulePath,
                   "../../ThirdParty/HoloLensWinrtDLL"));
        }
    }
}

2. В конструкторе класса добавьте следующий код для обновления пути включения, связывания новой библиотеки и задержки загрузки и копирования библиотеки DLL в расположение упаковаемого appx:

public ConsumeWinRT(ReadOnlyTargetRules target) : base(Target)
{
    // This is the directory the DLL's include header is in.
    PublicIncludePaths.Add(WinrtIncPath);

    // The code in HoloLensWinrtDLL will only work in a Windows Store app.
    // Only link these binaries for HoloLens.
    // Similar code can be written for desktop and similarly linked 
    // to use the same features when using Holographic Remoting.
    if(Target.Platform == UnrealTargetPlatform.HoloLens)
    {
        // Link the lib
        PublicAdditionalLibraries.Add(Path.Combine(
              WinrtIncPath, "ARM64", "Release",
              "HoloLensWinrtDLL","HoloLensWinrtDLL.lib"));

        string winrtDLL = "HoloLensWinrtDLL.dll";
        // Mark the dll to be DelayLoaded
        PublicDelayLoadDLLs.Add(winrtDLL);
        // RuntimeDependencies are included in packaged builds.
        RuntimeDependencies.Add(Path.Combine(WinrtIncPath,
                "ARM64", "Release", "HoloLensWinrtDLL", winrtDLL));
    }

    // Preserve the original code in build.cs below:
}

3. Откройте WinrtActor.h и добавьте одно определение функции, которое будет вызываться схемой:

public:
    UFUNCTION(BlueprintCallable)
    static void OpenFileDialogue();

4. Откройте WinrtActor.cpp и обновите BeginPlay, чтобы загрузить библиотеку DLL:

void AWinrtActor::BeginPlay()
{
	Super::BeginPlay();

    // Gets path to DLL location
	const FString BinDir = FPaths::ProjectDir() / 
		"ThirdParty" / "HoloLensWinrtDLL" / 
		"arm64" / "Release" / "HoloLensWinrtDLL";

    // Loads DLL into application
	void * dllHandle = FPlatformProcess::GetDllHandle(
		*(BinDir / "HoloLensWinrtDLL.dll"));
}

void AWinrtActor::OpenFileDialogue()
{
#if PLATFORM_HOLOLENS
	HoloLensWinrtDLL::OpenFileDialogue();
#endif
}

Внимание!

Библиотека DLL должна быть загружена перед вызовом любой из ее функций.

Построение игры

1. Создайте игровое решение, чтобы запустить редактор Unreal, открытый для игрового проекта:
   • На вкладке Place Actors найдите новый WinrtActor и перетащите его в сцену.
   • Откройте схему уровня, чтобы выполнить вызываемую функцию схемы в WinrtActor.

2. В World Outliner найдите WindrtActor , ранее сохраненный в сцене, и перетащите его в схему уровня:

3. В схеме уровня перетащите выходной узел из WinrtActor, выполните поиск по запросу Открыть диалоговое окно файла, а затем перенаправьте узел из любых введенных пользователем данных. В этом случае диалоговое окно "Открыть файл" вызывается из события речи:

4. Упакуйте эту игру для HoloLens, разверните ее и запустите.

Когда Unreal вызывает OpenFileDialogue, на устройстве HoloLens открывается диалоговое окно с запросом на ввод имени файла .txt. После сохранения файла перейдите на вкладку Проводник на портале устройства, чтобы просмотреть содержимое "Hello WinRT".

Сводка

Мы рекомендуем использовать этот учебник в качестве отправной точки для использования кода WinRT в Unreal, если вам нужно сохранить файлы на диск HoloLens с помощью того же диалогового окна файлов, что и Windows. Этот же процесс применяется к экспорту дополнительных функций из заголовка HoloLensWinrtDLL и используемых в Unreal. Обратите особое внимание на код DLL, который ожидает асинхронный код WinRT в фоновом потоке MTA, что позволяет избежать взаимоблокировки игрового потока Unreal.

Следующий этап разработки

Если вы следуете изложенной нами стратегии разработки для Unreal, вы как раз прошли половину в изучении возможностей и API платформы Смешанной реальности. Здесь вы можете перейти к любой теме или перейти непосредственно к развертыванию приложения на устройстве или эмуляторе.

Развертывание на устройстве

См. также раздел

• API C++/WinRT
• Класс FileSavePicker
• Сторонние библиотеки Unreal