Classes and functions for interpolating light probe data.

Classes

Name	Description
Enlighten::InterpolatedPoint	Data structure describing a point in space to receive interpolated probe output.
Enlighten::InterpolationInputSet	Data structure describing the inputs and outputs of a probe set to be used as input data for interpolation.
Enlighten::InterpolationInputSet::CachedData	Internal cached data.
Enlighten::ProbeInterpolant	Data structure identifying a probe and associated weight (influence) which forms part of a set to be interpolated.
Enlighten::ProbeInterpolationTask	Task describing a set of probe sets to be used as inputs for interpolation, and a set of points which require interpolated outputs.

Functions

Name	Description
DoProbeInterpolationTask(const Enlighten::ProbeInterpolationTask *, Geo::u32 &)	Performs an interpolation of SH coefficients for a given set of points in space and probe sets.
GetProbeInterpolants(Geo::v128, const InterpolationInputSet , ProbeInterpolant , Geo::s32, Geo::s32 &, Geo::u32)	Retrieves the probes interpolants for a given point for a single probe set.
GetProbeInterpolants(Geo::v128, const InterpolationInputSet , Geo::s32, ProbeInterpolant , Geo::s32, Geo::s32 &, Geo::u32)	Retrieves the probes interpolants for a given point for multiple probe set.
GetProbeInterpolantsUnchecked(Geo::v128, const InterpolationInputSet , Geo::s32, ProbeInterpolant , Geo::s32, Geo::s32 &, Geo::u32)	Retrieves the probes interpolants for a given point for multiple probe set, without performing any kind of validation on the input arguments.
GetProbeSetInterpolants(Geo::v128, const InterpolationInputSet , Geo::s32, ProbeInterpolant , Geo::s32, Geo::s32 &)	Retrieves the probe set interpolants for a given point.
GetProbeShCoefficients(Geo::v128, const InterpolationInputSet , float , float , float , eSHOrder)	Retrieves the interpolated light probe spherical harmonics coefficients for a point based on a single input probe set.
GetProbeShCoefficients(Geo::v128, const InterpolationInputSet , Geo::s32, float , float , float , eSHOrder)	Retrieves the interpolated light probe spherical harmonics coefficients for a point based on multiple input probe sets.

bool GEO_CALL Enlighten::DoProbeInterpolationTask

public: bool GEO_CALL DoProbeInterpolationTask
(
const Enlighten::ProbeInterpolationTask * task,
Geo::u32 & timeUs
)

Performs an interpolation of SH coefficients for a given set of points in space and probe sets.

All parameters must point to valid non-null objects.

Parameters

[in]	task	A valid pointer to the probe interpolation task structure.
[out]	timeUs	Number of microseconds it took to solve the task.

Returns

TRUE if the interpolation is successful.

bool GEO_CALL Enlighten::GetProbeInterpolants

public: bool GEO_CALL GetProbeInterpolants
(
Geo::v128 point,
const InterpolationInputSet * inputSet,
ProbeInterpolant * interpolants,
Geo::s32 numMaxInterpolants,
Geo::s32 & numUsedInterpolants,
Geo::u32 lod
)

Retrieves the probes interpolants for a given point for a single probe set.

The output of this function is provided in an array of interpolants and by the number of valid entries in this arrays. The pointers to the output array has to be provided as input as well as its allocated size. The recommended number of interpolants is eight. If you experience discontinuities in the interpolation you can increase this size. However, eight is completely sufficient for the majority of cases. For regular grids, eight is also the minimum size.

For probe sets that are regular grids this function performs a fast trilinear interpolation. The order of probes as they get referenced by the indices in the output for regular grids is implicitly defined by the resolution in each dimension. The algorithm assumes an order similar to [x=3 y=2 z=2] -> {000,100,200,010,110,210,001,101,201,011,111,211}. The array with probe positions is ignored entirely in this case, and its input can be a NULL pointer.

For probe sets that are not

regular grids this function computes the distance to all probes in the probe set and picks the closest ones combined with a smooth interpolation kernel to generate the output weights. This can be a costly operation especially for large probe sets. The order of probes is explicitly given by the array of positions which has to be specified in this case. The length of this array has to not be smaller than the number of probes in the probe set.

The output interpolants are sorted by their weight from highest to lowest.

Parameters

[in]	point	Location used for the interpolation.
[in]	inputSet	Input probe set containing all relevant interpolation data.
[out]	interpolants	Output probe interpolants.
[in]	numMaxInterpolants	Size of the output interpolants array.
[out]	numUsedInterpolants	Number of interpolants actually used.
[in]	lod	Lod level to use when computing the interpolants, only applies when the input-sets are octree probe-sets.

Returns

TRUE if the input to this function is valid and the interpolation is successful, otherwise FALSE.

bool GEO_CALL Enlighten::GetProbeInterpolants

public: bool GEO_CALL GetProbeInterpolants
(
Geo::v128 point,
const InterpolationInputSet * inputSets,
Geo::s32 numInputSets,
ProbeInterpolant * interpolants,
Geo::s32 numMaxInterpolants,
Geo::s32 & numUsedInterpolants,
Geo::u32 lod
)

Retrieves the probes interpolants for a given point for multiple probe set.

This function has the same properties as its variant for a single input probe set. The only addition is that the computation only uses the up to eight best probe sets, and then within each probe set up to eight probes as interpolants.

Parameters

[in]	point	Location used for the interpolation.
[in]	inputSets	Input probe sets containing all relevant interpolation data.
[in]	numInputSets	Number of input probe sets.
[out]	interpolants	Output probe interpolants.
[in]	numMaxInterpolants	Size of the output interpolants array.
[out]	numUsedInterpolants	Number of interpolants actually used.
[in]	lod	Lod level to use when computing the interpolants, only applies when the input-sets are octree probe-sets.

Returns

TRUE if the input to this function is valid and the interpolation is successful, otherwise FALSE.

bool GEO_CALL Enlighten::GetProbeInterpolantsUnchecked

public: bool GEO_CALL GetProbeInterpolantsUnchecked
(
Geo::v128 point,
const InterpolationInputSet * inputSets,
Geo::s32 numInputSets,
ProbeInterpolant * interpolants,
Geo::s32 numMaxInterpolants,
Geo::s32 & numUsedInterpolants,
Geo::u32 lod
)

Retrieves the probes interpolants for a given point for multiple probe set, without performing any kind of validation on the input arguments.

This function has the same properties as its checked variant, noting no validation on the inputs is performed.

Parameters

[in]	point	Location used for the interpolation.
[in]	inputSets	Input probe sets containing all relevant interpolation data.
[in]	numInputSets	Number of input probe sets.
[out]	interpolants	Output probe interpolants.
[in]	numMaxInterpolants	Size of the output interpolants array.
[out]	numUsedInterpolants	Number of interpolants actually used.
[in]	lod	Lod level to use when computing the interpolants, only applies when the input-sets are octree probe-sets.

Returns

TRUE if the input to this function is valid and the interpolation is successful, otherwise FALSE.

bool GEO_CALL Enlighten::GetProbeSetInterpolants

public: bool GEO_CALL GetProbeSetInterpolants
(
Geo::v128 point,
const InterpolationInputSet * inputSets,
Geo::s32 numInputSets,
ProbeInterpolant * interpolants,
Geo::s32 numMaxInterpolants,
Geo::s32 & numUsedInterpolants
)

Retrieves the probe set interpolants for a given point.

Note that this function creates an interpolant for a probe set and not for an individual probe.

This function has the same properties as its variant for probes with a single input probe set.

Parameters

[in]	point	Location used for the interpolation.
[in]	inputSets	Input probe sets containing all relevant interpolation data.
[in]	numInputSets	Number of input probe sets.
[out]	interpolants	Output probe set interpolants.
[in]	numMaxInterpolants	Size of the output interpolants array.
[out]	numUsedInterpolants	Number of interpolants actually used.

Returns

TRUE if the input to this function is valid and the interpolation is successful, otherwise FALSE.

bool GEO_CALL Enlighten::GetProbeShCoefficients

public: bool GEO_CALL GetProbeShCoefficients
(
Geo::v128 point,
const InterpolationInputSet * inputSet,
float * r,
float * g,
float * b,
eSHOrder shOrder
)

Retrieves the interpolated light probe spherical harmonics coefficients for a point based on a single input probe set.

The interpolated coefficients get stored independently for each RGB channel in buffers that have to be provided to this function and which must be large enough to accommodate the coefficients that get generated. The number of generated coefficients depends on the requested SH order (L0, L1, L2), but also on the SH order of the probe set retrieved from the probe set metadata.

A fixed maximum of eight probes as interpolants is used in the computation.

Parameters

[in]	point	Location used for the interpolation.
[in]	inputSet	Single input probe set containing all relevant interpolation data.
[out]	r	Interpolated SH coefficients for the red color channel.
[out]	g	Interpolated SH coefficients for the green color channel.
[out]	b	Interpolated SH coefficients for the blue color channel.
[in]	shOrder	SH order for the interpolated coefficients. Make sure that the RGB output buffers are large enough to accommodate the resulting number of coefficients (1 for L0, 4 for L1, 9 for L2).

Returns

TRUE if the input to this function is valid and the interpolation is successful, otherwise FALSE.

bool GEO_CALL Enlighten::GetProbeShCoefficients

public: bool GEO_CALL GetProbeShCoefficients
(
Geo::v128 point,
const InterpolationInputSet * inputSets,
Geo::s32 numInputSets,
float * r,
float * g,
float * b,
eSHOrder shOrder
)

Retrieves the interpolated light probe spherical harmonics coefficients for a point based on multiple input probe sets.

This function has the same properties as its variant for a single input probe set. The only addition is that the computation only uses the up to eight best probe sets, and then within each probe set up to eight probes as interpolants.

Parameters

[in]	point	Location used for the interpolation.
[in]	inputSets	Input probe sets containing all relevant interpolation data.
[in]	numInputSets	Number or input probe sets.
[out]	r	Interpolated SH coefficients for the red color channel.
[out]	g	Interpolated SH coefficients for the green color channel.
[out]	b	Interpolated SH coefficients for the blue color channel.
[in]	shOrder	SH order for the interpolated coefficients. Make sure that the RGB output buffers are large enough to accommodate the resulting number of coefficients (1 for L0, 4 for L1, 9 for L2).

Returns

TRUE if the input to this function is valid and the interpolation is successful, otherwise FALSE.