Light source sampling API

Light Loop Methods

This is the recommended API for looping over light source samples.

AI_API void AiLightsPrepare (AtShaderGlobals *sg)
 Initialize light loop. More...
 
AI_API bool AiLightsGetSample (AtShaderGlobals *sg)
 Get a sample within a light loop. More...
 
AI_API AtRGB AiLightsGetShadowMatte (AtShaderGlobals *sg)
 Get the shadow/occlusion value for the current shading point and the active set of lights. More...
 
AI_API void AiLightsResetCache (AtShaderGlobals *sg)
 Reset the light cache before running another light loop. 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 AtRGB AiLightGetColor (const AtNode *node)
 Fast getter method for parameter color.
 
AI_API float AiLightGetIntensity (const AtNode *node)
 Fast getter method for parameter intensity.
 
AI_API bool AiLightGetAffectDiffuse (const AtNode *node)
 DEPRECATED: Fast getter method for parameter affect_diffuse.
 
AI_API bool AiLightGetAffectSpecular (const AtNode *node)
 DEPRECATED: Fast getter method for parameter affect_specular.
 
AI_API float AiLightGetDiffuse (const AtNode *node)
 Fast getter method for the light's diffuse shading multiplier.
 
AI_API float AiLightGetSpecular (const AtNode *node)
 Fast getter method for the light's specular shading multiplier.
 
AI_API float AiLightGetSSS (const AtNode *node)
 Fast getter method for the light's SSS shading multiplier.
 

Detailed Description

Function Documentation

AI_API void AiLightsPrepare ( AtShaderGlobals sg)

Initialize light loop.

Prepares the given shader globals for looping over lights. The current position and normal are cached so that the evaluation of lights (which might require evaluating filters and tracing shadow rays) can be skipped if nothing changes.

Parameters
[in,out]sgthe shader globals context
AI_API bool AiLightsGetSample ( AtShaderGlobals sg)

Get a 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, in which case all the light source related fields in the shader globals context are set:

  • sg->Li – incident radiance, same as sg->Liu * (1 - sg->Lo)
  • sg->Ld – normalized vector towards the light sample
  • sg->Lo – RGB occlusion factor, where (1,1,1) means fully occluded
  • sg->Liu – unoccluded incident radiance (this is the same as sg->Li without considering occlusion)
  • sg->Ldist – distance towards the light source
  • sg->we – weight of the light sample
  • sg->Lp – pointer to the light's AtNode
Parameters
[in,out]sgthe shader globals context
Returns
true if a valid sample was available
AI_API AtRGB AiLightsGetShadowMatte ( AtShaderGlobals sg)

Get the shadow/occlusion value for the current shading point and the active set of lights.

Shadow occlusion is calculated by accumulating all of the sg->Lo values for each of the lights weighted by their respective sg->we values, and then determining the maximum matte value of all the lights. It is this maximum value which is returned. This value can never be greater than 1.0.

It is not neccessary to call AiLightsPrepare() prior to calling this function. If the light samples have not been set up, then this function will prepare them by automatically calling AiLightsPrepare().

Parameters
sgthe shader globals context
Returns
the amount of shadow occlusion (clamped to 1.0)
AI_API void AiLightsResetCache ( AtShaderGlobals sg)

Reset the light cache before running another light loop.

The after calling AiLightsPrepare() various lighting data are cached so that subsequent calls will incur no overhead. However, if certain values change in the shader globals, that cached lighting data may not be valid and a reset is necessary to compute new data. This is particularly true if you wish to switch from hemispherical lighting to full-sphere lighting, change the surface normal or position, or change tracesets for shadow rays in a particular light loop.

Parameters
sgthe shader globals context

© 2009-2013 Solid Angle SL · all rights reserved · www.solidangle.com