The embedpano() function needs an Object as argument.
This Object is used to pass various settings.
All parameters except
are optional - when they were not defined, their default values will be used.
The
Embedding Parameters Object
provides the following settings:
embedpano({
target : "...",
xml : null,
id : "krpanoSWFObject",
bgcolor : "#000000",
vars : null,
initvars : null,
basepath : null,
cors : false,
sameorigin : true,
consolelog : false,
mwheel : true,
capturetouch : true,
focus : true,
webgl : true,
webglsettings : {webgl2:true, depth:true, stencil:true},
webxr : "auto",
mobilescale : 1.0,
safearea : "auto",
touchdevicemousesupport : true,
iosfullscreen : false,
passQueryParameters : false,
onready : function(krpano){ ... }
});
The Embedding Parameters in detail:
target:...
- Set the target html-element where the pano viewer should get embedded.
- Can be either the id of a html-element or directly the html-element itself.
- There will be a Javascript alert() error when no target will be set or no html-element with the given id can be found.
xml:null
- Name and path to the startup xml file (relative to the html file).
- When no xml file should be loaded on startup, set the value to null.
- Backward compatibility: When not set and a path to a swf file is set, then the given filename of the swf file will be used
as name of the startup xml file (e.g. 'krpano.xml' for 'krpano.swf').
id:"krpanoSWFObject"
- The id of the internal viewer object.
- 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.
bgcolor:"#000000"
- The background color of the viewer (in html color format).
- The default is #000000 (=Black).
- Optionally the value transparent can be used to see the content (the website, bglayer layers)
behind the pano (behind partial panos or 3D-models).
- Note - when using a transparent background, only normal crossfade pano-blending
is possible (other blending modes will automatically fallback to this).
vars:{...}
initvars:{...}
basepath:...
- Sets a custom path for resolving relative to the krpano viewer url paths.
- Note - changing this will affect the %VIEWER% url placeholder.
cors:false
- Enable the sending of CORS (Cross Origin Resource Sharing) HTTP headers when loading files from external servers.
- This can be necessary when the external server only allow selective access.
- Same as when setting the security.cors setting to use-credentials.
sameorigin:true
- A security feature as cross-site-scripting protection - when enabled (the default), the krpano viewer
will load 'text' files (xml, scripts, plugins, ...) only from the same server (same 'origin').
- Loading files from other origins (external servers, other domains) will be blocked and cause an 'External Access Denied' error.
This avoids the possibility to inject unwanted files,
especially when the passQueryParameters setting is set to true.
- Image and media files are not affected by this settings.
consolelog:false
- If enabled, the krpano log/trace messages
will also be displayed in the Browser's Javascript console.
mwheel:true
- 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 using the control.disablewheel setting.
capturetouch:true
- Control the capturing 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.
- This setting can be changed also using the control.capturetouch setting.
focus:true
- When set to true (the default), the viewer will get the input / keyboard focus on startup.
- When set to false, the current focus will be not changed.
- 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.
webgl:true
- Use WebGL for the rendering (recommended).
- Instead of WebGL,
CSS 3D-transforms
could be used for displaying the panos,
but compared to using WebGL this is very limited.
- Settings:
- true - Only use WebGL (the default).
- false - Don't use WebGL, always use CSS 3D-transforms.
- "auto" - Use WebGL when available, otherwise use CSS 3D-transforms.
- When WebGL and CSS 3D-transforms are not available, an Error will be shown.
- Note - without WebGL these features are not available:
- 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.
webglsettings:{webgl2:true, depth:true, stencil:true, ...}
- 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
- Use the WebGL 2.0 API
when available (true by default).
- If WebGL 2.0 will be available can be checked using the
device.webgl2 variable and the devices xml filter.
- 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.
- Better ThreeJS support.
- 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.
- 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.
- 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.
webxr:"auto"
- Control the WebXR API support.
- 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.
In such cases the WebVR API is typically the better choice.
- 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.
mobilescale:1.0
- A setting for optionally using a different global scale for mobile devices.
- See also the xml stagescale setting.
safearea:"auto"
- Enable or disable the general Safe-Area support (for iOS devices with a notch).
- Available settings:
- auto (the default) - Automatically enable the Safe-Area support when the viewer gets embedded into a 'full-page' html-element.
- true - Always enable the Safe-Area support.
Could be used when the embedding-target-html-element is not full-page-sized during embedding.
- false - Disable enable the Safe-Area support.
- Note - in the html file there need to be also this <meta> setting in the html <head> element to be able to use the Safe-Area:
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, viewport-fit=cover">
- More information: krpano Forum Post
touchdevicemousesupport:true
- A setting for optionally disabling the mouse support on touch devices.
iosfullscreen:false
- Enable / Disable (=default) the iOS HTML5 Fullscreen API support.
- On iOS the HTML5 Fullscreen Mode is unfortunately not very usable.
Every swipe downwards ends the fullscreen mode and this disrupts the typical panorama control.
Additionally there will be always an non-adjustable exit-button in the left top corner.
- Because of these restrictions, the HTML5 fullscreen mode support is currently disabled for iOS by default.
As an alternative, the special iPhone Landscape Fullscreen Mode will be used.
passQueryParameters:false
onready:...Javascript-Callback-Function...
- The onready function will be called when the krpano viewer is ready for usage.
- The given function will be called with the krpano Interface Object as argument.
- Notes - when a startup xml file is set, the onready event will be called when all startup xml files are loaded.
- Example:
embedpano({target:"...", onready:function(krpano)
{
console.log("krpano is ready - version="+krpano.version);
krpano.actions.loadpano("pano.xml",null,null,null,function()
{
var hs = krpano.addhotspot();
hs.type = "text";
hs.text = "Test Hotspot";
hs.ath = 20;
hs.atv = 10;
hs.onclick = function()
{
alert("Test");
}
});
}});