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.


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.


  • 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 xany abs (any x)
Sign of xany sign (any x)
Minimum between x and yany min (any x; any y)
Maximum between x and yany max (any x; any y)
Clamp x between xmin and xmaxany clamp (any x; any xmin; any xmax)
Mix between x and y, as (1-a)*x+a*yany mix (any x; any y; any a)
Highest integer smaller or equal to xany floor (any x)
Smallest integer greater or equat to x any ceil (any x)
Closest integer to xany round (any x)
x raised to the power of yfloat pow (float x; float y)
Exponential of xfloat exp (float x)
Square root of xfloat sqrt (float x)
Inverse square root of xfloat inversesqrt (float x)
Neper logarithm of xfloat log (float x)
Modulus of xfloat mod (float x; float modulo)

Trigonometric functions

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

Step functions

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


Derivative of x over ufloat Du (float x)
Derivative of x over ucolor Du (color x)
Derivative of x over uvector Du (point|vector|normal x)
Derivative of x over vfloat Dv (float x)
Derivative of x over vcolor Dv (color x)
Derivative of x over vvector Dv (point|vector|normal x)

Geometric functions

Extract x component of vfloat xcomp (vector|point|normal v)
Extract y component of vfloat ycomp (vector|point|normal v)
Extract z component of vfloat zcomp (vector|point|normal v)
Extract nth component of cfloat comp (color c; float component)
Euclidean length of vfloat length (vector|point|normal v)
Normalized vvector|normal normalize (vector|normal v)
Euclidean distance between a and bfloat distance (point a; point b)
Flips v if opposite to ivector|normal faceforward (vector|normal v; vector|normal i)
Flips v if opposite to ivector|normal faceforward (vector|normal v; vector|normal i; vector|normal n)
Reflected direction of v to nvector|normal reflect (vector|normal v; vector|normal n)
Refracted direction of v to n, with eta relative IORvector|normal refract (vector|normal v; vector|normal n; float eta)
Transforms point p from current to given spacepoint transform (string space; point p)
Transforms point p from fromspace to tospacepoint transform (string fromspace; string tospace; point p)
Transforms vector v from current to given spacevector vtransform (string space; point p)
Transforms vector v from fromspace to tospacevector vtransform (string fromspace; string tospace; vector v)
Transforms normal n from current to given spacenormal ntransform (string space; point p)
Transforms normal n from fromspace to tospacenormal ntransform (string fromspace; string tospace; normal n)
Computes normal from point pnormal calculatenormal (point p)

Noise and clouds

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


Sum of all ambient lightscolor ambient ()
Lambert contributioncolor diffuse (vector|normal n)
Specular contributioncolor specular (vector|normal n; vector|normal i; float roughness)
In illuminance/brdf loop, get light outputcolor lightoutput (string name)

String manipulation

Print a string, equivalent to the C printf functionvoid printf (string fmt, ...)
Build a string, equivalent to the C sprintf functionstring 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 pthe position being illuminated
normal nthe normal of the point being illuminated
vector wothe normalized direction to the viewer (-normalize (I))
"enabled"float enabled = 1enables/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 = 10000the maximum ray length for indirect illumination
"depth"uniform float depth = 1the maximum bounces
"samples"float samples = 16the 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 directthe resulting direct illumination
"indirect:output"output color indirectthe 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.


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 PLookup position in camera space.
string channelThe 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 = 1the velocity factor. A factor to enhance/reduce the motion blur effect. Default is 1.
"default"color default = 0the 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 = 0If != 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.