VisualEffects

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.

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 space like a panel.

These shadertoy-like uniforms are provided by panon.

Uniform Name	Type	Description
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. See example-iBeat/
iFrame	int
iMouse	vec4	Mouse position. This example shows how to use it.
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"
  }]
}

“type” can be “int”, “double” or “bool”. A decalred argument can be used in a shader file’s macros, like

#define NAME $arg_name

Which will be translated (by build_shader_source.py) into

#define NAME 3

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.