# 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.

#### Basic mathematical functions

Absolute value of x | |

Sign of x | |

Minimum between x and y | |

Maximum between x and y | |

Clamp x between xmin and xmax | |

Mix between x and y, as (1-a)*x+a*y | |

Highest integer smaller or equal to x | |

Smallest integer greater or equat to x | |

Closest integer to x | |

x raised to the power of y | |

Exponential of x | |

Square root of x | |

Inverse square root of x | |

Neper logarithm of x | |

Modulus of x |

#### Trigonometric functions

Radians to degrees | |

Degrees to radians | |

Sine of angle in radians | |

Radians arcsine of x | |

Cosine of angle in radians | |

Radians arccosine of x | |

Tangent of angle in radians | |

Radians arctangent of x | |

Radians arctangent of y/x | |

Radians arctangent of y/x |

#### Step functions

Hard step, equivalent to x >= edge ? 1 : 0 | |

Linear step between xmin and xmax | |

Cubic step between xmin and xmax | |

Filtered step, 1 pixel antiliasing for filterwidth=0.5 |

#### Derivatives

Derivative of x over u | |

Derivative of x over u | |

Derivative of x over u | |

Derivative of x over v | |

Derivative of x over v | |

Derivative of x over v |

#### Geometric functions

Extract x component of v | |

Extract y component of v | |

Extract z component of v | |

Extract nth component of c | |

Euclidean length of v | |

Normalized v | |

Euclidean distance between a and b | |

Flips v if opposite to i | |

Flips v if opposite to i | |

Reflected direction of v to n | |

Refracted direction of v to n, with eta relative IOR | |

Transforms point p from current to given space | |

Transforms point p from fromspace to tospace | |

Transforms vector v from current to given space | |

Transforms vector v from fromspace to tospace | |

Transforms normal n from current to given space | |

Transforms normal n from fromspace to tospace | |

Computes normal from point p |

#### Noise and clouds

Random value between 0 and 1 | |

1d perlin noise on x | |

2d perlin noise on x and y | |

3d perlin noise on xyz | |

4d perlin noise on xyz and w | |

1d periodic perlin noise on x | |

2d periodic perlin noise on x and y | |

3d periodic perlin noise on xyz | |

4d periodic perlin noise on xyz and w | |

1d cellular perlin noise on x | |

2d cellular perlin noise on x and y | |

3d cellular perlin noise on xyz | |

4d cellular perlin noise on xyz and w |

#### Lighting

Sum of all ambient lights | |

Lambert contribution | |

Specular contribution | |

In illuminance/brdf loop, get light output |

#### String manipulation

Print a string, equivalent to the C printf function | |

Build a string, equivalent to the C sprintf function | |

#### Misc functions

#### brdf loop

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.

the position being illuminated | ||

the normal of the point being illuminated | ||

the normalized direction to the viewer (-normalize (I)) | ||

"enabled" | enables/disables illumination computation | |

"raytype" | the type of the brdf, usually "d" for diffuse, "s" for pure specular, "g" for glossy | |

"rayfilter" | the ray path filter, see below for further ray filtering explanations | |

"length" | the maximum ray length for indirect illumination | |

"depth" | the maximum bounces | |

"samples" | the indicative number of samples for indirect, environment and direct illumination, each | |

"subset" | the name of the set of objects to use for indirect illumination and environment occlusion | |

"distribution" | the name of the sampling distribution | |

"scatter" | the name of the position scattering distribution | |

"direct:output" | the resulting direct illumination | |

"indirect:output" | 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

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");

Lookup position in camera space. | ||

The voxel channel name to lookup. | ||

"velocitychannel" | the velocity channel to use for the motion blur. Default is "", no motion blur. | |

"velocityfactor" | the velocity factor. A factor to enhance/reduce the motion blur effect. Default is 1. | |

"default" | 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" | The filter to use during the lookup. "nearest" : no filtering, "linear" : linear filtering (sharper), "cubic" : cubic filtering (smoother, slower). | |

"propagate" | 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. |