GPU nodes are custom nodes based on a GPU script used to interact with the data handled by Instant Terra.

Creating and editing a GPU custom node

  • To create a GPU custom node, select New custom node > GPU in the creation node menu.
  • Specify a name, a category and a color for the node.

The node is displayed in the graph with the default settings (an input terrain, a parameter, and an output terrain).

The node appears as invalid as it is not yet connected to any input terrain. Connect it to any terrain to view the default GPU node working.

  • Select the custom node to display its parameter, named "Strength". Change its value to apply a wave effect.

Editing the node's graph

Right-click the node to show the contextual menu then select Edit custom node.


The custom node's graph window opens.

This is where you will define the inputs, outputs and parameter (including manipulators) nodes, and also enter the GPU script.

Parameters

You can organize your parameters into groups for a better visibility.

The GPU script

The GPU script node is created from a default sample script. This default custom node has one input terrain, one output terrain, and one parameter: Strength.

Select the GPU script node to open its properties and the script editor.

When the node has no input terrain or mask (the node is a generator), specify the size (width, height, quad size); otherwise, these options are disabled and the values are retrieved from the input terrain / mask and the output grids.

Use C++ comments, starting with //, or use Python comments, starting with #.

Input and output data

Any new node, input, output or parameter triggers a new connector on the GPU Script node.

Inputs and outputs are referenced by the node's name.

  • An input can only be used to the right of a = sign.
  • An output can only be used to the left of a = sign. It is not possible to write an output then read and reuse it for another output.

The script is run for each vertex.

When several input grids are of different sizes, the size of the first grid is used for the output grids and the other input grids are scaled so their sizes match the first input's grid. A different scale may be applied on X and on Y.

Local variables

Define as many local variables as needed in the script. All local variables are the float type.

Predefined variables

The following predefined variables are available in the script:

  • Width: Output grid width, in meters
  • Height: Output grid height, in meters
  • X: Current vertex's X position, in meters
  • Y: Current vertex's Y position, in meters
  • QuadSize: Quad size of the output terrain or mask, in meters

For example, for a 2048 x 1024 vertices terrain with a 2 meters quad size, the values of the predefined variables are as follows:

  • Width: 4096 (2047 quads x 2 meters)
  • Height: 2046 (1023 quads x 2 meters)
  • X: 0, 2, 4, 6, ... up to 4096
  • Y: 0, 2, 4, 6, ... up to 2046

Functions

The complete list of available functions can be found in the Functions list page.

"Can access other points" option

Select this option if you need to read the values of a vertex that  is not the current vertex, inside an input grid.

To read a vertex in an input grid, provide its coordinates as a distance in meters from the current vertex.

Negative distance X:
Positive distance X:
Negative distance Y:
Positive distance Y:
Vertex left from the current vertex
Vertex right from the current vertex
Vertex up from the current vertex
Vertex down from the current vertex

If a script compiles with this option unchecked, it will not compile when the option is checked as you need to replace Input by Input[0,0].
This option may slow down the performance.

Example

// Copy of an input grid without any update, when "Can access other points" option is not checked:
Output = Input

// Copy of an input grid without any update, when "Can access other points" option is checked:
Output = Input[0, 0] // Input[0, 0] is the vertex being computed

// Offset of a terrain: 2 meters to the right and 4 meters lower:
Output = Input[-2, -4] // We read the vertex located 2 meters left and 4 meters upper from the vertex being processed.

Limitations

To remain GPU compatible, only vertices located at a maximum distance of 1023 vertices. are read.
- For a quad size of 1 meter, the maximum distance to read a vertex is 1023 meters.
- For a quad size of 0.5 meter, the maximum distance to read a vertex if 1023 x 0.5 = 511.5 meters.

  • If the distance is too high, it will be automatically reduced to respect the limitations.
  • If the distance goes beyond the input grid boundaries, then the distance will be adjusted to reach the border of the input grid.

"No limit on points to access" option

This option is visible only when "Can access other points" is checked.

When this option is checked, it is possible to access ANY vertex* in an input terrain or mask. This raises the limitation to the distance of 1023 vertices from the current vertex.
(*currently limited to 8192 x 8192 vertices)

This option may slow down the performances.

"Can use minimum and maximum values" option

Select this option if you need to use the minimum or maximum values of an input grid.

Use the following functions:
Minimum(InputName)
Maximum(InputName)

This option may slow down the performance.

Compiling the script

Once your script ready, compile it by clicking the Compile button below the text editor. Instant Terra checks the code syntax then runs the script. While running, a Stop button is shown to let you stop the execution of the script.

In case of any error while compiling or running, a message is displayed under the Compile button, with information about the error.


Copyright © 2020 · All Rights Reserved · Wysilab