Expressions

Expressions are scripts written by the user which are compiled into GPU code and can then be executed as part of internal Eddy operations, for example, field compositing, particles or rendering shaders. See ExpressionFieldRefLabel, ParticleExpressionRefLabel or ExpressionShaderRefLabel.

Languages

Expressions can currently be written in either EddyScript or C++.

EddyScript is a Python-like language which is compiled and ran on the GPU. It is very fast to compile (compared to C++), so is suitable when working interactively. Even scrubbing a parameter which requires script to be recompiled will generally still feel interactive. Although similar to Python it has significant differences which must be understood, these are documented here.

C++ scripts are for the most part standard C++, so might be preferable if you already have C++ experience. However they are slower to compile (typically around half a second), so are not quite as responsive when working interactively.

Parameters

Expressions can have input parameters which appear as knobs on their nodes, which can then be animated, or from other fields connected to the expression node, which can then be sampled from the script.

To add or modify the available parameters press the ‘Edit parameters’ button.

The expression parameter editing dialog

Parameters can be added or removed using the ‘Add’ and ‘Remove’ buttons, or can be re-ordered by dragging them into the desired order.

• Name: This is the name of the parameter as it will appear in the script function. It must therefore be a valid identifier (begin with a letter or underscore, and contain only letters, digits, and underscores).

• Type: The type of the parameter. Float, Int, or V3f parameters will appear as knobs in the node, whereas Field parameters will appear as an input on the node to which a field can be connected.

• Display name: This is the name of the parameter as it will appear in the UI. If this is not specified then the script name will be used.

• Tooltip: This is an optional tooltip that will appear in the UI.

Script access

To refer to a simple parameter from a script, use either ‘settings.parameter_name’ or ‘node.parameter_name’.

To sample an input field from a script, use ‘fields.parameter_name(position)’ where position is the position at which to sample the field. The return type will be either a float or vector depending on the type of the input field.

Note

The ‘settings’, ‘fields’, and ‘node’ methods of referring to parameters are completely interchangable, however using ‘fields’ to refer to the field parameters can help make the scripts easier to follow and understand.

Decorators

EddyScript expressions can optionally use decorators to specify their required input parameters. This can be useful for example when sharing expression scripts, as the script itself contains the information required to create the parameters.

Note

If decorators are used, then all parameters used by the script must be included in the decorator. It is not possible to mix both decorator parameters and parameters added manually.

An example of the syntax for a field expression is as follows:

@eddyscript.expression(fields=['source:Float'],
                       settings=['scale:Float:1.0', 'direction:Float3:[0.0, 0.0, 1.0]'])

An example of the syntax for a shader expression is as follows:

@eddyscript.shader(fields=['density:Float', 'temperature:Float'],
                   settings=['absorption_colour:Float3:[1.0, 1.0, 1.0]', 'scattering_colour:Float3:[1.0, 1.0, 1.0]'])

Each field parameter should consist of a string with the format ‘name:Type’, where the type can be either ‘Float’ for a scalar field or ‘Float3’ for a vector field. Each regular parameter should have the format ‘name:Type:Default’ where the type can be ‘Float’, ‘Float3’, or ‘Int’.