Cg functions

The Cg function table:

Functions

Function Description
abs( x ) Absolute value of x .
acos( x ) Arccosine of x in range [0, p], x in [–1, 1].
all( x ) Returns true if every component of x is not equal to 0. Returns false otherwise.
any( x ) Returns true if any component of x is not equal to 0. Returns false otherwise.
asin( x ) Arcsine of x in range [–p/2, p/2]; x should be in [–1, 1].
atan( x ) Arctangent of x in range [–p/2, p/2].
atan2( y , x ) Arctangent of y / x in range [–p, p].
ceil( x ) Smallest integer not less than x .
clamp( x , a , b ) x clamped to the range [ a , b ] as follows: Returns a if x is less than a . Returns b if x is greater than b . Returns x otherwise.
cos( x ) Cosine of x .
cosh( x ) Hyperbolic cosine of x .
cross( A , B ) Cross product of vectors A and B ; A and B must be three-component vectors.
ddx( a ) Approximate partial derivative of a with respect to screen-space x coordinate
ddy( a ) Approximate partial derivative of a with respect to screen-space y coordinate
void debug(float4 x ) If the compiler's DEBUG option is enabled, calling this function causes the value x to be copied to the COLOR output of the program, and execution of the program is terminated. If the compiler's DEBUG option is not enabled, this function does nothing.
determinant( M ) Determinant of matrix M .
distance( pt1 , pt2 ) Euclidean distance between points pt1 and pt2 .
dot( A , B ) Dot product of vectors A and B .
exp( x ) Exponential function e x .
exp2( x ) Exponential function 2 x .
faceforward( N , I , Ng ) N if dot( Ng , I ) < 0; - N otherwise.
floor( x ) Largest integer not greater than x .
fmod( x , y ) Remainder of x / y , with the same sign as x . If y is 0, the result is implementation-defined.
frac( x ) Fractional part of x .
frexp( x , out exp ) Splits x into a normalized fraction in the interval [½, 1), which is returned, and a power of 2, which is stored in exp . If x is 0, both parts of the result are 0.
isfinite( x ) Returns true if x is finite.
isinf( x ) Returns true if x is infinite.
isnan( x ) Returns true if x is NaN (Not a Number).
ldexp( x , n ) x x 2 n .
length( v ) Euclidean length of a vector.
lerp( a , b , f ) Linear interpolation: (1 – f )* a + b * f where a and b are matching vector or scalar types. f can be either a scalar or a vector of the same type as a and b .
lit( NdotL , NdotH , m ) Computes lighting coefficients for ambient, diffuse, and specular light contributions. Expects the NdotL parameter to contain N L and the NdotH parameter to contain N H . Returns a four-component vector as follows: The x component of the result vector contains the ambient coefficient, which is always 1.0. The y component contains the diffuse coefficient, which is 0 if ( N L ) < 0; otherwise ( N L ). The z component contains the specular coefficient, which is 0 if either ( N L ) < 0 or ( N H ) < 0; ( N H ) m otherwise. The w component is 1.0. There is no vectorized version of this function.
log( x ) Natural logarithm ln( x ) ; x must be greater than 0.
log2( x ) Base 2 logarithm of x ; x must be greater than 0.
log10( x ) Base 10 logarithm of x ; x must be greater than 0.
max( a , b ) Maximum of a and b .
min( a , b ) Minimum of a and b .
modf( x , out ip ) Splits x into integral and fractional parts, each with the same sign as x . Stores the integral part in ip and returns the fractional part.
mul( M , N ) Matrix product of matrix M and matrix N , as shown below: If M has size A x B , and N has size B x C , returns a matrix of size A x C .
mul( M , v ) Product of matrix M and column vector v , as shown below: If M is an A x B matrix and v is a B x 1 vector, returns an A x 1 vector.
mul( v , M ) Product of row vector v and matrix M , as shown below: If v is a 1 x A vector and M is an A x B matrix, returns a 1 x B vector.
noise( x ) Either a one-, two-, or three-dimensional noise function, depending on the type of its argument. The returned value is between 0 and 1, and is always the same for a given input value.
normalize( v ) Returns a vector of length 1 that points in the same direction as vector v .
pow( x , y ) xy .
reflect( I , N ) Computes reflection vector from entering ray direction I and surface normal N . Valid only for three-component vectors.
refract( I , N , eta ) Given entering ray direction I , surface normal N , and relative index of refraction eta , computes refraction vector. If the angle between I and N is too large for a given eta , returns (0, 0, 0). Valid only for three-component vectors.
round( x ) Closest integer to x .
rsqrt( x ) Reciprocal square root of x ; x must be greater than 0.
saturate( x ) Clamps x to the [0, 1] range.
sign( x ) 1 if x > 0; –1 if x < 0; 0 otherwise.
sin( x ) Sine of x .
sincos(float x , out s , out c ) s is set to the sine of x , and c is set to the cosine of x . If both sin( x ) and cos( x ) are needed, this function is more efficient than calculating each individually.
sinh( x ) Hyperbolic sine of x .
smoothstep( min , max , x ) For values of x between min and max , returns a smoothly varying value that ranges from 0 at x = min to 1 at x = max . x is clamped to the range [ min , max ] and then the interpolation formula is evaluated: –2*(( x min )/( max min ))3 + 3*(( x min )/( max min ))2
step( a , x ) 0 if x < a ; 1 if x >= a .
sqrt( x ) Square root of x ; x must be greater than 0.
tan( x ) Tangent of x .
tanh( x ) Hyperbolic tangent of x .
transpose( M ) Matrix transpose of matrix M . If M is an A x B matrix, the transpose of M is a B x A matrix whose first column is the first row of M , whose second column is the second row of M , whose third column is the third row of M , and so on.

Geometry Functions

Function Description

Texture Mapping

Only OpenGL profiles support the samplerRECT functions. All of the functions return a float4 value.

Function Description
• s indicates a one-, two-, or three-component texture coordinate.
• z indicates a depth comparison value for shadow map lookups.
• q indicates a perspective value, and is used to divide the texture coordinate ( s ) before the texture lookup is performed.

When you use the texture functions that allow specifying a depth comparison value, the associated texture unit must be configured for depth-compare texturing. Otherwise, no depth comparison will actually be performed.

E.4 Derivative Functions

Table E-4 presents the derivative functions that are supported by the Cg Standard Library. Vertex profiles do not support these functions.

Function

Description

E.5 Debugging Function

Table E-5 presents the debugging function that is supported by the Cg Standard Library. Vertex profiles are not required to support this function.

Table E-5. Debugging Function

Function

Description

The intent of the debug function is to allow a program to be compiled twice—once with the DEBUG option and once without. By executing both programs, it is possible to obtain one frame buffer containing the final output of the program and another frame buffer containing an intermediate value to be examined for debugging purposes.