BassBox GLSL Plugin – Minimal Tutorial (Template Walkthrough)
This post explains how to use the provided bbp_GLSL.cpp + GLSL.h template
to build a simple GLSL-based visual plugin for BassBox64 / MBox64.
The goal is not to introduce “modern OpenGL”, but to show how a GLSL fragment shader
is integrated cleanly into the existing BassBox OpenGL pipeline.
The template uses:
- a legacy full-screen quad (glBegin / glVertex)
- a minimal passthrough vertex shader
- a fragment shader driven by audio and time
- a 32-color LUT system shared between CPU and GPU
----------------------------------------------------------------
1) Plugin lifecycle (BBProc)
----------------------------------------------------------------
The host communicates with the plugin through the exported function:
ExportC long BBProc(BBPLUGIN &BBP);
The most important messages are:
BBP_CREATE
Called once to declare plugin identity and rendering mode.
Here you set:
- title
- author
- version
- BBP_OPENGL (mandatory for GLSL plugins)
BBP_INIT
Called once when the plugin is initialized.
This is where you:
- bind the host OpenGL context (wglMakeCurrent)
- reset OpenGL state
- initialize time and audio variables
- create textures (including the LUT)
- compile and link GLSL shaders
- cache uniform and sampler locations
BBP_RENDER
Called every frame.
This is where you:
- update time and audio values
- send uniforms to the shader
- bind textures
- draw a full-screen quad
BBP_SIZE
Called when the plugin window is resized.
You must update glViewport and internal width/height.
BBP_DESTROY
Called when the plugin is unloaded.
You must delete:
- GLSL program
- textures
- any allocated resources
----------------------------------------------------------------
2) Rendering model
----------------------------------------------------------------
This template uses a very simple and reliable rendering model:
- A full-screen quad is drawn in clip space (-1 .. +1)
- The vertex shader simply forwards gl_Vertex to gl_Position
- The fragment shader runs once per pixel
No VBO, no VAO, no FBO, no multipass.
This keeps the focus on the shader logic itself.
----------------------------------------------------------------
3) Core uniforms provided to the shader
----------------------------------------------------------------
The following uniforms are automatically filled by the plugin:
uniform vec3 iResolution;
- x = viewport width in pixels
- y = viewport height in pixels
- z = 1.0 (convention)
uniform float iTime;
- Accumulated animation time
- Already modulated by audio on the CPU side
- Suitable for driving motion directly
uniform float iAudio;
- Smoothed audio level
- Typically in the range 0.0 .. 1.0 (may slightly exceed)
- Stable enough for visual modulation
uniform vec3 iLutColor;
- One color selected from the 32-color LUT
- Chosen on the CPU side according to audio peaks
- Already normalized (0..1)
uniform vec3 iMouse;
- Present for compatibility
- Currently set to (0,0,0) in the template
- Can be wired later via BBP_MOUSE
uniform vec4 iDate;
- Only iDate.w is used in the template
- Contains raw system time in seconds
- Useful if you need a non-audio-modulated time source
----------------------------------------------------------------
4) LUT system (CPU + GPU)
----------------------------------------------------------------
The template defines a 32-color palette:
- On the CPU:
- gP.color[32] : packed ARGB
- gP.fR/G/B[32]: normalized float values
- On the GPU:
- a 32x1 RGB texture bound to iChannel1
You can:
- use iLutColor for a single selected color
- sample iChannel1 in the shader for custom palette logic
The LUT texture uses:
- GL_NEAREST filtering
- GL_CLAMP_TO_EDGE wrapping
----------------------------------------------------------------
5) Demo fragment shader (what it shows)
----------------------------------------------------------------
The provided demo shader demonstrates:
- coordinate normalization using iResolution
- time-based animation using iTime
- audio-driven modulation using iAudio
- color tinting using iLutColor
- a simple ring/pulse effect
- a subtle vignette
It does NOT require:
- any texture input
- any mouse interaction
- any advanced OpenGL features
Alpha output is set to 1.0, producing an opaque image.
----------------------------------------------------------------
6) Where to modify things
----------------------------------------------------------------
To change the visual effect:
Edit the quoted GLSL string inside:
static GLuint CompileShaderFromString()
To add textures:
Populate gP.mt[] in BBP_INIT and sample them as iChannel0..3.
To enable transparency:
- Output alpha < 1.0 in gl_FragColor
- Enable blending in BBP_INIT or BBP_RENDER
- Ensure the host compositing mode supports it
To react more strongly to audio:
- Adjust the scaling of audioNow
- Modify smoothing factor
- Use iAudio directly in the shader
----------------------------------------------------------------
7) Why this template matters
----------------------------------------------------------------
This template is intentionally:
- minimal
- stable
- legacy-compatible
- host-friendly
It avoids:
- undefined OpenGL state
- hidden multipass logic
- fragile modern-only constructs
Once this base works reliably, more complex shaders and techniques
can be layered on top with confidence.
----------------------------------------------------------------
End of tutorial
----------------------------------------------------------------
The VS 2022 bbp_GLSL.zip is attached to this post
