texutil.h File Reference

#include "coreexp.h"
#include "point2.h"
#include "point3.h"
#include "acolor.h"

Macros
#define	MAX_OCTAVES   50
#define	NOISE(p)   ((1.0f+noise3DS(p))*.5f)
#define	MAX_CELL_LEVELS   20

Functions
CoreExport float	bias (float a, float b)
CoreExport float	gain (float a, float b)
CoreExport float	clamp (float x, float a, float b)
CoreExport float	boxstep (float a, float b, float x)
CoreExport float	smoothstep (float a, float b, float x)
CoreExport float	mod (float x, float m)
CoreExport int	mod (int x, int m)
CoreExport float	sramp (float x, float a, float b, float d)
CoreExport float	threshold (float x, float a, float b)
CoreExport void	setdebug (int i)
CoreExport float	noise1 (float arg)
CoreExport float	noise2 (Point2 p)
CoreExport float	noise3 (Point3 p)
CoreExport float	noise4 (Point3 p, float time)
CoreExport float	noise3DS (Point3 p)
CoreExport float	turbulence (Point3 &p, float freq)
CoreExport int	Perm (int v)
CoreExport float	fBm1 (float point, float H, float lacunarity, float octaves)
CoreExport float	fBm1 (Point2 point, float H, float lacunarity, float octaves)
CoreExport float	fBm1 (Point3 point, float H, float lacunarity, float octaves)
CoreExport float	spline (float x, int nknots, float *knot)
CoreExport Color	color_spline (float x, int nknots, Color *knot)
int	FLOOR (float x)
float	frac (float x)
float	fastfmax (float x, float y)
float	fastfmin (float x, float y)
AColor	AComp (AColor cbot, AColor ctop)
CoreExport void	CellFunction (Point3 v, int n, float *dist, int *celIDs=NULL, Point3 *grads=NULL, float gradSmooth=0.0f)
CoreExport void	FractalCellFunction (Point3 v, float iterations, float lacunarity, int n, float *dist, int *celIDs=NULL, Point3 *grads=NULL, float gradSmooth=0.0f)
CoreExport float	RandFromCellID (int id)

Macro Definition Documentation

MAX_OCTAVES

#define MAX_OCTAVES   50

NOISE

#define NOISE

(

p

)

((1.0f+noise3DS(p))*.5f)

MAX_CELL_LEVELS

#define MAX_CELL_LEVELS   20

Function Documentation

bias()

CoreExport float bias	(	float	a,
		float	b
	)

Remarks

This function performs a mapping across the unit interval [0, 1] where the result is within the unit interval. If b is within the interval 0 to 1, the result of bias() is within the interval 0 to 1. This function is defined such that bias(a, 0.5)=a. The function is defined as follows:

float bias(float a, float b) { 
return (float)pow(a, log(b) / log(0.5f)); 
} 

gain()

CoreExport float gain	(	float	a,
		float	b
	)

Remarks

This function performs a mapping across the unit interval [0, 1] where the result is within the unit interval. If b is within the interval 0 to 1, the result of gain() is within the interval 0 to 1. This function is defined such that gain(a, 0.5)=a. Above and below 0.5, this function consists of two scaled down bias() curves forming an S-shaped curve. The function is defined as follows:

float gain(float a, float b)
{ 
float p = (float)log(1.0f - b) / (float)log(0.5f); 
if (a < .001f) 
return 0.f; 
else if (a > .999f) 
return 1.0f; 
if (a < 0.5f) 
return (float)pow(2 * a, p) / 2; 
else 
return 1.0f - (float)pow(2.0 * (1. - a), (double)p) / 2; 
} 

clamp()

CoreExport float clamp	(	float	x,
		float	a,
		float	b
	)

Remarks

The clamp() function is defined as follows:

float clamp( float x, float a, float b) { 
return (x < a ? a : (x > b ? b : x)); 
} 

Parameters

x	A floating point value.
a	A floating point value.
b	A floating point value.

Returns

Returns "a" when "x" is less than "a", the value of "x" when "x" is between "a" and "b", and the value "b" when "x" is greater than "b".

boxstep()

CoreExport float boxstep	(	float	a,
		float	b,
		float	x
	)

Remarks

This function is a smoother version of step() using a linear ramp. The boxstep() function is defined as follows:

float boxstep(float a, float b, float x) { 
return clamp((x-a)/(b-a),0.0f, 1.0f); 
} 

For comparison, note that step() returns values of 0 when x is less than a and 1 when x is greater than or equal to a. This function is not a part of the SDK, but step() is defined as follows:

float step(float a, float x) { 
return (float)(x >= a); 
} 

Parameters

a	The limit for the x value where the function will return 0.
b	The limit for the x value where the function will return 1.
x	A floating point value.

Returns

0 if "x" is less than "a", a linear interpolation between 0 and 1 if "x" is greater than or equal to "a" and less than or equal to "b", and 1 if "x" is greater than "b".

smoothstep()

CoreExport float smoothstep	(	float	a,
		float	b,
		float	x
	)

Remarks

This function is similar to step(), but instead of a sharp transition from 0 to 1 at a specified threshold, it makes a gradual transition from 0 to 1 beginning at threshold a and ending at threshold b. To do this, this function uses a cubic function whose slope is 0 at "a" and "b", and whose value is 0 at "a" and 1 at "b". This function provides a still smoother version of step() using a cubic spline. The smoothstep() function is used (instead of step()) in many procedural textures because sharp transitions often result in artifacts.

Parameters

a	The limit for the x value where the function will return 0.
b	The limit for the x value where the function will return 1.
x	A floating point value.

mod() [1/2]

CoreExport float mod	(	float	x,
		float	m
	)

Remarks

This function returns the mathematical modulo operation and handles negatives correctly. The standard math functions fmod() and fmodf() as well as the operator % return negative results if the first operand is negative. This function always returns a positive remainder.

mod() [2/2]

CoreExport int mod	(	int	x,
		int	m
	)

Remarks

This function returns the mathematical modulo operation and handles negatives correctly. The standard math functions fmod() and fmodf() as well as the operator % return negative results if the first operand is negative. This function always returns a positive remainder.

sramp()

CoreExport float sramp	(	float	x,
		float	a,
		float	b,
		float	d
	)

Remarks

This function makes a type of straight-segment S curve. The parameters are x, a, b, and d. The algorithm is as follows:

for a+d < x < b-d sramp(x) = x

for a-d < x < a+d sramp() makes a smooth transition (parabolic) from sramp' = 0 to sramp' = 1

for b-d < x < b+d sramp() makes a smooth transition (parabolic) from sramp' = 1 to sramp' = 0

threshold()

CoreExport float threshold	(	float	x,
		float	a,
		float	b
	)

Remarks

Returns 0 if "x" is less than "a", 1 if "x" is greater than "b", otherwise it returns "x".

setdebug()

CoreExport void setdebug

(

int

i

)

noise1()

CoreExport float noise1

(

float

arg

)

Remarks

An approximation of white noise blurred to dampen frequencies beyond some value.

noise2()

CoreExport float noise2

(

Point2

p

)

Remarks

An approximation of white noise blurred to dampen frequencies beyond some value in two dimensions.

noise3()

CoreExport float noise3

(

Point3

p

)

Remarks

A noise function in three dimensions implemented by a pseudo-random tricubic spline. This function is an approximation of white noise blurred to dampen frequencies beyond some value.

noise4()

CoreExport float noise4	(	Point3	p,
		float	time
	)

Remarks

This function is an approximation of white noise blurred to dampen frequencies beyond some value in three dimensions, and time.

noise3DS()

CoreExport float noise3DS

(

Point3

p

)

Remarks

A noise function in three dimensions implemented by a pseudo-random tricubic spline. This is the same as noise3() scaled up by factor of 1.65 and clamped to -1,+1. The macro NOISE can be used to map the value returned from the noise3DS() function into interval [0,1].

turbulence()

CoreExport float turbulence	(	Point3 &	p,
		float	freq
	)

Remarks

This turbulence function is a simple fractal generating loop built on top of the noise function. It is used to make marble, clouds, explosions, and so on. It returns a value in the range [0, 1].

Perm()

CoreExport int Perm

(

int

v

)

Remarks

Takes the low 9 bits of an input value and returns a number in that range (0-512).

fBm1() [1/3]

CoreExport float fBm1	(	float	point,
		float	H,
		float	lacunarity,
		float	octaves
	)

Remarks

A fractional Brownian motion fractal (or fBm for short) that returns a floating point value. This version of the fBm is said to be "homogeneous" (the same everywhere) and "isotropic" (the same in all directions). There are versions of this function that accept an input floating point, Point2, and Point3 value.

fBm1() [2/3]

CoreExport float fBm1	(	Point2	point,
		float	H,
		float	lacunarity,
		float	octaves
	)

fBm1() [3/3]

CoreExport float fBm1	(	Point3	point,
		float	H,
		float	lacunarity,
		float	octaves
	)

spline()

CoreExport float spline	(	float	x,
		int	nknots,
		float *	knot
	)

Remarks

A one-dimensional Catmull-Rom interpolating spline through a set of knot values. The spline() function used to map a number into another number. The parameter of the spline is a floating point value. If x is 0, the result is the second knot value. If x is 1, the result is the final knot value. For values between 0 and 1, the value interpolates smoothly between the values of the knots from the second knot to the second to last knot. The first and last knot values determine the derivatives of the spline at the endpoint.

color_spline()

CoreExport Color color_spline	(	float	x,
		int	nknots,
		Color *	knot
	)

Remarks

A variant of the spline() function for mapping colors.

FLOOR()

int FLOOR ( float  x )

inline

Remarks

A fast version of the standard C function floor(). It returns a floating-point value representing the largest integer that is less than or equal to x.

{ return ((int)(x) - ((int)(x)>(x)? 1:0)); }

frac()

float frac ( float  x )

inline

Remarks

Returns the fraction (non-integer) part of the value passed. This is defined as x - (float)FLOOR(x).

{ return x - (float)FLOOR(x); }

fastfmax()

float fastfmax ( float  x, float  y  )

inline

Remarks

Returns the larger of two values (returns the second value in the case of equality).

{ return x>y?x:y;   }

fastfmin()

float fastfmin ( float  x, float  y  )

inline

Remarks

Returns x if it is less than y. Otherwise, y.

{ return x<y?x:y;   }

AComp()

AColor AComp ( AColor  cbot, AColor  ctop  )

inline

Remarks

Performs an alpha-composite of one color (ctop) on top of another (cbot), assuming pre-multiplied alpha.

                                              {
    float ia = 1.0f - ctop.a;
    return (ctop + ia*cbot);
    }

CellFunction()

CoreExport void CellFunction	(	Point3	v,
		int	n,
		float *	dist,
		int *	celIDs = NULL,
		Point3 *	grads = NULL,
		float	gradSmooth = 0.0f
	)

Remarks

This is the noise function used by the 3ds Max Cellular texture. The idea is that there is a set of cells randomly distributed through space. This function returns the distances to the closest cells. Developers using this function can refer to: A Cellular Basis Function by Steven Worley, and published in the SIGGRAPH 1996 Conference Procedings.

FractalCellFunction()

CoreExport void FractalCellFunction	(	Point3	v,
		float	iterations,
		float	lacunarity,
		int	n,
		float *	dist,
		int *	celIDs = NULL,
		Point3 *	grads = NULL,
		float	gradSmooth = 0.0f
	)

Remarks

A fractal version of CellFunction(). It has additional parameters for iterations and lacunariy.

RandFromCellID()

CoreExport float RandFromCellID

(

int

id

)

Remarks

Returns a random number in the range 0.0 to 1.0 based on a cell identifier.