Data Structures
Light Sampling API

Light sampling. More...

Data Structures

struct  AtLightSample
 Light sample data structure. More...
 

Light Loop Methods

This is the API for looping over light source samples.

AI_API void AiLightsPrepare (AtShaderGlobals *sg)
 Initialize light loop. More...
 
AI_API bool AiLightsGetSample (AtShaderGlobals *sg, AtLightSample &sample)
 Get a sample within a light loop. More...
 
AI_API uint32_t AiLightsTrace (AtShaderGlobals *sg, const AtVector &dir, uint8_t ray_type, AtLightSample *&hits)
 Intersect all visible lights.
 
AI_API uint8_t AiLightsTraceRayTypes (AtShaderGlobals *sg)
 Returns bitmask of ray types for which AiLightsTrace can be used.
 
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

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.

Note
Deprecated, use shader closures instead of integrating light in shaders.
Parameters
[in,out]sgthe shader globals context
AI_API bool AiLightsGetSample ( AtShaderGlobals sg,
AtLightSample light_sample 
)

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. globals context are set:

Parameters
[in,out]sgthe shader globals context
Returns
true if a valid sample was available
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.

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
sgthe shader globals context
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
sgthe shader globals context
Returns
the amount of light occlusion per color channel
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
filenameThe name of the IES profile map
widthWidth of the IES profile intensity output array
heightHeight of the IES profile intensity output array
[out]max_intensityIES profile maximum intensity.
[out]dataIES 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.

© 2020 Autodesk, Inc. · All rights reserved · www.arnoldrenderer.com