# [`glbackend`][]
A [C++11][]/[OpenGL][] \>=[1.0][] [backend][] library.
Currently supported backends (one from each category listed under
[Context/Window Toolkits][] on the OpenGL wiki):
| Name | Category | Define | Include | Class |
| -- | -- | -- | -- | -- |
| [GLFW][] | Windowing/input | `GLBACKEND_GLFW` | `glbackend_glfw.hpp` | `BackendGLFW` |
| [SDL2][] | Multimedia | `GLBACKEND_SDL` | `glbackend_sdl.hpp` | `BackendSDL` |
| [wxWidgets][] | [Widget toolkit][] | `GLBACKEND_WXWIDGETS` | `glbackend_wxwidgets.hpp` | `BackendWxWidgets` |
[`glbackend`]: https://git.rcrnstn.net/rcrnstn/glbackend
[C++11]: https://en.wikipedia.org/wiki/C++11
[OpenGL]: https://en.wikipedia.org/wiki/OpenGL
[1.0]: https://en.wikipedia.org/wiki/OpenGL#Version_history
[backend]: https://www.khronos.org/opengl/wiki/Related_toolkits_and_APIs#OpenGL_initialization
[Context/Window Toolkits]: https://www.khronos.org/opengl/wiki/Related_toolkits_and_APIs#Context/Window_Toolkits
[GLFW]: https://www.glfw.org
[SDL2]: https://www.libsdl.org
[wxWidgets]: https://www.wxwidgets.org
[Widget toolkit]: https://en.wikipedia.org/wiki/Widget_toolkit
## Usage
### Overview
```cpp
#include <glbackend_default.hpp>
constexpr auto size = GLBackend::Size{640, 480};
int main()
{
// Create.
auto backend = GLBackendDefault("Default", size);
// Render loop.
backend.callback_render([&]()
{
glClearColor(1.0F, 0.0F, 0.0F, 0.5F);
glClear(GL_COLOR_BUFFER_BIT);
if (backend.key("Enter"))
backend.tga_write("screenshot.tga");
if (backend.key("Escape"))
backend.running(false);
});
backend.run();
}
```
### Global settings
#### Errors
After backend construction (see [Lifetime](#lifetime)) errors are non-fatal and
are reported to the output configured with
```
using OutputCallback = std::function<void(std::string const & message)>;
static std::ostream * output_stream(std::ostream * output_stream);
static OutputCallback output_callback(OutputCallback output_callback);
```
(defaults to `std::cerr` and empty, respectively). The old values are returned.
If the backend is constructed with `debug = true` (see [Lifetime](#lifetime))
and OpenGL \>=4.3 or the extension [`GL_KHR_debug`][] is available, OpenGL
debug messages with a severity other than `GL_DEBUG_SEVERITY_NOTIFICATION` are
also reported using the same output. The messages received from the OpenGL
implementation are modified slightly to remove trailing whitespace and double
quotes surrounding file names in lines starting with *"path":line*.
[`GL_KHR_debug`]: https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_debug.txt
#### File system
If the value passed to
```
static std::string directory(std::string directory);
```
is non-empty it is prepended, with a separating `"/"`, to all relative paths
(defined as paths not starting with `"/"`) given as arguments to other
functions. The old value is returned.
### Lifetime
Constructors [`throw`][] [`std::runtime_error`][] on failure, with a `what()`
describing the error.
To use a backend, instantiate the appropriate `Backend`-derived class. Several
objects can be instantiated, using the same or different underlying backends.
All the provided `Backend`-derived classes' constructors take the following
arguments, in this order:
- Window-related:
- `std::string const & title`: The window title.
- `int width`: The window width.
- `int height`: The window height.
- `bool fullscreen = false`: Whether or not to create a fullscreen
window.
- `bool transparent = false`: Whether or not to use the alpha channel of
the default framebuffer to blend with the background. If this is
enabled, window decorations are disabled and the window is kept on top
of other windows.
- [Context][]-related:
- `bool debug = false`: If `false`, creates a [no error][] context. If
`true`, creates a [debug context][], and enables [debug output][].
- `int samples = -1`: The number of samples used in
[mutlisample][multisampling] anti-aliasing (MSAA) of the default
framebuffer (`-1` lets the implementation decide).
- `int version_major = -1`: The major version with which the OpenGL
[context][] must be compatible (`-1` lets the implementation decide).
- `int version_minor = -1`: The minor version with which the OpenGL
[context][] must be compatible (`-1` lets the implementation decide).
The relevant underlying backend is automatically initialized at instantiation.
If no other code has initialized that backend, it is guaranteed to be
terminated when the last instance is destroyed. It is backend-specific if the
backend is terminated even if other code has initialized it.
The provided `Backend`s create double buffered, 32 bit color (including alpha),
24 bit depth, 8 bit stencil OpenGL [context][]s. If the requested version is
\>=3.2 a [forward compatible][] core context is created.
The `Backend`s are move(-constructible)-only types.
[`throw`]: https://en.cppreference.com/w/cpp/language/throw
[`std::runtime_error`]: https://en.cppreference.com/w/cpp/error/runtime_error
[context]: https://www.khronos.org/opengl/wiki/OpenGL_Context
[debug context]: https://www.khronos.org/opengl/wiki/Debug_Context
[debug output]: https://www.khronos.org/opengl/wiki/Debug_Output
[no error]: https://www.khronos.org/opengl/wiki/OpenGL_Context#No_error_contexts
[multisampling]: https://www.khronos.org/opengl/wiki/Multisampling
[forward compatible]: https://www.khronos.org/opengl/wiki/OpenGL_Context#Forward_compatibility
### Info
```
std::string info() const;
```
returns information about the underlying backend.
### Context
Each `Backend` instance has its own OpenGL [context][], which is made current
at instantiation. If several `Backend`s are used,
```
void current();
```
can be called to make the context of a specific one current.
### Render loop
```
void events();
```
handles events from the underlying backend.
```
void swap();
```
swaps the OpenGL default framebuffer.
```
bool running() const;
bool running(bool running);
```
queries and sets, respectively, the window "running" state.
```
float time() const;
float time(float time);
```
queries and sets, respectively, the current time, in seconds.
```
using Update = std::function<void(float t, float dt, bool final)>;
using Render = std::function<void()>;
Backend & update(Update const & update);
Backend & render(Render const & render);
```
sets the `update` and `render` callbacks, respectively, used by
```
void run(float dt_max = 0.0F);
```
which is a convenience function that uses the member functions and callbacks
described in this section to implement a render loop. `t` is the current time,
which is set to `0.0F` at the start of `run`. If `dt_max` is `0.0F`, the
`update` callback is called once for every frame, with `dt` holding the elapsed
time. Otherwise, the `update` callback is called as many times as necessary to
advance through the elapsed time while ensuring `dt` is never larger than
`dt_max`. `final` is `true` if this is the final update of the frame. `render`
is called at the end of each frame. Either of the callbacks can be unset.
### Input and output
```
void lock(bool lock);
```
controls mouse locking. If `true` is passed the mouse is locked, which means it
is hidden and prevented from leaving the window. Passing `false` restores the
normal behavior.
The input (keyboard and mouse) and output (framebuffer) state can be accessed
in two different ways: registering callbacks and / or polling. The same
function name is used for both methods (with function overloading). These are
described below.
#### Keyboard
The
```
key
```
*callback / poll* takes as argument a `std::string const & key` and *is called
when / returns `true` if* that key is pressed. Valid arguments are
backend-specific but guaranteed to support:
- `"A"` through `"Z"`
- `"0"` through `"9"`
- `"Left"`, `"Right"`, `"Up"`, `"Down"`
- `"Enter"`, `"Escape"`, `"Tab"`, `"Backspace"`
- `"Control"`, `"Shift"`, `"Alt"`
#### Mouse
The
```
button
```
*callback / poll* takes as argument an `int button` and *is called when /
returns `true` if* that button is pressed. Valid arguments are backend-specific
but guaranteed to support `1`, `2`, and `3`.
The
```
scroll
```
*callback / poll* takes as *argument / returns* `std::array<float, 2> scroll`.
The
```
position
```
*callback / poll* takes as *argument / returns* `std::array<float, 2>
position`.
The
```
move
```
*callback / poll* takes as *argument / returns* `std::array<float, 2> move`.
#### Framebuffer
The
```
size
```
*callback / poll* takes as *argument / returns* `std::array<int, 2> size`.
### Persisting frames
There is basic support for writing frames to disk, useful for testing or
screenshot functionality.
Writing is done with
```
bool frame_tga_write(
std::string const & path
) const;
```
As the name suggests, the frame is written as an uncompressed [BGRA][]
[Truevision TGA][] image, selected because it is widely supported and has a
trivial header and data layout. The function returns `true` on success, on
failure an [error](#errors) is emitted and `false` is returned.
```
bool frame_tga_compare(
std::string const & path,
bool write_on_failed_read = false
) const;
```
can be used to compare the current frame to one written previously. Note that a
general TGA reader is not used; the comparison is done byte for byte, header
included. If the given `path` cannot be read an [error](#errors) is emitted and
if `write_on_failed_read` is `true` the current frame is instead written to
`path`.
`".tga"` is automatically added to the end of `path`. In addition, `directory`
is applied if appropriate, see [File system](#file-system).
No function is provided to read the frame without interacting with the file
system. If this is required, simply use [`glReadPixels`][].
[BGRA]: https://en.wikipedia.org/wiki/RGBA_color_model
[Truevision TGA]: https://en.wikipedia.org/wiki/Truevision_TGA
[`glReadPixels`]: https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glReadPixels.xhtml
## Dependencies
System dependencies that need to be installed:
- Public (interface):
- [OpenGL][] (e.g. [`libgl1-mesa-dev`][]).
- [OpenGL Extension Wrangler (GLEW)][] (e.g. [`libglew-dev`][]).
- Private (tests):
- [GLFW][] (e.g. [`libglfw3-dev`][]).
- [SDL2][] (e.g. [`libsdl2-dev`][]).
- [wxWidgets][] (e.g. [`libwxgtk3.0-gtk3-dev`]).
[OpenGL Extension Wrangler (GLEW)]: http://glew.sourceforge.net
[`libgl1-mesa-dev`]: https://packages.debian.org/search?keywords=libgl1-mesa-dev
[`libglew-dev`]: https://packages.debian.org/search?keywords=libglew-dev
[`libglfw3-dev`]: https://packages.debian.org/search?keywords=libglfw3-dev
[`libsdl2-dev`]: https://packages.debian.org/search?keywords=libsdl2-dev
[`libwxgtk3.0-gtk3-dev`]: https://packages.debian.org/search?keywords=libwxgtk3.0-gtk3-dev
## Build system
This project supports [CMake][] and uses [`cmake-common`][]. There are several
ways to use it in other CMake-based projects:
- With [`find_package`][]: ([Package][] and) [install][] it on the system.
- With [`add_subdirectory`][]: Bundle it.
- With [`FetchContent`][]: Download it as part of the CMake configure step.
- With [`cmake-common`][]: Use any of the above methods through a simplified
interface.
As usual, use [`add_dependencies`][] or [`target_link_libraries`][] (or
`cmake-common`'s `DEPENDENCIES_*`) to declare the dependency.
[CMake]: https://cmake.org
[`cmake-common`]: https://git.rcrnstn.net/rcrnstn/cmake-common
[`FetchContent`]: https://cmake.org/cmake/help/v3.14/module/FetchContent.html
[`add_subdirectory`]: https://cmake.org/cmake/help/v3.14/command/add_subdirectory.html
[`find_package`]: https://cmake.org/cmake/help/v3.14/command/find_package.html
[Package]: #Package
[Install]: #Install
[`add_dependencies`]: https://cmake.org/cmake/help/v3.14/command/add_dependencies.html
[`target_link_libraries`]: https://cmake.org/cmake/help/v3.14/command/target_link_libraries.html
### Configure and generate
To configure and generate a build tree, use `cmake`:
```sh
cmake -B _build
```
To set the build type, pass e.g. `-D`[`CMAKE_BUILD_TYPE`][]`=Release`.
[`cmake`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#generate-a-project-buildsystem
[`CMAKE_BUILD_TYPE`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_BUILD_TYPE.html
### Build
To build, use [`cmake --build`][]:
```sh
cmake --build _build
```
To disable building tests, pass `-D`[`BUILD_TESTING`][]`=OFF`.
[`cmake --build`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#build-a-project
[`BUILD_TESTING`]: https://cmake.org/cmake/help/v3.14/module/CTest.html
### Test
To run tests, use [`ctest`][]:
```sh
(cd _build && ctest)
```
To show output from failing tests, pass `--output-on-failure`. To show output
from all tests, pass `--verbose`.
[`ctest`]: https://cmake.org/cmake/help/v3.14/manual/ctest.1.html
### Package
To package, use [`cpack`][]:
```sh
(cd _build && cpack)
```
[`cpack`]: https://cmake.org/cmake/help/v3.14/manual/cpack.1.html
### Install
To install onto the current system, use [`cmake --install`][]:
```sh
cmake --install _build
```
To set the prefix, pass e.g. `-D`[`CMAKE_INSTALL_PREFIX`][]`="$HOME/.local"`.
[`cmake --install`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#install-a-project
[`CMAKE_INSTALL_PREFIX`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_INSTALL_PREFIX.html
## 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