Defining new Operators

Operators vs. Operator-Definitions

Operator-Defintions are templates for adding new Operators. When adding a [Cube]-operator to your graph, you actually add a reference or instance to of the Operator-Definition for this operator. If the definition of the [Cube]-Operator is changed, all occurrences of Cube are immediately updated.

Why you want to define new Operators

There are several reasons why you want to create new Operator-Definitions:

1. If you graphs become more complex, breaking them down into smaller, reusable building-blocks can make project easier to understand.
2. Also, by exposing Parameters, you can define a Template of something that can be reused with different ways described by it's properties.
3. And sometimes, the gory details of how the graph looks like, is just no longer relevant. Encapsulating sub-functionality into a new Operator-Definition with a meaningful name, will make your project more readable.

There are basically two methods for creating new ''Definitions':

• Combining existing Operators
• Duplicating an Operator as a new Type.

Combining Operators into a new Operator Definition

Earlier we created a small graph with some Cubes and a Torus. Lets assume we want to keep this graph for working on it later:

1. Select all Operators by dragging a fence.
2. Right-Click and select "Combine".
3. Fill out the dialog with…

• projects.cubes-and-tori for namespace
• CubesAndTori as operator name
• Early test to show some geometry as description

4. Press the combine button.

Finding meaningful names for new Operators-Definitions is often not easy. But we highly encourage you to think a second or two about. Anything is better than place-holder names.

Also note, that we're setting the namespace to the projects.. With this, we're basically creating a new project for our test. Alternatively we could have used users.<your-username>.cubes-and-tori. We follow the convention to use CamelCase for the Operator-name and a "minus-sign" notation for the namespace.

After we complete the dialog, we tooll creates an instance of our new [CubesAndTori] operator. But wait – The ''Selection View'' no longer shows our graph! This is happens because the new Operator doesn't have any outputs. We could avoid this, by connecting the output of the [Camera]-Operator to a [Group] because combining the operators (without the [Group], of course) to create an output on the fly. But for the sake of learning, we're going to add it manually:

1. Double-Click the [CubesAndTori] operator to open it.

Adding outputs

The ''Workspace View'' now shows the definition of our new Operator with the graph the created earlier. Let's create the output we need to see the result of our graph:

1. Right-click on the darker area just above the ''Operator Workspace''.
2. Select ''Add Output''->''Scene''.
3. Enter "Scene" as for output name.

We created the output for our Operator, but we also need to connect it. So…

1. Drag a connection from the output-nose of the [Camera] onto the new [Scene] output.

Note how in the upper left corner of the ''Operator Workspace'' the path lists "Home">"CubesAndTori". Click on "Home" once to jump out of the Operator, back to your Home operator. Our Operator now has a greenish color, because we made it into a ''Scene'' Operator.

But if we look at the Parameter, our new Operator doesn't have any parameters yet. Let's change that.

Adding Operator Inputs

1. From your [Home]-operator select [CubesAndTori]
2. Look the upper ''Selection View'' to it
3. Double click the Operator to open it.
4. Select the upper [Material] - Operator
5. In the ''Parameter View'' right click its .Diffuse-parameter and select "Publish as Input".
6. Change the name to "SceneColor" and complete the dialog.

Tooll created four inputs (one for each color-channel) and connected them to the [Material] operator.

When we now jump out, back to the [Home] operator, we can see that we can adjust the color of our [CubesAndTori]-scene with the .SceneColor-parameter.

Changing Parameter Defaults

Note how the color-values are grayed out, indicating that the yellow color we selected earlier is set as the default for this parameter. Let's play with that:

1. Press the [Tab]-key to open the ''Quick Create Window''.
2. Search for CubesAndTori and press [Enter] to create a new instance.
3. In the ''Parameter View'' pick the color-thumbnail of '.SceneColor' and change it with the color-picker.

The scenes of the new instance is updated as expected. Note how the color-values are now listed with white color. Let's reset it:

1. [CTRL]+[Click] the.SceneColor parameter to set it back to yellow.

We have been discussing parameters-defaults for quite some time now. Let's try how this feels like:

1. Change .SceneColor to a greenish color.
2. Right-Click the .SceneColor-parameter and select "Set as Default".

With this all instances of [CubesAndTori] for which the color wasn't changed from the default, are now rendered with the new greenish color.

The Magic of Parameter-Groups

When parameter names include a . (a dot) they automatically define a ''Group'' and a ''Component'' part. For example: Size.Height defines a Size.-parameter-group that has a .Height component. This is supper powerful, because it allows you to easily define flexible ''Parameter Groups'' for things like Size, Rotation or Colors.

This not only makes the Parameter-View more readable, but it also makes these parameters easier to manipulate and to animate with keyframes.

If you define a value group that defines all .R, .G, .B., and .A components for a Value group, it's will be displayed as a color that can be modifier with the color-picker.

Tip: In Color-Groups, horizontally dragging the Group-Name will adjust the brightness.

Special Parameter-Names

We mentioned Input- and Conenction-Types, how ''Values'' and ''Strings'' are used for Options, Triggers and Filepaths. How does this work?

This happens, because the Parameter View looks for special patterns in the Names of Paramater of a type:

• Text-Parameters ending with *Path will have a file picker-button "…".
• Value-Parameters ending with *Trigger* will become a trigger