Initializing and Terminating Beast

This page details the preliminary steps that you must carry out in your code in order to begin using the Beast API, and how to release allocated resources when you are finished using the API. All other calls you make to the functions of the Beast API — such as those described under Creating a Scene, Rendering the Scene and Retrieving the Rendered Output — will be done in between the initialization and termination events outlined below.

Initialization

Initializing the Beast API usually involves the following steps.

Specify one or more output locations to which the API will print debug messages, by calling ILBSetLogTarget(). For additional information, see Debugging.
Initialize a Beast Manager handle. This Beast Manager will be responsible for allocating and maintaining memory resources as you work with the Beast API. It acts as a factory for most other types used in the API, and maintains a cache on disk for the objects it manages.
To initialize the Beast Manager, create a new ILBManagerHandle and set it up through a call to ILBCreateManager().
As described under System Overview, the Beast API will invoke other executables to carry out rendering jobs, and you need to provide it with access to these executables. If you choose to set the location of these executables programmatically, call ILBSetBeastPath() in your initialization code.
It is usually good practice to clear the disk cache by calling ILBClearCache(), unless you intend to re-use the data that already exists in the cache. See also Using the Cache.

// Send errors to stderr and info to stdout.
ILBSetLogTarget(ILB_LT_ERROR, ILB_LS_STDERR, 0);
ILBSetLogTarget(ILB_LT_INFO, ILB_LS_NULL, 0);

// Initialize the Beast Manager.
ILBManagerHandle bmh;
ILBCreateManager("C:/temp/myProject", ILB_CS_LOCAL,"LICENSE_KEY", &bmh);

// Set the path to the Beast executables.
ILBSetBeastPath(bmh, "../../../bin");

// Clear the disk cache maintained by the Beast Manager.
ILBClearCache(bmh);

Termination

The Beast API does not absolutely require any global termination steps in all cases. However, you may need to carry out some additional steps depending on how you use the API.

If you create your Beast handles on the stack, as is done in the example projects shipped with the SDK, the memory allocated for those handles will simply be freed automatically when the variables pass out of scope.
If you create your handles on the heap, you will have to free the memory yourself.

You can destroy or clear some kinds of handles explicitly if you need to clear the memory they are using at a certain point in your code. For more information, see Working With Object Handles. Note that when the Beast Manager handle passes out of scope or when you destroy it explicitly, all of the handles you initialized through that Manager (such as scenes, light sources, render jobs, etc.) are automatically invalidated. Therefore, destroying the Manager handle is typically the last thing you do through the API.