Skip to content

OSL#

Open Shading Language (OSL) is a rich scripting language for programmable shading in advanced renderers and other applications. It is ideal for describing materials, lights, displacement, and pattern generation.

OSL was originally developed by Sony Pictures Imageworks for use in its in-house renderer used for feature film animation and visual effects. The language specification was developed with input by other visual effects and animation studios who also wish to use it.

Clarisse textures supports a subset of OSL features, through its OSL file and OSL script textures. Current Clarisse OSL implementation doesn't support closure and is limited to pattern generation as well as a single OSL execution context per texture node.

More information on OSL is available here: Open Shading Language

OSL shader execution context is encapsulated in Clarisse textures. This means that any texturable attributes in Clarisse can take an OSL shader as input. While this is extremely powerful, this has a drawback as the OSL execution context isn't shared in the texture network.

In other words, OSL compiler can't perform aggressive optimization at the network level since it can only compile a single node at a time. When declaring an OSL shader, and if the compilation process is successful, all shader parameters are dynamically parsed to generate equivalent custom attributes in Clarisse gathered in four different attribute groups:

Shader Information Input Output
Specify and compile the OSL shader code. OSL shader general description : type and name. Available after compilation. OSL shader input parameters. Available after compilation. OSL shader output parameters. Available after compilation.

Configuration#

OSL comes properly configured in Clarisse and scripts can directly use functions defined in the OSL standard library. However, OSL can be configured to use custom libraries using Edit > Preferences... > OSL

Settings Description
Include Paths Set the location of OSL libraries. To add multiple locations just use the semicolon ; separator between each location.
Statistics Log Level Set the log level of OSL to filter out some type of messages.
Shader Template Set the default OSL script template file used when creating a new OSL Script texture.

Textures#

There are two ways to work with OSL in Clarisse: using the OSL Script texture to directly write your scripts in Clarisse or using the OSL File which takes as input OSL script file as source code or as a pre-compiled OSL shader.

OSL File#

The OSL file texture allows to use an OSL shader written in a file, pre-compiled or not (.oso or .osl) The OSL file cannot be edited in Clarisse and the only thing you are able to do is to force its compilation by clicking on the Force Compilation button.

Note
Note that the File > Resync Resources force the recompilation of all OSL file shaders at once.

OSL Script#

OSL Script texture allows you to write an OSL shader directly inside a Clarisse script editor. The compilation of the shader is performed automatically when the script is modified. However, Clarisse still provides a Force Compilation action that allow to force the recompilation of the shader in the event a dependency of the script has changed (an include file).

Note
OSL Script texture default script relies on a OSL file template that can be customized. You can change the location of the file in Clarisse Preferences. Go to Edit > Preferences.../Application/OSL and modify Shader Template.

Supported Features#

Here is an overview of the supported features and limitations of OSL in Clarisse.

Metadata#

Clarisse is capable of interpreting a subset of OSL metadata :

Name Description
"help" Will be displayed as tooltip in the Clarisse GUI.
"widget" Only a subset of widget are currently supported : "number", "string", "filename" and "null". Note that colors and vectors are directly displayed with Clarisse dedicated widgets.

Attributes properties#

A OSL input is basically a Clarisse attribute. This means that OSL input declared by OSL textures can be driven seamlessly by any kind of Clarisse textures or shading variables.

Note
Note that, when re-compiling your shaders, Clarisse will try to preserve previously set values if attribute definition (type and name) matches.

Matrices#

In Clarisse, the common OSL space is set to world space. The following OSL geometric spaces are currently supported :

  • "common" (="world")
  • "object"
  • "shader"
  • "world"
  • "camera"

Trace#

The trace method allows to perform raytracing directly in OSL shaders. Be aware that ray tracing an excessive amount of rays in OSL shaders can lead to performance breakdown. The current implementation can be used to perform a simple occlusion test and to retrieve basic geometric information such as ("hit", "hitdist", "geom:name", "P", "N", "Ng")

Note

You can choose the type of ray trace is using for Clarisse in the OSL texture as well as a group of Geometry on which raytracing is performed on. By default, trace uses the geometries of the scene and launch rays of type Camera.

Limitations#

The OSL implemention in Clarisse suffers from some limitations listed below:

  • OSL shaders are independent Clarisse textures which prevent OSL compiler to perform many aggressive optimizations.
  • Shaders output must match Clarisse's texture output interface. Concretely, only one output can be output at a time and they are automatically converted to color (as in all Clarisse textures)
  • OSL closures are not supported.