1 files changed, 80 insertions, 0 deletions
diff --git a/gfx/vr/service/openvr/README.mozilla b/gfx/vr/service/openvr/README.mozilla
new file mode 100644
index 0000000000..5a8e502192
--- /dev/null
+++ b/gfx/vr/service/openvr/README.mozilla
@@ -0,0 +1,80 @@
+This directory contains files from the OpenVR SDK, version 1.11.11.
+
+This SDK contains the OpenVR API interface headers and functions to load the
+OpenVR runtime libraries which actually implement the functionality. The
+loading functions parse a .json file in a pre-defined location on the
+end-user's machine to get details used to bind the correct runtime library.
+The OpenVR implementation ensures forward and backwards compatibility as of
+the current version.
+
+Updated versions of the OpenVR SDK are available on Github:
+
+https://github.com/ValveSoftware/openvr
+
+
+We only use some files from the SDK:
+
+- We strip out files such as C# headers, plain C API versions, and files
+  needed only when implementing OpenVR drivers.
+
+- CMake related files, such as CMakeLists.txt are skipped as we use moz.build
+  files to configure the library.
+
+- The "src/jsoncpp.cpp" file and the "src/json" directory can be skipped. OpenVR
+  uses the jsoncpp library, which we have already imported elsewhere. If
+  warnings about using deprecated jsoncpp classes show up during compilation
+  you might need to reapply the patch in bug 1598288. It replaces uses of the
+  `Json::Reader` and `Json::StyledWriter` classes with the more modern
+  `Json::CharReaderBuilder` and `Json::StreamWriterBuilder`.
+
+
+Steps to update the library:
+
+- Copy "README.md" from the root of the openvr repo to the "gfx/vr/service/openvr"
+  directory.
+
+- Copy "headers/openvr.h" to "gfx/vr/service/openvr/headers" directory. The other files
+  in this directory can be ignored.
+
+- The rest of the files in the "src" directory and the "src/vrcommon" are copied
+  to the "gfx/vr/service/openvr/src" directory.
+
+- Update "gfx/vr/service/openvr/moz.build" when files are added or removed.
+
+- Update the "strtools_public.h" and "strtools_public.cpp" files, commenting out
+  the "Uint64ToString", "wcsncpy_s", and "strncpy_s" functions.
+  The "Uint64ToString" function name conflicts with another used in Gecko and
+  the "errno_t" return type returned by the other functions is not defined in
+  Mozilla's macOS continuous integration build environments.  Fortunately, the
+  OpenVR SDK does not use these functions.
+
+- Replace the #define VR_INTERFACE in openvr.h to avoid extern'ing the functions.
+  Unlike the usual OpenVR API builds, we are not building a separate dll.
+
+- Add explicit in CVRSettingHelper constructor.
+
+- In strtools_public.cpp/.h, ensure that UTF16to8 and UTF8to16 are only
+  compiled under
+      #if defined( _WIN32 )
+  and redefine those functions to use ::WideCharToMultiByte and
+  MultiByteToWideChar, respectively. These are modified because the original
+  implementations contain unsupported try-catch.
+
+- In strtools_public.cpp, remove the definition of convert_type.
+
+- In strtools_public.cpp, remove the include of <codecvt>, as this causes
+  problems in compiling on Linux.
+
+- In pathtools_public.cpp/.h, comment out Path_UrlToFilePath and
+  Path_FilePathToUrl to avoid a compile error because 'alloca' isn't defined.
+
+- In vrpathregistry_public.cpp, CVRPathRegistry_Public::BLoadFromFile contains
+  a try-catch, which is not permitted. This code is simply commented out, but
+      Bug 1640068 - OpenVR code can fail JSON parsing and raise exceptions
+  is filed to address a safe fallback in the error condition.
+
+- Update this README.mozilla file with the new OpenVR SDK version and any
+  additional steps needed for newer versions.
+
+- Ensure that any changes made within the OpenVR files have comments including
+  the string "Mozilla" and reference this file for easy identification.