News • Examples • Documentation • Download • Buy • Forum • Contact
NOTE: This page is from an older version, see the latest version here.

WebVR Plugin webvr.js Version 1.20.1

  • krpano WebVR / MobileVR support:
    • WebVR support means using the browsers WebVR API when available. Here the browser and system will do the head- and position-tracking and the lens-distortion. That's the best-quality and best-performance case but requires a system and a browser with WebVR support.
    • MobileVR support means 'manual' VR support for mobile devices. That will be used as fallback when the browser doesn't support the WebVR API. Here the accelerometer and gyroscope sensors of the mobile device will be used for the head-tracking and the lens-distortion will be done manually. For getting the correct lens-distortion settings it can be necessary adjust the settings manually for the specific headset.
  • Experience any panoramic image or video (normal and stereoscopic) in 3D Virtual Reality mode directly inside the browser. When using depthmap-panos additionally also with positional-tracking.

Topics

Syntax

<plugin name="webvr" devices="html5" keep="true"
        url="webvr.js"
        postracking="auto"
        oversampling="1.0"
        fullscreen_mirroring="false"
        mouse_pointerlock="true"
        mobilevr_support="true"
        mobilevr_fake_support="true"
        mobilevr_touch_support="false"
        mobilevr_profile="80|60|42|35|0.441|0.156"
        mobilevr_screensize="auto"
        mobilevr_database_support="xml|internal|external"
        mobilevr_database_url="https://dpdb.webvr.rocks/dpdb.json"
        vr_cursor=""
        vr_cursor_enabled="true"
        vr_cursor_onover=""
        vr_cursor_onout=""
        vr_controller_support="true"
        vr_controller=""
        vr_controller_clickbuttons="0,1"
        onavailable=""
        onunavailable=""
        onunknowndevice=""
        onvrcontrollers=""
        onvrcontrollerbutton=""
        onhavepostracking=""
        onentervr=""
        onexitvr=""
        />
After loading the plugin will be additionally also available as global webvr variable.

krpano Events

Additionally to the plugin events, the plugin also dispatches these krpano events: 
<events webvr_onavailable=""
        webvr_onunavailable=""
        webvr_onunknowndevice=""
        webvr_onvrcontrollers=""
        webvr_onvrcontrollerbutton=""
        webvr_onhavepostracking=""
        webvr_onentervr=""
        webvr_onexitvr=""
        />

Plugin Attributes

Attribute name Type Default value
postrackingString"auto"
  • Enable VR Positional-Tracking.
  • Requires a VR headset with positional-tracking support, otherwise it has no effect.
  • The current position will be added to the view.tx/ty/tz settings.
  • When positional-tracking is available the onhavepostracking event will be called.
  • Available settings:
    • auto - Automatically enable positional-tracking when using depthmap-panos.
    • true - Always enable positional-tracking (when available by the VR hardware).
      But note - normal panoramic images would get distorted when not viewed from their normal image-center!
    • false - Always disable positional-tracking.
Attribute nameTypeDefault value
hlookatoffsetNumber0.0
  • A custom offset to the horizontal looking position (view.hlookat) in degrees.
  • Can be used to rotate the view independently and additionally to the users viewing.
Attribute nameTypeDefault value
oversamplingNumber1.0
  • An oversampling scale-factor for the rendering resolution.
  • Higher values will increase the image-quality, but require more GPU processing power.
  • Lower values will lower the image-quality and require fewer GPU processing power.
Attribute nameTypeDefault value
auto_oversamplingBooleantrue
  • When enabled apply an automatic additional oversampling factor depending on the actual VR headset.
  • This is done because the default resolution provided by the device is lower then the resolution that the device would be capable of for performance reasons.
  • The added oversampling factor improves image-quality at cost of a little performance.
  • When higher and more stable framerates are more important than image-quality consider disabling that setting or using a lower oversampling setting.
  • Supported headsets:
    • For Oculus Go and Oculus Quest a factor of ~1.4 will be automatically added.
  • Custom oversampling settings will be respected and a too high oversampling factor automatically avoided.
Attribute nameTypeDefault value
zoomNumber1.0
  • Apply a custom zoom-scale to the VR view.
  • Should be used very carefully and only for special cases!
Attribute nameTypeDefault value
frictionNumber0.0
  • A value between 0.0 and 0.999
  • Add a fricition to reduce the gyro responsive speed.
  • Should be used only for high zoom values to reduce shaking, but never for normal viewing!
Attribute nameTypeDefault value
headtrackingBooleantrue
  • By setting headtracking to false, it would be possible to disable the headset-movement-tracking and control the viewing direction by yourself by changing the view settings.
  • Warning - disabling this settings is NOT recommended!
  • Changing the viewing direction in VR different to the users head movement is a bad experience. And on systems with 're-projection' (HTC Vice, Oculus Rift) this can cause graphical errors, because these systems doesn't assume that the view will change different to the head-movement.
Attribute nameTypeDefault value
headtracking_absoluteBooleanfalse
  • Use an 'absolute' head tracking when possible.
  • When enabled the looking direction should be linked to the real world one.
  • When disabled (the default) the looking direction is relative to the startup looking direction when entering the VR mode.
Attribute nameTypeDefault value
fullscreen_mirroringBooleanfalse
  • Switch also automatically to fullscreen mode when using WebVR.
Attribute nameTypeDefault value
mouse_pointerlockBooleantrue
  • Lock the mouse-control when in VR mode (no visible mouse-cursor) and control the viewing direction directly by mouse movements.
Attribute nameTypeDefault value
mobilevr_supportBooleantrue
  • Enable or disable the MobileVR support.
  • This is a fallback solution when there is no WebVR API support available in the browser.
  • It allows using VR on any mobile devices that have gyroscope and accelerometer sensors.
Attribute nameTypeDefault value
mobilevr_desktop_supportBooleanfalse
  • Provide the MobileVR support also on Desktop devices.
  • By default the support is limited to mobile and tablet devices.
Attribute nameTypeDefault value
mobilevr_fake_supportBooleanfalse
  • Enable a 'fake' MobileVR support for tablet and non-VR desktop devices.
  • On these devices using VR wouldn't be possible normally, but with this setting enabled krpano will provide a fake solution / kind of simulation to give the user still an impression of the VR mode.
  • For checking if the fake mode is enabled there is the isfake attribute.
Attribute nameTypeDefault value
mobilevr_touch_supportBooleanfalse
  • Enable touch support for rotating / adjusting the horizontal offset.
  • This setting is disabled by default because some VR headsets are touching the screen with their case and can sometimes trigger wrong inputs.
Attribute nameTypeDefault value
mobilevr_profileString
  • The VR-headset profile parameters for MobileVR mode.
  • The Cardboard lens distortion model is used.
  • Parameters: 
    "fov|lensdistance|screendistance|traydistance|k1|k2"
    • fov - Field of view in degrees.
    • lensdistance - Inter-lens distance in millimeters.
    • screendistance - Screen to lens distance in millimeters.
    • traydistance - The distance from the headset tray bottom to the lens-center in millimeters. When set to 0 the center of the device will be used.
    • k1 and k2 - Lens distortion coefficents.
  • The default value (for Cardboard V1 headsets): 
    "80|60|42|35|0.441|0.156"
Attribute nameTypeDefault value
mobilevr_screensizeString"auto"
  • Set a custom diagonal device screen size in inch.
  • Knowing the physical screen size is necessary and very important to be able calculate the correct VR field-of-view and lens-distortion.
  • When set to auto (the default):
    • In this case the plugin tries to detect the device itself to get its screensize.
    • The plugin uses therefore an internal list of devices. Additionally a customizable list of devices can be defined in the xml.
    • When the device is unknown an external database can be used (see mobilevr_database_url) for finding the size of the device.
    • When detecting the size isn't possible, the plugin sends the onunknowndevice event.
Attribute nameTypeDefault value
mobilevr_database_supportString"xml|internal|external"
  • Set which databases should be used for finding the physical screensize for a device.
  • The setting can be a combination of these values:
  • Syntax of the mobilevr_device_database xml database: 
    <mobilevr_device_database>
      <device name="Samsung S8" ua="sm-g950" size="5.8" />
      <device name="Samsung S8+" ua="sm-g955" size="6.2" />
      ...
      <device name="iPhone X" screen="414x812x3" size="5.85|5.33" />
    </mobilevr_device_database>
    • A mobilevr_database_url element be xml defined anywhere in the xml files.
    • Multiple declarations will be automatically merged.
    • A device element can have the following settings to define a device:
      • name - the name of the device, need to be unique.
      • size - the physical screensize diagonal in inch (the detection result).
        For iOS devices two sizes can be defined. The first value is the size when using the full screen size, the second one when only using the safearea.
      • bevel - the physical bevel around the screen in millimeter (4 by default).
      • ua - a string that should be part of the user-agent string to detect the device, case-insensitive (used for detecting Android devices).
      • screen - the screen size (in portrait mode) in logical CSS pixels and optionally also the pixel-ratio (used for detecting iOS devices).
        Syntax: WIDTHxHEIGHTxPIXELRATIO.
Attribute nameTypeDefault value
mobilevr_database_urlString
  • Use a Cardboard Device Parameter Database (DPDB) as fallback for getting the screen-size for unknown devices.
  • By default this online database will be used:
  • When the database url setting will be set to an empty string value or to null, then no online database request will be made for unknown devices.
Attribute nameTypeDefault value
mobilevr_wakelockBooleantrue
  • Wakelock - try to keep the mobile device awaken and prevent that the display switches to sleep / standby mode. This is necessary because during the VR viewing typically no user touches on the display (which would prevent sleeping) are happening.
  • Currently the wake-locking is not a browser feature, currently it is only an ugly hack (which works by playing and looping a small hidden video). The current hack might be not working or could cause problems in newer/updated browser version, therefore it's optionally possible to disable that feature.
Attribute nameTypeDefault value
mobilevr_sensorint1
  • Define which browser event should be used for the device movement tracking:
    • 0 = the deviceorientation event
      • Here the sensor fusion will be done by the browser itself.
      • The data from this event is unfortunately buggy or just bad (slow, inaccurate, wrong) in many Android devices and Android browsers.
    • 1 = the devicemotion event (default)
      • Here the sensor fusion will be done by krpano.
      • The browser provides the raw data from the acceleration and the gyroscope sensors and krpano combines them for getting the final device rotation:
        • The gyroscope data is very quick and accurate but the gyroscope sensor measures only relative rotations and therefore it drifts away from the real physical orientation over time.
        • To compensate that drift, the acceleration sensor is used. That sensor measures the gravity acceleration of the earth and that can be used as absolute reference.
        • But the acceleration data is very noisy and it can be only used for detection 'tilt' rotations (tilt left, right, up or down) - rotations around the device itself can't detected by acceleration, for this the gyroscope data is required.
        • So the data from both sensor will be combined / fused. The acceleration data will be low-pass filtered and used as slow 'stabilization' and the gyroscope data for quick and accurate movements in all directions.
  • Using the devicemotion event (setting mobilevr_sensor=1) is the default and there should be normally no need or benefit to use the deviceorientation event, except maybe for some extreme browser bugs...
Attribute nameTypeDefault value
mobilevr_sensor_modeint3
  • The frame-rendering and the 'sensor-data-events' are happening in different time intervals / rates (depending on the system and browser), so it is necessary to evaluate and interpolate/extrapolate the sensor data somehow to get a smooth and also fast and responsive movement.
  • With this setting, different modes for this process can be selected.
  • Available modes:
    • 0 = Directly use the latest available sensor data. No interpolation or extrapolation. Depending on the sensor-time-intervals of the browser the movement can be either jerky or smooth.
    • 1 = Smoothly interpolate between the latest available sensor data. This will give a very smooth but delayed movement.
    • 2 = Forecast the device rotations and then interpolate between the sensor data.
    • 3 = Extrapolate the latest available sensor data to the current frame time. This will give a fast responsive and smooth movement, but there can be a jerking when the extrapolated/predicted data and the real movement don't match.
    • 4 = Forecast the device rotation to the current frame time. This will give a fast responsive and smooth movement, but there can be a jerking when the extrapolated/predicted data and the real movement don't match.
    • 5 = Forecast the device rotation and extrapolate the sensor data from the latest event to the current frame time.
    • 6 = Forecast the device rotation one frame ahead.
    • 7 = Forecast the device rotation two frames ahead.
  • Note - these settings would need to be rated inside a VR-HMD (head-mounted-display)! E.g. mode=1 looks good and super smooth on the screen, but inside a HMD the delayed movement can be unpleasing. Other modes might look jerking on the screen, but good inside the HMD.
    Additionally it depends on the sensor-rate of the browser, how good each mode will look. A good compromise for different devices are the modes 3 and 4.
Attribute nameTypeDefault value
vr_cursorString
  • Use a hotspot as vr-cursor.
  • That cursor hotspot will be displayed automatically above all other hotspots at the center of the screen and act as cursor / pointer. The styling of the hotspot itself can be controlled with the normal hotspot attributes.
  • The stereoscopic 3D depth of the cursor will be automatically adjusted to match the 3D depth of other hotspot when hovering them. This makes it eaiser to focus hotspots with different depths.
  • When the cursor will be over other hotspots, the onover and onout events of that hotspot itself and additionally also the vr_cursor_onover, vr_cursor_onout events will be called. This could be used to implement an automatic clicking when hovering a hotspots for some time.
  • Syntax: 
    vr_cursor="hotspot[name]"
    • name - The name of the hotspot.
    • The hotspot itself should be invisible (visible=false) on startup.
Attribute nameTypeDefault value
vr_cursor_enabledBooleantrue
  • Enable or disable the vr-cursor.
  • When disabled the cursor will not trigger onover / vr_cursor_onover events.
Attribute nameTypeDefault value
vr_cursor_onover
vr_cursor_onout
 Action Event
Action Event
  • These events will be called when the vr_cursor will move over and out of others hotspots.
  • The 'scope' of these events will be one of the hovered hotspots. That means these events act like the onover, onout events of the hotspot itself.
Attribute nameTypeDefault value
vr_controller_supportBooleantrue
  • Enable or disable the support for vr-controllers.
Attribute nameTypeDefault value
vr_controllerString
  • Define a comma-separated list of hotspots that should be used as as vr-controllers.
  • One or two hotspots can be used - for the left and right hands. When no hotspot for a hand should be used, the value null can be used instead.
  • Example: 
    vr_controller="vrcontroller_l,vrcontroller_r"
    where 'vrcontroller_l' and 'vrcontroller_r' are the names of <hotspot> elements.
  • The so linked hotspots will get automatically updated when the vr-controllers are used:
    • Their tx,ty,tz position will be set to the controller position.
    • The rx,ry,rz rotation set to match the controller rotation.
    • Additional dx,dy,dz attributes that represent the direction-unit-vector where the controller is pointing will be added to the controller-hotspot.
    • The controller hotspots can have handrotate="rx|ry|rz|rotationorder" settings for customizing the rotation of the hotspot controller image.
      • The defaults are handrotate="0|180|0|XYZ" for the left hand and
      • handrotate="0|0|0|XYZ" for the right hand.
    • When the controller is pointing to another hotspot:
      • A target attribute with a reference to that hotspot object will be added to the controller-hotspot.
      • The onover, onout events of the target hotspot and also of the controller hotspot will be called.
      • The hovering attribute of the target hotspot and also of the controller hotspot will be set to true.
      • For checking the exact position where the controller is pointing on the that hotspot, the hitx,hity,hitd attributes of that target hotspot can be used.
    • When pressing or releasing a controller button a onvrcontrollerbutton event of the controller hotspot will get called. Additionally the controller hotspot will get:
      • vrbuttonindex - The index of the current button (0-n).
      • vrbuttonstate - The current state of the button "down" or "up".
      variables for getting information about which button is pressed or released.
    • When pressing a controller button AND hovering an other hotspot at the same time AND the pressed button is one of the vr_controller_clickbuttons:
      • then the pressed attribute of the target hotspot and also of the controller hotspot will be set to true,
      • and the ondown, onup, onclick events of the target hotspot will be called.
    • For haptic feedback the hotspots get a pulse(value,duration) function added. This could be called e.g. in the onover event when hovering things.
      • value - The intensity of the pulse (controller vibration).
      • duration - The duration of the pulse in seconds.
  • When the controllers are getting updated the onvrcontrollers event will be called.
  • Information about the vr-controllers itself are also available by the vrcontrollers Array.
Attribute nameTypeDefault value
vr_controller_clickbuttonsString"0,1"

Plugin State Variables (read only)

Attribute nameTypeDefault value
isavailableBooleanfalse
  • Is VR support available?
  • Note - the correct state will be only available after the onavailable or onunavailable events!
Attribute nameTypeDefault value
isenabledBooleanfalse
  • Is the VR mode currently enabled?
Attribute nameTypeDefault value
iswebvrBooleanfalse
  • Is the WebVR API available / supported by the browser?
  • Note - the correct state will be only available after the onavailable event!
Attribute nameTypeDefault value
ismobilevrBooleanfalse
  • When there is no WebVR API support available, but the device itself is a mobile device with working gyroscope sensor support? ⇒ MobileVR support.
  • Note - the correct state will be only available after the onavailable event!
Attribute nameTypeDefault value
isfakeBooleanfalse
  • Is in MobileVR fake mode.
  • Note - the correct state will be only available after the onavailable event!
Attribute nameTypeDefault value
isvrbrowserBooleanfalse
  • Is the browser itself also a VR application?
  • This could be used for showing a special user-interface, e.g. instead of the normal desktop/mobile skin, directly a big 'Enter VR' button.
  • Note - the correct state will be only available after the onavailable event!
Attribute nameTypeDefault value
vrcontrollersJS-Array
  • A Javascript-Array with information about the currently available vr-controllers.
  • Each Array-item contains the following information:
    • id - The id/name of the vr-controller.
    • hand - A String: "left" or "right".
    • axes - A 4-count floating point Array with values in the range -1.0 to +1.0, representing the controls-stick axis (or touch-pad-hit) position (more information).
    • buttons - An array of Gamepad buttons (more information).
    • pressed - A Boolean indicating that one of the trigger buttons (according to vr_controller_clickbuttons) is pressed.
    • rx,ry,rz - Rotation angles in degrees.
    • dx,dy,dz - A direction unit-vector.
    • tx,ty,tz - The position of the vr-controller.
    • hs - A object-reference to the krpano hotspot that is assigned to that vr-controller.
Attribute nameTypeDefault value
havepostrackingBooleanfalse
  • Have positional-tracking?
  • Note - this state is first updated after entering VR mode and on the onhavepostracking event!
Attribute nameTypeDefault value
havesettingsBooleanfalse
Attribute nameTypeDefault value
devicenameString
  • Get the name of the WebVR device or the name of the detected mobile device.
  • Note - the correct state will be only available after the onavailable event!
Attribute nameTypeDefault value
devicesizeNumber0.0
  • Get the physical diagonal screen size of the device in inch.
  • The value will be 0.0 when the size will be unknown.
  • Note - the correct state will be only available after the onavailable or onunknowndevice events!

Plugin Events

Attribute nameTypeDefault value
onavailableAction Event
  • This event will be called when either WebVR or MobileVR support is available.
  • Could be used to show a 'Enter VR mode' button. This button could call the enterVR() action to enter it.
Attribute nameTypeDefault value
onunavailableAction Event
  • This event will be called when there is no VR support available.
Attribute nameTypeDefault value
onunknowndeviceAction Event
  • This event will be called when the mobile device and its screen size can't be detected.
  • In this case it might be possible to show a menu or setup screen and ask the user there about the screen size of his device.
Attribute nameTypeDefault value
onvrcontrollersAction Event
  • This event will be called when updating the vr-controllers.
  • Information about the vr-controllers itself are available by the vrcontrollers variable.
  • Note - when vr-controllers become available the vr-cursor will get automatically hidden.
Attribute nameTypeDefault value
onvrcontrollerbuttonAction Event
  • This event will be called when the state of a button on a vr-controller will be changed.
  • The call scope of the event will be the vr-controller hotspot element.
  • These information will be available in that scope:
    • vrbuttonindex - The index of the current button (0-n).
    • vrbuttonstate - The current state of the button "down" or "up".
    • vrcontroller - Information about the current vr-controller.
Attribute nameTypeDefault value
onhavepostrackingAction Event
  • This event will be called once when detecting the availability of positional-tracking.
  • This can happen only after entering VR mode.
Attribute nameTypeDefault value
onentervrAction Event
  • This event will be called when switching into VR mode.
  • Could be used for setting up a custom VR layout - e.g. like showing an 'Exit VR' button and hiding the UI elements that are unnecessary or interfering with VR mode.
Attribute nameTypeDefault value
onexitvrAction Event
  • This event will be called when exiting from VR mode.

Plugin Actions

enterVR()
  • Switch into the VR fullscreen mode.

exitVR()
  • Exit the VR mode.

toggleVR()
  • Toggle the current VR mode state - switch either into VR mode or exit from it, depending on the current state.

lookat(hlookat)
  • Set the horiztonally looking direction (hlookat).

calibrate(ondone*, onerror*)
  • Calibrate the gyroscope sensor manually (Mobile VR only).
  • Some devices (especially Android devices) could have an uncalibrated gyroscope sensor and this could lead to wrong and unintended rotations ('drifting').
  • When calling the calibrate() action the device should be absolutely still (!) for a few seconds (e.g. place the device on a flat and stable table for calibration). The orientation of the device itself doesn't matter for this process.
Parameters:
  • ondone (optionally)
    • Actions to call when the calibration is done.
  • onerror (optionally)
    • Actions to call when the calibration failed, e.g. when there was too much movement during the calibration.

resetCalibration()
  • Reset / zero the gyroscope sensor calibration data (Mobile VR only).

loadSettings()
saveSettings()
resetSettings()
  • Load or save the MobileVR settings (screensize, profile, gyro-calibration).
  • The settings will be stored only locally in the browsers localStorage.
  • When calling resetSettings() the setting storage will be cleared.
  • The storage works only for the current domain, cross-domain-storage sharing is not possible anymore due browser-restrictions.

iFrame Support

When trying to use MobileVR support inside an 'cross-origin' iframe (that means the outer page and inner iframe page are on different origins/domains) then the gyro-usage (and with that also the VR support) might be blocked by the browser.

To work-around that limitation it is possible to 'capture' the devicemotion event in the outer page and send it via the postMessage API to the inner iframe.
Here example Javascript code for the outer (the iframe-containing) webpage: 
<script>

var pano_iframe_name = "enter_here_the_id_of_your_iframe_element";

window.addEventListener("devicemotion", function(e){ var iframe = document.getElementById(pano_iframe_name); if (iframe) iframe.contentWindow.postMessage({ type:"devicemotion", deviceMotionEvent:{ acceleration:{ x:e.acceleration.x, y:e.acceleration.y, z:e.acceleration.z }, accelerationIncludingGravity:{ x:e.accelerationIncludingGravity.x, y:e.accelerationIncludingGravity.y, z:e.accelerationIncludingGravity.z }, rotationRate:{ alpha:e.rotationRate.alpha, beta:e.rotationRate.beta, gamma:e.rotationRate.gamma }, interval:e.interval, timeStamp:e.timeStamp } }, "*"); });

</script>