Monitoring Jobs and Retrieving Updates

When you launch a job by calling ILBStartJob(), you can interact with the job at any time to track its current progress and status, and to process any updates sent by eRnsT.

The type of activities you will need to carry out typically depend on the type of rendering job you are running:

For standard rendering jobs, you need to wait until the job is done before you retrieve the output data it generates. You can simply wait until the job is finished (see Monitoring Jobs and Retrieving Updates), or you can poll the job periodically to determine its current progress (see Monitoring Jobs and Retrieving Updates). When the job indicates that it has completed (see Monitoring Jobs and Retrieving Updates), and the result of the job indicates that the rendering was successful (see Monitoring Jobs and Retrieving Updates), the output data is ready for retrieval.
For eRnsT and live eRnsT sessions, the rendering job will also deliver periodic updates while it runs, which you should respond to in your code. Typically your code either waits passively until a new update is available (see Monitoring Jobs and Retrieving Updates), or it polls the job regularly to retrieve the most recent update (see Monitoring Jobs and Retrieving Updates). When an update is available, your code needs to retrieve it and handle it appropriately. See Monitoring Jobs and Retrieving Updates.

Retrieving job progress

You can query a standard baking job at any time to determine what phase of the rendering job is currently being executed, and the approximate percentage of that phase that has been completed. To query for progress, call the ILBGetJobProgress() function.

This is typically done in a loop as follows:

Periodically, call ILBJobHasNewProgress() to determine whether or not a new rendering phase has been started, and whether or not the completion percentage has been updated, since the last call to ILBGetJobProgress().
If ILBJobHasNewProgress() indicates that the current activity or completion percentage has been updated since the last call to ILBGetJobProgress(), call ILBGetJobProgress() again to retrieve the new values.

For example:

ILBBool newProgress;
ILBBool newActivity;
ILBJobHasNewProgress(job, &newActivity, &newProgress);
if (newProgress) {
    ILBStringHandle taskName;
    int32 progress;
    ILBGetJobProgress(job, &taskName, &progress);
    // Handle the progress update here
}

Note that you cannot query the progress of a standalone eRnsT job or a live eRnsT job.

Querying current status

You can determine whether or not a rendering job is currently in progress by calling ILBIsJobRunning().

You can determine whether or not a rendering job is done by calling ILBIsJobCompleted().

Waiting for updates

You can call ILBWaitJobDone() at any time to pause the execution flow of a thread until a rendering job has an update.

For simple rendering jobs, the only update is at the end of the job, so this function effectively waits until the job is completed.

For eRnsT and live eRnsT jobs, this function pauses until a new update is available.

Processing eRnsT updates

When you run an eRnsT job in the standalone eRnsT viewer, or a live eRnsT job in your level editor, the rendering job will periodically provide you with updates. Depending on the type of rendering job, these updates will contain different kinds of information and need to be processed in different ways:

For standalone eRnsT jobs, each update will indicate a change that the user makes in the eRnsT viewer. This may be a change to the objects contained in the scene (adding, modifying or deleting a light source), the camera position, or the Beast configuration parameters for the scene or for target entities. Depending on the change, you may need to reflect the change in your own game level, such as by modifying the lights in the level.
For live eRnsT jobs, each update will indicate that a target has newly rendered output data available in a new framebuffer or vertexbuffer, or that the previously rendered information for a target is now invalidated. You are responsible for updating your level editor to reflect the new lighting data.

For both types of jobs, the general procedure to retrieve the update is the same:

Create a new ILBBool and a new ILBJobUpdateHandle, and pass them in a call to ILBGetJobUpdate(). Your ILBBool is updated to indicate whether or not an update has occurred in the eRnsT interface. If it evaluates to true, the ILBJobUpdateHandle is updated with details about the change.
To find out what kind of change was made, create a new ILBUpdateType and pass it with your ILBJobUpdateHandle in a call to ILBGetJobUpdateType().
The ILBGetJobUpdateType() function updates your ILBUpdateType to an element from the ILBUpdateType enumeration that indicates the kind of change made. Depending on the value assigned to your ILBUpdateType, you will need to make different kinds of changes:
Standalone eRnsT jobs can produce the following types of updates:
- ILB_UT_NEW_LIGHTSOURCE, ILB_UT_UPDATE_LIGHTSOURCE or ILB_UT_DELETE_LIGHTSOURCE: The user has added, modified or removed a light source. You can call ILBGetUpdateLightSource() to retrieve a handle on the new, modified or deleted light source. The beastlightsource.h file offers several additional ILBGet...() functions for accessing the properties in this handle so that you can update your level accordingly.
- ILB_UT_SCENE_INFO: The user has modified a global property of the scene. In this case, you can call ILBGetUpdateLightSource() to retrieve a handle that contains the new settings. The beastscene.h file offers additional ILBGet...() functions for accessing the properties in this handle, so that you can update your level accordingly if necessary.
- ILB_UT_UPDATE_CAMERA: The user has moved the camera to a different position or rotated it to a different orientation. In this case, you can call ILBGetUpdateCamera() to retrieve a handle that contains the new settings. The beastcamera.h file offers additional ILBGet...() functions for accessing the properties in this handle, so that you can update your level accordingly if necessary.
- ILB_UT_UPDATE_TARGET: The user has changed the way the lighting information for a shape instance is baked to a texture or vertices. In this case, you can call ILBGetUpdateTargetEntity() to retrieve a handle on the target that contains the new settings. The beasttargetentity.h file offers additional ILBGet...() functions for accessing the properties in this handle, so that you can update the instance properties in your level accordingly.
Live eRnst jobs can produce the following types of updates:
- ILB_UT_UPDATE_CAMERA_FRAME_BUFFER, ILB_UT_UPDATE_TEXTURE, and ILB_UT_UPDATE_VERTEX: Indicates that a newly rendered framebuffer is available for one of the targets being treated by the rendering job. You can retrieve the updated framebuffer by calling ILBGetUpdateFramebuffer(). If the framebuffer comes from a texture target or vertex target, you can retrieve the target and target entity that it corresponds to by calling ILBGetFramebufferTarget() and ILBGetFramebufferTargetEntity(). For information on reading the output data from the framebuffer, see Retrieving the Rendered Output.
- ILB_UT_INVALIDATE_FRAMEBUFFER: Indicates that the baked data for a target is no longer up-to-date, due to changes in the lighting setup for your scene. You can retrieve the target entity whose data in invalid by calling ILBGetUpdateInvalidateFramebuffer().
When you are done handling the update, destroy the update by calling ILBDestroyUpdate(). NOTE: do not destroy the frame buffer handle; destroying the update will release the frame buffer.
As long as the eRnsT job is still running, repeat these steps in a loop. When a call to ILBIsJobRunning() indicates that the eRnsT job has been finished, you can exit the loop.

Evaluating the final job results

After a render job has been completed, you can call ILBGetJobResult() to retrieve an element from the ILBJobStatus enumeration that indicates whether the job was completed successfully, or what type of error occurred during the processing.