Table of Contents
Umbra is a third party visibility library produced by Umbra Software Ltd (www.umbra.fi). Umbra is not provided as part of the BigWorld Technology license and needs to be licensed separately if required.
Umbra uses graphics hardware to determine what parts of the scene are visible. Any opaque object that writes to the depth buffer can be used as an occluder and any chunk item with a bounding box can potentially be occluded.
To enable Umbra, the preprocessor definition UMBRA_ENABLE needs to be set to 1 in umbra_config.hpp in the chunk library (src/lib/chunk/umbra_config.hpp).
You will also need to add the Umbra include and library paths to your projects.
To link against the Umbra debug library, change the #pragma
comment(lib, "umbra.lib") in the file
(src/lib/chunk/chunk_umbra.cpp).
Umbra can run in two different modes: Hardware and Software.
The engine will choose to use hardware mode when hardware occlusion queries are supported.
In hardware mode, Umbra uses the z-buffer for occluding objects, this means that any opaque object that is rendered in the scene can occlude objects that are further away.
In hardware mode only 2 umbra cells are created, one for inside objects and one for outside objects, both cells exist in world space and are connected by umbra portals.
The BigWorld Client will chose to use Umbra in software mode when hardware occlusion queries are not supported.
In software mode only objects specified as occluders can occlude other objects. By default only terrain occludes geometry, additional static models can be set manually as occluders in Model Editor (for details, see the document Content Tools Reference Guide's section Model Editor → Panel summary → Object Properties panel). All chunk items with a physical size can be occluded by Umbra. Please refer to the Umbra reference documentation for descriptions of Umbra-related objects.
In software mode chunks correspond fairly well to Umbra cells. Each indoor chunk has a corresponding Umbra cell, which is connected to other Umbra cells by Umbra portals. All outdoor chunks share one common Umbra cell, which is owned by the chunk space. All cells exist in world space.
When using Umbra to render the scene, every ChunkItem needs to have a corresponding Umbra object. The chunk item is set as the Umbra object's user data, so that when an Umbra object is deemed visible, its chunk item can be retrieved and rendered.
When implementing a specialised chunk item, you will need to add a Umbra object for it. The chunk item contains a UmbraObjectProxy and a UmbraModelProxy, which can store the Umbra object and Umbra model for the specialised chunk item. The object-to-cell matrix is the world transform of the object.
To ease handling of Umbra objects, BigWorld Technology provides proxy objects for Umbra objects (class UmbraObjectProxy) and Umbra models (class UmbraModelProxy). These objects are a thin wrapper around the corresponding Umbra objects, allowing BigWorld Technology to use standard smart pointers to reference them.
The proxies are also stored in a managed list, to ensure that all Umbra objects are destructed before Umbra is shut down. For details on these classes, see the C++ API documentation.