This is the documentation for Enlighten.

Debug the low level runtime

Owned by William Joseph
Sept 07, 2020
2 min read

Overview

GeoRadiosity provides a number of visualisation services that you may wish to integrate into your engine. Until then, you can load scenes that you export via the HLBS into GeoRadiosity to test what they look like. By saving some of the critical runtime data (from your game) to disk, you can also use GeoRadiosity to check that your integration code is working as expected, and use more of the GeoRadiosity debugging features.

Validity checks

All pointers are checked upon entry to the API functions to ensure that NULL, invalid or corrupt data is detected as soon as possible. If you wish to check these objects yourself at an earlier point (post-load for example) the IsValid() functions are visible to your code in EnlightenDebugging.h. There are overloads available for all the API objects that may be loaded into memory. You may optionally specify a text string to be included in the error log should the function fail.

Data generation

Since these data objects are part of your engine integration, there is no simple stage to run that will save the data out. Instead, each of the objects that can be visualised has read and write methods available in EnlightenUtils. In order to load these files easily in GeoRadiosity, use the filename generation functions in GeoEn2Support/SceneDesc.cpp. These filenames will point to locations within the debugging subfolder of the __Build_XXX__ folder of the given scene.

Debugging objects

The critical runtime objects required for debugging are:

InputLightingBuffer
bool GEO_CALL WriteInputLightingBuffer(const Enlighten::InputLightingBuffer* inputLightingBuffer, Geo::IGeoStream& stream);
bool GEO_CALL WriteInputLightingBufferToFile(const Enlighten::InputLightingBuffer* inputLightingBuffer, const Geo::c16* filename);

Geo::GeoFileString BuildDebugInputLightingBufferFilename(Geo::s32 systemIdx, Geo::ePlatform platform) const;

An input lighting buffer holds the lighting values from the write/end input lighting stages. Loading this into GeoRadiosity and getting the correct lighting proves that this stage of your integration is correct.

RadIrradianceTask
bool WriteRadIrradianceTaskOutput(const RadIrradianceTask* task, Geo::IGeoStream& stream);
bool WriteRadIrradianceTaskOutputToFile(const RadIrradianceTask* task, const Geo::c16* filename);

Geo::GeoFileString BuildDebugRadTaskFilename(Geo::s32 systemIdx, Geo::ePlatform platform, Enlighten::eRadTaskDump radTaskType) const;

The irradiance task depends on the input lighting to be correct, so perform the input lighting check first. Loading this data into GeoRadiosity and getting the correct lighting proves that the irradiance solver is generating the correct values in your integration.

RadProbeTask
bool GEO_CALL WriteRadProbeSetCore(const Enlighten::RadProbeSetCore* probeSet, Geo::IGeoStream& stream);
bool GEO_CALL WriteRadProbeSetCoreToFile(const Enlighten::RadProbeSetCore* probeSet, const Geo::c16* filename);

Geo::GeoFileString BuildDebugProbeTaskFilename(Geo::s32 probeSetIdx, Geo::ePlatform platform) const;

The rad probe task should be saved out when debugging dynamic or other probe lit objects. Visualisation of this in GeoRadiosity requires activating the Rendering > ProbeSets option.

For more information, see the Debugging Utilities module in the API reference documentation.