Building with the HLBS

GeoPrecompute is a build system that is composed of a number of build targets, connected by dependencies. This simple structure describes a directed graph that allows the controlling logic to run each of the precompute steps in turn in order to create the output. GeoPrecompMonitor is an Enlighten application that runs GeoPrecompute internally and constructs a graphical representation of the steps as they run. Both applications share the same command line arguments; you can treat GeoPrecompMonitor as the interactive application and GeoPrecompute as the automation interface.

There are three main top level targets: Precompute, ExtractScene, and MeshConversion.

Precompute example

    GeoPrecompute.exe /t:Precompute /p:InputScene="<path>\ubox\ubox.scene"

The Precompute task runs a number of sub-targets, starting by examining the content of the .scene file and from that working out all the steps required to build the final runtime data. For complete details of the Precompute stages, refer to the Precompute API documentation. For each stage, the incoming data is parsed and, if necessary, converted into IPrecomp* objects. As the tasks progress, intermediate and final output files are created in the __Build_ubox__ folder, using the structure explained in Defining a scene for the HLBS.

Incremental builds

GeoPrecompute attempts to execute as few actions as necessary to produce the requested output. If only part of the scene changes since the last run (based on last-modified timestamps), then GeoPrecompute repeats only the actions requiring those files and their dependencies.

Because this behaviour depends on the timestamps of included files, files that are optional and only implicitly included (such as .mats files, which are not explicitly referred to by an XML attribute), do not trigger a rebuild when deleted.

In rare cases, the incremental build may fail when the precompute process previously crashed or was killed during the build.

To force a full rebuild, either delete the __Build_<scene>__ directory, or pass the command-line option /t:ForcePrecompute to GeoPrecompute or GeoPrecompMonitor.

Console and File Logging

The GeoPrecompMonitor application has a fixed console log level which determines the text in the Log tab. The GeoPrecompute application has controllable logging output. Both applications can be logged to a file for later validation and reporting, using a different verbosity if required. These options are set with:

    GeoPrecompute.exe <other options> /v:<verbosity_level> /fl /flp:LogFile=<path_to_log_file>;Verbosity=<verbosity_level>

/v sets the console verbosity level. /fl enables file logging, and logger properties are set with /flp. The various values for <verbosity_level> are:

Console I/O

By default, the GeoPrecompute application uses coloured output to make errors more visible in an interactive process, and allows the capture of just one stream (stdout). If your build pipeline distinguishes between output and errors by the stream they came in on, you can set GeoPrecompute to use a more simple TTY interface. When this option is set, information messages are output to stdout, and errors are output to stderr.

    GeoPrecompute.exe <other options> /p:UseBasicTty=true

Scene extraction

    GeoPrecompute.exe /t:ExtractScene /p:InputDumpFolder="<path_to_dump>"

If your integration is using the High Level Build System, then you should be able to load your scenes into GeoRadiosity at any time to check that the export is correct and that the precompute results are as expected. If you are using the Low Level Precompute API, you can check your precompute and runtime integrations by instructing the IPrecompute interface to save all incoming data to a dump folder, and then asking GeoRadiosity to generate from that a new .scene and related files. Running a precompute on this new scene file checks that you have provided all the precompute data, and the debugging features of GeoRadiosity will help you work through any runtime or authoring issues.

Mesh conversion

GeoPrecompute.exe /t:MeshConversion /p:InputScene="<path>\ubox\ubox.scene"

This task is run by GeoRadiosity as soon as the scene is loaded. It does the work of converting the intermediate file formats into runtime data for the application. BasicRadiosity does not need to do this because the assets are already in runtime format. When you integrate the HLBS into your own tool-chain you do not need this step.
 

Lightmap UV generation

The tasks in the lightmap UV pipeline are run using either the MeshConversion or Precompute build targets. The output from these tasks are placed in the following folders:

In any case, the Processed files are read by the CreateInputGeometry stage of the Precompute target.