krpano各类Objects

krpano中有好多object，krpano Plugin Interface, krpano Plugin Object, krpano Base Object, krpano Interface Object, krpano Javascript Interface... 真心以为官方文档的组织形式太晦涩了，因此这里整理下

krpano Plugin Interface

定义krpano plugin的时候须要遵循的接口。
http://krpano.com/docu/plugininterface

定义krpano插件的时候，基本上就是定义一个叫krpanoplugin的function，这个function会在krpano加载插件的时候调用到。

krpanoplugin的方法里，有几个特殊的地方：

1. this指向当前的plugin对象

2. 须要按照krpano Plugin Interface，在this下定义并实现几个方法。registerplugin, unloadplugin必选；onresize可选

registerplugin当krpano要去加载该插件的时候被调用，调用时会传三个参数：依次是krpano Interface Object, plugin path, krpano Plugin Object

例如：

/*
    krpano HTML5 Javascript Plugin Example
*/

function krpanoplugin () {
    var local = this;   // save the 'this' pointer from the current plugin object
    var krpano = null;  // the krpano and plugin interface objects
    var plugin = null;

    var xml_value = 100.0;   // the value for a custom xml attribute

    // registerplugin - startup point for the plugin (required)
    // - krpanointerface = krpano interface object
    // - pluginpath = the fully qualified plugin name (e.g. "plugin[name]")
    // - pluginobject = the xml plugin object itself
    local.registerplugin = function (krpanointerface, pluginpath, pluginobject) {
        // get the krpano interface and the plugin object
        krpano = krpanointerface;
        plugin = pluginobject;

        // first - say hello
        krpano.trace(1, "hello from plugin[" + plugin.name + "]");

        // add plugin attributes
        plugin.registerattribute("mode", "normal");
        plugin.registerattribute("value", xml_value, value_setter, value_getter);

        // add plugin action (the attribute needs to be lowercase!)
        plugin.dosomething = action_dosomething;

        // optionally - add some graphical content:

        // register the size of the content
        plugin.registercontentsize(200,200);

        // use 100% width/height for automatic scaling with the plugin size
        var text = document.createElement("div");
        text.style.cssText = "width:100%;height:100%;"+
            "display:flex;color:white;background:rgba(10,50,100,0.5);"+
            "align-items:center;justify-content:center;text-align:center;";
        text.innerHTML = "HTML5<br>TEST PLUGIN<br>click me";

        // the plugin 'sprite' variable is the internal html element of the plugin
        plugin.sprite.appendChild(text);
    }

    // unloadplugin - exit point for the plugin (optionally)
    // - will be called from krpano when the plugin will be removed
    // - everything that was added by the plugin should be removed here
    local.unloadplugin = function() {
        plugin = null;
        krpano = null;
    }

    // onresize (optionally)
    // - width,height = the new size for the plugin
    // - when not defined then only the krpano plugin html element will be sized
    local.onresize = function(width,height) {
        // not used in this example
        // the plugin content will resize automatically because
        // of the width=100%, height=100% CSS style
        return false;
    }

    function value_setter(newvalue) {
        if (newvalue != xml_value) {
            krpano.trace(1, "'value' will be changed from " + xml_value + " to " + newvalue);
            xml_value = newvalue;
        }
    }

    function value_getter () {
        return xml_value;
    }

    function action_dosomething () {
        // trace the given action arguments
        krpano.trace(1, "dosomething() was called with " + arguments.length + " arguments:");
        for (var i=0; i < arguments.length; i++)
            krpano.trace(1, "arguments[" + i + "]=" + arguments[i]);

        // trace some infos
        krpano.trace(1, "mode=" + plugin.mode);
        krpano.trace(1, "lookat=" + krpano.view.hlookat + " / " + krpano.view.vlookat);

        // call krpano actions
        plugin.accuracy = 1;    // disable grid fitting for smoother size changes
        krpano.call("tween(width|height, 500|100)", plugin);
        krpano.call("lookto(0,0,150); wait(1.0); lookto(90,0,90);");
        krpano.call("tween(width|height, 200|200)", plugin);
    }
}

krpano Plugin Object

在定义krpano plugin时，其中一个接口registerplugin中的第三个参数，指代plugin对象自己。
http://krpano.com/docu/plugininterface/#plugininterface

在plugin定义时的registerplugin方法中的第三个参数krpano plugin object，其实是xml文件中<plugin>元素的内部呈现。可是除了<plugin>元素的各类属性意外，plugin object还有几个特殊的属性和方法：

1. sprite

   • HTML5 - The HTML <div> element of the plugin object.

   • The sprite object can be used for adding custom display elements (DisplayList elements in Flash, HTML DOM elements in HTML5) to the plugin itself.
     Note - when using the plugin as hotspot, then the sprite object is only available when rendering the hotspot via CSS3D (see the renderer setting)!

2. videoDOM

   • 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).

3. 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.

4. 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.

5. getfullpath()

   • Returns the xml embedding path/name - e.g. "plugin[name]" or "hotspot[name]".

6. _assignEvents(htmlelement, mode)

krpano Interface Object

在定义krpano plugin时，其中一个接口registerplugin中的第一个参数，是内部访问krpano的直接媒介（接口对象）。
http://krpano.com/docu/plugininterface/#krpanointerface

这个接口对象提供了访问整个krpano的全部结构和方法，以外还额外提供了一些方法来作数据访问，action调用等。

这些额外的方法有：

1. set(variable, value)
2. get(variable)
3. call(actioncode, callerobject*)
4. trace(code, message)
5. parsepath(path)
6. loadFile(file, donecallback, errorcallback*)
7. loadImage(fiel, donecallback, errorcallback*)
8. screentosphere(x, y)
9. spheretoscreen(v, h)

krpano Base Object

http://krpano.com/docu/plugininterface/#baseobject

全部的xml中定义的元素、对象和数组对象，包括krpano Interface Object都是继承与krpano Base Object。（上面说过krpano Plugin Interface就是xml中的<plugin>元素，因此它也继承了base）

Base提供了一些基础的添加/注册属性或者建立子数组结构的方法：

1. registerattribute(attributename, defaultvalue, setter*, getter*)
2. removeattribute(attributename)
3. getattributes()
4. createobject(objectname)
5. removeobject(objectname)
6. createarray(arrayname)
7. removearray(arrayname)

krpano Array and Array-Item Objects

http://krpano.com/docu/plugininterface/#array

krpano中的数组对象，不一样于javascript中的数组。当在xml中一个元素定义了name属性，那么其实就建立了一个krpano数组；或者是当给一个变量设置了array-path，即'arrayname[itemname].variable'时，也建立了krpano数组。

数组中的元素也是继承与krpano Base Object，而且额外提供了name和index属性。这些数组元素能够用来保存任何属性，方法或者是另一个krpano数组。

例如：

var kr = document.getElementById('krSWFObject');
var hotspots = kr.get('hotspot');           // hotspots就是krpano array
var aHotspot = hotspot['spot1'];            // aHotspot就是krpano array item

krpano Array Object提供的属性和方法：

1. count
2. createItem(name or index)
3. getItem(name or index)
4. renameItem(oldname:String, newname:String)
5. removeItem(name or index) / removearrayitem(name or index)
6. getArray()

krpano Array-item Object提供的属性：

1. name
2. count

krpano Javascript Interface / krpano Javascript-Interface Object

http://krpano.com/docu/js/#top

在krpano外部同步javascript操做krpano的接口，实现这个接口的对象就是krpano Javascript-Interface Object

这个对象提供的接口有：

1. set(variable, value)
2. get(variable)
3. call(action)
4. spheretoscreen(h, v)
5. screentosphere(x, y)

ygjack: 能够看到这个接口是krpano Interface Object提供接口的子集

得到krpano Javascript-Interface Object:

var kr = document.getElementById('krpanoSWFObject'); // 'krpanoSWFObject'是默认id