Merge pull request #55 from OSVR/updateChanges

Updated documentation and documentation-building.

Author: rpavlik

CONTRIBUTING.md

@@ -8,17 +8,20 @@ A few tips:
 
 The OSVR system consists of a number of repositories, many of which are in the [OSVR organization on GitHub][osvr-org].
 
-The `OSVR-Unity` repo consists of two parts: the Managed-OSVR bindings for using OSVR ClientKit from .NET-based languages, and the OSVR-Unity integration and sample code.
+The `OSVR-Unity` repo contains the code that integrates OSVR, via the [Managed-OSVR][] bindings (for using OSVR ClientKit from .NET-based languages), with the Unity game engine, as well as some sample code.
 
-- If you've got an issue to report, a bug fix, or a feature addition to those components: **yes**, you're in the right spot!
+[Managed-OSVR]: https://github.com/OSVR/Managed-OSVR
+
+- If you've got an issue to report, a bug fix, or a feature addition specific to the OSVR-Unity integration components: **yes**, you're in the right spot! (If you aren't sure if it's Unity-specific or in Managed-OSVR, it's fine to start here.)
+- If you're got something that's related to .NET but not Unity-specific: **you're close** - see the [Managed-OSVR][] repo for the non-Unity-specific OSVR .NET bindings.
 - If you have an issue, bug fix, or other contribution related to the OSVR server (which comes bundled with an OSVR-Unity binary snapshot) or one of the plugins: **you're close** - see the [OSVR-Core](https://github.com/osvr/OSVR-Core) repo for the server and its bundled plugins.
 - If you have a hardware or software issue related to OSVR but aren't sure exactly where it fits: **let us know with a support ticket at <http://support.osvr.com>**
 
 [osvr-org]: https://github.com/osvr
 
 ## Getting ready
 
-General "getting started" instructions can be found at <http://wiki.osvr.com>.
+General "getting started" instructions can be found at <http://osvr.github.io>.
 
 When making pull requests, please fork the project and create a topic branch off of the `master` branch.
 (This is what GitHub does by default if you start editing with your web browser.)
@@ -31,7 +34,7 @@ Avoid merging from master into your topic branch: if you need a change from mast
 
 Try to develop code that is portable (not particularly tied to a single operating system/compiler/etc) - OSVR runs on a number of platforms, and while we don't expect you to have all of them to test on, it's good to keep in mind.
 
-Note that the Managed-OSVR code should be entirely Unity-independent, so it can be used in other .NET-based applications. The reason for the specific version of the .NET framework it is using is for compatibility with the runtime used by Unity.
+Please note the compatible versions of Unity in the project README, and make sure that any change is either optional (and properly version-guarded) or works all the way back to the oldest version of Unity we support.
 
 If you're adding something reasonably testable, please also add a test.
 If you're touching code that already has tests, make sure they didn't break.

OSVR-Unity/CHANGES.md

@@ -3,27 +3,47 @@
 This is an abbreviated changelog for the OSVR Unity Plugin.
 
 Use git for a full changelog.
-##Recent Changes (updated 30-June-2015)
+##Recent Changes
 
-##Update/rename of Managed-OSVR assembly v0.1-94-gf4d3c44
-- The Unity plugin now uses the external Managed-OSVR project and assembly, providing improved reliability, development progress, and 64-bit support.
-- Projects upgrading to the new version should remove all copies of `ClientKit.dll` from their `Assets` (including subdirectories) before importing the updated package, as the file has been renamed to `OSVR.ClientKit.dll` to match .NET conventions.
+### Update/rename of Managed-OSVR assembly
+> 30-June-2015 - v0.2 (commit 429546f) and approximately v0.1-94-gf4d3c44
+
+- The Unity plugin now uses the external [Managed-OSVR][] project and assembly, providing improved reliability, development progress, and **64-bit support**. Yes, this means you can now use OSVR-Unity with the default Windows version of Unity 5.x (which is 64-bit unless you seek out otherwise).
+- Projects upgrading to the new version should remove all copies of `ClientKit.dll` from their `Assets` (including subdirectories) **before** importing the updated package, as the file has been renamed to `OSVR.ClientKit.dll` to match .NET conventions.
+- Projects upgrading to the new version may want to also remove the entire `OSVRUnity` folder **before** importing the updated package, to ensure any references to JSON display descriptor files are removed, as these files are no longer included in the Unity plugin.
+
+[Managed-OSVR]: https://github.com/OSVR/Managed-OSVR/
+
+### Displays Folder removed
+> 31-May-2015 - v0.1.78-ge7ad2a0
 
-##Displays Folder removed v0.1.78-ge7ad2a0 (31-May-2015)
 - Unity developers no longer need to assign a JSON display descriptor in the Unity editor. The OSVR server sends the display descriptor to Unity, so switching HMDs requires changing the server config file to use a different display, not recompiling your Unity project. 
 
-##DLL Search Path v0.1-69-gb80966b (31-March-2015)
-- The built executable will now find the plugins it needs in the _Data folder. Previously, the executable had to be in the same directory with Assets/Plugins. That is no longer necessary.
+### DLL Search Path
+> 31-March-2015 - v0.1-69-gb80966b
+
+- The built executable will now find the plugins it needs in the _Data folder. Previously, the executable had to be in the same directory with Assets/Plugins. That is no longer necessary.  (Basically, don't worry about copying DLLs - it should always work correctly on its own, whether you're in the editor or a build.)
+
+### Substantially Reduced Latency
+> 30-March-2015 - v0.1-65-g09dc6fa
+
+- We're now handling OSVR messages more frequently (in more steps of the Unity run loop) so rendering, among other interactions, has much fresher data.
+
+### External Json File
+> 28-March-2015 - v0.1-56-gf2d8bab
 
-##External Json File v0.1-56-gf2d8bab (28-March-2015)
 - The JSON file containing display configuration can now be read from a file at runtime. To do this, add a config file "hmd.json" to the _Data folder that is created in a build. The format of the JSON file has not changed at all. It is the same file you would drag-and-drop onto the DisplayInterface component on your VRDisplayTracked prefab. If "hmd.json" does not exist in the Data folder (and it won't by default unless you put it there), then the plugin will look for the JSON file assigned in the DisplayInterface component in your scene. If that also has not been assigned, it will fall back to reading OSVR's /display parameter (this will eventually be the default).
 
-##Distortion v0.1-55-g046c709(20-March-2015)
-- Unity 4 Free limitations. The new distortion shader will not work with Unity 4 Free version. It will work with Unity 4 Pro or Unity 5. If you are using Unity 4 Free, everything will still work but there won't be any distortion. This is due to the distortion shader using a render to texture pass.
+### Distortion
+> 20-March-2015 - v0.1-55-g046c709
+
+- For HMDs that require it, the plugin can turn on a customized distortion shader. This works with Unity 4 Pro or Unity 5. If you're using Unity 4 Free, you might see an error or warning, and there won't be distortion (due to render to texture pass required), but everything else will still work fine.
 - Fixed Timestep was changed from 0.2 to 0.01667. This is how often FixedUpdate() gets called. The change should result in a more comfortable VR experience, but make sure it doesn't break any physics in your game.
 - Changed the default quality settings. Turned on 4x AA and disabled shadows.
 
-##Unity 5 Update v0.1-55-g046c709 (updated 18-March-2015)
-- Refactored VRHead.cs and VREye.cs to be Unity 5-friendly (mostly instances of "camera" that needed to become GetComponent<Camera>()). Upgrading from Unity 4 to Unity 5 should be seamless.
-- VRDisplayTracked.prefab has been updated to use the json descriptor file for the HDK by default. If you are using another HMD, be sure to set the corresponding json file on the VRDisplayTracked prefab's DisplayInterface script. 
+### Unity 5 Update
+> 18-March-2015 - v0.1-55-g046c709
+
+- Refactored VRHead.cs and VREye.cs to be Unity 5-friendly (mostly instances of "camera" that needed to become `GetComponent<Camera>()`). Upgrading from Unity 4 to Unity 5 should be seamless.
+- `VRDisplayTracked.prefab` has been updated to use the json descriptor file for the HDK by default. If you are using another HMD, be sure to set the corresponding json file on the `VRDisplayTracked` prefab's `DisplayInterface` script. 
 - Fixed issue with stereo overlap and roll for HMDs with multiple video inputs.

README.md

@@ -6,35 +6,33 @@
 > For support, see <http://support.osvr.com>
 
 ## .NET Binding for OSVR - "Managed-OSVR"
-The Unity integration is based on the [Managed-OSVR][] .NET binding for OSVR, which is now maintained in a separate repository. That code is entirely Unity-independent so it can be used in other applications/frameworks.
+The Unity integration is based on the [Managed-OSVR][] .NET binding for OSVR, which is maintained in a separate repository. That code is entirely Unity-independent so it can be used in other applications/frameworks.
 
 [Managed-OSVR]: https://github.com/OSVR/Managed-OSVR
 
 ## OSVR Unity Integration
 The development "project" for Unity is in the `OSVR-Unity` directory. We are currently maintaining support for 4.6.1 as well as 5.x in the same tree, so be aware of that if you're using a newer version that you don't break the older version. (You can parallel-install different versions of Unity, you just need to specify a different install directory). This is the project used to generate the `.unitypackage` file (there is an editor script that does it for the CI's sake).
 
-The `OSVR-Unity` directory contains its own README with some basic documentation that is shipped with the built version.
+The `OSVR-Unity` directory contains its own [README](OSVR-Unity/README.md) with some basic documentation that is shipped with the built version, as well as a [CHANGES](OSVR-Unity/CHANGES.md) file (also shipped with builds) that should be updated when changes that affect consumers of this project (users of the plugin) are made.
 
 Note that if you're looking at the source, you'll need to download and import the Managed-OSVR project artifacts, see below.
 
-
 ## Development Information
+When the `build-for-unity.cmd` script in [Managed-OSVR][] is run (by the CI or a human), it generates a tree with `Managed-OSVR-Unity` as the root directory.
 
-### Managed-OSVR
-When the `build-for-unity.cmd` script is run (by the CI or a human) in Managed-OSVR, it generates a tree with `Managed-OSVR-Unity` as the root directory. The contents of that (which will be a `.dll`, and some additional subdirectories and files) should be moved to the `OSVR-Unity/Assets/Plugins` directory.
-
-`install-managed-osvr.cmd` can do this if you place the `Managed-OSVR-Unity` in the root of this repository.
+`install-managed-osvr.cmd` can put those files in the right spot if you place the `Managed-OSVR-Unity` in the root of this repository first. Otherwise, the contents of that (which will be a `.dll`, and some additional subdirectories and files) should be moved to the `OSVR-Unity/Assets/Plugins` directory.
 
 ### OSVR-Unity
 This contains the source project used to generate `.unitypackage` files, since that seems more useful as "source" than a repo containing a `.unitypackage` file. Any one of the scenes should work to get you in there. There is an editor script to automate the bundling of a `.unitypackage` for the sake of CI.
 
 ### Other files
 
-- `third-party/discount-2.1.6-win32` - This contains binaries of a liberally-licensed Markdown-compatible file formatter, used by CI to generate HTML documentation from the markdown README in OSVR-Unity.
-- `prep-package.cmd` - Used by CI to create a directory that will eventually be packed as a snapshot, copy the source into it, and format the Unity readme markdown file as HTML. Not used in the course of normal development.
+- `install-managed-osvr.cmd` - A script to copy the output of a Managed-OSVR build to the right spot in the current repo, given that you place the `Managed-OSVR-Unity` directory (produced by the `build-for-unity.cmd` script over in Managed-OSVR) in the root of this repository first.
+- `prep-package.cmd` - Used by CI to create a directory that will eventually be packed as a snapshot, format the Unity readme and other markdown files as HTML, and copy files into the snapshot directory as well as the `OSVR-Unity` directory. Not used in the course of normal development.
 - `build-unity-packages.cmd` - Used by CI (but potentially others as well) to invoke the Unity editor script that packs the Unity plugin into a `.unitypackage` file. Requires that the Managed-OSVR build already have been run to copy over the .NET assembly and native DLLs into the right place in the tree. It copies that `.unitypackage` file into the distribution directory made by `prep-package.cmd` if that directory exists.
 - `unity-generate.lua` - Generates some very repetitive code wrapping the raw C-style pinvoke callbacks in something more .NET-idiomatic. It can be run with any reasonably recent version of a Lua interpreter, and its output should be placed into `OSVR-Unity/Assets/OSVRUnity/src/InterfaceCallbacks.cs` in the designated area (see comments in that file)
+- `third-party/discount-2.1.6-win32` - This contains binaries of a liberally-licensed Markdown-compatible file formatter, used by CI (specifically `prep-package.cmd`) to generate HTML documentation from the markdown files in OSVR-Unity.
 
 ## License
 
-This project: Licensed under the Apache License, Version 2.0.
+This project: Licensed under the Apache License, Version 2.0.

prep-package.cmd

@@ -4,11 +4,15 @@ mkdir OSVR-Unity-Dist
 
 rem the -F 0x4 is to turn off smartypants.
 third-party\discount-2.1.6-win32\markdown.exe -F 0x4 -o README.html OSVR-Unity/README.md
+xcopy README.html OSVR-Unity\Assets\OSVRUnity /Y
 move README.html OSVR-Unity-Dist\
 third-party\discount-2.1.6-win32\markdown.exe -F 0x4 -o CONTRIBUTING.html CONTRIBUTING.md
+xcopy CONTRIBUTING.html OSVR-Unity\Assets\OSVRUnity /Y
 move CONTRIBUTING.html OSVR-Unity-Dist\
 
 
 rem Copy the license and the notice
 xcopy LICENSE OSVR-Unity-Dist /Y
-xcopy NOTICE OSVR-Unity-Dist /Y
+xcopy LICENSE OSVR-Unity\Assets\OSVRUnity /Y
+xcopy NOTICE OSVR-Unity-Dist /Y
+xcopy NOTICE OSVR-Unity\Assets\OSVRUnity /Y