ShaderNodeSL¶

A SL programmable shader node. Double click SL nodes to edit the SL code in the console. This node uses a SL script to shade. SL boxes may contain more than a single function, but the returned value is taken from the last function. A SL function is a prototype declaring the return type, the function name and the function arguments. Arguments may also be output values.
For instance:

color myFunc (float A; color B)
{
        return A * B;
}

computes the product of the input float called A and the input color B. The compiled script automatically creates 2 inputs A and B, and an output Output. You can also add several outputs by specifying the output keyword before the argument type. Ex:

color myFunc (float A; color B; output color Half)
{
        Half = B * 0.5;
        return A * B;
}

You add meta-information in the SL comments to customize the SL node template in the UI:

// %param A = {type=types.float{min=0,slidermax=1,step=0.1},name="DisplayAsA"}
// %param B = {type=types.color,name="DisplayTab/AsB"}
color myFunc (float A; color B; output color Half)
{
        Half = B * 0.5;
        return A * B;
}

Possible meta-information on parameters are:

name: a '/' separated string. Ex: name="Tab/Subtab/Item" will display the parameter in the Tab > Subtab hierarchy, as Item
type: a Guerilla type. See types description in Guerilla SDK. Ex: type=types.float{min=0,max=1}, type=types.color, ...
hidden: the parameter is not visible in the node. Ex: hidden=true
exposed: the parameter is automatically exposed. Ex: exposed=true
help: a help string to be display in a tooltip. Ex: help="A protip for Guerilleros!"

Most Renderman SL functions are available, nevertheless there are some restrictions:

if control statement is currently not supported, and for control statement is partly supported.
the gather loop is replaced by the brdf loop.

Texture

color texture (string filename, float s, float t, ...)
color environment (string filename, vector v, ...)

Read a texture by its file name and its texture coordinates (s,t) or a 3d direction (v).

texture accepts additional optional parameters, as pairs of string and value:

float "%1": replace the first "%d" pattern of the texture filename by this number. Can be used to specify a udim number or a frame number in a texture sequence.
float "%2": replace the second "%d" pattern of the texture filename by this number. Can be used to specify a udim number or a frame number in a texture sequence.
float "alpha": if 1.0, returns the alpha component of the texture. If 0.0, returns the color components.
float "blur": the filter minimum size. Default is 0. Blur the texture lookup using a fixed filter size. A blur of 1.0 means the filter size is the image size.
string "channel": the texture channel name to return. Only available with PSD files.
color "default": the color to return if no texture name is provided. Defaut is white.
string "filter": the filter kernel name to use, either "box", "triangle" (default), "gaussian" or "bspline"
float "gamma": the texture gamma as a float or a string, which indicates in which gamma color space the texture is. Can be a float gamma value (like 2.2), "sRGB" or "linear".
color "missing": the color to return if the texture is missing. Defaut is pink.
string "mode": the texture clamping mode, a string of 2 characters, the first for s mode and the second for t mode, "cc" for clamp/clamp, "ww" for wrap/wrap (default)
float "samples": an indicative number of anisotropic texture samples to filter at every texture lookup, default is 16.
float "width": the filter size multiplier. Default is 1. If width is greater than 1.0, the filter is more blurry. If lower than 1.0, the filter is sharper.

Note:

The texture must have been built previously with matching filter and mode parameters.
texture is not yet supported in realtime.
Guerilla normally uses Guerilla texture path which has been built, and is not the original bitmap path. For reasons of convenience, you can still use the bitmap file path, but Guerilla will assume a predefined path for the texture using given filter and clamp parameters. For instance, texture ("/a/path/to/my/bitmap.tiff", s, t) will use "/a/path/to/my/.guerilla/bitmap.tiff_triangle_ww" as input texture, while texture ("/a/path/to/my/bitmap.tiff", s, t, "filter", "gaussian", "mode", "cc") will use "/a/path/to/my/.guerilla/bitmap.tiff_gaussian_cc" as input texture.

In an SL Box, declare you file name parameter as types.texture to benefit from Guerilla's preview and handy UI:

// %param[Texture,types.texture]

color MyOwnTexture (string Texture = "")

{

    return texture (Texture, s, t);

}

Occlusion and Indirect diffuse

color occlusion (point p, vector dir, float samples, ...)
color indirectdiffuse (point p, vector dir, float samples, ...)

Compute occlusion/indirect diffuse from the given position p, in the given direction dir.

occlusion and indirectdiffuse accept additional optional parameters, as pairs of string and value:

float coneangle: The cone opening of the gather, in radians. PI/2 for full hemispherical gather
float raylength: The maximum ray length for the gather function
string environmentmap: The environment map texture
string filter: The environment map texture filter
float blur: The environment map texture blur
float gamma: The environment map texture gamma
matrix matrix: The environment map texture transform, as a matrix
color hitcolor: The occlusion hit color, default is 0 black
color skycolor: The sky color, in case no environmentmap is provided, default is 1 white
float bentnormal: Compute bent normal occlusion when 1

Option "pointbased" indicates that the gather function must use a specific point based cloud, instead of raytracing. By default, the gathering uses raytracing.

Here are the raytracing options:

string subset: The subset of objects to trace
float opacity: Indicates that the hit objects must be shaded for opacity, so one can compute occlusion on semi transparent objects.
float depth: The maximum recursive raytracing depth.
string value: Indicates the surface shader output to use instead of Ci. If said output doesn't exist in the shader, the shading engine will revert to Ci.
float lastrayenv: If 0, the rays deeper than the maximum depth return the sky color, else they return the environment
float doubleprecision: If not 0, the ray tracer uses a double precision intersection algorithm. It is slower but can solve some precision issues.

Guerilla expects subset to be a correct value, and unless you crafted you RIB files, which is most unlikely, you can't know this value. To be able to use subsets, simply declare your subset parameter as a types.trace, which will let you connect the SL Box just like any raytracing node:

// %param[Trace,types.trace]

color MyOwnOcclusion (string Trace = "")

{

    return occlusion (P, N, 16, "subset", Trace);

}

Here are the point based options (i.e. when "pointbased" 1 is specified):

string filename: The point based cloud file to use
float maxsolidangle: The maximum solid angle
float rasterize: gather uses rasterization.
float usebackface: gather uses surfels back side.

Note: varying coneangle and raylength are not supported for point based gathering.

Guerilla expects filename to be a correct point cloud name, and unless you crafted you RIB files, which is most unlikely, you can't know this value. To be able to use Guerilla point cloud, simply declare your filename parameter as a types.pointcloud, which will let you connect the SL Box just like any point based gathering node:

// %param[PointCloud,types.pointcloud]

color MyOwnPBOcclusion (string PointCloud = "")

{

    return occlusion (P, N, 16, "pointbased", 1, "filename", PointCloud);

}

SL functions

Here is the exhaustive list of supported functions. For more detail on function behaviour, please refer to the Renderman SL reference.

any is a shortcut for float|vector|point|normal|color.

Basic mathematical functions

Absolute value of x	any abs (any x)
Sign of x	any sign (any x)
Minimum between x and y	any min (any x; any y)
Maximum between x and y	any max (any x; any y)
Clamp x between xmin and xmax	any clamp (any x; any xmin; any xmax)
Mix between x and y, as (1-a)x+ay	any mix (any x; any y; any a)
Highest integer smaller or equal to x	any floor (any x)
Smallest integer greater or equat to x	any ceil (any x)
Closest integer to x	any round (any x)
x raised to the power of y	float pow (float x; float y)
Exponential of x	float exp (float x)
Square root of x	float sqrt (float x)
Inverse square root of x	float inversesqrt (float x)
Neper logarithm of x	float log (float x)
Modulus of x	float mod (float x; float modulo)

Trigonometric functions

Radians to degrees	float degrees (float angle)
Degrees to radians	float radians (float angle)
Sine of angle in radians	float sin (float angle)
Radians arcsine of x	float asin (float x)
Cosine of angle in radians	float cos (float angle)
Radians arccosine of x	float acos (float x)
Tangent of angle in radians	float tan (float angle)
Radians arctangent of x	float atan (float x)
Radians arctangent of y/x	float atan (float y; float x)
Radians arctangent of y/x	float atan2 (float y; float x)

Step functions

Hard step, equivalent to x >= edge ? 1 : 0	float step (float edge; float x)
Linear step between xmin and xmax	float boxstep (float xmin; float xmax; float x)
Cubic step between xmin and xmax	float smoothstep (float xmin; float xmax; float x)
Filtered step, 1 pixel antiliasing for filterwidth=0.5	float filterstep (float edge; float value; float filterwidth)

Derivatives

Derivative of x over u	float Du (float x)
Derivative of x over u	color Du (color x)
Derivative of x over u	vector Du (point\|vector\|normal x)
Derivative of x over v	float Dv (float x)
Derivative of x over v	color Dv (color x)
Derivative of x over v	vector Dv (point\|vector\|normal x)

Geometric functions

Extract x component of v	float xcomp (vector\|point\|normal v)
Extract y component of v	float ycomp (vector\|point\|normal v)
Extract z component of v	float zcomp (vector\|point\|normal v)
Extract nth component of c	float comp (color c; float component)
Euclidean length of v	float length (vector\|point\|normal v)
Normalized v	vector\|normal normalize (vector\|normal v)
Euclidean distance between a and b	float distance (point a; point b)
Flips v if opposite to i	vector\|normal faceforward (vector\|normal v; vector\|normal i)
Flips v if opposite to i	vector\|normal faceforward (vector\|normal v; vector\|normal i; vector\|normal n)
Reflected direction of v to n	vector\|normal reflect (vector\|normal v; vector\|normal n)
Refracted direction of v to n, with eta relative IOR	vector\|normal refract (vector\|normal v; vector\|normal n; float eta)
Transforms point p from current to given space	point transform (string space; point p)
Transforms point p from fromspace to tospace	point transform (string fromspace; string tospace; point p)
Transforms vector v from current to given space	vector vtransform (string space; point p)
Transforms vector v from fromspace to tospace	vector vtransform (string fromspace; string tospace; vector v)
Transforms normal n from current to given space	normal ntransform (string space; point p)
Transforms normal n from fromspace to tospace	normal ntransform (string fromspace; string tospace; normal n)
Computes normal from point p	normal calculatenormal (point p)

Noise and clouds

Random value between 0 and 1	float\|color\|point random ()
1d perlin noise on x	float\|color\|point noise (float x)
2d perlin noise on x and y	float\|color\|point noise (float x; float y)
3d perlin noise on xyz	float\|color\|point noise (vector\|point\|normal xyz)
4d perlin noise on xyz and w	float\|color\|point noise (vector\|point\|normal xyz; float w)
1d periodic perlin noise on x	float\|color\|point pnoise (float x)
2d periodic perlin noise on x and y	float\|color\|point pnoise (float x; float y)
3d periodic perlin noise on xyz	float\|color\|point pnoise (vector\|point\|normal xyz)
4d periodic perlin noise on xyz and w	float\|color\|point pnoise (vector\|point\|normal xyz; float w)
1d cellular perlin noise on x	float\|color\|point cellnoise (float x)
2d cellular perlin noise on x and y	float\|color\|point cellnoise (float x; float y)
3d cellular perlin noise on xyz	float\|color\|point cellnoise (vector\|point\|normal xyz)
4d cellular perlin noise on xyz and w	float\|color\|point cellnoise (vector\|point\|normal xyz; float w)

Lighting

Sum of all ambient lights	color ambient ()
Lambert contribution	color diffuse (vector\|normal n)
Specular contribution	color specular (vector\|normal n; vector\|normal i; float roughness)
In illuminance/brdf loop, get light output	color lightoutput (string name)

String manipulation

Print a string, equivalent to the C printf function	void printf (string fmt, ...)
Build a string, equivalent to the C sprintf function	string format (string fmt, ...)
	float atof (string str)

Misc functions

float shadert ()

brdf loop

brdf (point P; normal N; vector wo, ...)

The brdf loop is an extension of the RSL language, although similar in mind to the illuminance loop. The brdf loop evaluates all light sources (e.g. basic lights, area lights and indirect illumination) and gathers them using a user provided code.

For example, as simple lambert diffuse can be written:

color direct = 0, indirect = 0;
normal n = normalise (N);
brdf (P, n, -normalize (I),
                "raytype", "d",
                "rayfilter", "^[st]*g?d*$",
                "length", 10000,
                "depth", 1,
                "samples", 16,
                "distribution", "cosine",
                "subset", "Diffuse",
                "direct:output", direct,
                "indirect:output", indirect)
{
        return Cl * max (n.normalize (L), 0);
}
return direct+environment+indirect;

Notice how the brdf loop has its structure slightly changed from the original illuminance loop, where the inner loop code returns the computed color, rather than accumulates it into an accumulator.

brdf accepts the following parameters (the 3 first are mandatory):

	point p	the position being illuminated
	normal n	the normal of the point being illuminated
	vector wo	the normalized direction to the viewer (-normalize (I))
"enabled"	float enabled = 1	enables/disables illumination computation
"raytype"	uniform string raytype = "d"	the type of the brdf, usually "d" for diffuse, "s" for pure specular, "g" for glossy
"rayfilter"	uniform string rayfilter = "^[st]g?d$"	the ray path filter, see below for further ray filtering explanations
"length"	float length = 10000	the maximum ray length for indirect illumination
"depth"	uniform float depth = 1	the maximum bounces
"samples"	float samples = 16	the indicative number of samples for indirect, environment and direct illumination, each
"subset"	uniform string subset = "All"	the name of the set of objects to use for indirect illumination and environment occlusion
"distribution"	uniform string distribution = "uniform"	the name of the sampling distribution
"scatter"	uniform string scatter = ""	the name of the position scattering distribution
"direct:output"	output color direct	the resulting direct illumination
"indirect:output"	output color indirect	the resulting indirect illumination

Ray path filtering

Each ray in the raytracer holds its current path, starting from the camera and going through consecutive bounces. For instance, a ray that first hits a specular surface, then a diffuse and the another diffuse surface will have the "sdd" path, where 's' stands for specular and 'd' for diffuse.

Although a path tracer is able to produce good quality global illumination, some ray paths are still hard to integrate, such as caustics. Caustics are usually produced by diffuse/glossy surfaces hitting purely specular or refractive surface, and it is advisable to forbid those paths during shading. To that end, the "rayfilter" parameters enables the raytracer to discard some surface contributions, based on the current ray path.

Ray filters are Lua patterns. See Lua patterns for the Lua patterns reference.

Here are some examples of possible ray filters:

^[st]*g?d*$: No caustics. Allows any number of pure specular/refraction, then one glossy at most, and then any number of diffuse. This filter is the most restrictive and will not produce caustics. In counterpart, the image is darker than it should.
^[st]*[gd]*$: Glossy caustics. Allows any number of pure specular/refraction, then any number of glossy or diffuse. This filter is less restrictive, but might generate caustics artefacts with sharp glossy. In counterpart, the light intensity is more preserved.
^[stgd]*$: Caustics. Allows all ray path, no filtering at all. The light intensity of the image is fully preserved, but caustic artefacts are highly plausible.

Brdf distributions

Guerilla provides some builtin brdf distributions:

"uniform": uniformly distributed in the hemisphere.
"oppositeuniform": uniformly distributed in the opposite hemisphere.
"cosine": cosine distributed in the hemisphere.
"reflect": Purely reflective brdfs.
"refract": Purely refractive brdfs, uses "distribution:eta" additional parameter.
"powercosinereflect": Powered cosine in the reflected direction, used for Blinn-like brdfs, uses "distribution:roughness" additional parameter.

Volumetrics

color voxel (point P; string channel; ...)

the voxel function makes a lookup in the current 3d voxel object. If the shaded object is not a 3d voxel it returns the default color.

Example :

color density = voxel (P, "density", "filter", "linear");

voxel accepts the following parameters (the 3 first are mandatory):

	point P	Lookup position in camera space.
	string channel	The voxel channel name to lookup.
"velocitychannel"	string velocitychannel = ""	the velocity channel to use for the motion blur. Default is "", no motion blur.
"velocityfactor"	float velocityfactor = 1	the velocity factor. A factor to enhance/reduce the motion blur effect. Default is 1.
"default"	color default = 0	the default value to return if the lookup is out of the voxel or if there is no voxel. Default is (0,0,0).
"filter"	string filter = "linear"	The filter to use during the lookup. "nearest" : no filtering, "linear" : linear filtering (sharper), "cubic" : cubic filtering (smoother, slower).
"propagate"	float propagate = 0	If != 0, propagate the border values outside the voxel. This option has no effect with openvdb voxels. Default is 0 : no propagation, returns the default value outside of the voxel.