Octane-specific features and extensions

List of intrinsic functions

Using intrinsics defined by Octane requires including <octane-oslintrin.h>.

Intrinsics for texture evaluation

_evaluateDelayed

color _evaluateDelayed(
    color inputVar,
    float texU,
    float texV)

Evaluates an input, and make texU and texV available during that evaluation. inputVar must be a color input variable for the OSL shader. See using delayed input textures.

_evaluateDelayedP

color _evaluateDelayedP(
    color inputVar,
    point p)

Evaluates an input with a custom value for P. inputVar must be a color input variable for the OSL shader. See using delayed input textures.

Spectral colors

_gaussian

color _gaussian(
    float mean,
    float sigma)

Return a Gaussian spectrum, normalized so the maximal value is 1.0:

$$L(λ) = e^{-\frac{(λ-μ)²}{2σ²}}$$

The useful ranges for the inputs are:

• mean: 380nm – 720 nm
• sigma: 0 – 250 nm

The returned color is represented as a spectrum.

_squareSpectrum

color _squareSpectrum(
    float begin,
    float end)

Return a spectrum which is 1.0 between begin and end, and 0.0 otherwise.

_triangularSpectrum

color _triangularSpectrum(
    float mean,
    float spread)

Return a triangular spectrum which is 1.0 at mean, and which reaches 0 at mean ± spread.

_spectrum

color _spectrum(
    float a,
    float b,
    float c,
    float d)

Makes a spectral color. The 4 inputs correspond to the intensities at the wavelengths returned by getattribute("color:wavelengths", wl).

color _spectrum(
    color c)

Returns the given color and guarantees it is represented as a spectrum.

_arraySpectrum

color _arraySpectrum(
    float  spectrum[])

color _arraySpectrum(
    float  spectrum[],
    int    start,
    int    length)

Interpret an array as a spectrum.

The first and last data points in the array correspond to 380 and 720 nm, with other data points evenly spaced in between. Linear interpolation is used between data points.

You can optionally select a slice of the array of length elements starting at start. You must ensure the slice doesn't exceed the array bounds ( i.e. start >= 0 and start + length <= arraylength(spectrum)).

Use an array of length 35 for data points every 10 nm, and 69 for data points every 5 nm.

_whiteLightSpectrum

color _whiteLightSpectrum()

Returns the user-selected white light spectrum.

All textures are considered to be filters that will be multiplied with a light spectrum (even textures used for emission), so to make an absolute emission texture that directly produces a light spectrum you need to divide the light spectrum by _whiteLightSpectrum() to cancel out the multiplication that will happen later.

wavelength_color

wavelength_color(float wavelength) returns a spectrum consisting of a narrow band around wavelength. Colors returned for wavelengths outside (390, 700) will be close to black.

Octane converts this call to _triangularSpectrum(wavelength, 30.0).

blackbody

blackbody(kelvins) has the same meaning as in standard OSL, but returns a spectral color.

The returned spectrum is a black body emission spectrum divided by _whiteLightSpectrum(), so it will produce the correct black body emission spectrum when used as an emission texture.

_hueshift

color _hueshift(
    color c,
    float shift)

Shifts the hue of the given color. This is a circular shift, shift = 6 represents a full circle. The returned color is represented in the same way as the c argument.

For RGB colors, 1 will shift red to yellow and 2 will shift red to green.

For spectral colors, colors will be shifted to lower or higher wavelengths. Octane samples only a limited number of wavelengths, so color fidelity will be rather low.

Baking camera

_findBakingPrimitive

int _findBakingPrimitive(
    float u,
    float v) BUILTIN;

Finds the primitive which covers the given point in UV space. This should only be called in the camera shader of an OSL baking camera node. Primitives are mapped into this space according to various settings, like the baking group ID on the camera node. By default the triangles are mapped according to the first UV set.

This function may be called more than once, but only the results from the last call may be queried using getmessage().

Meaning of global variables

Octane provides the standard OSL global variables, except for dPdtime and Ps. Since material shaders are not supported, shaders must not assign to Ci.

Octane doesn’t allow referencing the absolute time stamp from within shaders at the moment. The shutter interval, as well as the time global variable are set by assuming current time 0, and by aligning the shutter interval as specified in the shutter alignment setting in the animation settings.

dtime is the length of the time interval covered by the subframe interval.

Optional parameters

A few OSL functions take optional string/value pairs after the fixed argument list.

texture()

Name	type	Meaning
"wrap"	string	Image texture wrapping mode
"interp"	string	Texture interpolation mode.
"alpha"	float	Output variable for alpha channel

List of string values

Global attributes

Attribute names used by the getattribute() function. Must be passed in as strings literals. It must be possible to assign from the corresponding output type to the output variable. In this context float[2] may be assigned to a point or other vector-like type.

Some of these values are also available via intrinsic functions, these are mentioned in the Meaning column.

String	Output type	Meaning
"camera:resolution"	int[2]	Film resolution
"camera:pixelaspect"	float	Aspect ratio of a single pixel
"camera:projection"	string	Camera type
"camera:fov"	float float[2]	Scalar: horizontal field of view; Array: horizontal and vertical field of view
"camera:shutter"	float[2]	Shutter interval (see the note about the time variable above)
"camera:shutter_open"	float	Start of shutter interval
"camera:shutter_close"	float	End of shutter interval
"camera:shutter_reltime"	float	Time relative to the shutter interval, i.e. the ratio $\frac{\mathrm{time} - t_\mathrm{open}}{t_\mathrm{close} - t_\mathrm{open}}$. Varies between subframe start and end percentages. Intrinsic function: float _time();
"camera:clip_near"	float	Near clipping plane
"camera:clip_far"	float	Far clipping plane
"camera:clip"	float[2]	Near and far clipping plane
"camera:distortion"	float	Distortion (thin lens camera)
"camera:dofrandom"	float[2]	Camera shaders only: random numbers used for DOF sampling
"color:wavelengths"	float[4]	Wavelengths in nanometres in our current sample. Contains 4 values as of Octane 3.08.
"hit:t"	float	Distance from previous shading point (or from camera for primary rays).
"hit:obj-color"	color	Object layer color.
"hit:obj-seed"	int	Object layer random seed value, provides a random but deterministic value for each object.
"hit:instance-id"	int	Instance ID provided by the user, eg. the A_INSTANCE_IDS attribute on the scatter node. Intrinsic function: int _getinstanceid();
"hit:smooth-normal"	normal	Interpolated smooth normal on triangles before bump mapping is applied.
"hit:uv"	float[2]	UV coordinates. The arrayindex input value may be used to select one 1 of 3 UV channels provided by Octane. Intrinsic function: point _getuv(int index);
"hit:w"	float	W coordinate, value which increases along hair strands.
"pixel:pos"	int[2]	Pixel coordinate on the film plane

Texture attributes

Attribute names used by gettextureinfo().

String	Output type	Meaning
"exists"	int	0 or 1, indicates if this texture was loaded successfully.
"resolution"	int[2]	Returns the resolution of this image
"channels"	int	Amount of channels in this texture

Messages

Attribute names used by getmessage().

Only one message source is supported: "baking", which return the results of the last call to _findBakingPrimitive(). The returned values are undefined before the first call or if the last call returned 0.

String	Output type	Meaning
"u", "v"	float	The UV coordinate on the mesh of the sampled point
"P"	point	The position of the sampled point
"Ng"	normal	The geometric normal at the sampled point
"N"	normal	The smooth normal at the sampled point
"offset"	float	The suggested offset to use to avoid self-intersections

Attribute names used by setmessage().

String	Input type	Meaning
"octane:throughput"	color	Define the initial throughput of a camera ray Supported in camera shaders

Noise types

First input argument of the noise() function. A pair of string indicate unsigned and signed variants.

String	Meaning
"uperlin", "perlin"	Perlin noise
"noise", "snoise"	Default noise type (Perlin)
"cell"	Cell noise (constant value for each unit cell)
"circular", "scircular"	Worley noise (F1)
"chips", "schips"	Worley noise (F2 - F1)
"voronoi", "svoronoi"	Voronoi noise

Ray types

Input argument of the raytype() function.

String	Meaning
"camera"	Camera ray
"shadow"	Shadow ray (includes first bounce for photon rays)
"AO"	Ambient occlusion
"diffuse"	Diffuse
"glossy", "reflection"	Specular reflection
"refraction"	Refraction
"photon"	Photon tracing ray

Coordinate spaces

Used in functions like transform() and matrix()

String	Meaning
"common"	Standard coordinate space, (world space)
"world"	World space
"object"	Object space
"shader"	Synonym for object space
"camera"	Camera space

String	Meaning
"rgb"	sRGB color space
"hsv"	HSV color space, based on sRGB
"hsl"	HSL color space, based on sRGB
"XYZ"	CIE XYZ color space
"xyY"	CIE xyY color space

Camera projection types

Returned from getattribute("camera:projection", type)

String	Meaning
"spherical"	Panoramic camera, spherical mode
"cylindrical"	Panoramic camera, cylindrical mode
"cube"	Panoramic camera, cube mapping mode
"cube:+x"	Panoramic camera, cube mapping, +X face
"cube:-x"	Panoramic camera, cube mapping, -X face
"cube:+y"	Panoramic camera, cube mapping, +Y face
"cube:-y"	Panoramic camera, cube mapping, -X face
"cube:+z"	Panoramic camera, cube mapping, +Z face
"cube:-z"	Panoramic camera, cube mapping, -Z face
"perspective"	Thin lens camera
"orthographic"	Thin lens camera, orthographic mode
"baking"	Baking camera
"custom"	OSL camera or Custom camera

Image texture wrapping mode

Used as optional wrap argument for texture() calls.

String	Meaning
"black"	Meanings are the same as for the image texture border mode input.
"white"
"clamp"
"mirror"
"periodic"

Texture interpolation mode

Used as optional interp argument for texture() calls.

String	Meaning
"closest"	Nearest value
"linear"	Linear interpolation

Identification macro

Octane defines the macro __OCTANE_VERSION__. This is an integer constant with value 1000000 * major + 10000 * minor + 100 * patch + revision.

---

Last update: November 3, 2023