OSL Shaders

OSL is a shading language designed for modern physically based rendering, supported starting from Arnold 5.0. It can be used to write shaders that work in Arnold and other renderers. It is an alternative to C++ shaders, with a higher level API that makes writing shaders simpler while at the same time providing advanced optimizations.

Getting Started

OSL shaders are written in .osl files, with each file corresponding to a single Arnold shader node. Here is a simple example:

gamma.osl

The shader name gamma must match the gamma.osl filename. The shader defines input and output parameters much like Arnold C++ shader nodes, but using a more compact syntax. Here Cin and gamma are input parameters, while Cout is the output parameter. All parameters must be initialized with default values.

Compilation

Shaders are compiled automatically when they are found by Arnold in the shader searchpath, from .osl files to .oso files in the same directory. This happens if no corresponding .oso file exists, or if the .osl file was modified since the last compilation.

Alternatively, shaders can be manually compiled using the oslc program included with Arnold.

.oso files contain intermediate code that is operating system and CPU agnostic. At render time, OSL translates shader networks into machine code on the fly, and in the process heavily optimizes shaders and networks with full knowledge of the shader parameters and other runtime values that could not have been known when the shaders were compiled from .osl source code.

Installation

.osl and .oso files are installed the same way as .so and .dll shader files: place them anywhere in the shader searchpath, and Arnold will find them.

Using kick we can verify that Arnold detects the shader and its parameters.

Manually Loading Shaders

Besides the automatically registered OSL shaders in the search path, it is possible to load shaders manually through an osl node. This can be useful to insert expressions into a shader network, or to get more control over which shaders are loaded and how their parameters should be interpreted.

osl accepts a shadername parameter to specify the shader, without the .osl or .oso file extension. As soon as the shadername parameter is set, the OSL shader parameters are added to the node, with a param_ prefix.

For inserting expressions into the network, the .OSL or .OSO code can be embedded as well: 

Supported Features

Parameters

OSL shader parameters are converted to the corresponding Arnold parameters where possible. Arnold only supports one output parameter per node, so if there are multiple output parameters the first parameter will be used. 

OSL TypeArnold Type
intINT
int (with metadata)
BOOLEAN
int (with metadata)
ENUM
floatFLOAT
colorRGB
colorRGBA
pointVECTOR
vectorVECTOR
normalVECTOR
pointPOINT2
matrixMATRIX
array of any typeARRAY
closure colorCLOSURE
structPOINTER

Boolean and enum parameter types are created with OSL metadata on integers.

Attributes

Node parameters and user data are available through getattribute().

Shader Globals

Arnold supports most OSL shader globals, like PuvNNg and time. Their meaning is the same as in the C++ shading API.

Ps (for light filters), surfacearea()dtime and dPdtime shader globals are not supported currently.

All shader globals are considered to be read-only, we do not support writing to Ci and P to output closures or displacement. Output parameters should be used instead.

Textures

Textures are accessed through the built-in texture() and gettextureinfo() functions. The texture() function accepts an optional colorspace argument to indicate the texture's color space to convert from.

Note that unlike the Arnold C++ shading API, the texture origin is assumed to be in the top left corner rather than the bottom left corner, for consistency with the OSL standard. To match, the v coordinate can be flipped to 1 - v, or floor(v) + 1 - mod(v, 1) in case of UDIM textures.

Volume Channels

Volume channels are available through texture3d() using object space coordinates.

Closures

The following closures are supported, matching the closures in the C++ shader API.

Supported Closures

Example shader outputting a closure:

Trace

The OSL trace() function is supported, for tracing probe rays. The shade argument to perform shading is not supported. The traceset argument is supported, using an inclusive traceset by default, and exclusive if the traceset name is prefixed with a - characeter.

Information about the hit may be retrieved with getmessage(), supporting hit, hitdist, P, N, u, v, and arbitrary user data and parameter lookups on the object that was hit.

Performance

 OSL and C++ shaders can be linked into a single shader network. However there is a small overhead (perhaps 1-2 % overall render time) in connecting the output of an OSL shader into a C++ shader. For the OSL optimizer to be able to do aggressive whole network optimizations, as many OSL shader nodes as possible should be used.

Runtime compilation and optimization of OSL shaders happens the first time the shader is evaluated, during rendering. This increases the time to first pixel, but can pay off in reduced render time overall.

Debugging

The OSL_OPTIONS environment variable can be used to debug common errors in shaders or print more detailed information:

More Information

  • No labels