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

Add implementation

Robert Cranston authored on 15/03/2021 19:32:43
Showing 1 changed files
README.md
History View file @ c5349b9
... ... 
@@ -6,7 +6,110 @@ A [C++11][]/[OpenGL][] \>=[1.0][] [testing][] library.
6 6 
 [C++11]: https://en.wikipedia.org/wiki/C++11
7 7 
 [OpenGL]: https://en.wikipedia.org/wiki/OpenGL
8 8 
 [1.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 
-[testing]: https://en.wikipedia.org/wiki/Software_testing
9 
+
10 
+## Usage
11 
+
12 
+```cpp
13 
+#include <cerrno>
14 
+#include <cstring>
15 
+#include <fstream>
16 
+#include <stdexcept>
17 
+#include <string>
18 
+
19 
+#include <GL/glew.h>
20 
+
21 
+#include <glbackend.hpp>
22 
+#include <gltest.hpp>
23 
+
24 
+
25 
+// Function that throws with a system-supplied message.
26 
+void file_open(std::string const & filename)
27 
+{
28 
+    auto file = std::ifstream{"nonexistent"};
29 
+    if (!file)
30 
+        throw std::runtime_error(std::string{} +
31 
+            "Could not open file '" + filename + "':\n" +
32 
+            std::strerror(errno) + "." // NOLINT
33 
+        );
34 
+}
35 
+
36 
+
37 
+GLTEST(gltest, 640, 480, 2, 0)
38 
+{
39 
+    backend.prefix("assets/tests");
40 
+
41 
+    GLTEST_EXPECT_VALUE(
42 
+        GL_FALSE,
43 
+        glIsEnabled(GL_DEPTH_TEST)
44 
+    )
45 
+    GLTEST_EXPECT_EXCEPTION(false,
46 
+        "Expected exception",
47 
+        throw std::runtime_error("Expected exception")
48 
+    )
49 
+    GLTEST_EXPECT_EXCEPTION(true,
50 
+        "Could not open file 'nonexistent':\n",
51 
+        // "No such file or directory"
52 
+        file_open("nonexistent")
53 
+    )
54 
+
55 
+    constexpr auto size = 0.5;
56 
+    glBegin(GL_TRIANGLE_STRIP);
57 
+    glVertex3f(-size, -size, 0);
58 
+    glVertex3f(-size, +size, 0);
59 
+    glVertex3f(+size, -size, 0);
60 
+    glVertex3f(+size, +size, 0);
61 
+    glEnd();
62 
+    backend.tga_compare("GLTest.tga");
63 
+}
64 
+```
65 
+
66 
+A `main()` entry point is provided which calls each test declared with the
67 
+macro `GLTEST(VERSION_MAJOR, VERSION_MINOR, WIDTH, HEIGHT, NAME)`. A double
68 
+buffered OpenGL debug context compatible with the specified version and with a
69 
+window of the specified width and height is set up prior to each test run and
70 
+teared down afterwards.
71 
+
72 
+If OpenGL \>=4.3 or the extension [`KHR_debug`][] is available,
73 
+non-notification debug messages throw errors unless disabled by calling `bool
74 
+gltest_debug(false)` (which returns the old value). The root directory for
75 
+reading and writing files is set with `void gltest_root(std::string)`. Timing
76 
+can be manipulated with `void gltest_set_time(float)` and `float
77 
+gltest_get_time()`. Swapping buffers is performed with `void
78 
+gltest_swap_buffers()`.
79 
+
80 
+The macro `GLTEST_EXPECT_VALUE(EXPR, VALUE)` runs `EXPR`, compares the result
81 
+to `VALUE` and throws an error if they do not match.
82 
+
83 
+The macro `GLTEST_EXPECT_EXCEPTION(PREFIX, EXPR, WHAT)` catches any
84 
+[`std::exception`][]-derived exception thrown by `EXPR`, compares its
85 
+[`what()`][] to `WHAT` and throws an error if they do not match. If `PREFIX` is
86 
+true it is only required that `WHAT` is a prefix of `what()`, to allow trailing
87 
+external messages of unknown format. An error is also thrown if `EXPR` throws
88 
+no exception at all. `gltest_debug(false)` is automatically called before
89 
+`EXPR` is run, the previous value is restored afterwards.
90 
+
91 
+The macro `GLTEST_EXPECT_FRAME(PATH)` reads `PATH` from disk, compares it to
92 
+the current (back) framebuffer and throws an error if they do not match. If
93 
+`PATH` does not exist, the current framebuffer is instead written to it and a
94 
+warning is printed.
95 
+
96 
+If a `GLTEST_EXPECT_*` fails, the values of `GL_VENDOR`, `GL_RENDERER`,
97 
+`GL_VERSION` and `GL_SHADING_LANGUAGE_VERSION` is printed to standard error. In
98 
+addition, `GLTEST_EXPECT_VALUE` or `GLTEST_EXPECT_EXCEPTION` print something in
99 
+the style of:
100 
+
101 
+```
102 
+>>> Expression:
103 
+glIsEnabled(GL_DEPTH_TEST)
104 
+>>> Expected value:
105 
+GL_TRUE = 1
106 
+>>> Got:
107 
+0
108 
+```
109 
+
110 
+[`std::exception`]: https://en.cppreference.com/w/cpp/error/exception
111 
+[`what()`]: https://en.cppreference.com/w/cpp/error/exception/what
112 
+[`KHR_debug`]: https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_debug.txt
10 113
11 114 
 ## Build system
12 115
Browse code

Add project

Robert Cranston authored on 15/03/2021 19:32:33
Showing 1 changed files
README.md
History View file @ 39cafb9
... ... 
@@ -8,6 +8,95 @@ A [C++11][]/[OpenGL][] \>=[1.0][] [testing][] library.
8 8 
 [1.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 9 
 [testing]: https://en.wikipedia.org/wiki/Software_testing
10 10
11 
+## Build system
12 
+
13 
+This project supports [CMake][] and uses [`cmake-common`][]. There are several
14 
+ways to use it in other CMake-based projects:
15 
+
16 
+-   With [`find_package`][]: ([Package][] and) [install][] it on the system.
17 
+
18 
+-   With [`add_subdirectory`][]: Bundle it.
19 
+
20 
+-   With [`FetchContent`][]: Download it as part of the CMake configure step.
21 
+
22 
+-   With [`cmake-common`][]: Use any of the above methods through a simplified
23 
+    interface.
24 
+
25 
+As usual, use [`add_dependencies`][] or [`target_link_libraries`][] (or
26 
+`cmake-common`'s `DEPENDENCIES_*`) to declare the dependency.
27 
+
28 
+[CMake]: https://cmake.org
29 
+[`cmake-common`]: https://git.rcrnstn.net/rcrnstn/cmake-common
30 
+[`FetchContent`]: https://cmake.org/cmake/help/v3.14/module/FetchContent.html
31 
+[`add_subdirectory`]: https://cmake.org/cmake/help/v3.14/command/add_subdirectory.html
32 
+[`find_package`]: https://cmake.org/cmake/help/v3.14/command/find_package.html
33 
+[Package]: #Package
34 
+[Install]: #Install
35 
+[`add_dependencies`]: https://cmake.org/cmake/help/v3.14/command/add_dependencies.html
36 
+[`target_link_libraries`]: https://cmake.org/cmake/help/v3.14/command/target_link_libraries.html
37 
+
38 
+### Configure and generate
39 
+
40 
+To configure and generate a build tree, use `cmake`:
41 
+
42 
+```sh
43 
+cmake -B _build
44 
+```
45 
+
46 
+To set the build type, pass e.g. `-D`[`CMAKE_BUILD_TYPE`][]`=Release`.
47 
+
48 
+[`cmake`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#generate-a-project-buildsystem
49 
+[`CMAKE_BUILD_TYPE`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_BUILD_TYPE.html
50 
+
51 
+### Build
52 
+
53 
+To build, use [`cmake --build`][]:
54 
+
55 
+```sh
56 
+cmake --build _build
57 
+```
58 
+
59 
+To disable building tests, pass `-D`[`BUILD_TESTING`][]`=OFF`.
60 
+
61 
+[`cmake --build`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#build-a-project
62 
+[`BUILD_TESTING`]: https://cmake.org/cmake/help/v3.14/module/CTest.html
63 
+
64 
+### Test
65 
+
66 
+To run tests, use [`ctest`][]:
67 
+
68 
+```sh
69 
+(cd _build && ctest)
70 
+```
71 
+
72 
+To show output from failing tests, pass `--output-on-failure`. To show output
73 
+from all tests, pass `--verbose`.
74 
+
75 
+[`ctest`]: https://cmake.org/cmake/help/v3.14/manual/ctest.1.html
76 
+
77 
+### Package
78 
+
79 
+To package, use [`cpack`][]:
80 
+
81 
+```sh
82 
+(cd _build && cpack)
83 
+```
84 
+
85 
+[`cpack`]: https://cmake.org/cmake/help/v3.14/manual/cpack.1.html
86 
+
87 
+### Install
88 
+
89 
+To install onto the current system, use [`cmake --install`][]:
90 
+
91 
+```sh
92 
+cmake --install _build
93 
+```
94 
+
95 
+To set the prefix, pass e.g. `-D`[`CMAKE_INSTALL_PREFIX`][]`="$HOME/.local"`.
96 
+
97 
+[`cmake --install`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#install-a-project
98 
+[`CMAKE_INSTALL_PREFIX`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_INSTALL_PREFIX.html
99 
+
11 100 
 ## License
12 101
13 102 
 Licensed under the [ISC License][] unless otherwise noted, see the
Browse code

Add license

Robert Cranston authored on 15/03/2021 19:07:38
Showing 1 changed files
README.md
History View file @ 0aad30d
... ... 
@@ -7,3 +7,11 @@ A [C++11][]/[OpenGL][] \>=[1.0][] [testing][] library.
7 7 
 [OpenGL]: https://en.wikipedia.org/wiki/OpenGL
8 8 
 [1.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 9 
 [testing]: https://en.wikipedia.org/wiki/Software_testing
10 
+
11 
+## License
12 
+
13 
+Licensed under the [ISC License][] unless otherwise noted, see the
14 
+[`LICENSE`][] file.
15 
+
16 
+[ISC License]: https://choosealicense.com/licenses/isc
17 
+[`LICENSE`]: LICENSE
Browse code

Add readme

Robert Cranston authored on 15/03/2021 19:07:05
Showing 1 changed files
README.md
History View file @ f5a69c2
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,9 @@
1 
+# [`gltest`][]
2 
+
3 
+A [C++11][]/[OpenGL][] \>=[1.0][] [testing][] library.
4 
+
5 
+[`gltest`]: https://git.rcrnstn.net/rcrnstn/gltest
6 
+[C++11]: https://en.wikipedia.org/wiki/C++11
7 
+[OpenGL]: https://en.wikipedia.org/wiki/OpenGL
8 
+[1.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history
9 
+[testing]: https://en.wikipedia.org/wiki/Software_testing