This is the documentation for Enlighten.
module Input Lighting
Operations relating to input lighting generation for the Enlighten runtime.
This is the original input lighting api. Note that there is a new 'extended' input lighting api available on most platforms through EnlightenInputLighting.h.
There is a considerable amount of freedom in how you choose to provide input lighting to Enlighten and the design trade-offs involved can have a huge impact on the success of Enlighten in your product. Most games are unique in some respect, so please feel free to contact Enlighten support for help in choosing the best option for your game.
There are also now two apis for providing input lighting to Enlighten. This one (the original api) and a newer 'extended' input lighting api, available through EnlightenInputLighting.h. They both use the same InputWorkspace structure and have other elements in common, but differ in how the calculation is performed, and the extended api supports additional features.
Enlighten uses a physically realistic algorithm for bouncing indirect light around a scene (subject to the tweakable albedo and bounce scale values), but makes no particular assumptions about the direct lighting model.
In practice, it's often more convenient to use a non-physical fall-off model for spot and point lights. They can be simpler to work with, reduce artefacts, and given the limitations of output displays it's often the only way to produce the desired effect.
Because of this, Enlighten allows users to specify a custom distance fall-off for point and spot light using the Enlighten::InputLightFalloffTable. Now, it is worth emphasising that there needn't be an exact correspondence between the model used for direct, on-screen lighting and the model used for producing input lighting for Enlighten. The closer the two models correspond, the more self-consistent the lighting model as a whole; on the other hand, if the Enlighten input lighting uses a completely non-physical model, it can produce counter-intuitive effects. (One example would be that the amount of light in the scene could vary wildly as a light source of constant intensity is moved closer to or further away from geometry; as soon as the model is non-physical, energy is not necessarily conserved.)
For convenience, Enlighten provides two API functions for generating suitable fall-off tables: Enlighten::GenerateUnrealCompatibleLightFalloffTable(), Enlighten::GenerateUnityCompatibleLightFalloffTable() and Enlighten::GenerateInverseSquaredLightFalloffTable(). See also the Enlighten::InputLight class.
Classes
Name | Description |
|---|---|
A base class all light types must derive from to work with any input lighting API. | |
Class encapsulating the description of a light falloff curve. | |
A single frame of the InputWorkspace lighting (internal). | |
A structure for receiving the data held internally about a duster point for debugging visualisation purposes. | |
Runtime data storing precomputed visibility information (eg, for directional lights) | |
Runtime data allocated by end user that stores uncompressed precomputed visibility data. | |
Supported formats for visibility data. |
Variables
Name | Description |
|---|---|
void *const LIGHT_VISIBILITY_DISABLED = (void*)1 | Equivalent to light visibility data with all bits set to 0. |
Functions
Name | Description |
|---|---|
Adds light values from one input lighting buffer to another. | |
AddDusterValuesToInputWorkspace(const InputWorkspace *, InputLightingBuffer *, const Geo::v128 *) | Adds light values laid out in a duster block to an Enlighten input workspace. |
CalcInputLightingBufferSize(const InputWorkspace *, PrecisionHint::Value) | Tells you the amount of memory required to hold input lighting for a given system. |
Determine how much memory is required for a light visibility block. | |
CalcLightVisibilitySize(const InputWorkspace *, Enlighten::VisibilityFormat::Type) | Determine how much memory is required for a light visibility block. |
CalcPrecomputedVisibilityWorkspaceSize(const InputWorkspace *, const PrecomputedVisibilityData *) | Determine how much memory is required for a precomputed visibility workspace. |
ClearInputWorkspace(const InputWorkspace *, InputLightingBuffer *) | Clear the input lighting to black. |
Compares Returns true if the lighting buffers could be compared. | |
CreateInputLightingBuffer(void *, const InputWorkspace *, PrecisionHint::Value) | Construct an InputLightingBuffer inside the memory provided. |
Construct an PrecomputedVisibilityWorkspace inside the memory provided. | |
GenerateInverseSquaredLightFalloffTable(InputLightFalloffTable *, float, float) | Helper function that generates a Falloff Table using an inverse squared light falloff function, closely approximating real world light falloff. |
GenerateUnityCompatibleLightFalloffTable(InputLightFalloffTable *) | Helper function that generates a falloff table compatible with the Unity light falloff model. |
GenerateUnrealCompatibleLightFalloffTable(InputLightFalloffTable *, float) | Helper function that generates a Falloff Table compatible with the Unreal light falloff model. |
GetInputLightingBufferLightValue(const InputLightingBuffer *, float, Geo::s32) | Fill the specified array with the current light value for the given cluster index. |
Returns the size of the specified InputLightingBuffer object. | |
GetInputLightingBufferSystemId(const Enlighten::InputLightingBuffer *) | Get system id from InputLightingBuffer. |
GetInputWorkspaceDebugIterator(const InputWorkspace *, Enlighten::InputWorkspaceDebugIterator &) | Return a debug iterator object in {debugIterator} which can be used to iterate through the systems debug points. |
GetInputWorkspaceDebugPoint(const InputWorkspace *, InputWorkspaceDebugPoint *, Geo::s32) | Fill the specified debug data structure with the current values for the given input workspace sample point. |
Fill the specified debug data structure with the current values for the given input workspace sample point. | |
GetInputWorkspaceNormalArray(const InputWorkspace *, Geo::v128 *) | Fills an array with the normals of all of the input points in an input workspace. |
GetInputWorkspaceNumPointsPerClusterArray(const InputWorkspace *, Geo::s32 *) | Fills the array with the number of points per cluster. |
GetInputWorkspacePositionAndNormalArray(const InputWorkspace *, Geo::v128 *, Geo::v128 *) | Fills arrays with the positions and normals of all of the input points in an input workspace. |
GetInputWorkspacePositionArray(const InputWorkspace *, Geo::v128 *) | Fills an array with the positions of all of the input points in an input workspace. |
Returns the size of the specified InputWorkspace object. | |
Returns the total number of clusters in an input workspace. | |
Returns the total number of output buckets. | |
Returns the total number of output pixels being lit. |