For embedding the krpano viewer into a HTML page the krpano.js script file (the filename can differ) need to be included
and the embedpano() function be called.
The krpano script file need to be included once anywhere (but before the embedpano() usage) on the html page:
<script src="krpano.js"></script>
Some details and notes:
The 'krpano.js' file can be named different - e.g. when using the MAKE PANO or MAKE VTOUR droplets it's typically named 'pano.js' or 'tour.js'.
The file itself contains the krpano viewer and when registered also the license information.
Typically the file is always the same for all panos and tours (unless custom protection settings were applied).
That means the same file can be used and shared for multiple panos and tours.
When hosting multiple panos and tours this is even a recommend way - use one global location for the krpano viewer and plugins files
and refer from all other projects to them. With that updating the version will be much eaiser.
Create anywhere on the html page a <div> element where the viewer should be embedded,
give that div element an unique 'id' name and define its size via css styles:
After defining the <div> element, create a <script> element with the embedding script code.
For the embedding itself there is the global embedpano() function:
The embedpano() function needs a Javascript object as argument.
This object is used to pass all parameters (in random order) by using parametername:value pairs.
Almost all parameters (except the target parameter) are optional - when they were not defined, their default values will be used.
Name and path to the startup xml file (relative to the html file).
When no xml file should be loaded on startup, don't set the value or use null.
Backward compatibility: When not set and a path to a swf file is set, then the filename of the swf file will be used (e.g. 'krpano.xml' for 'krpano.swf').
Pass a Javascript Object with krpano variable:value pairs.
The variables will be set AFTER the xml file has been be loaded and parsed.
So these variables can be used to add new settings or to overwrite settings that were already defined in the xml.
Pass a Javascript Object with krpano variable:value pairs.
This is basically the same as the vars setting,
but these variables will be set BEFORE the xml file wil be loaded and parsed.
The main usage of this setting will be to set custom path variables that can be
used as placeholders inside url paths in the xml files
and / or to set variables that can be used inside xml-if-checks for <include> elements.
Example:
embedpano({..., initvars:{mypath:"./panos1/"} });
XML:
url="%$mypath%image.jpg"
To be able to pass initvars variables via http queries directly
at the url of the html file this syntax need to be used:
A Boolean setting to control the mouse-wheel support.
When set to true (the default), then the mouse-wheel events will be captured and can be used in the viewer (e.g. for zooming).
When set to false, then any mouse-wheel usage will be ignored and the browser will do its default mouse-wheel handling (typically scrolling the webpage).
The mouse-wheel support can be changed also at runtime by using the control.disablewheel setting.
A Boolean setting to control the captureing of touch events.
When set to true (the default), then the touch events will be captured and can be used in the viewer (e.g. for panning and zooming).
When set to false, then touch events itself will be still used by the viewer, but their default event processing will be not stopped.
That means in this case the browser might pan or zoom the webpage.
The setting can be changed also at runtime by using the control.capturetouch setting.
A Boolean setting to give the viewer the input / keyboard focus on startup.
When not set, the setting will be set automatically depending on the viewer size -
when the viewer will cover the whole webpage, focus will be set to true, otherwise to false.
Note - depending on the Browser and device the number of WebGL elements on a single webpage is limited
(e.g. to only 8 WebGL elements).
When requesting more WebGL elements, then the least recently used one will get released.
This needs to be considered when putting multiple panos on one single webpage.
For simple panos/tours disabling WebGL for this usage case can be an option.
Pass an object with special settings for the WebGL context creation.
The WebGL context will be created at startup and can't be changed at runtime, therefore these settings
need to be specified already during embedding.
Available settings:
webgl2 -
Try using the WebGL 2.0 API when available.
Set to false by default for the moment, because still slightly experimental and not fully tested across all systems.
Current WebGL2 advantages in krpano:
Non-power-of-two textures also can use mipmapping.
Non-power-of-two textures can use repeatable texture-coordinates (needed for some .obj 3D-Models) without shader-workarounds.
preserveDrawingBuffer -
Keep the drawing buffer content.
Would need to be enabled for when trying to make screenshots of the WebGL canvas via toDataURL or readPixels in some browsers.
Set to false by default for better performance.
depth - Create a depth buffer.
Required for depthmap support and 3D-object rendering.
Set to true by default, but could be disabled when not needed.
stencil - Create a stencil buffer. Required for a correct line rendering of polygonal-hotspots when using an alpha-transparent line-border color.
Set to true by default, but could be disabled when not needed.
failIfMajorPerformanceCaveat - Don't use WebGL when the rendering performance would be dramatically lower than the OpenGL rendering performance of a native application. Set to false by default.
antialias -
Set if anti-aliasing should be used - true or false.
When not set, krpano decided itself for optimal performance because some device/browser/gpu combinations are performing very bad (e.g. half framerate)
with enabled anti-aliasing.
This setting should be used only for internal testing or very special cases.
For using the WebXR API it is neccesady to do several initial setup-steps already on startup,
therefore the usage of the WebXR API need to be defined already when embedding the viewer.
Available settings:
auto (the default)
Use the WebXR API only on desktop browsers and dedicated VR systems/browsers.
On Android mobile systems the alternative krpano MobileVR support has a currently a better and wider device support.
When the WebVR API and the WebXR API are both available the same time, then prefer the WebVR API.
Today the WebVR API is still the better choice.
It allows using oversampling for higher image quality and device specific performance optimizations.
Both is currently not possible with the WebXR API, eventually future API versions and browsers might get better here.
preferwebvr
Prefer the WebVR API when WebVR and WebXR are both available.
prefer or true
Prefer the WebXR API when WebVR and WebXR are both available.
no or false
Don't use the WebXR API at all, always use the WebVR API or the krpano MobileVR support for VR display.
With this setting it will be possible to pass/redirect http-query parameters from the url to the krpano viewer as variables.
Possible values:
true - pass all parameters to the viewer.
false - don't pass any parameters (the default).
"param1,param2,param3,..." - define a custom list of comma-separated parameters that are allowed to be passed.
Usage example:
tour.html?startscene=scene2&initvars.design=flat
Security Warning:
When allowing all parameters (set to true) or parameters that can contain executable code to be passed, this can open potentials for
Cross-site-scripting.
If this can be a problem depends on the individual usage-case and the surrounding/containing website.