Skip to content
Snippets Groups Projects

SRB2 Shader Guide

Last edited by Hannu Hanhi

SRB2 has basic support for mods that replace the GLSL vertex and fragment shaders used by the OpenGL renderer. Currently shader mods apply to the entire game. Level-specific or character-specific shaders, for example, are not supported by the current shader system. NOTE: As the OpenGL renderer in SRB2 is developed further, the shader system may get changed and the backward compatibility has not been decided. This guide was written for SRB2 version 2.2.8.

A shader mod consists of a configuration file and one or more shader source files. For WADs the configuration is stored inside a lump called SHADERS and for PK3s it's stored in a SHADERS file on the root of the package. In WADs the shader sources are in lumps whose names begin with SH_ and in PK3s the source filenames must start with sh_ and be placed in a folder named Shaders.

Configuration file

The configuration file (or lump) determines what shaders are replaced. You first determine the type of shader to replace with a line that either says "GLSL Fragment" or "GLSL Vertex". All lines after this will replace either fragment or vertex shaders. Each line consists of the vanilla shader to be replaced, an equals sign and the name of the replacement shader.

There are 7 shaders that can be replaced by mods:

  • Flat: All floors and ceilings are rendered with this shader, except when WaterRipple is used.
  • WallTexture: All walls are rendered with this.
  • Sprite: This shader is used for sprite rendering.
  • Model: This shader is used for rendering models.
  • WaterRipple: Surfaces that have the water ripple effect applied to them are rendered with this shader.
  • Fog: Fog blocks are rendered with this shader.
  • Sky: This shader is used for rendering the sky backdrop texture. (Not the skybox)

Example configuration file:

GLSL Fragment
Flat = Shiny
Fog = NoiseGenerator
GLSL Vertex
WaterRipple = WobblyVertices

When SRB2 reads this example configuration in a PK3, it will replace two fragment shaders with Shaders/sh_Shiny.glsl and Shaders/sh_NoiseGenerator.glsl and one vertex shader with Shaders/sh_WobblyVertices.glsl. (Other file extensions work too)

Shader source files

The shader source consists of code written in the GLSL language. This guide assumes basic knowledge of GLSL.

2.2.8's default shaders for reference (written using C macros) https://git.do.srb2.org/STJr/SRB2/blob/SRB2_release_2.2.8/src/hardware/r_opengl/r_opengl.c#L618

Uniform variables

The shaders have access to the following uniform variables:

  • vec4 poly_color: This is a RGBA color, that is always white. The alpha value is set depending on the translucency of the surface.
  • vec4 tint_color: The color of the colormap (linedef type 606) applied to the surface. 0,0,0,0 for no colormap.
  • vec4 fade_color: The color that light fades into. It is black by default and can be modified by the colormap linedef special.
  • float lighting: The light level of the surface. Ranges from 0 to 255.
  • float fade_start: The start of the light fade in the colormap. Ranges from 0 to 31.
  • float fade_end: The end of the light fade in the colormap. Ranges from 0 to 31.
  • float leveltime: The time in the level. Measured in seconds.

Shader compatibility and errors

The default shaders are meant to be compatible with (desktop) OpenGL version 2.0. If you want best compatibility, you should probably write for GLSL version 1.10. Link to the specifications: https://www.khronos.org/registry/OpenGL/specs/gl/GLSLangSpec.1.10.pdf Higher versions may work, depending on the user's GPU and drivers.

Any errors encountered during shader compilation and linking are reported by SRB2 to the console when loading the shader mod. However, just having the shader load succesfully on your machine unfortunately does not mean that it will also work on other machines! Some GPU drivers are less strict on following the GLSL standard and will allow minor discrepancies in the code without throwing an error. Therefore, to ensure compatibility across a wide variety of graphics processors (from NVIDIA, AMD, Intel etc.) I suggest you check your code using the OpenGL Reference Compiler found here: https://www.khronos.org/opengles/sdk/tools/Reference-Compiler/

Comments

    Please register or sign in to add a comment.