krpano Javascript Interface Version 1.22

Select Version:

• 1.22
• 1.21
• 1.20.11
• 1.20.10
• 1.20.9
• 1.20.8
• 1.20.7
• 1.20.6
• 1.20.5
• 1.20.4
• 1.20.2
• 1.20.1
• 1.20
• 1.19-pr16
• 1.19-pr15
• 1.19-pr14
• 1.19-pr13
• 1.18
• 1.0.8.15
• 1.0.8.14
• 1.0.8.12
• 1.0.7

• When the actions system is currently not blocked (e.g. due xml-loading or xml-parsing), then the actions will be directly executed.
• But when blocked, the actions will be 'queued' and automatically executed once the actions system is unblocked again.

• The 'caller' of the action code.
• This is an Object that will be used as local variable scope.
• This allows direct access to the attributes of that Object.

• 0 = DEBUG message (these will be only shown with enabled debugmode)
• 1 = INFO message
• 2 = WARNING message
• 3 = ERROR message (when showerrors is enabled, the log will also be opened)
• 4 = FATAL ERROR (a noticeable message in the middle of the screen)

• The 'caller' of the expression.
• This is an Object that will be used as local variable scope.
• This allows direct access to the attributes of that Object.

• The number of decimal places, 0 by default.
• Negative values work like positive ones, except that trailing zeros are automatically removed (except for a least one zero after the comma dot).

krpano.roundNumber(1.5) ⇒ "2.0"
krpano.roundNumber(1.23, 6) ⇒ "1.230000"
krpano.roundNumber(1.23, -6) ⇒ "1.23"
krpano.roundNumber(1.0, -6) ⇒ "1.0"

• The lower and upper limit for the result.

val = krpano.clampNumber(val, 0.0, 1.0);
val = krpano.clampNumber(val, -1.0, +1.0);
val = krpano.clampNumber(val, -90.0, +90.0);

• object - the layer or hotspot object
• url - on creating the url if set, or the custom type name in angle-brackets if no url is used. On destroying null will be passed as url to allow a custom unload/destroy handling.
• okaycallback - a callback to be called with true or false to signal if the creating is done and was successful. This will also trigger the onloaded event.

<hotspot name="spot1" type="special" ... >

krpano.registerType("special", function(hotspot, url, callback)
{
  if (url)
  {
    // create or load the special hotspot
    ... 
    // callback with true to signal that the creating was successful
    callback(true);
  }
  else
  {
    // destroy or unload the special hotspot
  }
});

• rqurl - the request url that was used on the loadFile call.
• url - the parsed and resolved url of the file.
• data - the loaded file content as String.
• errmsg (errorcallback only)
  • A boolean flag with the default value true.
  • When kept set to true, krpano will show a default loading error message.
  • When set to false, no error message will be shown.

• type - the request type: GET or POST
• url - the server url.
• data
  • The data to send with the request.
  • Can be an Object or a String.
  • Objects will be automatically converted to a JSON String.
• headers (optionally)
  • Optional headers, can be an Object or a String.
  • String-syntax: "key:value, key:'a,b,c', ..."
• cors (optionally) - when set to true, the CORS credentials will be added.
• user and password (optionally) - HTTP Basic Authentication.

• ok - true when the request was ok, false when it has failed.
• statuscode - the HTTP status code, e.g. 404 on loading errors.
• statustext - the HTTP status as text description.
• responsetext - the response text.

• Each function will be called with a callback function as argument.
• This callback function must becalled when the function is completed.
• Optionally, it is possible to pass an argument to this function as return/result value.

• This function will be called when all functions are completed.
• The function gets an Array as argument that contains the all the return/result values from the called functions (in the same order the functions were defined).

krpano.mergeCallbacks(
    [   function(callback){
            console.log("1 start");
            setTimeout(function(){  // randomly delay
                console.log("1 done");
                callback(1);        // here the function is done
            }, Math.random()*5000); 
        },
        function(callback){
            console.log("2 start");
            setTimeout(function(){  /// randomly delay
                console.log("2 done");
                callback(2);        // here the function is done
            }, Math.random()*5000); 
        },
        function(callback){
            console.log("3 start");
            setTimeout(function(){  /// randomly delay
                console.log("3 done");
                callback(3);        // here the function is done
            }, Math.random()*5000); 
        }
    ],
    function(results){
        // all functions from above are done
        console.log("all done, results:", results);  // "[1, 2, 3]"
    }
);

<action type="Javascript" autorun="preinit"><![CDATA[
  krpano.customParsePath = function(url)
  {
    console.log("url:",url);
    
    // load 'image2.jpg' instead of 'image1.jpg':
    if(url == "image1.jpg") url = "image2.jpg";
    
    return url;
  }
]]></action>	

• url - the base tile-url template.
• cube - the cube side index, range 0-5, an index into the cubelabels values. Non-cubical panos will use the value 1 here.
• level - the level index, range baseindex to N.
• h, v - horizontal and vertical tile index, range baseindex to N.
• stereo - stereo side, 0 or 1, an index into the stereolabels values.
• image - the related xml <image> element as object.

• spheretospace - an Object with x,y,z properties.
• spacetosphere - an Object with h,v,depth properties.

• url - the input url
• path - the path (including protocol and folders) but excluding the filename
• filename - the filename, including the file extension
• basename - the filename, without the file extension
• ext - the file extension
• query - the query string
• hash - the hash string

• 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]".
• plugin
  The krpano Plugin Object - this object provides direct access to all plugin attributes and functions.

1. Using setter AND getter functions - in this case when the attribute will be set to a new value, the setter function with that 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 - in this case the setter/getter functions will need to store the actual value by itself anywhere!
2. Using ONLY a setter function - in this case the current value of the attribute will be stored internally and the setter function will be called on changes with:

   setter(newvalue, oldvalue, object, attributename)

   This allows using fewer code for simple cases and/or sharing the same setter function for multiple attributes. The setter function can optionally also return a modified new value.

var layer = krpano.addlayer();
layer.setvars({type:"text", text:"test", align:"center"});

function callback(array){ ... }

callback(item, index)

• This event will be called after rendering the pano image and after the post-processing phase 1, but before rendering the krpano hotspots. It can be used to render custom elements.
• callback(framebuffer, viewport, pano, panoview, stereo)
  • framebuffer - the current krpano WebGL rendering framebuffer (can be null when currently rendering to the screen backbuffer). This can be used normally with a gl.bindFramebuffer() call or with the krpano redirectBackbuffer() function when there is no control about the current framebuffer binding.
  • viewport - the current viewport as Array with 4 values: [x,y,width,height]
  • pano - an Object with information about the current pano:
    • Can be used to render something only for a specifc pano image/scene, e.g. when rendering two panos the same time during blending.
    • id - a consecutive number of used pano images.
    • image - the related <image> Object.
    • suspended - when set to true, then this is an 'old' pano that is only rendered during blending.
  • panoview - an Object with information about the current pano-view:
    • h, v, r ⇒ view.hlookat, view.vlookat, view.camroll
    • tx, ty, tz ⇒ view.tx, view.ty, view.tz
      (adjusted with stereo-offsets when stereo-rendering)
    • rx, ry ⇒ view.rx, view.ry
  • stereo - the stereo rendering state: 0=off, 1=left, 2=right

• This event will be called to check hits / collisions with a custom elements.
• When the hit is on a custom type hotspot, krpano can automatically handle the hotspot events (like onover/onout, onclick and so on).
• callback(eventtype, origin, direction, hitresult, hittesthotspots)
  • eventtype
    • null - no user action, just checking for a hit (e.g. on hovering)
    • raycast - checking for a 3D collision, occlusion
      • The 3D geometry that is used for collision testing, should be checked here.
      • When using hotspots for the 3D geometry, only the hotspots in the hittesthotspots Array should be checked in this case.
    • ondown - mouse-down or touch-down
    • onup - mouse-up or touch-up
    • onclick - mouse-click or touch-down/up event
    • onwheel - mouse-wheel event
    • ongesture - gesture event
  • origin - the origin of the hit-test ray as 3D point object {x,y,z}.
  • direction - the direction of the hit-test ray as 3D point object {x,y,z}.
  • hitresult - an Object with information about the hit-result:
    • d - distance from the origin to the hit-point, -1 if there was no hit yet
    • x,y,z - the hit-point 3D position
    • nx,ny,nz - the normal vector of the surface at the hit-point
    • hs - hotspot object (if the hit was on a hotspot)
    • Note: the hitresult object can be already filled with hits on a krpano 3D-model or krpano hotspots, therefore check if the new hit-distance is shorter then the current stored one before filling the hitresult object with new information about the hit.
  • hittesthotspots - an Array of all krpano hotspots with hittest=true.
  • return value - true if there was a hit, false if not

• source
  • A GLSL fragment 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.
• name (optionally)
  • A name for the shader.
• onrendercallback (optionally)
  • A Javascript callback function that will be called before rendering the shader.
  • That could be used to set or update uniform values.
  • Function parameters:

    function onrendercallback(side, shader, gl)

    • side - the stereo side, 0=non-stereo, 1=left, 2=right
    • shader - the current shader object
    • gl - the current WebGL context

• A krpano 'Shader' object.
• Can be added to the ppShaderArray or ppShaderArray2 arrays.

• enable - true to enable, false to disable the redirection
• framebuffer - a WebGL framebuffer
• stereo - the stereo rendering state: 0=off, 1=left, 2=right

• width, height - The size in pixels. If set to 0, the current size will be used.
  If the size will be larger than actually possible, 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.