Skip to content

VisualEffects

Jump to bottom
rbn42 edited this page Feb 18, 2021 · 40 revisions

Visual effects installed along with panon can be found here. Visual effects installed through the Download New Effects dialog can be found in ~/.local/share/panon/, and you can create your own visual effects in the same folder.

Shaders are written in GLSL language. A visual effect may consist of a single main shader file with its name ended with .frag, like solid.frag, or a folder, like spectrogram/, with the following struture.

  • effect folder
    • image.frag, is the main shader file, must exist.
    • buffer.frag, draws to the buffer(iChannel2), is optional.
    • hint.html, shows hints to the user, is optional.
    • meta.json, declares the arguments for the user, is optional.
    • texture.png, a static image to be used as a texture(iChannel3), is optional.

Shader API and Shadertoy.com

What is a shader? And a turtorial for beginners.

Shadertoy.com is a cross-browser online community and tool for creating and sharing shaders through WebGL, from where you can find many wonderful works shared by kind people. By default, these works are licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. And here is an interactive tutorial for shadertoy.com.

Panon’s shader API is designed to be similar to shadertoy.com. Many of the works can be copied directly to panon, providing you add #version 130 to the shader file’s first line. example-shadertoy.frag is such an example. But all these works were designed to be shown in a browser, so they won’t look good in tiny room like a panel.

These shadertoy-like uniforms are provided by panon.

  • iResolution : vec3
    • Width and heigh of the applet
  • iTime : float
  • iTimeDelta : float
  • iBeat : float
    • If iBeat > 0, then this frame is a beat, otherwise not. Provided by aubio. See example-iBeat/. This uniform is not available before panon 0.4.1, and it is only available when using pulseaudio as the back-end. To use this uniform, you must install python-aubio.
  • iFrame : int
  • iMouse : vec4
  • iChannel0 : sampler2D
    • Wave data: Red channel corresponds to left audio channel, green channel corresponds to right audio channel.
  • iChannel1 : sampler2D
    • Spectrum data: Red channel corresponds to left audio channel, green channel corresponds to right audio channel.
  • iChannel2 : sampler2D
    • Buffer data: Output of buffer.frag, has the same width and height of the applet.
  • iChannel3 : sampler2D
    • The static image texture.png. This example shows how to use it.
  • iChannelResolution : vec3[]
    • Input channels’ width and height

Both image.frag (or the single main shader) and buffer.frag can access these uniforms.

Arguments

Arguments exposed in the configuration dialog are declared in meta.json. meta.json contains a JSON list like this.

{
  "arguments":[{
    "name":"arg_name",
    "default":3,
    "type":"int"
  }]
}

A decalred argument can be referenced in a shader file’s macros, like

#define NAME $arg_name

Which will be translated (by build_shader_source.py) into

#define NAME int(3)

“type”s of arguments

Name Shown as Will be translated into Introduced by
“bool” CheckBox bool panon 0.3.0
“color” ColorButton vec4 panon 0.4.1
“double” (legacy) TextField float panon 0.3.0
“float” TextField float panon 0.4.2
“int” TextField int panon 0.3.0

Util functions

There are 2 libraries provided. hsluv-glsl by William Malo ( https://github.com/williammalo ) and hsv2rgb from ( https://gist.github.com/patriciogonzalezvivo/114c1653de9e3da6e1e3 ). They can be used to convert hsluv and hsv colors into rgb colors. With these 2 libraries, I created the function vec3 getRGB(double x), x is expected to range from 0 to 1. getRGB(x) can be used to generate the color defined by user’s color space configurations.

Debugging

Neither KDE Panel nor Latte-Dock shows the errors caused by the shaders. To catch the error messages, you need to install plasma-sdk, and start plasmoidviewer in a console.

#Providing plasma-sdk is installed
$ plasmoidviewer --applet ./plasmoid/

In plasmoidviewer, go to the configuration window and choose your own visual effect. Then plasmoidviewer will run your visual effect and show the errors, if exist, in the console.

Publish a visual effect

You can share your visual effect by publish it on store.kde.org, under “Linux/Unix Desktops > Desktop Extensions > KDE Extensions > Panon Shader” category. So that other people can install your effect through the Doawload New Effects dialog.

Clone this wiki locally