Unreal 中的 WinRT

在开发 HoloLens 的过程中，可能需要使用 WinRT 编写功能。 例如，在 HoloLens 应用程序中打开文件对话框需要 winrt/Windows.Storage.Pickers.h 标头文件中的 FileSavePicker。 Unreal 的生成系统从版本 4.26 开始支持 WinRT。

4.26

标准 WinRT API

使用 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 库包含在其他平台上。 因为需要 IUnknown 接口，所以添加了 unknwn.h。

NuGet 包中的 WinRT

如果需要添加支持 WinRT 的 NuGet 包，则会稍微复杂一些。 在这种情况下，Visual Studio 可以完成几乎所有工作，但 Unreal 生成系统不能。 还好这并不是很困难。 下面是有关如何下载 Microsoft.MixedReality.QR 包的一个示例。 可以将其替换为其他包，只需确保自己不会丢失 winmd 文件并复制正确的 DLL 即可。

前面部分中 Windows SDK DLL 由 OS 进行处理。 NuGet 的 DLL 必须由模块中的代码进行管理。 建议添加代码来下载这些 DLL，将其复制到二进制文件夹，以及在模块启动时加载到进程内存。

第一步，应将 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);
	}
}

需要手动将 NuGet DLL 加载到 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 在版本 4.25 中不会对 WinRT 代码进行本机编译，因此你需要单独生成一个可供 Unreal 生成系统使用的二进制文件。

目标

• 创建用于打开 FileSaveDialogue 的通用 Windows DLL
• 将该 DLL 链接到 Unreal 游戏项目
• 使用新的 DLL 从 Unreal 蓝图中保存 HoloLens 上的文件

使用入门

1. 检查是否已安装所有必需的工具
2. 创建新的 Unreal 项目，并将其命名为 Consumewinrt
3. 启用 HoloLens 开发所需的插件
4. 完成部署到设备或仿真器的设置

创建 WinRT DLL

1. 打开新的 Visual Studio 项目，并在 Unreal 游戏的 uproject 文件所在的目录中创建一个“DLL (通用 Windows)”项目。

2. 将该项目命名为 HoloLensWinrtDLL，并将位置设置为 Unreal 游戏的 uproject 文件的 ThirdParty 子目录。
   • 选择“将解决方案和项目置于同一目录中”，以简化以后查找路径的过程。

重要

新项目编译完成后，请特别注意名称为 HoloLensWinrtDLL.cpp 的空白 cpp 和名称为 HoloLensWinrtDLL.h 的标头文件。 该标头文件是在 Unreal 中使用 DLL 的 include 文件，而 cpp 包含所导出的任何函数的主体，并且包含 Unreal 无法通过其他途径编译的所有 WinRT 代码。

3. 添加任何代码之前，需要更新项目属性，以确保所需的 WinRT 代码可以编译：
   • 右键单击“HoloLensWinrtDLL”项目并选择“属性”
   • 将“配置”下拉列表更改为“所有配置”，将“平台”下拉列表更改为“所有平台”
   • 在“配置属性”>“C/C++”>“所有选项”下：
     • 将“await”添加到“其他选项”，以确保可以等待异步任务
     • 将“C++ 语言标准”更改为“ISO C++17 标准(/stf:c++17)”以包括任何 WinRT 代码

你的项目已准备好使用 WinRT 代码更新 DLL 的源，代码会打开文件对话框，并将文件保存到 HoloLens 磁盘。

添加 DLL 代码

1. 打开“HoloLensWinrtDLL.h”，并添加供 Unreal 使用的 DLL 导出函数：

#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 解决方案将 DLL 生成到子目录 ARM64/Release/HoloLensWinrtDLL。

向 Unreal 添加 WinRT 二进制文件

在 Unreal 中链接和使用 DLL 需要一个 C++ 项目。 如果使用的是蓝图项目，可以通过添加 C++ 类轻松将其转换为 C++ 项目：

1. 在 Unreal 编辑器中，打开“文件”>“新建 C++ 类…”，并新建一个名为“WinrtActor”的参与者以运行 DLL 中的代码：

注意

现在，已在 uproject 文件所在的目录中创建了解决方案以及名为 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 编辑器：
   • 在“放置参与者”选项卡中，搜索新建的“WinrtActor”，并将其拖放到场景中
   • 打开关卡蓝图，以执行 WinrtActor 中的蓝图可调用函数

2. 在“世界大纲视图”中，找到之前拖放到场景中的“WindrtActor”，并将其拖动到关卡蓝图：

3. 在关卡蓝图中，从 WinrtActor 拖动输出节点，并搜索“打开文件对话框”，然后通过任何用户输入路由该节点。 在本例中，我们通过语音事件调用“打开文件对话框”：

4. 为 HoloLens 打包此游戏，完成部署，然后运行。

当 Unreal 调用 OpenFileDialogue 时，系统会在 HoloLens 上打开一个文件对话框，提示输入 .txt 文件名。 保存该文件后，在设备门户中转到“文件资源管理器”选项卡，可看到内容“Hello WinRT”。

总结

如果需要使用与 Windows 相同的文件对话框将文件保存到 HoloLens 磁盘，建议将本教程作为在 Unreal 中使用 WinRT 代码的基础。 若要从 HoloLensWinrtDLL 标头文件导出其他函数，可以采用相同的过程，该过程也在 Unreal 中使用。 请特别注意在后台 MTA 线程中等待异步 WinRT 代码的 DLL 代码，以避免 Unreal 游戏线程出现死锁。

下一个开发检查点

如果你遵循我们规划的 Unreal 开发历程，则你处于探索混合现实平台功能和 API 的过程之中。 从这里，你可以继续了解任何主题或直接跳到在设备或仿真器上部署应用。

部署到设备

另请参阅

• C++/WinRT API
• FileSavePicker 类
• Unreal 第三方库