HoloJs apps
The easiest way to create a HoloJs app is to generate one with Spin. You can then inspect the auto-generated app to understand it's structure.The JSON file
A HoloJs app is comprised of JavaScript files and resource files alongside a JSON file that stores a list of these files:
{
"scripts":["threejs/three.js", "app.js"],
"resources":["media/images/crate.png"]
}
"scripts":["threejs/three.js", "app.js"],
"resources":["media/images/crate.png"]
}
It is important that all scripts and resources reside under the same directory as the JSON file. Paths in the JSON file are resolved relative to the location of the JSON file itself. HoloJs will not read files outside of the app's directory.
For web hosted JSON files, scripts and resources are resolved relative to the base URL of the JSON file.
Note: All text files must be UTF8 encoded
The XRSX package
To simplify sharing of apps, the JSON file and all scripts and resources can be packaged in a XRSX file. HoloJs will automatically decompress and execute files with this extension.The Spin tool can be used to create XRSX packages from a JSON file:
spin publish --source [path_to_app_json] --destination [path_to_xrs]
If crafting the XRSX file manually, please consider the following:
- The XRSX file is just a zip file containing the files in the app's directory (scripts, resources, json file)
- The app's JSON file must be named app.xrs in the XRSX package
- Paths and file names in the XRSX file are case sensitive; HoloJs uses lower case lookup in XRSX files and consequently files should be archived with lower case names.
Script files
- Script files are standard JavaScript code (UTF8 encoded). They execute in the order they appear in the JSON file. They can be minified, uglified etc.
-
Scripts check if they execute under HoloJs by looking for the holojs object in the navigator:
const isHoloJs = typeof navigator.holojs !== 'undefined';
Rendering
- In HoloJs, scripts always render to the canvasvr. Use the following code to obtain the canvasvr:
const canvas = document.createElement('canvasvr');That is all you need to initialize the rendering canvas. You can obtain a webgl context for it and start rendering.
Note: You cannot modify the size of the canvasvr or obtain a 2d context for it.If you want to reuse code in a web browser:
const canvas = document.createElement(isHoloJs ? 'canvasvr' : 'canvas');
if (isHoloJs === false) {
// If running in browser, add the canvas to the DOM
canvas.width = window.innerWidth;
canvas.height = window.innerHeight;
document.body.appendChild(canvas);
}
- You can create additional canvases for offscreen rendering, but as of now only the 2d context is supported for them and with a limited instruction set. Offscreen canvases are intended to be used for image scaling and text rendering. They can be used as textures for the webgl context.
WebVR
HoloJs apps should always attempt to render for WebVR. The underlying HoloJs runtime always initializes in VR mode if a headset is available (or on the HoloLens). Unlike in a web browser, the JavaScript code can request access to the VR headset without user input. Just execute this code:
navigator.getVRDisplays().then(
function (value) {
if (value.length > 0) {
// Add code here to initialize your renderer for VR. This example assumes a ThreeJS renderer
renderer.vr.enabled = true;
renderer.vr.setDevice(value[0]);
value[0].requestPresent([{ source: renderer.domElement }]);
}
});
This code differs from a web browser code only by the fact that it can be called at any time, not just on a user
action callback.
function (value) {
if (value.length > 0) {
// Add code here to initialize your renderer for VR. This example assumes a ThreeJS renderer
renderer.vr.enabled = true;
renderer.vr.setDevice(value[0]);
value[0].requestPresent([{ source: renderer.domElement }]);
}
});
If a WebVR device is not available, the app can continue to render in simple mode.