MetaSL specification 1.2.2
14 March 2011

MetaSL standard library functions

abs	cross	isnan	normalize	step
acos	ddx	length	pow	tan
all	ddy	lerp	radians	tex1D
any	degrees	log	reflect	tex2D
asin	distance	log10	refract	tex3D
atan	dot	log2	rotate_basis	texCUBE
atan2	eval_at_wavelength	luminance	round	transform_from_local
bsdf_check_type	exp	max	rsqrt	transform_to_local
bsdf_choose_component	exp2	max_value	saturate	transpose
bsdf_component_sum	faceforward	max_value_wavelength	sign
bsdf_invalid_sample	floor	min	sin
ceil	fmod	min_value	sincos
clamp	frac	min_value_wavelength	smoothstep
cos	isfinite	modf	sqrt

Functions by category

Math functions
Geometric functions
Spectrum functions
BSDF functions
Texture functions
Derivatives

Function overloading in MetaSL

MetaSL provides a set of standard library functions that can be called in shader methods and in user-defined (global) functions. Most functions may be used with more than one data type for their return type and arguments; in this case, the function is said to be overloaded.

For example, the abs function returns the absolute value of its parameter. If it is called with an argument of type int, it returns a value of type int:

int abs(int x)

Call with an argument of type float, however, abs returns a float:

float abs(float x)

For aggregate types like float3, function abs will return an aggreate type of the same simple type, using the appropriate version of abs on each component:

float3 abs(float3 x)

To simplify the documentation of a given function, the various sets of data types are represented by the symbols in the following table. A symbol in a declaration represents the same actual type throughout the function.

For example, function max is described in this way:

N max( N a, N b)

The type chosen for N — a non-matrix numeric type — must be the same throughout the function call. For example, if the type of argument a is float3, then the type of argument b must also be of float3, and the function will return a value of float3.

float3 max(float3 a, float3 b)

However, five functions — clamp, fmod, lerp, pow, and smoothstep — can be used with mixed argument types. Each possible combination is therefore listed individually.

Symbols for combined types

Symbol	Types represented by the symbol	MetaSL type names
B	All Boolean types	bool bool2 bool3 bool4
I	All integer types	int int2 int3 int4
V	Vector floating-point types	float2 float3 float4 Color3 Color
F	Vector and scalar floating-point types	float float2 float3 float4 Color3 Color
C	Color types	Color3 Color Spectrum
S	F + `Spectrum` All non-matrix floating-point types	float float2 float3 float4 Color3 Color Spectrum
N	I + S All non-matrix numeric types	int int2 int3 int4 float float2 float3 float4 Color3 Color Spectrum
A	B + I + S All Boolean types and all non-matrix numeric types	bool bool2 bool3 bool4 int int2 int3 int4 float float2 float3 float4 Color3 Color Spectrum
M	Matrices of dimensions `{2,3,4}x{2,3,4}` containing elements of type `half`, `float`, or `double`.	half2x2 half2x3 half2x4 half3x2 half3x3 half3x4 half4x2 half4x3 half4x4 float2x2 float2x3 float2x4 float3x2 float3x3 float3x4 float4x2 float4x3 float4x4 double2x2 double2x3 double2x4 double3x2 double3x3 double3x4 double4x2 double4x3 double4x4

Math functions

N `abs(`N `x)`	Returns the absolute value of each vector component.
S `acos(`S `x)`	Returns the arc cosine of each vector component.
`bool all(`A `x)`	Returns true if all components are true or not equal to zero, false otherwise.
`bool any(`A `x)`	Returns true if any component is true or not equal to zero, false otherwise.
S `asin(`S `x)`	Returns the arc sine of each vector component
S `atan(`S `x)`	Returns the arc tangent of each vector component
S `atan2(`S `y,` S `x)`	Returns the arc tangent of `y/x` for each vector component. The signs of `y` and `x` are used to determine the quadrant of the result.
S `ceil(`S `x)`	Rounds each component of the given vector to the nearest integer that is greater than or equal to the component's value and returns the component results in a vector.
N `clamp(`N`x, float min, float max)`N `clamp(`N `x, float min,` N`max)`N `clamp(`N `x,` N`min, float max)`N `clamp(`N `x,` N `min,` N `max)`	Compares the `x` parameter to `min` and `max` in a component-wise fashion. If `x` is less than `min` then `min` is selected. If `x` is greater than `max` then `max` is selected. Otherwise `x` is selected. Note that the `min` and `max` parameters can be single values, regardless of whether the `x` parameter is a vector or a scalar. All combinations of single and vector values are permissible for the `min` and `max` parameters.
S `cos(`S `x)`	Returns the cosine of each vector component. The angles specified by `x` are in radians.
S `degrees(`S `x)`	Converts each component of the given vector from radians to degrees
S `exp(`S `x)`	Applies the exponential function to each component of `x` by raising the constant `e` to the power `x`.
S `exp2(`S `x)`	Applies the exponential function to each component of `x` by raising the value two to the power `x`.
S `floor(`S `x)`	Rounds each component of the given vector to the nearest integer that is less than or equal to the component's value and returns the component results in a vector.
S `fmod(`S`a, float b)`S `fmod(`S `a,` S `b)`	Returns `a` modulo `b`, in other words, the remainder of `a/b`. The component-wise result has the same sign as `a`. Note that the `b` parameter can be single valued, regardless of whether the `a` parameter is a vector or single valued.
S `frac(`S `x)`	Returns the positive fractional part of each vector component
B `isnan(`F `x)`	Returns component-wise if the respective element of the given parameter no longer represents a valid number. This can occur as the result of an invalid operation such as taking the square root of a negative number. Note: This function is also available under the name `is_nan`, as it was named in MetaSL 1.0.
B `isfinite(`F`x)`	Returns component-wise if the respective element of the given parameter represents values that are both valid numbers (i.e., `isnan(`e`)` is false) and not infinite (i.e., `-infinity` `< e <` `infinity` ). Note: This function is also available under the name `is_finite`, as it was named in MetaSL 1.0.
S `lerp(`S`a,`S`b, float x)`S `lerp(`S`a,`S `b,` S`x)`	Linearly interpolates between `a` and `b` based on the value of `x`. The result is: `a(1-x) + bx`. The `x` parameter can be either a scalar or a vector, providing the vector is the same type as `a` and `b`.
S `log(`S`x)`	Computes the natural logarithm of each component of `x`
S `log2(`S`x)`	Computes the base 2 logarithm of each component of `x`
S `log10(`S`x)`	Computes the base 10 logarithm of each component of `x`
N `max(`N`a,`N `b)`	Compares each component of `a` and `b` and selects the component that is greater than the other.
N `min(`N`a,`N `b)`	Compares each component of `a` and `b` and selects the component that is less than the other.
S `modf(`S`x, out`S `i)`	Splits `x` into integral and fractional parts. The fractional part is returned and the integral part is stored in `i`. Both the fractional and integer parts have the same sign as `x`.
N `pow(`N`a, float b)`N `pow(`N`a,`N `b)`	Raises each component of `a` to the power `b`. Note that the `b` parameter can be single valued, regardless of whether the `a` parameter is a vector or single valued. Floating-point component values in `a` must not be negative, while for the overloaded functions with integer exponent `b`, the integer components in `a` may be negative.
S `radians(`S`x)`	Converts each component of the given vector from degrees to radians
S `round(`S`x)`	Rounds each component of `x` to the nearest integer value
S `rsqrt(`S`x)`	Returns the reciprocal of the square root of each component of `x`
S `saturate(`S `x)`	Clamps each component of `x` so that `0.0 <= x <= 1.0`
N `sign(`N`x)`	Returns 1 if `x` is greater than 0, -1 if `x` is less than 0, and 0 otherwise, on a component-wise basis.
S `sin(`S`x)`	Returns the sine of each component of `x`. The angles specified by `x` are in radians.
`void sincos(`S`x, out`S `s, out` S `c)`	Computes the sine and cosine of x simultaneously, which can be more efficient than calculating them individually when both are required. The angles specified by `x` are in radians.
S `smoothstep(`S `a,` S`b, float x)`S `smoothstep(`S`a,`S `b,` S`x)`	Returns 0 if `x` is less than `a` and 1 if `x` is greater than `b` in a component-wise fashion. A smooth curve is applied in-between so that the return value varies continuously from 0 to 1 as `x` varies from `a` to `b`. Note that the `x` parameter can be single valued, regardless of whether the `a` and `b` parameters are vectors or single valued.
S `sqrt(`S`x)`	Returns the component-wise square root of `x`
S `step(`S`a,`S `b)`	Returns 0 if `b` is less than `a` and 1 otherwise, on a component-wise basis.
S `tan(`S`x)`	Returns the component-wise tangent of `x`. The angles specified by `x` are in radians.
M `transpose(`M `x)`	Computes the transpose of the matrix `x`. Note that overloaded versions to support matrices with `double` and `half` elements are also provided.

Geometric functions

`float3 cross(float3 a, float3 b)`	Returns the cross product of `a` and `b`, which must be of type `float3`.
`float distance(`F `a,` F `b)`	Returns the distance between `a` and `b`.
`int dot(`I `a,`I`b) float dot(`F `a,` F `b)`	Returns the dot product of `a` and `b`.
V `faceforward(`V `n,` V `i,` V `ng)`	If the dot product of `i` and `ng` is less than zero this function returns `n` otherwise it returns `-n`.
`float length(`F `x)`	Returns the length of `x`.
V `normalize(`V `x)`	Scales the vector `x` by the reciprocal of its length to give it a length of 1. If the length of `x` is zero the result of `normalize()` is undefined.
`float3 reflect(float3 i, float3 n)`	Reflects the vector `i` about the normal vector `n`. It is assumed that `i` is pointing toward the surface represented by the normal `n`.
`float3 refract(float3 i, float3 n, float eta)`	Generates the refraction vector given the normal vector `n`, the incoming ray direction `i`, and the ratio `eta` of the index of refraction of the medium entered and the index of refraction of the medium left. If the angle between `i` and `n` is too large for the given `eta`, this function returns a zero vector.
`void rotate_basis(inout tangent_u, inout tangent_v, float angle)`	Assuming that `tangent_u` and `tangent_v` are part of an orthonormal basis, this function rotates both vectors around the implied normal, `cross(tangent_u, tangent_v)`, by `angle` radians.
`float3 transform_from_local(float3 dir, float3 tangent_u, float3 tangent_v, float3 normal)`	Transforms the direction `dir` from the orthonormal basis given by `tangent_u` for the x-axis, `tangent_v` for the y-axis, and `normal` for the z-axis to the coordinate system in which the basis vectors are given. The orientation of the coordinate systems depends on the uv-parametrization used.
`float3 transform_to_local(float3 dir, float3 tangent_u, float3 tangent_v, float3 normal)`	Transforms the direction `dir` to the orthonormal basis given by `tangent_u` for the x-axis, `tangent_v` for the y-axis, and `normal` for the z-axis. `dir` is assumed to be in the same space as the other vectors. The orientation of the coordinate systems depends on the uv-parametrization used.

Spectrum functions

`float eval_at_wavelength(Spectrum s, float wavelength)`	Evaluates and returns the value of `s` at the given wavelength, where the wavelength argument is given in nanometers `[nm]` and `WAVELENGTH_MIN` `≤` `wavelength` `≤` `WAVELENGTH_MAX`.
`float luminance(`C `s)`	Returns the CIE luminance of the spectrum or color. The alpha value of a `Color` argument is ignored.
`float max_value(Spectrum s)`	Returns the largest value.
`float min_value(Spectrum s)`	Returns the smallest value.
`float max_value_wavelength(Spectrum s)`	Returns the smallest wavelength in `[nm]` at which the largest value lies.
`float min_value_wavelength(Spectrum s)`	Returns the smallest wavelength in `[nm]` at which the smallest value lies.

BSDF functions

`Bsdf_components bsdf_invalid_sample(float3 sampled, Spectrum weight)`	Convenience function to handle invalid samples in the BSDF `sample` method, e.g., reflection samples which fall below the surface. In such cases, implementations can use code like: `return bsdf_invalid_sample(sampled,weight);` This function sets `sampled` and `weight` to zero and returns `bsdf::no_components`.
`Bsdf_components bsdf_check_type(float3 normal, float3 fixed, float3 sampled, Bsdf_components allowed)`	Checks if `fixed` and `sampled`, together with the geometry normal `normal`, represent reflection or refraction. The value of `allowed` is restricted to the appropriate flags and returned.
`float bsdf_component_sum(float pmf[], Bsdf_components types[], Bsdf_components allowed)`	Computes the sum of enabled BSDF component probabilities. This function computes the sum of all elements of `pmf` whose `types` are not suppressed by `allowed`. The lengths of `pmf` and `types` must be equal.
`int bsdf_choose_component(float pmf[], Bsdf_components types[], inout select, Bsdf_components allowed, float norm)`	Chooses a BSDF component from `types` according to the discrete probabilities in `pmf`. `select` `∈ [0,1)` drives the selection, `allowed` restricts the selection to components with matching entries in `types`. All elements of `pmf` must be non-negative and the lengths of `pmf` and `types` must be equal. The elements of `pmf` do not need to sum up to `1`. This function returns the index of the selected component, or `-1` if no component could be selected. This may happen e.g., if none of the elements of `types` are allowed by `allowed`, or no component has a positive probability. `norm` will be set to the sum of elements from `pmf` whose `types` element is not disabled by `allowed`. `select` will be renormalized so that it can be reused for further sampling.

Texture functions

`Color tex1D(texture1D tex, float coord)`	Sample a one dimensional texture and return a color value.
`Color tex2D(texture2D tex, float2 coord)`	Sample a two dimensional texture and return a color value.
`Color tex3D(texture3D tex, float3 coord)`	Sample a two dimensional texture and return a color value.
`Color texCUBE(textureCUBE tex, float3 coord)`	Sample a cube texture and return a color value.

Derivatives

S ddx(Sx)S ddy(S x) These functions return an approximation of the partial derivative of a with respect to the x and y coordinates of a rectangular surface element defined by the renderer. Typically x and y correspond to the x and y directions of raster space, but can be defined relative to another coordinate system, which would likely be the case for secondary rays. The expression a is restricted to a linear combination of state variables, which must be mentioned literally in a.