4.8. sl — RenderMan Shading Language functionality

This module provides some of the functionality from the RenderMan Shading Language. Those functions that require an actual rendering context (surfaces, light sources, etc.) are not supported.

Most of the functions can be used just like in the Shading Language. An exception are those functions whose return type is dependant on the context as it is the case with random() or noise(). Here, those functions have to be prepended with the return type, for example float_random() or point_noise() (that is, the cast is part of the name).

4.8.1. Constants

cgkit.sl.PI

This is the same as math.pi.

4.8.2. Math functions

cgkit.sl.abs(x)

Returns the absolute value of its argument. This is just the builtin abs() function.

cgkit.sl.acos(a)

Returns the arc cosine. This function is imported from the math module.

cgkit.sl.asin(a)

Returns the arc sine. This function is imported from the math module.

cgkit.sl.atan(y[, x])

Returns the arc tangent. With one argument math.atan() is called, with two arguments math.atan2() is called.

cgkit.sl.ceil(x)

Returns the largest integer not greater than x. This function is imported from the math module.

cgkit.sl.clamp(x, min, max)

Returns min if x < min, max if x > max, otherwise x.

cgkit.sl.color_cellnoise(p)

Returns a color value (actually a vec3) whose value is a (pseudo) random function of its arguments. The return value is constant between integer lattice points.

cgkit.sl.color_noise(p)

Returns a color value (actually a vec3) whose value is a (pseudo) random function of its arguments.

cgkit.sl.color_pnoise(p, period)

Returns a color value (actually a vec3) whose value is a periodic (pseudo) random function of its arguments.

cgkit.sl.color_random()

Return a color whose componenets are a random number between 0 and 1. The function actually returns a vec3.

cgkit.sl.cos(a)

Returns the cosine. This function is imported from the math module.

cgkit.sl.degrees(rad)

Converts from radians to degrees.

cgkit.sl.exp(x)

Returns pow(e,x). This function is imported from the math module.

cgkit.sl.float_cellnoise(p)

Returns a float value which is a (pseudo) random function of its arguments. The return value is constant between integer lattice points. This function is imported from the noise module.

cgkit.sl.float_noise(p)

Returns a float value which is a (pseudo) random function of its arguments. This function is imported from the noise module.

cgkit.sl.float_pnoise(p, period)

Returns a float value which is a periodic (pseudo) random function of its arguments. This function is imported from the noise module.

cgkit.sl.float_random()

Return a random number between 0 and 1. This call is equivalent to random.random().

cgkit.sl.floor(x)

Returns the smallest integer not smaller than x. This function is imported from the math module.

cgkit.sl.inversesqrt(x)

Returns 1/sqrt(x).

cgkit.sl.log(x[, base])

Returns the natural logarithm of x (the same as math.log()) or the logarithm to the specified base.

cgkit.sl.max(a, b, ...)

Returns the argument with maximum value. This is just the builtin max() function.

cgkit.sl.min(a, b, ...)

Returns the argument with minimum value. This is just the builtin min() function.

cgkit.sl.mix(val0, val1, t)

For t = 0 the value val0 is returned, for t = 1 the value val1 is returned. For values of t between 0 and 1 a linearly interpolated value is returned.

cgkit.sl.mod(a, b)

Returns a%b. This is just an equivalent for the %-operator.

cgkit.sl.point_cellnoise(p)

Returns a point (as a vec3) whose value is a (pseudo) random function of its arguments. The return value is constant between integer lattice points.

cgkit.sl.point_noise(p)

Returns a point (as a vec3) whose value is a (pseudo) random function of its arguments.

cgkit.sl.point_pnoise(p, period)

Returns a point (as a vec3) whose value is a periodic (pseudo) random function of its arguments.

cgkit.sl.point_random()

Return a point (a vec3) whose componenets are a random number between 0 and 1.

cgkit.sl.pow(x, y)

Returns x**y. This function is imported from the math module.

cgkit.sl.radians(deg)

Converts from degrees to radians.

cgkit.sl.round(x)

Returns the integer closest to x. This is just the builtin round() function.

cgkit.sl.sign(x)

Returns -1 with a negative argument, +1 with a positive argument, and 0 if its argument is zero.

cgkit.sl.sin(a)

Returns the sine. This function is imported from the math module.

cgkit.sl.smoothstep(min, max, value)

Returns 0 if value < min, 1 if value > max, and performs a smooth Hermite interpolation between 0 and 1 in the interval min to max.

cgkit.sl.spline(t, controlpoints)

Fits a spline to the control points given and returns the value at t which ranges from 0 to 1. At least four control points must always be given.

cgkit.sl.sqrt(x)

Returns the square root. This function is imported from the math module.

cgkit.sl.step(min, x)

Returns 0 if x < min, otherwise 1.

cgkit.sl.tan(a)

Returns the tangent. This function is imported from the math module.

cgkit.sl.tan(a)

Returns the tangent. This function is imported from the math module.

cgkit.sl.vector_cellnoise(p)

Returns a vector (as a vec3) whose value is a (pseudo) random function of its arguments. The return value is constant between integer lattice points.

cgkit.sl.vector_noise(p)

Returns a vector (as a vec3) whose value is a (pseudo) random function of its arguments.

cgkit.sl.vector_pnoise(p, period)

Returns a vector (as a vec3) whose value is a periodic (pseudo) random function of its arguments.

4.8.3. Geometric functions

cgkit.sl.distance(p1, p2)

Returns the distance between two points. The arguments should be of type vec3.

cgkit.sl.faceforward(N, I, Nref)

Flips N so that it faces in the direction opposite to I.

Note

In contrast to the Shading Language Nref is not optional.

cgkit.sl.length(v)

Returns the length of a vector. This is equivalent to calling v.length().

cgkit.sl.normalize(v)

Returns a unit vector in the direction of v. This is equivalent to calling v.normalize().

cgkit.sl.ptlined(p0, p1, q)

Returns the distance between point q and the line segment p0, p1. The arguments should be of type vec3.

cgkit.sl.reflect(I, N)

Returns the reflection vector given an incident direction I and a normal vector N. This is equivalent to calling I.reflect(N)().

cgkit.sl.refract(I, N, eta)

Returns the transmitted vector given an incident direction I, the normal vector N and the relative index of refraction eta. This is equivalent to calling I.refract(N, eta)().

cgkit.sl.xcomp(p)

Return the x component of p. This is equivalent to p.x.

cgkit.sl.ycomp(p)

Return the y component of p. This is equivalent to p.y.

cgkit.sl.zcomp(p)

Return the z component of p. This is equivalent to p.z.

cgkit.sl.setxcomp(p, x)

Set the x component of p. This is equivalent to p.x = x.

cgkit.sl.setycomp(p, y)

Set the y component of p. This is equivalent to p.y = y.

cgkit.sl.setzcomp(p, z)

Set the z component of p. This is equivalent to p.z = z.

cgkit.sl.comp(c, index)

Get an individual color component. This is equivalent to c[index].

cgkit.sl.setcomp(c, index, value)

Set an individual color component. This is equivalent to c[index] = value.

4.8.4. String functions

cgkit.sl.concat(str1, ..., strn)

Returns a concatenated string.

cgkit.sl.format(pattern, val1, val2, ..., valn)

Returns a formatted string (similar to the C function sprintf()). Any occurance of the character % followed by a letter is replaced by a value. In this implementation it doesn’t matter what letter you are actually using (in the Shading Language it would be %f for floats, %p for points, vectors or normals, %c for colors, %m for matrices and %s for strings).

cgkit.sl.match(pattern, subject)

String pattern matching.

cgkit.sl.printf(pattern, val1, val2, ..., valn)

Prints the values of the specified variables. Any occurance of the character % followed by a letter is replaced by a value. In this implementation it doesn’t matter what letter you are actually using (in the Shading Language it would be %f for floats, %p for points, vectors or normals, %c for colors, %m for matrices and %s for strings).

4.8.5. Unsupported functions

The following functions are not supported by this module:

• Du()
• Dv()
• Deriv()
• filterstep()
• area()
• calculatenormal()
• depth()
• fresnel()
• transform()
• vtransform()
• ntransform()
• ambient()
• diffuse()
• phong()
• specular()
• specularbrdf()
• trace()
• environment()
• shadow()
• texture()
• textureinfo()
• atmosphere()
• displacement()
• incident()
• lightsource()
• opposite()
• surface()
• attribute()
• option()
• rendererinfo()