WinRT in Unreal

Ao longo do desenvolvimento do HoloLens, poderá ter de escrever uma funcionalidade com o WinRT. Por exemplo, abrir um diálogo de ficheiro numa aplicação HoloLens precisaria do FicheiroSavePicker no ficheiro de cabeçalho winrt/Windows.Storage.Pickers.h. O WinRT é suportado no sistema de compilação da Unreal a partir da versão 4.26.

4.26

As APIs WinRT padrão

A forma mais comum e fácil de utilizar o WinRT é chamar métodos do WinSDK. Para tal, abra o ficheiro YourModule.Build.cs e adicione as seguintes linhas:

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

Em seguida, tem de adicionar os seguintes cabeçalhos 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

O código WinRT só pode ser compilado nas plataformas Win64 e HoloLens, pelo que a instrução if impede que as bibliotecas WinRT sejam incluídas noutras plataformas. unknwn.h foi adicionado para ter a interface IUnknown.

WinRT de um pacote NuGet

É um pouco mais complicado se precisar de adicionar um pacote NuGet com suporte winRT. Neste caso, o Visual Studio pode fazer praticamente todo o trabalho por si, mas o sistema de compilação Unreal não consegue. Felizmente, não é muito difícil. Segue-se um exemplo de como iria transferir o pacote Microsoft.MixedReality.QR. Pode substituí-lo por outro, apenas certifique-se de que não perde o ficheiro winmd e copie o dll correto.

Os dlls do SDK do Windows da secção anterior são processados pelo SO. Os dlls do NuGet têm de ser geridos pelo código no módulo. Recomendamos que adicione código para os transferir, copiar para a pasta de binários e carregar para a memória do processo no arranque do módulo.

No primeiro passo, deve adicionar um packages.config (/nuget/reference/packages-config) à pasta raiz do módulo. Aí deve adicionar todos os pacotes que pretende transferir, incluindo todas as respetivas dependências. Aqui adicionei Microsoft.MixedReality.QR como um payload principal e outros dois como dependências. O formato desse ficheiro é igual ao do 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>

Agora, pode transferir o NuGet, os pacotes necessários ou consultar a documentação do NuGet.

Abra YourModule.Build.cs e adicione o seguinte código:

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

Terá de definir o método SafeCopy da seguinte forma:

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

Os DLLs NuGet têm de carregar manualmente para a memória do processo Win32; recomendamos que adicione o carregamento manual ao método de arranque do módulo:

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
}

Por fim, pode incluir cabeçalhos WinRT no seu código, conforme descrito na secção anterior.

4.25

O Unreal não compila nativamente o código WinRT na versão 4.25, pelo que é sua função criar um binário separado que o sistema de compilação da Unreal possa consumir.

Objetivos

• Criar uma DLL universal do Windows que abra um FileSaveDialogue
• Associar essa DLL a um projeto de jogo irreal
• Guardar um ficheiro no HoloLens a partir de um esquema Unreal com a nova DLL

Introdução

1. Verifique se tem todas as ferramentas necessárias instaladas
2. Crie um novo projeto Unreal e dê-lhe o nome Consumewinrt
3. Ativar os plug-ins necessários para o desenvolvimento do HoloLens
4. Configuração para implementação num dispositivo ou emulador

Criar uma DLL WinRT

1. Abra um novo projeto do Visual Studio e crie um projeto DLL (Universal Windows) no mesmo diretório que o ficheiro uproject do jogo Unreal.

2. Atribua um nome ao projeto HoloLensWinrtDLL e defina a localização como um subdiretório ThirdParty para o ficheiro uproject do jogo Unreal.
   • Selecione Colocar solução e projeto no mesmo diretório para simplificar a procura de caminhos mais tarde.

Importante

Após a compilação do novo projeto, preste especial atenção aos ficheiros cpp e cabeçalho em branco, denominados HoloLensWinrtDLL.cpp e HoloLensWinrtDLL.h , respetivamente. O cabeçalho é o ficheiro de inclusão que utiliza a DLL em Unreal, enquanto o cpp contém o corpo de quaisquer funções que exportar e inclui qualquer código WinRT que a Unreal não conseguiria compilar.

3. Antes de adicionar qualquer código, tem de atualizar as propriedades do projeto para garantir que o código WinRT de que precisa pode compilar:
   • Clique com o botão direito do rato no projeto HoloLensWinrtDLL e selecione propriedades
   • Alterar a lista pendente Configuração para Todas as Configurações e a lista pendente Plataforma para Todas as Plataformas
   • Em Propriedades de> Configuração C/C++> Todas as Opções:
     • Adicionar aguardar a Opções Adicionais para garantir que podemos aguardar em tarefas assíncronas
     • Altere C++ Language Standard para ISO C++17 Standard (/std:c++17) para incluir qualquer código WinRT

O seu projeto está pronto para atualizar a origem da DLL com o código WinRT que abre um diálogo de ficheiros e guarda um ficheiro no disco do HoloLens.

Adicionar o código DLL

1. Abra HoloLensWinrtDLL.h e adicione uma função exportada dll para Unreal consumir:

#pragma once

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

2. Abra HoloLensWinrtDLL.cpp e adicione todos os cabeçalhos que a classe utilizará:

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

Nota

Todo o código WinRT é armazenado em HoloLensWinrtDLL.cpp , pelo que a Unreal não tenta incluir nenhum código WinRT ao referenciar o cabeçalho.

3. Ainda no HoloLensWinrtDLL.cpp, adicione um corpo de função para OpenFileDialogue() e todo o código suportado:

// 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. Adicione uma classe SaveGameManager ao HoloLensWinrtDLL.cpp para lidar com o diálogo de ficheiros e guardar o ficheiro:

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. Crie a solução para Libertar > ARM64 para criar a DLL para o diretório subordinado ARM64/Release/HoloLensWinrtDLL a partir da solução DLL.

Adicionar o binário WinRT a Unreal

Ligar e utilizar uma DLL em Unreal requer um projeto C++. Se estiver a utilizar um projeto do Blueprint, este pode ser facilmente convertido num projeto C++ ao adicionar uma classe C++:

1. No editor Unreal, abra File > New C++ Class... e crie um novo Ator com o nome WinrtActor para executar o código na DLL:

Nota

Uma solução foi agora criada no mesmo diretório que o ficheiro uproject, juntamente com um novo script de compilação chamado Source/ConsumeWinRT/ConsumeWinRT.Build.cs.

2. Abra a solução, procure a pasta Jogos/ConsumeWinRT/Source/ConsumeWinRT e abra ConsumeWinRT.build.cs:

Ligar a DLL

1. Em ConsumeWinRT.build.cs, adicione uma propriedade para encontrar o caminho de inclusão para a DLL (o diretório que contém HoloLensWinrtDLL.h). A DLL está num diretório subordinado para o caminho de inclusão, pelo que esta propriedade será utilizada como o dir de raiz binária:

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. No construtor de classes, adicione o seguinte código para atualizar o caminho de inclusão, ligue a nova lib e atrase-load e copie a DLL para a localização do appx empacotado:

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. Abra WinrtActor.h e adicione uma definição de função, que um esquema irá chamar:

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

4. Abra WinrtActor.cpp e atualize BeginPlay para carregar a 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
}

Atenção

A DLL tem de ser carregada antes de chamar qualquer uma das respetivas funções.

Construir o jogo

1. Crie a solução de jogo para iniciar o editor Unreal aberto no projeto de jogo:
   • No separador Place Actors , procure o novo WinrtActor e arraste-o para a cena
   • Abra o esquema de nível para executar a função callable do esquema no WinrtActor

2. No World Outliner, localize o WindrtActor anteriormente removido para a cena e arraste-o para o esquema de nível:

3. No esquema de nível, arraste o nó de saída do WinrtActor, procure Abrir Diálogo de Ficheiros e, em seguida, encaminhe o nó a partir de qualquer entrada de utilizador. Neste caso, o Open File Dialogue está a ser chamado a partir de um evento de voz:

4. Empacote este jogo para o HoloLens, implemente-o e execute-o.

Quando a Unreal chama OpenFileDialogue, é aberto um Diálogo de Ficheiros no HoloLens a pedir um nome de ficheiro .txt. Depois de guardar o ficheiro, aceda ao separador Explorador de ficheiros no portal do dispositivo para ver o conteúdo "Hello WinRT".

Resumo

Recomendamos que utilize este tutorial como ponto de partida para consumir código WinRT em Unreal quando precisar de guardar ficheiros no disco do HoloLens com o mesmo diálogo de ficheiros que o Windows. O mesmo processo aplica-se à exportação de funções adicionais a partir do cabeçalho HoloLensWinrtDLL e utilizado no Unreal. Preste especial atenção ao código DLL que aguarda o código WinRT assíncrono num thread MTA em segundo plano, o que evita o impasse do thread de jogo Unreal.

Próximo Ponto de Verificação de Desenvolvimento

Se estiver a seguir o percurso de desenvolvimento Irreal que definimos, está no meio de explorar as capacidades e APIs da plataforma Mixed Reality. A partir daqui, pode continuar para qualquer tópico ou avançar diretamente para a implementação da sua aplicação num dispositivo ou emulador.

Implementar no dispositivo

Ver também

• C++/WinRT APIs
• FileSavePicker class (Classe FileSavePicker)
• Bibliotecas de Terceiros Irreais