Doc: Add GLSL std430 memory layout documentation

3 months ago · b6e68eccec
4 changed files with 344 additions and 0 deletions
--- a/doc/README.org
+++ b/doc/README.org
@ -0,0 +1,9 @@
 #+TITLE: Documentation
 #+AUTHOR: Riyyi
 #+LANGUAGE: en
 #+OPTIONS: toc:nil
 Topics:
 - [[./shaders.org][Shaders]]
 - [[./references.org][References]]
--- a/doc/memory-layout.org
+++ b/doc/memory-layout.org
@ -0,0 +1,326 @@
 #+TITLE: Memory Layout
 #+AUTHOR: Riyyi
 #+LANGUAGE: en
 #+OPTIONS: toc:nil
 This chapter is about the memory layout of interface blocks in GLSL.
 An interface block is a group of variables, a struct if you will.
 There are 4 types of memory layouts that can be used, where the first two aren't
 widely used as those are implementation dependent and require querying the
 OpenGL API for memory offsets.
 - packed
 - shared
 - std140
 - std430
 ** std140
 This type is usable in Uniform Buffer Objects (=UBO=) and Shader Storage Buffer
 Objects (=SSBO=).
 ** std430
 This type is only usable in Shader Storage Buffer Objects (=SSBO=).
 Main points:
 - Memory is organized into chunks.
 - One chunk has 4 slots, 4 bytes per slot.
 - Can't fit? Move to next chunk.
 - An interface block is at least the size of 1 chunk.
 The rules:
 - Scalar =bool=, =int=, =uint=, =float=, and =double=
 #+BEGIN_SRC
 Both the size and alignment are the size of the scalar in basic machine types
 (e.g., sizeof(GLfloat))
 #+END_SRC
 - Two-componment Vectors (e.g., =ivec2=)
 #+BEGIN_SRC
 Both the size and alignment are twice the size of the underlying scalar type.
 #+END_SRC
 - Three-component Vectors (e.g., =vec3=) and Four-component Vectors (e.g., =vec4=)
 #+BEGIN_SRC
 Both the size and alignment are four times the size of the scalar type. However,
 this is only true when the member is part of an array or nested structure
 #+END_SRC
 - Array of Scalars and Vectors
 #+BEGIN_SRC
 The size of each element in the array will be the same size of the element type,
 where three-component vectors are rounded up to the size four-component
 vectors. This is also the array's alignment. The array's size will be the
 element size times the number of elements.
 #+END_SRC
 - Column-major matrix or an array of column-major matrices of size C columns and R rows
 #+BEGIN_SRC
 Same layout as an array of N vectors each with R components, where N is the
 total number of columns present.
 #+END_SRC
 - Row-major matrix or an array of row-major matrices of size R rows and C columns
 #+BEGIN_SRC
 Same layout as an array of N vectors each with C components, where N is the
 total number of rows present.
 #+END_SRC
 Both =GLSL= and the =GLM= math library we're using have column-major matrices!
 - Single-structure definition or an array of structures
 #+BEGIN_SRC
 Structure alignment is the same as the alignment of the biggest structure
 member, where three-component vectors are rounded up to the size of
 four-component vectors. Each structure will start on this alignment, and its
 size will be the space neeeded by its members, according to the previous rules,
 rounded up to a multiple of the structure alignment.
 #+END_SRC
 All of the examples described in the following segments are verified by querying
 the OpenGL API.
 *** Scalars
 These types take up 1 (or 2 with =double=) slot and can appear after anything.
 In the example below you can see that due to the larger alignment, the ~double~
 is forced to the next chunk.
 #+BEGIN_SRC glsl
 //        Var    Size    Alignment    Offset
 bool      a; //   4       4            0
 int       b; //   4       4            4
 uint      c; //   4       4            8
 double    d; //   8       8           16
 float     e; //   4       4           24
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][b][c][ ] #1
 [d][d][e][ ] #2
 #+END_SRC
 *** Two-component Vectors
 **** Float
 A Vec2 takes up 2 slots, so will be in the first or last half of a chunk.
 #+BEGIN_SRC glsl
 //        Var    Size    Alignment    Offset
 vec2      a; //   8       8            0
 float     b; //   4       4            8
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][a][b][ ] #1
 #+END_SRC
 #+BEGIN_SRC glsl
 //        Var    Size    Alignment    Offset
 float     a; //   4       4            0
 vec2      b; //   8       8            8
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][ ][b][b] #1
 #+END_SRC
 **** Double
 #+BEGIN_SRC glsl
 //        Var    Size    Alignment    Offset
 float     a; //   4       4            0
 dvec2     b; //  16      16           16
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][ ][ ][ ] #1
 [b][b][b][b] #2
 #+END_SRC
 *** Three-component and Four-component Vectors
 A Vec3 takes up 3 slots, the alignment is 4 slots so only fits at the start of a
 chunk.
 #+BEGIN_SRC glsl
 //        Var    Size    Alignment    Offset
 vec3      a; //  12      16            0
 float     b; //   4       4           12
 vec4      c; //  16      16           16
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][a][a][b] #1
 [c][c][c][c] #2
 #+END_SRC
 #+BEGIN_SRC glsl
 //        Var    Size    Alignment    Offset
 float     a; //   4       4            0
 vec3      b; //  12      16           16
 vec4      c; //  16      16           32
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][ ][ ][ ] #1
 [b][b][b][ ] #2
 [c][c][c][c] #3
 #+END_SRC
 *** Array of Scalars and Vectors
 #+BEGIN_SRC glsl
 //        Var    Size    Alignment    Offset
 float[3]  a; //  12       4            0
 float     b; //   4       4           12
 float     c; //   4       4           16
 float[3]  d; //  12       4           20
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][a][a][b] #1
 [c][d][d][d] #1
 #+END_SRC
 *Note* the optimizations in the alignment and strides are not applicable to
 ~vec3~ elements, these remain unchanged from =std140=.
 #+BEGIN_SRC glsl
 //        Var    Size    Alignment    Offset
 float     a; //   4       4            0
 vec3[3]   b; //  48      16           16
 float     c; //   4       4           64
 float     d; //   4       4           68
 vec2[2]   e; //  16       8           72
 float     f; //   4       4           88
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][ ][ ][ ] #1, offset:  0
 [b][b][b][ ] #2, offset: 16
 [b][b][b][ ] #3, offset: 32
 [b][b][b][ ] #4, offset: 48
 [c][d][e][e] #5, offset: 64
 [e][e][f][ ] #6, offset: 80
 #+END_SRC
 *Note* the offset needs to be a multiple of the alignment, forcing an entire
 empty chunk in the example below.
 #+BEGIN_SRC glsl
 //        Var    Size    Alignment    Offset
 float     a; //   4       4             0
 dvec2[2]  b; //  32      16            16
 dvec3[2]  c; //  64      32            64
 float     d; //   4       4           128
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][ ][ ][ ] #1, offset:   0
 [d][d][d][d] #2, offset:  16
 [d][d][d][d] #3, offset:  32
 [ ][ ][ ][ ] #4, offset:  48
 [c][c][c][c] #5, offset:  64
 [c][c][ ][ ] #6, offset:  80
 [c][c][c][c] #7, offset:  96
 [c][c][ ][ ] #8, offset: 112
 [d][ ][ ][ ] #9, offset: 128
 #+END_SRC
 *** Matrices
 Alignment is the same as an array of 1 “row” of the matrix.
 No padding between the “rows” of a matrix, but will pad at the end.
 #+BEGIN_SRC glsl
 //        Var    Size    Alignment    Offset
 float     a; //   4       4             0
 mat2      b; //  16       8             8
 vec2      c; //   4       4            24
 float     d; //   4       4            32
 mat2[2]   e; //  32       8            40
 float     f; //   4       4            72
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][ ][b][b] #1, offset:   0
 [b][b][c][c] #2, offset:  16
 [d][ ][e][e] #3, offset:  32
 [e][e][e][e] #4, offset:  48
 [e][e][f][ ] #5, offset:  64
 #+END_SRC
 TODO: Add more examples
 *** Structs
 Alignment same as biggest struct member. Size is the size of all members,
 rounded up to a multiple of the alignment.
 In the example below you can see that the ~Stuff~ struct, including padding
 between members, is 20 bytes in size. To make that a multiple of the alignment
 additional padding needs to be put at the end, to make the total size 24 bytes.
 Each element in the array of structs will apply the alignment again, as seen
 with ~Stuff[1].a~.
 #+BEGIN_SRC glsl
 struct Stuff {
 	float a;
 	vec2 b;
 	float c;
 };
 //        Var    Size    Alignment    Offset
 Stuff     a; //  20       8
        a.a; //   4       4            0
        a.b; //   8       8            8
        a.c; //   4       4           16
 float     b; //   4       4           24
 Stuff[2]  c; //  44       8
        c.a; //   4       4           32
        c.b; //   8       8           40
        c.c; //   4       4           48
 float     d; //   4       4           80
 #+END_SRC
 #+BEGIN_SRC
 Chunks:
 [a][ ][a][a] #1, offset:   0
 [a][ ][b][ ] #2, offset:  16
 [c][ ][c][c] #3, offset:  32
 [c][ ][c][ ] #4, offset:  48
 [c][c][c][ ] #5, offset:  64
 [d][ ][ ][ ] #6, offset:  80
 #+END_SRC
 TODO: Add more examples
 * References
 - https://learnopengl.com/Advanced-OpenGL/Advanced-GLSL
 - https://www.khronos.org/opengl/wiki/Interface_Block_(GLSL)#Memory_layout
 - [[https://www.oreilly.com/library/view/opengl-programming-guide/9780132748445/app09lev1sec2.html][The std140 Layout Rules]]
 - [[https://www.youtube.com/watch?v=JPvbRko9lBg][(YouTube) WebGL 2: Uniform Buffer Objects]]
--- a/doc/references.org
+++ b/doc/references.org
@ -0,0 +1 @@
--- a/doc/shaders.org
+++ b/doc/shaders.org
@ -0,0 +1,8 @@
 #+TITLE: Shaders
 #+AUTHOR: Riyyi
 #+LANGUAGE: en
 #+OPTIONS: toc:nil
 Topics:
 - [[./memory-layout.org][Memory Layout]]