| 02de0a76 |
In order to promote modularity, interoperability and consistency, this document
tries to lay forward a set of conventions, mostly surrounding naming. This is
important when moving from a monolithic copy-and-paste regime, especially for
shaders, to one based on re-usable libraries. Historical (often deprecated)
OpenGL, other graphics APIs, uniformity and brevity are the main points of
reference and driving forces.
[`glconventions`]: https://git.rcrnstn.net/rcrnstn/glconventions
[OpenGL]: https://en.wikipedia.org/wiki/OpenGL
## Spaces and matrices
```
mat4 world;
mat4 view;
mat4 projection;
```
Note that `world` is what is sometimes known as `model`. OpenGL historically
had a combined `modelview` matrix which transformed *from* model space all the
way (through world space) *to* view space. Since having to name each matrix
with both the "from" space *and* "to" space results in overly long names, the
convention chosen here is to only use the "to" space name. This is consistent
with Direct3D. When we combine space names in a matrix name we use several "to"
space names, e.g. `view_world` or `projection_view_world`. Note the order! It
is the same as order of multiplication: `projection_view = projection * view`.
The "from" space is implicitly the space before the (last) named "to" space;
model->world->view->projection.
To enable instancing, `world` is (always) specified as a vertex attribute.
`view` and `projection` are uniforms (optionally a uniform block).
[`glVertexAttrib`]: https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glVertexAttrib.xhtml
## Shaders
### Variable naming
- [Uniforms][]
- `*`
- Vertex shader [inputs][] (attributes)
- `vert_*` (both per-vertex and per-instance data)
uniforms
- Geometry shader [inputs][]
- `geom_*`
- Fragment shader [inputs][] (vertex or geometry shader [outputs][])
- `*`
- Fragment shader [outputs][] (data)
- `frag_*`
Note that the prefixes correspond to the file extensions used by the [GLSL
reference compiler][].
Every name that is general enough that a collision might occur, even in
principle, must be suffixed with an `0`-based index (without any separating
`_`). Examples include `in vec4 color0`, `uniform sampler2D texture0`, `out
vec4 frag_data0`.
[uniforms]: #uniforms
[inputs]: #inputs
[outputs]: #outputs
[GLSL reference compiler]: https://www.khronos.org/opengles/sdk/tools/Reference-Compiler/
### Uniforms
#### Geometric
```glsl
uniform mat4 view;
uniform mat4 projection;
```
If the GLSL code is distributed with corresponding CPU code to set its
uniforms, the following is also acceptable, since the names and their scope is
the same:
```glsl
uniform camera
{
mat4 view;
mat projection;
}
```
Note that this is a [uniform block][] and requires [uniform buffer][] support,
i.e. OpenGL [\>=3.1][] or the [`ARB_uniform_buffer_object`][] extension.
Further more, it requires some more work on the CPU. The advantage is that the
uniforms do not have to be set for every used shader program and can be set
"globally" e.g. once per frame.
[uniform block]: https://www.khronos.org/opengl/wiki/Interface_Block_(GLSL)
[uniform buffer]: https://www.khronos.org/opengl/wiki/Uniform_Buffer_Object
[\>=3.1]: https://en.wikipedia.org/wiki/OpenGL#Version_history
[`ARB_uniform_buffer_object`]: https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_uniform_buffer_object.txt
### Inputs
#### Geometric
```glsl
in mat4 {prefix_}world;
in vec3 {prefix_}position;
in vec3 {prefix_}normal;
in vec2 {prefix_}tex_coord;
```
In order of likelihood to be needed.
#### Common
```glsl
in vec4 {prefix_}color0;
```
### Outputs
As a general rule, all inputs should be forwarded to outputs because, in a
modular world, it may not be known what input the next shader stage requires.
All geometric quantities should be outputted in the [standard space][] of the
next shader stage *and* in any spaces between the standard space of the current
shader stage (exclusive) and the next. Specifically, this means the vertex
shader should output e.g. both `vec3 normal` and `vec3 world_normal`.
Unused outputs will be optimized out in the link stage.
The overwhelmingly most common fragment shader output is `vec4
frag_color`, and it is acceptable if data that might not quite be color
is written to this output, provided that it is the only output and that
the data can be held in `GL_RGBA8` (i.e. only 8 bits per channel).
[standard space]: #standard-spaces
### Standard spaces
Each shader stage has a standard space in which input geometric quantities are
expressed:
- vertex: `model`
- geometry: `view`
- fragment: `view`
Quantities that is not expressed in the standard space has the space prefixed,
e.g. `world_normal`.
|
git.rcrnstn.net