WinRT dans Unreal

Au cours de votre développement HoloLens, vous devrez peut-être écrire une fonctionnalité à l’aide de WinRT. Par exemple, l’ouverture d’une boîte de dialogue de fichier dans une application HoloLens nécessite le fichier d’en-tête FileSavePicker dans winrt/Windows.Storage.Pickers.h. WinRT est pris en charge dans le système de build d’Unreal à partir de la version 4.26.

4.26

API WinRT standard

Le moyen le plus courant et le plus simple d’utiliser WinRT consiste à appeler des méthodes à partir de WinSDK. Pour ce faire, ouvrez le fichier YourModule.Build.cs et ajoutez les lignes suivantes :

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

Ensuite, vous devez ajouter les en-têtes WinRT suivants :

#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

Le code WinRT ne peut être compilé que sur les plateformes Win64 et HoloLens, de sorte que l’instruction if empêche l’inclusion des bibliothèques WinRT sur d’autres plateformes. unknwn.h a été ajouté pour avoir l’interface IUnknown.

WinRT à partir d’un package NuGet

C’est un peu plus compliqué si vous devez ajouter un package NuGet avec la prise en charge de WinRT. Dans ce cas, Visual Studio peut effectuer pratiquement tout le travail pour vous, mais pas le système de build Unreal. Heureusement, ce n’est pas trop difficile. Voici un exemple de la façon dont vous souhaitez télécharger le package Microsoft.MixedReality.QR. Vous pouvez le remplacer par un autre. Assurez-vous simplement que vous ne perdez pas le fichier winmd et copiez la dll correcte.

Les dll du Kit de développement logiciel (SDK) Windows de la section précédente sont gérées par le système d’exploitation. Les dll de NuGet doivent être gérées par le code de votre module. Nous vous recommandons d’ajouter du code pour les télécharger, de les copier dans le dossier binaires et de charger dans la mémoire du processus au démarrage du module.

À la première étape, vous devez ajouter un packages.config (/nuget/reference/packages-config) dans le dossier racine de votre module. Vous devez y ajouter tous les packages que vous souhaitez télécharger, y compris toutes leurs dépendances. Ici, j’ai ajouté Microsoft.MixedReality.QR comme charge utile principale et deux autres en tant que dépendances. Le format de ce fichier est le même que dans 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>

Vous pouvez maintenant télécharger nuGet, les packages requis, ou consulter la documentation NuGet.

Ouvrez YourModule.Build.cs et ajoutez le code suivant :

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

Vous devez définir la méthode SafeCopy comme suit :

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

Les DLL NuGet doivent se charger manuellement dans la mémoire de votre processus Win32 ; nous vous recommandons d’ajouter le chargement manuel dans la méthode de démarrage de votre 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
}

Enfin, vous pouvez inclure des en-têtes WinRT dans votre code, comme décrit dans la section précédente.

4.25

Unreal ne compile pas en mode natif le code WinRT dans la version 4.25. Il vous faut donc créer un binaire distinct que le système de build d’Unreal peut utiliser.

Objectifs

• Créer une DLL Windows universelle qui ouvre un FileSaveDialogue
• Lier cette DLL à un projet de jeu Unreal
• Enregistrer un fichier sur HoloLens à partir d’un blueprint Unreal à l’aide de la nouvelle DLL

Prise en main

1. Vérifiez que tous les outils requis sont installés
2. Créer un projet Unreal et le nommer Consumewinrt
3. Activer les plug-ins requis pour le développement HoloLens
4. Configuration pour le déploiement sur un appareil ou un émulateur

Création d’une DLL WinRT

1. Ouvrez un nouveau projet Visual Studio et créez un projet DLL (Windows universel) dans le même répertoire que le fichier uproject du jeu Unreal.

2. Nommez le projet HoloLensWinrtDLL et définissez l’emplacement en tant que sous-répertoire ThirdParty sur le fichier uproject du jeu Unreal.
   • Sélectionnez Placer la solution et projeter dans le même répertoire pour simplifier la recherche de chemins d’accès ultérieurement.

Important

Une fois le nouveau projet compilé, portez une attention particulière aux fichiers cpp et d’en-tête vides, nommés Respectivement HoloLensWinrtDLL.cpp et HoloLensWinrtDLL.h . L’en-tête est le fichier include qui utilise la DLL dans Unreal, tandis que le cpp contient le corps de toutes les fonctions que vous exportez et inclut tout code WinRT que Unreal ne serait pas en mesure de compiler autrement.

3. Avant d’ajouter du code, vous devez mettre à jour les propriétés du projet pour vous assurer que le code WinRT dont vous avez besoin peut être compilé :
   • Cliquez avec le bouton droit sur le projet HoloLensWinrtDLL et sélectionnez les propriétés
   • Remplacez la liste déroulante Configuration par Toutes les configurations et la liste déroulante Plateforme par Toutes les plateformes
   • Sous Propriétés> de configuration C/C++> Toutes les options :
     • Ajouter await à Options supplémentaires pour nous assurer que nous pouvons attendre sur les tâches asynchrones
     • Remplacez C++ Language Standard par ISO C++17 Standard (/std:c++17) pour inclure n’importe quel code WinRT

Votre projet est prêt à mettre à jour la source de la DLL avec du code WinRT qui ouvre une boîte de dialogue de fichier et enregistre un fichier sur le disque HoloLens.

Ajout du code DLL

1. Ouvrez HoloLensWinrtDLL.h et ajoutez une fonction dll exportée pour qu’Unreal consomme :

#pragma once

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

2. Ouvrez HoloLensWinrtDLL.cpp et ajoutez tous les en-têtes que la classe utilisera :

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

Notes

Tout le code WinRT est stocké dans HoloLensWinrtDLL.cpp . Unreal n’essaie donc pas d’inclure de code WinRT lors du référencement de l’en-tête.

3. Toujours dans HoloLensWinrtDLL.cpp, ajoutez un corps de fonction pour OpenFileDialogue() et tout le code pris en charge :

// 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. Ajoutez une classe SaveGameManager à HoloLensWinrtDLL.cpp pour gérer la boîte de dialogue de fichier et enregistrer le fichier :

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. Générez la solution pour la version > ARM64 pour générer la DLL dans le répertoire enfant ARM64/Release/HoloLensWinrtDLL à partir de la solution DLL.

Ajout du fichier binaire WinRT à Unreal

La liaison et l’utilisation d’une DLL dans Unreal nécessitent un projet C++. Si vous utilisez un projet Blueprint, il peut être facilement converti en projet C++ en ajoutant une classe C++ :

1. Dans l’éditeur Unreal, ouvrez File > New C++ Class... et créez un acteur nommé WinrtActor pour exécuter le code dans la DLL :

Notes

Une solution a maintenant été créée dans le même répertoire que le fichier uproject, ainsi qu’un nouveau script de build nommé Source/ConsumeWinRT/ConsumeWinRT.Build.cs.

2. Ouvrez la solution, recherchez le dossier Games/ConsumeWinRT/Source/ConsumeWinRT , puis ouvrez ConsumeWinRT.build.cs :

Liaison de la DLL

1. Dans ConsumeWinRT.build.cs, ajoutez une propriété pour rechercher le chemin d’accès include de la DLL (répertoire contenant HoloLensWinrtDLL.h). La DLL se trouve dans un répertoire enfant du chemin d’accès include. Cette propriété sera donc utilisée comme dir racine binaire :

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. Dans le constructeur de classe, ajoutez le code suivant pour mettre à jour le chemin d’accès include, lier la nouvelle bibliothèque et retarder le chargement et copier la DLL vers l’emplacement appx empaqueté :

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. Ouvrez WinrtActor.h et ajoutez une définition de fonction, celle qu’un blueprint appellera :

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

4. Ouvrez WinrtActor.cpp et mettez à jour BeginPlay pour charger la 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
}

Attention

La DLL doit être chargée avant d’appeler l’une de ses fonctions.

Création du jeu

1. Créez la solution de jeu pour lancer l’éditeur Unreal ouvert sur le projet de jeu :
   • Sous l’onglet Placer les acteurs , recherchez le nouveau WinrtActor et faites-le glisser dans la scène.
   • Ouvrez le blueprint de niveau pour exécuter la fonction d’appel de blueprint dans winrtActor

2. Dans World Outliner, recherchez le WindrtActor précédemment déposé dans la scène et faites-le glisser dans le blueprint de niveau :

3. Dans le blueprint de niveau, faites glisser le nœud de sortie à partir de WinrtActor, recherchez Ouvrir le dialogue de fichier, puis routez le nœud à partir de n’importe quelle entrée utilisateur. Dans ce cas, Ouvrir le dialogue de fichier est appelé à partir d’un événement speech :

4. Empaqueter ce jeu pour HoloLens, le déployer et l’exécuter.

Quand Unreal appelle OpenFileDialogue, une boîte de dialogue de fichier s’ouvre sur HoloLens et vous invite à entrer un nom de fichier .txt. Une fois le fichier enregistré, accédez à l’onglet Explorateur de fichiers dans le portail de l’appareil pour voir le contenu « Hello WinRT ».

Résumé

Nous vous encourageons à utiliser ce tutoriel comme point de départ pour utiliser du code WinRT dans Unreal lorsque vous devez enregistrer des fichiers sur le disque HoloLens à l’aide de la même boîte de dialogue que Windows. Le même processus s’applique à l’exportation de fonctions supplémentaires à partir de l’en-tête HoloLensWinrtDLL et utilisées dans Unreal. Portez une attention particulière au code DLL qui attend sur du code WinRT asynchrone dans un thread MTA en arrière-plan, ce qui évite d’interblocage du thread de jeu Unreal.

Point de contrôle de développement suivant

Si vous suivez le parcours de développement Unreal que nous avons mis en place, vous explorez actuellement les API et les fonctionnalités de la plateforme Mixed Reality. À partir de là, vous pouvez passer à n’importe quelle rubrique ou accéder directement au déploiement de votre application sur un appareil ou un émulateur.

Déploiement sur un appareil

Voir aussi

• API C++/WinRT
• Classe FileSavePicker
• Bibliothèques tierces Unreal