Unreal의 WinRT

표준 WinRT API

WinRT를 사용하는 가장 일반적이고 쉬운 방법은 WinSDK에서 메서드를 호출하는 것입니다. 이렇게 하려면 YourModule.Build.cs 파일을 열고 다음 줄을 추가합니다.

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

다음으로, 다음 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

WinRT 코드는 Win64 및 HoloLens 플랫폼에서만 컴파일할 수 있으므로 if 문은 WinRT 라이브러리가 다른 플랫폼에 포함되지 않도록 합니다. unknwn.h가 IUnknown 인터페이스를 갖기 위해 추가되었습니다.

NuGet 패키지의 WinRT

WinRT 지원을 사용하여 NuGet 패키지를 추가해야 하는 경우 좀 더 복잡합니다. 이 경우 Visual Studio는 거의 모든 작업을 수행할 수 있지만 Unreal 빌드 시스템은 수행할 수 없습니다. 다행히도, 그것은 너무 어렵지 않다. 다음은 Microsoft.MixedReality.QR 패키지를 다운로드하는 방법에 대한 예입니다. winmd 파일을 잃지 않도록 하고 올바른 dll을 복사하여 다른 파일로 바꿀 수 있습니다.

이전 섹션의 Windows SDK dll은 OS에서 처리됩니다. NuGet의 dll은 모듈의 코드에 의해 관리되어야 합니다. 코드를 추가하여 다운로드하고, 이진 파일 폴더에 복사하고, 모듈 시작 시 프로세스 메모리에 로드하는 것이 좋습니다.

첫 번째 단계에서는 모듈의 루트 폴더에 packages.config(/nuget/reference/packages-config)를 추가해야 합니다. 여기에서 모든 종속성을 포함하여 다운로드하려는 모든 패키지를 추가해야 합니다. 여기서는 Microsoft.MixedReality.QR을 기본 페이로드로, 다른 두 페이로드는 종속성으로 추가했습니다. 해당 파일의 형식은 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>

이제 필요한 패키지인 NuGet을 다운로드하거나 NuGet 설명서를 참조할 수 있습니다.

YourModule.Build.cs를 열고 다음 코드를 추가합니다.

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

다음과 같이 SafeCopy 메서드를 정의해야 합니다.

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은 Win32 프로세스 메모리에 수동으로 로드해야 합니다. 모듈의 시작 메서드에 수동 로드를 추가하는 것이 좋습니다.

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
}

마지막으로 이전 섹션에서 설명한 대로 WinRT 헤더를 코드에 포함할 수 있습니다.

Unreal은 기본적으로 버전 4.25에서 WinRT 코드를 컴파일하지 않으므로 Unreal의 빌드 시스템에서 사용할 수 있는 별도의 이진 파일을 빌드하는 것이 사용자의 작업입니다.

목표

• FileSaveDialogue를 여는 유니버설 Windows DLL 만들기
• 해당 DLL을 Unreal 게임 프로젝트에 연결
• 새 DLL을 사용하여 Unreal 청사진에서 HoloLens에 파일 저장

시작

1. 필요한 도구가 모두 설치되어 있는지 확인합니다.
2. 새 Unreal 프로젝트를 만들고 이름을 Consumewinrt로 지정합니다.
3. HoloLens 개발에 필요한 플러그 인 사용
4. 디바이스 또는 에뮬레이터에 배포를 위한 설정

WinRT DLL 만들기

1. 새 Visual Studio 프로젝트를 열고 Unreal 게임의 uproject 파일과 동일한 디렉터리에 DLL(유니버설 Windows) 프로젝트를 만듭니다.

2. 프로젝트 이름을 HoloLensWinrtDLL 로 지정하고 위치를 ThirdParty 하위 디렉터리로 Unreal 게임의 uproject 파일로 설정합니다.
   • 솔루션 및 프로젝트를 동일한 디렉터리에 배치를 선택하여 나중에 경로를 찾는 작업을 간소화합니다.

3. 코드를 추가하기 전에 필요한 WinRT 코드를 컴파일할 수 있도록 프로젝트 속성을 업데이트해야 합니다.
   • HoloLensWinrtDLL 프로젝트를 마우스 오른쪽 단추로 클릭하고 속성을 선택합니다.
   • 구성 드롭다운을 모든 구성으로 변경하고 플랫폼 드롭다운을 모든 플랫폼으로 변경
   • 구성 속성> C/C++> 모든 옵션에서 다음을 수행합니다.
     • 추가 옵션에 await를 추가하여 비동기 작업을 대기할 수 있는지 확인합니다.
     • WinRT 코드를 포함하도록 C++ 언어 표준을ISO C++17 표준(/std:c++17) 으로 변경

프로젝트는 파일 대화 상자를 열고 파일을 HoloLens 디스크에 저장하는 WinRT 코드로 DLL의 원본을 업데이트할 준비가 된 것입니다.

DLL 코드 추가

1. HoloLensWinrtDLL.h를 열고 Unreal에서 사용할 dll 내보내기 함수를 추가합니다.

#pragma once

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

2. HoloLensWinrtDLL.cpp를 열고 클래스에서 사용할 모든 헤더를 추가합니다.

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

3. HoloLensWinrtDLL.cpp에서 OpenFileDialogue() 및 지원되는 모든 코드에 대한 함수 본문을 추가합니다.

// 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. HoloLensWinrtDLL.cpp에 SaveGameManager 클래스를 추가하여 파일 대화 상자를 처리하고 파일을 저장합니다.

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. 릴리스 > ARM64용 솔루션을 빌드하여 DLL 솔루션에서 자식 디렉터리 ARM64/Release/HoloLensWinrtDLL에 DLL을 빌드합니다.

Unreal에 WinRT 이진 파일 추가

Unreal에서 DLL을 연결하고 사용하려면 C++ 프로젝트가 필요합니다. Blueprint 프로젝트를 사용하는 경우 C++ 클래스를 추가하여 C++ 프로젝트로 쉽게 변환할 수 있습니다.

1. Unreal 편집기에서 파일 > 새 C++ 클래스...를 열고 WinrtActor라는 새 행위자를 만들어 DLL에서 코드를 실행합니다.

2. 솔루션을 열고 Games/ConsumeWinRT/Source/ConsumeWinRT 폴더를 찾아 서 ConsumeWinRT.build.cs를 엽니다.

DLL 연결

1. ConsumeWinRT.build.cs에서 속성을 추가하여 DLL의 포함 경로(HoloLensWinrtDLL.h를 포함하는 디렉터리)를 찾습니다. DLL은 포함 경로에 대한 자식 디렉터리에 있으므로 이 속성은 이진 루트 dir로 사용됩니다.

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. 클래스 생성자에서 다음 코드를 추가하여 포함 경로를 업데이트하고, 새 lib를 연결하고, DLL을 지연 로드하고, 패키지된 appx 위치에 복사합니다.

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. WinrtActor.h를 열고 청사진이 호출하는 함수 정의를 하나 추가합니다.

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

4. WinrtActor.cpp를 열고 BeginPlay를 업데이트하여 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
}

게임 빌드

1. 게임 솔루션을 빌드하여 게임 프로젝트에 열린 Unreal 편집기를 시작합니다.
   • 행위자 배치 탭에서 새 WinrtActor를 검색하여 장면으로 끌어옵니다.
   • 수준 청사진을 열어 WinrtActor에서 청사진 호출 가능 함수를 실행합니다.

2. World Outliner에서 이전에 장면에 떨어뜨린 WindrtActor를 찾아 수준 청사진으로 끌어옵니다.

3. 수준 청사진에서 WinrtActor에서 출력 노드를 끌어 서 파일 대화 상자 열기를 검색한 다음, 사용자 입력에서 노드를 라우팅합니다. 이 경우 음성 이벤트에서 파일 대화 상자 열기가 호출됩니다.

4. HoloLens용으로 이 게임을 패키지하고 배포하고 실행합니다.

Unreal이 OpenFileDialogue를 호출하면 .txt 파일 이름을 묻는 HoloLens에서 파일 대화 상자가 열립니다. 파일이 저장되면 디바이스 포털의 파일 탐색기 탭으로 이동하여 "Hello WinRT" 콘텐츠를 확인합니다.

요약

Windows와 동일한 파일 대화 상자를 사용하여 HoloLens 디스크에 파일을 저장해야 하는 경우 Unreal에서 WinRT 코드를 사용하기 위한 시작점으로 이 자습서를 사용하는 것이 좋습니다. HoloLensWinrtDLL 헤더에서 추가 함수를 내보내고 Unreal에서 사용하는 프로세스도 마찬가지입니다. 백그라운드 MTA 스레드에서 비동기 WinRT 코드를 대기하는 DLL 코드에 특히 주의하여 Unreal 게임 스레드의 교착 상태를 방지합니다.