Using the Cache

As introduced under Initializing and Terminating Beast, most calls to the Beast API are done within the context of a Beast Manager, which handles memory management and object creation tasks. Each Beast Manager stores records of objects such as meshes and textures in a file cache. You may be able to increase the speed of your baking by re-using the meshes and textures from the cache rather than re-creating them from their corresponding game objects each time you render a level.

You can re-use these objects in two ways:

Over successive rendering jobs. For example, the first time you bake lighting for a level in your game, you create Beast representations of all your meshes and textures. If you tweak some configuration parameters and want to re-bake the lighting for the level, the next time you create the Beast scene you can retrieve the meshes and textures generated in the previous run.
Over simultaneous rendering jobs in different threads. If you have different Beast Managers in different threads running jobs in parallel that rely on the same meshes and textures, you can make those Beast Managers share a cache and retrieve those shared objects from the cache.

The contents of your cache can also aid Autodesk support in diagnosing problems or unexpected results that you may encounter when using Beast. You may be asked to provide your cache, so that support engineers can attempt to reproduce your problem using the same set of data.

Setting up cache sharing

In order for a Beast Manager to be able to share meshes and textures that were added to the cache by a different Beast Manager:

Both Beast Managers that you want to share the cache must use the same cache directory.
Both Beast Managers must be set to use the global scope (ILB_CS_GLOBAL).

These values are set when the Beast Manager is created. See the ILBCreateManager() function.

Note that both Beast Managers need to have access to read, write and delete files in the cache directory.

Finding cached objects

You can retrieve an object from the cache by the unique name that you specified at the time the object was created. You can retrieve:

Meshes, by calling ILBFindMesh().
Textures, by calling ILBFindTexture().
Materials, by calling ILBFindMaterial(). Note that materials can only be used within the context of the same scene in which they were initially created, and scenes are not persisted in the cache. Materials therefore cannot be re-used once the scene has been destroyed.

Each of the functions listed above requires you to provide a pointer to a handle of the appropriate type. If an object of the requested type with the specified name is found in the cache, the handle you provide is updated to point to the retrieved object. If no matching object could be found in the cache, the handle is not updated and the function returns ILB_ST_UNKNOWN_OBJECT. Your code should handle this case by re-creating the object from scratch from the corresponding game object.

Invalidating cached objects

All cached objects can be removed (invalidated) by calling ILBClearCache().

If any other resource in the same Beast Manager is currently referring to the object you try to erase (e.g. if a scene contains the texture that you want to erase), your call will fail. However, note that if any object handles exist that already refer to the erased object, those handles will be invalidated. Any further use of those handles will cause undefined behavior.

Updating cached objects

If the source of an object that exists in the cache is changed in your level design tool or game editor, you need to introduce a mechanism to ensure that you do not keep re-using the cached version of the object the next time you render your scene. You can either:

Invalidate the cached object each time the corresponding object in the level editor is changed. Your code that sets up the Beast scene should detect that the object is not available in the cache, and therefore re-create it from the current level content.
Embed a unique ID, revision number or modification timestamp in your game objects, which you retrieve when you create the unique names that you assign to your Beast meshes and textures. Each time you build a Beast scene and look for an object in the cache, you will therefore be guaranteed to retrieve the Beast representation that matches the current version of the game object in the level editor. Using this approach guarantees that you never have a mismatch between the objects in your game level and the objects read from the cache, even if you load earlier versions of the game level into your level editor.