@@ -13,8 +13,25 @@ project(glbackend

 ## Main target

 add_library(${PROJECT_NAME})

+## Variables

+set(GLBACKEND_DEPENDENCIES)

+set(GLBACKEND_DEFINITIONS)

+

 ## Common

 include(common.cmake)

 common(

     CXX_STANDARD 11

+    FETCHCONTENT

+        https://git.rcrnstn.net/rcrnstn/glbase

+        https://git.rcrnstn.net/rcrnstn/cxx-str

+    DEPENDENCIES_PRIVATE

+        glbase

+        cxx-str

+        ${GLBACKEND_DEPENDENCIES}

+    DEPENDENCIES_TESTS

+        glbase

+        cxx-str

+        ${GLBACKEND_DEPENDENCIES}

+    DEFINITIONS

+        ${GLBACKEND_DEFINITIONS}

 )

@@ -2,12 +2,327 @@

 A [C++11][]/[OpenGL][] \>=[1.0][] [backend][] library.

+Currently supported backends:

+

+| Name | Category | Define | Include | Class |

+| --   | --       | --     | --      | --    |

+

 [`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

+## 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:

@@ -1,4 +1,4 @@

-/// Include guard

+/// Guards

 #ifndef GLBACKEND_HPP_

 #define GLBACKEND_HPP_

@@ -158,6 +158,6 @@ protected:

 };

-/// Include guard

+/// Guards

 #endif

new file mode 100644

@@ -0,0 +1,10 @@

+#ifndef GLBACKEND_DEFAULT_HPP_

+#define GLBACKEND_DEFAULT_HPP_

+

+

+#if 1

+    #error "No GLBackendDefault configured"

+#endif

+

+

+#endif

@@ -0,0 +1,308 @@

+/// Includes

+

+

+#include <glbackend.hpp>

+

+#include <algorithm>

+#include <cstddef>

+#include <exception>

+#include <iomanip>

+#include <regex>

+#include <sstream>

+#include <string>

+

+#include <glbase.hpp>

+

+// NOLINTNEXTLINE

+#define STR_EXCEPTION GLBase::Exception

+#include <str.hpp>

+

+

+/// Special member functions

+

+

+GLBackend::GLBackend()

+:

+    callback_update_{},

+    callback_render_{},

+    scroll_{},

+    position_{},

+    move_{},

+    size_{},

+    callback_key_{},

+    callback_button_{},

+    callback_scroll_{},

+    callback_position_{},

+    callback_move_{},

+    callback_size_{}

+{

+}

+

+

+void GLBackend::init_()

+{

+    #ifdef __GLEW_H__

+    if (auto error = glewInit())

+        STR_THROW(

+            "Failed to initialize GLEW:" << "\n" <<

+            glewGetErrorString(error)

+        );

+    #endif

+

+    if (debug() >= 1)

+    {

+        if (supported({4, 3}, "GL_KHR_debug"))

+        {

+            glEnable(GL_DEBUG_OUTPUT);

+            glEnable(GL_DEBUG_OUTPUT_SYNCHRONOUS);

+            glDebugMessageControl(

+                GL_DONT_CARE, GL_DONT_CARE, GL_DONT_CARE,

+                0, nullptr,

+                GL_TRUE

+            );

+            glDebugMessageControl(

+                GL_DONT_CARE, GL_DONT_CARE, GL_DEBUG_SEVERITY_NOTIFICATION,

+                0, nullptr,

+                GL_FALSE

+            );

+            glDebugMessageCallback(debug_gl_message_callback_, nullptr);

+        }

+    }

+}

+

+

+/// Render loop

+

+

+void GLBackend::run(float dt_fixed)

+{

+    auto t = time(0);

+    running(true);

+    while (events(), running())

+    {

+        if (callback_update_)

+        {

+            auto t_next = time();

+            auto dt = t_next - t;

+            if (dt_fixed != 0.0F)

+                dt = dt_fixed;

+            while (t + dt <= t_next)

+            {

+                callback_update_(t, dt, !(t + 2 * dt <= t_next));

+                t += dt;

+            }

+        }

+        if (callback_render_)

+            callback_render_();

+        swap();

+    }

+}

+

+

+/// Path

+

+

+GLBASE_GLOBAL(GLBackend::prefix_, {})

+

+

+/// TGA

+

+

+void GLBackend::tga_write(

+    Path const & path

+) const

+{

+    tga_().write(path_prefix_(path, prefix()));

+}

+

+

+bool GLBackend::tga_compare(

+    Path const & path,

+    bool         write_on_failed_read

+) const

+{

+    auto path_prefix = path_prefix_(path, prefix());

+    auto tga = tga_();

+    try

+    {

+        auto tga_read = TGA_::read(path_prefix);

+        return tga_read.data() == tga.data();

+    }

+    catch (std::exception const & exception)

+    {

+        if (!write_on_failed_read)

+            throw;

+        if (debug() >= 1)

+            debug_callback()(exception.what());

+        debug_callback()(STR("Writing TGA \"" << path_prefix << "\"."));

+        tga.write(path_prefix);

+        return false;

+    }

+}

+

+

+GLBackend::TGA_ GLBackend::tga_() const

+{

+    glFlush();

+    auto size = this->size();

+    auto data = std::vector<GLubyte>((4 * (size_t)size[0] * (size_t)size[1]));

+    glPixelStorei(GL_PACK_ALIGNMENT, 4);

+    glReadPixels(

+        0, 0,

+        size[0], size[1],

+        GL_BGRA, GL_UNSIGNED_BYTE,

+        data.data()

+    );

+    return TGA_(size, std::move(data));

+}

+

+

+/// Debug

+

+

+std::string GLBackend::debug_info() const

+{

+    auto ostream = std::ostringstream{};

+

+    #ifdef __GLEW_H__

+    // NOLINTNEXTLINE

+    #define GLBACKEND_INFO_GLEW_(NAME) \

+        {#NAME, (char const *)glewGetString(GLEW_##NAME)}

+    debug_info_(ostream, "GLEW", {

+        GLBACKEND_INFO_GLEW_(VERSION),

+    });

+    #endif

+

+    // NOLINTNEXTLINE

+    #define GLBACKEND_INFO_GL_(NAME) \

+        {#NAME, (char const *)glGetString(GL_##NAME)}

+    // NOLINTNEXTLINE

+    #define GLBACKEND_INFO_GL_FLAG_(NAME) \

+        { \

+            #NAME, \

+            (flags & (GLuint)GL_CONTEXT_FLAG_##NAME##_BIT) \

+                ? "TRUE" \

+                : "FALSE" \

+        }

+    // NOLINTNEXTLINE

+    #define GLBACKEND_INFO_GL_INTEGER_(NAME) \

+        {#NAME, std::to_string(integer(GL_##NAME)) }

+    auto const flags = (GLuint)integer(GL_CONTEXT_FLAGS);

+    debug_info_(ostream, "OpenGL", {

+        GLBACKEND_INFO_GL_(VENDOR),

+        GLBACKEND_INFO_GL_(RENDERER),

+        GLBACKEND_INFO_GL_(VERSION),

+        GLBACKEND_INFO_GL_(SHADING_LANGUAGE_VERSION),

+        GLBACKEND_INFO_GL_FLAG_(FORWARD_COMPATIBLE),

+        GLBACKEND_INFO_GL_FLAG_(DEBUG),

+        GLBACKEND_INFO_GL_FLAG_(ROBUST_ACCESS),

+        GLBACKEND_INFO_GL_FLAG_(NO_ERROR),

+        GLBACKEND_INFO_GL_INTEGER_(SAMPLE_BUFFERS),

+        GLBACKEND_INFO_GL_INTEGER_(SAMPLES),

+    });

+

+    return ostream.str();

+}

+

+

+void GLBackend::debug_info_(

+    std::ostream                                           & ostream,

+    std::string                                      const & category,

+    std::vector<std::pair<std::string, std::string>> const & values,

+    char                                                     fill

+)

+{

+    auto length_max = int{0};

+    for (auto const & value : values)

+        length_max = std::max(length_max, (int)value.first.length());

+    ostream << category << "\n";

+    for (auto const & value : values)

+        ostream

+            << "  "

+            << std::left << std::setw(length_max + 1 + 2) << std::setfill(fill)

+            << (value.first + " ")

+            << (" " + value.second)

+            << "\n";

+}

+

+

+void GLAPIENTRY GLBackend::debug_gl_message_callback_(

+    GLenum          source,

+    GLenum          type,

+    GLuint          id,

+    GLenum          severity,

+    GLsizei         length,

+    GLchar  const * message,

+    void    const * user_param

+)

+{

+    (void)length;

+    (void)user_param;

+

+    auto ostream = std::ostringstream{};

+    ostream << std::hex << std::showbase;

+

+    // https://www.khronos.org/opengl/wiki/Debug_Output#Message_Components

+    ostream << "GL debug message ";

+    // NOLINTNEXTLINE

+    #define GLBACKEND_CALLBACK_CASE_(CATEGORY, VALUE) \

+        case GL_DEBUG_##CATEGORY##_##VALUE: \

+            ostream << #VALUE; \

+            break;

+    switch(source)

+    {

+        GLBACKEND_CALLBACK_CASE_(SOURCE, API)

+        GLBACKEND_CALLBACK_CASE_(SOURCE, WINDOW_SYSTEM)

+        GLBACKEND_CALLBACK_CASE_(SOURCE, SHADER_COMPILER)

+        GLBACKEND_CALLBACK_CASE_(SOURCE, THIRD_PARTY)

+        GLBACKEND_CALLBACK_CASE_(SOURCE, APPLICATION)

+        GLBACKEND_CALLBACK_CASE_(SOURCE, OTHER)

+        default:

+            ostream << source;

+    }

+    ostream << " ";

+    switch(type)

+    {

+        GLBACKEND_CALLBACK_CASE_(TYPE, ERROR)

+        GLBACKEND_CALLBACK_CASE_(TYPE, DEPRECATED_BEHAVIOR)

+        GLBACKEND_CALLBACK_CASE_(TYPE, UNDEFINED_BEHAVIOR)

+        GLBACKEND_CALLBACK_CASE_(TYPE, PORTABILITY)

+        GLBACKEND_CALLBACK_CASE_(TYPE, PERFORMANCE)

+        GLBACKEND_CALLBACK_CASE_(TYPE, MARKER)

+        GLBACKEND_CALLBACK_CASE_(TYPE, PUSH_GROUP)

+        GLBACKEND_CALLBACK_CASE_(TYPE, POP_GROUP)

+        GLBACKEND_CALLBACK_CASE_(TYPE, OTHER)

+        default:

+            ostream << type;

+    }

+    ostream << " ";

+    switch(severity)

+    {

+        GLBACKEND_CALLBACK_CASE_(SEVERITY, HIGH)

+        GLBACKEND_CALLBACK_CASE_(SEVERITY, MEDIUM)

+        GLBACKEND_CALLBACK_CASE_(SEVERITY, LOW)

+        GLBACKEND_CALLBACK_CASE_(SEVERITY, NOTIFICATION)

+        default:

+            ostream << severity;

+    }

+    ostream << " ";

+    ostream << id;

+    ostream << ":\n";

+

+    ostream << debug_gl_message_(message);

+

+    debug_callback()(ostream.str());

+}

+

+

+std::string GLBackend::debug_gl_message_(std::string message)

+{

+    message.erase(message.find_last_not_of(" \n") + 1);

+

+    auto static const file_line = std::regex{R""(^"([^"]+)"(:[0-9]+.*))""};

+    auto match = std::smatch{};

+    if (std::regex_match(message, match, file_line))

+        message = match.str(1) + match.str(2);

+

+    return message;

+}

new file mode 100644

@@ -0,0 +1,45 @@

+#ifndef GLBACKEND_TESTS_COMMON_RUN_HPP_

+#define GLBACKEND_TESTS_COMMON_RUN_HPP_

+

+

+#include <iostream>

+#include <string>

+

+#include <glbase.hpp>

+#include <glbackend.hpp>

+

+// NOLINTNEXTLINE

+#define STR_EXCEPTION GLBase::Exception

+#include <str.hpp>

+

+

+

+#define GLBACKEND_TESTS_COMMON_RUN(GLBACKEND) \

+    run<GLBACKEND>(#GLBACKEND);

+

+

+constexpr auto size = std::array<int, 2>{640, 480};

+

+

+template<typename GLBackend>

+inline void run(std::string const & name)

+{

+    GLBackend::prefix("assets/tests");

+

+    auto backend = GLBackend(name, size);

+

+    std::cout << backend.debug_info() << std::endl;

+

+    backend.callback_render([&]()

+    {

+        glClearColor(1.0F, 0.0F, 0.0F, 0.5F);

+        glClear(GL_COLOR_BUFFER_BIT);

+        if (!backend.tga_compare(name + ".tga", true))

+            STR_THROW("Frame did not match expected frame.");

+        backend.running(false);

+    });

+    backend.run();

+}

+

+

+#endif