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. | |
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.
[in,out] | sg | the 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 samplesg->Lo
– RGB occlusion factor, where (1,1,1) means fully occludedsg->Liu
– unoccluded incident radiance (this is the same as sg->Li
without considering occlusion)sg->Ldist
– distance towards the light sourcesg->we
– weight of the light samplesg->Lp
– pointer to the light's AtNode[in,out] | sg | the shader globals context |
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()
.
sg | the shader globals context |
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.
sg | the shader globals context |