KRPano官方文档中文版

krpano 为开发自己的插件提供了一个小而简单的界面。一个插件可以是一个 "仅代码" 插件, 扩展 krpano 与附加功能或控制 krpano 和/或它可以是一个 ' 图形插件 ', 显示或在屏幕上的东西。

有两种类型的插件:

HTML5 Javascript 插件 (. js) 为 krpano HTML5 播放器和
Flash Actionscript3 插件 (. swf) 用于 krpano Flash播放器。

对于 HTML5 和 Flash 插件, 基本的插件到 krpano 和 krpano 接口几乎相同, 只有系统和语言特定的代码是不同的。

基本结构是插件有这些公共功能, 将从 krpano 调用:

registerplugin函数-在加载插件时, 将从 krpano 调用此函数。该函数提供 krpano 接口对象和 krpano 插件对象 .
unloadplugin函数-当插件将从 krpano 中删除时, 将调用此函数。在这里, 插件添加的所有元素和事件都应该被删除。
和可选的 onresize函数, 允许插件对插件元素的大小更改作出反应。

插件本身可以向 krpano 添加自定义函数或属性, 只需将它们直接添加/设置到 krpano 对象或插件对象即可。对于可以从 xml 设置的自定义属性, 另外还有 registerattribute函数-它允许在保留 xml 值的同时添加具有默认值的属性。 registerattribute函数可用于添加 setter/getter 属性-这是在访问变量时会自动调用获取或 set 函数的属性, 这可用于在属性被改变.

HTML5 Javascript 插件

krpano javascript 插件只是普通的 javascript 代码。编译或生成的特殊工具是不必要的, 但建议减少最终插件文件的 filesize 压缩或最小化 Javascript 代码。

这里一个例子插件代码以基本的结构为 krpano Javascript 插件:

test view raw download

压缩/最小化 HTML5 Javascript 插件代码

此步骤或部分是可选的, 但为了减少插件的 filesize, 建议压缩或 minizing Javascript 文件。好的工具是 Google 闭包编译器、小锐压缩机或其他类似工具。

上述两种工具都可以脱机使用, 但也有可用的联机工具:

此外, 通过使用 krpano 加密工具, 可以更压缩和加密和保护 (最小化) Javascript 文件。.

Actionscript3 Flash插件

krpano Flash播放器的Flash插件可以使用来自 Flex SDK (推荐) 的免费 mxmlc 编译器或 flash 专业 CS来构建.

这里一个例子插件代码以基本的结构为 krpano Flash插件:

test view raw download

krpano 插件接口

这些是将从 krpano 调用的插件的接口函数。在 Flash/Actionscript3 中, 这些函数必须是启动 Flash 对象的公共函数。
在 HTML5/Javascript 中, 这些函数必须是名为 "krpanoplugin " 的全局定义函数对象的成员。

registerplugin (krpanointerface, pluginpath, pluginobject)
- 当插件加载到 krpano 并准备好使用时, 将调用 registerplugin () 函数。
- 在这里, 插件可以添加/注册属性, 功能, 添加图形内容到插件或播放器, 并做许多事情更多。
- 将与 registerplugin () 函数一起传递的参数:
  - krpanointerface
    krpano 接口对象-此对象提供对接口函数以及整个 krpano 数据结构的访问。
  - pluginpath
    带有 "完整路径 " 的插件对象的字符串, 例如 "plugin [name] "。
  - pluginobject
    krpano 插件对象-此对象提供对所有插件属性和函数的直接访问。
unloadplugin ()
- unloadplugin () 函数将从 krpano 调用, 当插件将被删除。
- 在这里, 插件应该删除它添加的所有内容 (例如图形对象、事件侦听器、计时器、...)。
onresize (宽度、高度) (可选)
- 在调整插件大小时, 将调用 onresize () 函数。
- 参数的宽度和高度是以像素为单位的新大小。
- 在这里, 插件可以调整或调整自己的图形内容。
- onresize () 函数可以选择返回一个布尔值-当它返回 true, 然后 krpano 将尝试自动缩放插件, 当假将返回然后 krpano 不会缩放插件。

krpano 接口对象

"krpano " 对象 ( registerplugin调用中的 "krpanointerface" 参数) 是 krpano 的直接接口。它提供了对整个 krpano 结构和所有功能的直接访问。所有映射的 xml 节点、数组、对象和属性都可以通过它直接访问。此外, 它还提供了一些用于数据访问、操作代码调用/执行的功能以及更多信息, 请参阅下文。

"krpano" 对象的函数:

set (变量、值)
- 将变量设置为给定值。
- 当变量或路径不存在时, 将创建变量和路径。
- 与 xml set ()操作类似。
get (变量)
- 返回变量的值。
- 当变量不存在时返回 "null "。
call (actionscode, callerobject *)
- 将操作代码调用 krpano 操作代码。
  当操作系统当前未被阻止时, 将直接执行给定的操作。
- actionscode = 具有一个或多个 krpano 操作的字符串.
- callerobject (可选) = 调用操作的对象 (例如, 插件对象本身)。这 allowes 直接访问操作代码中的对象属性, 例如仅设置 (x, 1) 而不是设置 (插件 [名称]. x, 1)。
跟踪 (代码、消息)
- 向 krpano 日志中跟踪消息。
- 代码= 消息类型的数字代码:
  - 0 = 调试消息-将只显示启用的调试模式
  - 1 = 信息
  - 2 = 警告
  - 3 = 错误-也将自动打开日志。
  - 4 = 致命错误-此消息将显示在播放器的中间。
parsepath (路径)
parsePath (路径)
- 解析给定路径字符串中的 krpano 占位符。
- 返回值: 已解析的路径字符串。
loadFile (文件, donecallback, errorcallback *)
loadImage (文件、donecallback、errorcallback *) 仅限Flash
- loadFile () -请求将文件作为 ByteArray加载到 Flash (任何类型可能) 中, 或作为 Javascript 中的字符串 (只有文本/xml 文件可能)。
- loadImage () -请求将文件加载为 Flash 加载程序对象 (只有图像/Flash文件)。
- 附加到普通文件这些函数还允许加载嵌入的和加密的文件。它们将在加载过程中自动解密。
- donecallback和 errorcallback -当加载成功或失败时, 将调用这些函数。 errorcallback 的用法是可选的。
  这两个函数都将用对象作为参数调用, 此对象具有以下属性:
  - rqurl
    在 loadFile/loadImage 调用中使用的请求 url。
  - url
    文件的完整 url-解析并解析。
  - 数据
    用于Flash插件: 加载的文件为 ByteArray .
    用于 Javascript 插件: 以字符串形式加载的文件。
  - 装载
    加载的图像的Flash 加载程序对象 (仅 loadImage)。
  - errmsg
    一个带有默认值 "true " 的布尔标志, 指示 krpano 是否应显示自动加载错误信息。仅用于 errorcallback 函数中的用法! 将其设置为 "false " 以禁用默认加载错误消息。
screentosphere (x, y)
spheretoscreen (h, v)
- 用于在屏幕和球面坐标之间转换的函数。
- 返回值: 具有 x 和 y 属性的对象。当无法转换时, 这些属性的值可以是 NaN (而不是数字)。

krpano 插件对象

"插件" 对象 ( registerplugin调用中的 "pluginobject " 参数) 它是 xml < plugin >元素的内部表示形式。所有插件 attriutes 和操作都由它直接访问。

"插件" 对象的特殊插件相关属性:

精灵
- Flash-热点的 Actionscript 3 精灵对象。
- HTML5-插件对象的 HTML < div > 元素。
  注意-当使用插件作为热点时, 只有当通过 CSS3D 呈现热点时, 精灵对象才可用 (请参见渲染器设置)!
- 精灵对象可用于向插件本身添加自定义显示元素 (Flash 中的 DisplayList 元素、HTML5 中的 HTML DOM 元素)。
videoDOM 仅限 HTML5)
- 一种特殊特性, 允许插件提供 HTML5 视频对象进行渲染。
- 当使用插件作为热点或全景图像 (通过 url = "插件: 视频 ") 时, krpano 播放器将使用该视频对象进行渲染。
- 安装程序: videowidth和 videoheight具有视频大小的属性需要添加到插件对象中, 并且一旦视频准备好呈现 onvideoreadyCB功能, 则调用该插件。有关所有详细信息, 请参阅录像机插件的示例源代码。 .
- 特殊用法: 用一些技巧也可以使用 HTML5 画布对象作为视频源。使用画布作为 videoDOM, 并将这些 "伪造" 属性添加到它: readyState=4、videoWidth = 画布. 宽度、currentTime = 时间或帧号 (内容更改时应更改)。

插件对象的特殊插件功能:

registercontentsize (宽度、高度)
- 定义插件显示内容的 "默认 " 大小。
- 这是用户没有设置宽度或高度时将使用的大小。
updatepos ()
- 分析与位置相关的设置并更新插件的内部显示对象。
- 调用此函数后, pixelwidth和 pixelheight变量将包含插件元素的最终像素大小。
getfullpath ()
- 返回 xml 嵌入路径/名称, 例如 "插件 [名称] " 或 "热点 [名称] "。
_assignEvents (htmlelement、模式) (仅 HTML5)
- 将 krpano 插件事件分配给给定的 html 元素。
- 模式-"添加" 用于添加事件, "删除" 以删除。
- 这可以用于特殊的自定义添加的 html 元素, 如 svg 路径元素。

krpano ' Base ' 对象  (编程语言中的 "基类 " 或 "超级类 ")

所有 krpano 映射 xml 节点、对象或数组元素以及 krpano 接口对象都是从 krpano "基" 对象派生的。 "基" 对象具有用于添加/注册新属性以及创建子数组结构的一些基本功能。

"基" 对象的函数:

registerattribute (attributename, 默认, setter *, 吸气 *)
- 向对象添加新属性, 并将其设置为给定的默认值。当对象已经具有该属性 (例如从 xml) 时, 将保留当前值, 但属性的类型将转换为默认值的类型。自动类型转换将用于 "数字 " 和 "布尔 " 数据类型。
  例如: 当属性在 xml 文件中设置为 "123 " 时, 属性的类型为 "String ", 但当注册该属性时具有 "数字 " 默认值, 则该属性也将转换为 "数字 ", 值为123。
  Setter/吸气 (可选)
  可以选择使用 setter 函数而不是普通属性。在这种情况下, 当属性将从 xml 或通过 set接口设置时, 将调用具有新值的 setter 函数, 当属性值被读取时, 将调用 getter 函数来返回值 (注释-禁忌在这种情况下, r/getter 函数将需要存储该值的任何位置)。
  
  从 Actionscript 或 Javascript 访问 setter/getter:
  - 在 Actionscript 中, setter 是特殊的对象。无法直接访问它们 (如普通变量/属性) 是不可能的, 因为 Actionscript 语言没有/支持动态 setter/getter。对于访问值, 这些对象具有用于设置新值的 set (value)函数, 以及用于获取值的 获取 ()函数。
  - 在 Javascript 中, setter/吸气剂表现为正常属性。它们可以直接与普通变量/属性一起使用。
  关于 setter/getter 的说明:
  - Setter 和 getter 是构建数据结构的强大工具。
  - 当属性的值被更改/更新时, 可以使用它们随时获得通知。
  - 与他们它可能检查, 并且, 如果需要改正价值在设置。
  - 和/或设置标志, 并调用其他函数时, 值将被更改。
removeattribute (attributename)
- 从当前对象中移除属性。
getattributes ()
- 获取对象的所有当前属性。
- 返回具有所有属性名称的 Flash/Javascript "数组 "。
createobject (objectname)
- 在当前对象的内部/下方创建一个新的 krpano 基对象。
- 返回新创建的 krpano 基对象。
- 如果对象已经存在, 则将保留并返回退出对象。
removeobject (objectname)
- 从当前对象中移除对象。
createarray (arrayname)
- 在当前对象内创建一个新的 krpano 数组。
- 返回新创建的 krpano 数组对象。
- 如果数组已存在, 则将保留当前数组, 并返回退出的数组。
removearray (arrayname)
- 删除并销毁 krpano 数组对象。

krpano ' 数组 ' 和 ' 数组-项 ' 对象

krpano 中的数组是内部特殊对象, 而不是本机 Javascript 或 Actionscript 数组。当 xml 中的节点具有 "name" 属性时, 或者当具有 "数组路径" (如 "arrayname [itenname]. 变量") 的变量被设置时, 将自动创建一个数组。
数组的项派生自 krpano ' Base ' 对象, 并具有 name和索引的附加属性。除此之外, 这些对象还可以存储任何类型的属性或函数, 还有其他 krpano 数组。

krpano "数组 " 对象的属性:

计数
- 数组中的元素数。
- 可以动态更改, 但只有减少才有意义, 例如将其设置为0以删除所有项。

krpano ' 数组 ' 对象的函数:

createItem (名称或索引) 或
createarrayitem (名称或索引) (从 xml 调用)
- 在数组内创建一个新项。
- 返回新创建的数组项对象。
getItem (名称或索引)
- 获取现有的数组项。
- 返回数组项对象或当项不存在时为 null。
renameItem (oldname: 字符串, newname: 字符串)
- 更改现有项的名称。
removeItem (名称或索引) 或
removearrayitem (名称或索引) (从 xml 调用)
- 从数组中移除项。
- removeItem () 函数返回移除的项对象。
- removearrayitem () 函数与 removeItem () 函数相同, 但没有返回值, 也可从 XML/krpano 操作中调用。
getArray ()
- 返回所有数组项的本机 Actionscript/Javascript "数组 "。
- 可用于直接快速访问。
- 数组项属性可以更改, 但数组本身 (长度、项顺序、...) 没有!

krpano "数组项 " 对象的默认属性:

名称
- 当前数组项的名称 (只读)。
- 此名称可用于直接访问数组项。
索引
- 当前数组项的基于0的索引 (只读)。

krpano WebGL API

krpano HTML5 播放器公开了一个 WebGL API, 用于访问内部 WebGL 画布和上下文以及管理自定义后处理着色。

krpano webGL
- krpano WebGL API 对象。
- 如果对象为 null, 则不存在 WebGL 支持。
krpano.webGL.canvas
- 内部 krpano WebGL < 画布 > 元素。
krpano.webGL.context
- < 画布 > 的 WebGL 呈现上下文。
krpano. webGL createPostProcessingShader (fragment_shader_source, 制服)
- 创建一个 krpano 后处理着色器 (WebGL GLSL 片段着色器)。
- 参数:
  - fragment_shader_source
    - GLSL 着色器源代码作为字符串。
    - 着色器代码需要:
      - 一个名为 sampler2D 的 sm -这将是当前屏幕作为输入纹理。
      - 一个名为 vec2 的 tx -这将是当前的纹理坐标。
      - 可选的 sz vec2 统一-这将包含屏幕大小。
  - 制服
    - 着色器中使用的统一名称的逗号分隔列表。
    - "统一位置" 将自动存储在返回的着色器对象同名。
- 返回:
  - krpano 的 "着色器" 对象。
  - 可以添加到 ppShaderArray数组中,
  - 或用于 useShader .
krpano.webGL.ppShaderArray
- 后处理着色器的数组。
- 这里可以添加、插入或删除自定义着色器。
- 着色器将按该数组中的顺序进行处理。
krpano. webGL. useShader (着色器)
- 选择/激活着色器进行接口, 例如设置统一值。
- 注意-使用后 useShader (null)需要调用以还原上一个着色器! 重要!
krpano. webGL deleteShader (着色器)
- 删除着色器 (释放 WebGL 资源)。
krpano.webGL.restoreProgram ()
- 通知 krpano 在下次使用时需要还原 krpano WebGL 程序。
- 当外部 WebGL 代码更改了当前 WebGL 程序时, 需要调用此项。
krpano. webGL. makeScreenshot (宽度, 高度, 热点, 类型, 质量)
- 在给定的大小中制作一个截图, 并将其作为 data-url/base64-encoded 图像返回。
- 仅当启用 preserveDrawingBuffer设置时才起作用。
- 当出现错误时, 将返回 null。
- 参数:
  - width、 height-以像素为单位的大小 (必需)。
  - hotspots-包括 (webgl) 热点: true 或 false, 默认为 false。
  - type -图像类型-"jpeg" (默认值) 或 "png"。
  - quality-jpeg 图像质量, 默认为 0.0-1.0, 0.85。

例子

具有开放源代码的插件: