For embedding the krpano viewer into a HTML page the core 'krpano.js' script file (the filename can differ) need to be included
and the embedpano() function be called.
The embedpano function detects the browser support and decides which krpano viewer to use (the krpano HTML5 or krpano Flash viewer).
When using the krpano Flash viewer, the embedding script also applies several Flashplayer and Browser fixes and workarounds (e.g.
to enable the Mouse-wheel usage inside Flash on systems where this isn't supported).
This makes the embedding of the krpano viewer easy and simple - just one script include and one line embedding code.
The krpano script file need to be included once anywhere (but before the embedpano() usage) in 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 two parts - the krpano embedding script and the krpano HTML5 viewer.
The krpano Flash viewer is a separate external file (e.g. the 'krpano.swf' file).
The file is always the same, it doesn't contain any pano or tour specific information,
that means it could be shared across several panos/tours or projects.
E.g. to make later updates easier just use only one global folder for the krpano viewer and plugins files
and link from all other projects to them. Then all projects can be updated by only updating the global krpano files.
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.
This will be the object for interfacing the viewer via the Javascript-Interface.
The default id is "krpanoSWFObject".
It is important that each viewer will have an unique id!
When there already exists an object with the given id, then the embedding script will automatically add numbers at the end of the id until it is unique.
auto - The default setting - automatically use the krpano HTML5 viewer.
With that setting, the krpano HTML5 viewer will be used when possible by default (since version 1.19, in older versions Flash was used as default)!
When HTML5 will be not possible, then the Flash viewer will be used as fallback.
prefer - Prefer the usage of the krpano HTML5 viewer when possible, otherwise use Flash (same as auto since version 1.19).
fallback - Prefer the usage of the krpano Flash viewer when possible.
Use the krpano HTML5 viewer only as fallback when Flash is not available.
only - Only use the krpano HTML5 viewer - never use the krpano Flash viewer.
With that setting, the krpano HTML5 viewer will be used when possible.
When the system/browser is not HTML5-compatible, then an error message will be shown.
always - Always use the krpano HTML5 viewer, regardless if the system and browser are
supporting the therefore necessary capabilities! Note - This setting should be only used for internal testing, never for publishing!
never - Never use the krpano HTML5 viewer, force using the krpano Flash viewer.
Additional extensions settings (for controlling the rendering method):
+webgl - Use the krpano HTML5 viewer only when WebGL is available.
Note - some features are only available when WebGL is available - e.g. panoramic-video-support,
WebVR-support, stereo-rendering,
spherical and cylindrical images, view distortions (fisheye, littleplanet), ...
+css3d - Prefer the usage of CSS3D rendering instead of WebGL rendering (by default WebGL will be preferred when available).
The css3d setting should be only used for internal testing, never for publishing!
Usage examples:
prefer+webgl - Use the krpano HTML5 viewer only when WebGL is available, otherwise use Flash.
only+webgl - Use the krpano HTML5 viewer only when WebGL is available, otherwise show an error message.
This is a basically the same as the html5 setting, just the inverse.
It can be used for nicer urls, e.g. by using flash=prefer instead of html5=fallback.
When the flash setting will be set, it will be mapped to a html5 setting and overwrite it.
prefer - Prefer the usage of the krpano Flash viewer when possible.
Use the krpano HTML5 Viewer only when there is no Flashplayer and the system/browser is HTML5-compatible.
This setting will be mapped to html5=fallback.
fallback - Prefer the usage of the krpano HTML5 viewer when possible.
Use the krpano Flash viewer only as fallback when HTML5 is not available.
This setting will be mapped to html5=prefer.
only - Only use the krpano Flash viewer - never use the krpano HTML5 viewer.
With that setting, the krpano Flash viewer will be used when possible.
When there is no Flashplayer, then an error message will be shown.
This setting will be mapped to html5=never.
never - Never use the krpano Flash viewer, only use the krpano Flash viewer.
This setting will be mapped to html5=only.
window - The Flashplayer default, a compromise between system support and performance.
Note - on some systems and browsers html elements can't overlap the Flashplayer in this mode!
See this wmode link for details.
opaque - Allow other html elements to overlap the Flashplayer (depending on the system and browser
this can cause slower and jerky rendering).
opaque-flash - Same as opaque but only for the Flashplayer (will be ignored by the HTML5 viewer - see the HTML5 notes below).
transparent - Make the Flashplayer background transparent to allow seeing html elements
behind the Flashplayer and additionally also allow other html elements to overlap the Flashplayer
(depending on the system and browser this can cause slower and jerky rendering).
transparent-flash - Same as transparent but only for the Flashplayer (will be ignored by the HTML5 viewer - see the HTML5 notes below).
direct - Best performance, hardware accelerated presentation, no html overlapping on many systems and browsers
(this is typically the fastest mode but on incompatible or older systems and browsers this can cause slowdowns).
krpano will use wmode=direct by default, except for Chrome - there wmode=window will be used
by default (better performance and no black window during resizing).
HTML5 notes: The wmode setting is typically a Flashplayer setting,
but wmode=opaque and wmode=transparent will be evaluated also by the krpano HTML5 viewer and make
the viewer background transparent there too. Overlapping html elements itself are always possible when
using the HTML5 viewer.
When running HTML5 content locally with file:// urls
several browsers (especially Chrome and Safari) are restricting the dynamic loading of data files!
In the krpano HTML5 viewer this affects the xml and plugin loading.
For more information about this case please see here - Local Usage.
To avoid just getting a xml loading error in this case, the embedding script checks in
this case if loading would be possible and if not, it offers some alternative solutions.
Possible settings:
An url of the krpano Testing Server (by default http://localhost:8090)
When the localfallback setting will be set to an url of the
krpano Testing Server (the default case)
and the server is currently already running, then the current page will be
automatically redirected to the testing server to allow a full featured local usage.
When the server is not running, the error fallback case will be used.
flash - Use the krpano Flash viewer instead. The Flashplayer is not affected by the local browser restrictions.
error - Show an error and information message about local usage.
The error message could be customized by using the onerror callback.
none - Ignore that they are local restrictions and start the HTML5 viewer anyway...
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 usage.
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).
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.
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.
This works only in HTML5 (all browsers) and in the Chrome Flashplayer.
In other browsers the Flash element requires an initial click by the user for getting the focus.
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:
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, false by default.
depth - Create a depth buffer, false by default.
Would need to be enabled for the correct ThreeJS plugin usage.
stencil - Create a stencil buffer, false by default.
failIfMajorPerformanceCaveat - Don't use WebGL when the rendering performance would be dramatically lower than the OpenGL rendering performance of a native application, false by default.
All these settings are disabled by default for performance and memory reasons (especially on mobile devices).
embedpano({target:"krpanoDIV", onready:krpanoReady});
function krpanoReady(krpano)
{
krpano.call("trace(krpano is ready...)");
}
Flashplayer Notes: This function requires the External Interface of the Flashplayer!
This means the call-back will work offline/locally only when the security settings of the Flashplayer were adjusted.
See here for more detatils - Local / Offline Usage.
For removing the pano viewer from the html page the removepano() function need to be used!
The removepano() function will remove all internally attached mouse-fixes (Flash) and all DOM elements and events (HTML5).