diff --git a/README.md b/README.md index 78c8c2da9..0a47ed04e 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,9 @@ MixedReality-WebRTC is part of the collection of repositories developed and main ## Download -NuGet packages are available for stable releases (`release/*` branches). See the [Release page on GitHub](https://github.com/microsoft/MixedReality-WebRTC/releases). +NuGet (C++, C#) and UPM (Unity) packages are available for stable releases (`release/*` branches). See the [Release page on GitHub](https://github.com/microsoft/MixedReality-WebRTC/releases) or the [Download documentation page](https://microsoft.github.io/MixedReality-WebRTC/manual/download.html) for details. -_Note_: The `master` branch contains the code for the next release, and therefore sometimes contains breaking API changes from the latest stable release. It is therefore not guaranteed to work with NuGet packages, which are only available for stable releases. In particular, the Unity integration scripts are only guaranteed to be compatible with NuGet packages if copied from a `release/*` branch. +_Note_: The `master` branch contains the code for the next release, and therefore sometimes contains breaking API changes from the latest stable release. It is therefore not guaranteed to work with NuGet packages, which are only available for stable releases. In particular, the Unity library scripts are only guaranteed to be compatible with NuGet packages if copied from a `release/*` branch, though it is strongly recommended to use the UPM packages instead. ## Build Status diff --git a/docs/manual/building-cslib.md b/docs/manual/building-cslib.md index 103b8171d..5b59d21bb 100644 --- a/docs/manual/building-cslib.md +++ b/docs/manual/building-cslib.md @@ -1,11 +1,11 @@ # Building the C# library -The MixedReality-WebRTC C# library is a platform-independent .NET Standard 2.0 library which relies on a platform-specific version of the C library to provide most of the implementation. The C# library is built on Windows from the `Microsoft.MixedReality.WebRTC.sln` Visual Studio solution located at the root of the git repository. Building from a non-Windows environment is not supported. +The MixedReality-WebRTC C# library is a platform-independent .NET Standard 2.0 library which relies on a platform-specific version of the C library to provide its WebRTC implementation. The C# library is built on Windows from the `Microsoft.MixedReality.WebRTC.sln` Visual Studio solution located at the root of the git repository. Building from a non-Windows environment is not supported. -This documentation assumes that the user has already built the native C library, and therefore has installed [its prerequisites](building-windows.md#prerequisites) and already cloned git the repository. +This documentation assumes that the user has already built the native C/C++ library on Windows, and therefore has installed [its prerequisites](building-windows.md#prerequisites) and already cloned the git repository of MixedReality-WebRTC. If you only built the Android archive `mrwebrtc.aar` on a different Linux machine then you should install those prerequisites first on the current Windows machine. > [!NOTE] -> If you have already built the entire solution for the native C library on Windows, then the C# library is already built. The steps below are mainly for Android-only users, although it is strongly recommended to build the Windows Desktop x64 configuration anyway to be able to run MixedReality-WebRTC in Play Mode in the Unity editor. +> If you have already built the entire solution for the native C/C++ library on Windows, then the C# library is already built. The steps below are mainly for Android-only users, although it is strongly recommended to build the Windows Desktop x64 configuration anyway to be able to run MixedReality-WebRTC in Play Mode in the Unity editor. ## Building the library @@ -18,7 +18,7 @@ This documentation assumes that the user has already built the native C library, On successful build, the C# assembly will be generated in a sub-folder of `bin/netstandard2.0`, and the DLL will also be copied by a post-build script to `libs\unity\library\Runtime\Plugins\` for the Unity library to consume it. > [!IMPORTANT] -> **Be sure to build the solution before opening any Unity integration project.** As part of the build, the library is copied to the `Plugins` folder of the Unity library. There are already some associated `.meta` files, which have been committed to the git repository, to inform Unity of the platform of each DLL and how to deploy it. If the Unity project is opened first, before the DLLs are present, Unity will assume those `.meta` files are stale and will delete them, and then later will recreate some with a different default config once the DLLs are copied. This leads to errors about modules with duplicate names. See the [Importing MixedReality-WebRTC](unity/helloworld-unity-importwebrtc.md) chapter of the "Hello, Unity World!" tutorial for more details. +> **Be sure to build the solution before opening any Unity library project.** As part of the build, the library is copied to the `Plugins` folder of the Unity library. There are already some associated `.meta` files, which have been committed to the git repository, to inform Unity of the platform of each DLL and how to deploy it. If the Unity project is opened first, before the DLLs are present, Unity will assume those `.meta` files are stale and will delete them, and then later will recreate some with a different default config once the DLLs are copied. This leads to errors about modules with duplicate names. See the [Building from Sources (Windows)](building-windows.md) page for more details. ## Testing the build diff --git a/docs/manual/building-windows.md b/docs/manual/building-windows.md index 07b08e1f7..311fff31a 100644 --- a/docs/manual/building-windows.md +++ b/docs/manual/building-windows.md @@ -61,8 +61,115 @@ Note that **this may take some time (> 5 minutes)** due to the large number of s On successful build, the binaries will be generated in a sub-directory under `bin/`, and the relevant DLLs will be copied by a post-build script to `libs\unity\library\Runtime\Plugins\` for the Unity library to consume them. +## Copying the binaries + +_Note: This section describes manual copying in case the Visual Studio solution is not used or the automated copying does not work for any reason. If the solution built successfully, the binaries should already have been copied (see above)._ + +The C# library `Microsoft.MixedReality.WebRTC.dll` is a .NET Standard 2.0 library. This means it is compatible with all CPU architectures. The C# library is available from `bin\netstandard2.0\Debug` or `bin\netstandard2.0\Release` depending on the build configuration which was compiled. In doubt you should use the `Release` configuration, which can provide better performance. This module needs to be copied somehwere into the `libs\unity\library\Runtime\Plugins\` folder of the git repository checkout. This is done automatically by the build process of the Visual Studio solution, but can also be done via the command line with `xcopy`, assuming that the git repository of MixedReality-WebRTC was cloned in `D:\mr-webrtc`: + +```cmd +cd /D D:\testproj +xcopy D:/mr-webrtc/bin/netstandard2.0/Release/Microsoft.MixedReality.WebRTC.dll libs/unity/library/Runtime/Plugins/Win32/x86_64/ +``` + +_Note_: By convention, and because of past experiences of getting errors when doing otherwise, the C# library is copied to the `Win32\x86_64` sub-folder where the native C library for the Unity editor is also located. It is unclear if this is best practice, as the Unity documentation is outdated on this topic. + +For the native C library `mrwebrtc.dll` things are a bit more complex. The DLL is compiled for a particular platform and architecture, in addition of the Debug or Release build configurations, and the correct variant needs to be used. On Windows, the Unity Editor needs a **64-bit Desktop** variant (`Debug` or `Release`); it is available from the `bin\Win32\x64\Release` folder (`Win32` is an alias for `Desktop`), and should be copied to the `libs\unity\library\Runtime\Plugins\Win32\x86_64\` folder. Again this is done automatically by the Visual Studio build process, but can be done manually with the following commands: + +```cmd +cd /D D:\testproj +xcopy D:/mr-webrtc/bin/Win32/x64/Release/mrwebrtc.dll libs/unity/library/Runtime/Plugins/Win32/x86_64/ +``` + +## Importing the library + +Once the necessary binaries have been added to `libs\unity\library\Runtime\Plugins`, the Unity library UPM package can be imported into any number of Unity projects. + +> [!WARNING] +> +> It is critical to setup the binaries first, before importing into a project and opening the Unity editor, otherwise the import settings might get overwritten by Unity. See [Configuring the import settings](#configuring-the-import-settings) below for details. + +The Unity library already has the proper layout on disk of a UPM package, and a `package.json` file is provided. This means the package can be imported simply by following [the official Unity instructions for installing a local package](https://docs.unity3d.com/Manual/upm-ui-local.html). + +## Configuring the import settings + +_Note: This step is normally not necessary, as the `.meta` files are already checked in the git repository and properly configured. It can happen that Unity deletes and recreates those files, therefore the configuration process is explained in details here anyway._ + > [!IMPORTANT] -> **Be sure to build the solution before importing the Unity library package into any Unity project.** As part of the build, the libraries are copied to the `Plugins` folder of the Unity library. There are already some associated `.meta` files, which have been committed to the git repository, to inform Unity of the platform of each DLL and how to deploy it. If the Unity project is opened first, before the DLLs are present, Unity will assume those `.meta` files are stale and will delete them, and then later will recreate some with a different default config once the DLLs are copied. This leads to errors about modules with duplicate names. See the [Importing MixedReality-WebRTC](unity/helloworld-unity-importwebrtc.md) chapter of the "Hello, Unity World!" tutorial for more details. +> **Be sure to build the binaries before importing the Unity library package into any Unity project.** As part of the build, the libraries are copied to the `Plugins` folder of the Unity library. There are already some associated `.meta` files, which have been committed to the git repository, to inform Unity of the platform of each DLL and how to deploy it. If the Unity project is opened first, before the DLLs are present, Unity will assume those `.meta` files are stale and will delete them, and then later will recreate some with a different default config once the DLLs are copied. This leads to errors about modules with duplicate names. If done correctly then none of the below is necessary. + +The git repository comes with pre-configured `.meta` files already setup. However we detail below the manual steps to configure those `.meta` files for the sake of clarity, and in case Unity deleted those files because the binaries have not been built yet (although using `git reset` is a faster and safer way to recover them), or if users want to get rid of the UPM package and incorporate a custom copy of the MixedReality-WebRTC into their Unity project and modify it. + +When building a Unity application for a given platform, another variant of the MixedReality-WebRTC native C/C++ library than the one the Unity editor uses may be required to deploy on that platform. In order for the C# library to be truly platform-independent, the name of all native C/C++ library variants is the same: `mrwebrtc`. This allows the C# code to reference that DLL with [the same `DllImport` attribute path](https://docs.microsoft.com/en-us/dotnet/api/system.runtime.interopservices.dllimportattribute?view=netcore-3.1). But this also means that multiple files with the same name exist in different folders, and Unity needs to know which one is associated with which build variant, to be able to deploy the correct one only. This is done by configuring the platform associated with a DLL in the import settings in the Unity inspector. + +When importing a UPM package into a Unity project, the content of the UPM package can be accessed from the **Packages** group of the **Project** window. + +![Packages in the Project window](unity/helloworld-unity-1b.png) + +To configure the import settings: + +- In the **Project** window, select one of the `mrwebrtc.dll` files from the `Plugins` folder. +- The **Inspector** window now shows the import settings for the selected file, which contains option to configure the deploy platform(s) and architecture(s). + +For example, by selecting in the **Inspector** window: + +- **Include Platforms: WSAPlayer**, the DLL will be used by Unity on UWP platforms. _WSAPlayer_ is the name Unity uses for its UWP standalone player. +- **CPU** equal to **x86_64**, Unity will only deploy that DLL when deploying on a 64-bit Intel architecture. + +This way, multiple variants of the same-named `mrwebrtc.dll` can co-exist in different sub-folders of `Assets/Plugins/` and Unity will deploy and use the correct variant on each platform. + +> [!NOTE] +> If Unity complains about "_Multiple plugins with the same name 'mrwebrtc'_", then the configurations of the various `mrwebrtc.dll` files are not exclusive, and 2 or more files have been allowed for deploying on the same platform. Check the configuration of all variants again. + +For **Windows Desktop**, the native implementation DLL variants are: + +| Path | Include Platforms | Settings | Example use | +|---|---|---|---| +| `Plugins/Win32/x86` | Standalone | x86 | 32-bit Windows Desktop application | +| `Plugins/Win32/x86_64` | Editor | CPU = x86_64, OS = Windows | Unity Editor on Windows | +| | Standalone | x86_64 | 64-bit Windows Desktop application | + +For **Windows UWP**, the native implementation DLL variants are: + +| Path | Include Platforms | SDK | CPU | Example use | +|---|---|---|---|---| +| `Plugins/UWP/x86` | WSAPlayer | UWP | X86 | Microsoft HoloLens (1st gen) | +| `Plugins/UWP/x86_64` | WSAPlayer | UWP | X64 | 64-bit UWP Desktop app on Windows | +| `Plugins/UWP/ARM` | WSAPlayer | UWP | ARM | HoloLens 2 (compatibility) | + +> [!NOTE] +> UWP ARM64 is not supported. The ARM (32-bit) architecture variant can be used as a fallback on HoloLens 2 and other devices which support running 32-bit ARM applications on ARM64 hardware. + +For **Android**, the native implementation archive `mrwebrc.aar` is configured as: + +| Path | Include Platforms | Example use | +|---|---|---| +| `Plugins/Android/arm64-v8a` | Android | Android phone | + +In all cases the "Any Platform" setting must be unchecked. + +If all variants are installed, the resulting hierarchy should look like this in the **Project** window: + +```shell +Plugins +├─ Android +| └─ arm64-v8a +| └─ mrwebrtc.aar +├─ Win32 +| ├─ x86 +| | └─ mrwebrtc.dll +| └─ x86_64 +| └─ mrwebrtc.dll +└─ UWP + ├─ x86 + | └─ mrwebrtc.dll + ├─ x86_64 + | └─ mrwebrtc.dll + └─ ARM + └─ mrwebrtc.dll +``` + +Note that the `.meta` files where the import settings are saved do not appear in the **Project** window. ## Testing the build diff --git a/docs/manual/building.md b/docs/manual/building.md index 07ecd9cf4..e6b4f1ba0 100644 --- a/docs/manual/building.md +++ b/docs/manual/building.md @@ -1,10 +1,14 @@ # Building from sources -Building the C and C# libraries of MixedReality-WebRTC from sources involves two main steps: +> [!IMPORTANT] +> +> Building MixedReality-WebRTC from sources, and in particular the native `libwebrtc` implementation, is fairly involved, and is not required to use the various MixedReality-WebRTC libraries. Prebuilt binaries are available for C/C++ and C# project (NuGet packages) and Unity (UPM packages), which provide a much easier way to obtain and consume those libraries. See [Installation](installation.md) for details. -1. Building the native C library for the specific platform(s) of interest: - - [Bulding for Windows platforms (Desktop and UWP)](building-windows.md) - - [Bulding for Android (Unity)](android/building-android.md) +Building the C/C++ and C# libraries of MixedReality-WebRTC from sources involves two main steps: + +1. Building the native C/C++ library for the specific platform(s) of interest: + - [Building for Windows platforms (Desktop and UWP)](building-windows.md) + - [Building for Android (Unity)](android/building-android.md) 2. [Building the platform-independent C# library](building-cslib.md). On Windows, if you want to start right away with MixedReality-WebRTC, the recommended approach is to consume the precompiled binaries distributed as NuGet packages instead. See [Download](download.md) for details. There is currently no prebuilt Android binaries. diff --git a/docs/manual/download.md b/docs/manual/download.md index 3785665d2..678dd1df5 100644 --- a/docs/manual/download.md +++ b/docs/manual/download.md @@ -6,11 +6,11 @@ The **C/C++ library** and **C# library** are distributed as NuGet packages for W ## Unity library -UPM packages are available for download on the [GitHub Releases page](https://github.com/microsoft/MixedReality-WebRTC/releases). +UPM packages are available for download on [the GitHub Releases page](https://github.com/microsoft/MixedReality-WebRTC/releases). Alternatively, the packages can be installed directly from [the Mixed Reality UPM package registry](https://dev.azure.com/aipmr/MixedReality-Unity-Packages/_packaging?_a=feed&feed=Unity-packages) by Unity without needing a manual download; see [Installation](installation.md#unity-library) for details. The library package contains prebuilt binaries for all supported Unity platforms: Windows Desktop (x86, x64), UWP (x86, x64, ARM), and Android (ARM64). -See [Installation](installation.md#unity-library) for details on how to use those packages in an existing Unity project. +See [Installation](installation.md#unity-library) for details on how to use those packages in an existing Unity project, whether downloaded manually or directly through the Unity Package Manager (UPM). ## NuGet packages diff --git a/docs/manual/installation.md b/docs/manual/installation.md index d9fb33e2a..9b658efc8 100644 --- a/docs/manual/installation.md +++ b/docs/manual/installation.md @@ -35,8 +35,15 @@ This will add a dependency to the currently selected C++ project. If multiple pr ## Unity library -Starting from v2.0.0, a [UPM package](https://docs.unity3d.com/Manual/Packages.html) named `com.microsoft.mixedreality.webrtc` is the main distribution method for the Unity library. +Starting from v2.0.0, a [UPM package](https://docs.unity3d.com/Manual/Packages.html) named `com.microsoft.mixedreality.webrtc` is the main distribution method for the Unity library. An optional package `com.microsoft.mixedreality.webrtc.samples` is also available which contains some samples to show how to use the Unity library. This samples package depends on the library package, and should not be used in production. -This package is currently distributed as [an on-disk package (local package)](https://docs.unity3d.com/Manual/upm-ui-local.html) containing prebuilt binaries for all supported Unity platforms. Follow [the official Unity instructions](https://docs.unity3d.com/Manual/upm-ui-local.html) to import the library package into a Unity project via the Unity Package Manager (UPM) window. +The library package contains prebuilt binaries for all supported Unity platforms: -An optional package `com.microsoft.mixedreality.webrtc.samples` is also available which contains some samples to show how to use the Unity library. This samples package depends on the library package. It should not be used in production. +- Windows Desktop (x86, x64) +- Windows UWP (x86, x64, ARM) +- Android (ARM64) + +These packages are currently distributed in two ways: + +- As [on-disk packages (local packages)](https://docs.unity3d.com/Manual/upm-ui-local.html) downloaded from [the GitHub Releases page](https://github.com/microsoft/MixedReality-WebRTC/releases). Follow [the official Unity instructions](https://docs.unity3d.com/Manual/upm-ui-local.html) to import the package into a Unity project via the Unity Package Manager (UPM) window. +- Directly via the Unity Package Manager by configuring UPM to use the official [Mixed Reality UPM package registry](https://dev.azure.com/aipmr/MixedReality-Unity-Packages/_packaging?_a=feed&feed=Unity-packages). See the [Unity tutorial](unity/helloworld-unity-importwebrtc.md) for details on how to configure the register and import the packages into an existing Unity project. diff --git a/docs/manual/unity/helloworld-unity-2.png b/docs/manual/unity/helloworld-unity-2.png index f66eeb167..81db8eaae 100644 Binary files a/docs/manual/unity/helloworld-unity-2.png and b/docs/manual/unity/helloworld-unity-2.png differ diff --git a/docs/manual/unity/helloworld-unity-3.png b/docs/manual/unity/helloworld-unity-3.png deleted file mode 100644 index d4bbf11ef..000000000 Binary files a/docs/manual/unity/helloworld-unity-3.png and /dev/null differ diff --git a/docs/manual/unity/helloworld-unity-4.png b/docs/manual/unity/helloworld-unity-4.png deleted file mode 100644 index 5fc810a3f..000000000 Binary files a/docs/manual/unity/helloworld-unity-4.png and /dev/null differ diff --git a/docs/manual/unity/helloworld-unity-importwebrtc.md b/docs/manual/unity/helloworld-unity-importwebrtc.md index da5ca55c5..f8104c6cc 100644 --- a/docs/manual/unity/helloworld-unity-importwebrtc.md +++ b/docs/manual/unity/helloworld-unity-importwebrtc.md @@ -6,135 +6,50 @@ In order to use the Unity library, the following pieces are required: - C# library : `Microsoft.MixedReality.WebRTC.dll` (single universal module for all platforms and architectures) - Unity library itself (scripts and assets) -> [!NOTE] -> There is currently no pre-packaged distribution method for Unity which include prebuilt binaries. - -## Copying the binaries - -The binaries can be obtained either prebuilt from the NuGet packages, or from a local build of the Visual Studio solution provided in [the GitHub repository](https://github.com/microsoft/MixedReality-WebRTC/). - -- **NuGet packages** do not require any build step, so are the most convenient approach. But they are generally only available for stable releases (_e.g._ [the `release/1.0` branch](https://github.com/microsoft/MixedReality-WebRTC/tree/release/1.0/)), so will be missing any newer development available on [the `master` branch](https://github.com/microsoft/MixedReality-WebRTC/tree/master/). - -- **A local build** via the Visual Studio solution `Microsoft.MixedReality.WebRTC.sln` allows accessing the latest features, but may contain some API breaking changes since the latest stable release, so may require some code changes when upgrading an existing project using an earlier API version. See [Building from Sources](../building.md) for details. - -### NuGet packages - -The native implementation and C# library of MixedReality-WebRTC are available precompiled via NuGet packages. See the [GitHub Releases page](https://github.com/microsoft/MixedReality-WebRTC/releases) for the latest packages. - -The packages can be downloaded from [nuget.org](https://www.nuget.org/profiles/MicrosoftMR). Once downloaded, they can be extracted by simply renaming their extension from `.nupkg` to `.zip`, and using any standard ZIP archive extraction method. After the packages are extracted, the DLLs can be copied as detailed on the **Unity library** section of the [installation page](../installation.md). - -### Local solution build - -If the native implementation and C# library are compiled from sources as explained in the [Building from Sources](../building.md) page, they are available in one of the sub-folders under the `bin/` folder at the root of the repository of the MixedReality-WebRTC project. - -The C# library `Microsoft.MixedReality.WebRTC.dll` is a .NET Standard 2.0 library. This means it is compatible with all CPU architectures. The C# library is available from `bin\netstandard2.0\Debug` or `bin\netstandard2.0\Release` depending on the build configuration which was compiled. In doubt you should use the `Release` configuration, which can provide better performance. This module needs to be copied somehwere into the `libs\unity\library\Runtime\Plugins\` folder of the git repository checkout. This is done automatically by the build process of the Visual Studio solution, but can also be done via the command line with `xcopy`, assuming that the git repository of MixedReality-WebRTC was cloned in `D:\mr-webrtc`: - -```cmd -cd /D D:\testproj -xcopy D:/mr-webrtc/bin/netstandard2.0/Release/Microsoft.MixedReality.WebRTC.dll libs/unity/library/Runtime/Plugins/Win32/x86_64/ -``` - -_Note_: By convention, and because of past experiences of getting errors when doing otherwise, the C# library is copied to the `Win32\x86_64` sub-folder where the native C library for the Unity editor is also located. It is unclear if this is best practice, as the Unity documentation is outdated on this topic. - -For the native C library `mrwebrtc.dll` things are a bit more complex. The DLL is compiled for a particular platform and architecture, in addition of the Debug or Release build configurations, and the correct variant needs to be used. On Windows, the Unity Editor needs a **64-bit Desktop** variant (`Debug` or `Release`); it is available from the `bin\Win32\x64\Release` folder (`Win32` is an alias for `Desktop`), and should be copied to the `libs\unity\library\Runtime\Plugins\Win32\x86_64\` folder. Again this is done automatically by the Visual Studio build process, but can be done manually with the following commands: - -```cmd -cd /D D:\testproj -xcopy D:/mr-webrtc/bin/Win32/x64/Release/mrwebrtc.dll libs/unity/library/Runtime/Plugins/Win32/x86_64/ +The Unity library is distributed as a [UPM package](https://docs.unity3d.com/Manual/Packages.html) containing all those components, including the prebuilt binaries for all supported Unity platforms. The library package itself, as well as the optional samples package, can be imported into an existing Unity project in two ways: + +- Manually by downloading the UPM package(s) from [the GitHub Releases page](https://github.com/microsoft/MixedReality-WebRTC/releases). Packages imported that way are referred to by Unity as [_on-disk packages_ or _local packages_](https://docs.unity3d.com/Manual/upm-ui-local.html), and the installation process is described in [the official Unity instructions](https://docs.unity3d.com/Manual/upm-ui-local.html). +- (Semi-)automatically via the UPM window inside the Unity Editor, after configuring UPM to use the official [Mixed Reality UPM package registry](https://dev.azure.com/aipmr/MixedReality-Unity-Packages/_packaging?_a=feed&feed=Unity-packages). + +In the following, we describe the latter method. + +As of Unity versions 2018.4 LTS and 2019.4 LTS, the Unity Package Manager (UPM) supports custom UPM package registries, but does not have any UI to configure those. Instead, users need to modify the `/Packages/manifest.json` file inside the project where they want to import the packages. + +Open the `/Packages/manifest.json` file inside a text editor. The file should start with (or at least contain) a "dependencies" section listing all packages that the current project depends on. Insert a new section called "scopedRegistries" to enable the official Microsoft Mixed Reality UPM registry, and add the `com.microsoft.mixedreality.webrtc` package (library), and optionally the `com.microsoft.mixedreality.webrtc.samples` package (samples), as dependencies. + +```json +{ + "scopedRegistries": [ + { + "name": "Microsoft Mixed Reality", + "url": "https://pkgs.dev.azure.com/aipmr/MixedReality-Unity-Packages/_packaging/Unity-packages/npm/registry/", + "scopes": ["com.microsoft.mixedreality"] + } + ], + "dependencies": { + "com.microsoft.mixedreality.webrtc": "2.0.0-preview.1", + "com.microsoft.mixedreality.webrtc.samples": "2.0.0-preview.1", + ...existing dependencies... ``` -## Importing the library +> [!NOTE] +> +> Merely configuring the Mixed Reality UPM registry is not enough, as current LTS versions of Unity do not support listing packages from it automatically. Therefore the packages have to be added manually too in the "dependencies" section. -Once the necessary binaries have been added to `libs\unity\library\Runtime\Plugins`, the Unity library UPM package can be imported into any number of Unity projects. +Once done, save the file and return to Unity. UPM will resolve the new packages via the configured registry, download the packages, and import them inside the Unity project. > [!WARNING] > -> It is critical to setup the binaries first, before importing into a project and opening the Unity editor, otherwise the import settings might get overwritten by Unity. See [Configuring the import settings](#configuring-the-import-settings) below for details. - -The Unity library already has the proper layout on disk of a UPM package, and a `package.json` file is provided. This means the package can be imported simply by following [the official Unity instructions for installing a local package](https://docs.unity3d.com/Manual/upm-ui-local.html). - -## Configuring the import settings +> The library package `com.microsoft.mixedreality.webrtc` currently contains the debug symbols (PDBs) for Windows platforms, and is therefore fairly large (100+MB). Unity _will_ take some time to download it, and may stop for several minutes at the "resolving" step (modal dialog). Be patient and let the process complete. -This step is normally not necessary. +After that the packages will be visible in the UPM window. It is recommended to ensure you have the latest version installed. -The git repository comes with pre-configured `.meta` files already setup. However we detail below the manual steps to configure those `.meta` files for the sake of clarity, and in case Unity deleted those files because the binaries have not been built yet (although using `git reset` is a faster and safer way to recover them), or if users want to get rid of the UPM package and incorporate a custom copy of the MixedReality-WebRTC into their Unity project and modify it. +![Packages in the Project window](helloworld-unity-2.png) -When building a Unity application for a given platform, another variant of the MixedReality-WebRTC native C library than the one the Unity editor uses may be required to deploy on that platform. In order for the C# library to be truly platform-independent, the name of all native C library variants is the same: `mrwebrtc`. This allows the C# code to reference that DLL with [the same `DllImport` attribute path](https://docs.microsoft.com/en-us/dotnet/api/system.runtime.interopservices.dllimportattribute?view=netcore-2.1). But this also means that multiple files with the same name exist in different folders, and Unity needs to know which one is associated with which build variant, to be able to deploy the correct one only. This is done by configuring the platform associated with a DLL in the import settings in the Unity inspector. - -> [!IMPORTANT] -> The `mrwebrtc.dll` module was in v1.0 named `Microsoft.MixedReality.WebRTC.Native.dll` when this module was also the C++ library. The `Microsoft.MixedReality.WebRTC.Native` name is still in use in some NuGet packages, so depending on the installation method one or the other name are used. However the Unity project must use the `mrwebrtc.dll` name only for the C# library to find it. - -When importing a UPM package into a Unity project, the content of the UPM package can be accessed from the **Packages** group of the **Project** window. +The packages content can be inspected from **Project window** > **Packages**: ![Packages in the Project window](helloworld-unity-1b.png) -To configure the import settings: - -- In the **Project** window, select one of the `mrwebrtc.dll` files from the `Plugins` folder. -- The **Inspector** window now shows the import settings for the selected file, which contains option to configure the deploy platform(s) and architecture(s). - -For example, by selecting in the **Inspector** window: - -- **Include Platforms: WSAPlayer**, the DLL will be used by Unity on UWP platforms. _WSAPlayer_ is the name Unity uses for its UWP standalone player. -- **CPU** equal to **x86_64**, Unity will only deploy that DLL when deploying on a 64-bit Intel architecture. - -This way, multiple variants of the same-named `mrwebrtc.dll` can co-exist in different sub-folders of `Assets/Plugins/` and Unity will deploy and use the correct variant on each platform. - -> [!NOTE] -> If Unity complains about "_Multiple plugins with the same name 'mrwebrtc'_", then the configurations of the various `mrwebrtc.dll` files are not exclusive, and 2 or more files have been allowed for deploying on the same platform. Check the configuration of all variants again. - -For **Windows Desktop**, the native implementation DLL variants are: - -| Path | Include Platforms | Settings | Example use | -|---|---|---|---| -| `Plugins/Win32/x86` | Standalone | x86 | 32-bit Windows Desktop application | -| `Plugins/Win32/x86_64` | Editor | CPU = x86_64, OS = Windows | Unity Editor on Windows | -| | Standalone | x86_64 | 64-bit Windows Desktop application | - -For **Windows UWP**, the native implementation DLL variants are: - -| Path | Include Platforms | SDK | CPU | Example use | -|---|---|---|---|---| -| `Plugins/UWP/x86` | WSAPlayer | UWP | X86 | Microsoft HoloLens (1st gen) | -| `Plugins/UWP/x86_64` | WSAPlayer | UWP | X64 | 64-bit UWP Desktop app on Windows | -| `Plugins/UWP/ARM` | WSAPlayer | UWP | ARM | HoloLens 2 (compatibility) | - -For **Android**, the native implementation archive `mrwebrc.aar` is configured as: - -| Path | Include Platforms | Example use | -|---|---|---| -| `Plugins/Android/arm64-v8a` | Android | Android phone | - -In all cases the "Any Platform" setting must be unchecked. - -> [!NOTE] -> ARM64 is not supported. The ARM (32-bit) architecture variant can be used as a fallback on HoloLens 2 and other devices which support running 32-bit ARM applications on ARM64 hardware. - -![Configure the import settings for a native C++ DLL for UWP](helloworld-unity-3.png) - -If all variants are installed, the resulting hierarchy should look like this in the **Project** window: - -```shell -Plugins -├─ Android -| └─ arm64-v8a -| └─ mrwebrtc.aar -├─ Win32 -| ├─ x86 -| | └─ mrwebrtc.dll -| └─ x86_64 -| └─ mrwebrtc.dll -└─ UWP - ├─ x86 - | └─ mrwebrtc.dll - ├─ x86_64 - | └─ mrwebrtc.dll - └─ ARM - └─ mrwebrtc.dll -``` - -Note that the `.meta` files where the import settings are saved do not appear in the **Project** window. - ---- Next : [Creating a peer connection](helloworld-unity-peerconnection.md)