Robert Cranston authored on 10/01/2022 00:25:45
| ... | ... |
@@ -2,11 +2,85 @@ |
| 2 | 2 |
|
| 3 | 3 |
A [C++11][]/[OpenGL][]>=[1.0][] [object][] library. |
| 4 | 4 |
|
| 5 |
+This library provides a class that is intended to be the base class of several |
|
| 6 |
+other classes that encapsulate different types of OpenGL objects, making it |
|
| 7 |
+easy to avoid [common mistakes][]. |
|
| 8 |
+ |
|
| 5 | 9 |
[`globject`]: https://git.rcrnstn.net/rcrnstn/globject |
| 6 | 10 |
[C++11]: https://en.wikipedia.org/wiki/C++11 |
| 7 | 11 |
[OpenGL]: https://en.wikipedia.org/wiki/OpenGL |
| 8 | 12 |
[1.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history |
| 9 | 13 |
[object]: https://www.khronos.org/opengl/wiki/OpenGL_Object |
| 14 |
+[common mistakes]: https://www.khronos.org/opengl/wiki/Common_Mistakes#The_Object_Oriented_Language_Problem |
|
| 15 |
+ |
|
| 16 |
+## Usage |
|
| 17 |
+ |
|
| 18 |
+### Template arguments |
|
| 19 |
+ |
|
| 20 |
+`GLObject` is template specialized the following values. |
|
| 21 |
+ |
|
| 22 |
+- `GL_TEXTURE` |
|
| 23 |
+- `GL_BUFFER` |
|
| 24 |
+- `GL_QUERY` |
|
| 25 |
+- `GL_PROGRAM` |
|
| 26 |
+- `GL_SHADER` |
|
| 27 |
+- `GL_VERTEX_ARRAY` |
|
| 28 |
+- `GL_FRAMEBUFFER` |
|
| 29 |
+- `GL_RENDERBUFFER` |
|
| 30 |
+- `GL_SAMPLER` |
|
| 31 |
+- `GL_TRANSFORM_FEEDBACK` |
|
| 32 |
+- `GL_PROGRAM_PIPELINE` |
|
| 33 |
+ |
|
| 34 |
+The class handles the lifetime of an OpenGL object of the corresponding type. |
|
| 35 |
+ |
|
| 36 |
+### Special member functions |
|
| 37 |
+ |
|
| 38 |
+All [special member functions][] are `protected`. It is impossible to directly |
|
| 39 |
+instantiate `GLObject`s, or to delete objects through `GLObject` pointers. |
|
| 40 |
+Instead, use a derived class that encapsulates a specific type of OpenGL |
|
| 41 |
+object. |
|
| 42 |
+ |
|
| 43 |
+There are no (non-[`delete`][]d) default constructor, copy constructor, or copy |
|
| 44 |
+assignment operators. This enforces the invariant that a successfully |
|
| 45 |
+constructed instance (that has not been moved from) always (is the only |
|
| 46 |
+instance that) corresponds to a valid OpenGL object. |
|
| 47 |
+ |
|
| 48 |
+The move constructor/assignment operator's [`noexcept`][] specifiers are only |
|
| 49 |
+guaranteed to be honored if [`debug()`][] is `0`. |
|
| 50 |
+ |
|
| 51 |
+The constructor takes as arguments: |
|
| 52 |
+ |
|
| 53 |
+- `std::string const & label`. Used when printing debug messages, throwing |
|
| 54 |
+ exceptions, and, if OpenGL>=[4.3][] or the [`KHR_debug`][] extension is |
|
| 55 |
+ available, passed to [`glObjectLabel`][]. |
|
| 56 |
+ |
|
| 57 |
+[special member functions]: https://en.wikipedia.org/wiki/Special_member_functions |
|
| 58 |
+[`delete`]: https://en.cppreference.com/w/cpp/language/function#Deleted_functions |
|
| 59 |
+[`noexcept`]: https://en.cppreference.com/w/cpp/language/noexcept_spec |
|
| 60 |
+[`debug()`]: https://git.rcrnstn.net/rcrnstn/glbase/#debug |
|
| 61 |
+[4.3]: https://en.wikipedia.org/wiki/OpenGL#Version_history |
|
| 62 |
+[`KHR_debug`]: https://registry.khronos.org/OpenGL/extensions/KHR/KHR_debug.txt |
|
| 63 |
+[`glObjectLabel`]: https://registry.khronos.org/OpenGL-Refpages/gl4/html/glObjectLabel.xhtml |
|
| 64 |
+ |
|
| 65 |
+### Object |
|
| 66 |
+ |
|
| 67 |
+`GLuint object() const` returns the underlying OpenGL object. This is |
|
| 68 |
+guaranteed to be valid, unless the constructor threw an exception or the |
|
| 69 |
+`GLObject` has been moved from, in which case it is `0`. |
|
| 70 |
+ |
|
| 71 |
+### Name |
|
| 72 |
+ |
|
| 73 |
+`std::string name() const` returns a string representation of the object. |
|
| 74 |
+ |
|
| 75 |
+### Debug |
|
| 76 |
+ |
|
| 77 |
+`void debug_action_(std::string const & action)` calls outputs a debug message |
|
| 78 |
+containing `action` and `name()`. |
|
| 79 |
+ |
|
| 80 |
+### Fail |
|
| 81 |
+ |
|
| 82 |
+`void fail_action_(std::string const & action) const` throws an exception with |
|
| 83 |
+a message containing `action` and `name()`. |
|
| 10 | 84 |
|
| 11 | 85 |
## Building |
| 12 | 86 |
|
Robert Cranston authored on 09/01/2022 03:34:28
| ... | ... |
@@ -8,6 +8,12 @@ A [C++11][]/[OpenGL][]>=[1.0][] [object][] library. |
| 8 | 8 |
[1.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history |
| 9 | 9 |
[object]: https://www.khronos.org/opengl/wiki/OpenGL_Object |
| 10 | 10 |
|
| 11 |
+## Building |
|
| 12 |
+ |
|
| 13 |
+See [`BUILDING.md`][]. |
|
| 14 |
+ |
|
| 15 |
+[`BUILDING.md`]: BUILDING.md |
|
| 16 |
+ |
|
| 11 | 17 |
## License |
| 12 | 18 |
|
| 13 | 19 |
Licensed under the [ISC License][] unless otherwise noted, see the |
Robert Cranston authored on 09/01/2022 03:32:53
| ... | ... |
@@ -7,3 +7,11 @@ A [C++11][]/[OpenGL][]>=[1.0][] [object][] library. |
| 7 | 7 |
[OpenGL]: https://en.wikipedia.org/wiki/OpenGL |
| 8 | 8 |
[1.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history |
| 9 | 9 |
[object]: https://www.khronos.org/opengl/wiki/OpenGL_Object |
| 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 |
Robert Cranston authored on 09/01/2022 03:32:16
| 1 | 1 |
new file mode 100644 |
| ... | ... |
@@ -0,0 +1,9 @@ |
| 1 |
+# [`globject`][] |
|
| 2 |
+ |
|
| 3 |
+A [C++11][]/[OpenGL][]>=[1.0][] [object][] library. |
|
| 4 |
+ |
|
| 5 |
+[`globject`]: https://git.rcrnstn.net/rcrnstn/globject |
|
| 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 |
+[object]: https://www.khronos.org/opengl/wiki/OpenGL_Object |
git.rcrnstn.net