Z滤镜插件

krpano插件, 第三方插件

简介

Z滤镜是一个后处理WebGL着色器插件，可实现全景图、layer和hotspot的动态效果，您可以为启动界面、场景变化、弹出窗口添加视觉效果，例如设置或调整简单属性可调节亮度，饱和度或模糊你的全景图！

  • 调整着色器 gamma、亮度、对比度，曝光、色调、饱和度、鲜艳度、怀旧、反转和混合色
  • 使用blur和fblur（fastblur）进行模糊！
  • 渐晕和颜色融合！
  • 有趣的着色器旋转、像素化、波纹、分裂和索贝尔！
  • 支持layer和hotspot的滤镜和背景滤镜！亮度、对比度、饱和度、色调、褐色调、反转、模糊、阴影
  • 可实时显示数值的编辑器

 

语法使用

  • 将zfilter.js添加到项目中
  • 在html (index/tour.html)中确认嵌入设置为 html5:”only+webgl”
  • 在主xml (tour.xml) 中添加
    或者直接把上面一整段包含全部默认值的代码块复制
  • 下面是一个简单的例子，可以通过设置初始属性值来完成开场动画
    结合onstart动作，将属性恢复回默认值。
  • 注意：z滤镜经过优化，可最大限度地减少设备上的性能负载。如果所有属性都设置为默认值，则插件将保持空闲状态，不会执行任何操作，完全不影响性能。

 

插件属性

属性名 类型 值
ready (只读) Boolean true | false
version (只读) String 插件版本号
shaders  (只读) Number 发生作用的着色器数量
shadernames (只读) String 发生作用的着色器名字
url String zfilter.js
preload Boolean true
keep Boolean true
regkey String
  • 如果插件加载并准备好应用时，ready为true
  • version记录插件版本号。
  • shaders包含发生作用的着色器数量
  • shadernames包含发生作用的WebGL着色器名字 (按照发生作用的次序)
  • url必须指向插件。
  • preload设置为true
  • 在绝大多数情况下，keep设置为true
  • regkey为插件注册码
属性名 类型 默认值 最小值 最大值
enabled Boolean true
phase Number 2 1 2
order String
iorder (read only) String adjust|swirl|pixelate|ripple|sobel|split|fblur|
blur|blendcolor|vignettecolor|mixcolor
webvr Number 2 0 3
csslegacy Boolean false
addzfilter Boolean false
  • enabled 全局启用或禁用全部后处理效果
  •  phase:
    • phase=”1″ 发生在渲染全景图后但在渲染热点之前
    • phase=”2″发生在渲染全景图后以及渲染热点之后
      • 可以查看krpano相关后处理文档
    • phase 用于设置Z滤镜属性的默认或特定阶段
    • phase 永远不会未定义，如果被忽略，则自动回退到上一次定义的默认值
    • 例子:
      • phase=”2″ 对所有Z滤镜属性设置为阶段2
      • phase=”2|blur=1|mixcolor=1″为 blur 和 mixcolor设置单独的阶段
    • 注意: phase仅支持 krpano 1.20以上版本
  • order:
    • order 用于在多个后处理插件被使用时的全局插件次序。
      order 永远不会未定义，如果被忽略，则会设置堆栈上的最高顺序

      • 可以查看krpano相关后处理文档
    • 除了全局的插件次序，order也可以设置Z滤镜的内部次序
    • 可以使用属性名更改内部次序，而无需赋值
    • 全局次序分配（numbers）在Z滤镜内部次序（names）之前
    • 例子:
      • order=”5″ 为所有Z滤镜属性设置次序
      • order=”5|blur=7|adjust=3″为 blur 和 adjust设置单独的次序
      • order=”5|blur|sobel” 设置内部次序，
        虽然所有z滤镜属性的次序都是5，但内部顺序现在是
        iorder=”“adjust|blur|swirl|pixelate|ripple|split|fblur|sobel|blendcolor|vignettecolor|mixcolor”“
      • order=”5|blendcolor=4|blur|sobel” 设置内部次序，在sobel之前执行blur，同时在默认值为5的情况下，为blendcolor设置为4
    • 注意:
      • 调整滤镜 (brightness, contrast, saturate, 等等) 被处理为组合后处理滤镜，因此无法单独设置次序
      • 如果使用了多个后处理插件，你应该为每一个设置单独的次序，不然可能或遇到滤波器干扰。
      • order仅支持 krpano 1.20以上版本
  • iorder 用于获取Z滤镜内部次序
    • iorder 是只读属性，无法用于改变数值！
    • 包含Z滤镜属性的单独次序
    • 例子:
      • order=”2|blur=3|fblur=1″ 也就是
        iorder=”“fblur|adjust|swirl|pixelate|ripple|sobel|split|blendcolor|vignettecolor|mixcolor|blur”“
  • webvr 用于对特定的webVR级别抑制z滤镜
    • z滤镜经过高度优化，在台式机、平板电脑和手机上表现出色。
      遗憾的是，在真正的webVR（即Oculus Go、Quest、Rift等）并非如此，
      其中在大多数设备上，WebGL性能较差。
    • 因此，默认值 webvr=”2″对于真正的webVR可抑制z滤镜。
    • webvr可用的设置:
      0=普通 / 非 VR, 1=fake VR, 2=mobile VR, 3=真 WebVR
  • csslegacy=”true” 启用layer和热点的遗留值范围
    zFilter 3更改了数值范围，使其与krpano 1.21兼容+
    重要:csslegacy=“true”仅适用于1.21以下的krpano！
  • addzfilter=”true” 使得不必为层和热点调用addzfilter()
    默认值为false，因为筛选器通常只用于特定的元素
    重要: addzfilter=”true”需要kprano 1.21+才能工作！

 

插件属性 (后处理滤镜)

属性 类型 默认值 最小值 最大值
gamma Number 2.2 0.0 4.4
brightness Number 0.0 -1.0 1.0
contrast Number 0.0 -1.0 1.0
exposure Number 0.0 -1.0 1.0
hue Number 0.0 -1.0 1.0
saturate Number 0.0 -1.0 1.0
vibrance Number 0.0 -1.0 1.0
sepia Number 0.0 0.0 1.0
invert Number 0.0 0.0 1.0
  • 基础图像滤镜
  • 例子:
    • set(plugin[zfilter].brightness, 0.25);
    • tween(plugin[zfilter].saturate, -1.0, 1.0);
属性 类型 默认值 最小值 最大值
swirl Number 0.0 0.0 1.0
pixelate Number 0.0 0.0 1.0
ripple Number 0.0 0.0 1.0
sobel Number 0.0 0.0 1.0
split Number 0.0 -1.0 1.0
  • swirl 漩涡效果
  • pixelate 像素化效果
  • ripple 波纹效果
  • sobel sobel边缘检测
  • split rgb通道分离
  • 例子:
    • set(plugin[zfilter].split, 0.5);
    • tween(plugin[zfilter].sobel, 1.0, 1.0);
属性 类型 默认值 最小值 最大值
fblur Number 0 0 50
fquality Number 6 0 32
blur Number 0 0 50
  • fblur (快速模糊) 快速高速模糊
  • fquality 定义 fblur的质量
    • 低质量设置下，fblur会有噪点
      但即使fquality设置到最大值，它仍然比标准的模糊滤镜要速度快
    • 推荐根据设备来单独设置
      所选值较低是为了获得最佳的设备支持
  • blur是没有伪影的高质量模糊
    • 注意: blur使用智能的、性能优化的算法，
      模糊值越高，需要的WebGL着色器过程就越多。
      在低性能设备上，应避免高模糊值或使用fblur。
  • 例子:
    • set(plugin[zfilter].fblur, 9);
    • tween(plugin[zfilter].fblur, 25, 1.0);
属性 类型 默认值 最小值 最大值
blendcolor String 0 0 0xffffffff
blendmode String add
  • blendcolor 通过混合模式将图像与颜色混合 (alpha 100% = 已融合图像)
  • 32bit ARGB :
    • 第一个: alpha (0x00 禁用着色器)
    • 第二个: red
    • 第三个: green
    • 第四个: blue
  • 支持的融合模式:
    • add, subtract, multiply, darken, colorburn, linearburn, lighten, screen
    • colordodge, lineardodge, overlay, softlight, hardlight, vividlight, linearlight,
    • pinlight, difference, exclusion, hue, saturate, color, luminosity, mix
  • 例子:
    • set(plugin[zfilter].blendmode, ‘overlay’);
    • set(plugin[zfilter].blendcolor, 0xffff0000);
    • tween(plugin[zfilter].blendcolor, 0x8000ff00, 1.0);
属性 类型 默认值 最小值 最大值
vignettecolor String 0 0 0xffffffff
  • vignettecolor 在图像上混合一个黑色渐晕
  • 32bit ARGB :
    • 第一个: alpha (0x00 禁用着色器)
    • 第二个: red
    • 第三个: green
    • 第四个: blue
  • 例子:
    • set(plugin[zfilter].vignettecolor, 0xffc01090);
    • tween(plugin[zfilter].vignettecolor, 0xff5060b0, 1.0);
属性 类型 默认值 最小值 最大值
mixcolor String 0 0 0xffffffff
  • mixcolor 将图像与颜色混合 (alpha 100% = 指定的颜色)
  • 32bit ARGB :
    • 第一个: alpha (0x00 禁用着色器)
    • 第二个: red
    • 第三个: green
    • 第四个: blue
  • 例子:
    • set(plugin[zfilter].mixcolor, 0xffff0000);
    • tween(plugin[zfilter].mixcolor, 0x8000ff00, 1.0);

 

32bit ARGB

32位ARGB值由4个字节组成，每个字节的范围为十六进制0x00到0xff。
通常32位ARGB值用于颜色并映射到透明通道、红色、绿色和蓝色，
但是z滤镜也可以将它们映射到其他参数，如渐晕颜色属性中。
上面为每个属性描述了字节到着色器的参数映射。

  • 可以通过十进制或十六进制格式的数字或字符串设置32位ARGB值
  • 读取32位ARGB值将返回十六进制格式的字符串
  • 例子:
    • ARGB数值0x801eff64代表:
      0x8000ff00 –> A = 0x80/128, R = 0x1e/30, G = 0xFF/255, B = 0x64/100
    • set(plugin[zfilter].blendcolor, 0x8000ff00);
    • tween(plugin[zfilter].blendcolor, 0xffff0000, 2.0);
    • copy(col, plugin[zfilter].blendcolor);

 

Layer 及 Hotspot 属性

z滤镜允许在layer和hotspot上使用CSS过滤器属性，
使用时有下列限制条件:

  • hotspot和layer必须通过调用addzfilter()手动初始化
    在移除layer/hotspot之前使用removezfilter() 进行释放
  • krpano 1.21 以上:
    如果addzfilter=”true”则自动执行addzfilter()
    在任何情况下removezfilter() 都会自动执行
  • 支持的属性:
    brightness, contrast, saturate, hue, sepia, invert, blur, dropshadow and
    bgbrightness, bgcontrast, bgsaturate, bghue, bgsepia, bginvert, bgblur
  • Hotspot需要设置 renderer=css3d
  • 浏览器支持:
    普通的过滤器在大多数主流浏览器下可正常运行
    但是支持可能会有所不同，特别是在多个过滤器处于活动状态的情况下。
  • 注意: krpano 1.21 对CSS过滤器仅提供有限的支持
    (background, layers, type=container 或 text)
    zFilter 对CSS过滤器提供全部支持
    (foreground & background, hotspots & layers, type=container, text 以及 image)

layer/hotspot初始化后，对其添加的zFilter属性可以像任何其他krpano layer属性一样使用：

  • set(hotspot[myhotspot].saturate, -1);
  • tween(layer[mylayer].blur, 15, 1);
  • tween(layer[mylayer].blur|layer[mylayer].alpha, 15|0, 1);

 

Layer and Hotspot 属性 (CSS 过滤器)

属性 类型 默认值 最小值 最大值
brightness / bgbrightness Number 1.0 0.0
contrast / bgcontrast Number 1.0 0.0
saturate / bgsaturate Number 1.0 0.0
hue / bghue Number 0.0
sepia / bgsepia Number 0.0 0.0 1.0
invert / bginvert Number 0.0 0.0 1.0
blur / bgblur Number 0.0 0.0
dropshadow String     参看layer.bgshadow

krpano 1.21+的新值范围或csslegacy=“false”的旧krpano版本
注意：这些范围对应于常规CSS过滤器的值范围

属性 类型 默认值 最小值 最大值
brightness / bgbrightness Number 0.0 -1.0 1.0
contrast / bgcontrast Number 0.0 -1.0 1.0
saturate / bgsaturate Number 0.0 -1.0 1.0
hue / bghue Number 0.0 -1.0 1.0
sepia / bgsepia Number 0.0 0.0 1.0
invert / bginvert Number 0.0 0.0 1.0
blur / bgblur Number 0.0 0.0 50.0
dropshadow String    参看 layer.bgshadow

csslegacy=“true”的旧krpano版本的旧/遗留值范围
注意：这些范围对应于zFilter提供的全景后处理过滤器

注意：csslegacy=“true”仅支持1.21以下的旧krpano版本！
在kprano 1.21上，必须使用新的值范围！

addzfilter 对指定的layer或hotspot初始化z滤镜。
对其添加的zFilter属性可以像任何其他krpano属性一样使用：

  • layer or hotspot
    如 “layer[mylayer]” 或 “hotspot[myhotspot]”这样的对象和字符串
    如果 layer/hotspot不存在，则自动创建

例子:

  • addzfilter(layer[mylayer]); // string
  • addzfilter(get(hotspot[myhotspot])); // object

removezfilter 对指定的layer或hotspot移除z滤镜

参数:

  • layer or hotspot
    如 “layer[mylayer]” 或 “hotspot[myhotspot]”这样的对象和字符串

 haszfilter检查z滤镜是否添加到指定的layer或hotspot

参数:

  • variable
    返回值的目标变量（true或false）
  • layer or hotspot
    如 “layer[mylayer]” 或 “hotspot[myhotspot]”这样的对象和字符串

 zfiltersupport 检查浏览器是否支持layer/hotspot过滤。

Parameters:

  • variable
    返回值的目标变量（true或false）

 

兼容性/限制

  • krpano 1.20 或以上版本, 仅能支持html5 + webgl
  • 后处理滤镜可在全景图以及 renderer=webgl 的热点上使用
  • Layer 和 hotpot过滤器支持有限的效果，需要 renderer=css3d
  • 对Layer 和 hotpot的过滤器支持取决于浏览器。
  • 对于真正的WebVR支持是试验性的。