krpano 1.19-pr16 (build 2018-04-04)

krpano Plugin Interface

krpano provides a small and simple interface for developing own plugins. A plugin can be either a 'code-only' plugin that extends krpano with additional functionality or controls krpano and / or it can be a 'graphical-plugin' which shows or does something on the screen.

There are two types of plugins: The basic plugin-to-krpano and krpano-to-plugin interfaces are almost the same for HTML5 and Flash plugins, only system and language specific code is different.

The basic structure is that the plugin has these public functions, which will be called from krpano:
  • A registerplugin function - this function will be called from krpano when the plugin will be loaded. The function provides a krpano Interface Object and a krpano Plugin Object.
  • An unloadplugin function - when the plugin will be removed from krpano, then this function will be called. Here all elements and events that the plugin has added should be removed.
  • And optionally an onresize function to allow the plugin reacting on size changes of the plugin element.
The plugin itself can add custom functions or attributes to krpano just by adding / setting them directly to the krpano object or to the plugin object. For custom attributes that can be set from the xml there is additionally the registerattribute function - it allows adding an attribute with a default value while keeping the value from the xml. And the registerattribute function can be used to add setter/getter attributes - this are attributes which will cause automatically calling a get or set function when accessing the variable - this can be used to get notified when an attribute will been changed.

HTML5 Javascript Plugins

The krpano Javascript plugins are just plain Javascript code. Special tools for compiling or building are not necessary, but to reduce the filesize of the final plugin file compressing or minimizing the Javascript code is recommended.
Here an example plugin code with the basic structure for a krpano Javascript plugin:
test view raw download

Compress / Minimize the HTML5 Javascript Plugin Code

This step or part is optionally, but to reduce the filesize of the plugin, compressing or minizing the Javascript file is recommended. Good tools for that are the Google Closure Compiler, the YUI Compressor or other similar tools.

Both of the above tools can be used offline, but there are also online tools available:

Additionally the (minimized) Javascript files can be even more compressed and encrypted and protected by using the krpano Encrypt Tool.

Actionscript3 Flash Plugins

Flash plugins for the krpano Flash viewer can be build either with the free mxmlc compiler from the Flex SDK (recommended) or with Flash Professional CS.
Here an example plugin code with the basic structure for a krpano Flash plugin:
test view raw download

The krpano Plugin Interface

These are the interface functions of the plugin that will be called from krpano. In Flash/Actionscript3 these functions must be public functions of the startup Flash object.
In HTML5/Javascript these functions must be members of a globally defined function object named 'krpanoplugin'.
  • registerplugin(krpanointerface, pluginpath, pluginobject)
    • The registerplugin() function will be called when the plugin was loaded into krpano and is ready for usage.
    • Here the plugin can add / register attributes, functions, add graphical content to the plugin or to the viewer and do many things more.
    • Parameters that will be passed with the registerplugin() function:
      • krpanointerface
        The krpano Interface Object - this object provides access to interfacing functions and to the whole krpano data structure.
      • pluginpath
        A String with the 'full path' to the plugin object, e.g. "plugin[name]".
      • pluginobject
        The krpano Plugin Object - this object provides direct access to all plugin attributes and functions.
  • unloadplugin()
    • The unloadplugin() function will be called from krpano when plugin will be removed.
    • Here the plugin should remove all content that it has added (e.g. graphical objects, event listeners, timers, ...).
  • onresize(width, height) (optionally)
    • The onresize() function will be called when the plugin will be resized.
    • The parameters width and height are the new size in pixels.
    • Here the plugin can adjust or resize own graphical content.
    • The onresize() function can optionally return a Boolean value - when it returns true then krpano will try to scale the plugin automatically, when false will be returned then krpano will not scale the plugin.

krpano Interface Object

The 'krpano' object (the 'krpanointerface' parameter in the registerplugin call) is the direct interface to krpano. It provides direct access to the whole krpano structure and all functions there. All mapped xml nodes, arrays, objects and attributes can be accessed directly with it. Additionally it provides some functions for data access, action-code calling/executing and more - see below.
Functions of the 'krpano' object:
  • set(variable, value)
    • Sets a variable to a given value.
    • When the variable or the path to it, don't exist then the variable and path will be created.
    • Works like the xml set() action.
  • get(variable)
    • Returns the value of a variable.
    • Returns 'null' when the variable doesn't exist.
  • call(actionscode, callerobject*)
    • Call action code to the krpano actions code.
      When the action system is currently not blocked, then the given actions will be directly executed.
    • actionscode = a String with one or more krpano actions.
    • callerobject (optionally) = the object that was calling the actions (e.g. the plugin object itself). This allowes direct access to the object attributes in the actions code, e.g. just set(x,1) instead of set(plugin[name].x,1).
  • trace(code, message)
    • Trace out messages to the krpano log.
    • code = numeric code of the message-type:
      • 0 = DEBUG message - will be only shown with enabled debugmode
      • 1 = INFO message
      • 2 = WARNING message
      • 3 = ERROR message - will also open the log automatically.
      • 4 = FATAL ERROR - this message will be shown in the middle of the viewer.
  • parsepath(path)
    parsePath(path)
    • Resolves the krpano placeholders in the given path string.
    • Return value: the resolved path string.
  • loadFile(file, donecallback, errorcallback*)
    • Request to load a file as String in Javascript or as ByteArray in Flash.
    • donecallback and errorcallback - these functions will be called when the loading was successfully or has failed. The usage of the errorcallback is optionally.
      Both functions will be called with an Object as parameter - and this Object has these attributes:
      • rqurl
        The request url that was used on the loadFile call.
      • url
        The parsed and resolved url of the file.
      • data
        Javascript: The loaded file as String.
        Flash: The loaded file as ByteArray.
      • errmsg
        A boolean flag with the default value 'true' that indicates if krpano should show an automatic loading error message. Only for usage in the errorcallback function! Set it to 'false' to disable the default loading error message.
  • screentosphere(x,y)
    spheretoscreen(h,v)
    • Functions for converting between screen and spherical coordinates.
    • Return value: an Object with x and y properties. The values of these properties can be NaN (Not a Number) when the conversion wasn't possible.

krpano Plugin Object

The 'plugin' object (the 'pluginobject' parameter in the registerplugin call) it the internal representation of the xml <plugin> element. All plugin attriutes and actions are directly accessible by it.
Special plugin-related attributes of the 'plugin' object:
  • sprite
    • Flash - The Actionscript 3 Sprite object of the hotspot.
    • HTML5 - The HTML <div> element of the plugin object.
      Note - when using the plugin as hotspot, then the sprite object is only available when rendering the hotspot via CSS3D (see the renderer setting)!
    • The sprite object can be used for adding custom display elements (DisplayList elements in Flash, HTML DOM elements in HTML5) to the plugin itself.
  • videoDOM (HTML5 only)
    • A special attribute to allow the plugin providing a HTML5 video object for rendering.
    • The krpano viewer will use that video object for rendering when using the plugin as hotspots or as pano image (via url="plugin:video").
    • Setup: videowidth and videoheight attributes with the size of the video need to be added to plugin object, and once the video is ready for rendering the onvideoreadyCB function of the plugin be called. For all details please see the example source code of the videoplayer plugin.
    • Special usage: with some tricks it's also possible to use a HTML5 canvas object as video source. Use the canvas as videoDOM and add these 'faked' properties to it: readyState=4, videoWidth=canvas.width, currentTime=time or frame number (should change when the content changes).
Special plugin-related functions of the 'plugin' object:
  • registercontentsize(width, height)
    • Define the 'default' size of the plugin display content.
    • This is the size that will be used when the user hasn't set the width or height.
  • updatepos()
    • Parse the position related settings and update the internal display object of the plugin.
    • After calling this function the pixelwidth and pixelheight variables will contain the final pixel sizes of the plugin element.
  • getfullpath()
    • Returns the xml embedding path/name - e.g. "plugin[name]" or "hotspot[name]".
  • _assignEvents(htmlelement, mode) (HTML5 only)
    • Assign the krpano plugin events to the given html element.
    • mode - "add" for adding the events, "remove" for removing.
    • This can be used for special custom added html elements, e.g. svg path elements.

krpano 'Base' Object (the 'base-class' or 'super-class' in programming language)

All krpano mapped-xml-nodes, objects or array-elements and also the krpano Interface Object are derived from a krpano 'Base' object. The 'base' object has some basic functions for adding / registering new attributes and for creating sub array structures.
Functions of 'Base' objects:
  • registerattribute(attributename, defaultvalue, setter*, getter*)
    • Adds a new attribute to the object and sets it the given default value. When the object already has that attribute (e.g. from xml) then the current value will be kept but the type of the attribute will be converted to the type of the default value. The automatic type conversion will work for 'Number' and 'Boolean' datatypes.
      For example: When the attribute was set in the xml file to "123" then the type of the attribute is a 'String', but when registering that attribute with a 'Number' default value, then the attribute will be also converted to 'Number' with the Value 123.
      Setter / Getter (optionally)
      Optionally it's possible to use setter and getter functions instead of a normal attribute. In this case when the attribute will be set from xml or via the set interface then the setter function with the new value will be called, and when the value of the attribute will be read then the getter function will be called to return the value (Note - the setter/getter functions will need to store the value anywhere in this case).

      Accessing the setter/getters from Actionscript or from Javascript:
      • In Actionscript the setter/getter are special objects. Accessing them direct like normal variables/attributes is not possible because the Actionscript language doesn't have/support dynamic setter/getters. For accessing the value these objects have a set(value) function for setting the new value and a get() function for getting the value.
      • In Javascript the setter/getter behave as normal attributes. They can be used directly like normal variables/attributes.

      Notes about setter / getters:
      • Setter and getters are a very powerful instrument for building data structures.
      • They can be used to get informed anytime when the value of an attribute will be changed / updated.
      • With them it possible to check and if necessary correct the value on setting.
      • And/or to set flags and call other functions when the value will be changed.
  • removeattribute(attributename)
    • Removes an attribute from the current object.
  • getattributes()
    • Get all current attributes of the object.
    • Returns a Flash/Javascript 'Array' with the names of all attributes.
  • createobject(objectname)
    • Create a new krpano Base Object inside / under the current object.
    • Returns the new created krpano Base Object.
    • If the object already exists then the exiting object will be kept and returned.
  • removeobject(objectname)
    • Removes an object from the current object.
  • createarray(arrayname)
    • Create a new krpano Array inside the current object.
    • Returns the new created krpano Array Object.
    • If the array exists already then the current Array will be kept and the exiting Array will be returned.
  • removearray(arrayname)
    • Removes and destroys a krpano Array object.

krpano 'Array' and 'Array-Item' Objects

Arrays in krpano are internally special objects, not native Javascript or Actionscript Arrays. An array will be automatically created when a node in the xml has a 'name' attribute or when a variable with a 'array path' like 'arrayname[itenname].variable' will be set.
The items of the arrays are derived from krpano 'Base' objects and have additional attributes for name and index. Beside of that, these objects can store any kind of attributes or functions, also additional krpano arrays.
Attributes of the krpano 'Array' objects:
  • count
    • The number of elements in the array.
    • Can be changed dynamically, but only decreasing makes sense, e.g. set it to 0 to remove all items.
Functions of the krpano 'Array' objects:

Default Attributes of the krpano 'Array-Item' Objects:
  • name
    • The name of the current array item (read-only).
    • This name can be used for direct access to the array item.
  • index
    • The 0-based index of the current array item (read-only).

krpano WebGL API

The krpano HTML5 viewer exposes a WebGL API for getting access to the internal WebGL canvas and context and for managing custom post-processing shaders.
  • krpano.webGL
    • The krpano WebGL API object.
    • When the object is null, then there is no WebGL support.
  • krpano.webGL.canvas
    • The internal krpano WebGL <canvas> element.
  • krpano.webGL.context
  • krpano.webGL.createPostProcessingShader(fragment_shader_source, uniforms)
    • Create a krpano post-processing shader (a WebGL GLSL fragment shader).
    • Parameters:
      • fragment_shader_source
        • A GLSL shader source code as string.
        • The shaders code needs to have:
          • A sm named sampler2D - this will be the current screen as input texture.
          • A tx named vec2 varying - this will be the current texture coordinate.
          • Optionally a sz vec2 uniform - this will contain the screen size.
      • uniforms
        • A comma separated list of the uniform names used in the shader.
        • The 'uniform location' will be automatically stored at the returned shader object with the same name.
    • Return:
  • krpano.webGL.ppShaderArray
    • An Array of post-processing shaders.
    • Here custom shaders can be added, inserted or removed.
    • The shaders will be processed by the order in that Array.
  • krpano.webGL.useShader(shader)
    • Select/activate the shader for interfacing, e.g. for setting uniform values.
    • NOTE - after usage useShader(null) needs be called to restore the previous shader! IMPORTANT!
  • krpano.webGL.deleteShader(shader)
    • Delete the shader (free-up the WebGL resources).
  • krpano.webGL.restoreProgram()
    • Notify krpano that it need to restore the krpano WebGL program on the next usage.
    • This need to be called when an external WebGL code had changed the current WebGL program.
  • krpano.webGL.makeScreenshot(width, height, hotspots, type, jpegquality, crop, sizeinfo, cache)
    • Make a screenshot in the given size and given type.
    • Parameters:
      • width, height - The size in pixels. When set to 0 the current size will be used.
        When the size will be larger than possible by the browser, then the size will be automatically proportionally downscaled.
      • hotspots - Render also the (webgl) hotspots: true or false (false by default).
      • type - This setting defines what will be returned by the function:
        • "jpeg" - A JPEG image as data-url / base64 encoded string. (default)
        • "png" - A PNG image as data-url / base64 encoded string.
        • "raw" - The direct pixels as Uint8Array with RGBA bytes per pixel.
        • "canvas" - A 2D Canvas Object with the screenshot image.
      • jpegquality - The JPEG image / compression quality, from 0.0 (worst) to 1.0 (best) and 0.85 by default. Only used for type="jpeg" and ignored for all other types.
      • crop - An optional Object with {x,y,w,h} properties to define an optional cropping of the screenshot image.
      • sizeinfo - An optional Object with {w,h} properties to pass to get information about the pixel size of the resulting image (useful for raw and image types).
      • cache - An optional empty Object where krpano can store internal buffers. When doing several screenshots with the same size, this can makeScreenshot calls faster. That object should be stored somewhere on application side and passed to all makeScreenshot calls.
    • When there will be an error, null will be returned.
    • Usage notes: Even when called 'screenshot', technically this functions renders a whole new frame directly in the given size/resolution (no interpolation).
      This also allows changing all kind of settings (e.g. a different viewing direction) before doing the 'screenshot' (and then restoring them after it) to render something different to that what's currently shown on the screen.
      There is only one limitation here - only the currently loaded pano tiles/image are used. That means when trying to render a whole different view (e.g. other direction or other zoom) on a multires pano, there might be only the preview image there to render.

Examples

Plugins with open sources: