Technical Reference

material property with the proper bulk absorption coefficient and apply it to your scattering object.

User Defined Bulk Scatter Expert

TracePro Expert provides new functionality to define phase functions for Bulk Scattering through compiled Dynamic Link Libraries (DLLs). Data from TracePro is passed into the DLL during raytrace. The DLL calculates a result, which is passed back to TracePro and used to scatter the ray. The Bulk Scatter Editor is used to select the desired DLL and to add user parameter data to control the calculations performed in the DLL. The TracePro random number function is accessible through the DLL initialization

Using Scatter DLLs

Using a bulk scatter phase function from a DLL is similar to using any existing Bulk Scatter property. The TracePro Bulk Scatter editor is opened and allows the appropriate user compiled DLL to be selected and for user parameters to be entered. The parameter data along with the DLL information is stored in the TracePro property database.

A new property entry is made by pressing the Add Bulk Scatter button in the Bulk Scatter property editor. Several scattering types are available including User DLL.

The DLL name with its location is entered in the DLL Name edit box. The Browse button may be user to navigate the computer's hard disk to locate the appropriate file. The spreadsheet rows allow user data to be added for use by the DLL during the raytrace. Each row allows six (6) coefficients with a wavelength. The data however, is passed to the DLL in its entirety and does not use the wavelength data as such.

Required DLL Functions called from TracePro

fnInitDll

Action:	Initialize DLL
Syntax:	BULK_API double fnInitDll(RAND_FN address)
Arg Types:	address	RAND_FN
Returns:	double	(ignored by TracePro)
Errors:	An error will be printed to the Macro Window if the function fails or does not exist in the
	DLL.
Description:	The Initialization function will pass in the address of the TracePro random number
	generator. Any other initialization may be performed done here. This routine is called after
Limitations:	the DLL is loaded by TracePro
	Not applicable
Example:

// This initializes the DLL

BULK_API double fnInitDll(RAND_FN address)

{

random_function = address; return (double) 1.0;

}

7.56	TracePro 5.0 User’s Manual

		Bulk Scattering
	fnMeanFreePath
Action:	Return the mean free path.
Syntax:	BULK_API double fnMeanFreePath(double wave, double temp, double rindex, double
	bulkabso, int num, double *coef);
Arg Types:	wave	double
	temp	double
	rindex	double
	bulkabso	double
	num	integer
	coef	double array
Returns:	double
Errors:	An error will be printed to the Macro Window if the function fails or does not exist in the
	DLL.
Description:	During importance sampling, TracePro generates a ray for a given solid angle. This function
	returns the fraction of the total scatter contained in the solid angle defined by the importance
	target from the origin of the scattered ray. TracePro passes the cosine of the solid angle as the
	last argument (angle).
	Return the scatter fraction for a which is scattered
Limitations:	Not applicable
Example:
	// This returns the mean free path
	BULK_API double fnMeanFreePath(double wave,
		double temp,
		double rindex,
		double bulkabso,
		int num,
	{	double *coef)
	if ( coef == NULL )
	return (double) 1.0;
	if ( coef[3] > 0 )
	return 1.0 / coef[3];
	return 1.0;
	}
	fnEvaluateBSDF
Action:	Return the scatter fraction for ray scattered in a particular solid angle
Syntax:	BULK_API double fnEvaluateBSDF(double wave, double temp, double rindex, double
	bulkabso, int num, double *coef, double cos_alpha);
Arg Types:	wave	double
	temp	double
	rindex	double
	bulkabso	double
	num	integer
	coef	double array
	cos_alpha	double
Returns:	double

TracePro 5.0 User’s Manual

7.57

Technical Reference

Errors:	An error will be printed to the Macro Window if the function fails or does not exist in the
	DLL.
Description:	During importance sampling, TracePro generates a ray for a given solid angle. This function
	returns the fraction of the total scatter contained in the solid angle defined by the importance
	target from the origin of the scattered ray. TracePro passes the cosine of the solid angle as the
	last argument (angle).
Limitations:	Return the scatter fraction for a which is scattered
	Not applicable

Example:

// Return the scatter fraction for ray scattered in a particular solid angle

BULK_API double fnEvaluateBSDF(double wave, double temp, double rindex, double bulkabso, int num,

double *coef, double cos_alpha)

{

double result = 0;

if ( coef == NULL )

return (double) result;

double g = coef[2]; double g2 = g * g; double cos_temp;

if ( (g < -1.0) || (g > 1.0) )

{

// Error condition result = 0.0;

}

else if ( fabs(g) < LF_ROUNDOFF_TOL ) result = 1.0 / (4.0 * PI);

else

{

cos_temp = 1.0 + g2 - 2.0 * g * cos_alpha;

//There is an extra factor of 1/TWOPI to correctly

//normalize the bsdf (really sdf)

//compared to the Wang and Jacques paper. Their formula

//(eq. 14) is used only for deriving the

//polar c.d.f., because they never heard of importance

//sampling. Requiring that the integral

//of the probability distribution over a sphere is equal

//to one produces the extra factor of 1/TWOPI.

result = ( 1.0 - g2 )/( TWOPI * 2.0 * pow( cos_temp, 1.5 ) );

7.58	TracePro 5.0 User’s Manual

Bulk Scattering

}

return (result);

}

fnScatterDirection

Action:	Returns the cosine of the scatter in theta and the angle in phi
Syntax:	BULK_API double fnScatterDirection(double wave, double temp, double rindex, double
Arg Types:	bulkabso, int num, double *coef, double phi);
	wave	double
	temp	double
	rindex	double
	bulkabso	double
	num	integer
	coef	double array
	phi	double pointer
Returns:	double, and double pointer in phi
Errors:	An error will be printed to the Macro Window if the function fails or does not exist in the
	DLL.
Description:	During ray trace, the scattered ray direction is calculated by the following function within a
	volume scatter region. This function calculates the cosine of the theta scatter angle where a
	value of 1.0 is along the original ray direction and -1.0 reverses the ray direction. The phi angle
Limitations:	is then calculated about the ray direction and passed back to TracePro is phi.
	Not applicable

Example:

// This returns the cosine of the scatter in theta and the angle in phi

BULK_API double fnScatterDirection(double wave, double temp, double rindex, double bulkabso, int num,

double *coef, double *phi)

{

double cos_theta = 1.0; *phi = 0.0;

if ( coef == NULL )

return (double) cos_theta;

double g = coef[2]; double g2 = g * g; double cos_temp;

if ( fabs(g) < SMALLANGLE ) cos_theta = 2.0*frand() - 1.0;

TracePro 5.0 User’s Manual

7.59