git.rcrnstn.net - rcrnstn/glconventions

@@ -2,6 +2,151 @@
                                      An [OpenGL][] conventions document.
                                     +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`.
+                                    +
                                      ## License
                                      Licensed under the [CC BY 4.0 License][] unless otherwise noted, see the

@@ -1,3 +1,10 @@
                                      # [`glconventions`][]
                                      An [OpenGL][] conventions document.
+                                    +
                                     +## License
+                                    +
                                     +Licensed under the [CC BY 4.0 License][] unless otherwise noted, see the
                                     +[`LICENSE`](LICENSE) file.
+                                    +
                                     +[CC BY 4.0 License]: https://choosealicense.com/licenses/cc-by-4.0/

                                     new file mode 100644
@@ -0,0 +1,3 @@
                                     +# [`glconventions`][]
+                                    +
                                     +An [OpenGL][] conventions document.

Add content

Add license

Add readme