# [`glslrun`][]
Run [GLSL][] code on the CPU.
Generates a wrapper file including some [C++][] standard library functionality
and [OpenGL Mathematics (GLM)][], compiles it with the systems C++ compiler (by
default [`gcc`][], can be changed by setting the [environment variable][]
`CXX`) and runs the result.
This, of course, does not *really* run GLSL code on the CPU. For an actual GLSL
compiler (but not to something that can run on the CPU), see [`glslang`][].
The wapper does the following:
- C++ standard library
- Brings the `std` namespace into global scope.
- `#include`s [`cassert`][] for testing.
- `#include`s [`iostream`][] for printing.
- GLM
- Brings the `glm` namespace into global scope.
- `#define`s `GLM_FORCE_SWIZZLE` to enable [swizzling][] support.
- `#include`s [`glm/gtx/io.hpp`][] to enable [`iostream`][] support.
- Other
- `#define`s `GLSLRUN`.
- Defines [built-in variable][]s (like [`gl_Position`][]).
- Defines [built-in function][]s (like [`EmitVertex`][]).
[`glslrun`]: https://git.rcrnstn.net/rcrnstn/glslrun
[GLSL]: https://en.wikipedia.org/wiki/OpenGL_Shading_Language
[C++]: https://en.wikipedia.org/wiki/C++
[OpenGL Mathematics (GLM)]: https://glm.g-truc.net
[`gcc`]: https://gcc.gnu.org
[environment variable]: https://en.wikipedia.org/wiki/Environment_variable
[`glslang`]: https://github.com/KhronosGroup/glslang
[`cassert`]: https://en.cppreference.com/w/cpp/header/cassert
[`iostream`]: https://en.cppreference.com/w/cpp/header/iostream
[swizzling]: https://en.wikipedia.org/wiki/Swizzling_(computer_graphics)
[`glm/gtx/io.hpp`]: http://glm.g-truc.net/0.9.9/api/a00332.html
[built-in variable]: https://www.khronos.org/opengl/wiki/Built-in_Variable_(GLSL)
[`gl_Position`]: https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/gl_Position.xhtml
[built-in function]: https://www.khronos.org/opengl/wiki/Built-in_Function_(GLSL)
[`EmitVertex`]: https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/EmitVertex.xhtml
## Usage
`glslrun --help`:
```
glslrun 1.0
Run GLSL code snippets on the CPU.
usage:
glslrun [options] [--] [<file>]
glslrun -h|--help
glslrun --version
arguments:
<file>
File containing code to run. If <file> is omitted or -, to read from
stdin instead.
options:
-m, --main
Generate an enclosing main() function.
-p, --print
Print the generated code that is passed to the compiler.
```
### Editor integrations
#### Vim
Add the following [Vimscript][] to `.vimrc`:
```vimscript
autocmd FileType glsl
\ set makeprg=glslrun
```
[`:make`][] (or [`:Dispatch`][]) runs this configured `makeprg`.
`:copen` opens the quickfix list.
[Vimscript]: https://en.wikipedia.org/wiki/Vim_(text_editor)#Vim_script
[`:make`]: https://vimhelp.org/quickfix.txt.html#:make
[`:Dispatch`]: https://github.com/tpope/vim-dispatch
#### Visual Studio Code
Add the following [JSON][] task to `.vscode/tasks.json`:
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "glslrun",
"type": "process",
"command": "glslrun",
"args": [ "${file}" ],
"problemMatcher": "$gcc"
}
]
}
```
<kbd>Ctrl</kbd><kbd>P</kbd> opens the Command Palette in which `task glslrun`
can be typed.
<kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>\`</kbd> opens the terminal output.
<kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>M</kbd> opens the list of problems.
[JSON]: https://en.wikipedia.org/wiki/JSON
[launch configuration]: https://code.visualstudio.com/docs/editor/debugging#_launch-configurations
## Dependencies
For compiling C++:
- C++ compiler (e.g. from [`g++`][])
- C++ standard library (e.g. from [`libstdc++`][])
- OpenGL Mathematics (GLM) (e.g. from [`libglm-dev`][])
All other dependencies are [POSIX][] (except `mktemp`, but most Unix-like
systems have some version), and are highly likely to be installed by default
(e.g. they all have the [Debian priority][] `required`).
- `sh` (e.g. from [`bash`][] or [`dash`][])
- `rm`, `cat`, `mktemp` (e.g. from [`coreutils`][])
- `sed` (e.g. from [`sed`][])
- `awk` (e.g. from [`mawk`][])
[`g++`]: https://packages.debian.org/g++
[`libstdc++`]: https://packages.debian.org/libstdc++
[`libglm-dev`]: https://packages.debian.org/libglm-dev
[POSIX]: https://en.wikipedia.org/wiki/POSIX
[Debian priority]: https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities
[`bash`]: https://packages.debian.org/bash
[`coreutils`]: https://packages.debian.org/coreutils
[`dash`]: https://packages.debian.org/dash
[`sed`]: https://packages.debian.org/sed
[`mawk`]: https://packages.debian.org/mawk
## Example
```glsl
TODO
```
## License
Licensed under the [ISC License][] unless otherwise noted, see the
[`LICENSE`](LICENSE) file.
[ISC License]: https://choosealicense.com/licenses/isc/
git.rcrnstn.net