WinRT in Unreal

In de loop van uw HoloLens-ontwikkeling moet u mogelijk een functie schrijven met behulp van WinRT. Als u bijvoorbeeld een bestandsdialoog wilt openen in een HoloLens-toepassing, hebt u fileSavePicker nodig in het headerbestand winrt/Windows.Storage.Pickers.h. WinRT wordt ondersteund in het buildsysteem van Unreal vanaf versie 4.26.

4.26

De standaard WinRT-API's

De meest voorkomende en eenvoudigste manier om WinRT te gebruiken, is door methoden aan te roepen vanuit WinSDK. Open hiervoor het bestand YourModule.Build.cs en voeg de volgende regels toe:

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

Vervolgens moet u de volgende WinRT-headers toevoegen:

#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-code kan alleen worden gecompileerd op het Win64- en HoloLens-platform, dus de if-instructie voorkomt dat WinRT-bibliotheken worden opgenomen op andere platforms. unknwn.h is toegevoegd voor het hebben van de IUnknown-interface.

WinRT van een NuGet-pakket

Het is iets ingewikkelder als u een NuGet-pakket met WinRT-ondersteuning moet toevoegen. In dit geval kan Visual Studio vrijwel alle taken voor u uitvoeren, maar het Unreal-buildsysteem niet. Gelukkig is het niet zo moeilijk. Hieronder ziet u een voorbeeld van hoe u het pakket Microsoft.MixedReality.QR zou downloaden. U kunt het vervangen door een andere, zorg ervoor dat u het winmd-bestand niet kwijtraakt en kopieer de juiste dll.

Windows SDK-DLL's uit de vorige sectie worden verwerkt door het besturingssysteem. De DLL's van NuGet moeten worden beheerd door de code in uw module. U wordt aangeraden code toe te voegen om deze te downloaden, naar de map met binaire bestanden te kopiëren en bij het opstarten van de module in het procesgeheugen te laden.

In de eerste stap moet u een packages.config (/nuget/reference/packages-config) toevoegen aan de hoofdmap van uw module. Daar moet u alle pakketten toevoegen die u wilt downloaden, inclusief alle bijbehorende afhankelijkheden. Hier heb ik Microsoft.MixedReality.QR toegevoegd als primaire nettolading en twee andere als afhankelijkheden. De indeling van dat bestand is hetzelfde als in 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>

Nu kunt u de NuGet, de vereiste pakketten downloaden of de NuGet-documentatie raadplegen.

Open YourModule.Build.cs en voeg de volgende code toe:

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

U moet de SafeCopy-methode als volgt definiëren:

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's moeten handmatig in uw Win32-procesgeheugen worden geladen; We raden u aan handmatig laden toe te voegen aan de opstartmethode van uw module:

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
}

Ten slotte kunt u WinRT-headers opnemen in uw code, zoals beschreven in de vorige sectie.

4.25

Unreal compileert geen WinRT-code in versie 4.25, dus het is uw taak om een afzonderlijk binair bestand te bouwen dat het buildsysteem van Unreal kan gebruiken.

Doelen

• Een universele Windows-DLL maken waarmee een FileSaveDialoog wordt geopend
• Die DLL koppelen aan een Unreal-gameproject
• Een bestand opslaan op de HoloLens vanuit een Unreal-blauwdruk met behulp van de nieuwe DLL

Aan de slag

1. Controleer of alle vereiste hulpprogramma's zijn geïnstalleerd
2. Maak een nieuw Unreal-project en geef dit de naam Consumewinrt
3. De vereiste invoegtoepassingen inschakelen voor HoloLens-ontwikkeling
4. Instellen voor implementatie op een apparaat of emulator

Een WinRT-DLL maken

1. Open een nieuw Visual Studio-project en maak een DLL-project (Universal Windows) in dezelfde map als het uproject-bestand van de Unreal-game.

2. Geef het project de naam HoloLensWinrtDLL en stel de locatie in als submap ThirdParty in het uproject-bestand van de Unreal-game.
   • Selecteer Oplossing en project in dezelfde map plaatsen om het zoeken naar paden later te vereenvoudigen.

Belangrijk

Nadat het nieuwe project is gecompileerd, moet u speciale aandacht besteden aan de lege cpp- en headerbestanden, met respectievelijk de naam HoloLensWinrtDLL.cpp en HoloLensWinrtDLL.h . De header is het include-bestand dat gebruikmaakt van de DLL in Unreal, terwijl de cpp de hoofdtekst bevat van alle functies die u exporteert en winRT-code bevat die Unreal anders niet zou kunnen compileren.

3. Voordat u code toevoegt, moet u de projecteigenschappen bijwerken om ervoor te zorgen dat de WinRT-code die u nodig hebt, kan compileren:
   • Klik met de rechtermuisknop op het project HoloLensWinrtDLL en selecteer eigenschappen
   • Wijzig de vervolgkeuzelijst Configuratie in Alle configuraties en de vervolgkeuzelijst Platform in Alle platforms
   • Onder Configuratie-eigenschappen> C/C++> Alle opties:
     • Voeg wachten toe aan Aanvullende opties om ervoor te zorgen dat we kunnen wachten op asynchrone taken
     • Wijzig de taalstandaard van C++ in ISO C++17 Standard (/std:c++17) om WinRT-code op te nemen

Uw project is gereed om de bron van de DLL bij te werken met WinRT-code waarmee een bestandsdialoogvenster wordt geopend en een bestand wordt opgeslagen op de HoloLens-schijf.

De DLL-code toevoegen

1. Open HoloLensWinrtDLL.h en voeg een dll-geëxporteerde functie toe voor Unreal om te gebruiken:

#pragma once

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

2. Open HoloLensWinrtDLL.cpp en voeg alle headers toe die door de klasse worden gebruikt:

#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>

Notitie

Alle WinRT-code wordt opgeslagen in HoloLensWinrtDLL.cpp , zodat Unreal geen WinRT-code probeert op te nemen bij het verwijzen naar de header.

3. Voeg in HoloLensWinrtDLL.cpp een functiebody toe voor OpenFileDialogue() en alle ondersteunde code:

// 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. Voeg een SaveGameManager-klasse toe aan HoloLensWinrtDLL.cpp om het bestandsdialoogvenster af te handelen en het bestand op te slaan:

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. Bouw de oplossing voor Release > ARM64 om de DLL te bouwen naar de onderliggende map ARM64/Release/HoloLensWinrtDLL vanuit de DLL-oplossing.

Het binaire WinRT-bestand toevoegen aan Unreal

Voor het koppelen en gebruiken van een DLL in Unreal is een C++-project vereist. Als u een Blauwdrukproject gebruikt, kan dit eenvoudig worden geconverteerd naar een C++-project door een C++-klasse toe te voegen:

1. Open in de Unreal-editor File > New C++ Class... en maak een nieuwe Actor met de naam WinrtActor om de code in het DLL-bestand uit te voeren:

Notitie

Er is nu een oplossing gemaakt in dezelfde map als het uproject-bestand, samen met een nieuw buildscript met de naam Source/ConsumeWinRT/ConsumeWinRT.Build.cs.

2. Open de oplossing, blader naar de map Games/ConsumeWinRT/Source/ConsumeWinRT en open ConsumeWinRT.build.cs:

Het DLL-bestand koppelen

1. Voeg in ConsumeWinRT.build.cs een eigenschap toe om het insluitingspad voor de DLL te vinden (de map met HoloLensWinrtDLL.h). De DLL bevindt zich in een onderliggende map naar het include-pad, dus deze eigenschap wordt gebruikt als de binaire hoofdmap:

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. Voeg in de klasseconstructor de volgende code toe om het include-pad bij te werken, koppel de nieuwe lib, en vertraagd laden en kopieer de DLL naar de verpakte appx-locatie:

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. Open WinrtActor.h en voeg één functiedefinitie toe, een die door een blauwdruk wordt aangeroepen:

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

4. Open WinrtActor.cpp en werk BeginPlay bij om het DLL-bestand te laden:

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
}

Waarschuwing

De DLL moet worden geladen voordat een van de functies wordt aangeroepen.

Het spel bouwen

1. Bouw de gameoplossing om de Unreal-editor te starten die is geopend voor het gameproject:
   • Zoek op het tabblad Actoren plaatsen naar de nieuwe WinrtActor en sleep deze naar de scène
   • Open de blauwdruk op niveau om de aanroepbare functie van de blauwdruk uit te voeren in de WinrtActor

2. Zoek in de World Outliner de WindrtActor die eerder in de scène is neergezet en sleep deze naar de blauwdruk op niveau:

3. Sleep in de blauwdruk op niveau het uitvoerknooppunt van WinrtActor, zoek naar Open File Dialog en routeer het knooppunt vervolgens vanuit gebruikersinvoer. In dit geval wordt Open File Dialogue aangeroepen vanuit een spraakgebeurtenis:

4. Verpak deze game voor HoloLens, implementeer deze en voer uit.

Wanneer Unreal OpenFileDialogue aanroept, wordt er een bestandsdialoog geopend op de HoloLens waarin wordt gevraagd om een .txt bestandsnaam. Nadat het bestand is opgeslagen, gaat u naar het tabblad Verkenner in de apparaatportal om de inhoud 'Hallo WinRT' te bekijken.

Samenvatting

We raden u aan deze zelfstudie te gebruiken als uitgangspunt voor het gebruik van WinRT-code in Unreal wanneer u bestanden moet opslaan op de HoloLens-schijf met behulp van hetzelfde bestandsdialoogvenster als Windows. Hetzelfde proces is van toepassing op het exporteren van extra functies uit de HoloLensWinrtDLL-header en gebruikt in Unreal. Let vooral op de DLL-code die wacht op asynchrone WinRT-code in een MTA-thread op de achtergrond, waardoor de Unreal-gamethread wordt geblokkeerd.

Controlepunt volgende ontwikkeling

Als u het Unreal-ontwikkelingstraject volgt dat we hebben uitgetekend, bent u bezig met het verkennen van de Mixed Reality platformmogelijkheden en API's. Vanaf hier kunt u doorgaan naar een willekeurig onderwerp of direct beginnen met het implementeren van uw app op een apparaat of emulator.

Implementeren op apparaat

Zie ook

• C++/WinRT-API's
• FileSavePicker-klasse
• Unreal-bibliotheken van derden