This is the documentation for Enlighten.

Enlighten SDK 3.10 Release Notes

Owned by William Joseph
Dec 22, 2020

Patches

3.10.P1

  • Added an option in GeoRadiosity to switch between per pixel or per mesh probe lighting.
  • Added documentation for the Sample implementation and the early access Precompute pipeline API.
  • Added the IPrecompute::ExtractOctreeProbeSet function to simplify the usage of the low level precompute API for automatic probe placement.
  • Deprecated IPrecompInputProbeSet::SetOctreeProbePositions: please use IPrecompute::ExtractOctreeProbeSet instead.
  • The Show Scene Report button in the GeoRadiosity Performance tab now correctly opens the scene report when the default browser is Chrome.
  • Fixed a precompute error "<name> has zero total surface area across all target geometry" when both terrain and regular instances are automatically grouped into radiosity systems.
  • CodeBuildTool now supports building with Visual Studio 2019 with toolset version 14.21 or later. The 2019 configuration builds with toolset 14.21. To build with a different toolset, specify the toolset version: e.g. configuration 1421 builds with the 14.21 toolset. By default, Enlighten builds against Windows SDK 10.0.16229. You can override this in the configuration name: e.g. 1421-16229.
  • Enlighten core libraries are now available for Windows and Xbox One compiled with Visual Studio 2017 15.9.2 (VC tools version 14.16)
  • Enlighten libraries are now built with PS4 SDK 7.008 and Switch NDK 9.3.1

New features

New documentation and samples to accelerate your implementation of Enlighten.

  • Added Artist Workflow section to help you provide an effective workflow for artists.
  • Added Implementation Guide section to help you implement the Enlighten pipeline and workflow within your engine.
  • The Sample Pipeline and Sample Runtime applications demonstrate how to implement the core Enlighten functionality.

Simplify implementation of the precompute pipeline in your tools: Enlighten Pipeline library (early access).

Faster precompute for massive worlds. 

  • New probe region object enables simple and efficient implementation of automatic probe placement in a massive world.
  • Group instances, probe regions and cubemaps into zones and limit their radiosity dependencies, to limit the memory usage and time taken by the precompute in a massive world.
  • Group instances by zone to automatically generate radiosity systems during the precompute. 

Improvements

Reduced time spent in AddPppiProbeSet on console platforms when adding many new probe sets

Streamlined high level runtime API

  • Added per pixel probe lighting to the high level runtime.
  • Added a simple method to allocate a system with a single lightmap LOD. Use the AllocateSystem overload which takes a set of output textures.
  • The output textures are now always released on the same thread on which the update manager was created.
  • Don't require a binary search when setting object parameters: Add alternative EnqueueSetObjectParameter implementation which takes a pointer to the object.

Simplified runtime material colour API:

  • Added new functions InitialiseMaterialDynamicity and SetMaterialAlbedoColour, which use a SurfaceSelection instead of a set of GUIDs to identify surfaces within a system.
  • To simplify your implementation, IPrecompInputMesh::AddMaterialGuidMapping is now optional and the guid attribute of the geom, mesh and material elements in a mesh object can be left unspecified.

Visual Studio builds:

  • Added prebuilt binaries compiled with Visual Studio 2017 15.7.1 and MSVC tools version 14.14.26428 for Win32, Win64 and XboxOne
  • CodeBuildTool now supports building with Visual Studio 2017 with MSVC tools version 14.14 or later.
  • Enlighten can now be used in projects compiled with MSVC with the  -std:c++17 option.
  • Enlighten static libraries built with Visual Studio now contain debug information embedded in the .lib files. Separate .pdb files for these libraries are no longer required. This does not affect your ability to debug Enlighten code.

Bug Fixes

  • A buffer provided to BaseSystem::SetAlbedoData is no longer overridden by a subsequent call that leaves the same buffer unspecified.
  • Fixed seams in per pixel probe lighting output that occur only in specific locations in the world.
  • Fixed missing per pixel probe lighting in some areas close to walls.
  • Fixed minor lighting artifacts when using per pixel probe lighting for surfaces exactly aligned with the probe grid.
  • Fixed a divide by zero in Enlighten::EncodeRGBM which caused differences in output between debug and optimized Windows builds.

Deprecated

General:

Core runtime:

  • Use of instance, material and mesh GUIDs in SetMaterialAlbedoColour is deprecated. Please refer to the upgrade notes below.

  • The low level API functions IPrecompSystemDependencies::SaveAsXml and IPrecompSystemDependencies::SaveBodyAsXml are deprecated.

  • SetSamplePositions is deprecated. Please use the precomputed sample positions instead.

  • InputWorkspaceDebugPoint::m_LightValue is deprecated. Please use GetInputLightingBufferLightValue instead.

  • InputWorkspaceDebugPoint::m_Albedo is deprecated. Please use GetDebugAlbedoValue instead.

  • InputWorkspaceDebugPoint::m_AreaLightId is deprecated. Please use GetDebugEmissiveValue instead.

High level build system:

  • The OptimiseScene target of the high level build system is deprecated. We recommend to automatically group instances into radiosity systems during the precompute. Please refer to the upgrade notes below.

  • The Enlighten scene probeOctree element is deprecated. Please refer to the upgrade notes below.

High level runtime:

  • The ILogHandler argument to MultithreadCpuUpdateManager::Create is deprecated. Please refer to the upgrade notes below.
  • IGpuTextureAllocator is deprecated. Please refer to the upgrade notes below.
  • IUpdateManager::IsSystemStatic, IsProbeSetStatic, IsCubeMapStatic are deprecated.
  • The option to use the legacy probe set solver with the high level runtime is deprecated.
  • The useVolumeTexture option in IUpdateManager::EnqueueAddDynamicObject is deprecated. To light large moving meshes, we recommend to use per pixel probe lighting.
  • The REMOVE_UPDATES_AND_INPUT option for IUpdateManager::EnqueueRemoveSystem is deprecated. Please use REMOVE_COMPLETELY instead.

Build configurations:

  • Support for Visual Studio 2013 is marked for future deprecation: please let us know if you need it.
  • Support for Visual Studio 2012 is deprecated. Prebuilt binaries can be provided on request.
  • 32 bit support is deprecated for the following projects, for which prebuilt binaries can be provided on request:
    • Core libraries: EnlightenPrecomp2, EnlightenBake, GeoRayTrace. 
    • Sample framework libraries: GeoLua, GeoUI, OpenExr.
    • Sample framework applications: GeoConvert, GeoPrecompute, GeoPrecompMonitor, GeoPrecomp2, GeoRadiosity, BasicRadiosity2, BasicLightmapBaking.

Removed

  • Forge is no longer included as part of the Sample Framework. We recommend to use the SamplePipeline and SampleRuntime as an example of how to implement Enlighten.
  • Visual Studio 2010 was deprecated in a previous release and is now unsupported. We can no longer provide prebuilt binaries compiled with Visual Studio 2010.

  • The WindowsExtra package now contains only prebuilt binaries for EnlightenPrecomp2, EnlightenBake and GeoRayTrace. If you need to build Checked or Static configurations of the remaining Enlighten libraries, please follow these instructions to compile from source.

  • PlayStation Vita is no longer supported.
  • The Windows Phone and Windows RT platforms are no longer supported.
  • The GroupInstancesIntoSystems function was deprecated in a previous release and has now been removed.
  • BaseProbeSet::GetAndClearUpdated was deprecated in a previous release and has now been removed.

Upgrade notes

Core runtime:

  • If you provide uniform material color data using a material GUID, to update your implementation to use a SurfaceSelection:
    1. As shown in the implementation guide, construct a mapping to associate each surface in the system with a material GUID.
    2. Optionally, remove the guid attribute from the material element in each mesh object, and remove calls to IPrecompInputMesh::AddMaterialGuidMapping.

    3. To provide a uniform color for a given material GUID, call SetMaterialAlbedoColour with the SurfaceSelection for each surface associated with that GUID.

      The SamplePipeline and SampleRuntime projects show how to create material color data for use at runtime

  • The alpha channel of the cubemap output texture now indicates the proportion of light incoming from the emissive environment, only if an emissive environment is provided. A value of zero indicates that all incoming light originated from the emissive environment, and a value of one indicates that all incoming light originated from radiosity systems. In Enlighten 3.09, this occurs only when the emissive environment is not provided. If your implementation uses the alpha channel of the cubemap output texture, you may need to update your implementation to handle this behaviour change.

High level runtime:

  • The high level runtime now uses the entire probe set solver. The entire probe set solver has smaller radiosity data and is significantly faster than the legacy probe solver. To prevent deprecation warnings, leave UpdateManagerProperties::m_UseEntireProbeSetSolver unset.
  • By default, the update manager now performs continuous updates for systems, probe sets and cubemaps. Calls to EnqueueSetAllUpdateCounters with INFINITE_UPDATES are now redundant and can be safely removed to reduce runtime overhead. To revert to the previous behaviour, set UpdateManagerProperties::m_UpdateCounterDefault = 0.
  • The ILogHandler argument to MultithreadCpuUpdateManager::Create is no longer required. To capture output of warnings and errors from the high level runtime, call GeoAttachLogger before you create the update manager.
  • The texture allocator is no longer required. To provide output textures to the high level runtime:
    1. Leave UpdateManagerProperties::m_TextureAllocator unset.
    2. Call GetOutputTextureSize to find the width and height of the output textures for a system.
    3. Call IUpdateManager::AllocateSystem with the result of your previous IGpuTextureAllocator::Create implementation.

    4. Start with the example below, and change the irradiance output format to match IUpdateManagerProperties::m_IrradianceOutputFormat. 

      Enlighten::IGpuTexture* outputTextures[Enlighten::ENLIGHTEN_NUM_OUTPUT_TEXTURE_TYPES] = {
    myAllocator.Create(width, height, TextureFormat_A16B16G16R16F), // irradiance: substitute appropriate texture format, see Enlighten::eOutputFormat
    myAllocator.Create(width, height, TextureFormat_A8R8G8B8), // directional
};

      The SampleRuntime project shows how to provide output textures for systems and cubemaps.

  • The high level runtime now always takes ownership of the output textures you provide. Do not delete the output textures until the high level runtime call your implementation of IGpuTexture::Release.
  • To update your existing per pixel probe lighting implementation to used the high level runtime, follow the implementation guide. If you prefer not to use the high level runtime, replace your existing PppiManager instance with PppiWorld.
  • BaseProbeSet::m_SelectedLod is now private. Please use BaseProbeSet::SetLod instead.

High level build system:

  • When the scene file is badly formed, the build system now reports an error and stops. To continue the precompute anyway, specify /p:Permissive on the command line.
  • To simplify the way your implementation groups instances into radiosity systems, allow the precompute to group instances automatically: 
    1. Remove the systemId and systemGuid attributes from each radiosity instance.
    2. Set the zone attribute to group instances into as few groups as possible. If your world is split into chunks for streaming, use the zone attribute to group instances into a single zone for each chunk.
    3. After the precompute, for each zone, load the IPrecompGeneratedSystems object to identify the Enlighten runtime data for each automatically grouped system.
    4. If you need to limit radiosity dependencies to speed up the precompute, add zone dependencies for each zone.
  • If you need to limit radiosity dependencies for cubemaps to speed up the precompute:
    1. If your world is split into chunks for streaming, set the zone attribute to group cubemaps into a single zone for each chunk.
    2. Add zone dependencies for each zone.
  • If your implementation uses probe octree objects, to quickly and safely update to the new probe region object:
    1. Replace IPrecompInputProbeOctree objects with IPrecompInputProbeRegion objects.
    2. Replace calls to IPrecompInputProbeOctree::Create with IPrecompInputProbeRegion::Create with the same voxelSize value.
    3. Call IPrecompInputProbeRegion::AddVolume, IPrecompInputProbeRegion::AddPoints or IPrecompInputProbeRegion::AddBoxes to specify the same input as previously provided to IPrecompInputProbeOctree::Create. 
    4. Replace each probeOctree element in your Enlighten scene with a probeRegion element that has the same name.
    5. Set the zone attribute of the probeRegion element to the same value as the name attribute.
    6. If you need to limit radiosity dependencies to speed up the precompute, add zone dependencies for each zone.