lecrapouille / openglcppwrapper

[Lib][Version 0.9][Partially Functional][WIP] A C++ 11 wrapper for Core Profile OpenGL allowing to write complete applications in a reduced number of lines of code

OpenGLCppWrapper

What is OpenGLCppWrapper Library ?

OpenGLCppWrapper is a C++11 wrapper for writing OpenGL Core Profile applications in few lines of code.

Warning: Do not confuse Core Profile OpenGL (>= 2.2) with Legacy Profile OpenGL (<= 2.1). This API does not manage OpenGL Legacy Profile, but manages OpenGL Core Profile version >= 3.3.

This API is split in two parts:

• The first API part (functional), greatly been inspired by the Glumpy project, is object-oriented based does not just content to give a C++ flavor name to OpenGL routines but hides for you the complexity of calling in the correct order OpenGL functions as well as passing correct parameters to them. You, as developer, will have just to deal writing your OpenGL shaders (GLSL language), asking to OpenGLCppWrapper to compile them, and filling data to populated VBOs (such as vertices position, texture coordinates, normals ...) or loading the desired textures image (png, jpeg) to populated samplers. Nothing more complex indeed, OpenGLCppWrapper will instantiate classes wrapping OpenGL VAOs, VBOs, texture, framebuffers once shaders have been compiled ... It also manages OpenGL object lifetime: it makes automatic the transfer of "dirty" CPU data (from your C++ space memory point of view) to the graphics card memory (VBOs, textures).

• The second API part (not functional, rework in progress), greatly been inspired by the three.js project gives you more abstraction, by offering some basic functionalities such as geometric primitives, materials, camera, lights and scene graph. This part will simplify you creating OpenGL scenes.

Warning: This library is not a game engine but just an oriented object wrapper for OpenGL that can be used for a game engine. As drawbacks, this API is less cache friendly than calling directly your OpenGL routines (due to a lot of if-then-else, smart pointers and dynamic cast). This is the price of hiding the complexity and staying generic.

Table Of Contents

• Installation
• Tutorial
• Examples
• Architecture
• Credits

openglcppwrapper's Issues

WIP

Progress bar:

• Update README: tutorial on Scene Graph: explanation on virtual update()
• Version 0.6: add a framebuffer. Rethink examples. finalize moving headers in include/ and write in README a small Makefile for using this lib.
• Version 0.7: check VBO size + add primitives + finish draw() (method with an implicit number of vertices, inheritance, dirty element for texture, hide private classes like GLLocation, VBO sizes checked)
• Version 0.8:
• Version 0.9: reworking folders of workspace
• [WIP] Version 0.10: simplifying API, reworking/adding basic classes: Materials/Geometry, Fog, make Camera, Light as nodes of SceneGraph, Renderer. Access to attributes and location even if shaders have not yet been compiled. Renderer(Scene, Camera). Add BoundingBox for scene nodes.
• Version 0.11: cleaning API. Add TrueType Fonts, float textures (update Mesa?), add more materials: bump mapping textures, GLSL includes, inside texture, working back to FrameBuffer
• Version 0.12: UniformCollection, FloatTextures.
• Version 1.0: Add GPUonlyTexture, GPUonlyVAO (no storage on CPU), Rethink how GLProgram stores Attributes and Uniforms

High:

• [API] draw batch of elements
• [API] Replace prog.draw(vao, ...) by vao.draw()
• [CRITICAL] aa = VBO[i] makes pending the ith element while we are just reading it (= get()). No solution on how distinguish between set and get. To be tested: https://stackoverflow.com/questions/19217813/operator-c-get-set
• WIP [API] Rework SceneGraph, Camera. Implement Light class. All are SceneGraph nodes.
• [API] Create a Mesh class (Geometry class holding shaders). Make hide code vao.bind(); prog.draw(vao);
• [API] Implement Renderer for SceneGraph.
• [API] Replace GLProgram::setInitVBOSize(x) by bind(vao, x=0) ?
• [FEATURE] Manage #include inside GLShaders https://github.com/tntmeijs/GLSL-Shader-Includes/blob/master/Shadinclude.hpp
• [IMPROV] glBindBuffer(GL_ARRAY_BUFFER) + glEnableVertexAttribArray seems not necessary to be called every time this can save important OpenGL calls.
• [FEATURE] GLumpy collection to be implemented
• [CRITICAL] cannot attach local variables of shaders to GLProg because prog will hold pointers of local variables and be compiled outside this fonction and therefore using wrong references.
• [MATHS] Check if *= does the product vector and no longer do componentProduct.
• https://learnopengl.com/Advanced-OpenGL/Instancing
• [BUG] Matrix transformation are transposed. Wrong results obtained in 07_AlphaTest.cpp
• [TODO] Refresh Projection/view matrix on the scene tree for camera nodes when window resized/mouse moved.
• [TODO] move vao->texture() to material->texture(). Fix DepthMaterial needs a loaded texture while not needed it.

Medium:

• [FEATURE] GLWindow fullscreen mode. Add mask for glwindows and events: mouse move ... avoid calling dummy callbacks.
• [FEATURE] GLWindow: create the callback onKeyPressed and onKeyReleased Update examples.
• [FEATURE] Adapt GLWindow to manage multiple windows. See https://gist.github.com/SnopyDogy/a9a22497a893ec86aa3e
• [API] Add iterator with a stack for iterating on SceneGraph nodes (see HeadFirst Design Pattern) (wont do)
• [API] SceneGraph => visitor (like done in three_cpp)
• [API] Load *.obj files
• [API] BumpMapping textures.
• [QUALITY] In example1 let suppose we forget to load a texture, a warning message occurred ERROR:GLTextures.hpp:246 Cannot setup texture with width or height set to 0 but this is not enough explicit: we need the VAO name ...
• [QUALITY] Check number of VBOs (<= 16) inside VAO ? Idem for max number of framebuffers, uniforms.
• [BUG] Wrong error message: Failed OpenGL program has not been bound to a VAO + Failed setting-up graphics => terminate called after throwing an instance of 'std::runtime_error' what(): The GLFW library is not initialized
• [TUTO] Redo and simplify tutorials: Split README into several tutorial files. Separate OpenGL wrapper examples from finale API (hiding OpenGL wrapper).

Low:

• Rename SceneGraph to Scene. Make a class 3DObject a SceneNode holding Material and Geometry. Do not let the user to have to write the recursivity for rendering or updating matrices.
• [API] Reload Shaders? https://github.com/tntmeijs/GLSL-Shader-Includes
• [API] release() as public or private ?
• [API] Complete FrameBuffer class.
• [BUG] FrameBuffer: resize window => image is broken.
• [API] Not possible to do: m_vao_floor.texture2D("texID").interpolation(xx).load(...) because missing of virtual load() method in IGLTexture.
• [API] Implement Node3D_SP operator[](std::string const& name) but fucked up by shared_from_this.
• [FEATURE] PendingContainer modifies GPUMemory() but this container may be used without OpenGL and no data transferred to GPU. Change GPUMemory() only way data are transferred to GPU.
• [FEATURE] Texture1D, Texture2DDepth, Texture3D (WIP: make an Example of texture3D http://www.mathematik.uni-marburg.de/~thormae/lectures/graphics1/code_v2/Texture3D/glut/Texture3D.cpp), TextureCube, Texture2DFloat to be implemented (for float check if the mesa has the good version supporting it https://www.mesa3d.org/index.html).
• [FEATURE] Implement in IGLTexture::update() conversion to pending data to texture x,y,w,h (FIXME: OpenGL does not like it).
• [FEATURE] VAO.VBOs and VAO.Textures holding data on CPU may be consuming too much RAM ie for a game. PendingContainer is only used for loading data during the startup of the project not anymore. Do a VBO and texture without pending container (maybe an identifier to pass in constructor and GLProgram knows how to interpret it and have an alternative of createVBO. Idea: VAO uses pointers for textures, VBOs and index ?
• [MAKEFILE] Update Makefile to compile with OS X (see dev branch but the code is messy)
• [API] Make this project to be a header-only project. (won't do)
• [API] Wrapper for VectorXf and MatrixXXf for choosing the desired matrix library (glm, Armadillo, Eigen ...). And rename glwrap::Vector3f to glwrap::vec3f or glwrap::fvec3. Idea

#if MATRIX_LIB == USE_GLM
#include <glm>
using glwrap::Vector3f = glm::vec3f; 
#elif MATRIX_LIB == USE_ARMADILLO
#include <armadillo>
using glwrap::Vector3f = arma::fvec3; 
#elif MATRIX_LIB == USE_EIGEN
#include <egein>
using glwrap::Vector3f = egein::Vector3f; 
#else // Builtin
#include "Math/Matrix.hpp"
#endif

Armadillo:

// g++ -W -Wall armad.cpp -o prog -larmadillo -llapack -lblas
#include <armadillo>

int main()
{
  arma::fmat44 A; A.ones();
  std::cout << A * A << std::endl;
  std::cout << A * 4.0 << std::endl;
  std::cout << A.eye() * 4.0 << std::endl;

  arma::fvec3 x({1.0f, 0.0f, 0.0f});
  arma::fvec3 y({0.0f, 1.0f, 0.0f});
  std::cout << arma::dot(x, y) << std::endl;
  std::cout << arma::cross(x, y) << std::endl;
  return 0;
}

• [API] Hide unnecessary classes to the developer (GLLocations, GLUniforms, Sampler ...)

• [UNIT-TESTS] Check if OpenGL context is not yet created no segfault occurs by calling OpenGL functions

• [UNIT-TESTS] Add more unit tests as checks on robustness when OpenGL context is not created or for example bind VAO to uncompiled program (or defining attributes before compiling a GLProgram).

• [UNIT-TESTS] Complete unit tests and add Travis-CI

• [UNIT-TESTS] Check destructor for every class (especially texture2D, Location)

• [UNIT-TESTS] Add unit test: attrib and uniform with the same name. Is this possible?

• [UNIT-TESTS] Can we do: m_prog.vector3f("textColor") = Vector3f({r, g, b}); when m_prog is not compiled ?

• [LICENSE] Change to MIT ?

• is possible to use sttruct => VBO:

struct Vertex { Vector3f Position; Vector4f Color; Vector2f TexCoords; };
attrib1.set<Vertex, Position>();
attrib2.set<Vertex, Color>();
attrib3.set<Vertex, TexCoords>(); 

Done:

• Compute GPU memory. (TODO: also compute shader memory)
• Pour compiler les exemples on utilise explicitemement le nom libopenglcppwrapper.a-0.6
• Reserve an GLIndexBuffer inside VAO ? See Example 07
• [API] Texture: Add new constructor(width, height) . Use pendingContainer for storing SOIL data instead of C array.
• [API] Texture: Conflict between SOIL_LOAD_RGBA vs TextureOptions::cpuPixelFormat = PixelFormat::RGBA; (dev-textures branch)
• [URGENT FEATURE] Move hpp files into include/. Install them through Makefile and generate and install a pkg-config .pc file for using my lib in another project.
• [URGENT FEATURE] be sure that prog.attribute<>("foo") = xx; is the same thing than vao.attribute<>("foo") = xx; ==> make VAO::attribute() { return m_binded_prog.bind(this); m_binded_prog.attribute<>("foo"); }
• [URGENT FEATURE] Maybe because of previous point we can simply:
  1. forbid prog.attribute("foo") ==> vao.T("foo") = ... ;
  2. replace prog.uniform<T>("foo") = ...; by prog.T("foo") = ...;
  3. I don't understand why vao1.VBO<Vector3f>("a_position") = { ... }; does not work when adding operator= in PendingContainer => I have to place this operator in GLVBO
• [URGENT FEATURE] Implement a GLProgram method checking if all VBOs and uniforms have been set and VBOs have the same size. (WIP FIXME: cannot compile)
• [API] missing GLProgram with a constructor with a reserved number of elements.
• [URGENT FEATURE] Implement a GLProgram method checking if the VAO we want to bind with is compatible with the program (2 GLProgram creating each 1 VAO, the user bind a VAO to the wrong program)
• ~~[URGENT FEATURE] Texture sampler has to follow the bound VAO (currently in Example1 texture is destroyed and created again at each cycle of the render loop). Add unit tests+ regression unit test: Example2 VAO not bound ~~
• [URGENT FEATURE] Finish draw() methods: test and give an example with index buffer. Finish draw with an implicit number of vertices. Pass VAO as param to draw() methods.
• [URGENT FEATURE] Remove unnecessary private classes like Logger, File, Maths, Singleton
• [FEATURE] Framebuffer class to be implemented. (WIP still buggy)
• [FEATURE] Rethink inheritance for Texture. Rename Texture3D as TextureCube and implement Texture3D.
• [IMPROV] PendingContainer: std::valarray is not the best container (todo: add unit tests)
• [IMPROV] Replace raw pointers by smart pointers in SceneGraph
• [API] add namespace.
• [API] Make GLBuffer and GLTexture2D have a common class ancestor (PendingContainer)
• [API] throw OpenGL exceptions instead of std::exception
• [API] Do not compile imgui into the lib but inside examples. Let compile the imgui wrapper. (wont do)
• [API] Convert OpenGL constant into C++ enum when they are required into public API.
• [API] Pass number of elements to reserved when creating VBOs
• [API] Make opengl::createContext() more generic (initially made for gtkmm)
• [API] Add SimTaDyn logger
• [API] Fix license in headers
• [API] Proper installation: move header code into include dir. Compile static and dynamic lib.
• [API] use shaders 330 in examples.
• [MATHS] Updating Vector.hpp and Matrix.hpp: uses method names from https://stanford.edu/class/ee103/julia_slides/julia_vectors_slides.pdf
  1. define template functions one() and zero(). See Lecrapouille/BacASable#1
  2. make alias method for magnitude() and norm(), length()
  3. add: addScaledVector(Vect, scal)
  4. change code operator*() for doing scalar product. Rename old code to: componentProduct()
  5. can be nice to add deviation, rms ...
• [TUTO] Rewrite the SimTaDyn SceneGraph tutorial with this API (in debug)
• [TUTO] Add the imgui SceneGraph as example.
• [TUTO] Add an example with draw + index (EBO)
• [TUTO] Framebuffer example
• [TUTO] Multi-textures example
• [TUTO] With some examples (ie 13), when resizing the window, the projection matrix is not correctly applied while others are ok (ie 04, 06).
• [DOC] Missing document differences with glumpy and opengl4csharp
• [CRASH] Fix in Example02 if we invert the position of m_cube and m_prog. This will produce a crash: the program wants to use a GPU released object.
• [QUALITY] GLProgram output error when shaders failed to compile is totally messy with carriage returns!
• [QUALITY] Init Makefile and directory for unit tests.

Matrice Product vs glm vs Scilab

OpenGL convention: column vector. For example Translation:
| 1 0 0 Tx | | x |
| 0 1 0 Ty | * | y |
| 0 0 1 Tz | | z |

• OpenGL and glm store transposed matrices (=> column major) but keep follow the M . x convention instead of x' . M' therefore their * is inversed and on my side I have to follow x' . M since I follow scilab matrix product.
• I would remove the transposed computation inside Transform.hpp and transformable.hpp + camera.cpp
• In addition vector * vector should be like Scilab: dot product + check about dimensions. The * is in fact a component product.
• I would make Vector be column or row: template <T, n, m> vector + check if n or m are 1. => ColumnVecor<T, n> = Vector<T, n, 1>