The Basic Renderer (bRenderer) is a cross-platform educational framework written in C++ and suited to teach basic knowledge in computer graphics. It was written for and tested on iOS, Windows, Mac OS X, and Linux.
Important: This framework is now outdated and not compatible with current versions of iOS.
The paper "bRenderer: A Flexible Basis for a Modern Computer Graphics Curriculum" was presented at Eurographics 2017 as part of the Education Program. It is available in the download section of this page.
Click on each of the boxes in the architecture overview below for more details about the classes.
Download directly from GitHub: click here
Download: click here
Download: click here
In this tutorial we are going to write a simple "Hello World"-application to get familiar with the basics of the framework. The final result will be a window on desktop systems or a view on iOS displaying a text of our choosing.
More advanced techniques to create beautiful scenes and effects are available in the guides section of this website. Additionally an example project can be downloaded in the download section, which demonstrates a multitude of possibilities the Basic Renderer offers.
To get started we first download the current version of the framework from the download section. After extracting the zip file, we are left with the following folders and files:
The easiest way to start is by opening one of the provided Visual Studio or Xcode projects and adjusting or replacing the provided code. In this case the setup phase is over and we can proceed with the next section.
If we want to start from scratch or use a different IDE (such as Eclipse), we need to follow a few steps first, which are mostly the same on all desktop systems yet differ on iOS by quite a bit. In this case please refer to the setup guide before continuing the tutorial.
The Basic Renderer can be downloaded with an example project or an empty project already included. If we are inexperienced with app development on iOS, this may be very helpful as we only need to write our code in the "RenderProject" class. The "main.cpp" file and the contents of the "project/ios/resources" folder take care of setting up the project on Windows, Mac or iOS.
However we'll probably need to adjust the standard file path defined in the "main.cpp" for Mac ("project/osx") and Windows ("project/windows"). If we keep the relative path, we need to know where the application will be located after compilation. This may differ depending on the operating system and the IDE. If we work on Windows, Visual Studio will create a "Debug" or "Release" folder where the executable will be placed, however if started in Visual Studio the relative path will refer to the location of the project in the folder "project/windows". On Mac we should set the working directory to "$PROJECT_DIR", which is the location of our Xcode project. To do that, we go to Product > Scheme > Edit Scheme > Run (on the right) > Options and select “Use custom working directory”. On iOS we just drag and drop the data into Xcode and the Basic Renderer will automatically request its URL.
If we decide to just use the provided project, we can now adjust it to our needs and continue with the next section of this tutorial. If we already have an application or want to start from scratch, we need to setup our own class inheriting the "IRenderProject" interface. Please refer to the setup guide and the renderer guide for details. In a nutshell we need to create a class and include the Basic Renderer as shown below:
This requires us to inherit three callback functions: the "initFunction", "loopFunction" and "terminateFunction". Additionally in either the constructor or a setup function of the custom class we need to initialize and run the renderer:
Now that we have our "RenderProject", we can start creating objects in the "initFunction", which gets called right after the Basic Renderer has been initialized. Since the goal of this tutorial is to display a text (e.g. "Hello World"), we first need a font. On Windows we can just copy a font file from "C:\Windows\Fonts" or we could download a file in the internet and place it in our specified data folder. As the fonts are loaded by FreeType, please consult the official homepage of the library for more information about supported file formats.
Next we can load our font file using the renderer's object manager as shown below:
To be able to draw text using the font, we need to create a text sprite. There are two different options in the object manager to do that: The first one creates a material and a shader automatically, whereas the second one would require us to do this ourselves. In this tutorial we'll choose the easier option that even lets us specify a color for the text to be drawn. For more advanced techniques refer to the guides. In the following example we set the red, green and blue values of the color to 1.0, which results in a white color, and choose the text to be "Hello World":
That's all it takes. In the next section we will draw our text sprite.
Objects can be drawn in the "loopFunction" of our class as it gets called by the renderer for every frame. Yet before we can draw our text, we first need a model matrix, a view matrix and a projection matrix as shown below:
By dividing the x-value of our scale by the aspect ratio of our view, the text will not be stretched in one direction if we change the resolution of our window. The view and projection matrix would usually be created by a camera object, yet for a text overlay this is not necessary. If we want to fly through a scene composed of actual models, we can consult the camera guide.
Now that we have our matrices we can draw the text sprite as a model using the model renderer further explained in the drawing guide:
If we run the program, we should get the following result:
As a last step we will animate our text. We can do this by manipulating our matrices in every frame. As an example we use the sinus of the elapsed time as our scale:
Have fun experimenting and observing the results.
For Windows, Mac and iOS ready-to-use Visual Studio and Xcode projects are provided in the download section. If another IDE should be used or the Basic Render is integrated into an existing project, this guide offers instructions on how to setup the framework on desktop systems as well as iOS.
If we are on Windows or Mac, we can use the external libraries provided as part of the project from the download section. On Linux we first need to compile some of the libraries (GLFW, GLEW and FreeImage are only available as dynamic libraries for Windows and OS X) to be able to include them in our project or we can directly use their source code. Please refer to the documentation of the respective libraries to integrate them into your project:
As soon as we have compiled versions of the external libraries or alternatively their source code, we can get started by creating a project in our favorite IDE and set the paths to the headers of all the libraries we need. The following list is based on Visual Studio and the folder "externalLibraries" in our solution directory. On OS X replace "$(SolutionDir)" with "$(SRCROOT)" and use slashes instead of backslashes.
Next we need to include the compiled dynamic (and static) libraries. In Visual Studio we need to define their directories first (the list is again based on the folder "externalLibraries"):
Now we can define the additional dependencies in Visual Studio:
Or we can do the same in Xcode in the "Link Binary With Libraries" section:
Finally we need to define a few preprocessor macros, which depend on whether we build the FreeType library or include the source code directly. If we include its source code, we define "FT2_BUILD_LIBRARY" on all systems, otherwise on Mac and iOS no macros are needed.
In Visual Studio some libraries could cause warnings (e.g. the vmmlib), we therefore define the following macros:
In Xcode we only need two macros (both for FreeType) yet it is important to remove the "DEBUG" macro as it may cause problems with FreeType:
For FreeType not all source files need to be integrated into the project. Click here for a list of files to include.
Now we are all set and can include the "bRenderer" folder into our project, which contains all headers and sources we need to start using the framework.
To access all the renderer's functionality, we include bRenderer.h:
On iOS we can use built-in libraries provided by Apple. We therefore don't need FreeImage, GLEW and GLFW. This reduces the list of header search paths to:
Next we include the following libraries in the "Link Binary With Libraries" section:
For FreeType we need two preprocessor macros and make sure to remove the "DEBUG" macro.
For FreeType not all source files need to be integrated into the project. Click here for a list of files to include.
As a final step we now drag the "bRenderer" folder into our Xcode project, which contains all headers and sources we need to start using the framework.
To access all the renderer's functionality, we include bRenderer.h:
The "Renderer" class is meant as the main gateway to the framework through which most functionality can be setup and accessed. It maintains one instance of each of the four building blocks of the framework:
To integrate the renderer into our own application, we can either directly create an instance of it and pass static callback functions or we can work in an object-oriented manner and inherit the abstract class "IRenderProject" (recommended). We are then required to implement three callback functions in order to ensure compatibility with the renderer:
An "IRenderProject" automatically holds an instance of the renderer, which may be accessed using the function "bRenderer()". Yet before we can use it, we need to initialize it and optionally define a standard file path (has no effect on iOS) and a configuration file as shown below:
During the initialization phase our initialization function inherited from "IRenderProject" will be called and we may use the object manager to load and create the objects to be drawn later.
Next we need to run the renderer, which starts the render loop:
On iOS we need to take another step to display the renderer's view. In our application's View Controller we can attach the renderer's view with either of the following functions:
Note that we created a function "getProjectRenderer()" as "bRenderer()" is not public.
The Basic Renderer features drawable objects inheriting the abstract class IDrawable. Those objects implement the "draw" and the "drawInstance" Method. If the "draw" function should be used, it is essential to first pass uniforms to the shader of the drawable or use a "Properties" object holding the uniforms.
The "drawInstance" method requires to add an instance to the object first and then pass the shader uniforms to the instance properties. The specific implementation of instancing may differ depending on the object to be drawn. As an example the "Model" class holds a map containing instance properties for every shader used by the model's underlying geometry objects.
The model renderer is one of the four modules offered by the Renderer main class. It is meant to simplify the drawing process and automatically passes uniforms to the shaders of the specified model or model instance. Additional uniforms not covered by the model renderer may be passed by setting the "Properties" of the model.
As illustrated below, a model can either be drawn directly or an instance of it may be stored in the render queue of the model renderer. For both functions there are various settings to be passed such as the lights to be used or whether or not view frustum culling should be performed.
Usually the drawing process is triggered in the "loopFunction" of the render project. The examples below illustrate different ways to draw models and objects inheriting the model class (sprites, text sprites):
As seen in the example, the model name or a pointer to the model may be passed to the "drawModel" and "queueModelInstance" functions. If a name is passed, the model renderer will consult its object manager to obtain the model. Since text sprites are stored separately in the object manager their names can't be used in above functions. To still be able to draw text, we can either use the "drawText" and "queueTextInstance" functions or pass a pointer to the text sprite as shown in the last section of the example code.
The render queue allows for storing and caching draw calls. Such draw calls consist of a pointer to a drawable, a string defining the instance to be rendered and for transparent objects it is even possible to define how the blending factors are computed. When the render queue is drawn, for every draw call it first sets the operation of blending and then calls the "drawInstance" method of the drawable.
The draw calls containing opaque objects are sorted for efficiency by avoiding costly state changes as much as possible. Transparent objects are drawn after opaque ones in a back-to-front order to allow for them to be displayed correctly.
Using the object manager we can either load a model from an OBJ file or create sprites and text sprites. The according functions allow us to pass a custom material or a custom shader. Otherwise the material files to load are read from the OBJ file and created automatically.
If we want to send data to the shader which is not covered by the model's material, we may pass additional "Properties" to the model at any time. Such data may include transformation matrices or light positions.
To create multiple instances of a model, we can use the "addInstance" function. This automatically creates a map of properties for every shader used by the underlying geometry of the model. This map can be obtained using the instance name as the argument of the "getInstanceProperties" function. It is however recommended to always use "addInstance" to request the map as this function automatically checks whether the instance already exists or if it needs to be created.
For every geometry object an axis aligned minimum bounding box is created and may be used for visibility culling or even rudimentary physics simulations. In the model the bounding volumes of all its geometry are merged and can be accessed using "getBoundingBoxObjectSpace".
The "AABB" object of the vmmlib is able to calculate its center and the distance from the center to the maximum vertex at any time. Thus it is possible to work with minimum bounding spheres as well.
Since those two choices might not be precise enough for physics simulations, the geometry objects feature the "getVertexData" function to get a pointer to their vertices and the "getNumVertices" function to allow for looping through them.
To display text, we need to first load a font from a file and then create a text sprite as shown in the example below:
Since the fonts are loaded by FreeType, please consult the official homepage of the library for more information about supported file formats.
Draw the text using the "drawText" and "queueTextInstance" functions of the model renderer, which is introduced in the drawing section.
The Basic Renderer is based on the programmable pipeline and thus relies on shaders to draw its objects. The data necessary to compile the shader programs may be either generated by the framework or loaded from custom shader files (recommended).
Shader files can be loaded using the "loadShaderFile" function of the object manager. Alternatively the "loadObjMaterial" function allows for specifying the shader to be loaded for a material. In addition the "loadObjModel" function may receive a boolean which determines whether to load the shader from file or to generate it. In this case the shader name needs to match the material name. If a model features multiple materials, a shader will be loaded for each of them.
To ensure compatibility to all supported platforms, it is recommended to use shader version 1.0 for OpenGL ES 2.0, which roughly corresponds to version 1.20 on desktop systems. Since the version needs to be specified in the file, the Basic Renderer offers a macro that is replaced with the correct shader version after loading. The head of every shader file should therefore consist of the following lines:
The precision can of course be chosen freely between "highp", "mediump" and "lowp" and the macro can be changed in the configuration file.
You may optionally define the shader versions replacing the macro in the object manager:
It is recommended to use the uniform and attribute names in the shader defined in the configurations. This ensures compatibility with the model renderer and the shaders constructed by the shader generator.
Simple shaders based on Phong interpolation can be generated to quickly experiment with different parameters or to speed up development of large applications. However the generator is not capable of advanced effects such as shadow mapping, reflections (using e.g. a cube map) or even post-processing effects like blur, bloom or color correction.
To generate a shader we have two options based on either custom settings or material data. For the first option we can use the "generateShader" function of the object manager:
The second option is used if in "loadObjModel" or in the function "createMaterialShaderCombination" the boolean "shaderFromFile" is set to false. In this case the shader generator will analyze the material data and construct a shader that fits the material's characteristics.
A material in the Basic Renderer holds shader uniforms and a pointer to a shader to define the look of a drawable object. It can be either created as an empty container to set custom values or can be loaded from an OBJ material file.
It is recommended to use the uniform names defined in the configurations. This ensures compatibility with the model renderer and the shaders constructed by the shader generator.
Some 3D applications, such as Blender, generate materials when exporting OBJ models, others including Cinema 4D do not. Therefore it might become necessary to write custom materials. A good source on how to write and adjust material files can be found on http://paulbourke.net.
However the Basic Renderer does not recognize all of the features an OBJ material would usually support. The following list shows the supported keys:
Textures can be loaded or created using the object manager. When creating a material from material data (which by default happens when loading an OBJ material), its textures are loaded automatically and can be accessed in the object manager.
If an empty texture holding no image data is desired, e.g. to attach it to a framebuffer, it can be created as shown below:
A cube map consists of six textures arranged in the shape of a cube. It allows for projecting the environment onto the sides of the cube and may therefore be used for reflections.
In the Basic Renderer a cube map can be loaded from files or created either based on a vector of six texture data objects or custom image data (allows for specifying no data for empty cube maps). For real-time reflections the cube map may be attached to a framebuffer as shown below:
Please note that cube maps must use square sizes. If used together with a framebuffer, it is therefore important to set the viewport's width and height to the same value.
Depth maps are used for a multitude of effects such as shadow mapping and simulating shallow depth of field. Just as cube maps they can be created in the object manager and attached to framebuffers for real-time effects. An example is shown below:
A custom framebuffer object allows to draw to non-default framebuffer locations and offers the possibility to attach textures. It is therefore possible to render a scene into a texture, one of the six faces of a cube map or to store the scene's depth information in a depth map. Such functionality is essential for post-processing effects. The aforementioned textures may be passed to shaders to be processed and drawn to either the default or another user defined framebuffer to accumulate multiple effects.
The framebuffer of the Basic Renderer is able to automatically adjust itself and an attached texture to the size of the viewport. If this functionality is not desired, it can be turned off by passing a fixed width and height when creating it in the object manager or later using the "resize" function of the framebuffer class.
When binding the framebuffer, the current framebuffer can be preserved by setting "preserveCurrentFramebuffer" to true. This buffer will then automatically be bound when unbinding the custom framebuffer. Otherwise we can use the static function "getCurrentFramebuffer" to get the framebuffer currently bound and then pass it to the "unbind" function of our custom framebuffer.
Sample code on how to bind a framebuffer and draw to a specified texture can be found in the "Textures" guide.
The camera object of the Basic Renderer simplifies the creation of the view and projection matrices for a model to be drawn. It can be rotated around all three of its axes by an arbitrary amount, which sets it apart from an ordinary "look at" method. The latter is still provided as a static function if needed. The class additionally allows for moving the camera upwards, sidewards, forwards and backwards at a freely selectable speed and at any time the field of view and aspect ratio can be set. The aspect ratio should be updated every frame as the resolution of the view may have changed. It can be obtained from the view using the "getAspectRatio" function.
To position objects relative to the camera, the inverse view matrix and the forward, right and up vector can be obtained. If an object should always face towards the camera yet not follow its position, its model matrix can be multiplied with the inverse rotation matrix of the camera. Since in some LOD techniques objects are replaced by sprites if they are far away, the camera offers querying the inverse rotation matrix for only one axis. Otherwise an object could rotate in an unnatural manner, as for example a tree would suddenly be uprooted when tilting the camera.
The example below shows how to create a camera using the object manager:
The Basic Renderer features dynamic lighting based on a simple light class. It allows for defining a point light by setting its position, color, intensity, attenuation and radius. It is possible to specify the values for diffuse and specular colors separately to for example intensify or soften reflections produced by the light.
Files, such as textures, fonts or OBJ models, can be loaded using the object manager. However for the files to be found we need to include them into our Xcode project on iOS (we just drag and drop them in) or set the file path on desktop systems.
By default, the file path is "data/" relative to the applications location. We can change that invoking the following function before loading the first file:
Alternatively we can set the location in the configuration file, which allows for changes even after the application was compiled:
For this to work the JSON file needs to always be placed in the "data/" folder.
The Basic Renderer features a multitude of fully configurable default values collected in the "Configuration" header and cpp-file for quick access. Those values include the string tags of the four log modes of the Logger, default settings for view creation (width, height and window title), default shader versions and the according macro to set in the shader files, as well as a pool of predefined shader uniforms. Moreover all keys to be read from OBJ .mtl-files are accessible and adjustable.
An example of how to specify custom configurations is listed below. The key to be set corresponds to the function name used to access the value in the framework. Even though they are not part of the official specifications of JSON, c-style comments are enabled as they may be helpful to explain the choice of a specific setting when working in a collaborative environment.
