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.
bool	checkPassType (PassTypeInfo *const pPassTypeInfo, unsigned int pPassID, unsigned int pTypeID)
	Check if the pass is the given type.
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, bool pVolumeShadows, 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,
		bool	pVolumeShadows,
		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]`	pVolumeShadows	Must be set to true when evaluating volume shadows
`[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

bool checkPassType	(	PassTypeInfo *const	pPassTypeInfo,
		unsigned int	pPassID,
		unsigned int	pTypeID
	)			`[inline]`

Check if the pass is the given type.

Parameters:

`[in]`	pPassTypeInfo	PassTypeInfo.
`[in]`	pPassID	the pass index.
`[in]`	pTypeID	pass type.

Returns:: x true if the pass, pPassID is the given type pTypeID. false otherwise

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

adskUtilities.h File Reference

Detailed Description

Functions

Function Documentation