Unreal 中的 WinRT

發行項
07/12/2023

在 HoloLens 開發過程中，您可能需要使用 WinRT 撰寫功能。例如，在 HoloLens 應用程式中開啟檔案對話需要 winrt/Windows.Storage.Pickers.h 標頭檔中的 FileSavePicker。從 4.26 版起，Unreal 的組建系統支援 WinRT。

4.26
4.25

標準 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 程式庫包含在其他平臺上。已新增 unknwn.h 以擁有 IUnknown 介面。

NuGet 套件的 WinRT

如果您需要新增具有 WinRT 支援的 NuGet 套件，則比較複雜。在此情況下，Visual Studio 可以為您執行幾乎所有工作，但 Unreal 建置系統無法執行。幸運的是，這不是太困難。以下是如何下載 Microsoft.MixedReality.QR 套件的範例。您可以將它取代為另一個，只要確定您不會遺失 winmd 檔案，並複製正確的 dll。

上一節的 Windows SDK dll 是由 OS 處理。 NuGet 的 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 標頭包含在程式碼中，如上一節所述。

Unreal 不會在 4.25 版中原生編譯 WinRT 程式碼，因此您的工作是建置 Unreal 建置系統可取用的個別二進位檔。

目標

建立開啟 FileSaveDialogue 的通用 Windows DLL
將該 DLL 連結到 Unreal 遊戲專案
使用新的 DLL，從 Unreal 藍圖將檔案儲存在 HoloLens 上

開始使用

確認您已安裝所有必要的工具
建立新的 Unreal 專案並將其命名為 Consumewinrt
啟用 HoloLens 開發所需的外掛程式
部署至裝置或模擬器的設定

建立 WinRT DLL

開啟新的 Visual Studio 專案，並在與 Unreal 遊戲uproject檔案相同的目錄中建立DLL (Universal Windows) 專案。

建立 DLL

將專案命名為 HoloLensWinrtDLL ，並將位置設定為 Unreal 遊戲 uproject 檔案的 ThirdParty 子目錄。
- 選取 [將方案與專案放在相同的目錄中 ]，以簡化稍後尋找路徑。

設定 DLL

重要

在新專案編譯之後，請特別留意名為 HoloLensWinrtDLL.cpp 和 HoloLensWinrtDLL.h 的空白 cpp 和標頭檔。標頭是使用 Unreal 中 DLL 的 Include 檔案，而 cpp 會保存您匯出之任何函式的主體，並包含 Unreal 無法編譯的任何 WinRT 程式碼。

新增任何程式碼之前，您必須更新專案屬性，以確保您可以編譯所需的 WinRT 程式碼：
- 以滑鼠右鍵按一下 HoloLensWinrtDLL 專案，然後選取屬性
- 將 [ 設定 ] 下拉式清單變更為 [所有 設定]，並將 [ 平臺 ] 下拉式清單變更為 [所有平臺]
- 在 [ 組態屬性 > C/C++] 底下 > ，所有選項：
  - 將 await 新增至 其他選項 ，以確保我們可以等候非同步工作
  - 將 C++ 語言標準 變更為 ISO C++17 Standard (/std：c++17) 以包含任何 WinRT 程式碼

升級專案屬性

您的專案已準備好使用 WinRT 程式碼更新 DLL 的來源，以開啟檔案對話方塊，並將檔案儲存至 HoloLens 磁片。

新增 DLL 程式碼

開啟 HoloLensWinrtDLL.h ，並為 Unreal 新增 dll 匯出的函式以取用：

#pragma once

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

開啟 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 程式碼。

仍在 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();
}

將 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");
    }
};

建置 Release > ARM64 的解決方案，以從 DLL 解決方案將 DLL 建置至子目錄 ARM64/Release/HoloLensWinrtDLL。

將 WinRT 二進位檔新增至 Unreal

在 Unreal 中連結和使用 DLL 需要 C++ 專案。如果您使用 Blueprint 專案，可以藉由新增 C++ 類別輕鬆地轉換成 C++ 專案：

在 Unreal 編輯器中，開啟[檔案 > 新 C++ 類別...]，然後建立名為WinrtActor的新動作專案，以在 DLL 中執行程式碼：

建立新的動作專案

注意

解決方案現在已建立于與 uproject 檔案相同的目錄中，以及名為 Source/ConsumeWinRT/ConsumeWinRT.Build.cs 的新組建腳本。

開啟方案，流覽 Games/ConsumeWinRT/Source/ConsumeWinRT 資料夾，然後開啟 ConsumeWinRT.build.cs：

開啟 ConsumeWinRT.build.cs 檔案

連結 DLL

在 ConsumeWinRT.build.cs中，新增屬性以尋找 DLL 的 include 路徑， (包含 HoloLensWinrtDLL.h 的目錄) 。 DLL 位於包含路徑的子目錄中，因此這個屬性將用來作為二進位根目錄的 dir：

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"));
        }
    }
}

在類別建構函式中，新增下列程式碼以更新 include 路徑、連結新的 lib，以及延遲載入並將 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:
}

開啟 WinrtActor.h 並新增一個函式定義，其中一個藍圖會呼叫：

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

開啟 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。

建置遊戲

建置遊戲方案，以啟動開啟至遊戲專案的 Unreal 編輯器：
- 在 [ 放置動作專案 ] 索引標籤中，搜尋新的 WinrtActor 並將它拖曳至場景
- 開啟層級藍圖，以在WinrtActor中執行藍圖可呼叫函式

將 WinrtActor 放在場景中

在 World Outliner中，尋找先前放入場景的 WindrtActor ，並將其拖曳至層級藍圖：

將 WinrtActor 拖曳至層級藍圖

在層級藍圖中，從 WinrtActor 拖曳輸出節點，搜尋 [開啟檔案對話]，然後從任何使用者輸入路由傳送節點。在此情況下，會從語音事件呼叫 Open File Dialogue：

在層級藍圖中設定節點

將此遊戲封裝為 HoloLens、部署並執行。

當 Unreal 呼叫 OpenFileDialogue 時，會在 HoloLens 上開啟檔案對話，提示輸入.txt檔案名。儲存檔案之後，請移至裝置入口網站中的 [ 檔案總管] 索引標籤，以查看內容「Hello WinRT」。

摘要

當您需要使用與 Windows 相同的檔案對話，將檔案儲存至 HoloLens 磁片時，建議您使用本教學課程作為在 Unreal 中使用 WinRT 程式碼的起點。相同的程式適用于從 HoloLensWinrtDLL 標頭匯出其他函式，並用於 Unreal。請特別注意在背景 MTA 執行緒中等候非同步 WinRT 程式碼的 DLL 程式碼，以避免將 Unreal 遊戲執行緒死結。

下一個開發檢查點

依循我們配置的 Unreal 開發旅程，此時您會探索混合實境平台功能和 API。您可以從這裡繼續任何主題，或直接跳到在裝置或模擬器上部署應用程式。

部署至裝置

共用方式為