npm package: @mapwhit/glsl-minify
Description: GLSL Preprocessor and Minifier
Author: Leo C. Singleton IV
Latest version: 1.0.0

[![NPM version][npm-image]][npm-url]
[![Build Status][build-image]][build-url]
[![Dependency Status][deps-image]][deps-url]

# 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

```glsl
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:

```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.

### 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.

```console
$ 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](https://www.leosingleton.com/).
Copyright (c) 2025 [Damian Krzeminski](https://pirxpilot.me).

This software is licensed under the [MIT License](LICENSE).

[webpack-glsl-minify]: https://npmjs.org/package/webpack-glsl-minify

[npm-image]: https://img.shields.io/npm/v/@mapwhit/glsl-minify
[npm-url]: https://npmjs.org/package/@mapwhit/glsl-minify

[build-url]: https://github.com/mapwhit/glsl-minify/actions/workflows/check.yaml
[build-image]: https://img.shields.io/github/actions/workflow/status/mapwhit/glsl-minify/check.yaml?branch=main

[deps-image]: https://img.shields.io/librariesio/release/npm/@mapwhit/glsl-minify
[deps-url]: https://libraries.io/npm/@mapwhit%2Fglsl-minify