Permalink
Browse files

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

…oses #333)
  • Loading branch information...
scheibel committed May 5, 2017
1 parent a7f5f32 commit 97666aa046a731a7c655eba8d88d418146612313
Showing with 44 additions and 2 deletions.
  1. +44 −2 README.md
View
@@ -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);

0 comments on commit 97666aa

Please sign in to comment.