Skip to content
Levi Webb edited this page Mar 21, 2018 · 4 revisions

Using and Configuring GLava

GLava installs with two configuration folders that it can use, the install path (usually /etc/xdg), and the user configuration path (usually ~/.config/glava). By default, the user configuration folder is empty (or does not exist), and can be created properly by running glava --copy-config. This will create the following structure in your user config directory:

Name Type Source or target path Description
rc.glsl copied file /etc/xdg/rc.glsl Global user config
smooth_parameters.glsl copied file /etc/xdg/smooth_parameters.glsl Smoothing options
[module].glsl copied file /etc/xdg/glava/module.glsl Module-specific options
[module] symlink /etc/xdg/glava/module Module source files

Module sources are intentionally symlinked to prevent duplicating larger source files and reflect future updates to GLava's modules.

The provided modules for GLava are as follows:

Name Description
bars cava style vertical bar visualizer
radial Similar to bars, except bars are drawn around a circle
graph Draw a vertical, solid graph of the fft output data
wave Draw the raw left audio wave recieved from PulseAudio
circle Draw a circle-style visualizer, where the radius is the visualizer amplitude

Documentation for global settings and modules can be found in the extensive comments in rc.glsl, smooth_parameters.glsl, and other *.glsl config files that belong to their respective modules. If the file does not reside within a subdirectory, then it is meant to be modified by normal users (files within directories are either internal module code or utilities used within other modules).

The configuration format may be confusing at first. This is because the format is in GLSL, the same language that is used to write the shaders that belong to GLava's modules. User parameters are usually set with #request directives (requesting some action from GLava's C code), or with #define (parameters for GLSL shaders). Nearly every behaviour in GLava is configurable via these directives with the following format:

#request [Name of request] [Request parameters]...
#define [Name of macro variable] [Macro contents]

Note that the contents of a variable created with #define copies all text after the variable name, including spaces, into value. Some module configurations use simple GLSL code within #define macros to create interesting effects (ie. color gradients).

Learning some GLSL will also allow you to further extend GLava's behaviour. If you already know GLSL and would like to handle rendering yourself, continue reading the section below.

Writing your own modules

GLava is actually just a C program that sets up the nessecary OpenGL and Xlib code for sets of 2D fragment shaders (executed per pixel) to be ran. It adds special #request directives that GLava itself processes in order for the shader source code request data to be sent to shader uniforms, and to perform some processing on said uniforms before it is sent to the GPU. All of the actual rendering is done in fragment shaders (which are compiled at runtime), thus giving you a lot of freedom on how you would like to display visualizer data.

The general process for making your own module is:

  • Create a folder in either your ~/.config/glava directory for the module, or the shader install path (usually `/etc/xdg/glava) and symlink to the installed module in your local config.

  • Create a 1.frag file inside the folder. This is the first fragment shader executed for the module, and is the final (output) shader if you do not add any additional shaders. If you choose to add more shaders, the output of 1.frag can be requested from 2.frag with #request uniform "prev" <name>, where <name> is the name of the sampler2D uniform you want to bind it to.

  • Optionally create a configuration file for your module (in the root install/config directory), to allow users to set various parameters for your shader. Include it with #include ":mymoduleconfig.glsl" (the : specifies the root config load path).

To obtain nicely processed audio visualizer data in a sampler1D, use the following code:

/* We need the texture size for smoothing */
#request uniform "audio_sz" audio_sz
uniform int audio_sz;

#request uniform "audio_l" audio_l
#request transform audio_l "window"
#request transform audio_l "fft"
#request transform audio_l "gravity"
#request transform audio_l "avg"
uniform sampler1D audio_l;

#request uniform "audio_r" audio_r
#request transform audio_r "window"
#request transform audio_r "fft"
#request transform audio_r "gravity"
#request transform audio_r "avg"
uniform sampler1D audio_r;

#include ":util/smooth.glsl"

And then obtain your smoothed data using the smooth_audio function with one of the audio textures like so:

float result = smooth_audio(audio_l, audio_sz, index, 0.025);

Where index is a value between 0.0F (inclusive) and 1.0F (exclusive). The final parameter can be increased or decreased for more or less smoothing. smooth_audio is a simple kernel smoother that uses parameters from :smooth_parameters.glsl.

Clone this wiki locally
You can’t perform that action at this time.