About XEngine

Home About XEngine Engine API SceneGraph Changelog Programming Guide

Introduction

XEngine is a C++ scene graph-based deferred rendering API that was initially implemented as standalone engine and a research platform for testing various real-time algorithms for shading and illumination effects using OpenGL. The engine is provided as a DLL (32/64bit, Debug and Release versions) with an ANSI C API for higher compatibility with different compilers. The engine is provided "as is", without its source code, and remains a property of the AUEB Graphics Group, under MIT license.

The API is split in two core parts, the engine API and a scenegraph API: The Engine API is responsible for various core engine tasks, such as management of the graphics engine main event loop, file utilities, logging system, timing and the internal rendering pipeline.

The SceneGraph API incorporates an extensible scene graph library that is responsible for the engine's scene management. It has been designed to work alongside the engine's deferred renderer in order to provide a generic scene description. Due to the restrictions that apply to the ANSI C interface of the engine, scene graph node extension is not exposed in the provided API. The graph can be also accessed by an external XML scene file description, with the use of the SceneGraph's Scene Description Language.

XEngine is accompanied by an example that demonstrates how the API is integrated onto a simple program. The example uses FreeGLUT for the window management and the input handling (such as mouse, joystick and keyboard functions).

Please keep in mind that this is an undergoing project still in its early stages and more advanced features will be added with each new version. See the Changelog for the latest changes.

Disclaimer and Licensing

XEngine is free software; you can redistribute it and/or modify it under the terms of the MIT License.

The MIT License (MIT)

Copyright (C) 2013 The AUEB Computer Graphics Group

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Dependencies and Third-Party Libraries

XEngine uses the Open GL Extensions Wrangler library (GLEW), the FreeImage image I/O and manipulation library, the TinyXML-2 XML parsing source code and the OpenGL Mathematics (GLM) template library. All necessary libraries for XEngine to function are included or statically linked into our DLLs and all appropriate license notifications are provided along with the distributable.

GLEW (http://glew.sourceforge.net/) is originally derived from the EXTGL project by Lev Povalahev. The source code is licensed under the Modified BSD License, the Mesa 3-D License (MIT License), and the Khronos License (MIT License). The automatic code generation scripts are released under the GNU GPL and constitute no part of the final library that we incorporate in our code. The GLM (http://glm.g-truc.net/index.html) source code is licensed under the MIT license. The FreeImage open source image library (http://freeimage.sourceforge.net/) is used under the FIPL license. TinyXML-2 (http://www.grinninglizard.com/tinyxml2/) is used under the zlib license.

Compatibility and Requirements

The XEngine external API is written in ANSI C, for maximum portability and is available in 32-bit and 64-bit binaries. It Requires full OpenGL 3.3 support or higher for rendering and full support of the GLSL 3.30.6 shading language specification. OpenGL 3.3 is fully supported by the majority of graphics cards released in the last 8 years.

The current version is released for Windows only and the DLLs were built using Visual Studio 2010.

Engine API

The Engine API is responsible for various core engine tasks, such as management of the graphics engine main event loop, file utilities, logging system, timing and the internal rendering pipeline. The internal engine consists of several independent libraries such as:

In deferred rendering, the generation of fragments from the raw geometric data being rasterized is decoupled from the lighting and color calculations of the final image fragments. To this end, all raw data that are necessary for the calculations are recorded in a set of primary buffers by using the technique of rendering to multiple render targets (MRTs). Then, all calculations are performed in screen space, disassociating the scene complexity from the image generation processing time. The benefits of such a system are focused on the ability to visualize large sets of complex geometry with potentially heavy overdraw (depth complexity), without wasting lighting calculations for invisible parts of the geometry. Complex lighting effects can be achieve both due to the bounded shading operations (in screen space) and the ability to randomly access data of other pixels in the framebuffer and the MRTs.

The Engine API is split onto several smaller API's, each one responsible for a specific task:

SceneGraph

The SceneGraph incorporates the SceneGraph library, an extensible library for scene graph support where the scene description is provided either as an XML file or in terms of a C API, by providing explicit function calls to the SceneGraph API. The scene description schema provides declarations for basic elements such as geometry, transformations and groups, but also an event-driven message passing mechanism to trigger functions and alter states and properties of nodes at run time.

One feature central to the design of the particular scene graph is the disassociation of the user, the camera and the input control entities. In fact, an arbitrary number of users, cameras and input control nodes can populate a scene, each one connected to the others in any combination. This provides an easy way to model a multi-user environment, where the user entities can be controller by humans (via input device nodes) or automata, which can be controlled by a behavioral animation controller. Switching among these options is simply done by assigning a different controller to each user on the fly with the corresponding message. The same mechanism goes for the camera nodes as well, which can follow any node or be left standing alone.

Events and Messages

Almost every node type in the scene graph triggers events, which signify a change in its state. For instance, a proximity trigger produces an enter and an exit event when at least one of a number of predefined nodes enters or leaves its area of effect, respectively, and the root of the scene graph (the "world") triggers an init event when the world is parsed and ready for display. In order to use the occuring events for dynamically altering the behavior or state of the scene, the scene graph supports event messages. The corresponding <eventmessage> XML tag can be placed inside any other node declaration and provides the association between an event type, another named node, which is going to receive the message (the recipient) and the command message to deliver. Messages contain instructions or attributes for redefining the look or behavior of the target node. For instance, the message text for a light source could contain the command "color 1.0, 0.95, 0.8" that changes the light color to the given rgb values. Multiple messages can be issued to a node by repeating the assignment of an event type to a new message.

Node Names and IDs

In the scene description language (XML scene file), to access a node for posting a message or using it as an attribute to another node (common when "attaching" a node to another, as is the case with the camera) one must reference the node by its name. A special name is reserved for the root of the scene graph, namely the "%root", as well as for automatically generated nodes, if one is not given. Names, node types and attributes are all case sensitive. Conversely, in the XEngine API, nodes are generaly identified by their unique ID. Every time a new node is generated, the API returns an ID for this entity, which can be subsequently used to reference the corresponding scene graph node for any operation, including posting a message to it.

Node APIs

The SceneGraph API is split onto several smaller API's, one for each node type and a generic one for generic node handling:

Using XEngine

XEngine is available as a Dynamic Linking Library (DLL). All functions are exported according to the ANSI C specification in order to increase compatibility between different compilers. Standard naming conventions for both the naming of the binaries as well as the function names have been used in order to increase readability and reduce the effort to understand source code.

The Bin folder contains the XEngine DLLs, each one located in its respective folder. The naming convention used is XEngine%plarform%%configuration%. So the folder XEngine64Debug contains the debug version of the 64-bit DLL.

The GlobalIncludes folder contains all the necessary header files for XEngine. The XEngineFunctions.h file contains all the API functions.

To add XEngine in your project:

1) Add the GlobalIncludes folder to the project's include paths and add the three main header files: XEngineDefinitions.h, XEngineFunctions.h and XEngineIncludes.h into your main header file (for example, a precompiled header).

2) Add the appropriate DLL to the library paths of your project

It is suggested that you have a look at the XEngine_GLUT VS2010 project, which shows a complete example of how XEngine works with FreeGLUT and how the basic function calls are being used.

The naming convention for all function names is XE_%api_name%_%function_name%. All mutator functions have their accessor counterparts, with the difference that the accessor function parameters always pass variables by reference or by pointer, in order to be able to return the result. This means that usually there is no return type, with only a few exceptions.

For example, XE_settings_set_ambient_color means that this XEngine function belongs to Settings API and sets the ambient color.

The exact function is void XE_settings_set_ambient_color(float x, float y, float z). The accessor for this function is void XE_settings_get_ambient_color(float& x, float& y, float& z);

 

Current Features

XEngine currently supports the following features:

  • Fully customizable, hierarchical scene graph, which provides a flexible scene management
  • Dynamic node loading/unloading with node caching
  • Point lights such as Spot lights, Omni and Directional lights
  • Loading of static geometry using .obj format
  • Dynamic rendering of primitive data, such as triangles-lines-points, similar to the OpenGL fixed-function immediate mode rendering pipeline.
  • Ambient occlusion (SSAO, HBAO, Alchemy AO, VO as well as MVAO (Multi-view Ambient Occlusion) - see figure
  • Shadows using shadow maps for point lights or cascaded shadow Maps for directional lights with 16-tap variable bias PCF
  • Real-time scalable frame buffer resolution
  • Run-time reconfigurable shaders to minimize overhead when switching on/off various features
  • Built-in lights, textures and mesh management
  • Individual internal buffer preview
  • Extensive logging and hardware analyzer
  • Memory leak detection
  • Available in 32-bit and 64-bit
  • Ready-made light rigs for easy incorporation in simple projects (skylight and portrait lighting configurations). They can both follow the user or be fixed.

For a complete list of all Engine API functions, please refer to the Engine API document.

For a complete list of supported node types, their attributes, events and messages that are recognised, please refer to the SceneGraph API reference document.



Kostas Vardis, Georgios Papaioannou, 31 May. 2013