WinRT di Unreal

Selama pengembangan HoloLens Anda, Anda mungkin perlu menulis fitur menggunakan WinRT. Misalnya, membuka dialog file dalam aplikasi HoloLens akan memerlukan FileSavePicker di file header winrt/Windows.Storage.Pickers.h. WinRT didukung dalam sistem build Unreal dari versi 4.26 dan seterusnya.

4.26

API WinRT standar

Cara paling umum dan term mudah untuk menggunakan WinRT adalah dengan memanggil metode dari WinSDK. Untuk melakukannya, buka file YourModule.Build.cs dan tambahkan baris berikut:

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

Selanjutnya, Anda perlu menambahkan header WinRT berikut:

#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

Kode WinRT hanya dapat dikompilasi di platform Win64 dan HoloLens, sehingga pernyataan if mencegah pustaka WinRT disertakan pada platform lain. unknwn.h ditambahkan karena memiliki antarmuka IUnknown.

WinRT dari paket NuGet

Ini sedikit lebih rumit jika Anda perlu menambahkan paket NuGet dengan dukungan WinRT. Dalam hal ini, Visual Studio dapat melakukan hampir semua pekerjaan untuk Anda, tetapi sistem build Unreal tidak dapat dilakukan. Untungnya, itu tidak terlalu sulit. Di bawah ini adalah contoh bagaimana Anda akan mengunduh paket Microsoft.MixedReality.QR. Anda dapat menggantinya dengan yang lain, pastikan Anda tidak kehilangan file winmd dan menyalin dll yang benar.

Dll Windows SDK dari bagian sebelumnya ditangani oleh OS. Dll NuGet harus dikelola oleh kode dalam modul Anda. Sebaiknya tambahkan kode untuk mengunduhnya, menyalin ke folder biner, dan memuat ke dalam memori proses di startup modul.

Pada langkah pertama, Anda harus menambahkan packages.config (/nuget/reference/packages-config) ke folder akar modul Anda. Di sana Anda harus menambahkan semua paket yang ingin Anda unduh, termasuk semua dependensinya. Di sini saya menambahkan Microsoft.MixedReality.QR sebagai payload utama dan dua lainnya sebagai dependensi untuk itu. Format file tersebut sama seperti di 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>

Sekarang Anda dapat mengunduh NuGet, paket yang diperlukan, atau merujuk ke dokumentasi NuGet.

Buka YourModule.Build.cs dan tambahkan kode berikut:

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

Anda harus menentukan metode SafeCopy sebagai berikut:

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

DLL NuGet perlu dimuat ke dalam memori proses Win32 Anda secara manual; sebaiknya tambahkan pemuatan manual ke dalam metode startup modul Anda:

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
}

Terakhir, Anda dapat menyertakan header WinRT ke dalam kode Anda seperti yang dijelaskan di bagian sebelumnya.

4,25

Unreal tidak mengkompilasi kode WinRT secara asli di versi 4.25, jadi tugas Anda adalah membangun biner terpisah yang dapat dikonsumsi oleh sistem build Unreal.

Tujuan

• Membuat DLL Windows Universal yang membuka FileSaveDialogue
• Tautkan DLL tersebut ke proyek permainan Unreal
• Simpan file di HoloLens dari cetak biru Unreal menggunakan DLL baru

Memulai

1. Periksa apakah Anda memiliki semua alat yang diperlukan terinstal
2. Buat proyek Unreal baru dan beri nama Consumewinrt
3. Aktifkan plugin yang diperlukan untuk pengembangan HoloLens
4. Penyiapan untuk penyebaran ke perangkat atau emulator

Membuat DLL WinRT

1. Buka proyek Visual Studio baru dan buat proyek DLL (Universal Windows) di direktori yang sama dengan file uproject game Unreal.

2. Beri nama proyek HoloLensWinrtDLL dan atur lokasi sebagai subdirektori ThirdParty ke file uproject game Unreal.
   • Pilih Tempatkan solusi dan proyek di direktori yang sama untuk menyederhanakan mencari jalur nanti.

Penting

Setelah proyek baru dikompilasi, beri perhatian khusus pada file cpp dan header kosong, masing-masing bernama HoloLensWinrtDLL.cpp dan HoloLensWinrtDLL.h . Header adalah file include yang menggunakan DLL di Unreal, sementara cpp memegang isi fungsi apa pun yang Anda ekspor dan menyertakan kode WinRT apa pun yang tidak akan dapat dikompilasi oleh Unreal.

3. Sebelum menambahkan kode apa pun, Anda perlu memperbarui properti proyek untuk memastikan kode WinRT yang Anda butuhkan dapat mengkompilasi:
   • Klik kanan pada proyek HoloLensWinrtDLL dan pilih properti
   • Ubah menu dropdown Konfigurasi ke Semua Konfigurasi dan dropdown Platform ke Semua Platform
   • Di bawah Properti> Konfigurasi C/C++> Semua Opsi:
     • Tambahkan tunggu ke Opsi Tambahan untuk memastikan kita dapat menunggu tugas asinkron
     • Ubah Standar Bahasa C++ menjadi STANDAR ISO C++17 (/std:c++17) untuk menyertakan kode WinRT apa pun

Proyek Anda siap untuk memperbarui sumber DLL dengan kode WinRT yang membuka dialog file dan menyimpan file ke disk HoloLens.

Menambahkan kode DLL

1. Buka HoloLensWinrtDLL.h dan tambahkan fungsi yang diekspor dll agar Tidak Dapat Dikonsumsi:

#pragma once

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

2. Buka HoloLensWinrtDLL.cpp dan tambahkan semua header yang akan digunakan kelas:

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

Catatan

Semua kode WinRT disimpan di HoloLensWinrtDLL.cpp sehingga Unreal tidak mencoba menyertakan kode WinRT apa pun saat mereferensikan header.

3. Masih di HoloLensWinrtDLL.cpp, tambahkan isi fungsi untuk OpenFileDialogue() dan semua kode yang didukung:

// 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. Tambahkan kelas SaveGameManager ke HoloLensWinrtDLL.cpp untuk menangani dialog file dan menyimpan file:

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. Bangun solusi untuk Release > ARM64 untuk membangun DLL ke direktori anak ARM64/Release/HoloLensWinrtDLL dari solusi DLL.

Menambahkan biner WinRT ke Unreal

Menautkan dan menggunakan DLL di Unreal memerlukan proyek C++. Jika Anda menggunakan proyek Blueprint, proyek tersebut dapat dengan mudah dikonversi ke proyek C++ dengan menambahkan kelas C++:

1. Di editor Unreal, buka File > Kelas C++ Baru... dan buat Aktor baru bernama WinrtActor untuk menjalankan kode di DLL:

Catatan

Solusi sekarang telah dibuat dalam direktori yang sama dengan file uproject bersama dengan skrip build baru bernama Source/ConsumeWinRT/ConsumeWinRT.Build.cs.

2. Buka solusinya, telusuri folder Games/ConsumeWinRT/Source/ConsumeWinRT , dan buka ConsumeWinRT.build.cs:

Menautkan DLL

1. Di ConsumeWinRT.build.cs, tambahkan properti untuk menemukan jalur include untuk DLL (direktori yang berisi HoloLensWinrtDLL.h). DLL berada dalam direktori anak ke jalur yang disertakan, sehingga properti ini akan digunakan sebagai dir akar biner:

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. Di konstruktor kelas, tambahkan kode berikut untuk memperbarui jalur sertakan, tautkan lib baru, dan tunda-muat dan salin DLL ke lokasi appx yang dipaketkan:

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. Buka WinrtActor.h dan tambahkan satu definisi fungsi, yang akan dipanggil cetak biru:

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

4. Buka WinrtActor.cpp dan perbarui BeginPlay untuk memuat 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
}

Perhatian

DLL harus dimuat sebelum memanggil salah satu fungsinya.

Membangun permainan

1. Bangun solusi game untuk meluncurkan editor Unreal yang dibuka untuk proyek game:
   • Di tab Tempatkan Aktor , cari WinrtActor baru dan seret ke dalam adegan
   • Buka cetak biru tingkat untuk menjalankan fungsi yang dapat dipanggil cetak biru di WinrtActor

2. Di World Outliner, temukan WindrtActor yang sebelumnya dijatuhkan ke adegan dan seret ke dalam cetak biru tingkat:

3. Dalam cetak biru tingkat, seret simpul output dari WinrtActor, cari Open File Dialogue, lalu rutekan simpul dari input pengguna apa pun. Dalam hal ini, Open File Dialogue sedang dipanggil dari acara ucapan:

4. Kemas game ini untuk HoloLens, sebarkan, dan jalankan.

Saat Unreal memanggil OpenFileDialogue, Dialog File terbuka pada HoloLens yang meminta nama file .txt. Setelah file disimpan, buka tab File explorer di portal perangkat untuk melihat konten "Hello WinRT".

Ringkasan

Kami mendorong Anda untuk menggunakan tutorial ini sebagai titik awal untuk mengkonsumsi kode WinRT di Unreal ketika Anda perlu menyimpan file ke disk HoloLens menggunakan dialog file yang sama dengan Windows. Proses yang sama berlaku untuk mengekspor fungsi tambahan dari header HoloLensWinrtDLL dan digunakan dalam Unreal. Beri perhatian khusus pada kode DLL yang menunggu kode WinRT asinkron di utas MTA latar belakang, yang menghindari kebuntuan utas game Unreal.

Titik Pemeriksaan Pengembangan Berikutnya

Jika Anda mengikuti perjalanan pengembangan Unreal yang telah kami susun, Anda berada di tengah-tengah menjelajahi kemampuan platform dan API Mixed Reality. Dari sini, Anda dapat melanjutkan ke topik apa pun atau melompat langsung ke penyebaran aplikasi Anda di perangkat atau emulator.

Menyebarkan ke perangkat

Lihat juga

• API C++/WinRT
• Kelas FileSavePicker
• Pustaka Pihak Ketiga Tidak Nyata