Light sampling. More...

Data Structures
struct	AtLightSample
	Light sample data structure. More...

Variables
const AtNode *	AtLightSample::Lp
	pointer to light node

float	AtLightSample::Ldist
	distance from P to light source

AtVector	AtLightSample::Ld
	normalized direction vector from P to the light sample

AtRGB	AtLightSample::Li
	incident radiance, same as `Liu` * (1 - `Lo`)

AtRGB	AtLightSample::Liu
	unoccluded incident radiance

AtRGB	AtLightSample::Lo
	shadow occlusion factor, (1,1,1) means fully occluded

float	AtLightSample::pdf
	sample probability density function

uint8_t	AtLightSample::trace_ray_types
	bitmask of ray types that will return light hits from AiLightsTrace More...

Light Loop Methods
This is the API for looping over light source samples.
AI_API void	AiLightsPrepare (AtShaderGlobals *sg)
	Initialize light sampling loop. More...

AI_API bool	AiLightsGetSample (AtShaderGlobals *sg, AtLightSample &sample)
	Get a cached light sample within a light loop. More...

AI_API uint32_t	AiLightsTrace (AtShaderGlobals sg, const AtVector &dir, uint8_t ray_type, AtLightSample &hits)
	Intersect all lights present in the light sampling loop for a given ray type and direction as seen from the shading point `AtShaderGlobals::P`, and return any hits as an array of `AtLightSamples`. More...

AI_API uint8_t	AiLightsTraceRayTypes (AtShaderGlobals *sg)
	Returns a bitmask of ray types for which `AiLightsTrace` can be effectively used in the given shading context. More...

AI_API void	AiLightsResetCache (AtShaderGlobals *sg)
	Reset the light cache before running another light loop. More...

AI_API AtRGB	AiLightsIntegrateShadowMatte (AtShaderGlobals sg, AtBSDF bsdf=NULL)
	Get the shadow or occlusion value for the current shading point and the active set of lights using the specified BSDF. More...

Light Getter Methods
These getters are to avoid slow AiNodeGet*() calls to access light parameters. Only the most common attributes are exposed for now.
AI_API AI_PURE AtRGB	AiLightGetColor (const AtNode *node)
	Fast getter method for parameter color.

AI_API AI_PURE float	AiLightGetIntensity (const AtNode *node)
	Fast getter method for parameter intensity.

AI_API AI_PURE float	AiLightGetDiffuse (const AtNode *node)
	Fast getter method for the light's diffuse shading multiplier.

AI_API AI_PURE float	AiLightGetSpecular (const AtNode *node)
	Fast getter method for the light's specular reflection shading multiplier.

AI_API AI_PURE float	AiLightGetTransmission (const AtNode *node)
	Fast getter method for the light's specular transmission shading multiplier.

AI_API AI_PURE float	AiLightGetSSS (const AtNode *node)
	Fast getter method for the light's SSS shading multiplier.

AI_API AI_PURE float	AiLightGetVolume (const AtNode *node)
	Fast getter method for the light's volume shading multiplier.

AI_API AI_PURE float	AiLightGetInfluence (const AtShaderGlobals sg, const AtNode node, uint8_t ray_type)
	Get light shading multiplier depending on the shading context and ray type.

Light IES Format Parser
Not a shader specific call, this is called by plugins or host DCCs to parse IES files
AI_API bool	AiLightIESLoad (const AtString filename, const unsigned int width, const unsigned int height, float max_intensity, float data)
	Loads an IES profile and returns a lat long array of intensity values. More...

Detailed Description

Light sampling.

Function Documentation

◆ AiLightsPrepare()

AI_API void AiLightsPrepare ( AtShaderGlobals * sg )

Initialize light sampling loop.

Prepares the given shader globals with a light sample cache and other variables used when looping over lights samples. The creation of the light sample cache is where lights are sampled, light samples are filtered, and shadow rays are cast as needed.

The sample cache will be reused in subsequent AiLightsPrepare() calls unless the shader globals has been changed in ways that would involve a different set of lights, different shadow rays to be traced or a different set of light samples to be produced.

AtShaderGlobals fields whose changes invalidate the light sample cache include: sc, fhemi, skip_shadow, inclusive_traceset, traceset, N, Nf, P

The light sample cache may also be manually invalidated at any time by calling AiLightsResetCache().

Note: Deprecated, use shader closures instead of integrating light in shaders.

Parameters

[in,out] sg the shader globals context

◆ AiLightsGetSample()

AI_API bool AiLightsGetSample	(	AtShaderGlobals *	sg,
		AtLightSample &	light_sample
	)

Get a cached light sample within a light loop.

After AiLightsPrepare() has been called, this function should be called inside a while loop. The call returns true if a valid light sample has been set. globals context are set:

Parameters

[in,out] sg the shader globals context

Returns: true if a valid sample was available

◆ AiLightsTrace()

AI_API uint32_t AiLightsTrace	(	AtShaderGlobals *	sg,
		const AtVector &	dir,
		uint8_t	ray_type,
		AtLightSample *&	hits
	)

Intersect all lights present in the light sampling loop for a given ray type and direction as seen from the shading point AtShaderGlobals::P, and return any hits as an array of AtLightSamples.

Note: It is expected for this function to be called only once per BSDF lobe sample as part of an MIS direct light sampling implementation. The number of BSDF samples for the lobe's AtBSDFLobeInfo::ray_type is defined by the corresponding render option GI sample setting.

Parameters

	sg	the shader globals context
	dir	the direction in which to sample
	ray_type	the ray type of the light sample
[out]	hits	array of light intersections detected for the given context

Returns: the number of light intersections detected for the given context

◆ AiLightsTraceRayTypes()

AI_API uint8_t AiLightsTraceRayTypes ( AtShaderGlobals * sg )

Returns a bitmask of ray types for which AiLightsTrace can be effectively used in the given shading context.

Parameters

sg	the shader globals context

Returns: a mask of the types of rays for which the prepared set of lights are potentially visible

◆ AiLightsResetCache()

AI_API void AiLightsResetCache ( AtShaderGlobals * sg )

Reset the light cache before running another light loop.

When called, AiLightsPrepare() caches a set of sampled and shadowed light samples such that subsequent calls will incur little overhead unless the light sampling context has changed in ways that would involve a different set of lights, different shadow rays to be traced or a different set of light samples to be produced. In these cases, the cached set of light samples is invalidated and a new set of samples is produced.

AtShaderGlobals fields whose changes invalidate the light sample cache include: sc, fhemi, skip_shadow, inclusive_traceset, traceset, N, Nf, P

These shader globals should capture all situations where built-in lighting and shading functionality would require a fresh set of samples to reflect the changed context, however, certain custom light loops and shading operations may involve other information that is not pertinent to the built-in light loop functionality. This function is provided as a manual reset of the light sample cache in situations for cache invalidation that are not contemplated by default.

Warning: Resetting the light cache when it is not strictly necessary may severely impact performance, as extra shadow rays are traced unnecessarily. Be sure to only use this when you need to make sure and gather a new set of light samples.

Parameters

sg	the shader globals context

◆ AiLightsIntegrateShadowMatte()

AI_API AtRGB AiLightsIntegrateShadowMatte	(	AtShaderGlobals *	sg,
		AtBSDF *	bsdf
	)

Get the shadow or occlusion value for the current shading point and the active set of lights using the specified BSDF.

Shadow occlusion is defined as the complementary of the ratio of actual reflected light with respect unshadowed reflected light, or the integral of (1 - Li / Liu)

If no BSDF is specified a default front facing Oren Nayar will be used.

Parameters

sg	the shader globals context

Returns: the amount of light occlusion per color channel

◆ AiLightIESLoad()

AI_API bool AiLightIESLoad	(	const AtString	filename,
		const unsigned int	width,
		const unsigned int	height,
		float *	max_intensity,
		float *	data
	)

Loads an IES profile and returns a lat long array of intensity values.

Parameters

	filename	The name of the IES profile map
	width	Width of the IES profile intensity output array
	height	Height of the IES profile intensity output array
[out]	max_intensity	IES profile maximum intensity.
[out]	data	IES profile normalized intensity data. Underlying buffer is allocated by caller. Caller should make sure it has the proper size.

Returns: true if the IES profile conversion was successful.

Variable Documentation

◆ trace_ray_types

uint8_t AtLightSample::trace_ray_types

bitmask of ray types that will return light hits from AiLightsTrace

and so can use multiple importance sampling (MIS)

Data Structures

Variables

Light Loop Methods

Light Getter Methods

Light IES Format Parser

Detailed Description

Function Documentation

◆ AiLightsPrepare()

◆ AiLightsGetSample()

◆ AiLightsTrace()

◆ AiLightsTraceRayTypes()

◆ AiLightsResetCache()

◆ AiLightsIntegrateShadowMatte()

◆ AiLightIESLoad()

Variable Documentation

◆ trace_ray_types