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