ACMX Vulkan Shader Library
GLSL 4.50 shader effects for ACMX's Vulkan renderer
Loading...
Searching...
No Matches
ACMX Default Vulkan Shader Library

Introduction

The ACMX Default Vulkan Shader Library is the standard collection of visual effects for the ACMXVK rendering backend. It contains more than 2,600 GLSL 4.50 fragment and compute shaders designed for real-time cameras, video files, still images, recording, playlists, live editing, audio reactivity, and MIDI-controlled performance.

ACMX is a real-time GPU video-synthesis and glitch-art workstation. Its Qt interface provides one workflow for selecting media, browsing shader libraries, assembling multipass effects, editing source, controlling custom uniforms, creating playlists, reacting to audio, mapping MIDI controls, and recording the result. The interface can launch either of two rendering backends:

Backend Graphics system Shader workflow
ACMX2 OpenGL / libmx2 The established GLSL engine and its legacy-compatible libraries.
ACMXVK Vulkan / MXVK Manifest-based GLSL source compiled to SPIR-V, with mixed fragment and compute pipelines.

This site documents the default ACMXVK source library. Its shaders are not automatically interchangeable with ACMX2 shaders because Vulkan uses an explicit descriptor ABI and compute shaders require a storage-image output. The ACMX interface hides much of that distinction during normal use.

ACMX links

What the shaders do

Every shader transforms the image produced by the preceding stage. A shader can be used by itself, as one pass in a longer chain, or as part of a named playlist node. The collection covers several broad families of effects:

  • Color and palette effects remap channels, quantize values, invert or posterize colors, create gradients, and animate procedural palettes.
  • Geometric effects mirror, rotate, stretch, fold, tunnel, ripple, tile, and kaleidoscope the source image.
  • Digital-glitch effects emulate channel displacement, scan-line damage, block corruption, datamoshing, bitwise logic, pixel sorting, and frame tearing.
  • Temporal and cache effects combine the current frame with older frames from a circular texture array. They create trails, echoes, recursive feedback, motion persistence, temporal XOR, and delayed mosaics.
  • Audio-reactive effects use amplitude, frequency bands, the current FFT spectrum, or a history of spectra to drive color, displacement, symmetry, and animation.
  • Procedural effects generate mandalas, fractal fields, plasma, waves, tunnels, cellular patterns, and other synthesized structures while still incorporating the source image.

Filenames are intentionally descriptive. A name containing cache normally uses frame history, while audio or spectrum identifies an audio-reactive shader. Files ending in .frag are fragment shaders and files ending in .comp are compute shaders. Those conventions make a very large library practical to search and combine.

Processing and multipass chains

ACMXVK compiles the source entries in library.json with glslc and writes the resulting .spv files plus a runtime manifest to the selected build directory. At runtime, MXVK executes the selected passes in order using ping-pong render images: pass one receives the media frame, pass two receives pass one's result, and so on. MXVK inserts the image transitions and memory barriers needed between fragment and compute work.

This ordering is creatively significant. A kaleidoscope followed by a color quantizer is different from a quantizer followed by a kaleidoscope. A cache effect placed late in the chain records a more heavily transformed result, while one placed early supplies temporal structure to every later pass. Playlist nodes preserve that order and can be selected manually, randomized, or changed by ACMX's crossfade and autopilot controls.

Video-mode timing follows the decoded media timeline. Consequently, animated shader motion is repeatable and does not speed up merely because an offline render processes frames faster, or slow down because a demanding effect takes longer to render. Camera and still-image modes use their corresponding live/normalized timing controls.

Fragment and compute shaders

Stage How it works Good uses
Fragment (.frag) Runs for each output fragment, samples the preceding image with normalized texture coordinates, and writes one color. Palette work, warps, mirroring, compositing, feedback sampling, and most full-screen effects.
Compute (.comp) Dispatches workgroups over pixel coordinates, samples binding 0, and explicitly writes binding 5. Tile algorithms, bitwise pixel operations, block glitches, neighborhood processing, and effects that map naturally to image-space kernels.

A compute shader must bounds-check gl_GlobalInvocationID.xy, because MXVK rounds dispatch dimensions up to complete workgroups. Common workgroup sizes are 8x8 or 16x16. Fragment and compute passes can be freely mixed in the same chain; the output of either stage becomes the sampled input of the next one.

ACMXVK shader interface

All descriptors use set 0. A shader should declare only the resources it actually reads or writes.

Binding Resource Purpose
0 sampler2D input_image Image produced by the media loader or preceding pass. Always available.
1 SpriteExtended uniform block Resolution, time, frame information, mouse state, scalar audio values, and up to 64 custom floats.
2 sampler2DArray history Optional circular frame-history cache shared by the active chain.
3 sampler1D spectrum Current 256-bin floating-point FFT spectrum.
4 sampler1DArray spectrum_history Circular history of earlier FFT spectra.
5 writeonly image2D output_image Required compute-shader destination; use rgba8 for SDR or rgba16f for HDR.

Binding numbers and descriptor types are part of the binary interface. GLSL variable names are not, so sources use several conventional names such as samp, input_image, and history. SPIR-V reflection lets ACMXVK detect cache and spectrum descriptors and prepare their runtime resources. Missing audio is represented safely by zero-filled spectrum data.

The complete binding-1 block is:

layout(set = 0, binding = 1, std140) uniform SpriteExtended {
vec4 mouse;
vec4 u0;
vec4 u1;
vec4 u2;
vec4 u3;
vec4 custom_uniforms[16];
vec4 audio_bands;
vec4 audio_history;
} ext;
layout(set=0, binding=1, std140) uniform SpriteExtended
Definition 3high.frag:7
ext
Definition 3high.frag:16

Frequently used values include ext.u0.y for media time, ext.u0.zw for render resolution, ext.u1.y for processed audio amplitude, ext.u2.x for the source-frame index, ext.u2.y for shader time, ext.u3.xy for the history head and layer count, and ext.audio_bands.xyz for low-, mid-, and high-frequency energy. A shader may stop the block after its last required field, but it must never reorder or omit earlier members.

Custom uniforms, MIDI, and live editing

The source manifest maps friendly names, ranges, defaults, and scalar slots to custom_uniforms[16]. Four consecutive values can be exposed as slider1 through slider4, for example:

#define slider1 ext.custom_uniforms[5].x
#define slider2 ext.custom_uniforms[5].y
#define slider3 ext.custom_uniforms[5].z
#define slider4 ext.custom_uniforms[5].w

The ACMX interface presents these values as named controls and can publish changes to the running engine immediately. A MIDI configuration can map physical knobs or faders to the same values. This lets one shader expose artist-friendly parameters such as scale, symmetry count, distortion, rotation speed, feedback amount, or color intensity without recompilation. Source edits can also be compiled and live-reloaded while ACMXVK is running; a failed preview leaves the last valid SPIR-V pipeline active.

Example effects

acidcam.frag: the reference pass

acidcam.frag samples binding 0 at the incoming texture coordinate and returns the color unchanged. Although visually simple, it is useful for verifying a library build, comparing transformed output with the source, and serving as a neutral pass while constructing a multipass chain.

acidcam_010_kaleidoscope.comp: mirrored geometry

This compute shader converts each pixel to polar coordinates around the image center. It divides the angle into six sectors, reflects alternate sectors, converts the folded coordinate back to image space, and samples the source there. The result is a stable six-way mirror that turns faces, rooms, and landscape edges into a moving mandala.

acidcam_004_history_xor_cache.comp: temporal XOR

This shader reads both the current frame and a selected layer of binding 2. It quantizes their channels to 8-bit integers, applies a bitwise XOR, and scales the result with its controls. Stationary areas retain structured digital patterns while motion exposes sharp differences from earlier frames. Increasing the cache delay produces wider temporal separation and a more fragmented look.

acidcam_050_datamosh_bands.comp: simulated codec damage

The image is divided into horizontal bands. A time-varying hash gives each band its own horizontal displacement and vertical drag, while selected samples receive a chromatic split. It resembles damaged motion vectors and displaced video blocks without requiring a corrupted input file. Adjusting its custom value changes the band size and displacement strength.

acidcam_058_pixel_sort_bands.comp: luminance streaks

This compute effect examines short horizontal spans and selects bright or dark candidates according to position and time. Blending those extrema back into the source produces directional streaks resembling pixel sorting. It works especially well after a high-contrast palette or edge-enhancement pass because the luminance choices become more pronounced.

ant_cache_spectrum8_oilslick.frag: audio, history, and color

This fragment shader combines eight cached image layers with eight layers of spectrum history. Audio energy drives displacement and chromatic separation, while a cosine palette converts the accumulated temporal data into an iridescent oil-slick surface. It demonstrates how the library can combine image history, current FFT data, spectral history, audio peaks, and animated color in one effect.

Mandala and fractal families

Files such as ant_cache_spectrum8_mandala.frag and ant_spectrum_kaleidoscope_dream.frag layer angular repetition, mirrored coordinates, procedural color, source sampling, and audio response. Their repeated geometry makes small source movements fill the frame, while the spectrum changes symmetry, displacement, or brightness in time with music. Different mandala shaders emphasize crisp tiling, fluid feedback, neon palettes, or recursively warped detail.

Example combinations

Useful chains often give each pass one clear job:

  1. Geometric performance: kaleidoscope, then a palette or color-cycle shader. Geometry creates repetition and the final pass unifies its color.
  2. Temporal glitch: datamosh bands, then history XOR, then chromatic separation. Motion is displaced before the cache comparison and colored at the end.
  3. Audio dreamscape: an audio displacement shader, an image-history mandala, then a restrained color pass. The early audio pass moves the image while the cache pass turns that movement into trails.
  4. Readable pixel sorting: contrast or edge enhancement, pixel-sort bands, then a mild blend with the source. Strong features give the sorter useful extrema while the final blend preserves recognizable content.

More passes are not automatically better. Each full-resolution pass costs GPU time and changes what all later passes receive. Short chains with a deliberate order are usually easier to control and reproduce.

History and audio requirements

A history shader uses a circular array of earlier input frames. The layer count controls both the available delay and GPU memory consumption, which grows with render resolution. ACMXVK can infer binding 2 from the compiled shader; explicit cache options remain useful when choosing the desired history depth. On the command line, a typical cache test is:

acmxvk --shaders .acmxvk-build \
--shader-file compute/acidcam_004_history_xor_cache.comp.spv \
--texture-cache-array --texture-cache-size 8

Audio shaders can react to scalar amplitude values in binding 1, the current FFT in binding 3, or the FFT history in binding 4. ACMX can use live audio or the audio track of a video as the analysis source. If no source is active, audio values remain zero and the shader continues to run, though its reactive movement may become still.

HDR behavior

For PQ or HLG video, ACMXVK converts the media into linear BT.2020 before the user shader chain and transfer-encodes it again afterward. Fragment shaders continue sampling floating-point colors through binding 0. Compute sources intended for HDR must use an rgba16f binding-5 output variant instead of rgba8; values outside the SDR range can then survive intermediate passes.

Browsing this documentation

Use the Files tree to browse shader names or use the search box to locate a visual family such as cache, spectrum, mandala, xor, pixel, or tunnel. Each file page contains its Doxygen summary, documented helper functions, and complete GLSL source. The declarations at the beginning of a file show exactly which descriptors and controls that effect requires.

Building the shader library

From this directory, compile the manifest with ACMXVK's builder:

acmxvk --build library.json --builddir .acmxvk-build --parallel 4

The builder preserves source subdirectories, compiles only entries that need updating, and emits a runtime library.json that refers to the generated SPIR-V files. The Qt interface's Build action performs the same workflow for the currently loaded ACMXVK source library.

Build this documentation separately with:

doxygen Doxyfile

The generated site is written to doxygen/html/index.html.