KMS GLSL is a command line tool that runs OpenGL fragment shaders, using the DRM/KMS Linux kernel subsystem. It runs shaders fullscreen, and does not require any windowing system, like X or Wayland.
It has initially been developed to run shaders from Shadertoy, on the Raspberry Pi, using the VC4/V3D KMS driver, that supports OpenGL ES 3.1 (as of January 2023). However, it should work with any GPU and display controller hardware, provided a DRM/KMS driver is available. It has been successfully tested with the Jetson Nano, as well as the Raspberry Pi Zero.
In the following picture, this Shadertoy shader runs on the Raspberry Pi 4, connected to the official Raspberry Pi 7" touchscreen monitor, in WVGA (800ร480) resolution:
Another shader that runs on the Jetson Nano in full HD (1920ร1080) resolution:
You need to clone the project, and run the following commands:
$ sudo apt update
# Install the build tools
$ sudo apt install gcc make
# Install the required DRM, GBM, EGL and OpenGL ES API headers
$ sudo apt install libdrm-dev libgbm-dev libegl-dev libgles2-mesa-dev
# Install the X C binding and RandR extension header / library files (optional)
$ sudo apt install libxcb-randr0-dev
# Build the glsl binary and library
$ make
Once you've successfully built the binary / library, you can either run it directly, or use the Python wrapper, that adds a layer for managing shader inputs, that you can also extend to add your own custom inputs.
$ ./glsl -h
Usage: ./glsl [-aAcDfmpvx] <shader_file>
options:
-a, --async use async page flipping
-A, --atomic use atomic mode setting and fencing
-c, --count run for the specified number of frames
-D, --device=DEVICE use the given device
-f, --format=FOURCC framebuffer format
-h, --help print usage
-m, --modifier=MODIFIER hardcode the selected modifier
-p, --perfcntr=LIST sample specified performance counters using
the AMD_performance_monitor extension (comma
separated list)
-v, --vmode=VMODE specify the video mode in the format
<mode>[-<vrefresh>]
-x, --surfaceless use surfaceless mode, instead of GBM surface
You can try it with the shaders available in the examples
directory, e.g.:
$ ./glsl examples/costal_landscape.glsl
Press Ctrl+c to exit the program.
You can explore shadertoy.com to find additional shaders.
Note the shaders from the examples
directory assume OpenGL ES 3.1 support, and may not work with lower versions of the specification.
No inputs can be provided using the native CLI directly. You can use the Python wrapper, that adds a layer around the native library for managing shader inputs, as explained below.
$ python glsl.py -h
usage: glsl.py [-h] [--async-page-flip | --no-async-page-flip]
[--atomic-drm-mode | --no-atomic-drm-mode] [-D DEVICE] [--mode MODE]
[-k UNIFORM] [--touch UNIFORM] [-c UNIFORM FILE] [-t UNIFORM FILE]
[-v UNIFORM FILE] [-m <UNIFORM>.KEY VALUE]
FILE
Run OpenGL shaders using DRM/KMS
positional arguments:
FILE the shader file
optional arguments:
-h, --help show this help message and exit
--async-page-flip, --no-async-page-flip
use async page flipping
--atomic-drm-mode, --no-atomic-drm-mode
use atomic mode setting and fencing
-D DEVICE, --device DEVICE
the DRM device
--mode MODE specify the video mode in the format
<resolution>[-<vrefresh>]
-k UNIFORM, --keyboard UNIFORM
add keyboard
--touch UNIFORM add touch device
-c UNIFORM FILE, --cubemap UNIFORM FILE
add cubemap
-t UNIFORM FILE, --texture UNIFORM FILE
add texture
-v UNIFORM FILE, --volume UNIFORM FILE
add volume
-m <UNIFORM>.KEY VALUE, --metadata <UNIFORM>.KEY VALUE
set uniform metadata
Note
Python 3.10+ is required.
You can try it with the shaders available in the examples
directory, e.g.:
$ python glsl.py examples/plasma_globe.glsl -t iChannel0 presets/tex_RGBA_noise_medium.png
Press Ctrl+c to exit the program. You can explore shadertoy.com to find additional shaders.
If you want to add your own inputs, you can find the documentation and some examples in the glsl.py
file.
Assuming you've installed Raspberry Pi OS, the DRM/KMS VC4/V3D driver can be configured by running the following commands:
-
Edit the
/boot/config.txt
file, e.g.:$ sudo vi /boot/config.txt
-
Set the following properties:
# Required: Enable the DRM/KMS VC4 V3D driver dtoverlay=vc4-kms-v3d # Optional: Increase the memory reserved for the GPU gpu_mem=128
-
Reboot your Raspberry Pi, so that the changes are taken into account, e.g.:
$ sudo reboot
Note this also works with the Raspberry Pi OS Lite versions, as it does not need any compositor like X, Wayland or similar.
It has successfully been tested on the RPi 4, running the Raspberry Pi OS 2023-09-22, Linux kernel 5.15.
- Add support for texture buffers
- Add support for audio / video inputs
- Parse GLSL files to retrieve uniforms metadata
The DRM/KMS ceremony code is copied from kmscube.
The shader examples are copied from the Shadertoy website URLs commented at the top of each file.