Supported input types for OSL nodes

Conceptually an OSL shader corresponds to a node in our node system. Input parameters will show up as input pins on the OSL texture node. There is a single output parameter corresponding to the output value of the node.

The types in OSL code correspond to the following Octane pin types:

OSL type Octane pin type
color Texture
point Projection (UV, spherical, cylindrical…)
or 3D float (X, Y, Z), see below
vector, normal 3D float
matrix Transform
float Float
int Int or Bool (depending on meta data)
float[N], int[N], up to 3 elements 1D, 2D or 3D float or int
string Filename, String or Enum. See String handling.

Array inputs other than the ones mentioned above are not supported.

If an input has a constant value as default value, the corresponding input pin will have that value as default value as well.

For disconnected pins Octane will look for vertex attributes with a matching name.

Built-in inputs

If an input is decorated with [[int builtin = 1]] Octane will not create an input pin for this parameter. Instead the value comes from Octane itself.

These are the currently available built-in input values:

Parameter meaning
int isNormalMap 1 if the output of this OSL shader is interpreted as a normal map, 0 otherwise.
int isEnvironmentMap 1 while an environment map is being evaluated, 0 otherwise.
int flipU 1 in contexts where Octane will generate mirrored U coordinates (environment maps, and distributions on lights).

If the current version doesn’t provide this parameter the provided initializer is used. Built-ins never fall back to vertex attributes.

Input meta data

OSL supports shader metadata to encode hints about the meaning of input parameters. Octane will use some of this metadata to change the appearance or ranges of input pins.

1
2
3
4
5
    float FocalLength = 1
      [[ string label = "Focal length",
         float min = 0.1,
         float max = 1000,
         float sliderexponent = 4]],

All inputs:

Metadata meaning
string widget Choose which type of widget to use. The meaning depends on the input type, see below.
string label Override the name shown in the node inspector (normally the variable name is shown)
string help Provides a tool tip for the pin when you hover your mouse over the pin
string page Can be used to group pins into categories

Color inputs:

Metadata meaning
string widget = "number" Use a float texture instead of an RGB spectrum as default input type.
string variant = "normalMap" Evaluate the nodes connected to this input as a normal map
string variant = "asOutput" Evaluate as normal map only if the output of this shader is evaluated as a normal map

Numeric inputs: int and float:

All numeric inputs support the following metadata:

Metadata meaning
float/int min, max Specify the minimum and maximum values for a float or int input (note that there's no guarantee that the actual value for the variable in the shader is inside these bounds)
float/int slidermin, slidermax Allows you to specify a more narrow value range for the sliders. Users may still enter values outside this range (but within min / max) using right mouse button drag, and by typing a value.
float/int sensitivity Allows you to specify the steps for a float/int type variable
float/int sliderexponent sets up the skew factor for the slider. In Octane, only linear (sliderexponent == 1) and logarithmic (sliderexponent > 1) are supported

Int inputs:

Metadata meaning
string widget = "checkBox" show a checkbox instead of a slider. The input value will be 0 or 1.
string widget = "boolean" synonym for “checkBox”
string widget = "mapper"
string options
Use a combo box. Options are separated by pipe characters, the keys and value by a colon.
Eg. "option one:1|option two:2|option three:3"

Vector inputs:

For vector inputs you may specify a sun direction node by default. Users can switch between plain 3D float inputs and sun direction inputs if desired.

Metadata meaning
string widget = "sunDirection" Show a sun direction node by default

Point inputs

For point inputs, Octane may create a projection pin or a 3D float pin.

You can explicitly choose a type by setting inputType:

Metada Octane pin type
string inputType = "projection" Create a projection pin
string inputType = "float" Create a 3D float pin

To specify a default projection type for projection input, use "projection:<type>". The type names follow the API names for the node type IDs.

Type name Default type Type ID
"box" Box NT_PROJ_BOX
"colorToUvw" Color to UVW NT_PROJ_COLOR_TO_UVW
"cylindrical" Cylindrical NT_PROJ_CYLINDRICAL
"distortedMeshUv" Distorted mesh UV NT_PROJ_DISTORTED_MESH_UV
"instancePosition" Instance position NT_PROJ_INSTANCE_POSITION
"linear" XYZ to UVW NT_PROJ_LINEAR
"matcap" MatCap NT_PROJ_MATCAP
"osl" OSL projection node NT_PROJ_OSL
"oslUv" OSL defined UV coordinates NT_PROJ_OSL_UV
"perspective" Perspective NT_PROJ_PERSPECTIVE
"samplePosition" Sample pos. to UV NT_PROJ_SAMPLE_POSITION
"spherical" Spherical NT_PROJ_SPHERICAL
"triplanar" Triplanar mapping NT_PROJ_TRIPLANAR
"uvw" Mesh UV NT_PROJ_UVW

Otherwise, the type depends on the initializer:

Initializer Octane pin type
point p = P Create a projection pin, with XYZ to UVW as default node type
point p = point(u, v, 0) Create a projection pin, with Mesh UV as default node type
point p = point(1, 2, 3)
(or any other constant value)
Create a 3D float pin

For other cases the behavior may change between Octane versions.

For projection inputs, you can also choose between the default behavior and the image projection behavior. The latter is enabled by setting the variant to:

Metadata meaning
string variant = "image" use the image projection behavior

Matrix inputs

Metadata meaning
int dim set to either 2 or 3, specifies if the matrix should be shown as a 2D or 3D transform

Matrix inputs can optionally specify that they are UVW transforms via the type metadata attribute. Inputs of string type = "uvw" will additionally be transformed by any parent UVW transform nodes.

Metadata meaning
string type = "uvw" matrices from parent UVW transform nodes will be premultiplied to this input

String inputs

Metadata meaning
string widget = "popup"
string options
Use a combo box. Options are separated by pipe characters.
Eg. "option one|option two|option three"
int editable If 1, this allows entering string values in a combo box which are not in the list of options

Info

File name inputs are always displayed as a file input, regardless of any given metadata.


Last update: October 2, 2023