WinRT no Unreal

Ao longo do desenvolvimento do HoloLens, talvez seja necessário escrever um recurso usando o WinRT. Por exemplo, abrir um diálogo de arquivo em um aplicativo HoloLens precisaria do FileSavePicker no arquivo de cabeçalho winrt/Windows.Storage.Pickers.h. O WinRT tem suporte no sistema de build do Unreal da versão 4.26 em diante.

4.26

As APIs padrão do WinRT

A maneira mais comum e fácil de usar o WinRT é chamar métodos do WinSDK. Para fazer isso, abra o arquivo 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, você precisa adicionar os seguintes cabeçalhos do 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, portanto, a instrução if impede que bibliotecas WinRT sejam incluídas em outras plataformas. unknwn.h foi adicionado para ter a interface IUnknown.

WinRT de um pacote NuGet

É um pouco mais complicado se você precisar adicionar um pacote NuGet com suporte ao WinRT. Nesse caso, o Visual Studio pode fazer praticamente todo o trabalho para você, mas o sistema de build do Unreal não pode. Felizmente, não é muito difícil. Veja abaixo um exemplo de como baixar o pacote Microsoft.MixedReality.QR. Você pode substituí-lo por outro, apenas certifique-se de não perder o arquivo winmd e copiar a dll correta.

As dlls do SDK do Windows da seção anterior são tratadas pelo sistema operacional. As dlls do NuGet devem ser gerenciadas pelo código em seu módulo. É recomendável adicionar código para baixá-los, copiar para a pasta binários e carregar na memória do processo na inicialização do módulo.

Na primeira etapa, você deve adicionar um packages.config (/nuget/reference/packages-config) à pasta raiz do módulo. Lá, você deve adicionar todos os pacotes que deseja baixar, incluindo todas as dependências. Aqui, eu adiciono Microsoft.MixedReality.QR como um conteúdo primário e outros dois como dependências para ele. O formato desse arquivo é o mesmo 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 você pode baixar 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"));
	}
}

Você precisará definir o método SafeCopy da seguinte maneira:

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

As DLLs do NuGet precisam ser carregadas na memória do processo do Win32 manualmente; É recomendável adicionar o carregamento manual ao método de inicialização 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, você pode incluir cabeçalhos WinRT em seu código, conforme descrito na seção anterior.

4.25

O Unreal não compila nativamente o código WinRT na versão 4.25, portanto, é seu trabalho criar um binário separado que o sistema de build do Unreal pode consumir.

Objetivos

• Criar uma DLL Universal do Windows que abre um FileSaveDialogue
• Vincular essa DLL a um projeto de jogo do Unreal
• Salvar um arquivo no HoloLens de um blueprint do Unreal usando a nova DLL

Introdução

1. Verifique se você tem todas as ferramentas necessárias instaladas
2. Criar um novo projeto do Unreal e nomeá-lo Consumwinrt
3. Habilitar os plug-ins necessários para o desenvolvimento do HoloLens
4. Configuração para implantação em um dispositivo ou emulador

Criando uma DLL do WinRT

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

2. Nomeie o projeto como HoloLensWinrtDLL e defina o local como um subdiretório ThirdParty como o arquivo de uproject do jogo do Unreal.
   • Selecione Colocar solução e projeto no mesmo diretório para simplificar a busca de caminhos posteriormente.

Importante

Depois que o novo projeto for compilado, preste atenção especial aos arquivos cpp e cabeçalho em branco, chamados HoloLensWinrtDLL.cpp e HoloLensWinrtDLL.h , respectivamente. O cabeçalho é o arquivo de inclusão que usa a DLL no Unreal, enquanto o cpp contém o corpo de todas as funções exportadas e inclui qualquer código WinRT que o Unreal não seria capaz de compilar de outra forma.

3. Antes de adicionar qualquer código, você precisa atualizar as propriedades do projeto para garantir que o código WinRT de que você precisa possa compilar:
   • Clique com o botão direito do mouse no projeto HoloLensWinrtDLL e selecione propriedades
   • Altere a lista suspensa Configuração para Todas as Configurações e a lista suspensa Plataforma para Todas as Plataformas
   • Em Propriedades> de Configuração C/C++> Todas as Opções:
     • Adicione await a Opções Adicionais para garantir que possamos aguardar tarefas assíncronas
     • Alterar o Padrão de Linguagem C++ para ISO C++17 Standard (/std:c++17) para incluir qualquer código WinRT

Seu projeto está pronto para atualizar a origem da DLL com o código WinRT que abre uma caixa de diálogo de arquivo e salva um arquivo no disco do HoloLens.

Adicionando o código DLL

1. Abra o HoloLensWinrtDLL.h e adicione uma função exportada de dll para o 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 usará:

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

Observação

Todo o código WinRT é armazenado no HoloLensWinrtDLL.cpp para que o Unreal não tente 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 com suporte:

// 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 manipular o diálogo do arquivo e salvar o arquivo:

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 a versão > ARM64 para criar a DLL no diretório filho ARM64/Release/HoloLensWinrtDLL da solução de DLL.

Adicionando o binário do WinRT ao Unreal

Vincular e usar uma DLL no Unreal requer um projeto C++. Se você estiver usando um projeto blueprint, ele poderá ser facilmente convertido em um projeto C++ adicionando uma classe C++:

1. No editor do Unreal, abra Arquivo > Nova Classe C++ e crie um novo Ator chamado WinrtActor para executar o código na DLL:

Observação

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

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

Vinculando a DLL

1. Em ConsumeWinRT.build.cs, adicione uma propriedade para localizar o caminho de inclusão para a DLL (o diretório que contém HoloLensWinrtDLL.h). A DLL está em um diretório filho para o caminho de inclusão, portanto, essa propriedade será usada como o dir raiz binário:

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 classe, adicione o seguinte código para atualizar o caminho de inclusão, vincule a nova biblioteca e a carga de atraso e copie a DLL para o local 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, uma que um blueprint 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
}

Cuidado

A DLL deve ser carregada antes de chamar qualquer uma de suas funções.

Criando o jogo

1. Crie a solução de jogo para iniciar o editor do Unreal aberto no projeto do jogo:
   • Na guia Colocar Atores , pesquise o novo WinrtActor e arraste-o para a cena
   • Abra o blueprint de nível para executar a função callable de blueprint no WinrtActor

2. No World Outliner, localize o WindrtActor lançado anteriormente na cena e arraste-o para o blueprint de nível:

3. No blueprint de nível, arraste o nó de saída do WinrtActor, pesquise Abrir Diálogo de Arquivo e encaminhe o nó de qualquer entrada do usuário. Nesse caso, o Open File Dialogue está sendo chamado de um evento de fala:

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

Quando o Unreal chama OpenFileDialogue, um Diálogo de Arquivo é aberto no HoloLens solicitando um nome de arquivo .txt. Depois que o arquivo for salvo, vá para a guia Explorador de arquivos no portal do dispositivo para ver o conteúdo "Hello WinRT".

Resumo

Incentivamos você a usar este tutorial como ponto de partida para consumir código WinRT no Unreal quando precisar salvar arquivos no disco do HoloLens usando o mesmo diálogo de arquivo que o Windows. O mesmo processo se aplica à exportação de funções adicionais do cabeçalho HoloLensWinrtDLL e usado no Unreal. Preste atenção especial ao código DLL que aguarda o código WinRT assíncrono em um thread MTA em segundo plano, o que evita o deadlock do thread do jogo Unreal.

Próximo ponto de verificação de desenvolvimento

Se está seguindo o percurso de desenvolvimento do Unreal que apresentamos, você está no meio da exploração de funcionalidades e APIs da plataforma de Realidade Misturada. A partir daqui, você pode continuar para qualquer tópico ou ir diretamente para implantar seu aplicativo em um dispositivo ou emulador.

Como fazer a implantação no dispositivo

Confira também

• C++/WinRT APIs
• Classe FileSavePicker
• Bibliotecas de terceiros do Unreal