Home

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

Documentation for user-facing module and global settings 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 (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.

Other resources

• List of uniform and transform requests