1. rcrnstn/glslquad
  2. README.md
Browse code

Add implementation

Robert Cranston authored on 20/12/2021 13:03:47
Showing 1 changed files
README.md
History View file @ d56f1a4
... ... 
@@ -2,11 +2,123 @@
2 2
3 3 
 A [GLSL][]/[OpenGL][] [\>=3.2][] [quad][] library.
4 4
5 
+The main functionality is [generation][] of (2D or 3D) quads with the provided
6 
+[vertex shader][] and [geometry shader][], expected to be used with a custom
7 
+[fragment shader][].
8 
+
9 
+Mostly as a convenience, [fragment shader][]s are provided for [drawing][] (2D
10 
+or 3D) textures.
11 
+
12 
+Other libraries, interoperating well with this one, that may be of interest:
13 
+
14 
+-   [`glshader`][], easing the use of [shader][]s.
15 
+-   [`glframebuffer`][], easing the use of [framebuffer object][]s.
16 
+-   [`glconventions`][], documenting the conventions used.
17 
+
5 18 
 [`glquad`]: https://git.rcrnstn.net/rcrnstn/glquad
6 19 
 [GLSL]: https://en.wikipedia.org/wiki/OpenGL_Shading_Language
7 20 
 [OpenGL]: https://en.wikipedia.org/wiki/OpenGL
8 21 
 [\>=3.2]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 22 
 [quad]: https://en.wikipedia.org/wiki/Quadrilateral
23 
+[generation]: #generation
24 
+[vertex shader]: https://www.khronos.org/opengl/wiki/Vertex_Shader
25 
+[geometry shader]: https://www.khronos.org/opengl/wiki/Geometry_Shader
26 
+[fragment shader]: https://www.khronos.org/opengl/wiki/Fragment_Shader
27 
+[drawing]: #drawing
28 
+[`glshader`]: https://git.rcrnstn.net/rcrnstn/glshader
29 
+[shader]: https://www.khronos.org/opengl/wiki/Shader
30 
+[`glframebuffer`]: https://git.rcrnstn.net/rcrnstn/glframebuffer
31 
+[framebuffer object]: https://www.khronos.org/opengl/wiki/Framebuffer_Object
32 
+[`glconventions`]: https://git.rcrnstn.net/rcrnstn/glconventions
33 
+
34 
+## Requirements
35 
+
36 
+[Geometry shader][]s require OpenGL [\>=3.2][] or the
37 
+[`ARB_geometry_shader4`][] extension.
38 
+
39 
+[`ARB_geometry_shader4`]: https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_geometry_shader4.txt
40 
+
41 
+## Usage
42 
+
43 
+Link the shader program with:
44 
+
45 
+-   `quad.vert`
46 
+-   `quad.geom`
47 
+
48 
+The following uniforms need to be set:
49 
+
50 
+-   `int instance_count`
51 
+
52 
+The following outputs are written by the [geometry shader][]:
53 
+
54 
+-   `vec3 position`, in the range `-1` to `+1`
55 
+-   `vec2 tex_coord`, in the range `0` to `1`
56 
+
57 
+When issuing the draw call, use the following for 2D:
58 
+
59 
+```
60 
+glDrawArrays(GL_POINTS, 0, 1);
61 
+```
62 
+
63 
+and the following for 3D:
64 
+
65 
+```
66 
+glDrawArraysInstanced(GL_POINTS, 0, 1 instance_count);
67 
+```
68 
+
69 
+Here, `instance_count` is the number of [layer][]s in the [framebuffer][]; `1`
70 
+for 2D, texture depth for 3D.
71 
+
72 
+[layer]: https://www.khronos.org/opengl/wiki/Geometry_Shader#Layered_rendering
73 
+[framebuffer]: https://www.khronos.org/opengl/wiki/Framebuffer
74 
+
75 
+### Generation
76 
+
77 
+Vertices are generated entirely within a [geometry shader][], so no vertex
78 
+state (except for the obligatory [vertex array object][] for OpenGL [\>=3.3][])
79 
+has to be set up on the CPU (no data is even read by the [vertex shader][]),
80 
+potentially making operation transparent to other code, which can leave their
81 
+state bound.
82 
+
83 
+[Instanced rendering][], with each instance rendering to a separate [layer][],
84 
+is used since it enables a large, dynamic, number of layers. [Geometry shader
85 
+instancing][] is more self-contained and requires less work by the CPU (simply
86 
+`glDrawArrays`), but is limited to a fixed, small, number of layers, and
87 
+requires OpenGL [\>=4.0][] or the [`ARB_gpu_shader5`][] extension.
88 
+
89 
+[vertex array object]: https://www.khronos.org/opengl/wiki/Vertex_Specification#Vertex_Array_Object
90 
+[\>=3.3]: https://en.wikipedia.org/wiki/OpenGL#Version_history
91 
+[instanced rendering]: https://www.khronos.org/opengl/wiki/Vertex_Rendering#Instancing
92 
+[geometry shader instancing]: https://www.khronos.org/opengl/wiki/Geometry_Shader#Instancing
93 
+[\>=4.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history
94 
+[`ARB_gpu_shader5`]: https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_gpu_shader5.txt
95 
+
96 
+### Drawing
97 
+
98 
+The following outputs are written by these fragment shaders:
99 
+
100 
+-   ` vec4 frag_color`
101 
+
102 
+#### 2D
103 
+
104 
+Link the shader program with:
105 
+
106 
+-   `quad2d.frag`
107 
+
108 
+The following uniforms need to be set:
109 
+
110 
+-   `sampler2D texture0`
111 
+
112 
+#### 3D
113 
+
114 
+Link the shader program with:
115 
+
116 
+-   `quad3d.frag`
117 
+
118 
+The following uniforms need to be set:
119 
+
120 
+-   `sampler3D texture0`
121 
+-   `float tex_coord_z`, `z` coordinate with which to sample `texture0`
10 122
11 123 
 ## Build system
12 124
Browse code

Add project

Robert Cranston authored on 17/12/2021 12:48:41
Showing 1 changed files
README.md
History View file @ 84b9b61
... ... 
@@ -8,6 +8,94 @@ A [GLSL][]/[OpenGL][] [\>=3.2][] [quad][] library.
8 8 
 [\>=3.2]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 9 
 [quad]: https://en.wikipedia.org/wiki/Quadrilateral
10 10
11 
+## Build system
12 
+
13 
+This project has support for [CMake][], and uses [`cmake-cxx`][].
14 
+
15 
+There are several ways to use this project in another CMake-based project:
16 
+
17 
+-   Use [`FetchContent`][] to download it and import the targets automatically
18 
+    as part of the configure step:
19 
+
20 
+    ```cmake
21 
+    include(FetchContent)
22 
+    FetchContent_Declare(project-name
23 
+        GIT_REPOSITORY https://example.com/user/project-name
24 
+    )
25 
+    FetchContent_MakeAvailable(
26 
+        project-name
27 
+    )
28 
+    ```
29 
+
30 
+-   Bundle it and import the targets with [`add_subdirectory`][].
31 
+
32 
+-   Use [`find_package`][] (requires that the project is [packaged](#packaging)
33 
+    or [installed](#installing)).
34 
+
35 
+As usual, use [`add_dependencies`][]/[`target_link_libraries`][] to declare the
36 
+dependency.
37 
+
38 
+[CMake]: https://cmake.org
39 
+[`cmake-cxx`]: https://git.rcrnstn.net/rcrnstn/cmake-cxx
40 
+[`FetchContent`]: https://cmake.org/cmake/help/v3.14/module/FetchContent.html
41 
+[`add_subdirectory`]: https://cmake.org/cmake/help/v3.14/command/add_subdirectory.html
42 
+[`find_package`]: https://cmake.org/cmake/help/v3.14/command/find_package.html
43 
+[`add_dependencies`]: https://cmake.org/cmake/help/v3.14/command/add_dependencies.html
44 
+[`target_link_libraries`]: https://cmake.org/cmake/help/v3.14/command/target_link_libraries.html
45 
+
46 
+### Configure and generate
47 
+
48 
+To configure and generate a build tree, use `cmake`:
49 
+
50 
+```sh
51 
+cmake -B build
52 
+```
53 
+
54 
+To set the [`CMAKE_BUILD_TYPE`][], pass e.g. `-DCMAKE_BUILD_TYPE=Release`.
55 
+
56 
+[`cmake`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#generate-a-project-buildsystem
57 
+[`CMAKE_BUILD_TYPE`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_BUILD_TYPE.html
58 
+
59 
+### Build
60 
+
61 
+To build, use [`cmake --build`][]:
62 
+
63 
+```sh
64 
+cmake --build build
65 
+```
66 
+
67 
+[`cmake --build`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#build-a-project
68 
+
69 
+### Test
70 
+
71 
+To run tests, use [`ctest`][]:
72 
+
73 
+```sh
74 
+(cd build && ctest --output-on-failure)
75 
+```
76 
+
77 
+[`ctest`]: https://cmake.org/cmake/help/v3.14/manual/ctest.1.html
78 
+
79 
+### Package
80 
+
81 
+To package, use [`cpack`][]:
82 
+
83 
+```sh
84 
+(cd build && cpack)
85 
+```
86 
+
87 
+[`cpack`]: https://cmake.org/cmake/help/v3.14/manual/cpack.1.html
88 
+
89 
+### Install
90 
+
91 
+To install onto the current system, use [`cmake --install`][]:
92 
+
93 
+```sh
94 
+cmake --install build
95 
+```
96 
+
97 
+[`cmake --install`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#install-a-project
98 
+
11 99 
 ## License
12 100
13 101 
 Licensed under the [ISC License][] unless otherwise noted, see the
Browse code

Add license

Robert Cranston authored on 17/12/2021 09:41:53
Showing 1 changed files
README.md
History View file @ 0a584fd
... ... 
@@ -7,3 +7,10 @@ A [GLSL][]/[OpenGL][] [\>=3.2][] [quad][] library.
7 7 
 [OpenGL]: https://en.wikipedia.org/wiki/OpenGL
8 8 
 [\>=3.2]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 9 
 [quad]: https://en.wikipedia.org/wiki/Quadrilateral
10 
+
11 
+## License
12 
+
13 
+Licensed under the [ISC License][] unless otherwise noted, see the
14 
+[`LICENSE`](LICENSE) file.
15 
+
16 
+[ISC License]: https://choosealicense.com/licenses/isc/
Browse code

Add readme

Robert Cranston authored on 17/12/2021 09:04:47
Showing 1 changed files
README.md
History View file @ eb6b9ab
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,9 @@
1 
+# [`glquad`][]
2 
+
3 
+A [GLSL][]/[OpenGL][] [\>=3.2][] [quad][] library.
4 
+
5 
+[`glquad`]: https://git.rcrnstn.net/rcrnstn/glquad
6 
+[GLSL]: https://en.wikipedia.org/wiki/OpenGL_Shading_Language
7 
+[OpenGL]: https://en.wikipedia.org/wiki/OpenGL
8 
+[\>=3.2]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 
+[quad]: https://en.wikipedia.org/wiki/Quadrilateral