Unify README.md for use in documentation; reference documentation (cl…

…oses #333)

README.md

@@ -10,6 +10,7 @@ It reduces the amount of OpenGL code required for rendering and facilitates cohe
 ![what-is-globjects](https://raw.githubusercontent.com/cginternals/globjects/master/docs/what-is-globjects.png)
 
 The following code snippet shows an exemplary use of the OpenGL API:
+
 ```cpp
 // OpenGL API
 
@@ -33,6 +34,7 @@ glUniform2f(glGetUniformLocation(program, "extent"), 1.0f, 0.5f);
 ```
 
 Using *globjects*, this can be reduced to the following code:
+
 ```cpp
 // globjects API
 
@@ -59,6 +61,7 @@ Visit [Professional Support and Services](https://www.cginternals.com) for more
 
 * [Examples](https://github.com/cginternals/globjects/wiki/examples)
 * [Project Health](#project-health)
+* [Doxygen Documentations](https://cginternals.github.io/globjects/docs) ([stable](https://cginternals.github.io/globjects/docs/v1.1), [master](https://cginternals.github.io/globjects/docs/master))
 
 ###### Installation and Development
 
@@ -111,8 +114,6 @@ Visit [Professional Support and Services](https://www.cginternals.com) for more
 | Jenkins <br><br><br><br> | Ubuntu 14.04 <br><br><br><br> | GCC 4.8 <br> GCC 4.9 <br> GCC 5.4 <br> Clang 3.8 <br> | [![Build Status](https://jenkins.hpi3d.de/buildStatus/icon?job=globjects-linux-gcc4.8)](https://jenkins.hpi3d.de/job/globjects-linux-gcc4.8) <br> [![Build Status](https://jenkins.hpi3d.de/buildStatus/icon?job=globjects-linux-gcc4.9)](https://jenkins.hpi3d.de/job/globjects-linux-gcc4.9) <br> [![Build Status](https://jenkins.hpi3d.de/buildStatus/icon?job=globjects-linux-gcc5)](https://jenkins.hpi3d.de/job/globjects-linux-gcc5) <br> [![Build Status](https://jenkins.hpi3d.de/buildStatus/icon?job=globjects-linux-clang3.8)](https://jenkins.hpi3d.de/job/globjects-linux-clang3.8) <br> |
 | Jenkins <br><br> | Windows 10 <br><br> | MSVC 2013 Update 5 <br>  MSVC 2015 Update 1 <br> | [![Build Status](https://jenkins.hpi3d.de/buildStatus/icon?job=globjects-windows-msvc2013)](https://jenkins.hpi3d.de/job/globjects-windows-msvc2013) <br> [![Build Status](https://jenkins.hpi3d.de/buildStatus/icon?job=globjects-windows-msvc2015)](https://jenkins.hpi3d.de/job/globjects-windows-msvc2015) <br> |
 
-Please note that our OS X build node is currently broken (physically). However, *globjects* is maintained for OS X as well and there are many people using it on OS X on a regular basis.
-
 
 ## Install Instructions
 
@@ -132,23 +133,28 @@ Alternatively, download the source code and commence [building from source](#bui
 *globjects* is provided on Ubuntu using PPAs.
 For Ubuntu 16.04 (xenial), 15.10 (wily), and 15.04 (vivid) use the [current PPA](https://launchpad.net/~cginternals/+archive/ubuntu/ppa), for Ubuntu 14.04 (trusty) use the [backports PPA](https://launchpad.net/~cginternals/+archive/ubuntu/backports-ppa).
 Using the current PPA as example, the following lines install *globjects* including the GLFW examples:
+
 ```shell
 > sudo apt-add repository ppa:cginternals/ppa
 > sudo apt-get update
 > sudo apt-get install libglobjects-examples-glfw
 > # start example
 > /usr/share/globjects/computeshader
 ```
+
 To use globjects as dependency, install the development package:
+
 ```shell
 > sudo apt-get install libglobjects-dev libglobjects-dbg
 ```
+
 Alternatively, download the source code and commence [building from source](#build-instructions).
 
 ###### OS X
 
 The package manager on OS X we depend on is homebrew. The package there is called [globjects](http://brewformulas.org/Globjects).
 To install *globjects* using homebrew, execute the following line:
+
 ```shell
 > brew install globjects
 ```
@@ -180,32 +186,39 @@ The only mandatory run-time dependencies of globjects are the STL of the used co
 For compilation, a C++11 compliant compiler, e.g., GCC 4.8, Clang 3.3, MSVC 2013 **Update 3**, is required.
 
 First, download the source code [as archive](https://github.com/cginternals/globjects/releases) or via git:
+
 ```shell
 > git clone https://github.com/cginternals/globjects.git
 > cd globjects
 ```
+
 Then, depending on the version of globjects you want to build, choose the appropriate tag or branch, e.g., for the 1.0.0 release:
+
 ```shell
 > git fetch --tags
 > git checkout v1.0.0
 ```
+
 The actual compilation can be done using CMake and your favorite compiler and IDE.
 
 For building *globjects* CMake via command line can be used (should work on all systems):
 
 First create a build directory (we do not recommend in-source builds):
+
 ```shell
 > mkdir build
 > cd build
 ```
 
 Configure *globjects* with your prefered or default generator, e.g., for Visual Studio 2015 in x64 use
 (note: some IDEs have integrated support for CMake projects, e.g., Qt Creator, and allow you to skip the manual project configuration):
+
 ```shell
 > cmake .. -G "Visual Studio 14 2015 Win64"
 ```
 
 In order to compile the project, either use you favorite Editor/IDE with the created project or use CMake as follows:
+
 ```shell
 > cmake --build .
 ```
@@ -214,13 +227,17 @@ In order to compile the project, either use you favorite Editor/IDE with the cre
 ## Tips for Linking
 
 We suggest using the build system of globjects for a smooth integration: [CMake](https://cmake.org/)
+
 For it, *globjects* provides a find configuration script that should be installed into your system or at least accessible by CMake. 
 In the projects CMakeLists.txt, add one of the following lines:
+
 ```
 find_package(globjects QUIET) # if you want to check for existance
 find_package(globjects REQUIRED) # if it is really required in your project
 ```
+
 Finally, just link globjects to your own library or executable:
+
 ```
 target_link_libraries(${target} ... PUBLIC globjects::globjects)
 ```
@@ -229,6 +246,7 @@ target_link_libraries(${target} ... PUBLIC globjects::globjects)
 
 globjects can handle multiple OpenGL contexts. For each context, you have to initialize the globjects state.
 Further, you have to tell globjects which context is active on a per-thread basis.
+
 ```cpp
 #include <globjects/globjects.h>
 
@@ -243,12 +261,15 @@ setCurrentContext();
 ```
 
 You can also use glbinding to automatically sync OpenGL active contexts and their glbinding and globjects counterparts:
+
 ```cpp
 glbinding::Binding::addContextSwitchCallback([](glbinding::ContextHandle handle) {
     setContext(handle);
 }
 ```
+
 The only additional thing to do is telling glbinding when a context is switched (per thread).
+
 ```cpp
 glbinding::Binding::useContext(handle);
 ```
@@ -258,6 +279,7 @@ glbinding::Binding::useContext(handle);
 ##### Global Functions
 
 Some often used functions are wrapped to ease the interface as proposed by the OpenGL API.
+
 ```cpp
 // somehow similar to glbinding
 
@@ -273,6 +295,7 @@ if (isCoreProfile())
 ##### Buffer
 
 A buffer in means of OpenGL can be used for vertex attributes, indices, uniform data, atomic counters, texture data, and shader storage data.
+
 ```cpp
 auto buffer = new Buffer();
 
@@ -289,6 +312,7 @@ buffer->bindBase(GL_SHADER_STORAGE_BUFFER, 0);
 ##### Texture
 
 Texture supports both traditional interfaces and bindless support.
+
 ```cpp
 auto texture1 = new Texture(GL_TEXTURE_2D); // type has to be fix during lifetime
 texture1->setParameter(GL_TEXTURE_MIN_FILTER, GL_LINEAR);
@@ -309,6 +333,7 @@ texture2->bindActive(0); // For traditional texturing
 ##### State
 
 OpenGL state is wrapped as States, StateSettings and Capabilities, where the latter two are mainly used internally.
+
 ```cpp
 auto currentState = State::currentState(); // full current state; usable for resetting
 
@@ -337,6 +362,7 @@ if (error)
 ##### Debug Message
 
 Enable DebugMessages to get performance hints, warnings and errors from your OpenGL driver.
+
 ```cpp
 DebugMessage::enable(); // enable automatic messages if KHR_debug is available
 
@@ -348,6 +374,7 @@ DebugMessage::setCallback([](const DebugMessage & message) {
 ##### Framebuffer
 
 Wraps a canvas with multiple render targets to render on.
+
 ```cpp
 auto fbo = new Framebuffer();
 fbo->attachTexture(GL_COLOR_ATTACHMENT0, texture1);
@@ -366,6 +393,7 @@ fbo->blit(GL_COLOR_ATTACHMENT0, {{ 0, 0, width, height }}, Framebuffer::defaultF
 ##### Named String
 
 Register compile-time shader replacements for shader includes.
+
 ```cpp
 // typically the only function call you'll need
 auto namedString1 = new NamedString("/upNormal.glsl", "const vec3 up = vec3(0.0, 1.0, 0.0);");
@@ -377,6 +405,7 @@ auto namedString2 = new NamedString("/phong.glsl", new File("data/shaders/phong.
 ##### Program
 
 The Program object can represent both render programs and compute programs. Prior usage it automatically relinks upon shader changes.
+
 ```cpp
 auto renderProgram = new Program();
 renderProgram->attach(vertexShader, fragmentShader);
@@ -402,6 +431,7 @@ pipeline->use(); // as Program interface
 ##### Query
 
 Query and measure time and perform conditional rendering with passed samples.
+
 ```cpp
 auto query = new Query();
 query->begin(GL_TIME_ELAPSED);
@@ -426,6 +456,7 @@ renderBuffer->storage(GL_RGBA32F, 512, 512);
 ##### Sampler
 
 For temporary overrides of texture parameters. Note: a newly created sampler is not configured by default, and thus invalid.
+
 ```cpp
 auto sampler = new Sampler();
 sampler->setParameter(GL_TEXTURE_MIN_FILTER, GL_LINEAR);
@@ -435,6 +466,7 @@ sampler->setParameter(GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
 
 sampler->bind(0); // override sampler state for texture at binding point 0
 ```
+
 ##### Shader
 
 ```cpp
@@ -461,6 +493,7 @@ sync->waitSync(1000000); // wait on CPU; 1 millisecond
 ##### Transform Feedback
 
 Connect shader outputs to buffers and restart drawing.
+
 ```cpp
 auto tf = new TransformFeedback();
 tf->setVaryings(program, { { "next_position" } }, GL_INTERLEAVED_ATTRIBS);
@@ -478,6 +511,7 @@ tf->draw(GL_TRIANGLE_STRIP);
 ##### Uniform
 
 Uniforms attached to Programs are updated automatically, even after relinking.
+
 ```cpp
 auto uniform1 = new Uniform<glm::vec3>("lightPos", glm::vec3(10.0f, 5.0f, 0.0f)); // name-based uniform binding
 auto uniform2 = new Uniform<glm::mat4>(0, glm::mat4(1.0f)); // location-based uniform binding
@@ -491,6 +525,7 @@ program->use(); // uniform values are updated if required
 ##### Uniform Block
 
 Use uniform blocks for large, often switched chunks of uniforms.
+
 ```cpp
 auto block = program->uniformBlock("uniforms");
 block->setBinding(0);
@@ -500,6 +535,7 @@ buffer->bindBase(GL_UNIFORM_BUFFER, 0);
 ##### Vertex Array
 
 Use to configure vertex shader inputs and trigger render pipeline processes.
+
 ```cpp
 auto vao = new VertexArray();
 // configure bindings (see next section)
@@ -530,15 +566,18 @@ binding2->setValue<float>(1.0f);
 globjects uses the RAII (resource allocation is initialization) principle, meaning that created objects are also created on the GPU.
 To effectively manage the dual-allocated memory, we use reference pointers.
 We advise that every globjects ```Object``` pointer is stored in a ```ref_ptr```.
+
 ```cpp
 {
     ref_ptr<Query> query = new Query(); // allocate on CPU and GPU
 
     // query is destructed and freed on GPU at the end of the block.
 }
 ```
+
 As the objects in globjects uses ```ref_ptr``` to store references, not using reference counting can lead to *accidentally* freed objects.
 If you don't want to use smart pointers, you have to use the manual reference counting interface:
+
 ```cpp
 program->ref(); // increase reference count
 program->unref(); // decreare reference count; potentially free program pointer and GPU program
@@ -547,6 +586,7 @@ program->unref(); // decreare reference count; potentially free program pointer
 ##### Shader Templates
 
 The sources of Shaders (```ShaderSource```) can be configured and templated.
+
 ```cpp
 auto template = new StringTemplate(new File("fragmentShader.frag"));
 template->replace("REPLACE", "WITH THIS");
@@ -557,6 +597,7 @@ auto shader = new Shader(template);
 ##### Strategy Override
 
 Although globjects tries to use most current OpenGL APIs, you can override this automatic process.
+
 ```cpp
 // Enable CPU shader includes (although supported, some drivers have problems, so disable it)
 globjects::init(Shader::IncludeImplementation::Fallback);
@@ -568,6 +609,7 @@ Buffer::hintBindlessImplementation(Buffer::BindlessImplementation::Legacy);
 ##### Logging
 
 globjects provides logging interfaces to its objects as well as glm objects.
+
 ```cpp
 std::cout << Framebuffer::defaultFBO();
 std::cout << glm::vec4(1.0, 0.0, 0.0, 1.0);