GLSL Loader, Preprocessor, and Minifier for Webpack
npm install webpack-glsl-minifywebpack-glsl-minify is a loader for Webpack that handles GLSL files. In addition to simply loading the GLSL program
into a JavaScript string, it also has a preprocessor which executes at compile time, and a minifier which shrinks the
GLSL program before embedding it in JavaScript.
npm install --save-dev webpack-glsl-minify
Usage
$3
To use, add the following to your webpack.js config file:javascript
module: {
rules: [
{
test: /\.glsl$/,
use: 'webpack-glsl-minify'
}
]
},
resolve: {
extensions: [ '.glsl' ]
}
`$3
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
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
glsl
const int A=$0$;
`
and the mapping from to the substitution value $0$ will be returned in the output.$3
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 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.$3
By default, an object is exported via JavaScript containing the source code and a map of the mangled uniforms and
constants:
`javascript
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.
TypeScript type definitions are included in the webpack-glsl-minify package for the output object. Simply cast to a
object when including GLSL code:
`javascript
import { GlslShader, GlslVariable, GlslVariableMap } from 'webpack-glsl-minify';let shader = require('./myshader.glsl') as GlslShader;
`Loader Options
javascript
module: {
rules: [
{
test: /\.glsl$/,
use: {
loader: 'webpack-glsl-minify',
options: {
output: 'object',
esModule: false,
stripVersion: false,
preserveDefines: false,
preserveUniforms: false,
preserveVariables: false,
disableMangle: false,
nomangle: [ 'variable1', 'variable2' ],
includesOnly: false,
}
}
}
]
},
resolve: {
extensions: [ '.glsl' ]
}
`This loader also supports the following loader-specific options:
*
: Default 'object', which outputs JavaScript code which exports an object described in the section above.
Alternatively, 'source' may be specified which exports only a string containing the source code instead.
Selecting 'source' automatically disables mangling of uniforms as there is no output map of the mangled names.
* esModule: Default false. Uses ES modules syntax instead of CommonJS. Applies to the "object" and "source"
output formats.
* stripVersion: Default false. Strips any #version directives.
* preserveDefines: Default false. Disables name mangling of #defines.
* preserveUniforms: Default false. Disables name mangling of uniforms.
* preserveVariables: Default false. Disables name mangling of variables.
* preserveAll: Default false. Disables all mangling.
* disableMangle: Default false. Disables name mangling. This is useful for development purpose.
* nomangle: Specifies an array of additional variable names or keywords to explicitly disable name mangling.
* includesOnly: Default false. Disables all processing except include files. Useful for development!Using Without Webpack
Additionally, webpack-glsl-minify provides a command-line tool which can be used as a build step without Webpack. 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.`console
$ npx webpack-glsl-minify --help
webpack-glsl-minify [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]
`Compiling From Source
The source code is written in TypeScript. The build script supports two commands:*
- Compiles the output to build/
*