Update documentation and add UPM registry mentions (#495)

Update the documentation with the various feedback items from #150, and
move the .meta files configuration to the "Building from Sources"
section, and add references to the new UPM package register for Mixed
Reality.

Bug: #150

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
 

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
 

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
 

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.

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
 

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.