This is the documentation for Enlighten.

Libraries

The Enlighten distribution is a collection of libraries, some of which may not be required for your application. In particular, libraries that we expect to be linked into the final game have very minimal dependencies and do not depend on any precompute libraries. The precompute libraries necessarily have a wider set of dependencies and reference some third party libraries, such as Intel TBB, where they provide a clear performance benefit. The precompute libraries can be linked in much the same way as the runtime libraries, but their API design also allows them to be encapsulated into an executable and driven as a separate process. The High Level Build System provided as part of Enlighten takes this approach and encapsulates the precompute into the GeoPrecomp2 and GeoConvert tool applications.

All Enlighten libraries necessarily depend on the CRT library provided by the compiler. In order to be compatible with as many build configurations as possible we provide variations of each library to cover different CRT configurations, including different versions of Visual Studio and different CRT linkages.

Distribution layout

The code in the Enlighten distribution can be split into two categories:

  • API code that is provided to you as pre-compiled libraries, headers, and sometimes source code for reference.
  • Sample Framework code that is provided as source.

All the code (headers, libs and source) for the first category can be found under the Src\EnlightenAPI folder in the distribution. The remaining sample framework code is in the Src\Samples folder. The applications themselves are all pre-built and can be found under the Bin folder.

If a library is shipped with source, you will find both the source and headers under a LibSrc directory. If it is shipped without source, the headers are inside the Include folder. Precompiled libraries are always under the Libs folder. For the common case of adding the runtime libraries to a project you should therefore link again the appropriate libraries from the Libs folder and include the headers from both the Include and LibSrc folders.

Core libraries

Common functionality for both the runtime and the precompute.

Library name

Source

Description

GeoBase

(tick)

Low level cross-platform library

GeoCore

(tick)

Common classes for maths, containers, I/O and more

GeoBase is the top of Enlighten's library dependency graph and all other libraries depend on it. Most but not all libraries depend on GeoCore. You must link these libraries to your applications when linking to Enlighten libraries.

The remaining Geo libraries form the Sample Framework used to implement Enlighten sample applications.

Runtime libraries

Include the runtime libraries in your final executable to enable Enlighten runtime functionality.

Library name

Source

Description

Enlighten

(tick)

Required for real time radiosity updates using the low level runtime API

EnlightenHLRT + EnlightenPPPI

(tick)

Required for the high level runtime functionality

Precompute libraries

The precompute libraries are available for Windows, OS X and Linux only, with the 32- and 64-bit versions producing identical output. Your final executable should not require any of these libraries, though you are free to link them into distributed code if you wish.

Precompute library

Source

Description

EnlightenPipeline

(tick)

High level API to drive the precompute pipeline

EnlightenPrecomp2

(error)

The Low Level Precompute API implementation.

GeoRayTrace

(tick)

A CPU raytracer used in the precompute

Third-party libraries

These are required to build with either the runtime, precompute or both.

3rd party library

Description

Zlib

The zlib compression library, used in the High Level Build System when saving out intermediate files

Intel TBB

The Intel Threaded Building Blocks library, used in the Precompute (and optionally in the Windows runtime) to implement multi-threading

XML

The TinyXPath library, used to read and write XML files in the High Level Build System

Tool libraries

The source code in the Samples directory allows you to rebuild the GeoRadiosity debugging tool. You can use this code for reference, but we do not recommend that you include these libraries in your engine.

Code conventions

It's useful to be aware of a few conventions used by the Enlighten libraries:

  • Core library code (GeoBase, GeoCore) exists in the Geo namespace. All non-sample runtime and precompute Enlighten code is in Enlighten.
  • The Enlighten3 library (the low level runtime library) does not allocate memory internally or perform any file IO, and encapsulates state in opaque API objects under user control. Functions that would require these operations (such as serialisation) live in the EnlightenUtils.inl header which is shipped as source for you to re-implement or use as-is in your own engine.
  • All code includes GeoBase\GeoBase.h as the first file. This sets the majority of all compiler and platform specific settings and declares the basic typedefs.
  • We do not use STL containers in Enlighten, but do use algorithmic content such as <algorithm>. All STL includes are made centrally by including GeoBase\GeoStl.h.
  • Similar include conventions exist for GeoLanguageDefs.h (additional CRT includes) and GeoWinDefs.h (including Windows or pseudo-Windows headers).
  • In order to support differing default function call conventions all non-member functions are prefixed with GEO_CALL to explicitly set the calling convention.
  • In order to support differing default class and structure packing conventions our headers are wrapped in #pragma pack(push,16) to explicitly set the packing.
  • All memory allocations are made through GeoBase\GeoMemory.h. By default this uses the normal aligned allocator or malloc, but can be overridden by the integration using the MemoryAllocator interface. Providing you have not overridden the default allocator you can obtain a set of memory statistics at runtime through the functions available in GeoMemory.h. This memory system is suitable for use in an integration.
  • All message logging goes through GeoBase\GeoMsgLogger.h. This uses a set of predefined log types and will callback to handler functions as required. New loggers can be attached or removed by an integration.