adskUtilities.h File Reference

---

Detailed Description

Autodesk Shader Software Development Kit utility functions.

Utility functions for use in constructing shaders using the Autodesk Shader Software Development Kit.

#include "adskColor.h"
#include "adskVector.h"
#include "adskRenderPassTypes.h"
#include "adskRenderPassUtilities.h"
#include "adskFrameBufferState.h"
#include <shader.h>
#include "adskShaderSDKNamespaceBegin.h"
#include "adskShaderSDKNamespaceEnd.h"

Include dependency graph for adskUtilities.h:

This graph shows which files directly or indirectly include this file:

Functions
void	adskFatal (const string &pString)
	Emit fatal error from shader.
void	adskError (const string &pString)
	Emit error from shader.
void	adskWarning (const string &pString)
	Emit fatal warning from shader.
void	adskInfo (const string &pString)
	Emit information from shader.
template<class T>
T *	adskNewMIObject ()
	Allocate and construct an object on the mental ray heap.
template<class T>
T *	adskNewMIArray (size_t itemCount)
	Allocate and construct an object array on the mental ray heap.
template<class T>
void	adskDeleteMIObject (T *ptr)
	Destruct and deallocate an object on the mental ray heap.
template<class T>
void	adskDeleteMIArray (T *ptr, size_t itemCount)
	Destruct and deallocate an object array on the mental ray heap.
miUint	getNamedFrameBufferID (const miState *pState, const char *pBufferName)
	Obtain the numeric ID for a named frame buffer.
miUint	getNamedFrameBufferID (const miState *pState, const miTag pBufferTag)
	Obtain the numeric ID for a named frame buffer.
template<typename T, typename F>
T	applyScale (const T &value, const F &scale)
	Scaling function used internally by operateOnFrameBuffer.
template<>
miInteger	applyScale< miInteger, miScalar > (const miInteger &value, const miScalar &scale)
	Template specialization of applyScale for integers and scalars.
template<>
miInteger	applyScale< miInteger, miColor > (const miInteger &value, const miColor &scale)
	Template specialization of applyScale for integers and colors. Should not be used.
template<>
miScalar	applyScale< miScalar, miColor > (const miScalar &value, const miColor &scale)
	Template specialization of applyScale for scalars and colors.
template<>
miVector	applyScale< miVector, miColor > (const miVector &value, const miColor &scale)
	Template specialization of applyScale for vectors and colors.
template<typename T>
miBoolean	operateOnFrameBuffer (const miState *pState, const T &pValue, FrameBufferInfo &pFrameBufferInfo, const miInteger &pFrameBufferWriteOperation, const miInteger &pFrameBufferWriteFlags, const miScalar &pFrameBufferWriteFactor, const bool &pUseIrradiance, const miColor *const &pIrradianceNoShadow=0)
	Perform the desired operation on a frame buffer.
template<typename T>
miBoolean	accumulateLightSample (const miState *pState, const T &pValue, FrameBufferInfo &pFrameBufferInfo, const bool &pUseIrradiance, const miColor *const &pIrradianceNoShadow=0)
	Accumulates a frame buffer value for the current light sample.
template<typename T>
void	operateOnFrameBuffersOfType (const miState *pState, const T &pValue, FrameBufferInfo *const pFrameBufferInfo, PassTypeInfo *const pPassTypeInfo, const PassTypeID &pTypeID, const miInteger &pFrameBufferWriteOperation, const miInteger &pFrameBufferWriteFlags, const miScalar &pFrameBufferWriteFactor, const bool &pUseIrradiance, const miColor *const &pIrradianceNoShadow=0)
	Operate on all frame buffers of a given material pass type.
void	operateOnNormalMaterialFrameBuffersOfType (const miState *pState, miVector pValue, FrameBufferInfo *const pFrameBufferInfo, PassTypeInfo *const pPassTypeInfo, const miInteger &pFrameBufferWriteOperation, const miInteger &pFrameBufferWriteFlags, const miScalar &pFrameBufferWriteFactor)
	Operate on material normal frame buffers.
template<typename T>
T	MAYA_CLAMP (const T &x, const T &a, const T &b)
	Clamp value to range.
template<typename T>
T	MAYA_MIN (const T &x, const T &y)
	Find minimum value.
template<typename T>
T	MAYA_MAX (const T &x, const T &y)
	Find maximum value.
bool	MAYA_ISZERO (const miScalar a)
	Is value effectively zero.
template<typename T>
T	lerp (const T &t, const T &a, const T &b)
	Computer linear interpolation.
template<typename T>
T	linearRamp (const T &a, const T &b, const T &x)
	Computer linear ramp.
template<typename T>
T	remap (const T &pValue, const T &pOldMinimum, const T &pOldMaximum, const T &pNewMinimum, const T &pNewMaximum)
	Remap value to new range.
template<typename T>
T	clampedRemap (const T &pValue, const T &pOldMinimum, const T &pOldMaximum, const T &pNewMinimum, const T &pNewMaximum)
	Remap value to new range and clamp to that range.
void	convertToNormalizedPixels (const miState *pState, miVector &vec)
	Convert pixel aspect ratio.
void	tracePassInit (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, miState *pState)
	Prepare the frame buffer states for a series of reflection and/or refraction trace recursions.
void	tracePassAdd (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, miState *pState, miColor pFactor, bool pIsRefraction)
	Composite the frame buffer states after a series of reflection and/or refraction trace recursions.
bool	traceShadow (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, miColor &pFilter, const miColor &pLightColor, const miColor &pShadowColor, bool pUsingShadowMap, miState *pState)
	Trace a shadow ray using per frame-buffer lighting Note: should only be called from a light shader.
void	setLightIrradiance (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, const miColor &pLightColor)
	When not rendering with shadows, this function is called to set the irradiance value for the current light Note: should only be called from a light shader.
void	traceShadowAccumulateBegin (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo)
	Initialize frame buffer states for shadow area sampling, used for area lights, final gathering, etc. Note: should only be called from a light shader when not using a shadow map.
bool	traceShadowAccumulate (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, miColor &pFilter, miState *pState)
	Trace a shadow ray and accumulate results for per frame-buffer lighting Note: should only be called from a light shader, between calls to traceShadowAccumulateBegin and traceShadowAccumulateEnd.
void	traceShadowAccumulateEnd (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, unsigned int pNumberOfRays, const miColor &pLightColor, const miColor &pShadowColor, miState *pState)
	Process accumulated shadow rays for light sampling Note: should only be called from a light shader when not using a shadow map.
void	sampleLightBegin (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo)
	Function to be called before all light sampling loops. Takes care of initializing light sample accumulators.
void	sampleLightEnd (miState *pState, unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, const int pSamples, const miInteger &pFrameBufferWriteOperation, const miInteger &pFrameBufferWriteFlags, const miScalar &pFrameBufferWriteFactor)
	Function to be called after all light sampling loops. Takes care of combining sample values into the material frame buffer values.
void	setupLightContributions (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, miState *pState)
	Initializes the frame buffer states for receiving illumination information Note: should be called at the beginning of a light shader.
miBoolean	applyShadowTransparencyToFrameBuffers (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, const miColor &pTransparency, miState *pState)
	Applies the shadow opacity of the current object to all relevant frame buffer states. Note: should only be called from shadow shaders.
void	handleNonAdskLights (unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, const miColor &pLightColor, miTag pLightInstance, miState *pState)
	This function should be called at the beginning of light sample loops in material shaders. It enables renderpass contributions for lightshaders that were not developped using the AdskShaderSDK. Whenever such light shaders are used, pass contributions will continue to work for controlling light contributions, but not for controlling shadow casters. Only SDK-compliant light shaders support per-pass independent shadow casting.
void	hsv_to_rgb (const miColor *hsv, miColor *rgb)
	Convert HSV color to RGB.
void	rgb_to_hsv (const miColor *rgb, miColor *hsv)
	Convert RGB color to HSV.
void	get_derivs (miState *state, miVector *u, miVector *v, int space, int tangentSet)
	Retrieve derivatives at point.
void	compute_refraction (miColor *resRefr, miColor *resTrsp, miInteger *pRefractionLimit, miScalar *pRefractiveIndex, miBoolean refractions, const miColor *transparency, miBoolean hideSource, miScalar *pRefractionBlur, miInteger *pRefractionBlurLimit, miInteger *pRefractionRays, miScalar *pSurfaceThickness, miScalar *pTransparencyDepth, miScalar *pLightAbsorbance, miBoolean *pChromaticAberration, miVector *normal, float dot_nd, miState *state, unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, PassTypeInfo *pPassTypeInfo, const miScalar &pFrameBufferScale)
	Compute the reflection at the current point.
void	compute_reflection (miColor *resRefl, miScalar reflectivity, const miColor *specularColor, miScalar glowIntensity, miColor *pReflectedColor, miInteger *pReflectionLimit, miScalar *pReflectionBlur, miInteger *pReflectionBlurLimit, miInteger *pReflectionRays, miBoolean hideSource, miVector *normal, float dot_nd, miState *state, unsigned int pNumberOfFrameBuffers, FrameBufferInfo *pFrameBufferInfo, PassTypeInfo *pPassTypeInfo, const miScalar &pFrameBufferScale)
	Compute the reflection at the current point.
void	compute_irradiance (miColor *resIrrad, miColor *pIrradianceColor, float diffuse, const miColor *color, const miColor *transparency, miScalar glowIntensity, miColor *pIrradiance, miState *state)
	Compute irradiance for material.
float	compute_lambert_translucence (miState *state, float cos_nl, miVector *ldir, miScalar translucence, miScalar translucenceFocus, miScalar translucenceDepth, void *blindData)
	Compute lambertian translucence.
float	compute_phong_specular (miVector *ldir, miScalar cosinePower, miScalar reflectionSpecularity, miVector *reflDirection, miState *state)
	Compute phong specular value.
float	compute_blinn_specular (float cos_nl, float cos_nv, miVector *ldir, miScalar eccentricity, miScalar specularRollOff, miScalar reflectionSpecularity, miVector *normal, miState *state)
	Compute blinn specular value.
float	compute_hairtubeshader_specular (miScalar specularPower, const miVector *lightDir, const miVector *viewDir, const miVector *tubeDir)
	Compute specular for hair tube shader.
float	arealight_lambertian_reflect (const miVector *point, const miVector *normal, const void *blindData)
	Compute area light lambertian reflection.
void	arealight_max_phong_spec_dir (const miVector *point, const miVector *direction, const void *blindData, miTag lightInst, miVector *result)
	Compute area light maximum phong specular direction.

---

Function Documentation

template<typename T>

miBoolean accumulateLightSample	(	const miState *	pState,
		const T &	pValue,
		FrameBufferInfo &	pFrameBufferInfo,
		const bool &	pUseIrradiance,
		const miColor *const &	pIrradianceNoShadow = 0
	)			[inline]

Accumulates a frame buffer value for the current light sample.

Template Parameters:

T

The type to contribute to the frame buffer.

Parameters:

[in]	pState	mental ray state.
[in]	pValue	The value to accumulate.
[in]	pFrameBufferInfo	The frame buffer info of the buffer to be written to.
[in]	pUseIrradiance	Set to true if the value should be modulated by irradiance. This option should only be used inside a light loop.
[in]	pIrradianceNoShadow	Sample irradiance without shadows, used to compute differential shadow passes. When non-null, the difference between pIrradianceNoShadow and the sample irradiance is used as a lighting factor, instead of the sample irradiance.

template<class T>

void adskDeleteMIArray	(	T *	ptr,
		size_t	itemCount
	)			[inline]

Destruct and deallocate an object array on the mental ray heap.

Template Parameters:

T

The type of object array to delete.

Parameters:

[in]	ptr	reference to the object to be deleted.
[in]	itemCount	number of objects in the array.

template<class T>

void adskDeleteMIObject

(

T *

ptr

)

[inline]

Destruct and deallocate an object on the mental ray heap.

Template Parameters:

T

The type of object to delete.

Parameters:

[in]

ptr

reference to the object to be deleted.

void adskError

(

const string &

pString

)

Emit error from shader.

Parameters:

[in]

pString

The error message.

void adskFatal

(

const string &

pString

)

Emit fatal error from shader.

Parameters:

[in]

pString

The error message.

void adskInfo

(

const string &

pString

)

Emit information from shader.

Parameters:

[in]

pString

The information message.

template<class T>

T* adskNewMIArray

(

size_t

itemCount

)

[inline]

Allocate and construct an object array on the mental ray heap.

Template Parameters:

T

The type of object array to construct.

Parameters:

[in]

itemCount

number of objects in the array.

Returns:

pointer to the new object array

template<class T>

T* adskNewMIObject

(

)

[inline]

Allocate and construct an object on the mental ray heap.

Template Parameters:

T

The type of object to construct.

Returns:

pointer to the new object

void adskWarning

(

const string &

pString

)

Emit fatal warning from shader.

Parameters:

[in]

pString

The warning message.

template<typename T, typename F>

T applyScale	(	const T &	value,
		const F &	scale
	)			[inline]

Scaling function used internally by operateOnFrameBuffer.

This function ensures that proper rounding takes place when and only when dealing with miInteger frame buffer values. It also takes care of using the color luminance when scaling a scalar using a color.

Template Parameters:

	T	Type to scale.
	F	Type to scale by.

Parameters:

[in]	value	Value to scale.
[in]	scale	Amount to scale by.

Returns:

value scaled by amount scale.

template<>

miInteger applyScale< miInteger, miColor >	(	const miInteger &	value,
		const miColor &	scale
	)			[inline]

Template specialization of applyScale for integers and colors. Should not be used.

Parameters:

[in]	value	Value to scale.
[in]	scale	Amount to scale by.

Returns:

value scaled by amount scale.

template<>

miInteger applyScale< miInteger, miScalar >	(	const miInteger &	value,
		const miScalar &	scale
	)			[inline]

Template specialization of applyScale for integers and scalars.

Parameters:

[in]	value	Value to scale.
[in]	scale	Amount to scale by.

Returns:

value scaled by amount scale.

template<>

miScalar applyScale< miScalar, miColor >	(	const miScalar &	value,
		const miColor &	scale
	)			[inline]

Template specialization of applyScale for scalars and colors.

Parameters:

[in]	value	Value to scale.
[in]	scale	Amount to scale by.

Returns:

value scaled by amount scale.

template<>

miVector applyScale< miVector, miColor >	(	const miVector &	value,
		const miColor &	scale
	)			[inline]

Template specialization of applyScale for vectors and colors.

Parameters:

[in]	value	Value to scale.
[in]	scale	Amount to scale by.

Returns:

value scaled by amount scale.

miBoolean applyShadowTransparencyToFrameBuffers	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		const miColor &	pTransparency,
		miState *	pState
	)

Applies the shadow opacity of the current object to all relevant frame buffer states. Note: should only be called from shadow shaders.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures
[in]	pTransparency	The shadow transparency of the current material
[in]	pState	the shading state

Returns:

returns true if the light path is not completely opaque for at least one frame buffer for which shadows are computed.

float arealight_lambertian_reflect	(	const miVector *	point,
		const miVector *	normal,
		const void *	blindData
	)

Compute area light lambertian reflection.

Parameters:

[in]	point	The point to compute at.
[in]	normal	The normal
[in]	blindData	Custom light data

Returns:

The area light lambertian reflection

void arealight_max_phong_spec_dir	(	const miVector *	point,
		const miVector *	direction,
		const void *	blindData,
		miTag	lightInst,
		miVector *	result
	)

Compute area light maximum phong specular direction.

Parameters:

[in]	point	The point to compute at.
[in]	direction	The direction
[in]	blindData	Custom light data
[in]	lightInst	The light instance
[out]	result	The direction result

template<typename T>

T clampedRemap	(	const T &	pValue,
		const T &	pOldMinimum,
		const T &	pOldMaximum,
		const T &	pNewMinimum,
		const T &	pNewMaximum
	)			[inline]

Remap value to new range and clamp to that range.

Template Parameters:

T

Type to perform computation with.

Parameters:

[in]	pValue	Value to remap.
[in]	pOldMinimum	Old minimum value.
[in]	pOldMaximum	Old maximum value.
[in]	pNewMinimum	New minimum value.
[in]	pNewMaximum	New maximum value.

Returns:

The remapped, clamped value.

float compute_blinn_specular	(	float	cos_nl,
		float	cos_nv,
		miVector *	ldir,
		miScalar	eccentricity,
		miScalar	specularRollOff,
		miScalar	reflectionSpecularity,
		miVector *	normal,
		miState *	state
	)

Compute blinn specular value.

Parameters:

[in]	cos_nl	Dot product of normal and light
[in]	cos_nv	Dot product of normal and direction
[in]	ldir	Light direction
[in]	eccentricity	Eccentricity
[in]	specularRollOff	Specular rolloff
[in]	reflectionSpecularity	Reflection specularity
[in]	normal	normal
[in]	state	Pointer to mental ray state

Returns:

The Blinn specular value.

float compute_hairtubeshader_specular	(	miScalar	specularPower,
		const miVector *	lightDir,
		const miVector *	viewDir,
		const miVector *	tubeDir
	)

Compute specular for hair tube shader.

Parameters:

[in]	specularPower	Specular power
[in]	lightDir	Light direction
[in]	viewDir	View direction
[in]	tubeDir	Tube direction

Returns:

The hair tube shader specular value.

void compute_irradiance	(	miColor *	resIrrad,
		miColor *	pIrradianceColor,
		float	diffuse,
		const miColor *	color,
		const miColor *	transparency,
		miScalar	glowIntensity,
		miColor *	pIrradiance,
		miState *	state
	)

Compute irradiance for material.

Parameters:

[out]	resIrrad	Irradiance result
[in]	pIrradianceColor	Irradiance color
[in]	diffuse	Diffuse factor
[in]	color	Diffuse color
[in]	transparency	Transparency
[in]	glowIntensity	Glow intensity
[in]	pIrradiance	Irradiance
[in,out]	state	Pointer to mental ray state

float compute_lambert_translucence	(	miState *	state,
		float	cos_nl,
		miVector *	ldir,
		miScalar	translucence,
		miScalar	translucenceFocus,
		miScalar	translucenceDepth,
		void *	blindData
	)

Compute lambertian translucence.

Parameters:

[in,out]	state	Pointer to mental ray state
[in]	cos_nl	Dot product of normal and light
[in]	ldir	Light direction
[in]	translucence	translucence
[in]	translucenceFocus	Translucence focus
[in]	translucenceDepth	Translucence depth
[in]	blindData	Light data

Returns:

Lambertian translucence value.

float compute_phong_specular	(	miVector *	ldir,
		miScalar	cosinePower,
		miScalar	reflectionSpecularity,
		miVector *	reflDirection,
		miState *	state
	)

Compute phong specular value.

Parameters:

[in]	ldir	Light direction
[in]	cosinePower	Cosine power
[in]	reflectionSpecularity	Reflection specularity
[in]	reflDirection	Reflection direction
[in,out]	state	Pointer to mental ray state

Returns:

Phong specular value

void compute_reflection	(	miColor *	resRefl,
		miScalar	reflectivity,
		const miColor *	specularColor,
		miScalar	glowIntensity,
		miColor *	pReflectedColor,
		miInteger *	pReflectionLimit,
		miScalar *	pReflectionBlur,
		miInteger *	pReflectionBlurLimit,
		miInteger *	pReflectionRays,
		miBoolean	hideSource,
		miVector *	normal,
		float	dot_nd,
		miState *	state,
		unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		PassTypeInfo *	pPassTypeInfo,
		const miScalar &	pFrameBufferScale
	)

Compute the reflection at the current point.

Parameters:

[out]	resRefl	Reflection result
[in]	reflectivity	Reflectivity of material
[in]	specularColor	Specular color
[in]	glowIntensity	Glow intensity
[in]	pReflectedColor	Reflected color
[in]	pReflectionLimit	Reflection limit
[in]	pReflectionBlur	Reflection blur
[in]	pReflectionBlurLimit	Reflection blur limit
[in]	pReflectionRays	Reflection rays
[in]	hideSource	Hide source
[in]	normal	normal
[in]	dot_nd	Dot product of normal and direction
[in,out]	state	Pointer to mental ray state
[in]	pNumberOfFrameBuffers	Number of frame buffers
[in]	pFrameBufferInfo	Frame buffer information
[in]	pPassTypeInfo	The array pass type info structures.
[in]	pFrameBufferScale	Frame buffer scale

void compute_refraction	(	miColor *	resRefr,
		miColor *	resTrsp,
		miInteger *	pRefractionLimit,
		miScalar *	pRefractiveIndex,
		miBoolean	refractions,
		const miColor *	transparency,
		miBoolean	hideSource,
		miScalar *	pRefractionBlur,
		miInteger *	pRefractionBlurLimit,
		miInteger *	pRefractionRays,
		miScalar *	pSurfaceThickness,
		miScalar *	pTransparencyDepth,
		miScalar *	pLightAbsorbance,
		miBoolean *	pChromaticAberration,
		miVector *	normal,
		float	dot_nd,
		miState *	state,
		unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		PassTypeInfo *	pPassTypeInfo,
		const miScalar &	pFrameBufferScale
	)

Compute the reflection at the current point.

Parameters:

[out]	resRefr	Refraction result
[out]	resTrsp	Transparency result
[in]	pRefractionLimit	Refraction limit
[in]	pRefractiveIndex	Refractive index
[in]	refractions	refractions
[in]	transparency	transparency
[in]	hideSource	Hide source
[in]	pRefractionBlur	Refraction blur
[in]	pRefractionBlurLimit	Refraction blur limit
[in]	pRefractionRays	Refraction rays
[in]	pSurfaceThickness	Surface thickness
[in]	pTransparencyDepth	Transparency depth
[in]	pLightAbsorbance	Light absorbance
[in]	pChromaticAberration	Chromatic aberration
[in]	normal	normal
[in]	dot_nd	Dot product of normal and direction
[in,out]	state	Pointer to mental ray state
[in]	pNumberOfFrameBuffers	Number of frame buffers
[in]	pFrameBufferInfo	Frame buffer information
[in]	pPassTypeInfo	Pass type information
[in]	pFrameBufferScale	Frame buffer scale

void convertToNormalizedPixels	(	const miState *	pState,
		miVector &	vec
	)			[inline]

Convert pixel aspect ratio.

Parameters:

[in,out]	pState	Pointer to mental ray state.
[out]	vec	Result vector.

void get_derivs	(	miState *	state,
		miVector *	u,
		miVector *	v,
		int	space,
		int	tangentSet
	)

Retrieve derivatives at point.

Parameters:

[in,out]	state	Pointer to the mental ray state.
[in]	u	u-coordinate for derivative.
[in]	v	v-coordinate for derivative.
[in]	space	Space to compute derivatives in.
[in]	tangentSet	Tangent set to retrieve derivatives for.

miUint getNamedFrameBufferID	(	const miState *	pState,
		const miTag	pBufferTag
	)

Obtain the numeric ID for a named frame buffer.

Parameters:

[in]	pState	mental ray state
[in]	pBufferTag	The tag for the named frame buffer.

Returns:

The ID of the named frame buffer.

miUint getNamedFrameBufferID	(	const miState *	pState,
		const char *	pBufferName
	)

Obtain the numeric ID for a named frame buffer.

Parameters:

[in]	pState	mental ray state
[in]	pBufferName	The name of the buffer to look up.

Returns:

The ID of the named frame buffer.

void handleNonAdskLights	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		const miColor &	pLightColor,
		miTag	pLightInstance,
		miState *	pState
	)

This function should be called at the beginning of light sample loops in material shaders. It enables renderpass contributions for lightshaders that were not developped using the AdskShaderSDK. Whenever such light shaders are used, pass contributions will continue to work for controlling light contributions, but not for controlling shadow casters. Only SDK-compliant light shaders support per-pass independent shadow casting.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures
[in]	pLightColor	The light color used for the Master Beauty pass
[in]	pLightInstance	The light instance currently being evaluated
[in]	pState	the shading state

void hsv_to_rgb	(	const miColor *	hsv,
		miColor *	rgb
	)

Convert HSV color to RGB.

Parameters:

[in]	hsv	The HSV color.
[out]	rgb	The result RGB color.

template<typename T>

T lerp	(	const T &	t,
		const T &	a,
		const T &	b
	)			[inline]

Computer linear interpolation.

Template Parameters:

T

Type to perform computation with.

Parameters:

[in]	t	Split parameter.
[in]	a	Start value.
[in]	b	End value.

Returns:

Linearly interpolated value.

template<typename T>

T linearRamp	(	const T &	a,
		const T &	b,
		const T &	x
	)			[inline]

Computer linear ramp.

Template Parameters:

T

Type to perform computation with.

Parameters:

[in]	a	a value.
[in]	b	b value.
[in]	x	x value.

Returns:

Linear ramp value.

template<typename T>

T MAYA_CLAMP	(	const T &	x,
		const T &	a,
		const T &	b
	)			[inline]

Clamp value to range.

Template Parameters:

T

Type of value to clamp.

Parameters:

[in]	x	Value to clamp.
[in]	a	Minimum value for clamp.
[in]	b	Minimum value for clamp.

Returns:

x clamped to range [a,b].

bool MAYA_ISZERO

(

const miScalar

a

)

[inline]

Is value effectively zero.

Parameters:

[in]

a

Value.

Returns:

True if the value is within MAYA_EPS of zero.

template<typename T>

T MAYA_MAX	(	const T &	x,
		const T &	y
	)			[inline]

Find maximum value.

Template Parameters:

T

Type of value to find minimum.

Parameters:

[in]	x	First value.
[in]	y	Second value.

Returns:

Maximum of x and y.

template<typename T>

T MAYA_MIN	(	const T &	x,
		const T &	y
	)			[inline]

Find minimum value.

Template Parameters:

T

Type of value to find minimum.

Parameters:

[in]	x	First value.
[in]	y	Second value.

Returns:

Minimum of x and y.

template<typename T>

miBoolean operateOnFrameBuffer	(	const miState *	pState,
		const T &	pValue,
		FrameBufferInfo &	pFrameBufferInfo,
		const miInteger &	pFrameBufferWriteOperation,
		const miInteger &	pFrameBufferWriteFlags,
		const miScalar &	pFrameBufferWriteFactor,
		const bool &	pUseIrradiance,
		const miColor *const &	pIrradianceNoShadow = 0
	)			[inline]

Perform the desired operation on a frame buffer.

This function will retrieve the existing value in a frame buffer at the sample location in raster space, and will perform the desired operation with the given value, and write it back to the frame buffer.

Parameters:

[in]	pState	mental ray state.
[in]	pValue	The value to use in the operation.
[in]	pFrameBufferInfo	The info structure on the frame buffer to operate on.
[in]	pFrameBufferWriteOperation	The operation to be performed.
[in]	pFrameBufferWriteFlags	The flags pertaining to the operation.
[in]	pFrameBufferWriteFactor	The scaling factor to be used based on the flags.
[in]	pUseIrradiance	Set to true if the value should be modulated by irradiance. This option should only be used inside a light loop.
[in]	pIrradianceNoShadow	Sample irradiance without shadows, used to compute differential shadow passes. When non-null, the difference between pIrradianceNoShadow and the sample irradiance is used as a lighting factor, instead of the sample irradiance.

Returns:

The result code from the write. miTRUE on success, miFALSE on error.

template<typename T>

void operateOnFrameBuffersOfType	(	const miState *	pState,
		const T &	pValue,
		FrameBufferInfo *const	pFrameBufferInfo,
		PassTypeInfo *const	pPassTypeInfo,
		const PassTypeID &	pTypeID,
		const miInteger &	pFrameBufferWriteOperation,
		const miInteger &	pFrameBufferWriteFlags,
		const miScalar &	pFrameBufferWriteFactor,
		const bool &	pUseIrradiance,
		const miColor *const &	pIrradianceNoShadow = 0
	)			[inline]

Operate on all frame buffers of a given material pass type.

For all frame buffers of a given type, this function will perform the desired operation. If in light sampling mode (called between lightSampleBegin and lightSampleEnd), the value will simply be accumulated in a temporary location and the actual operation will be performed by lightSampleEnd.

Template Parameters:

T

The type to contribute to the frame buffer.

Parameters:

[in]	pState	mental ray state.
[in]	pValue	The value to add.
[in]	pFrameBufferInfo	The array of frame buffer info structures.
[in]	pPassTypeInfo	The array pass type info structures.
[in]	pTypeID	Only frame buffers of this type will be written to.
[in]	pFrameBufferWriteOperation	The operation to be performed.
[in]	pFrameBufferWriteFlags	The flags pertaining to the operation.
[in]	pFrameBufferWriteFactor	The scaling factor to be used based on the flags.
[in]	pUseIrradiance	Set to true if the value should be modulated by irradiance. This option should only be used inside a light loop.
[in]	pIrradianceNoShadow	Sample irradiance without shadows, used to compute differential shadow passes. When non-null, the difference between pIrradianceNoShadow and the sample irradiance is used as a lighting factor, instead of the sample irradiance.

void operateOnNormalMaterialFrameBuffersOfType	(	const miState *	pState,
		miVector	pValue,
		FrameBufferInfo *const	pFrameBufferInfo,
		PassTypeInfo *const	pPassTypeInfo,
		const miInteger &	pFrameBufferWriteOperation,
		const miInteger &	pFrameBufferWriteFlags,
		const miScalar &	pFrameBufferWriteFactor
	)			[inline]

Operate on material normal frame buffers.

For all material normal frame buffers, this function will perform the desired operation.

Parameters:

[in]	pState	mental ray state.
[in]	pValue	The value to add.
[in]	pFrameBufferInfo	The array of frame buffer info structures.
[in]	pPassTypeInfo	The array pass type info structures.
[in]	pFrameBufferWriteOperation	The operation to be performed.
[in]	pFrameBufferWriteFlags	The flags pertaining to the operation.
[in]	pFrameBufferWriteFactor	The scaling factor to be used based on the flags.

template<typename T>

T remap	(	const T &	pValue,
		const T &	pOldMinimum,
		const T &	pOldMaximum,
		const T &	pNewMinimum,
		const T &	pNewMaximum
	)			[inline]

Remap value to new range.

Template Parameters:

T

Type to perform computation with.

Parameters:

[in]	pValue	Value to remap.
[in]	pOldMinimum	Old minimum value.
[in]	pOldMaximum	Old maximum value.
[in]	pNewMinimum	New minimum value.
[in]	pNewMaximum	New maximum value.

Returns:

The remapped value.

void rgb_to_hsv	(	const miColor *	rgb,
		miColor *	hsv
	)

Convert RGB color to HSV.

Parameters:

[in]	rgb	The RGB color.
[out]	hsv	The result HSV color.

void sampleLightBegin	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo
	)

Function to be called before all light sampling loops. Takes care of initializing light sample accumulators.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures

void sampleLightEnd	(	miState *	pState,
		unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		const int	pSamples,
		const miInteger &	pFrameBufferWriteOperation,
		const miInteger &	pFrameBufferWriteFlags,
		const miScalar &	pFrameBufferWriteFactor
	)

Function to be called after all light sampling loops. Takes care of combining sample values into the material frame buffer values.

Parameters:

[in]	pState	the shading state
[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures
[in]	pSamples	The number of times the current light was sampled
[in]	pFrameBufferWriteOperation	The operation to be performed.
[in]	pFrameBufferWriteFlags	The flags pertaining to the operation.
[in]	pFrameBufferWriteFactor	The scaling factor to be used based on the flags.

void setLightIrradiance	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		const miColor &	pLightColor
	)

When not rendering with shadows, this function is called to set the irradiance value for the current light Note: should only be called from a light shader.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures
[in]	pLightColor	unattenuated irradiance

void setupLightContributions	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		miState *	pState
	)

Initializes the frame buffer states for receiving illumination information Note: should be called at the beginning of a light shader.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures
[in]	pState	the shading state

void tracePassAdd	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		miState *	pState,
		miColor	pFactor,
		bool	pIsRefraction
	)

Composite the frame buffer states after a series of reflection and/or refraction trace recursions.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures
[in]	pState	shading state
[in]	pFactor	the light transport factor
[in]	pIsRefraction	must be set to true if the the traced rays were refraction rays.

void tracePassInit	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		miState *	pState
	)

Prepare the frame buffer states for a series of reflection and/or refraction trace recursions.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures
[in]	pState	shading state

bool traceShadow	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		miColor &	pFilter,
		const miColor &	pLightColor,
		const miColor &	pShadowColor,
		bool	pUsingShadowMap,
		miState *	pState
	)

Trace a shadow ray using per frame-buffer lighting Note: should only be called from a light shader.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures
[out]	pFilter	attenuation factor cause by shadows
[in]	pLightColor	unattenuated irradiance
[in]	pShadowColor	Shadow Color
[in]	pUsingShadowMap	must be set to true if shadow maps are used
[in]	pState	shading state

Returns:

false if full occlusion is detected

bool traceShadowAccumulate	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		miColor &	pFilter,
		miState *	pState
	)

Trace a shadow ray and accumulate results for per frame-buffer lighting Note: should only be called from a light shader, between calls to traceShadowAccumulateBegin and traceShadowAccumulateEnd.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures
[out]	pFilter	attenuation factor cause by shadows
[in]	pState	shading state

void traceShadowAccumulateBegin	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo
	)

Initialize frame buffer states for shadow area sampling, used for area lights, final gathering, etc. Note: should only be called from a light shader when not using a shadow map.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures

void traceShadowAccumulateEnd	(	unsigned int	pNumberOfFrameBuffers,
		FrameBufferInfo *	pFrameBufferInfo,
		unsigned int	pNumberOfRays,
		const miColor &	pLightColor,
		const miColor &	pShadowColor,
		miState *	pState
	)

Process accumulated shadow rays for light sampling Note: should only be called from a light shader when not using a shadow map.

Parameters:

[in]	pNumberOfFrameBuffers	the number of frame buffers in the state
[in,out]	pFrameBufferInfo	the array of frame buffer info structures
[in]	pNumberOfRays	the number of rays cast during the accumulation process
[in]	pLightColor	unattenuated irradiance
[in]	pShadowColor	Shadow Color
[in]	pState	shading state