Shader Closure API

AtClosure creation. More...

Enumerations
enum class	AtRandomWalkVersion { v1 = 1 , v2 , v3 }

Functions
AI_API AI_DEVICE AtClosure	AiClosureEmpiricalBSSRDF (const AtShaderGlobals *sg, const AtRGB &weight, const AtVector &mfp, const AtRGB &albedo)
	Create BSSRDF closure for subsurface scattering in surface shaders. More...
AI_API AI_DEVICE AtClosure	AiClosureRandomWalkBSSRDF (const AtShaderGlobals *sg, const AtRandomWalkVersion &version, const AtRGB &weight, const AtVector &mfp, const AtRGB &albedo, float g=0.0f)
	Create BSSRDF closure for random walk subsurface scattering in surface shaders. More...
AI_API AI_DEVICE void	AiClosureBSSRDFSetDirectIndirect (AtClosure closure, float weight_direct, float weight_indirect)
	Set the BSSRDF closure direct and indirect light contribution weights. More...
AI_API AI_DEVICE AtClosure	AiClosureEmission (const AtShaderGlobals *sg, const AtRGB &weight)
	Create emission closure for surface shaders. More...
AI_API AI_DEVICE AtClosure	AiClosureTransparent (const AtShaderGlobals *sg, const AtRGB &weight=AI_RGB_WHITE, const AtClosureList interior=NULL, int32_t importance=0)
	Create transparent closure for surface shaders. More...
AI_API AI_DEVICE AtClosure	AiClosureMatte (const AtShaderGlobals *sg, const AtRGB &weight=AI_RGB_WHITE)
	Create matte closure for surface shaders. More...
AI_API AtClosure	AiClosureBackground (const AtShaderGlobals *sg, const AtRGB &weight=AI_RGB_WHITE)
	Create background closure for background surface shaders. More...
AI_API AI_DEVICE AtClosure	AiClosureVolumeAbsorption (const AtShaderGlobals *sg, const AtRGB &weight)
	Create volume absorption closure, for volume shaders. More...
AI_API AI_DEVICE AtClosure	AiClosureVolumeEmission (const AtShaderGlobals *sg, const AtRGB &weight)
	Create volume emission closure, for volume shaders. More...
AI_API AI_DEVICE AtClosure	AiClosureVolumeHenyeyGreenstein (const AtShaderGlobals *sg, const AtRGB &absorption, const AtRGB &scattering, const AtRGB &emission, float g=0.f)
	Create Henyey-Greenstein volume scattering closure, for volume shaders. More...
AI_API AI_DEVICE AtClosure	AiClosureVolumeDoubleHenyeyGreenstein (const AtShaderGlobals *sg, const AtRGB &absorption, const AtRGB &scattering, const AtRGB &emission, float g=0.f, float g2=0.f, float w2=0.f)
	This creates a linear mix of two Henyey-Greenstein phase function lobes, of the form: More...
AI_API AI_DEVICE AtClosure	AiClosureVolumeMatte (const AtShaderGlobals *sg, const AtRGB &weight)
	Create volume matte closure, for volume shaders. More...
AI_API AI_DEVICE AtClosure	AiClosureVolumeAtmosphere (const AtShaderGlobals *sg, const AtRGB &emission, const AtRGB &transparent, const AtRGB &matte)
	Create volume atmosphere closure, for legacy atmosphere shaders. More...

Detailed Description

AtClosure creation.

Shaders can return these instead of final colors.

Closures describe the way surfaces and volumes scatter light, leaving the lights loops and integration to Arnold.

For creating BSDF closures, an AtBSDF can be wrapped in a closure:

AtBSDF *bsdf = AiOrenNayarBSDF(sg, sg->Nf);
sg->out.CLOSURE() = AtClosure(diffuse_color, bsdf);

Function Documentation

AiClosureEmpiricalBSSRDF()

AI_API AI_DEVICE AtClosure AiClosureEmpiricalBSSRDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		const AtVector &	mfp,
		const AtRGB &	albedo
	)

Create BSSRDF closure for subsurface scattering in surface shaders.

This is a diffusion BSSRDF model empirically fitted to match brute-force Monte Carlo scattering. The BSSRDF accounts for both single and multiple scattering. Note that Fresnel or other layer or mixing weights must be provided separately from the albedo, as the albedo affects the shape of the BSSRDF profile.

See also

http://graphics.pixar.com/library/ApproxBSSRDF/

BSSRDF sampling quality is controlled by the GI_sss_samples render option.

Parameters

sg	shader globals
weight	RGB weights for mixing profiles or applying fresnel
mfp	per RGB wavelength mean free path lengths (mfp = 1/sigmat' = 1/(sigmas' + sigmaa))
albedo	diffuse reflectivity

Returns

BSSRDF closure

AiClosureRandomWalkBSSRDF()

AI_API AI_DEVICE AtClosure AiClosureRandomWalkBSSRDF	(	const AtShaderGlobals *	sg,
		const AtRandomWalkVersion &	version,
		const AtRGB &	weight,
		const AtVector &	mfp,
		const AtRGB &	albedo,
		const float	g
	)

Create BSSRDF closure for random walk subsurface scattering in surface shaders.

Note that Fresnel or other layer or mixing weights must be provided separately from the albedo, as the albedo affects the shape of the BSSRDF profile.

BSSRDF sampling quality is controlled by the GI_sss_samples render option.

Parameters

sg	shader globals
weight	RGB weights for mixing profiles or applying fresnel
mfp	per RGB wavelength mean free path lengths (mfp = 1/sigmat' = 1/(sigmas' + sigmaa))
albedo	diffuse reflectivity
g	Henyey-Greenstein anisotropy parameter for anisotropic scattering

Returns

BSSRDF closure

AiClosureBSSRDFSetDirectIndirect()

AI_API AI_DEVICE void AiClosureBSSRDFSetDirectIndirect	(	AtClosure	closure,
		float	weight_direct,
		float	weight_indirect
	)

Set the BSSRDF closure direct and indirect light contribution weights.

For physically correct rendering, these must be set to the default 1.0, however for artistic control the direct and indirect light contributions can be scaled independently.

Parameters

closure	BSSRDF closure
weight_direct	Direct light weight
weight_indirect	Indirect light weight

AiClosureEmission()

AI_API AI_DEVICE AtClosure AiClosureEmission	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight
	)

Create emission closure for surface shaders.

Parameters

sg	shader globals
weight	emission radiance

Returns

emission closure

AiClosureTransparent()

AI_API AI_DEVICE AtClosure AiClosureTransparent	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		const AtClosureList	interior,
		int32_t	importance
	)

Create transparent closure for surface shaders.

When making a surface transparent, other surface closures should have the opacity multiplied in, so that the total weight of all closures does not exceed 1 and energy is conserved. Mixing with other closures can be done as follows:

closures *= opacity;
closures.add(AiClosureTransparent(sg, 1 - opacity));

Objects must have the opaque parameter off to render transparency.

Parameters

sg	shader globals
weight	transparency
interior	optional volume closures for interior of the object
importance	used to resolve overlaps

Returns

transparent closure

AiClosureMatte()

AI_API AI_DEVICE AtClosure AiClosureMatte	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight
	)

Create matte closure for surface shaders.

The matte closure creates a holdout effect by rendering alphas as zero. This works like the matte parameter on shapes.

Parameters

sg	shader globals
weight	matte transparency

Returns

matte closure

AiClosureBackground()

AI_API AtClosure AiClosureBackground	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight
	)

Create background closure for background surface shaders.

Parameters

sg	shader globals
weight	emission radiance

Returns

background closure

AiClosureVolumeAbsorption()

AI_API AI_DEVICE AtClosure AiClosureVolumeAbsorption	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight
	)

Create volume absorption closure, for volume shaders.

The closure weight is the absorption coefficient. This coefficient is the rate at which the volume absorbs light that is traveling along the given direction at the given point. Any light that traverses a volume with a given absoprtion coefficient will be attenuated at a rate of:

attenuation = expf(-(scattering_coefficient + absorption_coefficient) * distance_travelled)

Parameters

sg	shader globals that the volume shader was invoked with
weight	absorption coefficient
ior	the index of refraction of the bulk substrate medium

Returns

volume closure

AiClosureVolumeEmission()

AI_API AI_DEVICE AtClosure AiClosureVolumeEmission	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight
	)

Create volume emission closure, for volume shaders.

The closure weight is the emission coefficient. This coefficient is the rate at which the volume emits light along the given direction at the given point. Any ray that traverses a volume with a given emission coefficient will have radiance added at a rate of:

emission = emission_coefficient * distance_travelled

Note

The volume's emission is itself affected by the volume's attenuation.

Parameters

sg	shader globals that the volume shader was invoked with
emission	emission coefficient

Returns

volume closure

AiClosureVolumeHenyeyGreenstein()

AI_API AI_DEVICE AtClosure AiClosureVolumeHenyeyGreenstein	(	const AtShaderGlobals *	sg,
		const AtRGB &	absorption,
		const AtRGB &	scattering,
		const AtRGB &	emission,
		float	g
	)

Create Henyey-Greenstein volume scattering closure, for volume shaders.

The scattering coefficient is the rate at which the volume in-scatters radiance along the given direction at the given point, and the 'g' parameter is the Henyey-Greenstein phase at the given point. These coefficients are used for both direct and indirect light paths, and the amount of in-scattered radiance is:

scattering = scattering_coefficient * HenyeyGreensteinPhaseFunc(g, sg->Ld, sg->Rd) * radiance * distance_travelled

The absorption and emission coefficients are the same as in the volume absorption and emission closures. Creating a single volume scattering closures with all coefficients is faster than creating separate closures for each coefficient.

Note

The volume's scattering is itself affected by the volume's attenuation.

Parameters

sg	shader globals that the volume shader was invoked with
absorption	absorption coefficient
scattering	scattering coefficient
emission	emission coefficient
g	Henyey-Greenstein phase anisotropy, in the open interval (-1,+1) where negative values mean backward anisotropic scattering, positive values mean forward anisotropic scattering, zero means isotropic scattering
g2	Henyey-Greenstein phase anisotropy for the secondary HG lobe (defaults to 0)
w2	weight of the secondary, blended HG lobe (defaults to 0)

Returns

volume closure

AiClosureVolumeDoubleHenyeyGreenstein()

AI_API AI_DEVICE AtClosure AiClosureVolumeDoubleHenyeyGreenstein	(	const AtShaderGlobals *	sg,
		const AtRGB &	absorption,
		const AtRGB &	scattering,
		const AtRGB &	emission,
		float	g,
		float	g2,
		float	w2
	)

This creates a linear mix of two Henyey-Greenstein phase function lobes, of the form:

     (1 - w2) * HenyeyGreensteinPhaseFunc(g, ..) + w2 * HenyeyGreensteinPhaseFunc(g2, ..)

Parameters

sg	shader globals that the volume shader was invoked with
absorption	absorption coefficient
scattering	scattering coefficient
emission	emission coefficient
g	Henyey-Greenstein phase anisotropy, in the open interval (-1,+1) where negative values mean backward anisotropic scattering, positive values mean forward anisotropic scattering, zero means isotropic scattering
g2	Henyey-Greenstein phase anisotropy for the secondary HG lobe (defaults to 0)
w2	mix weight of the secondary HG lobe (defaults to 0)

Returns

volume closure

AiClosureVolumeMatte()

AI_API AI_DEVICE AtClosure AiClosureVolumeMatte	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight
	)

Create volume matte closure, for volume shaders.

If used in place of AiClosureVolumeAbsorption(), this works the same as the matte parameter on shapes.

Parameters

sg	shader globals that the volume shader was invoked with
weight	absorption coefficient

Returns

volume closure

AiClosureVolumeAtmosphere()

AI_API AI_DEVICE AtClosure AiClosureVolumeAtmosphere	(	const AtShaderGlobals *	sg,
		const AtRGB &	emission,
		const AtRGB &	transparent,
		const AtRGB &	matte
	)

Create volume atmosphere closure, for legacy atmosphere shaders.

The weights are the total emission, transparency and matte transparency integrated over the volume segment with length sg->Rl. Such weights maybe be more convenient and numerically stable for legacy atmosphere shaders that cover long volume segment distances.

Parameters

sg	shader globals
emission	integrated emission, equivalent to AiClosureEmission weight for surfaces
transparent	integrated transparency, equivalent to AiClosureTransparent weight for surfaces
matte	integrated matte transparency, equivalent to AiClosureMatte weight for surfaces

Returns

volume atmosphere closure