GLSL preprocessor and minifier

A fork of webpack-glsl-minify written in javascript with webpack related features removed.

Install

npm install --save-dev @mapwhit/glsl-minify

Usage

GLSL Preprocessor

The preprocessor uses an @ symbol to distinguish commands executed at Webpack compile time versus shader compile time. The following commands are supported:

include Directive

Includes another GLSL file. Example:

@include "../path/another-file.glsl"

define Directive

Defines a macro which will be substituted elsewhere in the code. Example:

@define PI 3.1415
// ....
float angle = 2.0 * PI;

Note that @define is not a replacement for #define. For minification purposes, it is often better to let the shader compiler do the macro substitution instead of the Webpack compiler.

nomangle Directive

Disables name mangling on one or more symbols. Example:

@nomangle symbol1 symbol2

const Directive

Defines a constant variable with a unique substitution value that can be used to search-and-replace to initialize the constant. Example:

@const int my_int

will produce

const int A=$0$;

and the mapping from my_int to the substitution value $0$ will be returned in the output.

Minification

The following minification optimizations are performed:

• Removal of comments and whitespace. Both C-style /* Comment */ and C++-style // Comment are supported.
• Shortening floating point numbers. 1.0 becomes 1.
• Mangling symbol names. All functions, variables, parameters, and uniforms are renamed to short names. Built-in GLSL functions and variables begining with gl_ are automatically excluded. Attributes and varying variables are also excluded, as the names must be consistent across multiple shaders. Additional symbols may be excluded with the @nomangle directive.

Output

By default, an object is exported via JavaScript containing the source code and a map of the mangled uniforms and constants:

module.exports = {
  sourceCode: 'uniform vec3 A;uniform float B;/* ... More minified GLSL code here */',
  uniforms: {
    // Map of minified uniform variables
    uniform1: {
      // Unminified uniform name
      variableName: 'A', // Minified uniform name
      variableType: 'vec3' // Type of the uniform
    },
    uniform2: {
      variableName: 'B',
      variableType: 'float'
    } // ...
  },
  consts: {
    // Map of minified const variables
    const1: {
      // Unminified const name
      variableName: '$0$', // Substitution value to replace to initialize the const
      variableType: 'vec2' // Type of the const
    } // ...
  }
};

The map of uniforms is included to make it easy for the JavaScript code compiling and executing the WebGL shader to set the uniform values, even after minification.

Command line

@mapwhit/glsl-minify provides a command-line tool. By default, it produces .js files for each of the input .glsl files specified, output in the same directory as the source .glsl. Alternatively, the -outDir parameter may be used to produce output in a separate output directory mirroring the input directory layout.

$ npx @mapwhit/glsl-minify --help
glsl-minify <files..> [options]

Minifies one or more GLSL files. Input files may be specified in glob syntax.

Options:
  --version            Show version number                             [boolean]
  --ext, -e            Extension for output files      [string] [default: ".js"]
  --outDir, -o         Output base directory. By default, files are output to
                       the same directory as the input .glsl file.      [string]
  --output             Output format
                 [choices: "object", "source", "sourceOnly"] [default: "object"]
  --esModule           Uses ES modules syntax. Applies to the "object" and
                       "source" output formats.                        [boolean]
  --stripVersion       Strips any #version directives                  [boolean]
  --preserveDefines    Disables name mangling of #defines              [boolean]
  --preserveUniforms   Disables name mangling of uniforms              [boolean]
  --preserveVariables  Disables name mangling of variables             [boolean]
  --preserveAll        Disables all mangling                           [boolean]
  --nomangle           Disables name mangling for a set of keywords      [array]
  --includesOnly       Only process include files                      [boolean]
  --help               Show help                                       [boolean]

License

Copyright (c) 2018-2022 Leo C. Singleton IV. Copyright (c) 2025 Damian Krzeminski.

This software is licensed under the MIT License.