quickGL

A quick and easy to use OpenGL wrapper

Report Bug · Request Feature

About the project

quickGL aims to provide a thin wrapper for OpenGL in order to automate common tasks and provide some useful features, such as:

• Automatic GLFW and GLAD initialization;
• Shader manager:
  • Name each program for easy access;
  • Automatic shader compilation and program linkage;
  • Detailed report for compilation and linkage errors;
• Automatic basic camera handling;
• Callback management:
  • Default callbacks are provided;
  • Any callback can be overriden;
  • Optionally use the default callback within the new one.

(back to top)

Requirements

• C++ 20
• GLFW 3.3.8
• GLM 0.9.9.8
• GLAD

(back to top)

Changelog

Version	Description
0.3.1	Adds initial support for definition of methods for input processing and pre-processing tasks.
0.3.0	Adds initial support for mouse and camera control.
0.2.0	Adds shader manager (with support for vertex, fragment, geometry and compute shaders).
0.1.0	Initial version for automatic GLFW and GLAD initialization.

Usage

Basic structure

#define QGL_GLAD_LOCAL
#include "quickgl.hpp"

int main(int argc, char const *argv[]) {
    QGlScene scene(argv[0]);
    scene.initialize(1000, 500, "quickGL smallest example");
    if (!scene.launchSuccessful())
        std::cerr << "Launch was not successful." << std::endl;
    else
        scene.run();
    return 0;
}

If you use GLAD, you must define one of the following before including quickgl.hpp:

Macro	Definition
QGL_GLAD	GLAD is available in the system, or the compiler has a link directive to its location.
QGL_GLAD_LOCAL	GLAD is available in the relative path "glad/glad.h".

(back to top)

Define tasks for each frame

quickGL runs a loop which performs the following functions by order:

#	Method	Description	Has default?
1	preProcessInput()	Tasks to be performed before processing input	No
2	processInput()	Input processing (mouse events, keyboard...)	Yes
3	refresh()	Frame renderization tasks	No

By default, processInput() exits the application when the Escape key is pressed and moves the camera with WASD keys.

void myRefresh(QGlScene& cls) {
    // some graphical code...

    /* It is NOT necessary to swap buffers nor poll events.
     * This is automatically done by quickGL. */
}

scene.refresh = myRefresh;

(back to top)

Add a personalized callback function

Callback functions must be declared inside namespace qgl::callback. Access to your QGlScene instance is done via the method getInstance(): quickGL automatically attaches the instance before rendering the next frame.

Callback	Set method
Frame buffer size	setFrameBufferSizeCallback()
Mouse button click	setMouseButtonCallback()
Cursor position	setCursorPositionCallback()
Mouse scroll	setScrollCallback()

The following example applies to mouse button clicks:

namespace qgl::callback {
    void myMouseClick(GLFWwindow *window, int button, int action, int mods) {
        getInstance()->finalize();
    }
}

// Whener you need it, add the line:
scene.setMouseButtonCallback(qgl::callback::myMouseClick);

(back to top)

Add and use shaders

A set of shaders constitues a program. You can add a new program by name and access it with the method withProgram("foo"): if the program named foo does not exist, it is automatically created.

bool result =       // Stores the result of program building
    scene.withProgram("triangle")   // Name for the program with the following shaders
    .withShaders(
        "shaders/triangle.vert",    // Path to vertex shader
        "shaders/triangle.frag"     // Path to fragment shader
    )
    .build();                       // Compile shaders and link program

if (!result) {
    // Print the report generated by the shader manager
    std::cerr << scene.withProgram("triangle").getReport() << std::endl;
}

// You can also check at anytime if the build was successful like so:
if (!scene.withProgram("triangle").wasSuccessful()) {
    // potatoes...
}

The type of shaders is automatically determined by the number os parameters given to withShaders():

• 1 — compute shader (because it requires a whole program for itself);
  • withShader("computeShader")
• 2 — vertex and fragment shaders, respectively;
  • withShader("vertexShader", "fragmentShader")
• 3 — same as 2, with the optional geometry shader as 3rd argument.
  • withShader("vertexShader", "fragmentShader", "geometryShader")

You can change an uniform variable within the shaders as well:

scene.withProgram("triangle").setInt("bar", 42);

Whenever you need to proceed your application with this program, call use():

scene.withProgram("triangle").use();

(back to top)

Access camera and mouse data and methods

Method	Description
Mouse
withMouseData()	Retrieves the mouse data handler
getMouseData()	⚠️ Deprecated! Same as withMouseData()
setMouseData()	Sets cursor position and if it shall be considered as first position
Camera
withCamera()	Retrieves the camera manager handler

scene.setMouseData(x, y, false);
scene.withMouseData().lastX *= .75f;

scene.withCamera().processMouseMovement(x, y);

(back to top)

Related projects

The following projects use quickGL as a basis and inspired its initial features:

• Bohr — A very small PDB molecular visualizer;
• MarchGL — An isosurface renderer using marching cubes on modern OpenGL.

(back to top)

Contributing

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the GNU General Public License v3.0. See LICENSE.md for more information.

(back to top)

Acknowledgments

• Joey de Vries, for his amazing website Learn OpenGL.

(back to top)