# [`gltraits`][]
A [C++11][](/[C++14][])/[OpenGL][]>=[1.0][](/[GLM][]) [trait][]s library.
This library seeks to unify some parts of the OpenGL [API][] to ease [generic
programming][]. It also provides sensible default arguments, [optional][debug]
[check][]s for [version][]/[extension][] support, and optional support for
[OpenGL Mathematics (GLM)][GLM] (which provides [GLSL][]-like types).
A more philosophical description: it aims to make the implicit symmetries of
the OpenGL API explicit. In the process, some wrinkles in the symmetry are also
brought to light. Therefore, it may be useful for learning and understanding
the OpenGL API (although this use case may be limited due to the (ab)use of C++
language features).
This header-only library makes heavy use of macros. For easy inspection of the
results, a script that runs the preprocessor is available in
[`doc/preprocess`][] and its output in [`doc/preprocess.hpp`][].
A typical use case is demonstrated by this quote from [OGLDEV on YouTube][]:
> Notice, in order to make this an unsigned integer texture we use `GL_RGB32UI`
> as the `internal_format`, `GL_RGB_INTEGER` as the `format`, and
> `GL_UNSIGNED_INT` as the data `type`. Combining all these formats and types
> correctly in OpenGL can often be a pain, and I literally pulled the last few
> pieces of hair from my head trying to get this to work.
These constants are provided in `GLTraits::Value<glm::uvec3>`. Of course, this
becomes even more valuable when `glm::uvec3` is replaced by some unknown
template parameter.
The function call seen in the video
```cpp
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB32UI, WindowWidth, WindowHeight, 0, GL_RGB_INTEGER, GL_UNSIGNED_INT, NULL);
```
can be replaced with
```cpp
GLTraits::Texture<2>::tex_image<glm::uvec3>(GL_TEXTURE_2D, {WindowWidth, WindowHeight});
```
It is recommended to use a library based on `gltraits` that abstracts this
further.
[`gltraits`]: https://git.rcrnstn.net/rcrnstn/gltraits
[C++11]: https://en.wikipedia.org/wiki/C++11
[C++14]: https://en.wikipedia.org/wiki/C++14
[OpenGL]: https://en.wikipedia.org/wiki/OpenGL
[1.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history
[GLM]: https://glm.g-truc.net
[trait]: https://en.wikipedia.org/wiki/Trait_(computer_programming)
[API]: https://en.wikipedia.org/wiki/API
[generic programming]: https://en.wikipedia.org/wiki/Generic_programming
[debug]: https://git.rcrnstn.net/rcrnstn/glbase#debug
[check]: https://git.rcrnstn.net/rcrnstn/glbase#check
[version]: https://en.wikipedia.org/wiki/OpenGL#Version_history
[extension]: https://www.khronos.org/opengl/wiki/OpenGL_Extension
[GLSL]: https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language
[`doc/preprocess`]: doc/preprocess
[`doc/preprocess.hpp`]: doc/preprocess.hpp
[OGLDEV on YouTube]: https://www.youtube.com/watch?v=71G-PVpaVk8&t=5m17s
## Usage
### Value
The [empty][] `struct GLTraits::Value<typename Value>` is template specialized
on the following types.
- `GLfloat`
- `bool`
- `GL{,u}byte`
- `GL{,u}short`
- `GL{,u}int`
- `GLdouble`
[GLM][] support is enabled if `glm/glm.hpp` is included (specifically, if
`GLM_VERSION` is defined) before inclusion of `gltraits.hpp`. In that case
`GLTraits::Value` is additionally template specialized on the following types.
- `glm::{,i,u,d}vec{2,3,4}`
- `glm::{,d}mat{2{,x3,x4},3{x2,,x4},4{x2,x3,}}`
`GLTraits::Value` contains the following `static constexpr` member variables.
- `char const name[]`
- `GLint columns`
- `GLint rows`
- `GLenum glsl`
- `GLenum format`
- `GLenum type`
- `GLenum internal_format`
- `GLenum internal_format_srgb`
- `GLenum internal_format_compressed`
- `GLenum internal_format_compressed_srgb`
- `bool integer`
- `GLenum id`
`id` is guaranteed to be unique to this `Value` and is equal to `glsl` for all
`Value`s except `GL{,u}{byte,short}`, for which it is equal to `type`.
`GLTraits::Value` contains the following `static` member functions.
- ```cpp
void uniform(GLint location, Value const & value)
```
Generalization of `glUniform*`.
Uploads `value` to the [uniform][] indicated by `location` of the current
[shader][] program.
- ```cpp
void vertex_attrib(GLint location, Value const & value)
```
Generalization of `glVertexAttrib*`.
Uploads `value` to the [non-array attribute][] indicated by `location`.
Note that [`glDisableVertexAttribArray`][] is not called (for performance).
- ```cpp
void vertex_attrib_pointer(
GLint location,
std::size_t offset = 0,
std::size_t stride = sizeof(Value)
)
```
Generalization of `glVertexAttrib*Pointer`.
Sets the [format][] as well as the [offset and stride][] of the [array
attribute][] indicated by `location`. Note that
[`glEnableVertexAttribArray`][] is not called (for performance).
If `location` is `-1`, the above calls will do nothing. No error will be
generated in this case.
Note that matrix types (e.g. from [GLM][], if enabled), occupy several
consecutive attribute locations (one per column), which are all handled
automatically by `vertex_attrib{,_pointer}(...)` above.
`GLTRAITS_VALUE*` macros are defined to ease the definition of new template
specializations of `GLTraits::Value`. Consult the source for the definitions
and usage examples.
The [empty][] `struct GLTraits::ValueID<GLenum id>` is template specialized on
the different values of `GLTraits::Value<Value>::id`.
`GLTraits::ValueID` contains the following type definitions.
- `Value`. An alias for the template type parameter for which
`GLTraits::Value<Value>::id == id` holds.
`GLTraits::ValueID` provides a compile time mapping from `GLenum id` back to
the type `Value`. E.g. `GLTraits::ValueID<GL_FLOAT>::Value` is an alias for
`GLfloat`. This works for all supported types, including those provided by
[GLM][] if enabled, e.g. `GLTraits::ValueID<GL_FLOAT_VEC3>::Value` would be an
alias for `glm::vec3`.
[empty]: https://en.cppreference.com/w/cpp/types/is_empty
[uniform]: https://www.khronos.org/opengl/wiki/Uniform_(GLSL)
[shader]: https://www.khronos.org/opengl/wiki/Shader
[non-array attribute]: https://www.khronos.org/opengl/wiki/Vertex_Specification#Non-array_attribute_values
[format]: https://www.khronos.org/opengl/wiki/Vertex_Specification#Vertex_format
[offset and stride]: https://www.khronos.org/opengl/wiki/Vertex_Specification#Vertex_buffer_offset_and_stride
[array attribute]: https://www.khronos.org/opengl/wiki/Vertex_Specification#Vertex_Buffer_Object
[`glDisableVertexAttribArray`]: https://registry.khronos.org/OpenGL-Refpages/gl4/html/glEnableVertexAttribArray.xhtml
[`glEnableVertexAttribArray`]: https://registry.khronos.org/OpenGL-Refpages/gl4/html/glEnableVertexAttribArray.xhtml
### Object
The [empty][] `struct GLTraits::Object<GLenum object_type>` is template
specialized on the following values.
- `GL_TEXTURE`
- `GL_BUFFER`
- `GL_QUERY`
- `GL_PROGRAM`
- `GL_SHADER`
- `GL_VERTEX_ARRAY`
- `GL_FRAMEBUFFER`
- `GL_RENDERBUFFER`
- `GL_SAMPLER`
- `GL_TRANSFORM_FEEDBACK`
- `GL_PROGRAM_PIPELINE`
`GLTraits::Object` contains the following `static constexpr` member variables.
- `char const name[]`
`GLTraits::Object` contains the following `static` member functions.
- ```cpp
template<typename... Args>
void gen_objects(GLsizei n, GLuint * objects, Args... args)
```
Generalization of `glGen*s` and `glCreate`.
- ```cpp
void delete_objects(GLsizei n, GLuint * objects)
```
Generalization of `glDelete*s` and `glDelete*`.
For `object_types` equal to `GL_SHADER`, `GL_PROGRAM`, and
`GL_PROGRAM_PIPELINE`, `GLTraits::Object` additionally contains the following
`static` member functions.
- ```cpp
std::string info_log(GLuint object)
```
Generalization of `glGet*InfoLog`.
`GLTRAITS_OBJECT*` macros are defined to ease the definition of new template
specializations of `GLTraits::Object`. Consult the source for the definitions
and usage examples.
### Texture
The [empty][] `struct GLTraits::Texture<std::size_t N>` is template specialized
on the following values.
- `1`. 1D textures.
- `2`. 2D textures.
- `3`. 3D textures.
`GLTraits::Texture` contains the following type definitions.
- `Size`. An alias for `std::array<GLsizei, N>`.
- `Offset`. An alias for `std::array<GLsizei, N>`.
- `CopySize`. An alias for `std::array<GLsizei, min(N, 2)>`.
- `CopyOffset`. An alias for `std::array<GLsizei, 2>`.
`GLTraits::Texture` contains the following `static constexpr` member variables.
- `default_target`. This is the default target, but many other targets can be
used with the member functions described below. E.g. for `N = 2`
`default_target` is `GL_TEXTURE_2D`, but valid `target` function arguments
are `GL_{,PROXY}_TEXTURE_{2D,RECTANGLE,1D_ARRAY}`,
`GL_TEXTURE_CUBE_MAP_{POSITIVE,NEGATIVE}_{X,Y,Z}`, and
`GL_PROXY_TEXTURE_CUBE_MAP`.
- `default_binding`. Likewise, this is the default binding.
`GLTraits::Texture` contains the following `static` member functions.
- ```cpp
template<typename Value = GLubyte>
void tex_image(
GLenum target,
Size size,
GLenum internal_format = 0,
Value const * data = nullptr,
GLenum format = 0,
GLenum type = 0,
GLint level = 0,
GLint border = 0
)
```
Generalization of `glTexImage{1,2,3}D`.
OpenGL requires that `format` matches the kind of [image format][]
specified by `internal_format` (even if `data` is `nullptr`!). Moreover, if
`internal_format` specifies an unsized image format, `type` may be used by
the implementation when choosing a size (perhaps even if that size is
slow!). Therefore, if `format` and/or `type` is `0` (the default) sensible
values will be chosen based on the given (or automatically chosen, see
below) `internal_format` (note that there is no requirement that the number
of color components of `internal_format` and `format` match):
- [Color formats][]: `GLTraits::Value<Value>` member variables.
- [Depth/stencil formats][]: `GL_DEPTH_STENCIL`, `GL_UNSIGNED_INT_24_8`.
- [Depth formats][]: `GL_DEPTH_COMPONENT`, `GL_UNSIGNED_INT`.
- [Stencil formats][]: `GL_STENCIL_INDEX`, `GL_UNSIGNED_BYTE`.
- ```cpp
template<typename Value = GLubyte>
void {tex,texture}_storage(
{GLenum,GLuint} {target,texture},
Size size,
GLenum internal_format = 0,
GLsizei levels = 1
)
```
Generalizations of `gl{Tex,Texture}Storage{1,2,3}D`, which both use
[immutable storage][], where the latter uses [Direct State Access][].
- ```cpp
template<typename Value = GLubyte>
void {tex,texture}_sub_image(
{GLenum,GLuint} {target,texture},
Size size,
Value const * data,
GLenum format = 0,
GLenum type = 0,
Offset offset = {},
GLint level = 0
)
```
Generalizations of `gl{Tex,Texture}SubImage{1,2,3}D`, where the latter uses
[Direct State Access][].
- ```cpp
void copy_{tex,texture}_sub_image(
{GLenum,GLuint} {target,texture},
CopySize copy_size,
CopyOffset copy_offset = {},
Offset offset = {},
GLint level = 0
)
```
Generalizations of `glCopy{Tex,Texture}SubImage{1,2,3}D`, where the latter
uses [Direct State Access][].
- ```cpp
void compressed_tex_image(
GLenum target,
Size size,
GLenum internal_format,
GLsizei data_size = 0,
void const * data = nullptr,
GLint level = 0,
GLint border = 0
)
```
Generalization of `glCompressedTexImage{1,2,3}D`.
- ```cpp
void compressed_{tex,texture}_sub_image(
{GLenum,GLuint} {target,texture},
Size size,
GLsizei data_size,
void const * data,
GLenum internal_format,
Offset offset = {},
GLint level = 0
)
```
Generalizations of `glCompressed{Tex,Texture}SubImage{1,2,3}D`, where the
latter uses [Direct State Access][].
For the member functions that are template parameterized on `Value`, when
`internal_format`, `format` and/or `type` is `0` (the default), the value used
will be taken from the corresponding `GLTraits::Value<Value>` member variable.
Note that when the `Value` template type parameter is deduced from `data` the
automatically chosen `format` may not be correct. E.g. it is reasonable for
`data` to be a `GLubyte` pointer to RGBA values in which case `format` must be
manually specified as `GL_RGBA` since the automatically chosen `format` would
be `GL_RED`.
Note that the [pixel transfer parameters][] are not modified, this must be
handled manually if required.
(There is no `copy_tex_image(...)` because OpenGL does not provide
`glCopyTexImage3D`, only `glCopyTexImage{1,2}D`.)
(There is no `{tex_image,tex_storage,texture_storage}_multisample(...)` because
OpenGL does not provide `gl{TexImage,TexStorage,TextureStorage}1DMultisample`,
only `gl{TexImage,TexStorage,TextureStorage}{2,3}DMultisample`.)
(There is no `compressed_texture_image(...)` because OpenGL does not provide
`glCompressedTextureImage{1,2,3}D`, only the `Sub` variants.)
(There is no `framebuffer_texture(...)` because OpenGL provides incompatible
signatures for `glFramebufferTexture1D` and `glFramebufferTexture{2,3}D`.)
[image format]: https://www.khronos.org/opengl/wiki/Image_Format
[color formats]: https://www.khronos.org/opengl/wiki/Image_Format#Color_formats
[depth/stencil formats]: https://www.khronos.org/opengl/wiki/Image_Format#Depth_stencil_formats
[depth formats]: https://www.khronos.org/opengl/wiki/Image_Format#Depth_formats
[stencil formats]: https://www.khronos.org/opengl/wiki/Image_Format#Stencil_only
[Direct State Access]: https://www.khronos.org/opengl/wiki/Direct_State_Access
[immutable storage]: https://www.khronos.org/opengl/wiki/Texture_Storage#Immutable_storage
[pixel transfer parameters]: https://www.khronos.org/opengl/wiki/Pixel_Transfer#Pixel_transfer_parameters
### Member
`GLTraits::members()` provides compile time reflection for types consisting
(only) of types supported by `GLTraits::Value`. This feature is only available
if [C++14][] or above is supported.
If `T` is a non-[empty][] [trivially copyable][] [standard-layout][] type and
there exists template specializations of `GLTraits::Value` for the types of
either
- public member variables of `T`, if `T` is a [class][], or
- elements of `T`, if `T` is an [array][], or
- `T` itself, if `T` is a [scalar][]
then `constexpr auto GLTraits::members<T>()` returns an instance of the
[empty][] `struct GLTraits::Members<typename T, typename... Members>` where
each of `Members...` is `GLTraits::Member<typename Value, std::size_t offset>`
that describe the ("member") types above, in the order they occur in `T`.
`Value` is the type of the member and `offset` is the offset of the member in
`T`. Note that `offset` is only correct if the padding in `T` is minimal while
still satisfying the [`alignof`][] of the member types. The author knows of no
compiler that breaks this assumption unless explicitly instructed (e.g. with
[`alignas`][], which are not taken into account), however the standard allows
it.
An example use case would be along the lines of:
```cpp
template<
typename T,
typename Value,
std::size_t offset,
typename... Members
>
void vertex_setup(
GLTraits::Members<T, GLTraits::Member<Value, offset>, Members...>,
GLint location = 0
)
{
GLTraits::Value<Value>::vertex_attrib_pointer(location, offset, sizeof(T));
vertex_setup(
GLTraits::Members<T, Members...>{},
location + GLTraits::Value<Value>::columns
);
}
template<typename T>
void vertex_setup(GLTraits::Members<T>, GLint)
{}
struct Vertex
{
glm::vec3 position;
glm::vec2 tex_coord;
glm::mat3 tbn;
glm::ivec4 bone_indices;
glm::vec4 bone_weights;
GLubyte flags;
GLdouble unaligned;
};
vertex_setup(GLTraits::members<Vertex>());
```
This use case is tested in [`tests/vertex_setup.cpp`][]. To verify that the
compiler sees through all the templates, a script that builds it and
disassembles it available in [`doc/vertex_setup`][] and its output in
[`doc/vertex_setup.i`][].
It is recommended to use a library based on `gltraits` that abstracts this
further.
Many thanks to Antony Polukhin (the author of [Boost.PFR][] and its standalone
version [`magic_get`][]) on whose talks this implementation is based:
- [CppCon 2016: C++14 Reflections Without Macros, Markup nor External Tooling][]
- [Meeting C++ 2018: Better C++14 reflections][]
[trivially copyable]: https://en.cppreference.com/w/cpp/types/is_trivially_copyable
[standard-layout]: https://en.cppreference.com/w/cpp/types/is_standard_layout
[class]: https://en.cppreference.com/w/cpp/types/is_class
[array]: https://en.cppreference.com/w/cpp/types/is_array
[scalar]: https://en.cppreference.com/w/cpp/types/is_scalar
[`alignof`]: https://en.cppreference.com/w/cpp/language/alignof
[`alignas`]: https://en.cppreference.com/w/cpp/language/alignas
[`tests/vertex_setup.cpp`]: tests/vertex_setup.cpp
[`doc/vertex_setup`]: doc/vertex_setup
[`doc/vertex_setup.i`]: doc/vertex_setup.i
[Boost.PFR]: https://www.boost.org/libs/pfr
[`magic_get`]: https://github.com/apolukhin/magic_get
[CppCon 2016: C++14 Reflections Without Macros, Markup nor External Tooling]: https://www.youtube.com/watch?v=abdeAew3gmQ
[Meeting C++ 2018: Better C++14 reflections]: https://www.youtube.com/watch?v=UlNUNxLtBI0
## Building
See [`BUILDING.md`][].
[`BUILDING.md`]: BUILDING.md
## License
Licensed under the [ISC License][] unless otherwise noted, see the
[`LICENSE`][] file.
[ISC License]: https://choosealicense.com/licenses/isc
[`LICENSE`]: LICENSE
git.rcrnstn.net